Skip to content

[codex] Add template widget communication helpers#5

Merged
riderx merged 3 commits into
mainfrom
codex/widget-template-communication
May 21, 2026
Merged

[codex] Add template widget communication helpers#5
riderx merged 3 commits into
mainfrom
codex/widget-template-communication

Conversation

@riderx
Copy link
Copy Markdown
Member

@riderx riderx commented May 21, 2026

Summary

  • add startLiveActivity: false so JS can persist SVG template surfaces for regular widgets without launching an iOS Live Activity
  • add native widget reload support through reloadWidgets, plus automatic reloads after template, widget session, and widget message changes
  • add iOS SwiftUI template surface/hotspot helpers so widget extensions can render resolved SVG content and overlay action buttons
  • document the widget-only SVG path and new native helper pieces

Validation

  • bun run build
  • bun run lint (passes with existing SwiftLint warnings)
  • bun run verify:ios
  • JAVA_HOME=/opt/homebrew/opt/openjdk@21 ANDROID_HOME="$HOME/Library/Android/sdk" ANDROID_SDK_ROOT="$HOME/Library/Android/sdk" PATH="/opt/homebrew/opt/openjdk@21/bin:$HOME/Library/Android/sdk/platform-tools:$PATH" bun run verify:android
  • bun run verify:package

Notes

The first bun run verify attempt passed iOS and then stopped because the shell had no Java runtime configured. Android verification passed after pinning the local Java 21 and Android SDK paths.

Summary by CodeRabbit

  • New Features
    • Added reloadWidgets(...) to refresh widget timelines (optional kind filter).
    • Added startLiveActivity option when starting templates; added startTemplateWidget to persist a widget template without launching a Live Activity.
    • Added home-screen surface support and an iOS SwiftUI home-screen widget with hotspot-aware interactive buttons (hotspot intents on iOS 17+).
  • Documentation
    • README and API docs updated with new methods, types, and SwiftUI usage examples for Home Screen widgets.

Review Change Stack

@coderabbitai
Copy link
Copy Markdown

coderabbitai Bot commented May 21, 2026

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info
⚙️ Run configuration

Configuration used: Organization UI

Review profile: ASSERTIVE

Plan: Pro

Run ID: a6f45fdc-a880-4b5e-ad4a-6fe2287e8636

📥 Commits

Reviewing files that changed from the base of the PR and between 6d12ec1 and 91aa2be.

📒 Files selected for processing (15)
  • README.md
  • android/src/main/java/app/capgo/widgetkit/CapgoWidgetKitPlugin.java
  • android/src/main/java/app/capgo/widgetkit/TemplateRuntime.java
  • example-app/android/app/src/main/java/app/capgo/widgetkit/exampleapp/TemplateSampleWidgetProvider.java
  • example-app/ios/App/ExampleWidgetExtension/ExampleWidgetBundle.swift
  • example-app/src/main.js
  • example-app/widget-extension/ExampleWidgetBundle.swift
  • ios/Sources/CapgoWidgetKitPlugin/CapgoTemplateHomeWidget.swift
  • ios/Sources/CapgoWidgetKitPlugin/CapgoTemplateWidgetBridge.swift
  • ios/Sources/CapgoWidgetKitPlugin/CapgoWidgetKitPlugin.swift
  • package.json
  • src/definitions.ts
  • src/helpers/workout.ts
  • src/runtime.ts
  • src/web.ts

📝 Walkthrough

Walkthrough

Adds cross-platform widget reload API and types, a startLiveActivity flag to control native ActivityKit requests, iOS timeline reload hooks after template/activity/session mutations, latest-activity resolution bridge methods, new SwiftUI surface views with hotspot intent buttons, Android reload broadcasts, plugin wiring, and a web stub.

Changes

Widget Kit Extensions: Reload, Live Activity Control, and SwiftUI Views

