🤖 Building a mini-app

A mini-app is a small client-side program that lives alongside chats — a to-do list, a poll, reminders. This guide is written for both humans and LLMs: follow it top to bottom and you can add a new app in one self-contained file.

> This directory holds apps and nothing else. Every .js file in > web/static/apps/ calls defineApp — one app per file. Shared machinery an > app leans on (the schema engine + renderer, the conversation-flow engine, > Eleven's scripted-conversation feel, the Vault's lock crypto) is a sibling > module in web/static/, imported as ../<name>.js. So listing this > directory lists the apps.

The one idea

An app has no server. It trades typed events over the same end-to-end encrypted thread stream that chat messages use, and derives its state by folding those events. The server only ever sees ciphertext, so it can't run or even recognise app logic — everything happens in the browser.

> The encrypted thread log IS the app's database. You never store state; you > emit events and fold them back into state. Two devices that fold the same > events arrive at the same state by construction.

> The app schema. To-do and Reminders are SCHEMA-DESCRIBED: a declarative > JSON schema (schemas/<name>.json, spec: docs/app-schema.md) declares > their state, folds, actions, and views, and BOTH platforms interpret it — > the web via ../schema-engine.js + ../schema-render.js (their app files wire > schemaEvents/schemaRender into defineApp and keep only the glue: > commands, preview/unread, chat wording, named parsers), the native apps via > the Swift twin engine with SwiftUI components. To change those apps' events, > folds, or view behaviour, change the schema (and its byte-identical copy in > ios/LChatCore/Sources/LChatCore/Schemas/) in the same PR; npm test holds > the twins together. > > Views (views.js, design: docs/views.md) ride this same engine from > the other direction: a bot posts SCHEMA + DATA (never code) as thread > events, and the views app expands each into a schema list pinned above the > feed — opened from an open_view chip on the bot's reply, reopened with > /views. Apps and bots in the chat can read and replace a view's data > through ordinary view.create/view.update events.

An app is four small things:

1. an events map — the event types it owns and how each folds into state,
2. an initialState — the empty state to start from,
3. commands and/or a message action — how a user creates events,
4. a surface — how state renders (a full pane, or a panel above a chat).

Everything ships in one file under web/static/apps/, including the app's CSS. No build step; these are plain ES modules.

On top of that model the framework gives every app three capabilities for free (details in their own sections below):

• Time — ctx.schedule(event, when) has the server deliver an event into the thread later, so things happen when no client is open (reminders that actually fire). The server holds only ciphertext and a timestamp.
• Memory — folded state is snapshotted (encrypted) to the server and re-seeded on open, so an app's state survives beyond the loaded message window. 1,000 todos work as well as 10. Apps do nothing to opt in.
• Voice — an event can carry a notice (or the app a notify hook) to alert the user the moment it arrives: a toast in the open app, a system notification when hidden, a push notification when closed. All wording stays encrypted end-to-end.

A complete app

This is a real, working app — copy it, rename it, and change the guts. It's a personal "Notes" list: /note <text> from any chat files a note; the app's own sidebar pane lists them.

// web/static/apps/note.js
import { defineApp, namespace, addItem, removeItem } from "../apps.js";

// One declaration of the app's prefix — N.ev("add") is the "note.add" event
// type, N.cls("item") is the "note-item" CSS class. See "Namespacing" below.
const N = namespace("note");

export const app = defineApp({
  name: "note",          // unique id, lowercase — also the default namespace
  title: "Notes",        // shown in the sidebar and header
  glyph: "📝",           // avatar glyph
  places: ["you"],       // where copies can live: just for you (its own sidebar thread)

  // The empty state. A factory (not a value) so every thread gets its own.
  initialState: () => ({ items: [] }),

  // The events map: KEYS are the event types this app owns, VALUES fold each
  // event into new state. This one declaration is the whole model — the owned
  // types and the reducer are both derived from it. Handlers must be PURE:
  // return new state, never mutate the old. The collection helpers make that
  // easy and keep adds idempotent (see "Invariants" below).
  events: {
    [N.ev("add")]: (s, e) => (e.text ? { items: addItem(s.items, { id: e.id, text: e.text, by: e.name || "" }) } : s),
    [N.ev("remove")]: (s, e) => ({ items: removeItem(s.items, e.id) }),
  },

  // A slash command a user can type in any chat. It emits an event; because
  // this is a personal app, the event is routed into the user's own Notes
  // thread wherever they typed it, and they get a toast confirming it landed.
  commands: {
    "/note": (args, ctx) => {
      const text = args.trim();
      if (text) ctx.emit({ type: ctx.ev("add"), id: ctx.id(), text });
    },
  },

  // The app's CSS travels with it — injected once by the framework. Read the
  // theme's CSS variables (var(--ink), var(--accent), …) so it follows the theme.
  // The stylesheet stays a plain literal; ctx.cls() below keeps the JS in step.
  styles: `
.note-item { display: flex; gap: 8px; padding: 6px 2px; border-bottom: 1px solid var(--border); }
.note-text { flex: 1 1 auto; overflow-wrap: anywhere; }
`,

  // Personal, full-pane: `el` is the whole thread pane. Build DOM nodes and set
  // text with textContent — NEVER innerHTML for anything a user typed.
  render(state, el, ctx) {
    for (const item of state.items) {
      const row = document.createElement("div");
      row.className = ctx.cls("item");        // "note-item"
      const text = document.createElement("span");
      text.className = ctx.cls("text");       // "note-text"
      text.textContent = item.text; // user content → textContent, never innerHTML
      const rm = document.createElement("button");
      rm.textContent = "×";
      rm.onclick = () => ctx.emit({ type: ctx.ev("remove"), id: item.id });
      row.append(text, rm);
      el.appendChild(row);
    }
  },
});

Then register it (one line) in web/static/shell.js, next to the others:

import "/static/apps/note.js";

That's a whole app. Everything below is reference detail and the optional hooks.

Pick your app's shape first

Before the field reference, decide which archetype you're building. An app's shape is two independent choices — where copies can LIVE, and how each copy PRESENTS:

1. Places (places: ["you", "chat", "space"], any subset) — where a copy of this app can live: your own sidebar thread, a chat everyone in it shares, one copy for the whole space. A place is a thread; place = privacy (docs/space-apps.md). [] = host-mounted/utility, never instantiable. When a place is off on purpose, say why with placeNote — the Apps sheet shows it where the Add button would be.
2. Does it project into chat? (a chatMessage hook) — with it, the app is a companion (a Chat view beside its Interface); without it, a takeover (its render IS the whole surface). See "Views" in CLAUDE.md.

Those compose into the archetypes you'll actually build:

| You want… | declare | surface | examples | | --------- | ------- | ------- | -------- | | A private tool that IS its own thread | places: ["you"] (no chatMessage) | full-pane takeover | a secrets vault | | A private tool you also chat with | places: ["you"] + chatMessage | full-pane companion (Chat ⇄ Interface) | todo, remind | | …either of those, shared with a chat or the whole space | add "chat" / "space" to places | the widget bar's Interface pane, beside any conversation | todo, remind, bookmarks | | A group tool with no personal copy | places: ["chat"] | widget pane; its command auto-adopts it in a group | poll, board | | Not user-instantiable (host mounts it) | places: [] | host decides | the chat feed, setup, /emoji |

