brane 0.3.0 → 0.3.2

package/docs/view-urls.md

@@ -3,7 +3,7 @@
 The query string of a narrative screen is not decoration — it is the only way
 a view travels. Active tab, pinned tabs, open file and line range are kept in
 `sessionStorage`, which is **origin-scoped**, and two menu items cross an
-origin: **Isolate** hops between `brane.organelle.dev` and a daemon's own
+origin: **Isolate** hops between a shared app's origin and a daemon's own
 bundle, and **Meld** hands a URL to another device. Whatever is not in the URL
 does not arrive.
 
@@ -15,16 +15,36 @@ tab, pin subset, path and line spec):
 |---|---|
 | `viewParams()` | The view as params, `undefined` for anything at its default — which is how `router.setParams` clears one |
 | `parseActiveTab()`, `parsePinnedTabs()`, `parseLineSpec()` | Read them back. Writer and reader live together on purpose: a param whose two halves sit in different modules drifts |
+| `isIsolated(pageHost, daemonHost)` | Whether this page is the daemon's own bundle: `location.host` against the connection's host, no constant in it |
 | `buildViewUrl(target, opts)` | The same narrative, same view, somewhere else |
-| `buildIsolateUrl()` / `buildMeldUrl()` | The same builder with one bit different — see below |
+| `buildIsolateUrl()` / `buildMeldUrl()` | The same builder with one bit different — see below. Isolate is `null` from a daemon's bundle that reported no app host |
 | `withoutConnectionParams()`, `withoutConnectionHash()` | Strip `host`/`token` from the query string and from the fragment, and leave everything else |
 | `connectionFragment()` | `#host=…&token=…` for the shared app, `#token=…` for a daemon's own bundle — the one place the connection is written into a URL, used by `buildViewUrl` and by `brane meld` |
 
 **Isolate flips the origin kind; Meld stays on it.** Isolate exists to change
-which app serves you. Meld aims at another *device* — hand a phone a shared-SPA
+which app serves you. Meld aims at another *device* — hand a phone a shared-app
 link while the operator is reaching the daemon directly, and the phone loads an
 app that has never heard of that daemon.
 
+**The app knows no host.** There is no constant naming `brane.organelle.dev`
+in the bundle, and `src/test/app-host-literal.test.ts` keeps it that way.
+"Isolated" means *this page is served by the daemon it is connected to*:
+`window.location.host` equal to the connection's host, which a daemon's own
+bundle fills from the same `location.host`. Everything else is a shared app,
+whichever host serves it: the hosted shell, a staging hostname, a fork's
+deployment, a dev server on `localhost`. From a shared app, Meld stays on
+*that* origin and Isolate hops in to the daemon; neither needs to be told a
+host. From a daemon's bundle, Isolate hops *out* to whatever the daemon
+reports as its `app_domain` in `GET /api/status` (`useAppHost`,
+`expo/lib/appHost.ts`, fetched before the tap, since a `window.open` after an
+await is a popup the browser blocks). A daemon that reports none, or cannot
+be reached for it, has no way out, and the menu leaves Isolate out rather
+than hand you a link to a host the app made up. `brane meld` reads the same
+config, so a fork changes `CONFIG_DEFAULTS.app_domain` and both its CLI and
+its daemons name its own shell. None of this is trust: the daemon accepts any
+origin (`SECURITY.md`, Authentication); the host only decides which copy of
+the app a browser loads.
+
 **Back undoes a jump, never a view change.** A jump pushes a history entry: to
 a different narrative (from the list, an `@nid` link, the switcher, Revive or
 Twin), and to a message by `nid:seq`, *including one in the narrative you are
@@ -37,7 +57,12 @@ since the stack did not grow. So the URL keeps that state and Back returns to
 it, but it never costs an extra Back: browsing ten files is one entry, not ten.
 A bare link to the narrative you are in, with no seq, goes nowhere. The list
 is a jump too: **All narratives** in the switcher pushes it, so Back returns
