@brass-build/client 0.1.0

package/dist/ws-frame-limit.js

@@ -0,0 +1,40 @@
+// The ceilings an op can hit, measured before it is sent.
+//
+// Duplicated from the server's `frameExceedsWsLimit` / `op-blob.ts`
+// rather than imported: this package ships unbundled and can only import
+// its own relative files. The server owns the contract; these follow it.
+// The transport does not deliver a message above this. It closes the
+// connection instead, taking down everything else multiplexed onto the
+// socket, so an oversized frame must never be sent.
+const WS_FRAME_MAX_BYTES = 128 * 1024;
+// What one stored record holds inline. Past it the blob is uploaded
+// straight to storage rather than carried in a request body, so this is
+// where the write path changes shape, not where it stops.
+const OP_ROW_MAX_BLOB_CHARS = 350 * 1024;
+// The largest op the platform accepts. A single value past this cannot
+// be split (a record is the merge unit, so one assignment is the
+// smallest thing a commit carries), which is why the refusal points at
+// storing the bulk as a file instead.
+const MAX_OP_BLOB_CHARS = 8 * 1024 * 1024;
+/**
+ * True when the serialized frame would exceed what the socket carries.
+ *
+ * The envelope is measured with the blob emptied, so a multi-megabyte
+ * value is never serialized just to be counted. Every byte is ASCII
+ * (base64 blob, topic, id), so length is byte length.
+ */
+export function opFrameExceedsWsLimit(frame) {
+    const envelopeChars = JSON.stringify({ ...frame, op_blob: '' }).length;
+    return envelopeChars + frame.op_blob.length > WS_FRAME_MAX_BYTES;
+}
+/** True when the blob is too large to ride in a request body, so it is
+ *  uploaded to storage first and the write names the staged object. */
+export function opBlobNeedsStaging(opBlobB64) {
+    return opBlobB64.length > OP_ROW_MAX_BLOB_CHARS;
+}
+/** True when no single op can hold the blob, so the server could only
+ *  refuse it. Checked locally to save an upload that ends in a 400. */
+export function opBlobExceedsDurableLimit(opBlobB64) {
+    return opBlobB64.length > MAX_OP_BLOB_CHARS;
+}
+//# sourceMappingURL=ws-frame-limit.js.map

package/dist/ws-frame-limit.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ws-frame-limit.js","sourceRoot":"","sources":["../src/ws-frame-limit.ts"],"names":[],"mappings":"AAAA,0DAA0D;AAC1D,EAAE;AACF,oEAAoE;AACpE,yEAAyE;AACzE,yEAAyE;AAEzE,qEAAqE;AACrE,uEAAuE;AACvE,oDAAoD;AACpD,MAAM,kBAAkB,GAAG,GAAG,GAAG,IAAI,CAAC;AAEtC,oEAAoE;AACpE,wEAAwE;AACxE,0DAA0D;AAC1D,MAAM,qBAAqB,GAAG,GAAG,GAAG,IAAI,CAAC;AAEzC,uEAAuE;AACvE,iEAAiE;AACjE,uEAAuE;AACvE,sCAAsC;AACtC,MAAM,iBAAiB,GAAG,CAAC,GAAG,IAAI,GAAG,IAAI,CAAC;AAS1C;;;;;;GAMG;AACH,MAAM,UAAU,qBAAqB,CAAC,KAAc;IAClD,MAAM,aAAa,GAAG,IAAI,CAAC,SAAS,CAAC,EAAE,GAAG,KAAK,EAAE,OAAO,EAAE,EAAE,EAAE,CAAC,CAAC,MAAM,CAAC;IACvE,OAAO,aAAa,GAAG,KAAK,CAAC,OAAO,CAAC,MAAM,GAAG,kBAAkB,CAAC;AACnE,CAAC;AAED;uEACuE;AACvE,MAAM,UAAU,kBAAkB,CAAC,SAAiB;IAClD,OAAO,SAAS,CAAC,MAAM,GAAG,qBAAqB,CAAC;AAClD,CAAC;AAED;uEACuE;AACvE,MAAM,UAAU,yBAAyB,CAAC,SAAiB;IACzD,OAAO,SAAS,CAAC,MAAM,GAAG,iBAAiB,CAAC;AAC9C,CAAC"}

