@brass-build/client 0.1.0 → 0.2.0

package/README.md

@@ -35,23 +35,17 @@ npm install @brass-build/client
 
 ## Quickstart
 
-`@brass-build/client` turns a document into a live, multi-user,
-persistent workspace. Your app supplies the UI; Brass supplies sign-in,
-the file toolbar, and one subscribe-render-mutate loop per open
-document. A working app is mostly your own rendering and event handling
-wrapped around a handful of Brass calls.
-
-**Describe it to a coding agent.** An app's dashboard page shows a
-ready-to-paste prompt with its id already filled in. Paste it into
-Claude, Cursor, or another assistant; the assistant reads this README
-and [`AGENTS.md`](./AGENTS.md), then wires, verifies, and ships the
-integration. The prompt is one line naming what you want and the SDK:
+The easiest way to use Brass is to tell a coding assistant to do it for
+you. Paste a line like the one below into Claude, Cursor, or another
+assistant. The assistant reads this README and
+[`AGENTS.md`](./AGENTS.md), then wires, verifies, and ships the
+integration.
 
 ```
 Build a shared checklist on @brass-build/client (NPM).
 ```
 
-**Or wire it by hand.** The Brass surface of an app is small:
+**Or wire it by hand.**
 
 ```ts
 import { Brass } from '@brass-build/client';
@@ -87,8 +81,7 @@ await Brass.init('brass_app_...');
 
 `bindEditor` is your code: take a handle for the data you render
 (`doc.orderedMap('items', 'item_order')` for a checklist), `subscribe`
-to paint your list, and call `.mutate` from a click. The rendering,
-styling, and event handling around it are ordinary app code.
+to paint your list, and call `.mutate` from a click.
 [Document lifecycle](#document-lifecycle) and
 [Editing documents](#editing-documents) show the loop in full.
 
@@ -102,8 +95,8 @@ npx @brass-build/cli publish ./dist
 ```
 
 The first publish creates the app, hosts it at
-`https://<slug>.onbrass.app`, and writes its id to `.brass/project.json`
-(the `brass_app_...` above). Your users sign in at that URL.
+`https://<slug>.onbrass.app` where your users sign in, and writes the
+app id (the `brass_app_...` above) to `.brass/project.json`.
 
 ## Setup
 
