@brass-build/client 0.4.0 → 0.5.0

package/docs/schemas.md

@@ -1,6 +1,6 @@
 # Schemas
 
-A schema declares what your app expects a document to hold. Declaring one
+A schema declares what your app expects a document to contain. Declaring one
 in your `brass-app.json` routes matching documents to your app, and lets
 any developer who can open one of those documents build against the same
 shape.
@@ -21,13 +21,16 @@ stream's root collections and records.
   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
+- **`streams`** maps each stream name your app expects a document to have
   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
   streams that carry the same shape carry the same body.
 - **A collection of records** is an object whose `additionalProperties`
   is the record schema, so the keys are record ids. An ordered collection
   is an array, or an array of keys alongside the map.
+- **A text root** (`doc.text(key)`) reads as a string wherever the
+  document is read as data, `brass contents` included, so describe it as a
+  string property of the stream: `{ "type": "string" }`.
 - **Foreign keys** ride as an `x-brass-ref` extension on the referring
   field, an object whose `to` names the collection it points at.
   Standard validators ignore an `x-` keyword.
@@ -54,8 +57,8 @@ 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
-holds and rejects any other name.
+does not have it yet. `doc.stream(name)` opens one the document already
+has and rejects any other name.
 
 ```ts
 const stream = await doc.getOrCreateStream(name);
@@ -67,7 +70,7 @@ stream.map('records').mutate((m) => {
 `getOrCreateStream` is idempotent, and concurrent callers converge on one
 stream, so an app reaches for the stream it expects on every open without
 checking first. Only that call writes, so a read-only open reads through
-`doc.stream` and handles the rejection when the document does not hold
+`doc.stream` and handles the rejection when the document does not have
 the stream. Names follow the same rule a family does: `a-z 0-9 . _ -`, 1 to
 64 characters, starting with a letter or digit.
 

package/docs/services.md

@@ -43,7 +43,7 @@ the host needs, and tells anyone who cannot answer who to ask.
 
 | `code`                | What it means                                                                                             |
 | --------------------- | --------------------------------------------------------------------------------------------------------- |
-| `credential_required` | No credential is connected for this host, or the one connected is not approved for your app, no longer covers what your app sends, or carries no value under a name your app reads back. One code, because the dialog is the answer to all of them. The body's sentence says which, for a person to read. |
+| `credential_required` | No credential is connected for this host, or the one connected is not approved for your app, no longer covers what your app sends, or carries no value under a name your app reads back. One code, because the dialog is the answer to all of them. The body's sentence says which, for a user to read. |
 
 **Your own key is what is missing.** These are yours to settle on your app's
 settings page, so there is nothing to raise on the page: report the feature as
@@ -78,7 +78,7 @@ on their own.
 | `code`               | What it means                                                                          |
 | -------------------- | -------------------------------------------------------------------------------------- |
 | `cap_exceeded`       | A cap has been reached. Try again later.                                               |
-| `rate_limited`       | Over Brass's own rate limit. Slow down.                                                |
+| `rate_limited`       | Over Brass's own rate limit. The SDK resends a call that limit turns away for only a moment, so wait before calling again. |
 | `calls_paused`       | Whoever owns the account being spent set its cap to zero. Waiting will not clear it.   |
 | `vault_unavailable`  | Brass could not read the stored key just now. Nothing is wrong with it; make the same call again. |
 
@@ -112,7 +112,7 @@ signed in, the app has no organization, or it is running in one that has not
 installed it.
 
 Each entry also carries `connectable`, which says whether the dialog has
-anything for the person on the page to do at that host. Together the two are
+anything for the user on the page to do at that host. Together the two are
 the whole branch:
 
 ```js
@@ -134,7 +134,7 @@ if (await Brass.connectService('api.anthropic.com')) showSummariseButton();
 
 Passing `requestMissingCredentials: true` to `callService` opens the same
 dialog from the call, which then goes through once the user answers. It covers
