@brass-build/client 0.4.0 → 0.5.0

package/docs/app-manifest.md

@@ -14,8 +14,8 @@ build: a bundler that skips dot-directories drops it silently.
 
 `brass publish` reads that same path out of the directory it publishes
 (`<dir>/.well-known/brass-app.json`), falling back to `brass-app.json` in
-the working directory, so it takes your `name` and `client_token` from the
-manifest you already ship.
+the working directory, and refuses to publish a manifest whose `$ref`
+entries do not resolve.
 
 The platform re-reads the manifest after each deploy, so publishing
 your bundle is what registers it. If Brass hosts your bundle
@@ -25,8 +25,12 @@ 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.
 
-The `opens` and `creates` tokens below only drive discovery and grant
-no access, so you declare them yourself.
+Brass applies your published manifest, including to your app running
+on your own machine, so publish after every change to it.
+
+Brass uses `opens`, `inputs` and `creates` below to decide where to
+offer your app. Declaring them grants your app no access to any
+document.
 
 ## What goes in it
 
@@ -47,15 +51,57 @@ no access, so you declare them yourself.
 
 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.
-- **`imports`** 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.
+- **`opens`** lists the families of documents your app opens as
+  the document a user is working in. Brass offers your app in "Open
+  with" for them, and a user can make it their default. Declaring a `schema`
+  already folds its family in, so most apps list nothing extra here.
+- **`inputs`** lists the schemas your app reads as inputs, such as the
+  models and drawings a dashboard counts. Each entry is a schema,
+  `{ "family", "streams" }`. The hosted picker presents a document to the
+  user when it matches one of these schemas (see
+  [What an app can open](./schemas.md#what-an-app-can-open)). For files that
+  have not been imported yet, the picker evaluates compatibility against the
+  schema declared by the file's importer. A schema declared only under
+  `inputs` does not add your app to the "Open with" menu for those documents.
+  Declare a schema under `inputs` rather than its family under `opens`
+  when your app reads documents through `Brass.chooseInputs` and never
+  edits them. Extract the schema from an existing document with
+  `npx @brass-build/cli schema pull --doc <docId> --out input-schema.json`,
+  which writes to that file while leaving your manifest's own `schema`
+  intact. Copy that file's `schema` into an `inputs` entry, then trim it to
+  only the required fields your code reads, since fewer requirements match
+  a wider set of documents.
+
+  ```json
+  {
+    "inputs": [
+      {
+        "family": "ifc",
+        "streams": { "default": { "type": "object", "required": ["instances"] } }
+      }
+    ]
+  }
+  ```
+
+- **`imports`** lists the file types your app imports. Brass offers your app
+  to whoever uploads a matching file and passes the file to your
+  `Brass.registerImporter` callback. Each entry has these fields:
+
+  | Field | |
+  | --- | --- |
+  | `extension` | The file extension to match, without the dot, in any case, such as `"csv"`. |
+  | `content_type` | The media type to match exactly, such as `"text/csv"`. |
+  | `schema` | Optional. The schema of the document your importer makes from a matching file. Without it, your app's `schema` applies. |
+
+  An entry needs `extension` or `content_type`, and a file matches an entry
+  when it matches every field the entry sets. A file whose entry has no
+  `schema`, in an app with no `schema`, is not imported.
+- **`creates`** is the family Brass stamps on the documents your
+  app makes, so peer apps that declare `opens` for that family can open
+  them. It folds into your own `opens` as well. When you declare a
+  `schema`, Brass stamps `schema.family` instead, so either leave
+  `creates` out or set it to the same family. `brass publish` warns
+  when the two differ.
 - **`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
@@ -74,6 +120,64 @@ Every field is optional, so ship only the ones your app uses.
 - **`schema`** declares the record shape your app works with, whether
   you designed it or adopted an existing one. See
   [`schemas.md`](./schemas.md).
+- **`shared_schemas`** defines schemas by name for other fields to refer
+  to. See [Shared schemas](#shared-schemas) below.
+- **`access`** says who may use your app. Declare `"create": "anyone"`
+  when a visitor who is not signed in can do something in your app, so
+  they can try it before creating an account. A visitor belongs to no
+  organization, so `Brass.chooseInputs`, `Brass.chooseInput` and calls to
+  a service your manifest declares are not available to them.
+
+  | Field | Values |
+  | --- | --- |
+  | `create` | Who may start a new document in your app. `false` when your app makes no new documents of its own, such as a viewer of files other apps import: Brass then offers no New for it, and if your app calls `Brass.createDocument` anyway, the call throws a `BrassError` whose `code` is `"create_not_offered"`. Brass still opens uploaded and imported files in it. `"signed-in"` for people who are signed in. `"anyone"` adds visitors without an account, who can create, upload and edit temporary documents. For `"anyone"`, publish the app with `--gate off --visibility public`. |
+  | `open` | Who may open an organization's public link in your app: `"anyone"`, or `"signed-in"` to ask a visitor to sign in first. |
+
+  When you leave `create` out, Brass uses `"anyone"` for a public app
+  whose load gate is off and `"signed-in"` otherwise, so declare it to
+  keep the same answer when the gate changes. When you leave `open` out,
+  Brass uses `"anyone"`.
+
+  ```json
+  { "access": { "create": "anyone", "open": "anyone" } }
+  ```
+
+  The hosted load gate (`brass publish --gate on|off`) is separate from
+  `access`: it decides whether your hosted bundle loads for a visitor who
+  is not signed in, before any of your code or this manifest runs.
+
+## Shared schemas
+
+Define schemas by name in `shared_schemas`. To use one, write
+`{ "$ref": "#/shared_schemas/<name>" }` in place of a schema in `schema`, a
+`inputs` entry, or an `imports` entry's `schema`. Brass treats a reference as
+the schema it names.
+
+This app writes `tracker` documents, reads as inputs any tracker that has
+`rows`, and imports CSV files as `csv-table` documents that it also reads
+as inputs:
+
+```json
+{
+  "shared_schemas": {
+    "tracker": {
+      "family": "tracker",
+      "streams": { "default": { "type": "object", "required": ["rows", "columns"] } }
+    },
+    "tracker-input": {
+      "family": "tracker",
+      "streams": { "default": { "type": "object", "required": ["rows"] } }
+    },
+    "csv-table": {
+      "family": "csv-table",
+      "streams": { "default": { "type": "object", "required": ["header", "rows"] } }
+    }
+  },
+  "schema": { "$ref": "#/shared_schemas/tracker" },
+  "inputs": [{ "$ref": "#/shared_schemas/tracker-input" }, { "$ref": "#/shared_schemas/csv-table" }],
+  "imports": [{ "extension": "csv", "schema": { "$ref": "#/shared_schemas/csv-table" } }]
+}
+```
 
 ## Services, for calling third-party APIs
 
@@ -132,7 +236,7 @@ because that name belongs to whoever created the bucket.
 
 ### Credential fields
 
-A field is one value the person connecting a credential is asked for. Each one
+A field is one value the user connecting a credential is asked for. Each one
 is a box on the form they fill in.
 
 Some authentication methods declare their own fields, and each method below
@@ -142,7 +246,7 @@ lists the ones it declares. Declare any others in `fields`:
 | --- | --- |
 | `name` | Required. Identifies the field. |
 | `secret` | `true` by default. Brass encrypts the value and shows only its last few characters afterwards. `false` stores it in the clear and shows it in full. |
-| `label` | What the form calls the field. Use the vendor's own word for it, since that is what the person is reading from. Defaults to the name. |
+| `label` | What the form calls the field. Use the vendor's own word for it, since that is what the user is reading from. Defaults to the name. |
 | `readable` | `false` by default. `true` returns the value to your app with the service, for a value your app has to include in the request. Such a field is not secret, so `secret` defaults to `false` for it and declaring both is refused. See [Values the app reads](./services.md#values-the-app-reads). |
 
 ```json
@@ -200,9 +304,9 @@ The fields are `username` and `password`.
 { "host": "api.twilio.com", "auth": { "type": "basic" } }
 ```
 
-Some services take a fixed word as the user half rather than an account name,
+Some services take a fixed word as the username rather than an account name,
 such as `api` for Mailgun. Set it as `username` on the `auth` block and the
-person is asked for the password alone.
+form asks for the password alone.
 
 ```json
 { "host": "api.mailgun.net", "auth": { "type": "basic", "username": "api" } }

package/docs/custom-chrome.md

@@ -44,7 +44,9 @@ Each piece renders one cluster wired to `Brass.session` and returns
 - `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.mountUndoRedo` renders undo / redo as icon buttons once either
+  can act, and nothing before then, so leave its container free to
+  collapse.
 - `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").
@@ -55,17 +57,19 @@ Each piece renders one cluster wired to `Brass.session` and returns
 - `Brass.mountAccountMenu` renders the account avatar menu (email, an
   Open Brass 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
-needs no extra mount for it. A fully custom shell (next section, no
+`mountHeader` draws two strips under the bar. One tells a visitor whose
+document was made without an account that it is temporary, and offers
+sign-in. The other is
+the historical-version preview banner (the return-to-live strip shown
+while a document is previewing an earlier version). A multi-pane app on
+the header shell gets both without another mount. A fully custom shell (next section, no
 `mountHeader`) mounts it itself with `Brass.mountVersionPreview(el)`,
 which renders nothing until there is something to show, like the drive
 badge.
 
-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`).
+Mount the chrome once, when the user signs in or becomes a guest, not
+per document: the file menu has to exist before any document is open or
+a fresh user has no New / Open (the same rule as `mountToolbar`).
 
 ## Fully custom shells: the command list as data
 
@@ -87,8 +91,8 @@ 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.                              |
+| `new`      | `session`  | `menu`    | New                | Signed in, or signed out where `access.create` in your manifest resolves to `"anyone"`. Never when it is `false`. |
+| `open`     | `session`  | `menu`    | Open... / Upload... (signed out) | Signed in, or signed out where `access.create` in your manifest resolves to `"anyone"`. |
 | `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.         |
@@ -98,8 +102,8 @@ The full built-in set when a doc is bound, in list order:
 
 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
+state of this one there, `share` shares the document with someone or
+exports it to a file, and `manage` (the entry that offers delete) comes last. Render the
 list in the order you receive it.
 
 Each command carries `enabled` (read on every notification),
@@ -108,8 +112,8 @@ 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.
+knows whether the document has an exportable file, since downloading is
+one option in 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
@@ -132,7 +136,11 @@ invoke, and the SDK owns the behavior:
 
 - **`new`** creates a document and binds it, asking the platform where
   to put it (`Brass.session.create()` under the hood).
-- **`open`** opens the hosted picker and binds what the user chooses.
+- **`open`** opens the hosted picker and opens the document the user chooses.
+  Without an account it reads `Upload...` and creates a document from a file
+  the visitor chooses (`Brass.session.open()` under the hood). Before either
+  command replaces a document the visitor created without an account and has
+  edited, it prompts whether to sign in to save it to their account.
 - **`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`
@@ -142,7 +150,7 @@ invoke, and the SDK owns the behavior:
   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.
+  and, where an exportable file is available, the download action.
 - **`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,

package/docs/hosted-ui-advanced.md

@@ -1,7 +1,7 @@
 # Hosted UI: advanced
 
 Brass owns some surfaces: you call one method and Brass renders the UI
-in a modal iframe over your page. `Brass.session` wires the common ones
+in a modal iframe over your page. `Brass.session` runs 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.
 
@@ -9,9 +9,34 @@ the rest and how they behave in browsers that block the iframe.
 
 | 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. |
 
+## Narrowing a choice to the files you need
+
+`Brass.chooseInputs(families, options?)` is how a user chooses files,
+folders and projects for your app to read (see the README). `accept`
+narrows the files of those families, for one call, by name or extension. Pass it once your app knows which files it
+needs. An app that has just parsed a federation file asks for the models
+that file names:
+
+```js
+await Brass.chooseInputs(['ifc'], {
+  prompt: `Models in ${federation.name}`,
+  accept: { names: federation.modelFileNames },
+});
+```
+
+The picker renders `prompt` as a subtitle beneath its title. Pass a prompt
+when narrowing the list with `accept`, explaining why only specific files appear.
+On a request you do not narrow, omit the prompt as the picker already shows
+all documents your app can open.
+
+`names` matches both the document's name and the original filename it was imported
+from, and `extensions` matches either name's extension. A document in the specified
+families passes when it matches any given name or extension. When a user selects a
+folder or project, this filtering persists, so listing the container returns only
+the matching documents.
+
 Version history is a built-in file-menu command (`history` in
 `session.commands` and the SDK toolbar's file menu) rather than a
 launcher method, so an app on `mountToolbar` or `mountFileMenu` gets it
@@ -22,13 +47,18 @@ with no code.
 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`.
+Open picker (`Brass.session.open()`) 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 convenience,
-correct whenever you receive it.
+Brass.session.open()` never runs, and the picked document opens into the
+session on reload instead.
+
+`chooseInputs` and `chooseInput` do not redirect. Where the browser blocks
+their iframe they reject with a `BrassError` whose `code` is
+`'iframe_unavailable'`. Show the error's `message` and keep the references
+your app already has.
 
 ## `BrassError` `.code` values
 
@@ -38,6 +68,8 @@ The hosted-UI launchers reject with `BrassError` carrying a `.code`
 - `'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.
+- `'iframe_unavailable'`: the browser blocked the iframe and the surface
+  has no redirect to fall back on (`chooseInputs`, `chooseInput`).
 
 ## Theming
 

package/docs/imported-documents.md

@@ -11,67 +11,123 @@ editor: declare the document's schema in `brass-app.json` so peers can
 open it, and read the records through the ordinary handle surface. See
 [`schemas.md`](./schemas.md).
 
-**Any other file.** The document is an opaque file (source `schema_type`
-is `brass:file`) until your app parses it. Register the parse half with
+**Any other file.** Nothing imports the file until your app registers an
+importer for its type. Register the parse half with
 `Brass.registerImporter` and the inverse with `Brass.registerSerializer`.
 
 ## Registering an importer
 
 Register your parse half once at boot, and Brass runs it when an import
-is needed:
+is needed. Call `Brass.registerImporter` at startup, unconditionally: not
+after sign-in, and not after a document opens. Brass may load your app only
+to run its importer, in a page where nobody signs in and no document opens,
+and an importer registered behind either step is never registered there.
 
 ```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();
+Brass.registerImporter(async (file) => {
+  const parsed = parseMyFormat(await file.bytes()); // your own parser
+  const instances: Record<string, unknown> = {};
+  for (const r of parsed) instances[r.id] = { type: r.type, params: r.body };
+  return {
+    streams: {
+      default: { instances, instance_order: parsed.map((r) => r.id) },
+    },
+  };
 });
 ```
 
-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. `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.
-
-Sealing the write with `doc.createCheckpoint()` 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`. Brass
-retries an import that wrote no records. Once records are written, it
-refuses a later import of that document, because running the importer
-again over them would write each of those records twice.
+The importer takes a file and returns JSON, so a test can call it
+directly with a file the test builds. `DocumentImporter` types the
+callback, `ImportFile` types the file it receives (`name`,
+`content_type`, `byte_size`, and `bytes()`, which fetches the file), and
+`ImportResult` types what it returns.
+
+`streams` is the document's content, keyed by stream name. The
+document opens on `default`. Your app opens any other stream with
+`doc.stream(name)`, so put content there that a user can skip while
+reading the rest (a heavy geometry layer beside the elements). Each stream
+is a JSON object whose top-level values are objects, arrays, or strings. A
+stream name uses lowercase letters, digits, `.`, `-`, and `_`. The
+`schema` in your `brass-app.json` describes this shape, and
+`npx @brass-build/cli contents --doc <docId>` writes the content of a
+document your importer produced to `contents.json` (`--stdout` prints it
+instead).
+
+Brass decides when a document needs an import and runs your importer
+once. Every client with the document open then receives the whole result
+together. Declare the `schema` of the records your importer returns in
+`brass-app.json`. The import publishes that schema and stamps it on the
+document.
+
+When your importer throws, or returns no streams or only empty
+collections, Brass reports the error through `Brass.onError`. Brass also
+records the failure on the document and does not run your importer on
+that file again until the file changes. Everyone who opens the document
+sees your error's message after your app's name, so write it for that
+user: "Row 3 has no date column" rather than a stack trace.
 
 Key each record by the format's own stable id. When the format has no
 native id, derive one from the record's own content rather than from its
 position in the file, which is not stable across a re-import.
 
-## Reading the source bytes
+## Reporting what the import skipped or assumed
 
-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, so code
-that iterates `streams` handles both cases in one path:
+When your importer reads only part of a file, return an `ImportReport`
+beside the streams that says what it left out and what it filled in.
+Brass stores the report with the import and shows it, in your words, on
+the document's page:
 
 ```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
+Brass.registerImporter(async (file) => {
+  const rows = parseCsv(new TextDecoder().decode(await file.bytes()));
+  const content = rowsToContent(rows); // your own mapping
+  const findings: ImportFinding[] = [];
+  if (rows.ragged > 0) {
+    findings.push({
+      kind: 'skipped',
+      message: `Skipped ${rows.ragged} rows with more fields than the header.`,
+    });
+  }
+  if (!rows.delimiterDeclared) {
+    findings.push({
+      kind: 'assumed',
+      message: 'The file does not say how its fields are separated, so commas were used.',
+    });
+  }
+  return findings.length > 0
+    ? { streams: { default: content }, report: { summary: `Read ${rows.length} rows.`, findings } }
+    : { streams: { default: content } };
+});
 ```
 
-`doc.sourceBlob()` is the same read 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.
+`summary` is one optional sentence stating what the import read, which Brass
+shows above the findings.
+
+Each finding's `message` is one sentence, and the user sees it as you
+wrote it. Its `kind` says what the sentence describes:
+
+- `skipped` is content in the file that the import did not read.
+- `assumed` is a value the file did not give, which the import supplied.
+- `missing` is something the file names that did not arrive (a texture a
+  model refers to, a drawing it references).
+
+Return a report only when your importer has findings. Report only what
+your importer can establish from the file, and do not tell the user a
+file was read completely when the format cannot confirm it.
+
+An app reads an open document's report from `doc.importReport` (`null`
+when there is none), whichever importer wrote it. A `skipped` or `missing` finding means the document
+contains only part of its file. An `assumed` finding means the importer
+supplied some of the document's values rather than reading them from the
+file.
+
+## Reading the source bytes
+
+Code outside the importer that needs the original bytes (a "view
+original" affordance) calls `doc.sourceBlob()`. It resolves the stored
+file as `{ url, filename, content_type, byte_size }`, where `url` is a
+short-lived download URL. It rejects with a `BrassError` for a document
+that has no stored original file.
 
 ## Registering a serializer
 
@@ -83,23 +139,20 @@ after `Brass.init`:
 ```ts
 Brass.registerSerializer((doc) => {
   const records = doc.orderedMap('instances', 'instance_order');
-  const text = myFormatToText(records.ordered()); // inverse of your parser
+  const text = myFormatToText(records.entries()); // inverse of your parser
   return new TextEncoder().encode(text);
 });
 ```
 
 The serializer returns the bytes (`Uint8Array`, or a promise of one).
-`DocumentSerializer` types the callback. It runs detached, with no
-subscription feeding it, so the document it is handed reads its
-containers whole: `StoredDocument` types that document, and its `map` /
-`list` return a `StoredMap` / `StoredList`, which add `read()` to the
-handle an app holds.
+`DocumentSerializer` types the callback. It receives the same document
+your app reads, and walks each container with `entries()` or `values()`.
 
 Your app exports so that software outside Brass can read its work, so
-write a format 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.
+write a format that outside software already supports. If your app imports a file
+format, export that same format back out. If your app creates documents from
+scratch, determine which formats users need to open in outside tools and export
+that format.
 
 ## Declaring what your app handles
 

package/docs/presence.md

@@ -3,7 +3,10 @@
 `doc.presence` is the "who is here right now" layer over an open
 document: the roster of other live participants plus a small per-user
 `state` (cursor / camera / selection) and an app-namespaced `ext` blob.
-It is non-null on any open writable `Document`, and `null` otherwise.
+It is non-null on any live open, editable or `{ readOnly: true }`,
+including a signed-out visitor's open through a shared link, so a viewer
+shows up in the roster beside the editors, and `null` on a
+`{ frozen: true }` copy.
 Presence is fully ephemeral: nothing survives a disconnect.
 
 ```ts
@@ -16,6 +19,8 @@ const doc = await Brass.openDocumentById('doc_abc');
 // (e.g. on every pointermove).
 doc.presence?.set({ state: { cursor: { x, y, z } } });
 doc.presence?.set({ ext: { myApp: { tool: 'select' } } });
+// A key set to `undefined` is removed, for you and for every peer.
+doc.presence?.set({ state: { selection: undefined } });
 
 // React to everyone else. `roster` is the other participants; each
 // carries a server-stamped `displayName` + `color` (CSS-ready string,
@@ -78,8 +83,8 @@ interface PresenceState {
 
 A caret belongs in `state` rather than in `ext` for the same reason a
 selection does: a document of prose is often open in more than one app,
-and a reader wants to see where the other person is working whichever
-app they are each in. Publish it on every selection change, which the
+and each user wants to see where the others are working, whichever
+app each is in. Publish it on every selection change, which the
 10 Hz debounce already paces.
 
 App-specific state (the current tool, a chat bubble, a typing
@@ -122,7 +127,14 @@ is a `PresenceParticipant` with
 `{ connectionId, sub, displayName, avatarUrl, color, joinedAt, lastSeen,
 state, ext }`. `displayName`, `avatarUrl`, and `color` are always
 present as strings, and `avatarUrl` is `''` when the user has no
-picture. Both types are exported from `@brass-build/client`, alongside
+picture. A signed-out visitor on a shared link has `sub: ''` and a
+`displayName` such as `Guest 1a2b3c`, so when you group participants
+into people by `sub`, show each participant with an empty `sub` on its
+own, keyed by `connectionId`. A visitor's second tab is a second guest.
+On that visitor's page, every signed-in participant also arrives with
+`sub: ''`, an empty `avatarUrl` and a `displayName` such as
+`Member 4d5e6f`.
+Both types are exported from `@brass-build/client`, alongside
 `PresenceSetInput` and `PresenceChangeListener`, for annotating your
 handlers and roster state.