@@ -111,18 +104,18 @@ To take the [quickstart](#quickstart) from source to a
 signed-in, hosted app:
 
 1. **Set up the bundler.** The SDK ships a WebAssembly module, and your
-   bundler needs to know how to load it; see
+   bundler needs to know how to load it. See
    [Bundler setup](#bundler-setup).
 2. **Ship it.** `npx @brass-build/cli publish ./dist` creates the app,
-   hosts it, and returns a URL your users sign in at. A hosted bundle
-   needs no app id; it inherits one from its serving origin. See
-   [Ship it](#ship-it).
-3. **Local dev and self-hosting need an app id.** Pass it to
-   `Brass.init('brass_app_...')`. The first publish writes the id to
-   `.brass/project.json`, or copy it from the app's dashboard page. A
-   new app already allows sign-in from `localhost` / `127.0.0.1` on any
-   port with no allowlist step; add a self-hosted origin on the app's
-   detail page.
+   hosts it, and returns its sign-in URL. See [Ship it](#ship-it).
+3. **Pass an app id unless Brass hosts your bundle.** Brass resolves
+   the id from its own hosting origins, so a published bundle calls
+   `Brass.init()` with no argument. Pass the id everywhere else, in
+   local development and on your own origin:
+   `Brass.init('brass_app_...')`. Read it from `.brass/project.json`,
+   which the first publish writes, or copy it from your app's page in
+   the dashboard. A new app already allows sign-in from `localhost` /
+   `127.0.0.1` on any port; add your own origin on that same page.
 
 **CSP.** If (and only if) your app sends a `Content-Security-Policy`,
 extend it: `script-src` needs `'wasm-unsafe-eval'` for the SDK's
@@ -134,43 +127,38 @@ picker and share dialog, and `img-src` needs
 ### Bundler setup
 
 `@brass-build/client` ships as ES modules, loaded by a bundler (Vite,
-webpack, esbuild) or Node's ESM loader with `import`.
+webpack) or Node's ESM loader with `import`.
 
-Without a WASM loader, `npm run build` fails with
-`[vite:wasm-fallback] ... "ESM integration proposal for Wasm" is not
-supported`. For Vite, install two plugins and add the SDK's own helper:
+Without a WASM loader, `vite dev` fails with `"ESM integration proposal
+for Wasm" is not supported currently`. Install one plugin and add the
+SDK's own helper:
 
 ```sh
-npm install --save-dev vite-plugin-wasm vite-plugin-top-level-await
+npm install --save-dev vite-plugin-wasm
 ```
 
 ```ts
 // vite.config.ts
 import { defineConfig } from 'vite';
 import wasm from 'vite-plugin-wasm';
-import topLevelAwait from 'vite-plugin-top-level-await';
 import { brassVite } from '@brass-build/client/vite';
 
 export default defineConfig({
-  plugins: [wasm(), topLevelAwait(), brassVite()],
+  plugins: [wasm(), brassVite()],
   build: { target: 'es2022' },
 });
 ```
 
 `brassVite()` configures Vite's dep-prebundling step so the SDK's WASM
-runtime loads on first `vite dev`. Vite 5/6 need
-`vite-plugin-top-level-await`; Vite 8's rolldown bundler supports
-top-level await natively. Webpack 5 needs `experiments.asyncWebAssembly: true` plus a
-matching top-level-await plugin. The WASM bundle is ~3 MB uncompressed
-(~600 KB gzipped).
+runtime loads on first `vite dev`, and it names the SDK's WebAssembly
+dependencies for you, so your config keeps working as they change.
+Webpack 5 loads them with no extra configuration.
 
 ### Init
 
-The first argument to `Brass.init` is your `app_id` (a hosted bundle
-omits it and inherits the id from its serving origin). The second is a
-typed options object
-(`BrassInitOptions`); the defaults are right for most apps, so you
-usually pass nothing:
+The first argument to `Brass.init` is your `app_id` ([Setup](#setup)
+covers when you need one). The second is a typed options object,
+`BrassInitOptions`. Its defaults suit most apps:
 
 | Init option | Default |
 | ----------- | ------- |
@@ -183,7 +171,7 @@ usually pass nothing:
 
 `Brass.init` resolves after one auth round-trip. Register `onError`
 and `onUserChange` BEFORE calling `init`, so that validation failures
-fire through your listener instead of dying as unhandled rejections; a
+fire through your listener instead of dying as unhandled rejections. A
 bad `app_id` still resolves, with `Brass.user === null`.
 
 ### Ship it
@@ -198,9 +186,9 @@ npm run build
 npx @brass-build/cli publish ./dist
 ```
 
-The first run creates the app, enables hosting, uploads the build, and
-writes the app id to `.brass/project.json`. Commit that file so later
-publishes and your teammates target the same app.
+The first publish creates the app, enables hosting, uploads the build,
+and writes the app id to `.brass/project.json`. Commit that file so
+later publishes and your teammates target the same app.
 
 Run `brass login` once first to authenticate (it opens your browser),
 or set `BRASS_SERVICE_TOKEN` in a pipeline. The CLI also pulls a
@@ -211,27 +199,23 @@ document's schema into your `brass-app.json`. See
 
 Auth has **four** states: `Brass.authStatus` is
 `'unknown' | 'signed-in' | 'signed-out' | 'guest'`, where `'unknown'`
-is the bootstrap window before `init` settles. The distinction matters
-because a page reload always passes through `'unknown'`, and during it
-`Brass.user` is still `null` even for a signed-in user. Never gate a
-sign-in CTA on `!Brass.user`: that flashes the sign-in screen at
-signed-in users on every reload. Render the CTA only on
-`'signed-out'`, and render your working surface for **both**
-`'signed-in'` and `'guest'`.
+is the bootstrap window before `init` settles. A page reload always
+passes through `'unknown'`, and during it `Brass.user` is still `null`
+even for a signed-in user, so gating a sign-in CTA on `!Brass.user`
+flashes the sign-in screen at signed-in users on every reload. Render
+the CTA only on `'signed-out'`, and render your working surface for
+**both** `'signed-in'` and `'guest'`.
 
 `'guest'` is the "anyone with the link" case: someone opened a public
 view link, so there is no signed-in user but `Brass.session` still
 opens the shared document **read-only** for them (`Brass.isGuest` is
 `true`). When the page URL carries the link token, the session boots
-the read-only document automatically; render your working surface for
-`'guest'` too (the document is read-only, so edits are already
-disabled).
+that read-only document on its own.
 
 `Brass.onUserChange` is the single source for reacting to auth
 changes. It fires once when `init` resolves (with the real user or
 `null`), then on every sign-in and sign-out. A listener registered
-before `init` does not fire on registration; one registered after
-does.
+before `init` does not fire on registration. One registered after does.
 
 The plain-DOM sample in the [quickstart](#quickstart) gets this
 right with no extra code, because both shells start `hidden` and
@@ -256,11 +240,9 @@ Brass.onUserChange(() => { authStatus.value = Brass.authStatus; });
 `Brass.mountToolbar(container)` fills a container with the full
 document toolbar, wired to the session: creating, opening, renaming,
 sharing, and deleting documents, undo / redo, an account menu, and a
-presence roster. Grow beyond it into your own header only when you need
-one, and even then compose
-the standard pieces (below) rather than rebuilding them. The call
-returns a `tools` slot where your app's own persistent controls (a mode
-palette, a save indicator) sit alongside the standard pieces:
+presence roster. The call returns a `tools` slot where your app's own
+persistent controls (a mode palette, a save indicator) sit alongside
+the standard pieces:
 
 ```ts
 const bar = Brass.mountToolbar(document.getElementById('app-bar')!);
@@ -280,21 +262,21 @@ filling the rest:
 ```
 
 **Mount it once when the user signs in, not when a document opens.**
-New and Open live in its file menu, so the bar has to exist in the
-"signed in, nothing open" state; otherwise a user who just signed in
-has no way to open or create a document. It re-renders itself as
-documents open, switch, and close. It takes options `{ presence?, account? }` (both
-default to `true`), and the returned handle's `destroy()` removes it.
-
-A multi-pane app that builds its own header can still take the
-standard pieces (file menu, title, undo / redo, presence roster,
-drive-sync badge, account menu) individually instead of
-re-implementing them; see "Composable header pieces" in
-[`docs/custom-chrome.md`](./docs/custom-chrome.md). Include the
-drive-sync badge (`Brass.mountDriveSync(el)`): on a document linked to
-a connected drive it carries the user's pull, publish, and reconcile
-actions, and on any other document it renders nothing, so mount it
-unconditionally.
+New and Open live in its file menu, so a user who has just signed in
+reaches a first document only through a bar that is already there. It
+re-renders itself as documents open, switch, and close. It takes
+options `{ presence?, account?, drive? }` (all default to `true`), and
+the returned handle's `destroy()` removes it.
+
+A multi-pane app that builds its own header takes the standard pieces
+(file menu, title, undo / redo, presence roster, drive-sync badge,
+account menu) individually rather than re-implementing them. See
+"Composable header pieces" in
+[`docs/custom-chrome.md`](./docs/custom-chrome.md). Mount the
+drive-sync badge (`Brass.mountDriveSync(el)`) unconditionally: on a
+document linked to a connected drive it carries the user's pull,
+publish, and reconcile actions, and on any other document it renders
+nothing.
 
 ## Document lifecycle
 
@@ -317,9 +299,8 @@ Brass.session.subscribe((session) => {
 
 `session.subscribe` fires on lifecycle changes (open, close, switch,
 command state, sign-in / sign-out), and calls your callback with the
-`DocumentSession` synchronously on registration. It does **not** fire
-on document edits; those arrive through the document's own `subscribe`
-(below).
+`DocumentSession` synchronously on registration. Document edits arrive
+through the document's own `subscribe` (below), not here.
 
 `session.status` tells you which of six screens to render:
 
@@ -335,24 +316,22 @@ on document edits; those arrive through the document's own `subscribe`
 Gate edit affordances on `ready`: a canvas that accepts input in the
 `empty` state lets the user produce work with nowhere to save it.
 
-**When an open fails.** A link to a document that was deleted, or that
-the user cannot access, fails the open and the session enters `error`.
-Someone else deleting the document while the user is editing lands in
-the same state, so one screen covers both. Render the platform's
-message with your own recovery actions:
+**When an open fails.** The session enters `error` when it cannot open a
+document: someone deleted it, the user cannot access it, or Brass could
+not prepare it (a file it could not read). Someone else deleting the
+document while the user is editing lands in the same state, so one
+screen covers them all. Render the platform's message with your own
+recovery actions:
 
 ```ts
-if (session.status === 'error') {
+if (session.error) {
   showMessage(session.error.message); // render verbatim; don't write your own
   // ...alongside your app's own New / Open buttons.
 }
 ```
 
-Display `session.error.message` verbatim; the platform authors it,
-like `session.loadingMessage` and `doc.status.message`. Supply the
-recovery actions yourself (your New / Open buttons). Use
-`session.error.status` for logging or your own handling. A failed open
-from an already-open document is different: the session keeps the
+Use `session.error.status` for logging or your own handling. A failed
+open from an already-open document is different: the session keeps the
 document you were editing and the `open()` call rejects, so catch that
 at the call site instead.
 
@@ -364,6 +343,14 @@ indeterminate). The document binds only after its content downloads,
 so the first `ready` render already has the real model to read
 directly.
 
+**Work on an open document.** Brass prepares an imported file, syncs a
+document to its drive, and does other work while the document is open.
+`doc.status` carries that work and reads `null` when there is none;
+`doc.onStatus(cb)` fires on every phase. Render `status.message`
+verbatim and read `status.pending` for whether the work is still
+running. The message is prose written for the reader, so show it rather
+than parsing it or inferring a phase from it.
+
 **Where new documents land.** The `new` command (and
 `session.create()`) places the document for you: a sibling of the open
 document, or a platform-chosen home from the empty state.
@@ -393,14 +380,14 @@ document.addEventListener('keydown', (e) => {
 });
 ```
 
-Code that runs outside the render loop can await the bound document
-with `await Brass.session.whenReady()`; it resolves with the same
-instance as `session.document`, immediately if one is already bound,
-and rejects if the open fails or the user signs out before one binds.
+Code that runs outside the render loop awaits the bound document with
+`await Brass.session.whenReady()`. It resolves with the same instance
+as `session.document`, immediately if one is already bound, and rejects
+if the open fails or the user signs out before one binds.
 
-The hosted dialogs (`Brass.selectDocument()`, `Brass.shareDocument()`)
-handle browsing, picking, and sharing existing documents; the
-session's Open and Share commands invoke them for you.
+The session's Open and Share commands invoke the hosted dialogs
+(`Brass.selectDocument()`, `Brass.shareDocument()`) for you, so
+browsing, picking, and sharing an existing document take no code.
 
 ## Editing documents
 
@@ -412,11 +399,16 @@ in [Document lifecycle](#document-lifecycle) does this in `bindEditor`,
 called whenever `s.document` changes:
 
 ```ts
+import type { Document } from '@brass-build/client';
+
 function bindEditor(doc: Document): void {
   const walls = doc.map<Wall>('walls');
-  // One subscribe line is the whole render loop; the first fire
+  // One subscribe block is the whole render loop; the first fire
   // carries the current state, so there is no separate initial render.
-  const stop = walls.subscribe(() => renderWalls(walls.read()));
+  const stop = walls.subscribe((change) => {
+    for (const [id, wall] of change.set) reconcileWall(id, wall);
+    for (const id of change.deleted) removeWall(id);
+  });
   doc.onGone(() => stop());
 }
 ```
@@ -430,11 +422,18 @@ rebind and strand your editor on the previous state.
 
 The primary editing surface is a **typed container handle**:
 `doc.map<T>(key)` returns a scoped reference to one root container,
-and its `read`, `mutate`, and `subscribe` only see (and only pay for)
+and its `subscribe`, `mutate`, and `get` only see (and only pay for)
 that container. A large document stays cheap because your editor
 touches the slice it cares about instead of walking the whole
 document.
 
+**Make an item the smallest thing two people edit independently.** Two
+people editing different items always keep both edits. Two editing the
+same item keep one of the two, not a blend, so a grid where people edit
+single cells is one item per cell rather than one per row. A small
+collection merges more finely than a large one, so a small test is not
+proof that your items are the right size.
+
 ```ts
 type Wall = { type: 'wall'; x: number; z: number };
 
@@ -444,7 +443,6 @@ walls.mutate((m) => { m[id] = { type: 'wall', x: 0, z: 0 }; }); // add
 walls.mutate((m) => { m[id].x = 42; });                          // field edit
 walls.mutate((m) => { delete m[id]; });                          // remove
 
-const all = walls.read();      // Record<string, Wall>
 const one = walls.get(id);     // Wall | undefined
 ```
 
@@ -461,15 +459,19 @@ doc.list<Col>('cols').mutate((l) => {
 });
 ```
 
+Reposition an entry with `l.move(from, to)`. Two people moving the same
+entry at once converge on one entry, where a removal paired with an
+insertion keeps both insertions and leaves the entry in the list twice.
+
 For a keyed collection that has to **stay in a stable order** (a list
 of notes, layers, or steps), use `doc.orderedMap<T>(mapKey, orderKey)`
 rather than a plain map with an app-computed sort key. It binds the map
 to a sibling order list and keeps them in lockstep: a new key appends in
 insertion order and a delete prunes from the order, both in the same
-commit as the map edit. There is no counter or index to derive a sort
-key from, which is what makes a hand-rolled key wrong here (a count is
-not stable across deletes, so a later entry can sort before an earlier
-one). Read it in order with `ordered()` or `keys()`.
+commit as the map edit. A hand-rolled key goes wrong here because
+nothing gives you a stable number to build one from: a count shifts as
+entries are deleted, so a later entry can sort before an earlier one.
+Read the collection in order with `ordered()` or `keys()`.
 
 ```ts
 const notes = doc.orderedMap<Note>('notes', 'note_order');
@@ -478,45 +480,65 @@ notes.mutate((m) => { m[id].text = 'hi'; });       // field edit; order untouche
 for (const { key, value } of notes.ordered()) renderRow(key, value);
 ```
 
+`insert(key, value, at)` puts a new key somewhere other than the end,
+and `move(key, to)` repositions one the collection already holds. Both
+write the record and its place in the order in one commit, the way a
+`mutate` add does.
+
+```ts
+notes.insert(newId, { text: '' }, { after: caretId });  // Enter, mid-document
+notes.move(dragged, { before: droppedOn });             // a drag landing
+notes.move(dragged, { index: 0 });                      // send to the top
+```
+
+Name a neighbouring key where you have one. A key still anchors where
+the reader meant after a peer adds or removes a row between your render
+and your write, where an index by then counts different rows.
+`{ index: n }` counts the positions `keys()` reports and leaves the key
+at `n`, or last when `n` is past the end. Two readers inserting at one
+spot both keep their record, and a reader who repositions a record
+another deletes leaves the delete standing.
+
 A field edit leaves the order alone, so its `subscribe` fire carries
-only `set` / `deleted`; a change that moves the order also carries
+only `set` / `deleted`. A change that moves the order also carries
 `change.order` (the live keys in order). Re-sequence your rows when
 `change.order` is present and patch in place otherwise, so a field echo
 never disturbs the row a user is editing.
 
-The doc-wide `doc.mutate(fn)` remains as a simpler fallback for tiny
-documents and one-liner integrations (a proxy over the default
-`entities` root). It operates on the same state as the handles, so an
-app can mix the two freely.
+`doc.mutate(fn)` is the simpler surface for tiny documents and
+one-liner integrations (a proxy over the default `entities` root). It
+operates on the same state as the handles, so an app can mix the two.
 
-Two mutation rules:
+Three mutation rules:
 
-- **A nested list read through a parent proxy is a detached
-  snapshot**, so `m[id].tags.push(x)` does not persist. Assign a whole
-  new array (`m[id].tags = [...m[id].tags, x]`), or take a handle for
-  the list itself (`parent.list(key)`). Nested **maps** walked through
-  the proxy are live; the snapshot rule applies to lists only.
+- **Edit a nested list by assigning a new array, or through its own
+  handle.** `m[id].tags = [...m[id].tags, x]` persists wherever the
+  record is stored, and `parent.list(key)` gives a list you edit often a
+  handle of its own. Nested **maps** walked through the proxy are live.
 - **Don't write `undefined`.** Mutations JSON-serialise, so
   `undefined` inside an array becomes `null` and `undefined` property
   values are dropped. Use `null`, length checks, or `'key' in obj`
   instead.
+- **Keys are yours except for the `brass:` prefix.** A map keeps its own
+  bookkeeping beside your records, under keys beginning with `brass:`,
+  so a write under one is refused. Any other key is free.
 
 A document starts **empty**, and the user's first action is their
 first undoable edit. Don't seed a baseline from the client: a faked
-"initial state" write is an ordinary edit, which means Ctrl-Z can
-delete it unexpectedly. Content the user asked for (their first add) is
-safe to persist; auto-written content they didn't ask for is not.
+"initial state" write is an ordinary edit, so Ctrl-Z deletes it and the
+user sees content vanish they never wrote. Persist what the user asked
+for, and nothing else.
 
 ### Subscribing
 
 `handle.subscribe(cb)` is one channel for every change, whatever
-produced it: your own edit, a remote peer's, an undo, a version
-checkout. It fires once on registration with the whole container as
-`change.set`, then on every change, and each fire costs O(changed)
-regardless of document size. Because your own edits arrive here too,
-you render from one place and never patch a second copy at the edit
-site, where a field updates but a header showing the same value does
-not.
+produced it: your own edit, a remote peer's, an undo, a move through
+version history. It fires once on registration with the whole container as
+`change.set`, then on every change, and each fire carries what that
+change wrote, so editing one record costs one entry whatever the
+document holds. Your own edits arrive here too, so render
+from this one place: an app that also paints at the edit site updates
+the field it touched and leaves a header showing the same value stale.
 
 ```ts
 const stop = walls.subscribe((change) => {
@@ -525,38 +547,94 @@ const stop = walls.subscribe((change) => {
 });
 ```
 
-**Reconcile, don't rebuild, and skip the focused input.** The input
-the user is typing in already shows what they typed, and a peer's
-conflicting value should resolve when they blur the field, not by
-yanking the caret mid-keystroke.
-
-In a declarative framework, your own edit echoes back through
-`subscribe` and re-renders the field mid-keystroke. Don't bind an editable input's value to a reactive
-expression derived from the document. Bind it to a **local edit
-buffer** (`v-model` on a per-field ref, `useState`), write the buffer
-through to the document on input, and copy the document's value back
-into the buffer only for fields that are not focused.
-
-**`subscribe` is deferred; `read` and `get` are not.** A fire lands on
-a microtask after the commit, so for the instant between your own
-`mutate` and its echo a value you cached from the previous fire is
-stale. Rendering never notices, because the echo repaints right after,
-but a **synchronous read-after-write** does: allocating the next id,
-checking a new name against the current set, or otherwise writing and
-then immediately reading the derived state. Read those from `read()` /
-`get()`, which always reflect the edit you just made, rather than from
-a projection you keep in sync only through `subscribe`. The failure
-mode is a mirror that you write through `mutate` and read back
-synchronously in the same turn: the read runs before the subscription
-that would have updated the mirror, so it sees the pre-write picture.
-
-A `list` handle has no per-key delta; its subscriber takes no
-arguments and re-reads (`list.subscribe(() => render(list.read()))`).
+**Treat the document as the single source of truth.** Write each edit as
+your user makes it, and draw what the document says. If you keep a local
+model to render from, fill it from `subscribe`.
+
+Assigning to `input.value` moves the caret, so skip a text input while it
+has focus and read the document when focus leaves.
+
+```ts
+input.addEventListener('input', () => {
+  cells.mutate((m) => { m[key] = input.value; });
+});
+input.addEventListener('blur', () => { input.value = cells.get(key) ?? ''; });
+
+const stop = cells.subscribe((change) => {
+  for (const [key, value] of change.set) {
+    if (key === editingKey) continue;   // the caret is in this one
+    paint(key, value);
+  }
+});
+```
+
+When two people edit one value, the document's merge picks the winner and
+every client gets that same answer.
+
+In a declarative framework, bind the input to a per-field ref (`v-model`,
+`useState`) rather than to the document, and have your subscriber assign
+that ref for every field except the focused one.
+
+**A subscriber runs inside the `mutate` that caused it**, so what it
+gave you is current the moment `mutate` returns. Answer a read straight
+after a write (allocating the next id, checking a new name against the
+ones in use) from what you already hold.
+
+A `list` handle's subscriber receives splices, each carrying the
+position an edit lands at, applied in the order they arrive:
+
+```ts
+const stop = steps.subscribe((change) => {
+  for (const { at, removed, inserted } of change.splices) {
+    rows.splice(at, removed, ...inserted.map(renderStep));
+  }
+});
+```
+
+**A reorder arrives as a removal and an insertion, so pair them if the
+item owns anything.** Rebuilding is correct and costs whatever the item
+holds: a DOM node loses its focus, its selection and its scroll
+position, and a view built on it starts over. As you apply a splice you
+know which of your own items it removed, so match them against what the
+same change inserts and move the one you already have.
+
+```ts
+const stop = steps.subscribe((change) => {
+  const lifted = new Map<string, Row>();
+  for (const { at, removed, inserted } of change.splices) {
+    for (const row of rows.splice(at, removed)) lifted.set(row.id, row);
+    rows.splice(at, 0, ...inserted.map((step) => lifted.get(step.id) ?? renderStep(step)));
+  }
+});
+```
+
 An `orderedMap` fire also carries `change.order` (the live ids in
 order) when the order moves. The optional second callback argument
-`origin` (`{ source: 'local' | 'remote' | 'undo' | 'redo' |
-'checkout' }`) exists for attribution, such as highlighting a peer's
-edit; a plain render ignores it.
+`origin` (`{ source: 'local' | 'remote' | 'undo' | 'redo' }`) carries
+attribution, for a render that highlights a peer's edit. A move through
+version history swaps the whole container rather than writing into it, so
+it arrives with no `origin`; `doc.subscribe` reports that move, with the
+version it landed on.
+
+### Knowing when you have the whole container
+
+`handle.onSettled(cb)` fires when the container has been delivered
+whole. Use it for work that belongs to the collection rather than to
+any one change: framing a camera on what arrived, running a first pass
+over it.
+
+```ts
+walls.onSettled(() => fitViewTo(walls));
+```
+
+It fires on registration, and again each time a version checkout, a
+return to head or a hydrate replaces the container, so a reader who
+moves through history gets the camera framed on the version they landed
+on. Set a flag of your own on the first fire for work that should run
+once.
+
+It reports what this peer had converged to when the delivery began.
+Later changes arrive through `subscribe`.
 
 `doc.subscribe(cb)` is the catch-all for events not tied to one
 container (saving-count ticks, branch-list changes). Use it for status
@@ -575,10 +653,8 @@ edits stay untouched. Outside the session, call `doc.undo()` /
 
 A **checkpoint** (`doc.createCheckpoint()`) is both the Ctrl-Z
 boundary and a marker on the document's version-history timeline, so
-checkpoint timing sets both granularities. Auto-seals fire 60 seconds after
-each burst of local edits settles, which means an app that does
-nothing still gets usable undo boundaries and a usable history pane.
-Tune it to your app's shape:
+checkpoint timing sets both granularities. Auto-seals fire 60 seconds
+after each burst of local edits settles. Tune that to your app's shape:
 
 | Your app shape                          | What to do                                       | Result                                     |
 | --------------------------------------- | ------------------------------------------------ | ------------------------------------------ |
@@ -594,9 +670,16 @@ The SDK renders version preview itself: while an earlier version is
 showing, `mountToolbar` / `mountHeader` show the "viewing an earlier
 version" banner and return-to-live control (mount `mountVersionPreview`
 for a fully custom shell). You handle your own edit controls:
-`doc.readOnly` flips `true` during a preview (and for a view-only share
-link, and while a document is still loading), so gate your custom tools
-on it, and `doc.mutate` throws while read-only.
+`doc.readOnly` flips `true` during a preview, for a reader whose access
+to the document is view-only, for a view-only share link, and while a
+document is loading or could not be loaded. Gate your custom tools on
+it, and `doc.mutate` throws while read-only.
+
+Read it inside your `doc.subscribe` handler rather than once when you
+bind the editor. It also flips when someone withdraws the reader's
+access while they have the document open, so re-reading is what
+disables your tools at the moment writing stops working. `Brass.onError`
+carries the message explaining what happened.
 
 ### Reacting to deletes
 
@@ -622,21 +705,19 @@ thumbnail on its dashboard card:
 Brass.session.useCanvas(() => document.querySelector('canvas'));
 ```
 
-The SDK debounces about a second after each local edit, screenshots
+The SDK debounces 1.5s after each local edit, screenshots
 the canvas, downscales, and uploads. **WebGL canvases must set
 `preserveDrawingBuffer: true`** (Three.js:
-`new THREE.WebGLRenderer({ preserveDrawingBuffer: true })`); without
-it the read-back is a blank PNG, and the SDK warns once if the flag is
-missing. Non-canvas apps skip this entirely; a document without a
-thumbnail shows a blank tile and still gets its version-history
-timeline.
+`new THREE.WebGLRenderer({ preserveDrawingBuffer: true })`). Without
+it the read-back is a blank PNG, and the SDK warns once about the
+missing flag.
 
 ## Presence (live cursors and who's here)
 
 `doc.presence` shows who else is in the document and what they are
 doing: a roster of the other live participants plus a small per-user
 `state` (cursor, camera, selection). It is non-null on any open
-writable document, and it is fully ephemeral; nothing survives a
+writable document, and it is fully ephemeral: nothing survives a
 disconnect. `Brass.session.presence` is the same client for the
 session's open document, so use whichever handle you have.
 
@@ -655,11 +736,14 @@ canvas.addEventListener('pointermove', (e) => {
 
 `cursor` is a 3D point in document world space (meters, right-handed,
 Z-up; a 2D app passes `z: 0`), and an entity or text editor publishes
-`selection` instead. `Brass.mountToolbar` and
-`Brass.mountPresenceRoster` render the header roster for you. To
-render remote cursors, diff the roster by `connectionId` on the
-`change` event; the full recipe, coordinate conventions, and types are
-in [`docs/presence.md`](./docs/presence.md).
+`selection` instead. A `selection` grows with what the user picked, so
+publish a bounded summary (the first few ids plus a count, or the
+selection's bounding box) once a selection can get large, and subscribe
+with `presence.onStatus` to catch a layer Brass withholds as oversized.
+`Brass.mountToolbar` and `Brass.mountPresenceRoster` render the header
+roster for you. To render remote cursors, diff the roster by
+`connectionId` on the `change` event. The full recipe, coordinate
+conventions, and types are in [`docs/presence.md`](./docs/presence.md).
 
 ## Streams (partitioning large documents)
 
@@ -676,23 +760,28 @@ records.mutate((m) => {
 });
 ```
 
-`Brass.openDocumentById(docId, { stream })` opens the document with that
-stream as its own state, so an app that works in one part of a large
-document downloads only that part; it defaults to `'default'`, the stream
-every document has. `doc.getOrCreateStream(name)` opens the document's
-stream of that name and makes it when the document does not hold it yet
-(idempotent, and concurrent callers converge on one stream, so an app
-reaches for the stream it expects on every open); `doc.stream(name)`
-opens one the document already holds and rejects any other name, and
-resolves the name the document was opened at back to the document itself;
-`doc.listStreams()` lists them. Code that iterates stream names
-therefore handles partitioned and unpartitioned documents with one path.
+Which call you reach for depends on what you already know about the
+document:
+
+- `Brass.openDocumentById(docId, { stream })` opens the document with
+  that stream as its own state, so an app that works in one part of a
+  large document downloads only that part. It defaults to `'default'`,
+  the stream every document has.
+- `doc.getOrCreateStream(name)` opens the document's stream of that name
+  and makes it when the document does not hold it yet. It is idempotent,
+  and concurrent callers converge on one stream, so your app reaches for
+  the stream it expects on every open.
+- `doc.stream(name)` opens one the document already holds and rejects
+  any other name. Ask it for the stream you opened the document at and
+  you get the document back, so one loop over `doc.listStreams()` reads
+  a partitioned and an unpartitioned document alike.
+
 A stream costs one extra round trip, so add one when it carries real
 content: partition by load unit (a discipline, a heavy layer), not by
 concept.
 
-A schema names the streams it expects under `streams`. An app that
-follows references between records reads every stream the document holds
+A schema names the streams it expects under `streams`. If your app
+follows references between records, read every stream the document holds
 (`doc.listStreams()`). A document can hold streams your schema does not
 name, and your app leaves those alone. Naming a stream is how records
 you work with (clash findings, review notes, a cache) ride in the
@@ -703,15 +792,14 @@ out of the exported file. See [`docs/streams.md`](./docs/streams.md) and
 
 ## Imported files
 
-Start from what your app will open: the file the app exists for,
-whether it is your own or an example from a user. Add it to an
-organization (the dashboard, or any app's hosted picker, brings a file
-in) and read what the document it becomes holds; that document decides
-the schema your app declares. Your app opens it the way every document
-opens: through the session and the hosted picker.
+Importers convert standard file types into Brass documents. Your app
+opens one through the session and the hosted picker like any other
+document. The schema its records follow is what lets a second app open
+the same file.
 
-A document imported from a file (an upload or a drive link) lands in
-one of two shapes, and the document's own page tells you which:
+What you build depends on whether an importer for the format already
+exists. Open a document of that type in the dashboard to see which case
+you are in:
 
 - **It holds records under a schema.** An importer for the format
   already exists (an installed app provides it). Adopt the document's
@@ -724,10 +812,11 @@ one of two shapes, and the document's own page tells you which:
   follows references between records, read every stream the document
   holds, see
   [streams](./docs/streams.md#reading-a-document-spread-across-streams).
-- **It is the stored file, and no schema resolves.** Nothing imports
-  the format yet, so your app is its first importer. Register both
-  halves of the format at boot: the importer parses the stored file
-  into records, the serializer reconstitutes the file from them.
+- **It holds the stored file under no schema.** Nothing imports the
+  format yet, so your app is its first importer, and your importer is
+  what makes files of that format openable. Register both halves at
+  boot: the importer parses the stored file into records, the serializer
+  reconstitutes the file from them.
 
   ```ts
   Brass.registerImporter(async (src, doc) => {
@@ -746,43 +835,39 @@ one of two shapes, and the document's own page tells you which:
   `brass-app.json`; importing publishes that schema and stamps it on
   the document, so the next app can adopt it like any imported
   document's. Declare the file match there too
-  (`"accepts": [{ "extension": "gpx" }]`) so Brass offers your app when
-  someone uploads one.
+  (`"imports": [{ "extension": "gpx" }]`) so Brass runs your importer on
+  files of that type.
 
 To make your app open documents of an existing file type, adopt that
 type's schema rather than re-derive its record shape. Get a document of
-the shape you target (upload a sample file to your organization, or
-open a document another app produced), copy
-its schema from the document's page in the dashboard (**Download
-brass-app.json**, or `npx @brass-build/cli schema pull --doc <docId>`),
-and keep it verbatim as `schema` in your `brass-app.json`. The schema's family folds
-into your `opens`, so documents of that shape route to your app, and
-building against the copied body keeps you compatible with the other
-apps that edit them. The declared schema is what routes existing
-documents to your app: the picker lists documents by matching your
-declared schema (or `accepts`), so ship the manifest with your first
-deploy.
+the shape you target: upload a sample file to your organization, or open
+one that another app produced. Copy its schema from the document's page
+in the dashboard (**Download brass-app.json**, or
+`npx @brass-build/cli schema pull --doc <docId>`), keep it verbatim as
+`schema` in your `brass-app.json`, and ship that manifest with your
+first deploy. The picker lists documents by matching your declared
+schema, and its family folds into your `opens`, so documents of that
+shape route to your app and your code stays compatible with the other
+apps that edit them.
 
 Every app ships a capability manifest at `/.well-known/brass-app.json`
 in its bundle root, next to `index.html`. It declares the schema your
-app works with, the files it accepts, the format it exports, and the
+app works with, the files it imports, the format it exports, and the
 icon the platform renders as your app's mark. The platform re-reads it
-after each deploy, so publishing your bundle is what registers it, and
-an app that does not serve one registers nothing.
+after each deploy, so publishing your bundle is what registers it.
 [`docs/app-manifest.md`](./docs/app-manifest.md) covers where the file
 goes, what each key does, and how to confirm your build carries it.
 
-The record-store shape, the conversion recipe, and schemas are covered
-in [`docs/imported-documents.md`](./docs/imported-documents.md) and
-[`docs/schemas.md`](./docs/schemas.md).
+[`docs/imported-documents.md`](./docs/imported-documents.md) covers the
+record store an imported file becomes, and
+[`docs/schemas.md`](./docs/schemas.md) covers declaring its schema.
 
 ## Reference
 
-`Brass` is the top-level namespace your app calls; its members are
-below. The package's TypeScript types document `Document` and the
-container handles (your editor's autocomplete lists every member and
-signature), and the examples above show them in use, so this reference
-does not repeat them.
+`Brass` is the top-level namespace your app calls. The package's
+TypeScript types document `Document` and the container handles, so your
+editor's autocomplete lists every member and signature, and the examples
+above show them in use.
 
 ### `Brass`
 
@@ -805,7 +890,7 @@ does not repeat them.
 | `Brass.shareDocument(docId)`                                 | `Promise<void>`                         |
 | `Brass.registerImporter(fn)`                                 | `void` (see `docs/imported-documents.md`) |
 | `Brass.registerSerializer(fn)`                               | `void` (see `docs/imported-documents.md`) |
-| `Brass.documents`                                            | namespace getter (metadata read, thumbnails, branches for a known doc id) |
+| `Brass.documents`                                            | namespace getter (metadata read and thumbnails for a known doc id) |
 
 The composable header mounts (`mountHeader`, `mountFileMenu`,
 `mountDocumentTitle`, `mountUndoRedo`, `mountPresenceRoster`,
@@ -813,8 +898,8 @@ The composable header mounts (`mountHeader`, `mountFileMenu`,
 [`docs/custom-chrome.md`](./docs/custom-chrome.md).
 
 `OpenedDocument = Document & { readonly id: string }`. Open / create
-methods return `OpenedDocument`; type app-level variables as
-`OpenedDocument` so `doc.id` stays non-null. `BrassUser` is
+methods return `OpenedDocument`, so type app-level variables as
+`OpenedDocument` and `doc.id` stays non-null. `BrassUser` is
 `{ sub: string; email?: string; display_name?: string; avatar_url?: string }`.
 
 ### Errors
@@ -823,7 +908,7 @@ Every call rejects with one error type, `BrassError`. HTTP calls carry
 `.status: number`, and the hosted-UI launchers (`selectDocument`,
 `shareDocument`, ...) carry `.code` (`'embed_error'`,
 `'not_in_browser'`). A call made without a signed-in session rejects
-synchronously with `.status === 401`.
+with `.status === 401` before it reaches the network.
 
 ## Guides
 
@@ -831,6 +916,7 @@ synchronously with `.status === 401`.
 - [`docs/app-manifest.md`](./docs/app-manifest.md): the `brass-app.json` capability manifest every app ships, where it goes in your bundle, and what each key declares.
 - [`docs/imported-documents.md`](./docs/imported-documents.md): the record store an imported file becomes, `Brass.registerImporter`, `doc.sourceBlob()`, and `Brass.registerSerializer`.
 - [`docs/schemas.md`](./docs/schemas.md): declaring a schema, creating a stream, what lets an app open a document, and what breaks that.
+- [`docs/streams.md`](./docs/streams.md): partitioning a document for lazy loading, per-stream undo, and reading a document spread across streams.
 - [`docs/custom-chrome.md`](./docs/custom-chrome.md): composable header pieces, and rendering `session.commands` yourself for a fully custom shell.
 - [`docs/presence.md`](./docs/presence.md): remote cursors, roster rendering, coordinate conventions, full types.
 - [`docs/hosted-ui-advanced.md`](./docs/hosted-ui-advanced.md): the hosted launchers (`Brass.selectDocument`, `Brass.shareDocument`), their redirect behavior in browsers that block the iframe, theming, CSP.