# 🤖 Native apps × the app platform: apps as first-class citizens

> Status: **SHIPPED — phases 0–5 + the voice surfaces merged to `main`
> 2026-07-23** (#1256, #1314–#1318; field fixes from live evaluation rode the
> same PRs). What runs today: the app-host protocol below (all rows marked
> shipped), `AppRegistry` (bundled seed from `tools/gen-app-catalog.mjs`,
> drift-gated by `test/appcatalog-seed.test.mjs`, live `appCatalog()` pulls),
> `SpaceApps`/`SpaceAppsStore` (installs survive relaunch), the platform-shared
> command host on both platforms (full forwarding, per-thread typeahead rows,
> the `needKey`/`needAppThread` bridge), space routing + the space band,
> projection/preview queries (feeds and sidebars narrate any app's events),
> and the voice contract (`web/static/apps/README.md § Voice`). Only phase 6
> ("make it good", below) remains open. This note is the standing design
> reference — the same role `docs/native-chat.md` plays for the native feed.

## The position (accepted, load-bearing)

**Member apps — every tier of them — are first-class citizens in the native
apps.** Concretely, the native apps (Mac and iOS, as one product) must:

1. **Recognise and use any app available in a space** — built-in, admin-installed
   custom, or member-built — with **zero per-app native code**. Native
   special-casing (the schema engine, hand-native surfaces) is a progressive
   enhancement selected per app, never a gate on availability.
2. **Offer one consistent way to discover, add, and open apps** — personal
   ("you"), per-group ("chat"), and space-wide ("space") — identical in
   behaviour across Mac and iOS.
3. **Support the full app capability set the web does** — posting into chat,
   commands and replies, panels, scheduling, snapshots, notices — generally,
   not as per-app special cases.
4. **Expect the app set to differ per space and change over time** — folding
   the install registries and reacting to the server's change prods, with the
   result surviving restart.
5. **Expect the command/completion set to differ per chat and per server** —
   assembled dynamically, never hard-coded.

"Make it work" means every app runs on native through the web implementation
(embedded, bridged); "make it good" means native surfaces replace webviews
per app **behind the same registry**, invisible to the rest of the system.

## What the app platform actually is (the contract a client implements)

Everything below already exists and is what the *web* client implements. A
native client is simply **the second implementation of the same contract** —
none of it requires server changes (see "What the server provides" below).

**Three tiers of apps, one registry.** Built-in apps are ES modules compiled
into the binary (statically imported, `shell.js`). Admin-installed **custom
apps** are plaintext JS: discovered via public `GET /api/apps` →
`{apps:[{name,url}]}`, served at `/static/apps-custom/<name>`
(`customapps.go`). **Member apps** are user content: instance-key-encrypted
blobs from `GET /api/member-apps`, executed only inside the opaque-origin
sandbox (`/app-sandbox`, `sandbox.js` / `sandbox-frame.js`). All three tiers
register through one `defineApp()` into one in-page registry (`apps.js`), and
the server broadcasts a content-free `{type:"apps_changed", kind}` WS frame
whenever the custom/member set changes.

**Install state is fold state.** Which apps live where is end-to-end encrypted
and client-derived — the server never learns it:

- *Personal* ("you"): implicit — a `kind:"self"` thread whose `name_blob`
  decrypts to `{app,title}`. Created on first use.
- *Group* ("chat"): `groupapps.add/remove` events in that group's own log,
  folded by the `installs` registry app (`apps.js`), pinned by
  `test/event-vectors/groupapps.json`.
- *Space-wide* ("space"): `spaceapps.add/remove` events in the hidden
  all-members **space thread** (`kind:"space"`; fetched explicitly via
  `GET /api/space-thread` — it never appears in `/api/threads`; its AES key
  rides `open_key`, wrapped under the *instance key*, so no private key is
  needed to open it). Pinned by `test/event-vectors/spaceapps.json`; design
  `docs/space-apps.md`. Creation is lazy + race-safe; the server prods online
  clients with a content-free `{type:"space_thread"}` frame.

Both registries filter **at read time** to apps the client actually has
registered and that are capable of that place — unknown installs fold but stay
inert, so clients on different versions converge on the same log.

**Commands are assembled per thread.** `commandCatalog(threadId)` (`apps.js`)
builds the typeahead/`/help` list dynamically: the owning app's local verbs
first, then every registered app's global commands stamped with *where the
data lands* ("chat"/"space"/"you", ranked by nearness), alt rows for the
`@me`/`@here`/`@everyone` flags, then floor commands, `/me`, and bot commands.
Invocation is `runCommand(text, threadId, reply)` — parse, route to the
nearest instance (`instanceThread`), build a ctx, run. Replies are private
in-place notices; a command may also open a **panel** (`ctx.panel`) — a
transient in-chat surface.

**Presentation is an app's own declaration.** `appWantsChatView(name)` — i.e.
"does the app implement `chatMessage(event)`" — decides companion
(Chat | Split | Interface) vs takeover; `defaultView` / `chatOnly` /
`chatReadOnly` refine it; `groupFeedMessage(event)` narrates a takeover app's
events into a *group's* feed without growing a Chat view. These are facts of
the app spec, not of the client.

**The capability set (`ctx`)** an app runs against: `emit` (encrypt + post
into the bound thread), `schedule`/`unschedule` (server-fired future events,
`/api/schedule`), `emitEphemeral` (relay-only), `getState`, `id`, `me`,
`meName`, `threadId`, `place`, `reply`, `panel`, `open`, `interval`,
`onCleanup`. **Memory** is automatic: folded state snapshots to
`GET/PUT /api/threads/{id}/state` (encrypted, optimistic-versioned, 409 →
refold + retry). **Voice** is `notice`/`notify` on events.

### What the server provides — and why this needs no server changes

The initial hunch list ("server APIs to communicate which apps are available",
"event folds doing rollup to a current state") turns out to already exist, in
the E2EE-shaped form the one rule demands:

| hunch | what exists |
|---|---|
| "APIs to say which apps are available" | `GET /api/apps` (custom-app code), `GET /api/member-apps` (member-app blobs), `apps_changed` prod. *Which apps are installed where* is deliberately not a server API — it's encrypted fold state (registries above), because the server must never learn the app set. |
| "rollup to a current state: recent messages + installed apps + app states" | Exactly the `thread_state` snapshot system: clients fold, encrypt, and PUT the rolled-up state per `(thread, slot)`; boot = snapshot + newer events. The server can't do the rollup (ciphertext), and doesn't need to. |
| "app added / app removed events" | `groupapps.*` / `spaceapps.*` wire events, already vector-pinned for native. |
| "a bridge like the web ctx" | Client-side by definition — the app-host protocol below. |
| "custom commands invoking across the bridge" | `commandCatalog` + `runCommand` exist; the gap is native consuming them. |

The whole plan is client work. The server's part — blobs, prods, schedules,
state slots, the space thread — is finished and in production.

## Where native was before this work (the honest map, kept as the record)

> 🤖 Historical: this section described native as of 2026-07-22, and is what
> the phases below were designed against. Every symptom in it is fixed on
> `main` except the vault passkey row (phase 6). Kept because the root-cause
> table is the best explanation of WHY the architecture looks the way it does.

Three parallel app subsystems grew independently in `ios/`:

1. **Schema apps** — `SchemaEngine/SchemaAppStore/SchemaAppView` (LChatCore)
   interpret `Schemas/{todo,remind}.json` natively. Generic and good — but
   fed only by two bundled files (`AppSchemaRegistry`).
2. **Webview embeds** — everything else renders the web client in a
   `WKWebView` seeded with `window.__lchatEmbed` (one thread, one thread key).
   iOS: `ChatView`+`WebBridge`+`FeedWebCache`; Mac: `AppThreadWebView`+
   `MacWebBridge`+`AppWebViewCache`, plus a Mac-only per-thread **command
   host** (`CommandPanelWebView`, `mode:"command"`) used for `/emoji`/`/gif`.
   *(Since resolved on iOS: `ChatView` — the embed that could carry a
   thread's CHAT — is deleted. `AppThreadScreen` renders app-thread chat
   native and pins every surviving embed to `view:"interface"`; a webview
   now only ever carries an app's own interface, on both platforms.)*
3. **Flow apps** — `FlowEngine` for `setup`/`welcome`.

Overlaid: a native `groupapps` fold (`GroupApps.swift`) and **~10 hand-kept
per-app lookup tables** that each re-state a fragment of app metadata:
`AppIdentity.symbols/marks`, `GroupApps.catalog` (4 apps),
`ThreadStore.appTitles/appGlyphs/appDescriptions/personalApps` (12/12/12/5),
`AppChatProjection.intros/title` (2), `AppDefaultCommand.specs` (2),
`NativeChatView.companionApps` (2), `ComposerTypeahead.botCommands`,
`SlashCommands.WebPanelCommands.catalog`. The same fact ("is this app a
companion?") lives in **two** independent sets (iOS keys off
`AppChatProjection.intros`, Mac off `companionApps`); the app catalogue exists
in **three** different-length lists.

### Symptoms → root causes

| symptom | root cause |
|---|---|
| Space restarts forget which apps are installed | Native has **zero** space-thread support: no `GET /api/space-thread` call, no `spaceapps` fold, no handling of the `space_thread`/`apps_changed` frames (`grep spaceapps ios/` → nothing). Group installs survive only because the *web* writes the `slot:"apps"` snapshot native re-seeds from. |
| No app slash commands anywhere native | The native typeahead floor is hard-coded (`ComposerTypeahead`); apps' commands are never learned. The Mac command host *can already run every command* (`window.lchatNative.runCommand` → the real `runCommand`) but the Mac shell only forwards `/emoji`/`/gif` to it; iOS has no command host at all, and its native feed posts a dead literal "/emoji" message. |
| Admin: no Chat\|View on Mac | `companionApps = {todo, remind}` hard-codes the companion set; Admin (a companion with `defaultView:"interface"`, whose Chat view now carries the changelog stream) isn't in it. |
| Admin on iOS shows chat, not the app | `ThreadListView.chatSurface` routes non-schema apps to `ChatView`, which seeds `view:"chat"` — wrong for interface-first and takeover apps. |
| Whiteboard won't load / can't be added to a group | The board is `places:["chat"]` with an `openEvent` — but native's group Apps sheet is the 4-app `GroupApps.catalog` (no board), and `GroupApps.known` filters unknown installs out. |
| Group todo on iOS: no chat part, janky menu | Group-app selection replaces the feed entirely (`activeGroupAppID`); there's no companion projection for group instances and no consistent switcher. |
| Vault passkey lock dead on native | WebAuthn inside an embedded `WKWebView` — needs a host bridge (deliberately deferred; "make it good"). |

## Target architecture

Three layers, all platform-shared in LChatCore; iOS and Mac keep only thin UI.

### Layer 1 — `AppRegistry`: one source of truth (native)

A LChatCore store that merges, and persists across launches:

- **The catalogue** — per-app manifest records reported by the app host
  (below): `name, title, glyph, places, listed, quiet, companion, chatOnly,
  chatReadOnly, defaultView, defaultCommand, composerPlaceholder,
  commands[{name, desc, args, local}]`. Cached to disk; invalidated by
  `apps_changed` → `catalogChanged`.
- **Install state** — personal app threads (`ThreadStore` already folds
  these); per-group `groupapps` folds (`ChatFeedModel` already); and the new
  **`SpaceAppsStore`**: fetch `/api/space-thread`, unwrap `open_key` with the
  native instance key, seed from its `slot:"apps"` snapshot + fold
  `spaceapps.*` per the existing vectors, subscribe to the
  `space_thread`/`apps_changed` frames in `ChatSocket`, persist.
- **Native enhancements** — `AppSchemaRegistry.hasSchema`, SF-symbol/brand-mark
  overrides (`AppIdentity` becomes a *decoration* keyed by registry id, with
  the manifest `glyph` as the universal fallback — unknown apps get their
  glyph, never a blank).

Every current lookup table collapses into a registry read. The two
companion-sets, three catalogues, and per-app titles/glyphs/blurbs all become
one record type with one source. **An app the registry doesn't know still
works**: title/glyph/commands come from the manifest, surface is a webview —
that is the first-class-citizen guarantee.

### Layer 2 — the app host: the web engine, bridged (the generalized command host)

The one component that can *execute* app JS is the web framework — so native
runs it, headless, and talks to it over a small protocol. This is not new
machinery: it is the Mac command host (`mode:"command"`), generalized and made
first-class on both platforms. The embed page already loads **all three app
tiers** (`bootEmbed` runs `loadCustomApps()` + `loadMemberAppsNow()`), already
runs any command, and already reports panels/replies/errors.

**The app-host protocol** (native ⇄ `window.lchatNative` / `"lchat"` posts):

| direction | call / post | meaning | status |
|---|---|---|---|
| native → js | `appCatalog()` → `[manifest…]` | the full registered-app catalogue (all tiers) | shipped |
| native → js | `commandItems()` → `[row…]` | `commandCatalog(threadId)` for the embed's thread — the typeahead/`/help` source | shipped |
| native → js | `runCommand(text)` → handled? | run any slash command; replies/panels post back | exists |
| native → js | `dismissPanel()` | close the open panel | exists |
| js → native | `{catalogChanged: kind}` | the app set changed (`apps_changed`); re-pull `appCatalog`, recreate stale webviews | shipped |
| js → native | `{commandHostReady}`, `{panel}`, `{panelHeight}`, `{notice}`, `{composerInsert}`, `{error}` | command-host lifecycle | exists |
| js → native | `{needKey: threadId}` → native calls `__lchatProvideKey(threadId, keyB64)` | cross-thread routing: a personal command typed in a group must emit into the personal app-thread, whose key the single-key embed doesn't hold. Native unwraps (it can only unwrap threads the user is in) and provides. | shipped |
| js → native | `{needAppThread: {app, title}}` → native calls `__lchatProvideAppThread(app, threadId, keyB64)` | the app→thread resolution itself: the embed can't decrypt other threads' name_blobs, so resolving there would mint a duplicate app thread. Native opens-or-creates (`openOrCreateAppThread`) and answers with the id + key. | shipped |
| native → js | `previewEvent(event, you)` → `{text} \| null` | the sidebar line for one app event — the app's own `preview(e, {you})` hook, defaulting in the engine to the actor-prefixed chat projection (the voice chain: notice → preview → chat projection → silent). `you` = the actor is the reader ("You added…"). | shipped |
| native → js | `projectEvent(event, group)` → `{text, action, title} \| null` | chat projection of an app event, for the native feed (companion Chat views, group narration) — the web's `chatMessage`/`groupFeedMessage` answered by the engine that owns them. Ownership resolves in the engine via `appForType` (native never prefix-guesses — `webhooks.*` belongs to webhook-monitor); `title` rides along so native names the bubble. | shipped |

Trust posture: the app host is a privileged surface *by job description* — it
is the command engine, so its reach is the union of the member's app threads,
group threads it's asked about, and the space thread. It still **never**
holds the user's private key (native unwraps and hands narrow thread keys),
and the server still only ever sees ciphertext. Member-app code inside the
host stays inside the `/app-sandbox` iframe exactly as on the web. The
`needKey` grant is native-policied: only keys native itself can unwrap, only
on request, never the private key or admin token.

Two host-shape decisions:

- **Per-thread hosts first** (the existing Mac shape, LRU-cached): minimal
  delta, and `appCatalog()` is thread-independent so *any* live embed can
  serve it. A single per-instance host (`mode:"apphost"`, threadless boot) is
  a later consolidation, not a prerequisite.
- **Snapshots come for free**: a host that folds a thread with real keys runs
  the framework's automatic snapshot writer — which fixes "native households
  never write snapshots" without new code. (Safe by construction: snapshot
  writes are optimistic-versioned, and racing writers refold + retry.)

The embed's space-thread bail (`loadSpaceThread`: `if (embed || !instanceKey)
return`) lifts for hosts seeded with the instance key, so space-installed
apps' commands route correctly inside the host too (phase 4).

### Layer 3 — registry-driven surfaces

- **Surface routing**: iOS `ThreadListView.chatSurface` and Mac
  `NativeChatView.feed` stop switching on hard-coded names. One shared
  decision: `registry.presentation(appId)` → *native-schema* (schema exists) /
  *flow* (`setup`/`welcome`) / *companion* (Chat|Split|Interface on Mac,
  Chat|Interface on iOS — the Chat pane is the NATIVE feed on both, honouring
  `defaultView`, `chatOnly`, `chatReadOnly`) / *takeover* (the app's
  interface, full pane) — with the interface-only webview as the universal
  fallback. Chat itself never renders in a webview: a webview may only carry
  an app's own interface (iOS `AppThreadScreen`/`AppInterfacePane`, Mac
  `companionSplit`/`appInterfacePane`).
- **Pickers**: New-chat ▸ Apps (personal = `places` ∋ "you"), group ⋮ ▸ Apps
  (chat-capable, so the board appears), and the space band (space installs,
  from `SpaceAppsStore`) all render from the registry — custom and member
  apps included, identically on both platforms.
- **Typeahead**: `ComposerTypeahead` consumes registry commands (per-thread
  rows via `commandItems()`, cached + refreshed on fold changes) instead of
  its hard-coded floor; selection routes to the command host. The floor
  (`/me`, `/help`, theme verbs) stays native.
- **Group instances**: the added-apps switcher and the group feed's app-event
  narration come from the registry + projection queries, one design on both
  platforms (Mac keeps Split; iOS keeps toggle).

## Phases (all shipped 2026-07-23 except phase 6; each landed as its own PR)

- **Phase 0 — protocol groundwork (web-side, testable in Node). SHIPPED.**
  `appCatalogReport()` in `apps.js`; `appCatalog()` / `commandItems()` on the
  embed bridge; `{catalogChanged}` post on `apps_changed` in embeds;
  `test/appcatalog.test.mjs` pins the shapes.
- **Phase 1 — installs survive: `SpaceAppsStore` + registry persistence. SHIPPED.**
  LChatCore: space-thread fetch/unwrap, `spaceapps` fold (vectors exist:
  `spaceapps.json`), `space_thread`/`apps_changed` in `ChatSocket`, disk
  persistence for catalogue + installs. Acceptance: kill + relaunch → a
  space's installed apps (vault included) are still listed.
- **Phase 2 — one registry, registry-driven routing. SHIPPED.** Collapse the lookup
  tables into `AppRegistry`; route surfaces and pickers from it. Acceptance:
  Admin gets Chat|View on Mac and opens as the app on iOS; the board is
  addable to a group and loads; unknown/custom apps appear with glyph+title.
- **Phase 3 — commands everywhere. SHIPPED.** iOS gains the command host; both
  platforms forward *every* non-floor slash command to it; typeahead rows
  from `commandItems()`; `needKey` bridge for cross-thread routing.
  Acceptance: `/todo buy milk` works from any chat on both platforms;
  `/emoji`/`/gif` stop dead-posting on iOS; a custom app's command appears in
  the typeahead with its desc/args.
- **Phase 4 — space routing in the host. SHIPPED.** Lift the embed space-thread bail
  when the instance key is present; space band UI. Acceptance: `/gif` (space
  app) works natively where installed.
- **Phase 5 — projection queries. SHIPPED.** Native feeds narrate app events for apps
  without native projections (`projectEvent`); `AppChatProjection` becomes the
  fast path for schema apps, same outputs, vector-pinned.
- **Phase 6 — make it good. OPEN.** More schemas; native panel rendering; the
  vault passkey/WebAuthn host bridge; per-instance host consolidation; native
  snapshot writing direct from `SchemaAppStore` if the host path isn't enough;
  the sandbox-projection relay, so MEMBER apps' events narrate in native feeds
  too (their `chatMessage` runs only inside the `/app-sandbox` iframe, so
  `projectEvent` deliberately answers null for them today).

## Deliberately out of scope

Bots and webhooks (already native-blind by design — sidecar processes);
changing any wire format or server behaviour; SDUI for the chat feed
(`docs/native-chat.md` locked that out). The schema engine keeps growing
*within* its archetype — it is the "make it good" tier, never the
availability gate.