-every refusal the person using your app can answer: `credential_required`, plus
+every refusal your app's user can answer: `credential_required`, plus
 `credential_rejected` and `credential_scheme_unusable` when the account that
 failed is one they own.
 
@@ -157,7 +157,7 @@ same one: you name a host, and Brass attaches whichever credential is in
 force.
 
 Your app reads `connectable` rather than the supplier, because that is the
-split it can act on. Where it is true, the person using your app can
+split it can act on. Where it is true, your app's user can
 settle it, so a Connect button leads somewhere; where it is false, the host is
 waiting on you, so there is nothing to raise. Leave the wording about who to
 ask to the dialog, which knows both the supplier and who is reading, where
@@ -205,7 +205,7 @@ if (cf?.ready && account) {
 
 Brass shows your setup instructions on the form that collects a credential,
 and you are strongly encouraged to provide them. Without them the form shows
-your field labels alone, and the person filling it in has to work out what
+your field labels alone, and the user filling it in has to work out what
 to create at the vendor and where.
 
 Declare a `setup` beside the host:

package/docs/streams.md

@@ -1,19 +1,29 @@
-# Streams: partitioning a document for lazy loading
+# Streams: loading a document in parts
 
 A document is a container of **streams**: named units of document
 state that load independently. Opening a document costs only the
 streams your app touches, so download, load, and memory scale with what
-you use rather than with the document's total size. Split a
-multi-discipline design into architectural, plumbing, HVAC, and
-structural streams, and a plumbing tool opens one of them. Every stream
+the app reads rather than with the document's total size. Every stream
 is live, collaborative state that merges the same way the rest of the
 document does.
 
+The app or importer that writes a document decides its streams. Your
+app can put a heavy part of its content (a terrain mesh, a point-cloud
+index, a layer only some views draw) in a stream of its own, and an open
+that does not ask for that stream never downloads it. Your app can also
+keep records about a document (clash findings, review notes, a cache of
+derived results) in a stream beside the document's content, so they sync
+and version with it and stay out of an exported file unless the exporter
+declares that stream. An
+importer can split a model the same way: with its geometry in a stream
+of its own, a property editor opens only the default stream, and a 3D
+viewer opens only the geometry.
+
 Every document has a stream named **`default`**, and an open that names
 no stream opens that one, so the doc-level handles (`doc.map(...)`,
-`doc.orderedMap(...)`) read it. An unpartitioned document is one whose
-content lives entirely there. Name another stream on the open (below)
-and the doc-level handles read that one instead.
+`doc.orderedMap(...)`) read it. A document with one stream keeps all of
+its content there. Name another stream on the open (below) and the
+doc-level handles read that one instead.
 
 ## Opening and editing a stream
 
@@ -28,25 +38,23 @@ records.subscribe((change) => render(change));
 
 `doc.stream(name)` resolves once per name: the first call downloads the
 stream's snapshot and subscribes it live, and repeat calls return the same
