@brass-build/client 0.1.0 → 0.2.0

package/src/embed-protocol.ts

@@ -0,0 +1,25 @@
+// The `__brass_embed` postMessage envelope, shared by the SDK's three bridge
+// endpoints: the hosted-UI launcher (`hosted-ui.ts`) and the version bar
+// (`version-bar.ts`), where the SDK is the host, and the export guest
+// (`export-guest.ts`), where the SDK is the iframe.
+//
+// Both sides drop any `message` whose `data[EMBED_ENVELOPE]` is not a version
+// they speak, so unrelated postMessage traffic never reaches a handshake.
+//
+// The SDK's half of every bridge freezes into each app's published bundle,
+// so it speaks exactly the version it was built with: it announces this
+// version on first contact and accepts only this version inbound. Staying
+// compatible across a bump is entirely the central (dashboard-served) side's
+// job: that side accepts every version it has ever shipped and replies at the
+// one the frozen counterpart announced. Two rules follow, and together they
+// are the bridge's compatibility invariant:
+//
+//   - the central side never drops a version while a published SDK still
+//     announces it, so an app pinned to an older client keeps working;
+//   - this constant rises only after a dashboard build that accepts the new
+//     version is deployed, because the SDK's first message (the launcher's
+//     `init`, the guest's `ready`) is what the central side negotiates from.
+//     A bump that lands first is dropped by the deployed dashboard, and every
+//     hosted dialog in an app carrying it waits out its timeout.
+export const EMBED_ENVELOPE = '__brass_embed';
+export const EMBED_PROTOCOL_VERSION = 1;

package/src/emitter.ts

@@ -113,7 +113,14 @@ export function createEmitter<T>(opts: EmitterOptions<T> = {}): Emitter<T> {
         retained = value;
         hasValue = true;
       }
-      for (const cb of listeners) dispatch(cb, value);
+      // Over a snapshot, because a listener may detach or clear the rest
+      // while the fanout is running: the session's own `onGone` handler
+      // closes the document, which clears its listener set, and a `Set`
+      // never visits an entry removed before its turn. Iterating live there
+      // silently drops every listener registered after the session's, which
+      // is all of the app's.
+      const receiving = Array.from(listeners);
+      for (const cb of receiving) dispatch(cb, value);
       if (oneShot) listeners.clear();
     },
     clear() {

package/src/export-guest.ts

@@ -15,10 +15,8 @@
 import { Document } from './documents.js';
 import type { DocumentStreamInfo } from './documents-namespace.js';
 import type { StreamRuntime } from './document-streams.js';
-import type { DocumentSerializer } from './serializer.js';
-
-const ENVELOPE = '__brass_embed';
-const PROTOCOL_VERSION = 1;
+import type { DocumentSerializer, StoredDocument } from './serializer.js';
+import { EMBED_ENVELOPE, EMBED_PROTOCOL_VERSION } from './embed-protocol.js';
 
 // The URL flag Brass appends when it frames an app purely to serialize.
 // A normal app load never carries it, so a real user visit is untouched.
@@ -102,7 +100,7 @@ export function startExportGuest(): ExportGuestController {
       }, STREAM_REQUEST_TIMEOUT_MS);
       pendingStreamFetches.set(requestId, { resolve, reject, timer });
       window.parent.postMessage(
-        { [ENVELOPE]: PROTOCOL_VERSION, type, requestId, ...extra },
+        { [EMBED_ENVELOPE]: EMBED_PROTOCOL_VERSION, type, requestId, ...extra },
         hostOrigin,
       );
     });
@@ -145,7 +143,7 @@ export function startExportGuest(): ExportGuestController {
       | { ok: false; code: string; message: string },
   ): void {
     window.parent.postMessage(
-      { [ENVELOPE]: PROTOCOL_VERSION, type: 'export-result', requestId, ...outcome },
+      { [EMBED_ENVELOPE]: EMBED_PROTOCOL_VERSION, type: 'export-result', requestId, ...outcome },
       hostOrigin,
     );
   }
@@ -168,7 +166,10 @@ export function startExportGuest(): ExportGuestController {
         : Document.create(identity);
       for (const op of tailOps) doc.applyRemoteOp(op);
       doc.setStreamRuntime(makeStreamRuntime(hostOrigin));
-      const bytes = await serializer(doc);
+      // A serializer runs detached, with no subscription to have been fed by,
+      // and it needs the document once, so it is handed the containers whole
+      // (`StoredDocument`) rather than the fed surface an app holds.
+      const bytes = await serializer(doc as StoredDocument & Document);
       reply(hostOrigin, requestId, { ok: true, bytes });
     } catch (err) {
       reply(hostOrigin, requestId, {
@@ -180,8 +181,13 @@ export function startExportGuest(): ExportGuestController {
   }
 
   function onMessage(event: MessageEvent): void {
+    // Source pinning, the counterpart of the origin pins below and of the
+    // one the host side applies: `window.parent` is the framer this guest
+    // replies to, so a message from any other window is not part of this
+    // exchange whatever origin it claims.
+    if (event.source !== window.parent) return;
     const data = event.data as Record<string, unknown> | null;
-    if (!data || data[ENVELOPE] !== PROTOCOL_VERSION) return;
+    if (!data || data[EMBED_ENVELOPE] !== EMBED_PROTOCOL_VERSION) return;
 
     // A reply to a proxied stream fetch. Accept only from the pinned framer
     // origin (set once the export request arrives), so a second frame cannot
@@ -262,7 +268,7 @@ export function startExportGuest(): ExportGuestController {
   window.addEventListener('message', onMessage);
   // Announce readiness. Posted with `'*'` because the host origin is not
   // known until its first message arrives; the ping carries no data.
-  window.parent.postMessage({ [ENVELOPE]: PROTOCOL_VERSION, type: 'ready' }, '*');
+  window.parent.postMessage({ [EMBED_ENVELOPE]: EMBED_PROTOCOL_VERSION, type: 'ready' }, '*');
 
   return {
     setSerializer(next: DocumentSerializer): void {

package/src/fetch-deadline.ts

@@ -0,0 +1,119 @@
+// A deadline for a request whose caller has no other way to stop waiting.
+//
+// `fetch` has no timeout of its own, so a request that draws no answer stays
+// pending for as long as the page is open. On the op-write path that pins the
+// op's entry in the outstanding tracker, which holds `doc.savingCount` above
+// zero, which is what an app renders as "Saving...". The reader is then shown
+// a save in progress that nothing will ever resolve, and no error reaches
+// `Brass.onError` because nothing failed.
+//
+// The deadline covers reading the body as well as getting a response, because
+// `fetch` resolves as soon as the headers land: a server that answers and then
+// stalls mid-body is the same hang, and clearing the timer on the response
+// would leave exactly the case this exists for uncovered. The helper therefore
+// reads the body itself rather than handing back a `Response` whose consumption
+// nothing bounds.
+//
+// An abort is deliberately reported as a request that drew no answer at all
+// (status `null`), because that is what it is: the write may or may not have
+// reached the handler. Callers price that the same way they price a network
+// throw.
+
+// How long a request that carries no meaningful body may go unanswered.
+//
+// The value matches the WebSocket transport's forced-resend ceiling, because
+// it answers the same question about the same op: whether a request still
+// outstanding this long after it went out is coming back. It sits well above
+// any latency a working connection produces.
+//
+// What a false positive costs is bounded. Staging is replayed, which writes
+// nothing durable until the op write names the key. The op write itself is
+// terminal for that op, which arms the durability handshake, and the
+// handshake pushes whatever the durable frontier is actually missing rather
+// than replaying the op blindly.
+export const OP_WRITE_TIMEOUT_MS = 60_000;
+
+// The uplink an upload is assumed to manage in the worst case, in bytes per
+// millisecond (16 KB/s). A request carrying megabytes is not unanswered while
+// its body is still going out, so a flat deadline would abort a working upload
+// on a slow mobile connection and fail an op that was about to land. The
+// allowance is generous on purpose: a deadline that fires early on real work is
+// a worse failure than one that takes longer to notice a dead request, since
+// the whole point is to distinguish silence from slowness.
+const ASSUMED_MIN_UPLOAD_BYTES_PER_MS = 16;
+
+/** Deadline for a request whose body is `byteLength` bytes of upload. */
+export function deadlineForUpload(byteLength: number): number {
+  return (
+    OP_WRITE_TIMEOUT_MS +
+    Math.ceil(Math.max(0, byteLength) / ASSUMED_MIN_UPLOAD_BYTES_PER_MS)
+  );
+}
+
+export class FetchDeadlineError extends Error {
+  override name = 'FetchDeadlineError';
+}
+
+export interface DeadlineResponse {
+  ok: boolean;
+  status: number;
+  text: string;
+}
+
+/**
+ * Run a fetch under a deadline covering the response and its body, aborting
+ * the request when it expires.
+ *
+ * The timer is cleared on every exit, so a completed request leaves nothing
+ * pending. An environment whose `fetch` ignores `AbortSignal` still rejects,
+ * because the deadline is raced against the request rather than relying on the
+ * abort landing.
+ */
+export async function fetchWithDeadline(
+  input: string,
+  init: RequestInit,
+  timeoutMs: number,
+): Promise<DeadlineResponse> {
+  const controller = new AbortController();
+  let expired = false;
+  let fire: (() => void) | undefined;
+  const timer = setTimeout(() => {
+    expired = true;
+    controller.abort();
+    fire?.();
+  }, timeoutMs);
+  // A long-lived deadline must not hold a Node process open on its own.
+  (timer as unknown as { unref?: () => void }).unref?.();
+
+  const expiry = new Promise<never>((_resolve, reject) => {
+    fire = () =>
+      reject(
+        new FetchDeadlineError(
+          `The request did not answer within ${Math.round(timeoutMs / 1000)}s.`,
+        ),
+      );
+  });
+
+  try {
+    return await Promise.race([
+      (async (): Promise<DeadlineResponse> => {
+        const response = await fetch(input, {
+          ...init,
+          signal: controller.signal,
+        });
+        const text = await response.text();
+        return { ok: response.ok, status: response.status, text };
+      })(),
+      expiry,
+    ]);
+  } catch (err) {
+    if (expired) {
+      throw new FetchDeadlineError(
+        `The request did not answer within ${Math.round(timeoutMs / 1000)}s.`,
+      );
+    }
+    throw err;
+  } finally {
+    clearTimeout(timer);
+  }
+}

package/src/fetch-retry.ts

@@ -14,11 +14,13 @@
 //
 // - A GET is idempotent, so replaying it is always safe: retry the whole
 //   transient 5xx / 429 set AND a thrown network error (`RETRY_READ`).
-// - A write is NOT idempotent, so only a 503 is safe to replay: the API
-//   gateway returns a 503 BEFORE the request reaches the handler (a transient
-//   throttle / scale-up / deploy-window blip), so the write never ran and
-//   a replay cannot double-apply it. A 502 / 504 / 429 or a network throw
-//   might mean the handler ran, so those stay hard failures (`RETRY_WRITE_503`).
+// - A write is NOT idempotent, so only a 503 is safe to replay, and only on
+//   a route where a 503 means the write did not land: the gateway's own 503
+//   (a transient throttle / scale-up / deploy-window blip) is returned before
+//   the request reaches the handler, and a handler that answers 503 does so
+//   for a write it refused rather than applied. A 502 / 504 / 429 or a network
+//   throw might mean the handler ran, so those stay hard failures
+//   (`RETRY_WRITE_503`).
 // - A 500 is never retried under either policy: an unhandled server error
 //   is usually deterministic, so a replay just doubles the cost without
 //   changing the outcome.
@@ -62,6 +64,9 @@ export interface RetryOptions {
   policy?: RetryPolicy;
   // Total attempts including the first. Default 3 (so up to 2 replays).
   maxAttempts?: number;
+  // Attempts a thrown network error gets, when the policy replays throws.
+  // Defaults to `maxAttempts`.
+  maxNetworkAttempts?: number;
   // Base backoff; attempt N waits ~base * 2^(N-1) with jitter. Default 300.
   baseDelayMs?: number;
   // Invoked before each replay with the 1-based attempt that just failed and
@@ -86,10 +91,12 @@ export async function fetchWithRetry(
 ): Promise<Response> {
   const policy = options.policy ?? RETRY_READ;
   const maxAttempts = options.maxAttempts ?? 3;
+  const maxNetworkAttempts = options.maxNetworkAttempts ?? maxAttempts;
   const baseDelayMs = options.baseDelayMs ?? 300;
   const sleep = options.sleep ?? defaultSleep;
 
   let lastError: unknown;
+  let networkThrows = 0;
   for (let attempt = 1; attempt <= maxAttempts; attempt += 1) {
     let response: Response | undefined;
     try {
@@ -99,6 +106,8 @@ export async function fetchWithRetry(
       // a write policy rethrows it rather than risk a double-apply.
       if (!policy.replayNetworkErrors) throw err;
       lastError = err;
+      networkThrows += 1;
+      if (networkThrows >= maxNetworkAttempts) throw err;
     }
     if (response && !policy.replayStatuses.has(response.status)) {
       return response;

package/src/handle-types.ts

@@ -0,0 +1,303 @@
+// The handle surface's public types, kept apart from the `handles.ts` code
+// that implements them against Loro. Every type the package entry re-exports
+// pulls its declaring module into a consumer's typecheck graph, so declaring
+// them here is what makes the public surface engine-neutral all the way down
+// rather than only in the signatures an app calls.
+// `public-types-engine-free.test.ts` holds that line.
+
+// What changed on a map, the first argument to a map subscriber. Reconcile
+// by it: upsert every entry in `set` (it carries the new value, so reconcile
+// never calls `get`), drop every key in `deleted`. The first fire carries
+// the whole map as `set`, so a subscriber is one loop with no
+// initial-vs-update branch. Each later fire is proportional to what the change
+// wrote, never to the map's size.
+export interface Change<T = unknown> {
+  // Entries the change wrote, by key, with the value the map now holds for
+  // them. `set` names what a change WROTE, which is a wider answer than what
+  // differs: assigning a record the value it already holds names it, and above
+  // the size at which a large map stores its records in groups, a mutation
+  // that replaces every record of a group names every record in it. An edit of
+  // one record names that record at every size. So reconcile by value and the
+  // two readings agree; to attribute a change instead (highlight a peer's
+  // edit, mark a record dirty, recompute per record), compare the value
+  // against the one you hold and act on the entries that moved.
+  readonly set: ReadonlyMap<string, T>;
+  // Keys removed from the map.
+  readonly deleted: readonly string[];
+  // Live keys in order, present ONLY on an ordered-map fire whose order
+  // changed. Re-sequence the views you hold to it; absent on a plain map and
+  // on an order-preserving field edit, keeping re-sequencing off the
+  // per-keystroke path.
+  readonly order?: readonly string[];
+}
+
+// What produced a change: read-only metadata, the optional SECOND argument
+// to a map subscriber. A render never needs it (the projection reconciles by
+// value regardless of cause, which makes local / remote / undo one path);
+// read it only to attribute a change, e.g. highlight a peer's edit
+// (`source === 'remote'`). It says who wrote the change, and `set` says what
+// the change wrote, so an attributing subscriber pairs it with the value
+// comparison `set` describes.
+//
+// A move through version history is not among them: it swaps the whole
+// container rather than writing into it, so it reaches a subscriber as a
+// whole-container fire with no origin. `doc.subscribe` reports that move as
+// `{ kind: 'history' }`, carrying the version it landed on.
+export type ChangeSource = 'local' | 'remote' | 'undo' | 'redo';
+export interface ChangeOrigin {
+  readonly source: ChangeSource;
+}
+
+// A map subscriber. Fires once on registration (the whole map as
+// `change.set`), then on every change. Both fires are synchronous: the
+// registration fire runs before `subscribe` returns, and a change fire runs
+// inside the `mutate` that caused it. So a subscriber cannot reach a `const`
+// its own registration fire initialises, and work it defers to a later tick
+// runs after the mutation has finished.
+export type MapSubscriber<T = unknown> = (
+  change: Change<T>,
+  origin?: ChangeOrigin,
+) => void;
+
+// Internal (not exported): a map subscriber that also learns whether a fire is
+// a whole-container catch-up (`resync: true`: registration, or a checkout /
+// return-to-head / hydrate swapping the source) or an incremental delta
+// (`false`). This is the "full re-sync vs incremental" distinction, ORTHOGONAL
+// to `origin` (which is authorship: local / remote / undo / redo, all one path
+// to a render). The ordered map needs it because a source swap can reorder
+// `instance_order` with the same key set, which its key-set move test cannot
+// see; keying off this explicit flag keeps that check gated to the rare
+// re-sync fires without overloading `origin`. The public `subscribe` wraps an
+// app `MapSubscriber` and drops the flag, so it never reaches an app.
+export type InternalMapSubscriber<T> = (
+  change: Change<T>,
+  origin: ChangeOrigin | undefined,
+  resync: boolean,
+) => void;
+
+/**
+ * One positional edit, applied in the order the change carries them.
+ *
+ * `at` indexes the sequence as the preceding splices in the same change left
+ * it, so applying them in order to what you already hold leaves you current.
+ * That is the whole contract: a subscriber never has to ask what the list
+ * holds, because every fire says how to get from its last state to this one.
+ */
+export interface Splice<E> {
+  readonly at: number;
+  readonly removed: number;
+  readonly inserted: readonly E[];
+}
+
+/**
+ * What changed in a list. Fires once on registration carrying the whole list
+ * as a single splice, then on every change carrying only what moved.
+ *
+ * A registration fire and a resync are not special cases a subscriber has to
+ * recognise: both arrive as splices that replace what it was last told, so
+ * one apply loop is the entire subscriber.
+ */
+export interface ListChange<T> {
+  readonly splices: readonly Splice<T>[];
+}
+
+export type ListSubscriber<T = unknown> = (change: ListChange<T>) => void;
+
+// Internal (not exported): a list subscriber that also learns what produced
+// the change, so the ordered map can stamp an `order` frame its order list's
+// own move produced. Undefined on a whole-container catch-up (registration, or
+// a checkout / return-to-head / hydrate swapping the source), which describes
+// no authored transition, matching `MapSubscriber`'s optional origin.
+export type InternalListSubscriber = (
+  change: ListChange<unknown>,
+  origin?: ChangeOrigin,
+) => void;
+
+export type HandleUnsubscribe = () => void;
+
+// Hooks the owning Document provides so handles participate in the SDK's
+// commit + origin machinery. Defined here (not in documents.ts) so handles.ts
+// has no compile-time dependency on the Document class.
+export interface HandleOwner {
+  // Throws if the Document is closed, suspended, or read-only.
+  assertWritable(): void;
+  // Throws if the Document is closed. `close()` releases the CRDT state the
+  // handles read through, so a read taken after it reaches released memory and
+  // fails with whatever the engine says about that. An app holds a handle
+  // across a close by design (it is what a subscription is registered on), so
+  // this is an ordinary race: a callback, a frame, or a settled promise
+  // reading one tick after the close. The gate is what makes that answer
+  // `Document is closed` in the app's own vocabulary, like a write does.
+  //
+  // Closed only, never suspended: a parked Document keeps its state, and its
+  // reads answer from it.
+  assertReadable(): void;
+  // Lazily, idempotently attaches the local-updates hook before first mutate.
+  ensureLocalUpdatesSubscribed(): void;
+  // Stamps the next commit with the mutate origin tag and commits, so the
+  // change's `origin.source` reads `'local'`.
+  commitMutate(): void;
+  // Classify a Loro event by what produced it. Derived from the commit's
+  // `by` + origin tag, so it survives microtask-deferred delivery.
+  originOf(event: unknown): ChangeSource;
+}
+
+// Public handle interfaces. Concrete classes below.
+
+export interface MapHandle<T = unknown> {
+  // Per-entry read. Returns undefined when missing.
+  get(entryKey: string): T | undefined;
+  // Keys currently in the map.
+  keys(): string[];
+  // Whether an entry exists at `entryKey`.
+  has(entryKey: string): boolean;
+  // Mutate through a typed JS-proxy, scoped to this container; same
+  // ergonomics as `doc.mutate(d => { d.entities[id].field = ... })`.
+  mutate(fn: (draft: Record<string, T>) => void): void;
+  // ONE channel for every change whatever produced it (local / remote / undo
+  // / redo / checkout): the projection reconciles by value. The callback gets
+  // `change` and optional `origin` a render ignores. Fires once on
+  // registration with the whole map as `change.set`, then on every change
+  // (each later fire proportional to what that change wrote).
+  subscribe(cb: MapSubscriber<T>): HandleUnsubscribe;
+  /**
+   * Report each time this container has been delivered whole: on
+   * registration, and again after a version checkout, a return to head or a
+   * hydrate replaces it.
+   *
+   * This is where the work that follows on the collection belongs rather than
+   * on any single change: frame the camera on what arrived, run the first pass
+   * over it. It repeats because that work is owed again each time the
+   * container is replaced.
+   *
+   * It reports that this peer holds what it had converged to when the delivery
+   * began, which is the only claim available: more always arrives afterwards.
+   */
+  onSettled(cb: () => void): HandleUnsubscribe;
+
+  // Child handle for `entries[entryKey]` when that entry is itself a map /
+  // list. Reads see empty until the container exists; the first mutate
+  // creates it, and a subscription taken before that delivers the container
+  // whole on whichever write creates it.
+  map<U>(entryKey: string): MapHandle<U>;
+  list<U>(entryKey: string): ListHandle<U>;
+}
+
+/**
+ * The array a list `mutate` hands its callback: an ordinary `T[]` plus
+ * `move`.
+ *
+ * `move` is here because a plain array has no way to say "this entry is now
+ * at that position", and the difference matters once two people edit at once.
+ * Spelled as a removal and an insertion, a reposition merges with another
+ * peer's reposition of the SAME entry by keeping BOTH insertions, so the entry
+ * ends up in the list twice and a reader has to guess which position was
+ * meant. `move` states the reposition, and the two merge to one entry.
+ */
+export interface ListDraft<T> extends Array<T> {
+  /** Reposition the entry at `from` so it sits at `to`. Indices are clamped
+   *  to the list, and a `from` outside it does nothing. */
+  move(from: number, to: number): void;
+}
+
+export interface ListHandle<T = unknown> {
+  length(): number;
+  mutate(fn: (draft: ListDraft<T>) => void): void;
+  // Fires once on registration carrying the whole list as one splice, then on
+  // every change carrying only what moved, so a subscriber applies splices to
+  // what it already holds and never re-reads. A keyed collection belongs in a
+  // map (or `orderedMap`), which reconciles by key; a list is for ordering
+  // keys and small positional data.
+  subscribe(cb: ListSubscriber<T>): HandleUnsubscribe;
+  /**
+   * Report each time this container has been delivered whole: on
+   * registration, and again after a version checkout, a return to head or a
+   * hydrate replaces it.
+   *
+   * This is where the work that follows on the collection belongs rather than
+   * on any single change: frame the camera on what arrived, run the first pass
+   * over it. It repeats because that work is owed again each time the
+   * container is replaced.
+   *
+   * It reports that this peer holds what it had converged to when the delivery
+   * began, which is the only claim available: more always arrives afterwards.
+   */
+  onSettled(cb: () => void): HandleUnsubscribe;
+}
+
+// An ordered map: a keyed map whose key insertion order is mirrored into a
+// sibling list, kept in lockstep. The record store (`instances` +
+// `instance_order`) is the motivating adopter, reached as
+// `doc.orderedMap('instances', 'instance_order')`, but the primitive names no
+// format: two ordinary root containers bound so an app cannot forget to
+// update the order list on add / remove.
+//
+// Add appends to the order list, delete removes from it, both in ONE commit
+// (one undo step). Reassigning a key's value (a `params` edit) leaves the
+// order untouched and stays O(1): only structural add / delete touches it.
+// `insert` and `move` place a key somewhere other than the end.
+
+/**
+ * Where an ordered map puts a key.
+ *
+ * The two anchor forms name a neighbouring key, which is what a reader's
+ * gesture actually means (insert after the paragraph the caret is in, drop
+ * this step on that one) and what survives a peer editing the collection
+ * between the render and the write. `index` counts positions in `keys()`, for
+ * a surface that works in indices; anything at or past the end appends, and a
+ * negative index goes to the front.
+ *
+ * An anchor key the order list does not name puts the key at the end.
+ */
+export type OrderedMapPosition =
+  | { before: string }
+  | { after: string }
+  | { index: number };
+
+export interface OrderedMapHandle<T = unknown> {
+  // Per-entry read. Returns undefined when missing.
+  get(entryKey: string): T | undefined;
+  // Whether an entry exists in the map.
+  has(entryKey: string): boolean;
+  // Keys in order-list order, filtered to keys still present in the map.
+  keys(): string[];
+  // `[key, value]` records walking the order list, so an app reading in
+  // source order doesn't re-walk the order list by hand.
+  ordered(): { key: string; value: T }[];
+  // Mutate the map; the sibling order list reconciles in the same commit
+  // (new keys appended in insertion order, deleted keys pruned). Drive it
+  // like `MapHandle.mutate`: `m[key] = record`, `delete m[key]`,
+  // `m[key].field = ...`.
+  mutate(fn: (draft: Record<string, T>) => void): void;
+  // Write `value` under `entryKey` and put that key at `at`, both in ONE
+  // commit (one undo step) like every other structural edit here. A key the
+  // map already holds is written and repositioned rather than named twice.
+  insert(entryKey: string, value: T, at: OrderedMapPosition): void;
+  // Reposition a key the map already holds, writing the order list alone. A
+  // key the map does not hold does nothing, so a reorder racing a peer's
+  // delete of the same key leaves the delete standing.
+  move(entryKey: string, to: OrderedMapPosition): void;
+  // Fires once on registration (the whole map as `change.set` in order),
+  // then on every change. A field edit carries only `set` / `deleted`; a
+  // change that moves the order also carries `change.order` (live keys in
+  // order) so the app re-sequences the views it holds. A move the map does
+  // not see (an edit of the sibling order list, a merge that resequences
+  // keys already present) arrives as an `order` of its own with an empty
+  // `set`. Content stays proportional to what the change wrote; re-sequencing
+  // happens only when the order moves, and at most once per change.
+  subscribe(cb: MapSubscriber<T>): HandleUnsubscribe;
+  /**
+   * Report each time this container has been delivered whole: on
+   * registration, and again after a version checkout, a return to head or a
+   * hydrate replaces it.
+   *
+   * This is where the work that follows on the collection belongs rather than
+   * on any single change: frame the camera on what arrived, run the first pass
+   * over it. It repeats because that work is owed again each time the
+   * container is replaced.
+   *
+   * It reports that this peer holds what it had converged to when the delivery
+   * began, which is the only claim available: more always arrives afterwards.
+   */
+  onSettled(cb: () => void): HandleUnsubscribe;
+}