Layer / File(s) Summary
API contracts, web stub, and README docs
src/definitions.ts, src/web.ts, README.md, package.json
Adds startLiveActivity?: boolean, StartTemplateWidgetOptions, ReloadWidgetsOptions, startTemplateWidget(...), reloadWidgets(...); README updated with docs/examples; web plugin adds stub reloadWidgets and startTemplateWidget.
Runtime layout selection and helpers
src/runtime.ts, src/helpers/workout.ts, android/src/main/java/app/capgo/widgetkit/TemplateRuntime.java
Introduces getTemplateLayout/layoutForSurface fallbacks so homeScreen falls back to lockScreen when absent; frame mutation selection now uses the unified helper; adds a homeScreen layout to example workout template.
iOS: Live Activity control and widget reloads
ios/Sources/CapgoWidgetKitPlugin/CapgoWidgetKit.swift, TemplateLiveActivityManager.swift
Adds startLiveActivity parameter (default true) to start flow, gates ActivityKit requests by flag and OS version, implements reloadWidgetTimelines() and reloadWidgets(kind:), and invokes reloads after session/activity/message mutations.
iOS bridge: latestActivity & resolveLatestLayout
ios/Sources/CapgoWidgetKitPlugin/CapgoTemplateWidgetBridge.swift
Adds .homeScreen surface, latestActivity(status:bundle:) to find the most recently updated envelope, resolveLatestLayout(...), and per-surface layout lookup helper with homeScreen→lockScreen mapping.
iOS SwiftUI surface views and hotspot buttons
ios/Sources/CapgoWidgetKitPlugin/CapgoTemplateWidgetViews.swift
Adds SwiftUI-only helpers: clear hotspot label, CapgoTemplateHotspotButton (AppIntents on iOS 17+), CapgoTemplateSurfaceView overlaying hotspots, CapgoTemplateWidgetSurface, CapgoTemplateLatestWidgetSurface, and resolution failure logging.
iOS WidgetKit home entry & provider
ios/Sources/CapgoWidgetKitPlugin/CapgoTemplateHomeWidget.swift
New WidgetKit home-screen timeline entry, CapgoTemplateWidgetTimelineProvider that resolves latest layout and schedules refresh, and CapgoTemplateHomeWidgetView rendering CapgoTemplateSurfaceView.
iOS plugin methods and wiring
ios/Sources/CapgoWidgetKitPlugin/CapgoWidgetKitPlugin.swift
Registers startTemplateWidget and reloadWidgets plugin methods, forwards startLiveActivity from JS into native start calls, and adds an Objective-C handler for reloadWidgets.
Android reloadWidgets and notify refactor
android/src/main/java/app/capgo/widgetkit/CapgoWidgetKit.java, CapgoWidgetKitPlugin.java, CapgoWidgetKitConstants.java, TemplateRuntime.java
Adds reloadWidgets(kind) broadcasting store and widget-bridge changes, refactors notify helpers to accept optional kind, adds EXTRA_WIDGET_KIND constant, and adjusts runtime layout lookup to use layoutForSurface.
Example app & sample widgets
example-app/*, example-app/widget-extension/*
Example app preview and demo flow switched to homeScreen; adds ExampleTemplateHomeWidget in iOS example bundles and updates Android sample provider to use home-screen surface.

Sequence Diagram(s)

(omitted — changes are organizational and spread; no new multi-component runtime sequence beyond those described in layers)

Estimated code review effort

🎯 4 (Complex) | ⏱️ ~60 minutes

Possibly related PRs

  • Cap-go/capacitor-widget-kit#1: Prior work modifying runtime surface/frame resolution; conceptually related to the homeScreen fallback and frame selection changes.
🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name Status Explanation Resolution
Docstring Coverage ⚠️ Warning Docstring coverage is 1.59% which is insufficient. The required threshold is 80.00%. Write docstrings for the functions missing them to satisfy the coverage threshold.
✅ Passed checks (4 passed)
Check name Status Explanation
Description Check ✅ Passed Check skipped - CodeRabbit’s high-level summary is enabled.
Title check ✅ Passed The title '[codex] Add template widget communication helpers' accurately describes the main changes: introducing new widget communication features (startTemplateWidget, reloadWidgets) and helper components for iOS template surface rendering.
Linked Issues check ✅ Passed Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check ✅ Passed Check skipped because no linked issues were found for this pull request.

✏️ Tip: You can configure your own custom pre-merge checks in the settings.

✨ Finishing Touches
📝 Generate docstrings
  • Create stacked PR
  • Commit on current branch

Comment @coderabbitai help to get the list of available commands and usage tips.

@github-actions
Copy link
Copy Markdown
Contributor

Beta npm build

Maintainers can publish this PR to npm for fast testing.

Comment /publish-beta after the PR checks are green.

The workflow will:

  • publish a prerelease package on the beta tag
  • add a pinned pr-5 dist-tag for this exact PR build
  • update this comment with the install command

Security note: beta publish is only enabled for branches inside this repository.

@riderx riderx marked this pull request as ready for review May 21, 2026 15:28
@chatgpt-codex-connector
Copy link
Copy Markdown

You have reached your Codex usage limits for code reviews. You can see your limits in the Codex usage dashboard.

Copy link
Copy Markdown

@coderabbitai coderabbitai Bot left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Actionable comments posted: 6

🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@android/src/main/java/app/capgo/widgetkit/CapgoWidgetKit.java`:
- Around line 188-191: reloadWidgets currently ignores its kind parameter and
always sends global broadcasts; change it to emit kind-scoped notifications when
kind is non-null by calling notifyStoreChanged and notifyWidgetBridgeChanged
with the kind context (or by adding/using overloads that accept a kind) so only
widgets of that kind reload. Locate the reloadWidgets method and update the
calls to notifyStoreChanged and notifyWidgetBridgeChanged (or add new methods
like notifyStoreChanged(kind) / notifyWidgetBridgeChanged(kind, /*options*/)) to
attach the kind string to the broadcast intent/extras; preserve the global
behavior when kind is null.