The old scope enum and the personal/groupCapable/spaceCapable flags are COMPAT-ONLY inputs now (#405 closed): already-deployed custom and member apps that declare them keep working — defineApp normalizes either generation into places and then DELETES the old fields from the app object — so new apps declare places, and nothing else in the product can even read the old vocabulary. (How long "keep working" lasts, who upgrades legacy apps, and how the floor may eventually rise: docs/member-apps.md § Legacy formats: the compat policy.) The one legacy archetype scope carried, the always-on ambient panel above every feed, is retired: Poll and Whiteboard live in chats now (places: ["chat"]), and a legacy scope:"shared" custom app degrades to command-only.

Layout patterns — and the example app that shows each

Once you've picked a shape, copy the closest working app rather than starting cold:

• Full-pane list (todo.js, remind.js) — an add form on top, then the list, optionally a collapsed archive/history section. Rebuilt from state on every change (NOT incremental); it's the simplest correct thing, and it's what makes a group instance converge — another member's edit just refolds and redraws. Keep transient UI (a reveal toggle, a grace-period ring) on the row DOM, never in reducer state.
• Ambient panel (poll.js) — render nothing when empty so the panel collapses (invariant #6), and set incremental: true + use keyedList so a half-interacted card (an armed "Close?" button) survives the refolds that votes trigger. Handlers read card._ctx (refreshed each render), because the one #app-surface is reused across threads — a stashed thread id would target the wrong chat.
• Long / scroll-back lists (chat.js, board.js) — incremental: true + keyedList with a rev, so unchanged rows keep their exact nodes (scroll position, focus, decrypted images survive).
• Companion projection — implement chatMessage(event, { group }): return a bot bubble (a string) or a /me-style action line ({ text, action: true }), or null for silence. The { group } hint lets wording differ when many people read it (remind.js drops "you asked me" in a group).
• Two-step inline confirm (poll.js) — embedded webviews have no confirm() panel (it silently answers false), so never call it: a first click arms the button ("Remove?"), a second within a few seconds commits.

A shape decision worth making deliberately: a takeover secrets/notes tool should usually NOT implement chatMessage, so its events don't spill names into the chat feed, previews, and push notifications. 🤖 When a group still needs to see that something happened (without the app becoming a companion), implement groupFeedMessage(event) instead: the feed-only projection hook. foldGroupAppEventBubble prefers it when folding a group's own feed — and only there, so the personal thread stays a pure takeover (no Chat view ever grows on it; appWantsChatView reads chatMessage alone). vault.js uses this for add/remove, deliberately without naming the secret in the line. Companion apps need no second hook — with no groupFeedMessage, the group fold falls back to chatMessage(event, { group: true }) (that's the { group } hint above); a companion that wants different group wording implements both, and returning null from groupFeedMessage keeps it silent in groups.

defineApp(spec) — the fields

| field | required | what it is | | -------------- | -------- | ---------- | | name | ✓ | Unique lowercase id. Also the conventional prefix for your event types. | | namespace | | The prefix for event types + CSS classes. Defaults to name (leave it off unless you need them to differ). Drives the ctx.ev / ctx.cls helpers and app.ns — see Namespacing. | | title | ✓ | Human name (sidebar, header). | | glyph | ✓ | One emoji/character used as the app's avatar. | | places | ✓ | WHERE copies of this app can live — the one placement declaration: any subset of ["you", "chat", "space"]. "you" = a personal, self-thread instance (Apps menu, personal-command routing, defaultCommand); "chat" = addable to a group chat (⋮ → Apps), one shared instance for everyone there (see "Group-scoped apps"); "space" = installable for the WHOLE space, one shared instance in the hidden space thread (see "Space-wide apps" + docs/space-apps.md). [] = host-mounted/utility. (Formally optional — omitting it means ["you"], and the legacy flags/scope normalize into it — but every new app declares it.) | | groupFeedMessage | | 🤖 (event) => { text, action? } \| string \| null. The FEED-ONLY projection: narrates the app's events in a GROUP chat's feed without opting the app into a companion Chat view (that's chatMessage's meaning). Implement it instead of chatMessage for a takeover app whose group activity should still be visible (vault.js); alongside it for group-specific wording; absent, the group fold falls back to chatMessage(event, { group: true }). See "Companion projection" above. | | listed | | false for a host-mounted app that is never user-instantiable (the chat feed, setup, the groupapps registry). Defaults to places.length > 0. | | quiet | | 🤖 true if a command answering in place must never itself force this app's PERSONAL thread into view. The thread still exists and still gets every event — that's the only durable record of the interaction — this only governs visibility. See "Quiet apps" below and issue #227. | | requiresService| | A connected-service name (e.g. "dnsimple"). The app is hidden from New chat until that service is linked — how a service "installs" its companion app. See docs/connected-services.md. | | initialState | ✓ | () => state. A factory, called to seed each thread's empty state. | | events | ✓ | { "<type>": (state, event, meta) => state }. The fold. | | commands | | { "/cmd": (args, ctx) => void }. Slash commands. The richer form { run, desc, args, local } feeds the / typeahead; local: true scopes a command to the app's own thread (see "Local & default commands"). | | defaultCommand | | The name of one of the app's commands that plain, non-slash text typed into the app's thread runs — a local verb (To-do's "/add") or, when the global verb IS the in-thread grammar, that global (Reminders' "/remind"). Only honoured while no bot member is in the thread. | | composerPlaceholder | | The composer placeholder shown in the app's thread while defaultCommand is active (e.g. "Add a to-do…") — it's how the implicit routing announces itself; set it whenever you set defaultCommand. | | render | | (state, el, ctx) => void. Draws the surface. | | messageAction| | (msg) => spec \| null. Adds an item to the chat message menu. | | renderEvent | | (event, meta) => Node \| null. An inline line in the message feed. | | notify | | (event, ctx) => {title, body} \| null. Speak on a live event (see Voice). | | ephemeral | | (event, ctx) => void. Handle relay-only events (see Ephemeral events). | | hostEvents | | Like events, but HOST-ONLY: folded via foldHostEvent, never registered as wire types — a member can't trigger them by posting a typed message. For translating server-enforced mechanisms (chat's reactions/edits/deletes) into fold state. | | snapshot | | Set false to opt out of state snapshots (an app whose state IS the log). | | incremental | | Set true to keep the surface between renders and reconcile it yourself (see keyedList). | | styles | | A CSS string, injected once. |

defineApp returns the app object (with .types and .reduce derived from events — handy in tests).

Places & discovery (places, listed)

scope used to be a single required enum, and then three capability flags, but both quietly conflated the one real question — WHERE can copies of this app live? — with how the app is discovered (#405). The model is now exactly two fields:

• places — the placement declaration (see the table above). "you" gives the app a personal instance: its own single-member thread in the sidebar, rendered full-pane (el is the whole thread view); a command or message action typed in any chat routes into it. Private tools live here: to-do, reminders, bookmarks, vault. Adding "chat" lets it also be added to a group chat, one shared instance for everyone there (next section) — a group tool isn't a separate archetype, just a place. "space" is the same idea, one scope up.
• listed: false — the app is not user-instantiable; the host mounts it explicitly (the chat feed, the setup/welcome conversations, the groupapps registry). Never appears in the Apps menu.

The legacy inputs still normalize in (scope: "personal" → ["you"], scope: "system" → [] + listed: false, and each capability flag → its place) because stored member-app manifests carry them — but defineApp deletes them after normalizing, so no code path reads them.

Not every full-pane thread surface should be an app, though — a pending (not-yet- joined) DM shows a waiting card instead of the chat app's pane, but that's a host-level concern, not an app archetype. See docs/mini-apps-architecture.html §5 for why, and the design question to revisit once the classic feed is retired.

Group-scoped apps: the same app, personal AND in a group

A personal app whose places include "chat" (To-do) can also be added to a group chat (⋮ → Add apps), where one shared instance runs for the whole group — at the same time as everyone's personal copies. This is not a new model; it's the existing one pointed at a different thread:

• Same events, same reducer, different log. The group's instance folds the app's ordinary events (todo.add, …) from the group thread's encrypted log instead of your personal app-thread's. Every member folds the same events, so everyone sees the same list; snapshots, scheduling, and live delivery already work per-thread and need nothing new.
• Which apps a group has added is itself fold state — the framework's groupapps registry app owns groupapps.add / groupapps.remove wire events ({ app: "todo" }), folded per thread like any other. It syncs to every member and the server never learns which app was added (or that one was). Any member can add or remove, like adding people; both acts render as action lines ("Ana added To-do to this chat").
• The widget bar. A group with apps added gets the header view toggle: Chat | Split (desktop) | one glyph button per added app. Tapping an app's button shows it beside the chat; a second tap gives it the full pane (on mobile, where there's no split, the first tap does); tapping a different app's button swaps the pane in place. The app renders in the same Interface pane a companion app-thread uses, with ctx bound to the group thread — ctx.emit lands in the group log. Nothing about your render changes.
• Chat projection is attributed. In a group, a chatMessage ACTION projection leads with the actor's name ("Ciara added “buy milk”" — a group has many hands); a MESSAGE projection (a reminder firing) stays a bubble in the app's voice. Write chatMessage exactly as for the companion view; the host adds the prefix. In a group it's called with { group: true } as a second argument, for wording that must differ when many people read it (Reminders drops "you asked me" there) — apps that don't care ignore it. 🤖 The host also substitutes “You” for the reader's own action (foldGroupAppEventBubble in shell.js, matching membershipLine's join/leave convention) — this is automatic and free; write your text as if it always follows a name (added “buy milk”), never bake in “You” yourself, or a bystander reading someone else's event will see “You added “buy milk””. This attribution is unique to chatMessage — a preview hook (below) gets no such help and must do its own “You” check.
• @-mention runs the default command. "@To-do buy milk" typed in the conversation runs the app's defaultCommand with the rest of the text — the event is what lands, shown as an action line, and the app joins the @ typeahead. This is the explicit form of defaultCommand: a group's plain text is real conversation, so a group app must never eat it implicitly (defaultCommand's automatic form stays personal-thread-only).
• Slash commands scope to the nearest instance. In a chat that has the app added, its global command acts on the GROUP instance — "/todo buy milk" there files into the shared list, exactly like "@To-do" (see runCommand). Everywhere else it keeps routing to your personal app-thread, so the same verb always addresses the instance you're looking at.
• @here installs and shares in one gesture. In a group without the app, "/todo @here buy milk" adds the app to the group (the same groupapps.add the sheet emits, so everyone gets the widget bar and the action line) and files the item into the new shared instance; a bare "/todo @here" just installs. Anywhere the flag can't apply — not a group, or an app that can't be shared — it answers with a private explanation instead of mis-filing the text. The "/" typeahead makes all of this discoverable: a group-capable command's description says where it will land — "for this group" when the app is added, "just for you" when it isn't — and in the fresh case the flags that would install it ride as extra rows that say so in the same sentence shape ("/todo @here" · "Add a to-do to a new To-do app for this group"; likewise "@everyone" for the space, when the policy lets you), so the install is never hidden. (Since the places grammar landed, EVERY app command names its place — personal ones read "just for you" everywhere — and /help closes with the one routing sentence: a command acts on the nearest copy of its app.)

What the "chat" place asks of your app: nothing beyond the standard invariants — a pure, idempotent, validating reducer (strangers' events are now first-class inputs), a render that works off ctx.threadId (never a stashed thread id), and per-user logic keyed on e.uid. If your app satisfies those, the place is the whole opt-in. Vectors: test/event-vectors/groupapps.json.

Currently chat-placed: To-do, Reminders, Bookmarks, the Vault — plus Poll and the Whiteboard, which are chat-place-ONLY (places: ["chat"], no personal copy): their commands auto-adopt the app into the group on first use (the ambient panel they used to ride is retired — #405). Deliberately NOT flagged: apps whose state derives from one member's private service credentials (Integrations, DNSimple) — sharing those needs its own design (whose credentials fetch? who may see the result?), so the per-app gate is the point, not a limitation.

Space-wide apps: install once, use everywhere

The third place up: an app whose places include "space" can be installed for the whole space (⋮ → Apps → "For everyone in this space", or /app @everyone) — ONE shared instance, its commands available in every chat, nobody else installs anything. Design + trust model: docs/space-apps.md. Currently parked for shipped apps (docs/space-apps.md § The pullback): the built-ins declare places: ["you", "chat"] and the multi-place UI hides behind the PLACES_UI device flag — the machinery below stays live and tested, and an app rejoins by adding "space" to its places line. Again not a new model, the same one pointed at a different thread:

• The space thread. Every instance gets (lazily, on first install) a hidden, all-members thread; the shared instance folds the app's ordinary events from ITS encrypted log. Its key travels like an open group's — open_key, wrapped under the instance key — so every member, including late joiners, can already unwrap it; the server still can't. The thread has no chat view and never pushes.
• Which apps the space installed is fold state — the spaceapps registry app owns spaceapps.add / spaceapps.remove ({ app: "stickers" }), folded from the space thread exactly like groupapps from a group's. Any member installs or removes; the Apps sheet's "Installed for everyone by …" line is the visible record. Vectors: test/event-vectors/spaceapps.json.
• Commands route to the nearest instance (see runCommand): local verbs → the app's OWN thread → this chat's group instance → the SPACE instance → your personal thread. So a space-installed app's global verb acts on the shared instance from every chat — the "/" typeahead says so ("for this space") — while the same verb typed inside the app's own personal thread, or in a group that added it, keeps addressing the instance you're looking at. @App text mentions work in any chat (and the @ typeahead suggests them) and target the space instance too.
• @everyone installs and uses in one gesture — /stickers @everyone installs for the space (creating the space thread on first use) and runs any trailing text against the fresh shared instance; a bare @everyone is just the install, confirmed privately (@space is an accepted alias). An app without the space place gets an explanation, never a mis-filed event.
• @me completes the flag family, pointing at privacy — /todo @me dentist files into YOUR copy even where a chat or space copy claims the bare verb. No install side effects, ever; an app with no personal place explains (its placeNote) instead of mis-filing. The / typeahead teaches the flags itself: when several copies are reachable it offers the flagged variants as extra rows (/todo @me · just for you), ranked after the default route — nobody reads docs, everybody reads the menu.
• Each space app gets a sidebar row — its home. The space band (badged "space", subtitle "For everyone in this space") opens your render full-pane with ctx bound to the space thread; your preview/unread hooks drive the row's activity line and dot, exactly as they do for chats. Space apps deliberately do NOT appear in other chats' widget bars — the widget bar always means "this chat's own copies" (place = location). A group's own add of the same app is a separate copy, in that chat.
• Message actions stay personal. "Save link" files into YOUR bookmarks even when Bookmarks is space-installed — saving somebody's message privately is the point of that gesture; the shared instances are reached by command or mention, always explicit.

What the "space" place asks of your app: the "chat" bar, verbatim — a pure, idempotent, validating reducer (the whole space now writes to one log), render off ctx.threadId, per-user logic keyed on e.uid. Member apps opt in through their manifest — places including "space", or the legacy spaceCapable: true boolean, which normalizes into it (see docs/building-member-apps.md). No shipped app currently declares the space place (§ The pullback); the built-ins that had it — Bookmarks, To-do, Reminders, the Vault — are one places-line edit from returning.

Local & default commands

A command is global by default: it's in the / typeahead of every thread, and (for a personal app) routes into your app-thread from wherever you typed it — that's /todo, the routing verb. Mark a command local: true and it becomes an in-thread verb instead: it resolves — and appears in the typeahead — only inside the app's own thread, never elsewhere, so short names like /add can't collide across apps. In its own thread the local commands lead the typeahead and the app's global aliases drop out as redundant. An app with no local commands leads with its globals instead — Reminders' /remind heads its own thread's list (the global verb is the in-thread verb; nothing supersedes it).

defaultCommand names one of the app's commands that plain text runs: with no bot member in the thread, typing buy milk into To-do's chat is /add buy milk, and typing call mum in 2h into Reminders is /remind call mum in 2h — because sending a chat message no one can answer is a dead end, the message becomes the action instead. The command can push back: Reminders replies "When should I remind you?" for text with no parseable time. (In-thread, replies carrying a short — transient confirmations — are suppressed, since the event's action line is feedback enough; replies without one, content and errors, always render.) Three rules keep this honest:

• Advertise it. Set composerPlaceholder (and write your chatIntro to say "just type") — implicit routing a user can't see is magic, not delight.
• It steps aside for an LLM. The gate is "no bot member here" (defaultCommandFor): if a bot later joins the thread, plain text goes back to being a real message for it to answer, and your commands become things it can invoke on the user's behalf.
• Personal app-threads only. A shared app in a group chat must never eat plain messages — those are real conversation. Slash text never falls through to the default either: a leading / always means "command".

A default-command thread is text-only: the composer hides its attach affordances (there's no one to read a file), and they return if a bot joins.

Quiet apps

🤖 A personal command answers in place by design (CLAUDE.md), but by default it still has a side effect on your sidebar: the first time you run a personal app's global command, its app-thread is created — via resolveAppThread/createAppThread in shell.js — and appears in the thread list, whether or not the command actually did anything. That's right for To-do or Notes (the thread IS where the item now lives, so surfacing it is the point), but wrong for an app whose commands mostly just answer a question or offer an action chip — it shouldn't spawn a sidebar entry the user never asked for.

Set quiet: true and the app's personal thread stops forcing its own way into view. The thread still exists — it's still the only durable record of the interaction, and every event you ctx.emit still lands there exactly as before — quiet only changes visibility, never storage:

• Brand new (never interacted with before): the thread is created (so your command has somewhere to emit into) but stays hidden — no new sidebar row.
• Already visible (the user has it open or it's in their list): nothing changes. Quiet is a no-op once the thread is already showing.
• Was visible, then the user closed it: your command's activity — a reply, a panel, or an emitted event — must not reopen it. Only the user's own tap (an action chip's ctx.open, or finding it via the Apps menu) brings it back, and when it does, every event sent while it was hidden is already there waiting.

You don't have to do anything else to get this — no different ctx.emit, no different reply shape. The enforcement lives entirely in the host (createAppThread creates it pre-hidden; the WS message handler reasserts the hide instead of letting the server's default "new activity reopens a closed chat" rule apply) because the server never learns which app owns a thread (see CLAUDE.md), so only the client can make this call. See issue #227. quiet only means something for a personal app-thread — it has no effect on a chat-placed app's shared group instance, since that thread is the chat the user already has open, never one the command creates.

Command panels — a transient results surface

A command can answer with more than a private reply: ctx.panel(spec) opens a panel — a temporary, interactive surface in the chat you typed in, sitting just above the composer (or pinned above the feed with position: "top"). It's still the "answer in place" doctrine: nothing navigates, nothing overlays what you're reading (the panel takes layout space), and leaving is always the user's tap. Two working references: apps/emoji.js (/emoji cat opens a picker; a tap drops the emoji into your message via panel.insertText) and apps/gif.js (/gif high five shows Giphy results — the first member to run it supplies a free Giphy key, which then belongs to the space and nobody is asked again; a tap posts the GIF into the chat as an ordinary encrypted attachment and closes the panel — its network + upload go through the host's scoped ctx.host.gif doorway, because apps never fetch).

"/emoji": {
  run(args, ctx) {
    const results = searchEmoji(args);
    if (!results.length) return ctx.reply({ text: "No matches." });
    const opened = ctx.panel({
      title: `Emoji matching “${args}”`,   // header line, next to the app's glyph
      // position: "top",                  // pin above the feed instead (default: above the composer)
      // animate: false,                   // appear/vanish instantly (default: ease up on open, roll down on dismiss)
      render(el, panel) {                  // build DOM into el — textContent for anything user-typed
        for (const r of results) {
          const b = document.createElement("button");
          b.textContent = r.ch;
          b.onclick = () => { panel.insertText(r.ch); panel.close(); };
          el.appendChild(b);
        }
      },
      onClose() {},                        // optional: told when the panel is replaced or dismissed
    });
    if (!opened) ctx.reply({ text: "…" }); // no chat surface here → answer with a reply
  },
},

The panel handle a render gets:

| member | what it does | | ------ | ------------ | | panel.close() | Dismiss the panel (the app deciding it's done). | | panel.refresh() | Re-run render (e.g. async results arrived — render a spinner first, refresh when ready). | | panel.insertText(t) | Insert t at the caret of the composer the panel sits above (forwarded to the native composer in the embedded shell). | | panel.attachFiles(files) | Stage files on that composer — the same encrypt-and-upload path the attach button uses. | | panel.threadId | The thread the panel is showing in (where you typed). |

A panel is generic UI, not a picker widget. render gets a bare container and full control: build any DOM you like, own its clicks, and — because the handler's ctx is your app's real context — a button can dispatch a typed event straight into the thread's encrypted log, where it folds like any other app event:

"/lunch": (args, ctx) => {
  ctx.panel({
    title: "Start the lunch poll?",
    render(el, panel) {
      for (const q of ["Pizza or noodles?", "Eat out or order in?"]) {
        const b = document.createElement("button");
        b.textContent = q;
        b.onclick = async () => {
          // An ordinary app event — encrypted, attributed, folded by every
          // member. The panel was just the UI that chose it.
          await ctx.emit({ type: "poll.create", id: ctx.id(), q, options: ["👍", "👎"] });
          panel.close();
        };
        el.appendChild(b);
      }
    },
  });
},

/gif composes the same pieces the other way round: its tiles call a privileged host doorway (ctx.host.gif — search/download/upload) and then ctx.emit a chat message with the uploaded attachment. If your panel needs the network or another privileged capability, don't reach for fetch (apps never fetch — Invariants #7): add a narrow, named doorway to setHostBridge in shell.js, the way gif and the connected services do, and route any new external host through the server's CSP deliberately (CLAUDE.md documents the Giphy exception).

The declarative form (and member apps). Instead of a render closure you may declare a top-level panel(data, el, panelCtx) hook on the app and call ctx.panel({ title, data }) — the host synthesizes the render, handing your hook the JSON data plus a panelCtx of { close, insertText, emit, id, me, getState }. This is the ONLY form the member-app sandbox supports (a closure can't cross its bridge — the hook runs in a fresh sandboxed frame mounted inside the panel), and it works identically compiled-in, so one file runs in both worlds: see apps-disabled/mood.js and docs/building-member-apps.md § Command panels.

On the native apps. The Mac app runs panel commands through a hidden per-thread command-host webview — your panel code runs there unchanged (insertText reaches the native composer; ctx.emit posts for real). One extra step: add your command to WebPanelCommands.catalog (ios/LChatCore/Sources/LChatCore/SlashCommands.swift) so the native composer forwards it and lists it in the typeahead. Only commands that act in the CURRENT thread (or need no thread) belong there — the native page holds a single thread's key, so a command that routes elsewhere (/todo) can't resolve in it.

Rules that keep panels honest:

• A panel is client-only chrome. Never sent, never folded, gone on dismissal or when the pane closes — state that matters goes through events, as ever.
• One per thread. Opening another replaces it (the outgoing one's onClose fires). The user can always dismiss it — its ✕, or Escape.
• It's a response, not an ambush. Only open one from a command the user just ran (ctx.panel exists only in command/mention handlers) — never spontaneously.
• ctx.panel returns false when the thread has no mounted chat surface to draw in — fall back to ctx.reply.
• It eases open and shut by default (and honours reduce-motion); pass animate: false for an instant panel. On the Mac the native shell drives the one animation, from the same flag.
• The usual surface rules apply: build DOM nodes, textContent for user content, theme variables for styling (ship the CSS in your app's styles).

The events map & the reducer

Each handler is (state, event, meta) => newState. Rules:

• Pure & immutable. Return new state; never mutate state. (Two devices fold the same events and must converge; the UI also re-folds on every reopen.)
• You don't write a default case. The framework returns state unchanged for any type your app doesn't handle. Your map only lists what you own.
• Event types must be globally unique. Two apps can't share a type — prefix every type with your app name (note.add, poll.vote).
• meta carries { id, ts } where id is the server message id (used for dedupe — see Invariants) and ts the sender's send time. You rarely need it.

Namespacing: one prefix, declared once

Every app prefixes the same string onto two families of names: its event types (board.stroke, joined with . — the wire string, part of the cross-platform contract, so the helper only spells it, it never changes it) and its CSS classes (board-canvas, joined with -). Writing that prefix by hand in a dozen places is where it drifts. So declare it once with namespace(name) and derive the rest:

import { defineApp, namespace, addItem } from "../apps.js";

const N = namespace("board");           // one declaration of the prefix

export const app = defineApp({
  name: "board",
  events: {
    [N.ev("stroke")]: (s, e) => …,      // key is "board.stroke"
    [N.ev("clear")]: (s, e) => …,       // key is "board.clear"
  },
  render(state, el, ctx) {
    const canvas = document.createElement("canvas");
    canvas.className = ctx.cls("canvas"); // "board-canvas"  (ctx.cls === N.cls)
    ctx.emit({ type: ctx.ev("stroke"), id: ctx.id(), points }); // "board.stroke"
    if (e.type === N.ev("stroke")) …    // compare against the same string
  },
});

• N.ev(short) → "board.short" — use it for the events map keys (computed: [N.ev("stroke")]), every ctx.emit({ type }), and every e.type === … comparison.
• N.cls(short) → "board-short" — use it for className and selector strings. The styles blob stays a plain literal (it's static text); the helper keeps the JS references to those classes in lock-step with them.
• Inside render/commands the same resolver is on ctx as ctx.ev / ctx.cls, bound to your app — no module-level N needed there.
• namespace defaults to name, so it's fully opt-in: an app that never calls it behaves exactly as before, and board.js is the migrated reference.
• A name that already contains a . passes through untouched (N.ev("chat.msg") → "chat.msg"), so referencing a full or foreign type still works — which makes converting an existing app a safe find-and-replace.

board.js is the worked example. (chat.js deliberately does not namespace its classes — it reuses the original feed's .msg/.bubble markup on purpose; the helper is opt-in precisely so it can. todo.js/remind.js are schema-described (docs/app-schema.md): their events map keys come from the JSON schema, not namespace() — but the hand-written glue around a schema app (commands, chatMessage/preview/unread) still compares against the wire type by hand, so it namespaces too: const N = namespace(schema.name), then N.ev("add") instead of a second hardcoded "todo.add".)

Collection helpers

Most apps fold into a list of { id, … } items. Import these from ../apps.js and your reducer is correct by construction — every op returns a new array, and addItem dedupes by id:

addItem(list, item)        // append item unless its id is already present; always a fresh array
updateItem(list, id, patch)// replace matching item with { ...item, ...patch }
removeItem(list, id)       // drop the matching item

Because addItem always returns a fresh array, you can .sort() its result in place safely:

"remind.add": (s, e) => {
  if (!e.id || !e.text || !e.when) return s;
  const items = addItem(s.items, { id: e.id, text: e.text, when: e.when, fired: false });
  items.sort((a, b) => a.when - b.when); // safe: items is a fresh copy
  return { items };
},

Not every fold is a flat list. poll.js keeps a per-poll votes map and writes it with a manual immutable update — the helpers are a convenience, not a requirement. When you go custom, keep it pure:

"poll.vote": (s, e) =>
  ({ polls: s.polls.map((p) => (p.id === e.pollId ? { ...p, votes: { ...p.votes, [e.uid]: e.choice } } : p)) }),

Emitting events — and the three free fields

You create events with ctx.emit(event). The event needs a type and whatever data your reducer reads. Mint ctx.id() once for a new entity and reuse that id in follow-up events (done / remove / vote):

ctx.emit({ type: ctx.ev("add"), id: ctx.id(), text });  // "note.add" — new entity → new id
ctx.emit({ type: ctx.ev("remove"), id: item.id });      // "note.remove" — follow-up → existing id

Three fields are added for you by the transport on every emit — don't set them yourself, just read them in your reducer:

| field | value | | -------- | ----- | | e.name | the sender's screen name | | e.ts | the send time (epoch ms) — use this for sorting, not Date.now() | | e.uid | the sender's user id — e.g. poll.vote keys votes by e.uid |

Encryption is automatic: emit encrypts the event to the thread key and sends it as a normal message. You never touch keys, and never send plaintext to the server.

Optimistic sends (optimistic: true)

By default an emitted event only appears once the server broadcasts it back — a round-trip's wait, and for a drawing a visible flash (the line vanishes on pen-up, then reappears). Set optimistic: true on your app and the framework folds each emitted event into your state immediately, locally, then lets the authoritative echo quietly replace it:

export const app = defineApp({
  name: "board",
  optimistic: true,   // a stroke shows the instant you lift the pen
  // …
});

How it stays correct: the transport tucks a client id (_cid) inside every event; the server relays the same ciphertext back, so the echo carries it verbatim. The optimistic copy folds with no server message id, and the echo re-folds the same event with the real id. That means your reducer runs on the event twice — so optimistic: true is only safe when your reducer is idempotent by the event's own id (mint it with ctx.id(), land it with a collection helper like addItem). This is the same property every reducer already needs — the message window re-folds on each thread re-open — so most apps qualify already; opt in explicitly rather than assume it. An app whose reducer counts or otherwise applies an event more than once per id must not set the flag. (Chat messages get this treatment built in — an outgoing bubble shows at once and wears a subtle "Sending…" state if it's still unconfirmed after 5s.)

ctx — what a handler and a render get

| member | in | what it does | | ---------------------------- | ------------- | ------------ | | ctx.emit(event) | anywhere | Emit a typed event (encrypted + sent). Returns Promise<boolean>. | | ctx.schedule(event, when) | anywhere | Have the server deliver event into the thread at when (epoch ms). Returns Promise<sid \| null>. | | ctx.unschedule(sid) | anywhere | Cancel a pending scheduled event. | | ctx.id() | anywhere | A fresh unique id for a new entity. | | ctx.ev(name) | anywhere | Your event type from a short name — ctx.ev("add") → "todo.add" (see Namespacing). | | ctx.cls(name) | anywhere | Your CSS class from a short name — ctx.cls("item") → "todo-item". | | ctx.me | anywhere | The current user's id. | | ctx.getState() | anywhere | The app's latest folded state for this thread. | | ctx.threadId | anywhere | The thread the app is acting in. | | ctx.place | anywhere | Where this ctx's copy lives: "you" (the app's own thread), "chat" (a shared copy in a conversation), or "space" (the one space-wide instance). | | ctx.open() | anywhere | Show this app instance — for an action chip, so leaving the current context is always the user's tap. The host picks the surface per place (the app's own thread, a chat copy's Interface pane, the space home). | | ctx.interval(fn,ms) | render only | A ticker the framework stops for you on redraw / reset. | | ctx.onCleanup(fn) | render only | Run fn before the next redraw or on thread reset. | | ctx.panel(spec) | commands only | Open a transient results panel where the command was typed (see "Command panels"). Returns false when the thread can't draw one. | | ctx.closePanel() | commands only | Dismiss that thread's open command panel. |

ctx.interval is how remind.js keeps its relative labels live without leaking a timer — never call setInterval directly in a render, or you'll leak one per redraw.

Replies disclose their place for you. When a command routes away from the thread it was typed in (a personal copy reached from a chat, or the space-wide instance), the framework stamps the reply with the routed place and the notice renders it as a muted footer in the stand-alone place words ("just for you" / "for everyone in this space" — placePhrase; the / typeahead's row labels use the flowing sibling placeRowPhrase). You get this without doing anything. If you want to word the destination yourself, read ctx.place — todo.js ("Added … to the space to-do list.") and remind.js ("I'll remind everyone in this space: …") are the reference examples — but never rely on apps doing so: the framework stamp is the disclosure of record.

Time — scheduled events

ctx.schedule(event, whenMs) is ctx.emit shifted into the future, executed by the server: the event is encrypted now, the server holds the ciphertext, and at the due moment it lands in the thread's message log and fans out exactly like a posted message — every device folds it, closed apps get a push, open apps can toast it. The server learns only (thread, time), never what was scheduled.

// Schedule first — the sid is part of the reminder's record.
const id = ctx.id();
const sid = await ctx.schedule(
  { type: ctx.ev("fire"), id, notice: { title: "⏰ Reminder", body: text } }, // "remind.fire"
  whenMs,
);
ctx.emit({ type: ctx.ev("add"), id, text, when: whenMs, sid: sid || "" });    // "remind.add"

Rules of thumb (all visible in remind.js, the reference implementation):

• Store the returned sid inside an emitted event. It's how any device — not just the one that scheduled — can later ctx.unschedule(sid).
• Give a scheduled event a notice (see Voice) — it's usually the whole point of scheduling one.
• Handle sid === null (offline / error): degrade gracefully (remind falls back to a best-effort client-side ticker for sid-less items).
• The scheduled event is still just an event. Its fold handler must be idempotent like any other — a cancel can race a delivery, so e.g. a remind.fire folding onto an already-removed id must be a no-op (it is, with updateItem).
• Cancelling an id that already fired succeeds quietly; that race is expected.

Memory — snapshots (automatic)

The client only holds a window of a thread's messages (~100), but folded app state is snapshotted automatically: after new events fold, the framework saves { states, upTo } — encrypted under the thread key — to the server (thread_state, versioned against concurrent writers), and re-seeds it when the thread opens, folding only events newer than upTo on top.

You get this for free. It works because of the reducer rules: folds are pure and deterministic, so snapshot + newer events ≡ folding all of history. What it means for you:

• Don't bound your state by the window. A 1,000-item todo list is fine.
• State is durable, so treat it with respect: never put anything in reducer state you wouldn't put in an event (it's all encrypted, but it's persisted). Credentials for a third-party service an app talks to can live here — the server sees only ciphertext — but prefer an event (service.connect) so all devices learn them through the normal fold.
• Schema-evolve defensively. A snapshot written by an old version of your app will be seeded into a new version. Reducers and render must tolerate missing fields (e.note || "" — the same rule as for old events).

Voice — talking to the user

Apps can speak the moment something happens, wherever the user is:

1. notice on an event — the simple, usual way. Any event (typically a scheduled one) may carry notice: { title, body }. When it arrives live, the framework toasts it in-app and raises a system notification if the page is hidden; when the app is closed, the service worker decrypts the push and shows the same notice. One field, every situation, end-to-end encrypted.

1. A notify(event, ctx) hook — for wording that depends on state. Called only for live events (never during history refolds — replaying the past must not re-alert it). Return { title, body } or null for silence:

``js notify(e, ctx) { if (e.type !== "poll.create" || e.uid === ctx.me) return null; return { title: "📊 New poll", body: e.q }; }, ``

App events with neither are silent — a todo.add from your other device never buzzes anyone. (Chat messages have their own notification path; this section is only about app events.)

Ephemeral events — presence without a trace

ctx.emitEphemeral(event) relays an event to the thread's connected members and forgets it: never stored, never pushed, never folded. It's for presence traffic — typing indicators, live cursors — where persistence would be wrong, not just wasteful. Receivers handle it in the app's ephemeral(event, ctx) hook; senders get their own echo (check e.uid !== ctx.me or filter by name).

Two rules:

• Own the type. Routing is by event type, so an ephemeral type must appear in your events map — claim it with a no-op fold ("chat.typing": (s) => s). That also makes it harmless if a hostile client stores one as a real message.
• Never touch reducer state from the hook. Ephemeral events are allowed to differ between devices (some were offline when it fired); folding one would break convergence. Keep transient UI in module-level state and redraw it yourself (see shell.js's typing line).

Incremental surfaces — keyedList

By default the framework wipes and rebuilds an app's surface on every state change — the right default for small surfaces. For long lists (a chat feed, a big checklist) set incremental: true (the framework stops wiping) and reconcile with keyedList:

keyedList(listEl, state.msgs, {
  key: (m) => m.id,          // stable identity
  rev: (m) => m.editedAt,    // re-render an item only when this changes
  render: (m) => buildRow(m) // build one item's DOM
});

Unchanged items keep their exact DOM nodes — scroll position, focus, and loaded images survive; appends build only the new item. The container must be fully managed by keyedList (no other children). Build any once-only skeleton (composer, headers) on first render by checking whether it already exists.

Rendering a surface

render(state, el, ctx) is called whenever state changes. The framework clears el first, so always rebuild from state — don't diff.

• Personal apps render full-pane: el is the thread view. Usually an add form on top, then the list.
• Shared apps render a panel above the chat feed. Render nothing when state is empty (just return) so the panel collapses until there's something to show. See poll.js.
• Never innerHTML user content. Build nodes with createElement and set text with textContent. innerHTML is only OK for static in-code strings.
• Style with the theme's CSS variables (--ink, --muted, --accent, --border, --panel, --bubble-them, …) so the app follows light/dark.

Optional: messageAction(msg)

Contribute an item to a chat message's long-press / hover menu. Given the decrypted message { text, from }, return { label, glyph, run(ctx) } to offer the action, or null to sit this message out. The run gets a ctx already bound to your app-thread (for a personal app), so the action files into your app. This is how bookmarks.js offers "Save link" on any message with a link:

// import { firstLink } from "../format.js";
messageAction(msg) {
  const url = firstLink(msg.text || "");
  if (!url) return null;
  return {
    label: "Save link",
    glyph: "🔖",
    run(ctx) {
      ctx.emit({ type: ctx.ev("add"), id: ctx.id(), url, from: msg.from || "" });
    },
  };
},

Optional: renderEvent(event, meta)

Return a DOM node to show an inline line in the message feed for one of your events (e.g. "Poll created"), or null to keep it silent. Most apps return nothing and render only in their surface.

What the server provides (and what it can see)

Everything an app touches goes through ctx — you never call these endpoints yourself — but knowing the surface keeps the trust model clear. In every row the blob is encrypted client-side under the thread key; the server can never open it.

| capability | endpoint(s) | server learns | | -------------- | ---------------------------------------- | ------------- | | Event log | POST /api/messages, GET /api/messages, WS msg | thread, time, size | | Scheduling | POST/GET /api/schedule, DELETE /api/schedule/{id} | thread, delivery time | | State snapshots| GET/PUT /api/threads/{id}/state | thread, size, write times | | Attachments | POST /api/upload, GET /api/blob/{id} | size | | Push fan-out | (server-initiated) | who is subscribed |

All endpoints are token-gated and thread-membership-gated. Server code lives in miniapps.go (scheduling + state), hub.go (fan-out), push.go (Web Push).

The app UI itself is client-side ES modules under web/static/ (this folder), embedded in the binary via go:embed — as are the HTML pages in web/pages/ (served with the group name substituted). There is currently no per-app server-rendered HTML; an app IS its module. (If an app ever needs a public, unauthenticated page, that's a new, deliberate surface — design it with the same rule: the server serves only what it's allowed to see.)

Mixing deterministic and LLM behaviour

An app's deterministic core is the reducer + commands: same events in, same state out, unit-testable in Node. When you want judgment, language, or agency, you don't bolt an API call into the app — you invite a bot into the thread.

Bots (see docs/bots.md) are ordinary members with keys: a bot in a thread decrypts its events like any member, and its sidecar can emit app events back through the same POST /api/messages doorway (lchat-post encrypts in the sidecar's trust domain). That composes with everything above, with no new machinery:

• the bot reads your app's events as they happen (they're just messages),
• the bot writes events your reducer already understands — to your fold, an LLM's contribution is indistinguishable from a human's,
• your reducer stays the deterministic arbiter: it validates every event the same way regardless of who emitted it (it already must — see Invariants).

So "add AI to an app" = define the events, let the bot emit them. Example: a /plan dinner party app where a bot member watches plan.create and responds with plan.suggest events the reducer folds into the list — every suggestion encrypted, attributed (e.uid is the bot), and replayable.

Chat as an app — the default chat experience

shell.js (scope system) is the chat feed: group/DM threads render it full-pane by default. It is the original chat retooled onto the framework, not a parallel one. There is no new wire protocol: its composer emits the same untyped { text } payload every client has always understood, and the host feeds the app exactly what the original feed consumed:

• each stored message's decrypted payload (text, attachment metadata, replyTo) folds as a host event keyed by its server message id — history, live, and scroll-back pages alike,
• the server's reaction / edit / delete frames fold as host translations (hostEvents, so no wire payload can spoof them — the server-enforced authorship and dedupe rules keep applying),
• typing rides the one wire type the app owns, as a relay-only ephemeral event,
• everything outbound (send, react, edit, unsend, upload, unfurl, older pages) goes back through the host machinery via a narrow bridge (setHost) — the app never touches crypto or tokens.

The app renders the ORIGINAL MARKUP: every element uses the same class names and structure the original appendMessage builds (.msg/.content/.bubble, .time-sep, .msg-actions hover strip with the exact time, .reply-quote, .reactions, .emoji-picker, the original composer classes), so style.css styles both feeds identically and there is no duplicated CSS — hover reveals, spacing, gestures all match by construction. The app's own stylesheet is a few lines of layout glue (a display: contents item wrapper; a mirror of the one id-based #feed rule). Feature surface: rich text (same tokenizers), @mentions with the member menu, jumbo emoji, time separators and sender runs, images (box reserved pre-decrypt, lightbox) and file chips, YouTube cards and unfurls, replies (quote + banner + tallies + swipe-right on touch), editing (15-min window, ↑-to-edit, ↓-to-cancel, full payload rebuild), reactions (hover icon, press-hold / double-tap picker, chips), unsend, attachment sending, paste/drop, typing rows in-feed, slash commands, helper action chips, the :emoji/@mention composer typeahead (one shared ranking function), and scroll-back pagination.

What stays deliberately OUTSIDE the event model — the boundaries of the fold, worth knowing when you design any app:

• Unsend / edit — real deletion removes ciphertext from the server's log (author-verified); an append-only fold could only tombstone. The app renders these but the mechanism is the server's, reached via the host bridge.
• Finding and inviting people — roster, invites, key wrapping: identity machinery, not thread events. (A pending DM also stays on the original path until the invitee joins — its waiting-card gating lives there.)
• Reactions' emoji live in a plaintext server column (pre-app mechanism); migrating them to encrypted fold events is a candidate follow-up.

One deliberate restyle: the original touch action sheet was a full-screen long-press menu; the app's long-press opens the compact emoji picker (same actions, Copy included) instead.

Sidebar presence hooks

An app decides how its events appear in the chat list: preview(event) returns the sidebar preview line, unread(event) says whether a live event lights the thread's unread dot. Both default to silent (the old behaviour); poll opts in — a new poll previews as 📊 <question> and marks unread, while votes stay quiet. Push wording for app events is the notice field (Voice).

🤖 preview gets no { group }-style hint and no ctx — it's a pure event => string, called for BOTH your personal thread's row and a group's. Two things worth knowing before you write one (learned adding vault.js's):

• It runs your event through, not a generic formatter. Before preview existed for a given type, the host fell back to treating the raw typed event as if it were a plain chat message (reading .text) — which a typed event doesn't have, so a group row read as the sender's name, a colon, and nothing ("Ciara: "). This is fixed at the host level (both the live path and the cold-load path in shell.js's loadThreads now call preview() for any typed event, updating the row only when it returns non-null) — but it means any event type your reducer owns should either have a preview line or stay silent on purpose; there's no longer a "raw" fallback to fall into by accident, so don't leave a type unhandled by assuming something reasonable will show.
• "You" is on you. Unlike chatMessage (attributed by the host, see above), preview has to do its own "your own event" check — import currentUserId from ../apps.js and compare it to event.uid: ``js import { defineApp, currentUserId } from "../apps.js"; preview(e) { const who = e.uid && e.uid === currentUserId() ? "You" : e.name || "Someone"; return ${who} did the thing; } ` currentUserId() exists for exactly this — a narrow door to "who's reading" for the pure hooks (preview, and any future one) that don't get a ctx`.

Embedded (native shell) mode

The iOS/macOS shell renders one thread per webview and draws its own composer, speaking a small contract: window.lchatNative inbound (sendText / typing / stageAttachment / cancelReply / typeahead / didAttach) and nativePost outbound ({replying}, {staged}, {error}). The chat app implements the same contract and is the default in the webview too; the host routes window.lchatNative to the app's composer handlers, the app hides its own composer chrome, and reply banners / staged state / errors post back to the shell. A shell that needs the original feed sets originalChat: true on the injected __lchatEmbed config.

Switching engines

The chat app is the default. A device switches to the original feed with the ⋮ menu → “Use original chat” (or localStorage.setItem("lchat-original-chat", "1")) — the same menu item switches back, and on the original feed the composer placeholder reads “Message (original chat)” so you always know which engine you're on. Once the original path has soaked out of rotation, it (~2k lines of shell.js plus its CSS) can be deleted.

The design rule stands: don't add app capabilities chat couldn't use, and prefer generalising an existing chat mechanism (as ephemeral generalised the typing frame) over inventing an app-only parallel.

Invariants (the things that fail silently if you skip them)

1. Idempotent fold. The message window is re-folded from scratch on every thread reopen, so folding the same add twice must produce one item. addItem handles this by deduping on id; a custom fold must dedupe too. (The framework also skips re-folding the same server message within a session, but that doesn't cover a genuinely duplicated emit — dedupe on your entity id.)
2. Pure, immutable reducers. Never mutate prior state. The collection helpers return fresh arrays; if you go custom, spread ({ ...obj }, [...arr]). This is also what makes snapshots (Memory, above) correct.
3. Don't set name / ts / uid on emit — the transport injects them. Setting ts: Date.now() is dead code (the transport overwrites it).
4. Namespace event types with your app name; they're globally unique. namespace(name) (see Namespacing) derives them for you so the prefix can't drift.
5. Never innerHTML user content — textContent / DOM nodes only.
6. Widget-pane apps render an honest empty state (a one-line hint beats a blank pane — see poll.js).
7. You never touch the server or keys. State persistence, scheduling, and notifications all flow through ctx — if you find yourself reaching for fetch or a key, you've taken a wrong turn.
8. Validate events in the reducer, not at the emitter. Anything a thread member (person, other device, bot) can send is a legal input to your fold — malformed or hostile events must fold to a no-op, never a crash or a lie.
9. A scheduled event will arrive later, into different state. Fold handlers for scheduled types must tolerate their target being gone (dismissed while the delivery was in flight).

Testing

Pure logic (reducers, parsers) is unit-tested in Node — see test/apps.test.mjs. Import the app object and test its synthesised reducer directly:

import { app as noteApp } from "../web/static/apps/note.js";
const reduce = noteApp.reduce;
// reduce(undefined, { type: "note.add", id: "a", text: "hi" }) → { items: [ … ] }

Keep any non-trivial parsing pure and exported (like parseReminder in remind.js) so it's testable without the DOM.

Shipping checklist

• [ ] web/static/apps/<name>.js — one file, self-contained (logic + styles).
• [ ] import "/static/apps/<name>.js"; added in web/static/shell.js.
• [ ] node --check web/static/apps/<name>.js passes.
• [ ] Reducer / parser tests added to test/apps.test.mjs; npm test green.
• [ ] A panel-opening command? Add it to WebPanelCommands.catalog (ios/LChatCore/.../SlashCommands.swift) so the native apps forward it.
• [ ] A user-facing changelog entry in changelog/<date>-<slug>.md.
• [ ] No trailing whitespace; user content rendered with textContent.

🤖 Voice: how one event speaks on every surface

An app's events can surface in three places, each with its own hook — and a defaulting chain so declaring less still reads well everywhere:

1. The chat feed — chatMessage(e, opts) / groupFeedMessage(e). Action lines are actor-neutral (added “X” to the to-dos); the HOST prefixes the actor ("You" for the reader's own act, their name otherwise) — never the app. Group lines should say where the data went ("to the to-dos"); the personal thread IS the list, so it stays terse.
2. The thread-list preview — preview(e, opts), with opts.you when the host resolved the actor as the reader. No hook → the chat projection speaks for the sidebar too, actor-prefixed.
3. Notifications — the event's notice: {title, body} when set; otherwise the same projection chain as the preview. State-only events (a whiteboard stroke) project null and stay silent everywhere.

Native clients honour the same chain: schema apps project natively (AppChatProjection mirrors the wording — change both sides + the vectors together), everything else answers through the app host (projectEvent/previewEvent, docs/native-apps.md).