@brass-build/client 0.2.0 → 0.4.0

package/src/internal.ts

@@ -21,4 +21,14 @@ export {
   type TokenSet,
 } from './auth-flow.js';
 export { decodeIdToken } from './jwt.js';
+export {
+  readDocumentContents,
+  type DocumentContents,
+} from './document-contents.js';
+export {
+  fetchWithRetry,
+  RETRY_READ,
+  type RetryOptions,
+  type RetryPolicy,
+} from './fetch-retry.js';
 export { BRASS_INIT_ARG_KEYS, type BrassInitArgKey } from './init-keys.js';

package/src/mutate-batching.ts

@@ -17,8 +17,8 @@
 //
 // The budget answers to STORAGE, not to the socket: an op past the frame cap
 // takes the HTTP write, which carries about 190x a frame. What storage meters
-// is op COUNT (a seq allocation and HEAD update on the document's one
-// partition, plus an entry in the join's tail budget). Measured on a
+// is op COUNT: each op costs the same bookkeeping whatever its size, and
+// takes a place in the join's tail budget. Measured on a
 // 500,000-element write, 48 KB produces 526 ops and 512 KB produces 158, past
 // which the budget stops binding for that shape, while encode time stays flat
 // throughout: a smaller budget spends op count and buys nothing.

package/src/open-document.ts

@@ -11,12 +11,14 @@ import {
   type DocumentOptions,
   type DocumentWorkStatus,
   type DocumentDriveStatus,
+  type DrivePublishTarget,
   type DocumentDriveTrackingState,
   type DriveMirrorDirection,
   type HostedUiProvider,
   type ReadOnlyReason,
   type ResyncPushOutcome,
 } from './documents.js';
+import { ensureWasmReady } from './wasm-runtime.js';
 import { createPresenceController } from './presence.js';
 import type { WsTopicCallback } from './ws-client.js';
 import { applyAppAssertionHeader, applyClientVersionHeader } from './api-headers.js';
@@ -214,6 +216,33 @@ export interface DocumentSnapshotResponse {
   // Drive provenance + tracking state, present only on drive-linked docs.
   // Seeds `doc.driveStatus`; live changes stream in via `doc_drive_status`.
   drive?: DocumentDriveSummaryWire;
+  // Whether this document's export runs in the app this client acts as.
+  // Server-answered per caller, so it says only that this app is the one to
+  // serialize, never which app is if it is not. Absent for a caller carrying
+  // no app assertion.
+  calling_app_exports?: boolean;
+  // The version of the document's current picture, absent when it has none.
+  // Only the version is read (a picture behind the head is what makes this
+  // open seed one), so the shape is deliberately narrow: the full wire record
+  // is the thumbnail routes' surface, not the join's.
+  thumbnail?: { version?: number } | null;
+  // Where a document that mirrors nothing can be published, present only
+  // while it mirrors nothing and its project is linked to a drive that
+  // takes a new file. The hosted drive badge offers the publish off this.
+  drive_publish_target?: DrivePublishTargetWire;
+}
+
+// Wire shape of a publish target on the join response. Snake_case,
+// mirroring the server's `DocumentDrivePublishTarget` (CONTRACT.md "Where
+// a document with no drive item can publish").
+export interface DrivePublishTargetWire {
+  drive_type?: unknown;
+  drive_name?: unknown;
+  container_name?: unknown;
+  detail?: unknown;
+  source_unreadable?: unknown;
+  publishing?: unknown;
+  publish_failed?: unknown;
 }
 
 // Wire shape of the `drive` block carried on the join response and the
@@ -237,6 +266,7 @@ export interface DocumentDriveSummaryWire {
   // Optional: a frame from an older server omits it, treated as not
   // publishing (the `canPush` affordance then behaves as before).
   publishing?: boolean;
+  source_unreadable?: string;
 }
 
 // Wire-protocol-pinned response shape from
@@ -343,10 +373,10 @@ export interface OpenDocumentFactoryOptions {
   // Backs the Document's built-in 'history' / 'manage' / 'share'
   // commands. When absent (tests), those commands render disabled.
   hostedUiProvider?: HostedUiProvider;
-  // The organization this page was launched from (`?brass_org=`), read
-  // through a getter because `init` resolves it after the factory's
-  // options are written. See `createDocumentId`.
-  launchOrganizationId?: () => string | null;
+  // The organization this app is already acting in, read through a getter
+  // because `init` resolves it after the factory's options are written and
+  // because it moves as the reader works. See `createDocumentId`.
+  preferredOrganizationId?: () => string | null;
   // Who is signed in, as the park cache's ownership stamp (see
   // `ParkedDocEntry.identity`). Read at park and at take, so a Document only
   // ever comes back to the person it was opened for. Absent (tests, the
@@ -620,6 +650,21 @@ interface DocDriveStatusFrame {
   drive: DocumentDriveSummaryWire;
 }
 
+// Server-pushed publish state for a document that mirrors nothing on a drive
+// yet. Wire shape pinned in CONTRACT.md "Server-pushed `doc_drive_publish`".
+// The first publish creates the artifact, so until it lands the document has
+// no drive summary and `doc_drive_status` carries nothing about the push it
+// started.
+interface DocDrivePublishFrame {
+  type: 'doc_drive_publish';
+  topic: string;
+  publish: {
+    publishing?: unknown;
+    failed?: unknown;
+    detail?: unknown;
+  };
+}
+
 // Server-pushed frame fired when the platform discards ops it cannot apply.
 // The prompt half of the durability
 // handshake: the SDK re-checks durability against ground truth now rather
@@ -651,7 +696,9 @@ function toDriveStatus(wire: DocumentDriveSummaryWire): DocumentDriveStatus {
     // update) must not be treated as unbroken and offered a push the server
     // would reject. Require an explicit `false` to enable, and an explicit
     // `true` to flag broken. Behaviour is unchanged for today's frames, which
-    // always carry the boolean.
+    // always carry the boolean. Whether the file is written server-side or
+    // from the app's own serializer is a REQUEST SHAPE the push path resolves
+    // for itself, so it says nothing about whether this document can publish.
     canPush:
       wire.broken === false &&
       mirrorDirection === 'two_way' &&
@@ -666,6 +713,31 @@ function toDriveStatus(wire: DocumentDriveSummaryWire): DocumentDriveStatus {
     itemName: wire.item_name,
     itemUrl: wire.item_url,
     publishing: wire.publishing === true,
+    // Spread rather than assigned, because `exactOptionalPropertyTypes`
+    // separates an absent optional field from one holding `undefined`.
+    ...(wire.source_unreadable !== undefined
+      ? { sourceUnreadable: wire.source_unreadable }
+      : {}),
+  };
+}
+
+// Map the wire target to the public shape, dropping one that does not carry
+// what a publish needs. A malformed target is skipped rather than failing
+// the open: the document is readable whatever its publish offer says.
+function toPublishTarget(
+  wire: DrivePublishTargetWire | undefined,
+): DrivePublishTarget | null {
+  if (typeof wire !== 'object' || wire === null) return null;
+  const driveName = wire.drive_name;
+  if (typeof driveName !== 'string' || driveName === '') return null;
+  return {
+    driveName,
+    driveType: typeof wire.drive_type === 'string' ? wire.drive_type : '',
+    containerName:
+      typeof wire.container_name === 'string' ? wire.container_name : '',
+    detail: typeof wire.detail === 'string' ? wire.detail : '',
+    publishing: wire.publishing === true,
+    publishFailed: wire.publish_failed === true,
   };
 }
 
@@ -969,6 +1041,15 @@ function isDocMetaFrame(frame: unknown): frame is DocMetaFrame {
   );
 }
 
+function isDocDrivePublishFrame(frame: unknown): frame is DocDrivePublishFrame {
+  if (typeof frame !== 'object' || frame === null) return false;
+  const f = frame as Record<string, unknown>;
+  if (f.type !== 'doc_drive_publish' || typeof f.topic !== 'string') {
+    return false;
+  }
+  return typeof f.publish === 'object' && f.publish !== null;
+}
+
 function isDocDriveStatusFrame(frame: unknown): frame is DocDriveStatusFrame {
   if (typeof frame !== 'object' || frame === null) return false;
   const f = frame as Record<string, unknown>;
@@ -1112,16 +1193,16 @@ export function createOpenDocument(
     // open on something that clears on its own.
     //
     // Longer than the default handful of attempts because of what a 503 means
-    // on this route: the document is intact and its storage is busy. Every op
-    // row a document has shares one partition, so the document most likely to
-    // answer 503 is one that was just written hard, which is exactly the
+    // on this route: the document is intact and its storage is busy. A
+    // document's own writes contend with each other, so the one most likely
+    // to answer 503 is one that was just written hard, which is exactly the
     // moment a person reloads to see their work. That pressure clears over
     // tens of seconds, not the one second the default budget spans, and the
     // cost of giving up early is telling someone their document will not open
     // when waiting would have opened it.
     //
     // A thrown request gets a short budget of its own: it never reached the
-    // API, so the busy partition is not what is wrong, and a blocked origin
+    // API, so busy storage is not what is wrong, and a blocked origin
     // or a host that does not resolve answers the seventh attempt as it
     // answered the first, with the reader watching a loading surface
     // throughout.
@@ -1264,7 +1345,7 @@ export function createOpenDocument(
   // piped through `open` to materialise the editable Document.
   // What the app hears when an op the socket could not carry also failed
   // over HTTP. The server's message is preferred where it has one, since it
-  // names the actual refusal (too large for the durable row, a revoked
+  // names the actual refusal (too large to store inline, a revoked
   // role); the status-shaped fallbacks cover a response that carries none.
   function opWriteFailureMessage(status: number, parsed: unknown): string {
     const serverMessage = (parsed as { error?: unknown } | undefined)?.error;
@@ -1276,12 +1357,12 @@ export function createOpenDocument(
     return `This change could not be saved (${status}).`;
   }
 
-  // Write one op over HTTP. The socket carries an op only up to API
-  // Gateway's message cap; past it the message is not delivered and the
-  // connection is closed, so `wireDocTransport` sends the large ones here.
+  // Write one op over HTTP. The socket carries an op only up to its own
+  // message cap; past it the message is not delivered and the connection is
+  // closed, so `wireDocTransport` sends the large ones here.
   // Not retried on a transient failure: the caller holds the op in its
   // outstanding tracker and re-asserts it, and a blind replay would write a
-  // second durable row for the same edit.
+  // second stored copy of the same edit.
   // Mint a presigned PUT and upload the blob to it, returning the staging
   // key the op write names. The PUT carries no Brass headers: the URL is
   // signed, and an extra header falls outside that signature.
@@ -1353,9 +1434,9 @@ export function createOpenDocument(
     };
     applyClientVersionHeader(headers);
     await applyAppAssertionHeader(headers, opts.getAppAssertion);
-    // Past what a durable row holds, the blob goes to storage directly
-    // and the write names the staged object, so a multi-megabyte op
-    // never travels through a request body.
+    // Past the size an op can carry inline, the blob is uploaded first and
+    // the write names what was staged, so a multi-megabyte op never travels
+    // through a request body.
     let stagedKey: string | undefined;
     if (opBlobNeedsStaging(opBlobB64)) {
       stagedKey = await stageOpBlob(docId, opBlobB64, token);
@@ -1445,32 +1526,36 @@ export function createOpenDocument(
   // a needed destination / organization before showing a loading state; any
   // other non-2xx throws.
   //
-  // A create that names no placement of its own inherits the organization
-  // the page was launched from, so a member of several organizations who
-  // opened this app from one of them is not asked to name a destination
-  // they already chose. An explicit `siblingOf` / `destination` outranks it:
-  // placing a document beside the open one is the more specific answer.
+  // A create that names no placement of its own lands in the organization the
+  // app is already acting in: the one a launch named, the one a document the
+  // reader just closed lives in, or the one they chose in the account menu's
+  // switch. Without it a member of several organizations is asked to name a
+  // destination they have already answered, once per create. An explicit
+  // `siblingOf` / `destination` outranks it: placing a document beside the
+  // open one is the more specific answer.
   const createDocumentId = async (
     args: CreateDocumentArgs,
   ): Promise<CreateDocumentResult> => {
-    const launchOrganizationId =
+    const preferred =
       args.siblingOf === undefined && args.destination === undefined
-        ? (opts.launchOrganizationId?.() ?? null)
+        ? (opts.preferredOrganizationId?.() ?? null)
         : null;
-    if (launchOrganizationId === null) return postAndClassify(args);
+    if (preferred === null) return postAndClassify(args);
     try {
       return await postAndClassify({
         ...args,
-        destination: { organization_id: launchOrganizationId },
+        destination: { organization_id: preferred },
       });
     } catch (err) {
-      // The launch organization is a hint carried on a URL, so it can name
-      // an organization the person has since left, which the server answers
-      // with a plain 404. Drop the hint and let the server resolve the
-      // destination on its own, which routes a multi-organization caller to
-      // the picker. A coded rejection (`app_not_installed`) belongs to the
-      // caller's own consent flow and passes through untouched, as does the
-      // 404 for an organization that exists but denies the app.
+      // Every source of this value is a preference rather than an answer: a
+      // URL parameter, a document open in an organization reached through a
+      // shared project, a choice made before the person left. Each can name
+      // an organization the caller no longer has, which the server answers
+      // with a plain 404. Drop it and let the server resolve the destination
+      // on its own, which routes a multi-organization caller to the picker. A
+      // coded rejection (`app_not_installed`) belongs to the caller's own
+      // consent flow and passes through untouched, as does the 404 for an
+      // organization that exists but denies the app.
       if (err instanceof BrassError && err.status === 404 && !err.code) {
         return postAndClassify(args);
       }
@@ -1712,6 +1797,7 @@ export function createOpenDocument(
         resyncFromSnapshot,
         skipPresence: true,
         parkable: false,
+        capacityReloadsDocument: false,
       });
     }
     return doc;
@@ -1738,10 +1824,19 @@ export function createOpenDocument(
     // (a stub opened mid-hydration returns `snapshot: null` + a `pending`
     // status).
     if (parsed.status !== undefined) doc._emitStatus(parsed.status);
+    // Whether this app is the one to serialize the document, which is what
+    // decides whether a push carries bytes. Answered by the server for the
+    // caller's own app and only on the join, since the fanout frame is one
+    // payload for every subscriber and has no caller to answer for.
+    doc._setExportRunsHere(parsed.calling_app_exports === true);
     // Seed `doc.driveStatus` from the join before the first
     // `doc_drive_status` frame.
     if (parsed.drive !== undefined) {
       doc._emitDriveStatus(toDriveStatus(parsed.drive));
+    } else {
+      // Only for a document that mirrors nothing: a mirror publishes through
+      // its link, and `_emitDriveStatus` clears any targets anyway.
+      doc._setPublishTarget(toPublishTarget(parsed.drive_publish_target));
     }
     // Highest seq seen; later `doc_op` / `op_ack` frames advance it. Kept in
     // a closure, not on the Document: it is a transport concern, not CRDT
@@ -2161,6 +2256,7 @@ export function createOpenDocument(
         await uploader(doc, image, width, height);
       });
     }
+    doc._setThumbnailVersion(parsed.thumbnail?.version ?? null);
     if (opts.checkpointCreator) {
       const creator = opts.checkpointCreator;
       doc.setCheckpointCreator(() => creator(doc));
@@ -2217,6 +2313,11 @@ export function createOpenDocument(
       }
     }
     if (opts.reportError) doc.setErrorReporter(opts.reportError);
+    // No socket on a document the caller can write to: the write path reaches
+    // no server, so the document reports the first attempt rather than
+    // discarding it. Outside tests this is `wsBaseUrl` left unset, which
+    // naming any other base URL does.
+    if (!opts.wsClient && !doc.readOnly) doc.markTransportUnavailable();
     return doc;
   }
 
@@ -2504,7 +2605,12 @@ export function createOpenDocument(
     canEdit: boolean,
   ): void {
     const wsClient = opts.wsClient;
-    if (!wsClient) return;
+    if (!wsClient) {
+      // No socket: a write would change local state and reach no server, so
+      // the document reports the first one instead of discarding it quietly.
+      if (canEdit) doc.markTransportUnavailable();
+      return;
+    }
     const topic = `doc:${docId}:${lineId}`;
 
     // Ops on the socket awaiting an answer, keyed by `client_op_id`. An
@@ -2842,11 +2948,12 @@ export function createOpenDocument(
   // create + obtain the doc_id, then `open(docId)`); they aren't fused
   // because the create response is metadata-only and the open path already
   // handles the empty-snapshot case via `Document.create()`. This is the
-  // low-level path (`Brass.createDocument`): the server places the doc in
-  // the caller's single organization; a caller with none is routed to the
-  // hosted acquire-organization surface and the create retries; a multi-org
-  // caller rejects with a 409 (no hosted picker here, that is the session's
-  // `create()`).
+  // low-level path (`Brass.createDocument`): the doc lands in the
+  // organization the app is acting in, and otherwise in the caller's single
+  // organization; a caller with none is routed to the hosted
+  // acquire-organization surface and the create retries; a multi-org caller
+  // whose app is acting nowhere rejects with a 409 (no hosted picker here,
+  // that is the session's `create()`).
   const create: CreateDocumentFn = async (options) => {
     const args: CreateDocumentArgs = { name: options?.name ?? 'Untitled' };
     if (options?.app_metadata !== undefined) args.app_metadata = options.app_metadata;
@@ -2941,6 +3048,13 @@ interface WireDocTransportArgs {
   // by the parent Document (closed on parent close), so it bypasses the
   // park cache and `close()` tears down immediately.
   parkable?: boolean;
+  // True for the session-owned top-level document: an unhealable capacity
+  // refusal tells the user and reloads, because the session reopens the id
+  // and rebinds the app to the platform's copy. False for a stream line,
+  // which has no such owner and is only one part of a document: it marks
+  // itself read-only at capacity and surfaces `stream.atCapacity` instead
+  // of alerting the reader and reloading a document the stream is part of.
+  capacityReloadsDocument?: boolean;
   // The branch the caller REQUESTED (`options.branch`), undefined for a
   // default-branch open. Distinct from `branchId`, which is the branch the
   // server RESOLVED. The park cache keys on this (symmetric with
@@ -3719,6 +3833,18 @@ function wireDocTransport(args: WireDocTransportArgs): void {
       clearTimeout(gapTimer);
       gapTimer = null;
     }
+    // A stream line reaches this only at capacity, and it has no owner to
+    // reopen it: the session reopens the top-level id, but a stream is one
+    // part of a document nothing reloads on its behalf. So it stops the
+    // divergence (above) and marks itself read-only at capacity, which
+    // `stream.readOnly` / `stream.atCapacity` already surface to the app,
+    // rather than alerting the reader and reloading a document it is part
+    // of. The diverged edit stays visible until the app reopens the stream;
+    // it reached no other reader, so nothing is lost by leaving it.
+    if (args.capacityReloadsDocument === false) {
+      args.doc._markReadOnly('capacity');
+      return;
+    }
     args.doc._markReadOnly('unsaved');
     // The user is told by the SDK, not by each app, because an app that
     // renders nothing is exactly the case this has to cover: a document that
@@ -4300,6 +4426,15 @@ function wireDocTransport(args: WireDocTransportArgs): void {
         args.doc._emitDriveStatus(toDriveStatus(frame.drive));
         return;
       }
+      if (isDocDrivePublishFrame(frame)) {
+        args.doc._emitPublishState({
+          publishing: frame.publish.publishing === true,
+          failed: frame.publish.failed === true,
+          detail:
+            typeof frame.publish.detail === 'string' ? frame.publish.detail : null,
+        });
+        return;
+      }
       if (isDocOpsDroppedFrame(frame)) {
         // Prompt durability re-check: the discard sealed a new snapshot, so
         // re-fetch the moved frontier and run the handshake now instead of at
@@ -4663,6 +4798,11 @@ async function materialise(
   documentOptions?: DocumentOptions,
   onSnapshotProgress?: (loaded: number, total: number | null) => void,
 ): Promise<OpenedDocument> {
+  // Constructing the document is the first thing in this package that runs the
+  // WASM, and `Brass.init` only starts the fetch, so this is where it is
+  // waited on. Usually it resolved during the auth round-trip and this costs
+  // nothing.
+  await ensureWasmReady();
   // Stamp the server-minted doc_id onto the Document (via DocumentOptions, so
   // it threads through the LoroDoc constructor without changing the static
   // factory signatures) so callers can read `doc.id` to correlate.

package/src/presence.ts

@@ -78,6 +78,12 @@ export interface PresenceState {
   /** Entity ids the user has selected. Use to highlight remote
    * selections so collaborators see what each other is working on. */
   selection?: string[];
+  /** Where the user's caret sits in a text container. `key` names the
+   * container (`doc.text(key)`), and both offsets count UTF-16 code
+   * units into its value: `anchor` where the selection began, `head`
+   * where it is now, equal for a plain caret. Use it to draw remote
+   * carets in prose, the way `selection` highlights picked entities. */
+  textCaret?: { key: string; anchor: number; head: number };
 }
 
 // A live participant on a presence topic. Keyed on `connectionId` (one

package/src/record-paging.ts

@@ -232,16 +232,15 @@ const TOMBSTONE_PREFIX = `${RESERVED_KEY_PREFIX}x:`;
 
 /** Pack one stored value into a page triple. A `null` tag is what says the
  *  body IS the record: an app's map holds whatever the app assigned, which has
- *  no tag to split off. A codec's records arrive already split, and a codec
- *  tag is a string, so the two forms cannot be confused however a codec names
- *  its records. */
+ *  no tag to split off. A typed record arrives already split, and its tag is a
+ *  string, so the two forms cannot be confused whatever the tag says. */
 export function packWholeValue<B>(key: string, value: B): PackedRecord<B> {
   return [key, null, value];
 }
 
 /** Re-pack `value` in the same triple shape `packed` already uses, so a page
- *  rewritten in place keeps the form its readers expect: a codec's records
- *  stay a tag beside a body, and an app's stay one whole value. A streaming
+ *  rewritten in place keeps the form its readers expect: a typed record stays
+ *  a tag beside a body, and an app's stays one whole value. A streaming
  *  read visits a page's triples without unpacking them, so a rewrite that
  *  changed the shape would hand it the wrong half of the record. */
 export function repackRecord(
@@ -259,7 +258,7 @@ export function repackRecord(
 }
 
 /** The stored value a page triple carries: the value itself for a whole-value
- *  record, else the `{ type, params }` pair a codec split it into. */
+ *  record, else the `{ type, params }` pair a typed one was split into. */
 export function unpackRecord(packed: PackedRecord<unknown>): unknown {
   if (packed[1] === null) return packed[2];
   return { [TAG_FIELD]: packed[1], [BODY_FIELD]: packed[2] };
@@ -269,12 +268,12 @@ export function unpackRecord(packed: PackedRecord<unknown>): unknown {
  *  separately, or null when the triple packs a whole value that is not a
  *  record.
  *
- *  A page holds both forms: a codec packs a record it has already split into a
- *  tag and a body, and a map an app writes packs whatever the app assigned as
- *  one whole value. Both forms occur in ONE store, because an app's bulk add
- *  to a codec's record map seals its own pages, so a reader that took
- *  `packed[1]` for the tag would report every record those pages hold as
- *  having no type at all. */
+ *  A page holds both forms: a typed record is packed as the tag and body it
+ *  was already split into, and a map an app writes packs whatever the app
+ *  assigned as one whole value. Both forms occur in ONE store, because an
+ *  app's bulk add to a store of typed records seals its own pages, so a reader
+ *  that took `packed[1]` for the tag would report every record those pages
+ *  hold as having no type at all. */
 export function unpackRecordPair(
   packed: PackedRecord<unknown>,
 ): { tag: string; body: unknown } | null {
@@ -454,7 +453,7 @@ const WIDTH_SAMPLE = 256;
 /** Mean JSON bytes of a record body, over a stride sample of at most
  *  `WIDTH_SAMPLE` records, which is what `recordsPerPage` sizes a page
  *  against. `bodyOf` returns the value the caller will pack as the triple's
- *  body: a codec's records carry a tag beside a body, and an app's map packs
+ *  body: a typed record carries a tag beside a body, and an app's map packs
  *  its whole stored value (`packWholeValue`), so each caller weighs the bytes
  *  its own pages will hold.
  *
@@ -673,7 +672,7 @@ export function applyRecordPatches(
  * value and as the `(tag, body)` pair split out of it, and return all three
  * after the fold.
  *
- * A patch names the record's own fields, which for a codec record are
+ * A patch names the record's own fields, which for a typed record are
  * `type` and `params` together, so a reader that walks tag and body
  * separately has to re-split the result. Both readers of a paged store
  * (the flattening one and the streaming one) resolve patches through this

package/src/serializer.ts

@@ -22,9 +22,9 @@ export interface StoredList<T = unknown> extends ListHandle<T> {
 /**
  * The document as a serializer sees it: the same containers, readable whole.
  *
- * A `Document` satisfies this, which is what keeps a built-in codec and a
- * third-party one on one surface. The difference between them is where they
- * run, not what they are allowed to reach.
+ * A `Document` satisfies this, which is what keeps a serializer the platform
+ * ships and one an app registers on one surface. The difference between them
+ * is where they run, not what they are allowed to reach.
  */
 export interface StoredDocument {
   readonly id: string | null;