package/docs/app-manifest.md

@@ -0,0 +1,65 @@
+# The capability manifest (`brass-app.json`)
+
+Every app ships a `brass-app.json`, and the platform reads it to decide
+where your app shows up. Brass adds an "Open in" link to a document
+card, offers your app when someone uploads a file it handles, and shows
+a download button on the documents your app writes out.
+
+## Where it goes
+
+The manifest is a file called `brass-app.json`. It must be placed in a
+directory called `/.well-known/` at your bundle root, next to
+`index.html`. Some bundlers skip dot-directories when they copy static
+assets, so confirm that the manifest is actually in your `dist/`
+directory after you build.
+
+The platform re-reads the manifest after each deploy, so publishing
+your bundle is what registers it. If Brass hosts your bundle
+(`brass publish`), it reads the manifest from the bytes it stores, so
+your capabilities register even when your load gate is on. If you serve
+the bundle from your own origin, the platform fetches
+`<origin>/.well-known/brass-app.json` as an anonymous client, so serve
+that path publicly even when the rest of your app requires sign-in.
+
+These tokens only drive discovery and grant no access, so you declare
+them yourself.
+
+## What goes in it
+
+```json
+{
+  "opens": ["tracker"],
+  "accepts": [{ "extension": "csv" }, { "content_type": "text/csv" }],
+  "creates": "tracker",
+  "exports": { "content_type": "text/csv", "file_extension": ".csv" },
+  "icon": "/icon.svg",
+  "schema": { "...": "see schemas.md" }
+}
+```
+
+Every field is optional, so ship only the ones your app uses.
+
+- **`opens`** lists the `schema_type`s of documents your app reads.
+  Declaring a `schema` already folds its family in, so most apps list
+  nothing extra here.
+- **`accepts`** matches an uploaded file by extension or content type,
+  so Brass offers your app to whoever uploads one. Your app then reads
+  the file's bytes through `sourceBlob()`.
+- **`creates`** is the `schema_type` Brass stamps on the documents your
+  app makes, so peer apps that declare `opens` for the token can open
+  them. It folds into your own `opens` as well.
+- **`exports`** names the file format your app writes a document out
+  to, and your `Brass.registerSerializer` callback produces the bytes.
+  Declaring it makes those documents downloadable. Declare it when your
+  app interoperates with a format outside Brass.
+  [`imported-documents.md`](./imported-documents.md) covers how an
+  importing app chooses that format.
+- **`icon`** points at your app's mark, which the platform renders on
+  your app's tiles and on the hosted consent screen when someone grants
+  your app access. Draw a small SVG and serve it from your own bundle
+  (`"icon": "/icon.svg"`, resolved against your origin), or give an
+  absolute `https://` URL. An emoji (`"icon": "🏗️"`) also renders,
+  though apps in one domain tend to land on the same few.
+- **`schema`** declares the record shape your app works with, whether
+  you invented it or adopted an existing one. See
+  [`schemas.md`](./schemas.md).

package/docs/custom-chrome.md