-open. It only reads, so a name the document does not hold rejects rather
-than being created. `doc.getOrCreateStream(name)` is the call that makes
-one. It is idempotent and concurrent callers converge on one stream, so an
-app reaches for the stream it expects on every open without checking
-first. A `DocumentStream` carries the document's own reading and writing
-surface scoped to that stream: `map` / `list` / `orderedMap` handles,
-`mutate`, `subscribe`, and `undo` / `redo`.
+open. It only reads, so it rejects a name the document does not have.
+To make a stream, see [Adding a stream](#adding-a-stream). A
+`DocumentStream` has the same read and write methods as the document,
+scoped to that stream: `map` / `list` / `orderedMap` handles, `mutate`,
+and `subscribe`.
 
 ## Opening at a stream
 
 `Brass.openDocumentById(docId, { stream })` opens the document with that
 stream as its own state, so `doc.map(...)` hands you its records and the rest
-of the document is never downloaded. An app that works in one part of a large
-document pays for that part alone:
+of the document is never downloaded. A 3D viewer of an imported model
+opens at `geometry` and downloads nothing else:
 
 ```ts
-const doc = await Brass.openDocumentById(docId, { stream: 'hvac' });
+const doc = await Brass.openDocumentById(docId, { stream: 'geometry' });
 doc.orderedMap('instances', 'instance_order').subscribe((change) => {
-  for (const [key, record] of change.set) hold(key, record); // hvac's records
+  for (const [key, record] of change.set) draw(key, record); // geometry records
 });
 ```
 
@@ -63,165 +71,142 @@ for (const info of await doc.listStreams()) {
 }
 ```
 
-Names are `a-z 0-9 . _ -`, 1 to 64 chars, starting with a letter or
-digit, the same rule a schema family follows. `default` is one of them:
-every document already holds it, so `getOrCreateStream` resolves it
-without a request, and a loop over the names your schema declares needs
-no case for it. `getOrCreateStream` writes, so a read-only open reads
-with `doc.stream` instead and shows a degraded view when the document
-does not hold the stream.
-
-## Undo and editing model
+## Adding a stream
 
-Each stream is its own collaborative unit: concurrent edits merge per
-stream, and each stream keeps its own local undo stack
-(`stream.undo()` / `stream.redo()`). The doc-level `doc.undo()` covers
-only the default stream.
-
-A stream's local edits group into one undo step until the group is
-**sealed** with `stream.sealUndoStep()`, the same same-stroke
-collapsing doc-level undo gets from checkpoints. Seal when a user
-operation completes. An app that never seals gets one giant step per
-session.
-
-### Undoing an operation that spans streams
-
-When one user action writes to several streams (move a wall in
-`architectural`, reroute its duct in `hvac`), keep an app-level
-operation journal and undo each touched stream once per journal entry.
-Two rules make the stacks line up:
-
-1. **Seal every touched stream when the operation completes.** The
-   seal is what makes the operation exactly one undo step in each
-   stream, however many mutates it took.
-2. **Route every local edit through the journal.** The alignment
-   argument is LIFO: if every operation is journaled and sealed, each
-   stream's stack top always belongs to the most recent journaled
-   operation that touched it. An edit that bypasses the journal
-   breaks that.
+`doc.getOrCreateStream(name)` opens the document's stream of that name,
+and creates it if the document does not have it yet. A stream your app
+adds syncs and versions with the rest of the document, and only the
+opens that ask for it download it. Your app can add a stream to any
+document the user can edit, including a file an importer or another app
+made. The call is idempotent, and
+concurrent callers get the same stream, so your app can call it on
+every open without checking first:
 
 ```ts
-import type { DocumentStream } from '@brass-build/client';
-
-type Op = { label: string; streams: string[] };
-const undoJournal: Op[] = [];
-const redoJournal: Op[] = [];
-
-// Wrap every user operation: run the writes, then seal + journal.
-async function operation(
-  label: string,
-  streams: string[],
-  run: (open: Map<string, DocumentStream>) => void,
-) {
-  const open = new Map(
-    await Promise.all(
-      streams.map(async (n) => [n, await doc.stream(n)] as const),
-    ),
-  );
-  run(open);
-  for (const s of open.values()) s.sealUndoStep();
-  undoJournal.push({ label, streams });
-  redoJournal.length = 0; // a fresh edit clears redo, as usual
-}
-
-await operation('Move wall', ['architectural', 'hvac'], (open) => {
-  open.get('architectural')!.map('instances').mutate((m) => {
-    /* move the wall */
-  });
-  open.get('hvac')!.map('instances').mutate((m) => {
-    /* reroute the attached duct */
-  });
+const findings = await doc.getOrCreateStream('clash-findings');
+findings.map('findings').mutate((m) => {
+  m[id] = { elements: [a, b], status: 'open' };
 });
+```
 
-async function undoOperation() {
-  const op = undoJournal.pop();
-  if (!op) return;
-  // Reverse application order, so dependent changes unwind last-first.
-  for (const name of [...op.streams].reverse()) {
-    (await doc.stream(name)).undo();
-  }
-  redoJournal.push(op);
-}
+Your app can add a stream to any document it can edit, including one
+that another app created or imported. When the document already has a
+stream of that name, such as one its importer wrote, `getOrCreateStream`
+opens that stream instead of making a new one. Name the streams your app
+adds after your app (`acme-clash-findings`) rather than after their
+content, so your app does not write into a stream that another writer
+named first.
+
+Names are `a-z 0-9 . _ -`, 1 to 64 characters, starting with a letter or
+digit, the same rule a schema family follows. `default` is a valid name
+too: every document already has it, so `getOrCreateStream` resolves it
+like any existing name, and a loop over the names your schema declares
+needs no case for it. `getOrCreateStream` writes, so on a read-only
+open, read with `doc.stream` instead, and render a reduced view when the
+document does not have the stream.
 
-async function redoOperation() {
-  const op = redoJournal.pop();
-  if (!op) return;
-  for (const name of op.streams) {
-    (await doc.stream(name)).redo();
-  }
-  undoJournal.push(op);
-}
-```
+## Undo and editing model
 
-Bind your keyboard shortcut and undo button to `undoOperation()`
-rather than `doc.undo()` (which covers only the default stream).
-Collaborators' edits do not disturb the alignment: undo stacks are
-local-peer-scoped, and each stream's undo rebases your reverted step
-over remote changes the same way single-document undo does.
-
-Design around two properties of it. The cross-stream undo is **not
-atomic**: each stream's revert is its own commit, so a collaborator can
-briefly observe one stream reverted before the other (the same window
-any multi-stream operation has). And the journal is **in-memory**: a
-reload starts it empty, exactly like single-document undo. When an
-operation cannot tolerate that window, its data belongs in one stream:
-partition by load unit, and keep records that must change together in
-the same stream.
-
-## When to partition
-
-Opening a stream costs a request for its snapshot, and the first one on a
-document also reads the stream manifest, so add a stream when it carries
-real content that some opens can skip. Partition by **load unit** (a
-discipline, a heavy layer, a dataset a specific tool reads), not by
-concept. Aim for a handful of streams carrying megabytes each. Dozens
-of tiny streams make opening everything slower than a monolith, and
-content every open needs belongs in the default stream.
+Each stream is its own collaborative unit: concurrent edits merge per
+stream. One Undo reverts the whole step even while a collaborator edits
+the same stream, and a map or text handle's `subscribe` fires once for
+each commit the step took, each with `origin.source` `'undo'` (or
+`'redo'`). A write your app makes on its own, such as the results of a
+pass over other documents, passes `{ undoable: false }` to `mutate` so
+the user's Undo skips it.
+
+A stream that reaches the largest size Brass keeps stops taking writes on
+its own: `stream.readOnly` and `stream.atCapacity` read `true`, and the
+document's other streams keep taking writes. The edit Brass refused stays
+on screen until your app opens the stream again, which loads what Brass
+saved. Read `stream.atCapacity` to stop offering bulk work on that stream.
+
+## When to add a stream
+
+Opening a stream incurs a snapshot request, and opening the first stream
+on a document also retrieves the stream manifest. Add a stream when
+specific workflows can skip its content (such as a model's geometry, a heavy
+layer, or tool-specific data). Partition content by what each workflow loads,
+rather than by conceptual divisions. Aim for a handful of streams
+carrying several megabytes each. Opening dozens of tiny streams is slower than
+loading a single stream, and data required across every workflow belongs in
+the default stream.
 
 ## Reading a document spread across streams
 
 Your schema names the streams it expects a document to be spread over,
 under `streams`. A small document keeps every record in its default
-stream; a large one moves the bulk (an IFC's geometry, an index most opens
+stream; a large one moves the bulk (a model's geometry, an index most opens
 skip) onto the streams the schema names, so an app that reads only part of
 the content loads only that part. The declaration is the same either way,
 because it says which streams your app expects, not what any one document
-turned out to hold.
+turned out to contain.
+
+Open only the streams that contain the records your app needs. The SDK
+downloads and decodes each stream you open in full, so a property editor
+over a model whose geometry has its own stream opens the default stream
+alone.
 
-If your app follows references between records, read every stream the
-DOCUMENT holds, because a referenced record may live in one the default
-stream does not. `doc.listStreams()` is that list, so merge by id:
+If your app follows references into records in another stream (a
+viewer resolving an element's shape, a clash check reading bodies), open
+every stream the document has, because a referenced record can be in any
+of them. `doc.listStreams()` lists them, so open them together and merge the
+records by id:
 
 ```ts
 import type { OrderedMapHandle } from '@brass-build/client';
 
 type StoredRecord = { type: string; params: unknown };
 const store: Record<string, StoredRecord> = {};
-const fold = (records: OrderedMapHandle<StoredRecord>) =>
+
+const streams = await Promise.all(
+  (await doc.listStreams()).map((info) => doc.stream(info.name)),
+);
+const handles: OrderedMapHandle<StoredRecord>[] = streams.map((s) =>
+  s.orderedMap<StoredRecord>('instances', 'instance_order'),
+);
+for (const records of handles) {
   records.subscribe((change) => {
     for (const [key, record] of change.set) store[key] = record;
     for (const key of change.deleted) delete store[key];
   });
-
-fold(doc.orderedMap<StoredRecord>('instances', 'instance_order'));
-for (const info of await doc.listStreams()) {
-  const stream = await doc.stream(info.name);
-  fold(stream.orderedMap<StoredRecord>('instances', 'instance_order'));
 }
 // store['#137'] resolves wherever #137 lives.
 ```
 
-The loop reads an unpartitioned document the same way it reads a split
-one, so it needs no special case. Open only what you read: an app that
-needs just the default view's records reads the default stream alone,
-and one that resolves references reads them all and pays for the
-streams it opens.
+This reads a document with one stream the same way it reads one with
+several, so it needs no special case.
+
+### Knowing when every stream has arrived
+
+A handle's `onSettled` callback fires when that one container has arrived
+whole. A conclusion drawn across several streams (a model with no
+geometry, a count, "no run yet") is true only after every stream it reads
+has settled. Until your app opens a stream, its records are unknown, not
+empty. Render such a conclusion once every handle has settled, and show
+the loading state until then:
+
+```ts
+const unsettled = new Set(handles);
+for (const records of handles) {
+  records.onSettled(() => {
+    unsettled.delete(records);
+    if (unsettled.size === 0) render(store);
+  });
+}
+```
+
+`onSettled` fires again when a version checkout replaces a container, so
+`render` runs again for the version the user switched to. The same
+applies to streams your app adds (findings, review notes). Open the ones
+the document has alongside the rest, and treat their records as unknown
+until their handles settle.
 
-A document can hold streams your schema does not name (computed results,
-review notes, a cache), so the merge above skips them and an exporter that
-does not declare them writes nothing from them. Name a stream in your
-schema to read it, and `doc.getOrCreateStream` makes it when the document
-does not hold it yet.
+A document can have streams your schema does not name (computed results,
+review notes, a cache). An exporter writes nothing from a stream it does
+not declare. Read the streams your schema names, and the others only
+when you follow references into them. `doc.getOrCreateStream` makes a
+stream your schema names when the document does not have it yet.
 
 ## Exporting across streams
 
@@ -231,11 +216,15 @@ lives:
 
 ```ts
 Brass.registerSerializer(async (doc) => {
-  const arch = await doc.stream('architectural');
-  const hvac = await doc.stream('hvac');
+  const names = new Set((await doc.listStreams()).map((s) => s.name));
+  const geometry = names.has('geometry')
+    ? (await doc.stream('geometry'))
+        .orderedMap('instances', 'instance_order')
+        .entries()
+    : [];
   return encodeMyFormat(
-    arch.orderedMap('instances', 'instance_order').ordered(),
-    hvac.orderedMap('instances', 'instance_order').ordered(),
+    doc.orderedMap('instances', 'instance_order').entries(),
+    geometry,
   );
 });
 ```

package/docs/text-fields.md

@@ -9,7 +9,7 @@ what a keystroke costs, and where a text container belongs in a document.
 ## Paint a peer's edit without losing the caret
 
 Assigning `field.value` moves the caret to the end, so an editor that
-assigns unconditionally throws away the reader's place on every peer
+assigns unconditionally throws away the user's place on every peer
 keystroke, and one that skips a focused field never shows a peer's typing
 to anyone who is typing themselves. Find the span the incoming value
 replaced, and move the caret across it:
@@ -29,10 +29,12 @@ report.subscribe((value, origin) => {
   const max = Math.min(painted.length, value.length);
   let start = 0;
   while (start < max && painted.charCodeAt(start) === value.charCodeAt(start)) start += 1;
+  if (start > 0 && isHighHalf(value.charCodeAt(start - 1))) start -= 1;
   let tail = 0;
   while (tail < max - start
          && painted.charCodeAt(painted.length - 1 - tail)
             === value.charCodeAt(value.length - 1 - tail)) tail += 1;
+  if (tail > 0 && isLowHalf(value.charCodeAt(value.length - tail))) tail -= 1;
   const removed = painted.length - tail - start;
   const inserted = value.length - tail - start;
 
@@ -45,13 +47,13 @@ report.subscribe((value, origin) => {
     : caret >= start + removed ? caret + inserted - removed
     : start + Math.min(caret - start, inserted);
 
-  // A reader with text selected has two offsets, and `selectionDirection`
+  // A user with text selected has two offsets, and `selectionDirection`
   // says which of them their next keystroke extends from.
   const focused = document.activeElement === field;
   const anchor = carry(field.selectionStart ?? 0);
   const head = carry(field.selectionEnd ?? field.selectionStart ?? 0);
   const direction = field.selectionDirection;
-  // Assigning `value` resets the scroll, which throws a reader who is
+  // Assigning `value` resets the scroll, which throws a user who is
   // partway down a long field back to the top on every peer keystroke.
   const scroll = field.scrollTop;
 
@@ -65,19 +67,24 @@ report.subscribe((value, origin) => {
 ```
 
 Offsets count UTF-16 code units, which is what a text field's
-`selectionStart` reports, so the two agree with no conversion. The same
-units are why an offset needs one more check before it is used: a character
+`selectionStart` reports, so the two agree with no conversion. A character
 outside the Basic Multilingual Plane, an emoji above all, is two code units,
-and the `charCodeAt` walk above stops between them whenever the edit sits
-next to one. `nudgeOffPair` moves such an offset off the seam:
+and two emoji can share their first unit (😀 and 🙂 both start with
+`0xd83d`), so the `charCodeAt` walks can stop between the halves of a
+character. Keep the two checks after the walks: they move each end of the
+span back onto a whole character, so a caret where a peer types an emoji
+ends up after it, since the caret binds to the text on its right. A carried
+offset can still land inside a character the peer inserted, and
+`nudgeOffPair` moves it back to that character's start:
 
 ```ts
+const isHighHalf = (unit: number) => unit >= 0xd800 && unit <= 0xdbff;
+const isLowHalf = (unit: number) => unit >= 0xdc00 && unit <= 0xdfff;
+
 function nudgeOffPair(text: string, at: number): number {
   const bounded = Math.max(0, Math.min(at, text.length));
   if (bounded <= 0 || bounded >= text.length) return bounded;
-  const before = text.charCodeAt(bounded - 1);
-  const after = text.charCodeAt(bounded);
-  const splits = before >= 0xd800 && before <= 0xdbff && after >= 0xdc00 && after <= 0xdfff;
+  const splits = isHighHalf(text.charCodeAt(bounded - 1)) && isLowHalf(text.charCodeAt(bounded));
   return splits ? bounded - 1 : bounded;
 }
 ```
@@ -94,8 +101,8 @@ path, where it would otherwise run on every keystroke.
 
 ## Defer the paint, not the write, while an IME is open
 
-Assigning to the field while an IME is open discards what it is holding,
-which costs a reader typing Japanese, Chinese, or Korean the word they were
+Assigning to the field while an IME is open discards its unfinished input,
+which costs a user typing Japanese, Chinese, or Korean the word they were
 in the middle of. So track `compositionstart` / `compositionend` and skip
 the paint in between.
 
@@ -113,7 +120,7 @@ field.addEventListener('compositionend', () => {
   painted = field.value;
   report.update(painted);
   // What arrived while the composition was open is older than what the
-  // reader just committed, so paint the container's own value, which
+  // user just committed, so paint the container's own value, which
   // carries both.
   if (missed) {
     missed = false;
@@ -123,9 +130,9 @@ field.addEventListener('compositionend', () => {
 });
 ```
 
-Holding the incoming value and applying it at `compositionend` is the
+Keeping the incoming value aside and applying it at `compositionend` is the
 version that looks right and loses data: that value predates the
-composition, so painting it discards the word the reader just committed.
+composition, so painting it discards the word the user just committed.
 Deferring the write instead has the same shape of bug one layer down, since
 the field's value then has no record of the peer's edit and `update` diffs
 it back out.
@@ -152,7 +159,7 @@ revision pattern:
 | 300 KB | 4.09 |
 
 One paragraph, one description, or one report is far inside a frame at
-typing speed. A field holding a book is not, and an app whose document
+typing speed. A field containing a book is not, and an app whose document
 grows that large wants its prose split across containers, one per section,
 so an edit compares against a section rather than the book.
 
@@ -167,9 +174,9 @@ per-session, since a snapshot carries the history.
 
 A text container is a top-level root, and no nested-text surface exists, so
 per-element prose that merges costs one root per element. Loro prices a
-container against how many the document holds, so that does not stay flat
-the way the record store does, where paging holds container count down past
-`UNPAGED_MAX_RECORDS`. Creating one text root per element against the same
+container against how many the document contains, so that does not stay flat
+the way the record store does, where paging keeps container count down once
+a map contains many records. Creating one text root per element against the same
 elements written as records:
 
 | elements | a root each | as records | roots heap | records heap |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@brass-build/client",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "Client SDK for Brass",
   "type": "module",
   "main": "./dist/index.js",
@@ -39,8 +39,11 @@
     "prepublishOnly": "tsc -b --force"
   },
   "dependencies": {
+    "apache-arrow": "^21.2.0",
     "fflate": "^0.8.3",
-    "loro-crdt": "^1.13.0"
+    "flatbuffers": "^25.1.24",
+    "fzstd": "^0.1.1",
+    "loro-crdt": "1.13.9"
   },
   "devDependencies": {
     "typescript": "~6.0.0"

package/src/acting-organization.ts

@@ -154,18 +154,12 @@ export async function resolveActingOrganization(
   options: { ask?: boolean } = {},
 ): Promise<string | null> {
   const fromDocument = await deps.activeDocumentOrganizationId();
-  if (fromDocument) {
-    // Recorded, not merely returned. This is where the app is working, so it
-    // is what the next act spends once the document closes; without it a
-    // reader who opens a document, closes it and creates another is asked
-    // where to put the second one, having just worked in the answer. It carries no name (the
-    // document named an id) and does not reach the tab's slot: a document
-    // can live in an organization the reader reaches through a shared
-    // project and is not a member of, which is a place to act from while it
-    // is open rather than a choice to carry.
-    deps.remember(fromDocument, '', false);
-    return fromDocument;
-  }
+  // Answered, not recorded. A document can live in an organization the
+  // reader reaches through a shared project and is not a member of, which is
+  // a place to act from while it is open and not one to keep once it closes.
+  // The caller records a document's organization only after the server
+  // confirms membership and the install.
+  if (fromDocument) return fromDocument;
   const cached = deps.cachedResolution();
   if (cached) return cached;