Design and build WidgetKit usage glance

[cbusillo]

Objective

Design and build the beautiful macOS WidgetKit glance surface for Context Panel.

Finish Line

The widget presents multi-provider, multi-account usage status with compact visualizations that make remaining capacity, reset time, and degraded/stale states easy to understand at a glance.

Current Status

State: Large widget layout was tightened after live crop review. It now fits in the visible widget area, leads with OpenAI weekly as the primary signal, keeps 5-hour as a secondary guardrail, uses a compact provider strip, and shows four key main-limit rows without clipping. Commit gate and diff check pass.
Next action: Add a reset-aware capacity/runway forecast model so weekly OpenAI decisions are based on per-account reset timing rather than simple pooled remaining.
Blocked by: Need product decision on exact wording for accounts with staggered reset times, but implementation can start with simulation semantics.
Last verified: 2026-05-07.

Scope

• WidgetKit extension target.
• Small/medium/large layout strategy as appropriate for macOS.
• Provider/account grouping.
• Compact charts: rings, bars, sparklines, reset countdowns, or other suitable widgets.
• Stale/error/unknown states.
• Tap target/deep-link behavior into app details.

Acceptance Criteria

• Widget renders from local normalized snapshots without network work in the extension.
• Visual states are legible in supported sizes and macOS appearances.
• Empty/setup-needed state opens the app setup path.
• Screenshots or visual evidence are attached to the implementation PR.

Relationships

• Sub-issue of Build Context Panel v1 native app and widget #2.

Validation

• scripts/commit-gate.sh passed locally with 43 tests.
• swift build compiled the ContextPanelWidget SwiftPM target.
• Widget snapshot tests cover setup-needed, stale cached limits, and provider summaries.
• PR Add OpenAI limit probe prototype #14 CI passed on commit 0e81b79.
• PR Add OpenAI limit probe prototype #14 CodeQL passed on commit 0e81b79.
• Visual screenshot still needed from a real WidgetKit extension host after Xcode target packaging.

Decisions

• Use Quiet Instrument as the visual direction.
• Use Concept A - Instrument as the primary widget direction.
• Use Concept B - Ledger as the dense-list treatment inside the app and as a fallback large-widget layout.
• Widgets remain read-only and deep-link into the app for setup/detail.
• Status must use color plus shape/text, not color alone.
• Preserve last-good data for stale/loading/failure states instead of blanking the whole widget.

Open Questions

• Which visual vocabulary best balances beauty and dense provider/account state?

[cbusillo]

Implemented the next widget pass on branch codex/widget-main-limits-ui:\n\n- Added shared widget display preferences for the Main Limits rows, with defaults that prioritize OpenAI weekly, Claude weekly/5-hour, and Gemini daily while hiding OpenAI 5-hour by default.\n- Wired the widget timeline entry to load those preferences from the shared app-group location.\n- Added a standard macOS Settings pane section for toggling which main limits appear in the widget.\n- Verified the installed large widget with a widget-only crop after re-signing the app and extension with their separate entitlements. Current crop shows three selected rows and no clipping.\n\nValidation: scripts/commit-gate.sh && git diff --check passes; Xcode Debug build/install passes. Local WidgetKit testing still needs careful signing: ad-hoc app signing must not use --deep, or PlugInKit rejects the widget extension as not sandboxed.

[cbusillo]

Update from the current widget/app pass:

• Installed and inspected the native widget after the compact layout changes. The widget now renders fresh live data (2M AGO in the crop), no stale steady state, and OpenAI pooled weekly capacity shows 49% left instead of the prior incorrect 6%.
• Main-limit rows now rely on the provider badge and omit repeated provider names, with tighter widget padding. Large widget rows fit more comfortably.
• Main-limit display now uses percentage text whenever a usage ratio exists, so estimated Claude token budgets render as 71% used instead of huge raw token counts.
• App launch now runs an automatic refresh loop: refresh on launch when missing/stale/failed/unknown, then refresh local connectors about every 5 minutes while the app is running, followed by WidgetKit timeline reloads.

Validation: swift test, scripts/commit-gate.sh, git diff --check, Debug xcodebuild, and manual widget crop all passed.