@@ -0,0 +1,147 @@
+# Custom chrome
+
+`Brass.mountToolbar` renders the whole document bar and is the
+recommended path for an app that is one working surface under a bar.
+This page covers the two custom shapes, from least to most custom: a
+multi-pane app that builds its own header out of the **standard
+pieces**, and a fully custom shell that renders `session.commands`
+into its own DOM.
+
+## Composable header pieces (multi-pane apps)
+
+A multi-pane app (a tree beside an inspector, a list beside a preview)
+builds its own header for its own layout, but should not re-implement
+the account menu, presence roster, title, undo / redo, or the header's
+responsive layout by hand. Take the header shell with
+`Brass.mountHeader`, then drop the standard pieces into its three
+slots:
+
+```ts
+// Each piece mount owns (replaces the children of) the element you
+// give it, so hand each its own child within a cluster.
+const slot = (parent: HTMLElement) => {
+  const el = document.createElement('div');
+  parent.append(el);
+  return el;
+};
+
+const header = Brass.mountHeader(document.getElementById('app-header')!);
+Brass.mountFileMenu(slot(header.start));     // left: file menu + title
+Brass.mountDocumentTitle(slot(header.start));
+Brass.mountUndoRedo(header.tools);           // middle: wraps on mobile
+Brass.mountDriveSync(slot(header.end));      // right: pinned top-right
+Brass.mountPresenceRoster(slot(header.end));
+Brass.mountAccountMenu(slot(header.end));    // the account avatar
+```
+
+`mountHeader` gives you the same responsive bar layout `mountToolbar`
+uses, from one definition: `start` ellipsizes its title rather than
+wrapping, `tools` drops to its own row on a narrow screen, and `end`
+stays pinned top-right, so the account avatar never wraps below the
+tools on mobile (the detail a hand-rolled flex header gets wrong).
+Each piece renders one cluster wired to `Brass.session` and returns
+`{ destroy(): void }`; `header.destroy()` removes the shell.
+
+- `Brass.mountFileMenu` renders the hamburger file menu (the
+  `session.commands` menu surface).
+- `Brass.mountDocumentTitle` renders the document title plus a
+  location chip; both open the hosted location editor (rename / move /
+  file). On a non-default branch the title carries a branch chip.
+- `Brass.mountUndoRedo` renders undo / redo as prominent buttons.
+- `Brass.mountPresenceRoster` renders the who's-here roster of
+  coloured initials. It is the receiver half only: still publish your
+  own presence state (see the README's "Presence").
+- `Brass.mountDriveSync` renders the drive-sync badge. It renders
+  nothing on a non-drive doc, so it is safe to mount in any header.
+- `Brass.mountAccountMenu` renders the account avatar menu (email, an
+  Open dashboard link, and sign out).
+
+`mountHeader` already includes the historical-version preview banner
+(the return-to-live strip shown while a document is previewing an
+earlier version) above the bar, so a multi-pane app on the header shell
+gets correct preview UX with no extra mount. Only a fully custom shell
+(next section, no `mountHeader`) mounts it itself, with
+`Brass.mountVersionPreview(el)`; like the drive badge it renders
+nothing until there is something to show.
+
+Mount the chrome once, when the user signs in, not per document: the
+file menu has to exist in the "signed in, nothing open" state or a
+fresh user has no New / Open (the same rule as `mountToolbar`).
+
+## Fully custom shells: the command list as data
+
+The widgets are one renderer of this same command list, so nothing
+below is a different surface, just a lower-level entry point into it.
+
+`session.commands` is the SDK's built-in actions as data: the SDK owns
+each command's behavior and live state. Each carries a `surface` hint
+(`'menu'` for a file menu, `'toolbar'` for a prominent button) to
+filter on when placing it. It's a hint, not a constraint. The
+`Command` type is exported, so type your render code against it rather
+than re-declaring a local interface:
+
+```ts
+import type { Command } from '@brass-build/client';
+```
+
+The full built-in set when a doc is bound, in list order:
+
+| `id`       | `group`    | `surface` | `label`            | Enabled when                            |
+| ---------- | ---------- | --------- | ------------------ | --------------------------------------- |
+| `new`      | `session`  | `menu`    | New                | Signed in.                              |
+| `open`     | `session`  | `menu`    | Open...            | Signed in.                              |
+| `history`  | `document` | `menu`    | Version history... | A document is open.                     |
+| `branches` | `document` | `menu`    | Branches...        | A document is open. Has `children`.     |
+| `share`    | `document` | `menu`    | Share... / Share / Download... | A document is open.         |
+| `manage`   | `document` | `menu`    | Manage...          | A document is open.                     |
+| `undo`     | `edit`     | `toolbar` | Undo               | The document is editable and there is something to undo. |
+| `redo`     | `edit`     | `toolbar` | Redo               | The document is editable and there is something to redo. |
+
+The order runs use, then manage, then destructive: `new` / `open` put a
+different document on screen, `history` / `branches` put a different
+state of this one there, `share` hands the document to a person or to a
+file, and `manage` (the entry holding the delete) comes last. Render the
+list in the order you receive it.
+
+Each command carries `enabled` (read on every notification),
+`running` (true while `run()` is in flight, drives the pending
+affordance), and `run()` (always resolves; failures route to
+`Brass.onError`, never throw).
+
+Read `label` on every notification too. `share` relabels once the SDK
+knows whether the document has a file to hand over, since downloading is
+one row of the share dialog rather than a command of its own.
+
+Draw a rule where `group` changes: `'session'` (a different document),
+`'document'` (this document), `'edit'` (undo / redo). The widgets do
+this, so a custom menu matches them by following the same rule.
+
+A command may carry `children` (a submenu) and `selected` (the
+active choice). Render a command with `children` as a submenu parent
+with a disclosure chevron; render each child as a nested item,
+showing a checkmark or bold style when `child.selected` is true.
+
+Reading the list rather than hard-coding the commands you know about
+means you don't miss one as the SDK adds built-ins. Filter by `surface`
+to place each, and invoke one by id with `session.run('undo')` (the
+hook for keyboard shortcuts).
+
+## What each command does by default
+
+Reading the list and calling `run()` wires all of it; you render and
+invoke, the SDK owns the behavior:
+
+- **`history`** drives version preview end to end. During a preview
+  `doc.readOnly` is `true`, so gate your own edit controls on it;
+  returning to live is the chrome's job (the `mountVersionPreview`
+  banner), not yours.
+- **`branches`** carries `children` (the branches, the active one
+  `selected: true`) plus a fork-new child. Render it as a submenu and
+  invoke a child's `run()`; a flat-list shell can call the parent's
+  `run()` to open the hosted picker instead.
+- **`share`** opens the hosted share dialog: who can open the document,
+  and, where there is a file to hand over, the download.
+- **`manage`** opens the same dialog on the document itself: its name,
+  where it sits, Duplicate, and Delete.
+- **`undo` / `redo`** call `doc.undo()` / `doc.redo()` (see "Undo,
+  checkpoints, and version history" in the README).

package/docs/hosted-ui-advanced.md

@@ -0,0 +1,77 @@
+# Hosted UI: advanced
+
+Some surfaces are owned by Brass: you call one method and Brass renders
+the UI in a modal iframe over your page, so your app never builds the
+screen, fetches the data, or handles the mutation. `Brass.session`
+wires the common ones (`history`, `share`, `manage`) behind the file
+menu; this page covers the rest and how they behave in browsers that
+block the iframe.
+
+## Surfaces
+
+| Method | Returns |
+| --- | --- |
+| `Brass.selectDocument()` | `Promise<SelectDocumentResult \| null>`: opens the hosted document picker; resolves to the picked document, or `null` if the user dismisses it. |
+| `Brass.shareDocument(docId)` | `Promise<void>`: opens the hosted share dialog for the document. |
+
+Version history is a built-in file-menu command (`history` in
+`session.commands` and the SDK toolbar's file menu), not a launcher
+method; an app on `mountToolbar` or `mountFileMenu` gets it with no
+code.
+
+## Redirects in browsers that block the iframe
+
+Where the browser blocks the Hosted UI iframe (Safari, Firefox, Chrome
+with third-party cookies off), these surfaces open as a full-page
+redirect to Brass and return to your app when the user is done. The
+picker returns with the chosen document opened into `Brass.session`.
+
+So render the active document from the session (or `mountToolbar`): on
+the redirect path the page reloads, so the code after `await
+Brass.selectDocument()` never runs, and the pick arrives through the
+session instead. The resolved value is the modal path's inline
+convenience, correct whenever you receive it.
+
+## `BrassError` `.code` values
+
+The hosted-UI launchers reject with `BrassError` carrying a `.code`
+(rather than the `.status` the HTTP namespaces set):
+
+- `'embed_error'`: the hosted page loaded but couldn't proceed (e.g.
+  the user isn't signed in to Brass in this context).
+- `'not_in_browser'`: called outside a browser environment.
+
+## Theming
+
+Hosted UI surfaces render in Brass's own visual language; light/dark is
+the one axis you control, defaulting to `'light'`. Override in two
+cases:
+
+- **Dark-only app**: `hostedUiTheme: 'dark'`.
+- **App that follows the user's OS preference**: `hostedUiTheme: 'auto'`,
+  and only if your own CSS also responds to
+  `@media (prefers-color-scheme: dark)`. Otherwise a dark-OS user gets a
+  dark embed inside your light app with the close button invisible over
+  it.
+
+```ts
+await Brass.init('brass_app_live_...', {
+  hostedUiTheme: 'auto',
+});
+```
+
+## CSP
+
+If your app sends a `Content-Security-Policy`, it needs `frame-src
+https://app.brass.build` (the README's "Setup" lists the full set). A
+bare `default-src 'self'` blocks the iframe, because `frame-src` falls
+back to `default-src`, and the failure is silent. Apps that send no CSP,
+or no `frame-src` / `default-src`, need no change.
+
+## Mixing with `Brass.session`
+
+The session's file-menu commands invoke these surfaces for you:
+`open` opens the picker, `share` and `manage` open the
+document-settings dialog, and `history` opens version history. Each
+command's `run()` always resolves; a failure routes to `Brass.onError`
+rather than throwing.

package/docs/imported-documents.md

@@ -0,0 +1,261 @@
+# Imported files and formats
+
+Your app reads and edits an imported document through the ordinary
+handle surface, and Brass does the importing. A user uploads a file or
+opens a drive item, and the platform turns it into a document, so there
+is no client import call to make. How much of the file mapping you write
+yourself depends on whether the format already has an importer:
+
+- **A format with an importer**: the parsed records ARE the document
+  (an installed app provides the importer). You read and edit the
+  records through the ordinary handle surface, and Brass re-emits the
+  original on export and drive-push through an installed app that
+  serialises the format. Your app is an **editor**: declare the
+  document's schema in `brass-app.json`, the contract peers evaluate
+  compatibility against. The schema is also the record contract: its
+  `description`s declare how each field is encoded, so an analysis app
+  derives what it computes (a tree, geometry, quantities) from the
+  records the schema describes. A large document spreads those records
+  across the streams the schema names, so read them all (see [Reading a
+  document spread across
+  streams](./streams.md#reading-a-document-spread-across-streams)).
+- **Any other file**: the document is an opaque file (source
+  `schema_type` is `brass:file`). Your app is the importer/exporter:
+  it registers its parser with `Brass.registerImporter` (Brass runs it
+  on the stored bytes and stamps your schema on the document) and the
+  inverse with `Brass.registerSerializer`.
+
+Documents your app creates itself have no source file. If your app
+only makes its own documents, it reads and edits records and declares a
+schema so peers can open them.
+
+## The record store
+
+The record store is the same for every format. It lives at the
+document root as two containers: `instances` (a map keyed by record id
+`'#23'` whose values are `{ type, params }` records) and
+`instance_order` (the same keys in file order, which the serializer
+walks to re-emit the file). Every record in `instances` must have its
+key in `instance_order`, or the serializer drops it.
+
+**Reach for both as one handle:
+`doc.orderedMap('instances', 'instance_order')`.** The ordered map
+keeps the order list in step for you: an add appends the key, a delete
+prunes it, both in one commit (one undo step). You never write
+`instance_order` by hand.
+
+```ts
+const records = doc.orderedMap('instances', 'instance_order');
+
+records.read();              // { '#1': { type, params }, ... }
+records.get('#1');           // one record, or undefined
+records.ordered();           // [{ key, value }, ...] in file order
+records.keys();              // ['#1', '#2', ...] in file order
+
+records.mutate((m) => {
+  m[newKey] = { type, params };                // add: appended to order
+  delete m['#7'];                              // delete: pruned from order
+  m['#3'].params = [...];                      // field edit: order untouched
+});
+```
+
+`type` is the format's record tag, and `params` is the record body, whose
+shape is format-specific. Values read back are detached copies.
+
+**Edit a record by reassigning its whole `params`.** The record is the
+unit of change: the value you read back is a detached copy, so
+mutating it element-wise does not persist. Build the new `params` and
+assign it. Because edits live in the canonical store, the original
+format re-emits faithfully on export.
+
+**A newly added record lands at the end of source order.** When the
+order is structural (a record must sit inside a section or a parent's
+child range to re-emit validly), don't lean on physical record order:
+have your serializer reconstruct the structure from the records' own
+declared section / parent on the way out.
+
+## Cost by change: subscribe, don't re-read
+
+An imported model is commonly hundreds of thousands of records, so a
+per-change `read()` to rebuild your view is O(file) per keystroke. The
+subscription hands you a `change` on every fire: the first fire
+carries the whole store as `change.set` (build your view there), and
+every later fire names only the changed records (one path for your own
+edits, remote edits, and post-open hydration alike). Don't memoise the
+derivation on a record-count fingerprint: an in-place edit keeps the
+count, so the memo reads back stale. And keep view-only changes (pan,
+zoom, selection) off the content paint.
+
+## How a format maps to records
+
+Map every format to records by the same recipe, which is what lets
+independently-built apps predict and share a format's records:
+
+1. **One record per element the format enumerates as its own
+   addressable item** (a STEP instance, an entity, a named element).
+   Inline only anonymous leaf scalars that have no identity of their
+   own. The record is the concurrent-edit unit: its whole `params`
+   merges last-writer-wins, so keep `params` a small plain value and
+   never pack several independently-edited values into one record.
+2. **`type` is the format's own class tag, verbatim**: no renaming, no
+   prefix.
+3. **The key is the format's own stable id, verbatim.** When the
+   format has no native id, synthesize one deterministically from the
+   record's own content, never from its position in the file (a
+   positional index is not stable across a re-import) and never at
+   random.
+4. **`params` is the object's own fields as a plain value**,
+   reassigned whole to edit it.
+5. **A relationship is its own record only when the format makes it an
+   object**, and otherwise it stays a reference field, on the **child**
+   pointing up to its parent. A mutable child-list on the parent is a
+   concurrently-edited array, so two people adding different children
+   collide.
+6. **Decompose only what has a model.** Named objects shred into
+   records; binary bulk is referenced by hash, not inlined; a file
+   with no object model stays an opaque `brass:file` blob.
+
+To build against a format someone else imported, read its schema: it
+declares exactly how the importer encoded each field into `params`
+(value shapes, the reference convention) in its `description`s. Get it
+from the document's dashboard page (**Download brass-app.json**), and
+declare that copy in `brass-app.json` to route those documents to your
+app. See [`schemas.md`](./schemas.md).
+
+## Registering your format's importer (`Brass.registerImporter`)
+
+For a file kept as-is, register your parse half once at boot, and Brass
+runs it when an import is needed:
+
+```ts
+Brass.registerImporter(async (src, doc) => {
+  // src: { url, filename, content_type, byte_size, expires_in, streams }
+  const bytes = new Uint8Array(await (await fetch(src.url)).arrayBuffer());
+  const parsed = parseMyFormat(bytes); // your own parser
+  const records = doc.orderedMap('instances', 'instance_order');
+  records.mutate((m) => {
+    for (const r of parsed) m[r.id] = { type: r.type, params: r.body };
+  });
+  await doc.createCheckpoint();
+});
+```
+
+The importer receives the stored source file (a short-lived download
+URL plus the file's name, type, and size, with the bytes not inlined)
+and the open document, parses the bytes, and writes the records
+through the ordinary handles. `DocumentImporter` types the callback.
+
+Brass decides when an import is needed and runs your importer once. A
+document that already holds its records, or has no stored file, is left
+alone, and the records reach every open client through its normal
+subscription. Declare the `schema` of the records your
+importer writes in `brass-app.json`: importing publishes it and
+stamps it on the document, so the document routes and resolves its
+schema like any imported document.
+
+Sealing the write with `doc.createCheckpoint()` at the end of the
+importer makes the import one undo step, so an undo reverts it whole
+instead of leaving a half-deleted model. An importer that throws
+surfaces through `Brass.onError`, and Brass retries the import later.
+
+**Spread a large format across streams.** When your format is large,
+keep the records a default view reads in the default stream, and move
+the bulk (geometry, an index most opens skip) onto streams you create. Name those streams in your schema's `streams`, and a reader
+merges them the same way it merges any format's:
+
+```ts
+Brass.registerImporter(async (src, doc) => {
+  const { structured, geometry } = parseMyFormat(await bytesOf(src));
+  doc.orderedMap('instances', 'instance_order').mutate((m) => {
+    for (const r of structured) m[r.id] = { type: r.type, params: r.body };
+  });
+  // A stream your schema names, so your serializer composes it back and
+  // any app expecting it merges its records.
+  const geom = await doc.getOrCreateStream('geometry');
+  geom.orderedMap('instances', 'instance_order').mutate((m) => {
+    for (const r of geometry) m[r.id] = { type: r.type, params: r.body };
+  });
+  await doc.createCheckpoint();
+});
+```
+
+Name `geometry` under `streams` in the same schema you ship in
+`brass-app.json`, so a reader can resolve its contract. A document can
+also hold streams your schema does not name (a review overlay, a
+computed cache), and your serializer composes only the streams it
+declares, so those stay in the document and out of the file. Nothing
+here is privileged: a document your importer spreads is
+indistinguishable from one the platform produced, and every app that
+declares the same streams reads it the same way. Your serializer
+reassembles it by reading those same streams back
+(`doc.stream('geometry')`).
+
+`doc.sourceBlob()` is the same source-file read as the importer's
+`src` argument, for code outside the importer that needs the original
+bytes (a "view original" affordance). It rejects with a `BrassError`
+for a document that has no stored original file.
+
+A source file is a set of one or more byte streams: the primary stream
+(what the filename names) plus any sidecar streams uploaded with it (a
+glTF's `.bin` buffer, a shapefile's `.dbf`). `src.streams` lists every
+stream, primary first, each as `{ name, url, content_type, byte_size }`
+with its own download URL, so an app fetches exactly the streams it
+needs, in parallel. A single-stream file has exactly one entry (it
+mirrors the top-level fields), so code that iterates `streams` handles
+both cases in one path:
+
+```ts
+const byName = new Map(src.streams.map((s) => [s.name, s]));
+const buffer = byName.get('scene.bin'); // undefined when not part of the set
+```
+
+**Choose the record as the smallest thing two people edit
+independently.** Concurrent edits to one record resolve
+last-writer-wins on its whole `params`, so a grid of
+independently-edited values is one record per cell (keyed by row and
+column), not one record per row. Reconstruct rows for display and for
+the serializer by walking the cell records. The same reasoning bans
+nesting a collaboratively-edited array inside one record.
+
+## Registering your format's serializer
+
+Your serializer rebuilds the file from your records, and the platform
+runs it for the download button and for drive publish. Write it as the
+inverse of your importer so that it produces the format the importer
+read. Register it once at boot, either before or after `Brass.init`:
+
+```ts
+Brass.registerSerializer((doc) => {
+  const records = doc.orderedMap('instances', 'instance_order');
+  const text = myFormatToText(records.ordered()); // inverse of your parser
+  return new TextEncoder().encode(text);
+});
+```
+
+The serializer takes the open `Document` and returns the bytes
+(`Uint8Array`, or a promise of one). Producing the bytes is its only
+job, and `DocumentSerializer` types the callback. With it registered, your
+app only ever works with records, never with file I/O.
+
+Your app exports so that software outside Brass can read its work. The
+format therefore has to be one that software already opens. If your app
+imports a file, write that same format back out. If your app makes its
+documents from nothing, ask the people who use it which tool they need
+the download to open in, and write that tool's format. A format you
+invent yourself produces a file only your app can read, and apps inside
+Brass already share documents through the schema you declare.
+
+## Declaring what your app handles
+
+Your app declares what it reads and writes in its capability manifest
+at `/.well-known/brass-app.json`. `accepts` matches the uploaded files
+you import, `exports` names the format you write back out, and `schema`
+declares the records you work with. See
+[`app-manifest.md`](./app-manifest.md).
+
+An editor only needs to declare `opens`, and its copy of the format's
+`schema` already does that. Brass delegates a document's import and
+export to an installed app that handles the format, so your app reaches
+the records without writing either half. Write your own importer and
+serializer if you would rather not depend on another app being
+installed, or if you need a format the installed apps do not handle.