-to the narrative, whether or not a list was already beneath. The header has no
+to the narrative, whether or not a list was already beneath. So does a
+swipe down on the narrative's header card, which dismisses it. So does
+**Archive** in the narrative's 🦠 menu, once the daemon has confirmed it (the
+pushed list fetches on mount, and nothing is broadcast to correct a fetch that
+raced the archive); Back returns to the archived narrative. Archiving from the
+list's own menu just drops the row and goes nowhere. The header has no
 ← of its own; Back is the browser's.
 
 Back is instant and complete because the Stack keeps the screens behind the
@@ -86,9 +111,9 @@ by resetting to the bare pathname, which would throw away the view that just
 arrived.
 
 **The connection rides in the fragment; the view rides in the query string.**
-A query string is part of the HTTP request. On a `brane.organelle.dev` link
-that meant the daemon's bearer token and tailnet hostname reached Cloudflare's
-edge with every meld; on an Isolate hop it landed in the daemon's own request
+A query string is part of the HTTP request. On a shared-app link that meant
+the daemon's bearer token and tailnet hostname reached the shell host's edge
+with every meld; on an Isolate hop it landed in the daemon's own request
 log; and a meld URL pasted into iMessage or Slack handed it to the link
 unfurler. A fragment is never sent to any server, so `#host=…&token=…` is what
 every link carries now (`connectionFragment`), and `?token=` is read only for

package/docs/web-app.md

@@ -1,6 +1,6 @@
 # Web App (Expo)
 
-The Expo app runs as a web PWA served by the daemon (and optionally via Cloudflare Workers at `brane.organelle.dev`). It provides:
+The Expo app runs as a web PWA served by the daemon (and optionally via Cloudflare Workers at `brane.organelle.dev`, which serves the app of the `latest` npm release and is deployed only by a release — see [The app ships with the release](releasing.md#the-app-ships-with-the-release)). It provides:
 
 - **Narrative list** — shows all narratives with summary, status, and MCP connection indicator
 - **Spawn button** — header button that opens fold picker modal (or spawns directly with 1 fold)
@@ -13,7 +13,7 @@ The Expo app runs as a web PWA served by the daemon (and optionally via Cloudfla
 - **Quick bar** — macros (via MacroMenu component) + quick keys
 - **Full software keyboard** — multitouch with sticky/held modifiers
 - **Live updates** — control WebSocket pushes `status`, `meta`, and `new_events` hints
-- **Archive/unarchive** — swipe or long-press to archive narratives
+- **Archive/unarchive** — from the 🦠 menu, on a list card's status badge or in the narrative's header. Archive is offered only once the session has ended (the same test that swaps End for Revive); Unarchive on any archived narrative. Archiving from the header goes to the list as a jump, so Back returns — see [View URLs](view-urls.md)
 - **Payload rendering** — inline display of image payloads in chat
 - **Export** — download a narrative as standalone HTML via `/api/narratives/:id/export?format=html`. Foreign rows carry their speaker's hue inline, from the same `speakerColor` / `speakerBgColor` the chat uses, at the 🎨 Recolor salt the device sends as `&palette=` — the one place the salt leaves the browser. With messages selected, the menu offers both sides of the selection — **those messages only**, or the conversation with **those messages left out** — see [Export Scope](export-scope.md)
 - **Brane switcher** — dropdown to filter narratives by brane, add/switch daemons. Each brane row (and "All branes") shows its running metered cost as `$2441.72 (138) + 100.2 AIC (1)` — one total per unit with the number of sessions it covers, so a per-session figure can be read off without the line asserting one; the list screen re-reads `/api/branes` (debounced) when a cost `meta` arrives, since the total includes archived narratives the screen never loads. **Devices** lists every token on the active daemon (this device, this machine's CLI and agents, each melded device by browser, platform, address and when it was last seen, and any meld QR not yet scanned) with a Revoke on each other device; **Sign out other devices**, at the foot of that list, rotates instead — see [Token Rotation](token-rotation.md#the-devices-list)