Interactive MistDemo: web (MistKit vs CloudKit JS) + native app (pure CloudKit framework)

[leogdion]

Vision

Transform MistDemo from a CLI-driven example into an interactive demonstration with two distinct stories:

1. Web demo — a single HTML UI with a top-level mode toggle that runs the same CRUD operations through either MistKit (Swift on Hummingbird) or CloudKit JS (in the browser). Same auth, same container, same operations — only the SDK shape differs. This is the value-prop demonstration: MistKit is the Swift equivalent of CloudKit JS, suitable for server/Linux/WASI/Windows contexts where CloudKit JS would otherwise be your only option.

2. Native app — pure CKContainer / CKDatabase via the CloudKit framework, no MistKit. The honest pitch for Apple platforms: use the right tool. MistKit is unnecessary here.

Plan

Six issues, intended to be tackled in order. Refactor-first sequencing because the existing auth-token scaffolding will buckle under new routes/UI otherwise.

Phase 1 — Foundation refactors

• Refactor MistDemo auth-token server (Hummingbird scaffolding) #288 — refactor Hummingbird server scaffolding out of AuthTokenCommand. Routes file grows substantially once CRUD lands; current shape is already awkward.
• Refactor MistDemo auth-token inlined HTML/JS #289 — move inlined HTML/JS into a SwiftPM resource bundle (non-iOS gated). The web UI is about to grow substantially; raw-string distribution becomes painful.

Phase 2 — Web CRUD + comparison

• Add CRUD web interface via Hummingbird #274 — Hummingbird CRUD routes (query/create/update/delete/lookup) and a new index.html that consumes them. Includes the top-level mode toggle UI element.
• Integrate CloudKit JS into MistDemo web for MistKit-vs-CloudKit-JS comparison #329 — Integrate CloudKit JS as the alternate backend behind the mode toggle. Shared ckWebAuthToken.

Phase 3 — Database selection

• Add public database interface to MistDemoApp and web #275 — public/private database picker in the web demo. Mode + DB combine into four auth profiles:
  • MistKit + private → API token + web-auth token
  • MistKit + public → key-pair signing (server-to-server)
  • CloudKit JS + private → API token + web-auth token (shared with MistKit)
  • CloudKit JS + public → API token only

Phase 4 — Native app rework

• Replace NativeCloudKitService with CloudKit framework in MistDemoApp #328 — replace NativeCloudKitService (MistKit-based) with a CloudKit-framework service in MistDemoApp. Absorbs the app half of Add public database interface to MistDemoApp and web #275 (public/private becomes trivial: container.publicCloudDatabase vs container.privateCloudDatabase).

Auth model

The ckWebAuthToken is an opaque session credential tied to (Apple ID, API token, container). It works identically whether the request comes from CloudKit JS in the browser or from MistKit on the server. The demo issues one token via the existing auth-token flow (#287) and shares it across both modes — same credential, same backend, only the SDK changes.

The single place modes diverge is the public database on the server: MistKit can sign with the key pair (CLOUDKIT_KEY_ID + private key) while CloudKit JS in the browser cannot. The UI will surface this asymmetry as a teaching point rather than try to hide it.

Non-goals

• Subscriptions, push notifications, WebSocket fan-out. "Realtime" in this plan means interactive/live UI vs CLI, not push-driven. Subscriptions are a possible follow-up phase once the comparison story is in place.

[leogdion]

Umbrella complete. All sub-issues resolved: #274 (#333), #275 (#337), #288 (b20cc09), #289 (10ce538), #328 (#339), #329 (#335). Related: #338 (#340).