Plan Apple companion clients and shared UI extraction

[shiny-code-bot]

Objective

Make Context Panel visible away from the Mac by adding Apple companion clients for iPhone, iPad, and later Apple Vision Pro while keeping the Mac as the sole collector, credential owner, and provider-refresh runtime.

The companion clients should read a sanitized normalized snapshot over iCloud and reuse the existing widget/glance UI and portable settings pieces instead of rebuilding the same product surface multiple times.

Finish Line

Context Panel has a shared platform-neutral model/UI foundation, a one-way Mac-to-iCloud companion snapshot path, and read-only iPhone/iPad companion app/widget surfaces. visionOS is planned behind the same sync/UI boundary, and Liquid Glass visual work remains a separate final pass so macOS mechanics can ship without visual churn.

Current Status

Progress through 2026-06-19:

Completed mechanical foundation remains unchanged: shared companion-safe modules, sanitized one-way Mac-to-iCloud companion sync, iPhone/iPad companion app/widget surfaces, and release plumbing are on main.

Recent Apple-platform hardening:

• PR Fix refresh attention follow-up cases #212 fixed refresh-needed edge cases for app/widget/companion snapshots and merged at 5119439137919c5cbae35a1160f34ee462103620 with PR and post-merge CI/CodeQL green.
• PR Fix companion iCloud document publish #213 fixed signed Mac companion iCloud publish failures by creating the coordinated parent directory inside the file coordinator block and replacing companion documents via a sibling temp file. It merged at 8793cf39ade26c9c9b7bcf465f1735473a050480 with PR and post-merge CI/CodeQL green.
• Signed runtime validation after PR Fix companion iCloud document publish #213 showed /Applications/Context Panel.app as the canonical app/widget/refresh-agent runtime, baseline=OK, and successful app-group plus iCloud companion document updates from the installed refresh agent.

Active next track:

• Prepare companion TestFlight and device validation #174 remains the active companion TestFlight/device-validation parent.
• New Prepare companion TestFlight and device validation #174 sub-issues capture Apple-alignment follow-ups before broader device/App Store confidence:
  • Resolve companion iCloud container off the UI path #214 Resolve companion iCloud container off the UI path — next implementation slice.
  • Surface companion iCloud sync diagnostics #215 Surface companion iCloud sync diagnostics — next after Resolve companion iCloud container off the UI path #214.
  • Remove uncoordinated companion document read fallback #216 Remove uncoordinated companion document read fallback — small cleanup, can run alongside Surface companion iCloud sync diagnostics #215.
  • Evaluate active iCloud companion document observation #217 Evaluate active iCloud companion document observation — later research, only promote if device validation shows pull/mirror sync is insufficient.

Still open outside the immediate #174 path:

• Plan and build visionOS companion surface #168 visionOS validation/polish remains open after iPhone/iPad path stabilizes.
• Extract portable companion settings controls #165 portable companion settings controls remains open; companion remains read-only for now.
• Evaluate Liquid Glass visual pass separately #169 Liquid Glass visual evaluation remains explicitly deferred.

Scope

Included:

• Platform-portable core/model audit and any needed module split.
• Shared widget/glance UI extraction with no intentional macOS visual change.
• Portable settings extraction for display preferences where appropriate.
• Sanitized one-way iCloud companion snapshot design and implementation.
• iPhone/iPad read-only companion app and widgets.
• visionOS companion planning and later implementation using the same shared layers.
• Separate Liquid Glass/macOS-26+/visionOS visual evaluation after mechanics are stable.

Excluded from the first companion release:

• Provider auth, account setup, OAuth, local file probing, or refresh execution on iPhone/iPad/visionOS.
• Webhook/secret editing from companion clients.
• Bidirectional sync of collector/admin settings.
• Mac UI redesign mixed into mechanical extraction.

Phase Order

1. Audit and extract platform-portable models/shared UI while preserving current macOS behavior.
2. Define and implement the sanitized iCloud companion snapshot contract.
3. Build the iPhone/iPad read-only companion app and widgets first.
4. Build or defer the visionOS companion once the Apple platform support and WidgetKit/spatial surface are confirmed.
5. Evaluate Liquid Glass, color, materials, and macOS visual backports in a separate visual pass.

Acceptance Criteria

• Shared model/UI code compiles for macOS and iOS/iPadOS without AppKit, macOS App Group paths, login item APIs, security-scoped bookmarks, or provider connector code.
• The Mac collector continues to pass the canonical runtime gate when implementation touches app/widget behavior.
• The iCloud companion payload contains only sanitized display data: no tokens, raw provider responses, local file paths, webhook secrets, OAuth artifacts, or raw account identifiers.
• Companion clients cannot initiate provider refreshes or access credentials.
• Companion UI clearly distinguishes available, close to limit, limited, unknown, stale, collector-not-syncing, and no-Mac-snapshot states.
• Freshness includes both provider snapshot time and cloud sync receipt time where applicable.
• Multi-account/provider lanes remain distinct and do not collapse into misleading totals.
• iPhone/iPad widgets and app surfaces reuse shared glance components rather than duplicating the macOS widget UI.
• visionOS does not block iPhone/iPad delivery and does not force spatial/Liquid Glass choices back into macOS mechanics.
• Liquid Glass/macOS visual changes are reviewed in their own branch/PR after the mechanical foundation is stable.

Open Questions

• Do we want companion TestFlight upload automation as a separate workflow/script or integrated into the existing Ship workflow after the Mac upload path?
• Should companion signing use manually supplied provisioning profile secrets, matching the current Mac App Store path, or Apple-managed signing with App Store Connect API authentication?
• Do we need a native layered visionOS app icon before first internal TestFlight, or can that wait until external/App Store polish?
• Which display preferences are safe to edit on companion clients, if any, without creating bidirectional sync complexity?
• How should multi-Mac collector ownership work if more than one Mac publishes snapshots?

Relationships

Child issues should own the independent implementation tracks: portable extraction, shared settings, iCloud sync, iPhone/iPad companion, visionOS companion, and Liquid Glass visual evaluation.