In `@ios/Sources/CapgoWidgetKitPlugin/CapgoTemplateWidgetBridge.swift`:
- Around line 105-112: latestActivity currently takes the first filtered item
from listActivities without guaranteeing recency, so sort or pick the newest
envelope before returning: call listActivities(bundle:) then filter by status
(as in the existing guard), and return the envelope with the latest timestamp
(e.g., use max(by:) or sort by
StoredTemplateActivityEnvelope.createdAt/updatedAt descending) so latestActivity
always returns the most recent StoredTemplateActivityEnvelope; adjust
resolveLatestLayout callers if they rely on implicit ordering.

In `@ios/Sources/CapgoWidgetKitPlugin/CapgoTemplateWidgetViews.swift`:
- Around line 198-205: The computed property resolvedLayout currently uses
silent error suppression with "try?" around
CapgoTemplateWidgetBridge().resolveLayout(...) which hides failures; change it
to a do-catch: call CapgoTemplateWidgetBridge().resolveLayout(activityId:
activityId, surface: surface, bundle: bundle, now: now()), return the layout on
success, and in the catch block log the error (using os_log or Swift's Logger)
with context (activityId, surface, bundle) and then return nil so the
placeholder UI still appears but failures are visible for debugging.

In `@README.md`:
- Line 222: Revert all manual edits inside the README's <docgen-index> and
<docgen-api> sections (undo changes around reloadWidgets and the other listed
blocks), then add the proper TypeScript declarations and JSDoc in
src/definitions.ts: define the reloadWidgets() function signature, create the
ReloadWidgetsOptions interface, and add the startLiveActivity property to the
StartTemplateActivityOptions type with appropriate types and JSDoc comments;
finally run `bun run docgen` to regenerate the README so the auto-generated
sections are updated.
- Around line 139-140: Remove the redundant pre-action call to
CapgoWidgetKit.reloadWidgets() in the SVG Template Usage example: keep the await
CapgoWidgetKit.performTemplateAction(...) call only, since performTemplateAction
already triggers timeline refreshes on iOS
(TemplateLiveActivityManager.performAction calls reloadWidgetTimelines()) and
broadcasts ACTION_TEMPLATE_STORE_CHANGED on Android, and reloadWidgets() is a
no-op on web; update the example to avoid the extra await and any explanatory
text that implies a manual reload is required before performTemplateAction.

In `@src/web.ts`:
- Around line 416-418: The web implementation of reloadWidgets has a mismatched
signature; update async reloadWidgets(): Promise<void> to accept the optional
parameter used by the CapgoWidgetKitPlugin interface: async
reloadWidgets(_options?: ReloadWidgetsOptions): Promise<void> (you can ignore
the param name or prefix with underscore), ensuring the method signature matches
CapgoWidgetKitPlugin.reloadWidgets(options?: ReloadWidgetsOptions):
Promise<void>.
🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

  • Push a commit to this branch (recommended)
  • Create a new PR with the fixes

ℹ️ Review info
⚙️ Run configuration

Configuration used: Organization UI

Review profile: ASSERTIVE

Plan: Pro

Run ID: 0294c2e6-8f15-47d8-9d92-f4a4b11c1f7a

📥 Commits

Reviewing files that changed from the base of the PR and between d68db5a and f7716f6.

📒 Files selected for processing (10)
  • README.md
  • android/src/main/java/app/capgo/widgetkit/CapgoWidgetKit.java
  • android/src/main/java/app/capgo/widgetkit/CapgoWidgetKitPlugin.java
  • ios/Sources/CapgoWidgetKitPlugin/CapgoTemplateWidgetBridge.swift
  • ios/Sources/CapgoWidgetKitPlugin/CapgoTemplateWidgetViews.swift
  • ios/Sources/CapgoWidgetKitPlugin/CapgoWidgetKit.swift
  • ios/Sources/CapgoWidgetKitPlugin/CapgoWidgetKitPlugin.swift
  • ios/Sources/CapgoWidgetKitPlugin/TemplateLiveActivityManager.swift
  • src/definitions.ts
  • src/web.ts

Comment thread android/src/main/java/app/capgo/widgetkit/CapgoWidgetKit.java
Comment thread ios/Sources/CapgoWidgetKitPlugin/CapgoTemplateWidgetBridge.swift
Comment thread ios/Sources/CapgoWidgetKitPlugin/CapgoTemplateWidgetViews.swift
Comment thread README.md Outdated
Comment thread README.md
Comment thread src/web.ts Outdated
@riderx
Copy link
Copy Markdown
Member Author

riderx commented May 21, 2026

@coderabbitai review

@coderabbitai
Copy link
Copy Markdown

coderabbitai Bot commented May 21, 2026

✅ Actions performed

Review triggered.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.

@riderx
Copy link
Copy Markdown
Member Author

riderx commented May 21, 2026

@coderabbitai review

@coderabbitai
Copy link
Copy Markdown

coderabbitai Bot commented May 21, 2026

✅ Actions performed

Review triggered.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.

@riderx
Copy link
Copy Markdown
Member Author

riderx commented May 21, 2026

@coderabbitai full review

@coderabbitai
Copy link
Copy Markdown

coderabbitai Bot commented May 21, 2026

✅ Actions performed

Full review triggered.

@riderx riderx merged commit d1abd14 into main May 21, 2026
8 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant