@brass-build/client 0.1.0 → 0.2.0

package/docs/imported-documents.md

@@ -1,131 +1,24 @@
-# Imported files and formats
+# Handling a file format
 
-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 user uploads a file or opens a drive item, and Brass turns it into a
+document your app opens like any other. What your app writes 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`.
+**A format someone already imports.** The parsed records are the
+document, 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` so peers can
+open it, and read the records through the ordinary handle surface. See
+[`schemas.md`](./schemas.md).
 
-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.
+**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
+`Brass.registerImporter` and the inverse with `Brass.registerSerializer`.
 
-## The record store
+## Registering an importer
 
-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:
+Register your parse half once at boot, and Brass runs it when an import
+is needed:
 
 ```ts
 Brass.registerImporter(async (src, doc) => {
@@ -140,89 +33,52 @@ Brass.registerImporter(async (src, doc) => {
 });
 ```
 
-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.
+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, so the document routes and resolves its
-schema like any imported document.
+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()` 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();
-});
-```
+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.
 
-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')`).
+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.
 
-`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.
+## Reading the source bytes
 
 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:
+needs, in parallel. A single-stream file has exactly one entry, 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.
+`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.
 
-## Registering your format's serializer
+## Registering a 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`:
+inverse of your importer. Register it once at boot, either before or
+after `Brass.init`:
 
 ```ts
 Brass.registerSerializer((doc) => {
@@ -232,24 +88,24 @@ Brass.registerSerializer((doc) => {
 });
 ```
 
-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.
+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.
 
-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.
+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.
 
 ## 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`
+Your app declares what it reads and writes in its capability manifest at
+`/.well-known/brass-app.json`. `imports` 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).
 

package/docs/presence.md

@@ -1,11 +1,10 @@
 # Presence (live cursors, who's-here)
 
-`doc.presence` is the ephemeral "who is here right now" layer over an
-open document: the roster of other live participants plus a
-lightweight per-user `state` (cursor / camera / selection) and an
-app-namespaced `ext` blob. It is non-null on any open
-writable `Document`, and `null` otherwise. Presence is fully
-ephemeral: nothing survives a disconnect.
+`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.
+Presence is fully ephemeral: nothing survives a disconnect.
 
 ```ts
 import type { PresenceParticipant } from '@brass-build/client';
@@ -24,12 +23,9 @@ doc.presence?.set({ ext: { myApp: { tool: 'select' } } });
 // canvas APIs without parsing) and their last `state`. Interpolate
 // between updates in your render loop.
 //
-// `on('change', ...)` fires once on subscribe with the current roster
-// when peers are already present (you opened a document others are
-// already in), then on every join, leave, or `state` / `ext` update.
-// It does not fire on subscribe when you are the only one here, and an
-// empty roster is the default paint anyway, so one listener covers both
-// the initial render and every change.
+// `on('change', ...)` fires once on subscribe when peers are already
+// present, then on every join, leave, or `state` / `ext` update, so one
+// listener covers both the initial render and every change.
 const renderRoster = (roster: PresenceParticipant[]) => {
   for (const p of roster) renderAvatar(p.connectionId, p.color, p.state);
 };
@@ -79,16 +75,44 @@ indicator) goes under `ext` instead so it stays namespaced and out of
 the cross-app conventions. The `ext` block is otherwise free-form:
 `ext.myApp = { tool: 'select', chatBubble: 'hi' }`.
 
+## How much you can publish
+
+Each layer is capped at 2,048 bytes of serialised JSON, exported as
+`PRESENCE_LAYER_MAX_BYTES`. Brass measures the two layers separately, so a
+large `ext` blob leaves `state` its full budget.
+
+`selection` is the field that reaches the cap in ordinary use, because it
+grows with what the user picked, and one marquee select crosses it.
+Publish a bounded summary when a selection can get large, such as the
+first few ids plus a count, or the selection's bounding box.
+
+The SDK measures each layer before it sends and withholds one that is over
+the cap, so peers keep the last value that fit rather than losing it. Read
+`presence.status` for the current answer, or subscribe with `onStatus`:
+
+```ts
+doc.presence?.onStatus((status) => {
+  if (status.oversize) {
+    showNotice(`Not sharing your ${status.withheld.join(' and ')}`);
+  } else {
+    clearNotice();
+  }
+});
+```
+
+`onStatus` fires on attach and then whenever the answer changes, so an app
+publishing an oversized payload at 10 Hz hears about it once.
+
 ## Types
 
-`doc.presence` is typed `PresenceClient | null`; each `roster` entry
+`doc.presence` is typed `PresenceClient | null`. Each `roster` entry
 is a `PresenceParticipant` with
 `{ connectionId, sub, displayName, avatarUrl, color, joinedAt, lastSeen,
 state, ext }`. `displayName`, `avatarUrl`, and `color` are always
-present as strings; `avatarUrl` is `''` when the user has no picture.
-Both types are exported from `@brass-build/client` (alongside
-`PresenceSetInput` and `PresenceChangeListener`) so you can annotate
-handlers and roster state without source-reading the SDK.
+present as strings, and `avatarUrl` is `''` when the user has no
+picture. Both types are exported from `@brass-build/client`, alongside
+`PresenceSetInput` and `PresenceChangeListener`, for annotating your
+handlers and roster state.
 
 ## Hand-rolling the header roster (custom shell)
 
@@ -107,7 +131,7 @@ const renderRoster = (roster: readonly PresenceParticipant[]): void => {
     const pip = document.createElement('span');
     pip.className = 'pip';
     pip.style.background = p.color;
-    pip.title = p.displayName ?? p.sub ?? '';
+    pip.title = p.displayName;
     if (p.avatarUrl) {
       const img = document.createElement('img');
       img.src = p.avatarUrl;
@@ -115,7 +139,7 @@ const renderRoster = (roster: readonly PresenceParticipant[]): void => {
       img.style.cssText = 'width:100%;height:100%;object-fit:cover;border-radius:50%';
       pip.appendChild(img);
     } else {
-      pip.textContent = (p.displayName ?? p.sub ?? '?').slice(0, 1).toUpperCase();
+      pip.textContent = p.displayName.slice(0, 1).toUpperCase();
     }
     return pip;
   }));
@@ -125,5 +149,5 @@ const renderRoster = (roster: readonly PresenceParticipant[]): void => {
 Drive it from the same `change` subscription as the in-surface remote
 cursors (see the README's "Presence" section). The listener fires on
 subscribe whenever peers are already present, so it paints the initial
-roster for you; render `doc.presence?.roster ?? []` yourself only if you
-want the empty state on screen before anyone joins.
+roster for you. Render `doc.presence?.roster ?? []` yourself to put the
+empty state on screen before anyone joins.

package/docs/schemas.md

@@ -18,8 +18,9 @@ stream's root collections and records.
   other apps converge on, so it names the artifact rather than your app or
   your version: `gcode`, not `acme-cam` and not `gcode-2`. Lowercase
   `a-z 0-9 . _ -`, up to 64 characters, the same rule a stream name follows,
-  so a namespaced `acme.roster` works and a URL does not. A declaration whose family is missing or not a word is
-  not recorded, and your app's dashboard page says so.
+  so a namespaced `acme.roster` works and a URL does not. Brass does not
+  record a declaration whose family is missing or not a word, and reports
+  that on your app's page in the dashboard.
 - **`streams`** maps each stream name your app expects a document to hold
   to that stream's contract. `default` is the stream a document opens
   without asking for one, and takes an entry like any other name. Two
@@ -28,7 +29,7 @@ stream's root collections and records.
   is the record schema, so the keys are record ids. An ordered collection
   is an array, or an array of keys alongside the map.
 - **Foreign keys** ride as an `x-brass-ref` extension on the referring
-  field, an object with a `to` naming the collection referred to.
+  field, an object whose `to` names the collection it points at.
   Standard validators ignore an `x-` keyword.
 - **The `x-brass-` prefix is reserved for Brass.** Give your own extensions
   their own prefix (`x-acme-`), so a name you choose keeps its meaning when
@@ -53,7 +54,7 @@ and an approximation reads as a different contract.
 Streams let one document load in parts, so an app pays for what it opens
 rather than the document's total size. `doc.getOrCreateStream(name)`
 opens the document's stream of that name and makes it when the document
-does not hold it yet; `doc.stream(name)` opens one the document already
+does not hold it yet. `doc.stream(name)` opens one the document already
 holds and rejects any other name.
 
 ```ts
@@ -80,11 +81,9 @@ spread across several.
 
 An app opens a document when they share a family and **everything the app
 requires the document already guarantees.** That is the whole test, and
-it runs per stream, over the streams both sides name.
-
-It is deliberately loose. Your schema does not have to match a document's
-exactly, only ask no more of it, so an app opens documents written
-against shapes it was never built for.
+it runs per stream, over the streams both sides name. Your schema does
+not have to match a document's exactly, only ask no more of it, so an
+app opens documents written against shapes it was never built for.
 
 An exporter composes the streams it declares, so an app exporting a
 document writes the parts it knows about and leaves the rest. Two apps
@@ -103,10 +102,10 @@ that can break anything.
   documents never promised it.
 - **Adding an optional property is safe** in both directions.
 
-Two habits follow. Keep records open (no `additionalProperties: false`)
-so your app preserves fields it does not recognise rather than dropping
-them on write, and handle a missing field gracefully, since Brass
-enforces nothing and a writer may not have written it.
+Keep records open (no `additionalProperties: false`) so your app
+preserves fields it does not recognise rather than dropping them on
+write, and handle a missing field gracefully, since Brass enforces
+nothing and a writer may not have written it.
 
 ## Adding a required property anyway
 
@@ -129,7 +128,3 @@ written before `site` existed, and every document it saves guarantees
 `site` as well. An app still on the old shape reads the result, because
 the document now guarantees more than that app expects. Leave `writes`
 out and one contract covers both sides, which is what most apps want.
-
-The two directions are the whole rule: an app opens a document that
-guarantees at least what the app expects, and writes one whose guarantees
-its own writes cover.