@brass-build/client 0.1.0

package/dist/documents.js

@@ -0,0 +1,2045 @@
+// SDK surface: `Brass.Document` plain-object proxy over Loro.
+//
+// Two load-bearing Loro gotchas:
+//   1. `LoroDoc.subscribe(fn)` fires synchronously on every import,
+//      including the initial snapshot import (8.5 s on a 50k snapshot).
+//      So lazy-attach the Loro subscriber only on first `doc.subscribe`
+//      (see `_ensureLoroSubscribed`).
+//   2. The `getOwnPropertyDescriptor` trap participates in
+//      `Object.keys`; doing `loroMap.keys().includes(key)` there makes
+//      `Object.keys()` O(N^2). It reads a single `loroMap.get(key)`.
+import { LoroDoc, LoroMap, VersionVector, decodeImportBlobMeta, } from 'loro-crdt';
+import { MutateBatcher } from './mutate-batching.js';
+import { UndoController, } from './undo.js';
+import { createOrderedMapHandle, createRootListHandle, createRootMapHandle, rebindRootListAnchor, rebindRootMapAnchor, resyncRootHandle, teardownRootHandle, wrapLoroMapProxy, } from './handles.js';
+import { CURRENT_PAGING_SCHEME, isPagedByPageCount, META_KEY, PAGE_COUNT_KEY, PAGING_SCHEME_KEY, RECORDS_KEY, } from './record-paging.js';
+import { GoneSignal, WorkStatusSignal, DriveStatusSignal, } from './document-signals.js';
+import { ThumbnailCapture, } from './document-thumbnail-capture.js';
+import { CheckpointScheduler, } from './document-checkpoints.js';
+import { BranchController, } from './document-branches.js';
+import { CommandMenu, } from './document-commands.js';
+import { DocumentStream } from './document-streams.js';
+import { createEmitter } from './emitter.js';
+// The stream name `doc.stream()` resolves to the document's own default
+// state; mirrors the server's reserved name.
+export const DEFAULT_STREAM_NAME = 'default';
+// Commit-origin tags stamped on every locally-produced commit via Loro's
+// `setNextCommitOrigin`, so `origin.source` can be recovered off the
+// event. Stamping the commit (not a JS-side flag) survives a
+// microtask-deferred subscribe callback: the tag travels with the event.
+// `mutate()` carries `MUTATE`; `undo()`/`redo()` stamp their own tag
+// before driving the UndoManager so they read back as `'undo'`/`'redo'`
+// not `'local'`. A remote op (`by === 'import'`) and a checkout
+// (`by === 'checkout'`) need no tag.
+const MUTATE_COMMIT_ORIGIN = 'brass.mutate';
+const UNDO_COMMIT_ORIGIN = 'brass.undo';
+const REDO_COMMIT_ORIGIN = 'brass.redo';
+// Classify a Loro event by what produced it. The render path never calls
+// this (it reconciles by value); it backs a change's `origin.source` for
+// attribution and the SDK's own local-vs-remote side-effect gating
+// (thumbnail capture, auto-checkpoint).
+function changeSourceOf(event) {
+    const by = event.by;
+    if (by === 'import')
+        return 'remote';
+    if (by === 'checkout')
+        return 'checkout';
+    // by === 'local': disambiguate via the commit-origin tag.
+    const origin = event.origin;
+    if (origin === UNDO_COMMIT_ORIGIN)
+        return 'undo';
+    if (origin === REDO_COMMIT_ORIGIN)
+        return 'redo';
+    return 'local';
+}
+// Per-chunk cap on a resync-push blob (durability handshake). Each push
+// ships as one op frame, and the transport carries 128 KB; the blob is
+// base64-encoded (~1.33x) inside a JSON envelope, so the raw blob must
+// stay well under that. 64 KB base64s to ~85 KB. A larger missing slice
+// is split into multiple chunks (see `computeResyncPush`), each capped.
+const RESYNC_PUSH_MAX_BYTES = 64 * 1024;
+// Hard ceiling for a single irreducible op (one Loro op, unsplittable).
+// Sized so the base64 frame still clears the 128 KB limit (90 KB base64s
+// to ~120 KB plus envelope). An op this large cannot occur on a doc
+// whose normal edits send at all (same frame limit), so this only guards
+// a pathological op; it is skipped with a warning rather than retried
+// forever, while the doc's other chunks still heal.
+const RESYNC_PUSH_HARD_MAX_BYTES = 90 * 1024;
+// Element-wise max of two Loro version vectors. `VersionVector` exposes
+// no public join, so round-trip through its `Map<PeerID, number>` JSON
+// form. Counters are exclusive ends, so the larger is more advanced.
+// Used by the durability handshake to fold the durable tail into the
+// snapshot's version vector.
+function mergeVersionVectors(a, b) {
+    const merged = a.toJSON();
+    for (const [peer, counter] of b.toJSON()) {
+        const current = merged.get(peer);
+        if (current === undefined || counter > current)
+            merged.set(peer, counter);
+    }
+    return VersionVector.parseJSON(merged);
+}
+// Split half-open per-peer counter ranges into two halves by total op
+// count, splitting at most one range across the boundary. `total` must
+// be >= 2 so both halves are non-empty (the caller handles total === 1
+// as the irreducible single-op case). Order is preserved.
+function splitRangesByLength(ranges, total) {
+    const half = Math.floor(total / 2);
+    const first = [];
+    const second = [];
+    let acc = 0;
+    for (const r of ranges) {
+        const len = r.to - r.from;
+        if (acc >= half) {
+            second.push(r);
+        }
+        else if (acc + len <= half) {
+            first.push(r);
+            acc += len;
+        }
+        else {
+            const splitAt = r.from + (half - acc);
+            first.push({ peer: r.peer, from: r.from, to: splitAt });
+            second.push({ peer: r.peer, from: splitAt, to: r.to });
+            acc = half;
+        }
+    }
+    return [first, second];
+}
+// The record store's page count off a doc's `meta` map, or 0 when
+// unpaged. `handles.ts` reads it to resolve which page a key hashes to
+// AND to decide whether the store is paged at all (on every root-map
+// read / edit). Read by PATH, not `getMap(META_KEY)`: `getMap` is
+// get-or-create and would materialize an empty `meta` root on every
+// unpaged document, polluting its wire shape; `getByPath` is a pure read
+// returning undefined when `meta` does not exist.
+function readStorePageCount(source) {
+    const pc = source.getByPath(`${META_KEY}/${PAGE_COUNT_KEY}`);
+    // Same "is paged" predicate as the formats/core readers, so the SDK
+    // handle path and the store readers cannot disagree on a malformed
+    // count (e.g. a non-finite value must read as unpaged everywhere).
+    return isPagedByPageCount(pc) ? pc : 0;
+}
+// The paging scheme a paged store was written under, off the same `meta` map
+// as the page count (read by path, not `getMap`, for the same reason: a pure
+// read that never materializes an empty `meta` root). A paged store predating
+// the stamp reports the current scheme, so it stays editable; a store written
+// under a newer scheme reports that number, and the edit path refuses it
+// rather than hashing a key into the wrong page.
+function readStorePagingScheme(source) {
+    const s = source.getByPath(`${META_KEY}/${PAGING_SCHEME_KEY}`);
+    return typeof s === 'number' && s > 0 ? s : CURRENT_PAGING_SCHEME;
+}
+// Public Document class. Wraps a LoroDoc; exposes mutate / subscribe /
+// toJSON / close. Construction is cheap: the Loro subscriber attaches
+// lazily (see `_ensureLoroSubscribed`).
+export class Document {
+    _doc;
+    _rootKey;
+    // Server-minted `doc_id`, or `null` when constructed without one
+    // (test / offline path).
+    _docId;
+    _branchId;
+    // Active checkout state. `null` means the Document is on the live
+    // head of `_branchId`: edits are accepted, the WS stream applies
+    // remote ops directly to `_doc`. A non-null state means a historical
+    // version is being previewed: `_checkout.previewDoc` holds the
+    // materialised state at that version, reads go through it, and
+    // `mutate` throws. The LIVE `_doc` keeps receiving ops in the
+    // background; returning to head just clears the checkout state and
+    // the live state is already current.
+    _checkout;
+    // Bumped by every `_checkoutVersion` (before its await) and every
+    // `returnToHead`. A `_checkoutVersion` reads its token before awaiting the
+    // fetch and bails after if the token moved, so a return-to-live or a newer
+    // checkout issued during the fetch window wins instead of being overwritten
+    // when the stale fetch resolves. Without it, `returnToHead` sees
+    // `_checkout === null` mid-fetch, no-ops, and the resolving checkout strands
+    // the doc in the historical preview the user just left.
+    _checkoutGeneration = 0;
+    // True for Documents that have no live WS channel: the cold-link
+    // `Brass.openDocumentById(id, { version })` shape. Such Documents
+    // are frozen at the constructor-time version; `_checkoutVersion`
+    // and `returnToHead` reject. The live + checkout-on-demand path
+    // leaves this `false`.
+    _isFrozen;
+    // Forced read-only on a LIVE head open (distinct from `_isFrozen`, which
+    // is a version-pinned open with no live channel). The anonymous
+    // link-guest open sets this: the Document keeps a live WS subscription
+    // and applies incoming remote ops, but local `mutate` is rejected, so a
+    // guest sees edits stream in while being unable to write.
+    _forcedReadOnly;
+    _root;
+    _entities;
+    // The UndoManager is constructed eagerly so the first call to
+    // `doc.mutate(...)` lands in the undo stack. Lazy construction
+    // (deferred to first `doc.undo()`) would miss every commit made
+    // before that point, which is not the behaviour callers expect.
+    // The UndoManager attaches its own `subscribeLocalUpdates` listener
+    // only; it does NOT fire on snapshot import, so the
+    // cold-load contract is unaffected (imports are not local commits).
+    _undo;
+    // One subscriber channel. Every event reaches every subscriber, whatever
+    // produced it (local mutate, remote import, undo, redo, checkout); the
+    // app reconciles by value and reads `origin.source` only when it has a
+    // non-render reason to know the cause. A throwing subscriber is swallowed
+    // so it cannot strand the others or the WS router.
+    _subs = createEmitter({ onError: () => { } });
+    // Subscribers registered via `subscribeUndoState`. Fired after
+    // every underlying Loro event when `canUndo()` or `canRedo()`
+    // changed value vs the last fire, so UI bound to undo/redo
+    // enabled state stays current without the consumer caring
+    // whether the originating event was a local mutate, undo,
+    // redo, or remote import.
+    _undoStateSubs = new Set();
+    _lastCanUndo = false;
+    _lastCanRedo = false;
+    _unsubLoro = null;
+    _unsubLocal = null;
+    // Local commits drive this hook with the resulting op blob; the hook
+    // returns a `clientOpId` tracked for `op_ack` correlation. In-flight
+    // op bytes (keyed by `clientOpId`) live in `_outstandingByClientId`;
+    // `applyRemoteOp` checks them to short-circuit self-originated
+    // round-trips.
+    _localOpHook = null;
+    // Materialises a historical version against the server; returns the
+    // snapshot bytes (or null) + tail op blobs + effective version.
+    _checkoutFetcher = null;
+    // The stream seq vector from the active preview, so a stream opened WHILE
+    // a preview is active can open at its historical seq too. Cleared on
+    // `returnToHead`.
+    _checkoutStreamSeqs = null;
+    // Transport-provided cursor for the branch's live head seq. A
+    // provider (not a stored number) so the Document never has to be
+    // notified of every op. `null` on the offline / test path; a
+    // read-only historical open reports its frozen `version` instead.
+    _currentSeqProvider = null;
+    _branchCtl = new BranchController({
+        docId: () => this._docId,
+        branchId: () => this._branchId,
+        isActive: () => this._isLive,
+        onBranchesChanged: () => {
+            this._fireSubscribers({ kind: 'branches' });
+        },
+    });
+    _thumbnails = new ThumbnailCapture({
+        isCaptureAllowed: () => this._isLive && this._checkout === null,
+        isAttached: () => this._isLive,
+    });
+    _checkpoints = new CheckpointScheduler({
+        docId: () => this._docId,
+        isAttached: () => this._isLive,
+        isAutoAllowed: () => this._isLive && this._checkout === null,
+        currentSeq: () => this.currentSeq,
+        sealUndoStep: () => {
+            if (this._undo)
+                this._undo.sealStep();
+        },
+    });
+    // Drive push hook. `null` on the offline / test path; `pushToDrive`
+    // then throws with a clear message rather than silently dropping.
+    _drivePusher = null;
+    // Drive divergence-resolution hook. Mirrors `_drivePusher`: `null` on
+    // the offline / test path, in which case `resolveDrive` throws with a
+    // clear message. Wired by `client.ts` to open the hosted resolve
+    // surface and route any new mirror doc through `openSiblingDoc`.
+    _driveResolver = null;
+    // Source-blob fetch hook. When supplied, `doc.sourceBlob()` routes
+    // through it (the namespace's `GET .../source-blob`). When absent
+    // (tests / offline), `sourceBlob` throws with a clear message rather
+    // than silently dropping. Wired by `client.ts` from
+    // `documents.sourceBlob`.
+    _sourceBlobFetcher = null;
+    // Cached doc name. `null` on offline / test docs.
+    _name = null;
+    // True once the reader has asked for the version-browsing surface without
+    // checking anything out (the hosted history dialog's browse-in-the-app
+    // outcome). The host's version bar latches on this as well as on a live
+    // checkout, so browsing can start at the live head.
+    _versionBrowsing = false;
+    _commandMenu = new CommandMenu({
+        docId: () => this._docId,
+        branchId: () => this._branchId,
+        readOnly: () => this.readOnly,
+        isLive: () => this._isLive,
+        canUndo: () => this.canUndo(),
+        canRedo: () => this.canRedo(),
+        undo: () => {
+            this.undo();
+        },
+        redo: () => {
+            this.redo();
+        },
+        checkoutVersion: (version) => this._checkoutVersion(version),
+        browseVersions: () => {
+            this._setVersionBrowsing(true);
+        },
+        branches: () => this._branchCtl.branches,
+        hasBranchProvider: () => this._branchCtl.hasProvider,
+        createBranch: (input) => this._branchCtl.create(input),
+        refreshBranches: () => this._refreshBranches(),
+        setName: (name) => this._setName(name),
+        onCommandsChanged: () => {
+            this._fireSubscribers({ kind: 'commands' });
+        },
+    });
+    // The clientOpId of every local op that has not yet been acked. The
+    // open-document layer drains this on `op_ack`. Tracking is keyed by
+    // clientOpId, not op-blob bytes, because clientOpId is what the
+    // server echoes back; the blob is opaque to Brass.
+    _outstandingByClientId = new Map();
+    // client_op_ids of the in-flight resync push (durability handshake). A
+    // push can be a single op or several chunks for a large divergence, so
+    // this is a set. The loop guard: while any chunk is unacked, the
+    // handshake skips a fresh push so a flurry of reconnects cannot re-push
+    // the same missing slice. Each id is removed by `resolveOutstandingOp`
+    // when its ack lands; the guard reopens once the set drains.
+    _resyncPushClientOpIds = new Set();
+    // Async-error sink, shared with the built-in commands. `_failOutstandingOp`
+    // surfaces a terminally-rejected op here so a "could not be saved" outcome
+    // reaches the app instead of being a silent forever-retry.
+    _errorReporter = null;
+    _closed = false;
+    // Set true when the Document is parked in the SDK's per-(docId, branchId)
+    // cache after an app-level `close()`. The underlying LoroDoc, UndoController,
+    // and WS subscription stay alive so the next `openDocumentById` for the
+    // same key returns this same instance with its undo stack intact. The
+    // user-facing API gates as if the Doc were closed: `mutate` throws, no
+    // events fire to app-side subscribers (`_subs`
+    // and the gone / work-status signal listeners are cleared on suspend so
+    // a stale handle from a prior session does not receive events from the
+    // next session). `_resume()`
+    // flips the flag back when the SDK hands the Doc to a new open() call.
+    _suspended = false;
+    // Live = neither closed nor parked. This is the public-surface gate;
+    // internal ingress (remote ops, status emits) deliberately checks
+    // `_closed` alone, because a parked doc keeps applying remote state.
+    get _isLive() {
+        return !this._closed && !this._suspended;
+    }
+    _assertOpen() {
+        if (!this._isLive)
+            throw new Error('Document is closed');
+    }
+    // Server-pushed lifecycle signals: `_gone` is fire-once-then-cache
+    // for `doc_gone` eviction; `_workStatus` is latest-retained,
+    // re-emit-per-phase for `doc_status`.
+    _gone = new GoneSignal();
+    _workStatus = new WorkStatusSignal();
+    // Drive sync state, latest-retained. `null` until the open factory
+    // seeds it (drive-linked docs only) and on docs with no drive link.
+    _driveStatus = new DriveStatusSignal();
+    // Document-scoped presence. `null` until the WS transport is wired
+    // on, and on the offline / test path where there is no transport.
+    presence = null;
+    constructor(loroDoc, options) {
+        this._doc = loroDoc;
+        this._rootKey = options?.rootKey ?? 'entities';
+        this._docId = options?.docId ?? null;
+        this._branchId = options?.branchId ?? null;
+        // A Document constructed with a `version` is a "frozen" cold-link
+        // open: the SDK materialised the historical state directly into
+        // `loroDoc` and there is no live WS channel. The Document is
+        // permanently in checkout against itself; `returnToHead` /
+        // `_checkoutVersion` are not meaningful on this shape.
+        const initialVersion = options?.version ?? null;
+        if (initialVersion !== null) {
+            this._isFrozen = true;
+            this._checkout = {
+                previewDoc: loroDoc,
+                previewRoot: loroDoc.getMap(this._rootKey),
+                version: initialVersion,
+            };
+        }
+        else {
+            this._isFrozen = false;
+            this._checkout = null;
+        }
+        // `readOnly` on a live (non-version) open is a forced read-only: the
+        // guest link view. A version open is already frozen, so it does not
+        // also need the forced flag.
+        this._forcedReadOnly = options?.readOnly === true && initialVersion === null;
+        this._root = loroDoc.getMap(this._rootKey);
+        this._entities = wrapLoroMapProxy(this._root);
+        this._undo = new UndoController(this._doc, options?.undo);
+    }
+    // ---- Typed container handles (the primary read/write/subscribe surface) --
+    //
+    // Handles scope reads, writes, and subscriptions to one container in
+    // the underlying CRDT doc. The README leads with this surface; the
+    // doc-wide `mutate` / `subscribe` / `toJSON` methods below stay as a
+    // simpler-but-slower fallback for tiny docs and one-liner integrations.
+    //
+    // Identity: handles are cached per (key, kind), so
+    // `doc.map('entities') === doc.map('entities')` and bindings to the
+    // handle compare stable across renders.
+    // Cached root handles, keyed by kind + key so `doc.map('x')` and
+    // `doc.list('x')` coexist. One map, not one per kind, so a version checkout
+    // rebinds and each suspend / close tears down every root handle in a single
+    // traversal.
+    _rootHandles = new Map();
+    // Get a handle for a top-level LoroMap at `key`. The container is
+    // materialized in the underlying LoroDoc immediately (Loro's
+    // `getMap` is "get or create"); mutations through the handle do
+    // not need to create the container themselves.
+    map(key) {
+        this._assertOpen();
+        const cacheKey = `map:${key}`;
+        const existing = this._rootHandles.get(cacheKey);
+        if (existing)
+            return existing.handle;
+        // Source the LoroMap from the active source (live or checkout
+        // preview), same as `toJSON` does. Handles bound to a Document
+        // in checkout see the historical state via the preview doc.
+        const source = this._checkout !== null ? this._checkout.previewDoc : this._doc;
+        const loroMap = source.getMap(key);
+        // The page-count provider lets a handle over a large record store's
+        // `instances` map present its page containers transparently as a
+        // flat record map. It resolves the ACTIVE source at call time (not
+        // the one captured at handle creation): a checkout rebinds the
+        // handle's anchor to the preview doc, and the page count must come
+        // from that same doc or keyed reads hash into the wrong page (and a
+        // closure pinned to a preview doc would read a freed LoroDoc after
+        // returnToHead).
+        //
+        // Only the record store's paged root (`instances`) may report a page
+        // count. `readStorePageCount` reads the document-global
+        // `meta.page_count`, so handing it to every root map would make the
+        // sibling record-store roots (`meta`, `header`) and any app-owned
+        // root map read as paged once `instances` pages, routing their
+        // `get`/`has`/`mutate` through the page-hash path against a map that
+        // holds no page containers (`get` returns undefined for present keys;
+        // `mutate` writes a stray page container into a plain map). A non-
+        // record-store key gets a null provider and stays unpaged.
+        const handle = createRootMapHandle(loroMap, this._handleOwner, key === RECORDS_KEY
+            ? () => readStorePageCount(this._checkout !== null ? this._checkout.previewDoc : this._doc)
+            : undefined, key === RECORDS_KEY
+            ? () => readStorePagingScheme(this._checkout !== null ? this._checkout.previewDoc : this._doc)
+            : undefined);
+        this._rootHandles.set(cacheKey, { kind: 'map', key, handle });
+        return handle;
+    }
+    // Get a handle for a top-level LoroList at `key`.
+    list(key) {
+        this._assertOpen();
+        const cacheKey = `list:${key}`;
+        const existing = this._rootHandles.get(cacheKey);
+        if (existing)
+            return existing.handle;
+        const source = this._checkout !== null ? this._checkout.previewDoc : this._doc;
+        const loroList = source.getList(key);
+        const handle = createRootListHandle(loroList, this._handleOwner);
+        this._rootHandles.set(cacheKey, { kind: 'list', key, handle });
+        return handle;
+    }
+    // Get an ordered-map handle binding a keyed map at `mapKey` to a sibling
+    // order list at `orderKey`: adds append to the order list, deletes prune
+    // it, both in one commit, so an app cannot leave the two out of step.
+    // The record store every imported document carries is reached as
+    // `doc.orderedMap('instances', 'instance_order')`; the primitive itself
+    // is format-neutral (two root containers, no record-store knowledge).
+    // Built over the same `map(mapKey)` / `list(orderKey)` handles, so the
+    // paged-store presentation and subscriptions carry through.
+    _orderedMapHandles = new Map();
+    orderedMap(mapKey, orderKey) {
+        this._assertOpen();
+        const cacheKey = `${mapKey}\u0000${orderKey}`;
+        let h = this._orderedMapHandles.get(cacheKey);
+        if (!h) {
+            h = createOrderedMapHandle(this.map(mapKey), this.list(orderKey), this._handleOwner);
+            this._orderedMapHandles.set(cacheKey, h);
+        }
+        return h;
+    }
+    // Stable handle-owner closure: handles call back into this to
+    // participate in the standard commit + origin machinery. The bind
+    // happens once on first access; later mutations through any handle
+    // route through the same closure so the local-op hook, undo stack,
+    // and subscribe local-echo filter all fire correctly.
+    _handleOwnerCache = null;
+    get _handleOwner() {
+        if (this._handleOwnerCache)
+            return this._handleOwnerCache;
+        this._handleOwnerCache = {
+            assertWritable: () => {
+                this._assertOpen();
+                if (this._checkout !== null) {
+                    throw new Error('Document is read-only: it is showing a historical version. ' +
+                        'Call `doc.returnToHead()` to edit.');
+                }
+                if (this._forcedReadOnly) {
+                    throw new Error('Document is read-only: it was opened via a view-only share link.');
+                }
+                if (this._isLoadLocked()) {
+                    throw new Error('Document is still loading its content; wait for the load to ' +
+                        'finish before editing (see `doc.onStatus`).');
+                }
+            },
+            ensureLocalUpdatesSubscribed: () => {
+                this._ensureLocalUpdatesSubscribed();
+            },
+            commitMutate: () => {
+                this._doc.setNextCommitOrigin(MUTATE_COMMIT_ORIGIN);
+                this._doc.commit();
+            },
+            originOf: (event) => changeSourceOf(event),
+        };
+        return this._handleOwnerCache;
+    }
+    // Server-minted `doc_id`. Always a string for a Document returned
+    // from `Brass.openDocumentById` / `Brass.createDocument`; `null`
+    // only on the direct-construction (test / offline) path.
+    get id() {
+        return this._docId;
+    }
+    /**
+     * The branch this Document is open on, fixed for its lifetime (switching
+     * branches opens a new Document). `null` only on the offline / test path.
+     * The SDK reads it to scope WS / presence topics and thumbnail /
+     * checkpoint writes to the branch.
+     * @internal
+     */
+    get branchId() {
+        return this._branchId;
+    }
+    // True when the Document is currently showing a historical version
+    // (a checkout): `mutate` throws and edit affordances should be
+    // disabled. Reactive: flips on `_checkoutVersion(v)` /
+    // `returnToHead()`. `subscribe` fires when this changes, so apps
+    // bind it directly inside the subscribe handler.
+    get readOnly() {
+        // A doc that is still loading its first content (a drive-linked
+        // stub hydrating on first open) is read-only until the bytes
+        // arrive: editing it would write ops onto an empty doc that the
+        // incoming snapshot is about to replace. The SDK reloads the
+        // content automatically when the work finishes (see open-document's
+        // `reloadAfterHydration`); until then mutation is rejected. This is
+        // also what stops an app's "seed an empty doc" path from clobbering
+        // a doc that only looks empty because it has not loaded yet.
+        return (this._forcedReadOnly || this._checkout !== null || this._isLoadLocked());
+    }
+    // True when content-replacing work (hydration / extraction) is pending
+    // and editing must be locked so incoming bytes do not clobber local
+    // ops. A pending PUSH is outbound (it writes the doc out to the drive,
+    // nothing replaces local content), so the server marks it
+    // `blocking: false` and the doc stays editable while the importer
+    // runs. An older server omits `blocking`; absence is treated as
+    // blocking so hydration stays locked.
+    _isLoadLocked() {
+        const s = this._workStatus.status;
+        return s?.pending === true && s.blocking !== false;
+    }
+    /**
+     * The historical version this Document shows, or `null` for a live
+     * (head) open. Reactive alongside `readOnly`. The number is the
+     * server's effective version, which can round down from the
+     * requested version when compaction has TTL'd the exact op.
+     *
+     * An app that needs to know the doc is not editable reads the public
+     * `doc.readOnly` (true for a preview, a view-only link, or a load lock).
+     * @internal
+     */
+    get version() {
+        return this._checkout?.version ?? null;
+    }
+    /** @internal Whether the host should be showing its version-browsing
+     *  surface for this document. True from a browse-in-the-app outcome and
+     *  independent of `version`, so browsing can start at the live head; the
+     *  host clears it when the reader closes that surface. */
+    get versionBrowsing() {
+        return this._versionBrowsing;
+    }
+    /** @internal Set by the host (on close) and by the browse-in-the-app
+     *  command. Fires the `commands` signal so a host rendering off
+     *  subscription re-reads it. */
+    _setVersionBrowsing(on) {
+        if (this._versionBrowsing === on)
+            return;
+        this._versionBrowsing = on;
+        this._fireSubscribers({ kind: 'commands' });
+    }
+    /** @internal The version this Document currently shows: the branch's live
+     *  head seq for a head open (advanced by the WS op stream), or the frozen
+     *  checkout version when a historical version is being previewed. The
+     *  SDK's own anchors read it (a checkpoint seals at it, a thumbnail
+     *  upload pins to it); no app-facing operation takes a seq, since version
+     *  history is hosted chrome the app does not drive with numbers. */
+    get currentSeq() {
+        if (this._checkout !== null)
+            return this._checkout.version;
+        if (this._currentSeqProvider)
+            return this._currentSeqProvider();
+        return null;
+    }
+    /**
+     * Open a Document from a Loro snapshot (the SDK join path). Attaches
+     * the Loro subscriber lazily, AFTER import: subscribing at
+     * construction costs ~8 s on a 50k snapshot.
+     * @internal
+     */
+    static openFromSnapshot(snapshot, options) {
+        const loroDoc = new LoroDoc();
+        loroDoc.import(snapshot);
+        return new Document(loroDoc, options);
+    }
+    /**
+     * Construct an empty Document (empty-snapshot join case, and tests).
+     * @internal
+     */
+    static create(options) {
+        return new Document(new LoroDoc(), options);
+    }
+    // Apply a remote op blob produced by another peer (delivered via the
+    // WS `doc_op` server frame). Idempotent: Loro's import
+    // path dedupes by lamport, so re-applying a self-originated op is
+    // a no-op in terms of state. We still avoid the import work entirely
+    // when the caller can prove the op originated locally (matched by
+    // `clientOpId`); that saves the WASM round-trip on every echo and
+    // avoids firing the user-side `subscribe(cb)` listeners twice for
+    // the same mutation (optimistic mutate already fired them).
+    /** @internal */
+    applyRemoteOp(opBlob, opts) {
+        // A closed Document has freed its LoroDoc; a late transport closure (a
+        // reconnect/resync/reload that resolved after `close()`) must not import
+        // into freed WASM. Guard on `_closed` only, NOT `_suspended`: a parked
+        // doc keeps its LoroDoc alive and still applies remote ops.
+        if (this._closed)
+            return;
+        if (opts?.clientOpId && this._outstandingByClientId.has(opts.clientOpId)) {
+            // Echo of a local op: state is already up-to-date from the
+            // optimistic mutation; skip re-import to avoid double-fire on
+            // subscribers.
+            return;
+        }
+        this._doc.import(opBlob);
+    }
+    // Apply a snapshot blob over the top of an existing Document.
+    // Internal: the SDK calls this when the server delivers a fresh
+    // snapshot mid-session (e.g. after a compaction cycle). Persistence
+    // is server-authoritative, so there is no app-facing snapshot import.
+    /** @internal */
+    _applySnapshot(snapshot) {
+        // See `applyRemoteOp`: refuse the import on a closed (freed) doc so a late
+        // reload/resync closure can't touch freed WASM. `_closed` only; a parked
+        // doc still imports.
+        if (this._closed)
+            return;
+        this._doc.import(snapshot);
+        // The undo stack pre-snapshot referenced ops the new snapshot
+        // supersedes. Drop both stacks so undo doesn't try to revert
+        // into a state that no longer exists; the user's mental model
+        // here is "we just loaded fresh state", and silently retaining
+        // a now-broken redo entry would be the worst of both worlds.
+        if (this._undo)
+            this._undo.clear();
+    }
+    // Revert the most recent local commit. Returns `true` if an undo
+    // step was applied, `false` if the stack is empty. Remote peers'
+    // edits are not in this stack: Loro's UndoManager is local-peer-
+    // scoped, which is the user-visible behaviour every collaborative
+    // editor lands on (you don't get to undo your collaborator's typing).
+    //
+    // The reverted change is itself a local commit, so it ships over
+    // the WS transport like any other mutation and other peers see the
+    // state revert.
+    undo() {
+        this._assertOpen();
+        // During a checkout the UndoManager still tracks the live head, but reads
+        // go through the preview. Undoing would commit against the live `_doc` and
+        // ship over the WS transport while the previewing user sees nothing, a
+        // silent live edit. Match `canUndo()` (false during a checkout) and no-op.
+        if (this._checkout !== null)
+            return false;
+        // An undo produces a local commit exactly as `mutate` does, so it obeys
+        // the same read-only gates: a view-only guest link (`_forcedReadOnly`)
+        // and a pending content-replacing work-status (`_isLoadLocked()`), whose
+        // whole purpose is to keep local ops from racing the incoming bytes.
+        if (this._forcedReadOnly || this._isLoadLocked())
+            return false;
+        this._ensureLocalUpdatesSubscribed();
+        // Tag the commit the UndoManager is about to make so the resulting
+        // change reads back as `origin.source === 'undo'`, not `'local'`.
+        this._doc.setNextCommitOrigin(UNDO_COMMIT_ORIGIN);
+        return this._undo.undo();
+    }
+    // Re-apply the most recently undone local commit. Returns `true`
+    // if a redo step was applied, `false` if the stack is empty. The
+    // redo stack invalidates the moment a new local commit lands (the
+    // standard "fresh edit clears the redo branch" behaviour); remote
+    // edits do not clear redo, but Loro's UndoManager rebases redo
+    // entries against intervening remote state so the redone op
+    // composes correctly.
+    redo() {
+        this._assertOpen();
+        // No-op during a checkout, same reasoning as `undo()`.
+        if (this._checkout !== null)
+            return false;
+        // Same read-only gates as `undo()` / `mutate()`.
+        if (this._forcedReadOnly || this._isLoadLocked())
+            return false;
+        this._ensureLocalUpdatesSubscribed();
+        this._doc.setNextCommitOrigin(REDO_COMMIT_ORIGIN);
+        return this._undo.redo();
+    }
+    /**
+     * Seal the open undo group locally, so the NEXT local commit starts a
+     * fresh undo step. The doc-level path seals through checkpoints
+     * (`createCheckpoint` / the auto-checkpoint debounce); this is the
+     * boundary primitive a stream scope exposes directly, since streams
+     * carry no checkpoint machinery of their own.
+     * @internal
+     */
+    _sealUndoStep() {
+        if (this._undo)
+            this._undo.sealStep();
+    }
+    // Whether `undo()` would have an effect right now. Feeds the
+    // commands machinery and the undo-state notifier; apps consume it
+    // through `subscribeUndoState` snapshots.
+    canUndo() {
+        if (this._closed)
+            return false;
+        // During a checkout, the undo stack still tracks the live doc's
+        // history, but the UI is showing the historical preview and
+        // mutate is rejected. Surface that as "can't undo right now" so
+        // subscribeUndoState-bound buttons disable correctly.
+        if (this._checkout !== null)
+            return false;
+        // Fold the same read-only gates `undo()` enforces so a
+        // subscribeUndoState-bound button disables while the doc is a view-only
+        // guest link or load-locked, rather than inviting an undo the call
+        // would refuse.
+        if (this._forcedReadOnly || this._isLoadLocked())
+            return false;
+        return this._undo.canUndo();
+    }
+    // Whether `redo()` would have an effect right now. As above.
+    canRedo() {
+        if (this._closed)
+            return false;
+        if (this._checkout !== null)
+            return false;
+        if (this._forcedReadOnly || this._isLoadLocked())
+            return false;
+        return this._undo.canRedo();
+    }
+    // The plain-object proxy callers mutate. The mutation runs against
+    // the local LoroDoc immediately (optimistic UI), then commit + the
+    // `subscribeLocalUpdates` hook publish the resulting op blob over
+    // the WS transport when a `LocalOpSendHook` is installed.
+    //
+    // If no hook is installed (offline / migration script / unit tests),
+    // mutate still works but the op is not sent anywhere. This is the
+    // intentional escape hatch: `Brass.openDocumentById` wires the hook;
+    // `Document.create()` and direct construction stay
+    // hook-free so the class is usable without taking the WS dependency.
+    // `E` defaults to `EntityProxy` (the untyped Record<string, unknown>)
+    // for backwards-compat with existing callers. Apps with a typed
+    // entity shape pass it as a type argument:
+    //
+    //   doc.mutate<MyEntity>((d) => {
+    //     d.entities[id] = myTypedEntity;
+    //   });
+    //
+    // The mutator's `entities` field has the same proxy under the hood
+    // regardless of `E`; the generic exists purely to widen the type at
+    // the assignment site so closed interfaces don't need an
+    // `as Record<string, unknown>` cast.
+    mutate(fn) {
+        this._assertOpen();
+        if (this._checkout !== null) {
+            throw new Error('Document is read-only: it is showing a historical version. ' +
+                'Call `doc.returnToHead()` to edit.');
+        }
+        // A view-only share-link (guest) open is a live head held read-only:
+        // remote ops still stream in, but a local edit must be refused. The
+        // `_checkout` guard above only covers the version-pinned case, so this
+        // is a separate branch.
+        if (this._forcedReadOnly) {
+            throw new Error('Document is read-only: it was opened via a view-only share link.');
+        }
+        if (this._isLoadLocked()) {
+            throw new Error('Document is still loading its content; wait for the load to ' +
+                'finish before editing (see `doc.onStatus`).');
+        }
+        this._ensureLocalUpdatesSubscribed();
+        // A fresh proxy for the call, because the batcher rides it: the
+        // long-lived `this._entities` must stay batcher-free for the reads
+        // that go through it outside a mutation.
+        const batcher = new MutateBatcher(() => {
+            this._doc.setNextCommitOrigin(MUTATE_COMMIT_ORIGIN);
+            this._doc.commit();
+        });
+        fn({
+            entities: wrapLoroMapProxy(this._root, batcher),
+        });
+        // Stamp the commit so `subscribe`'s default path can identify
+        // and suppress the local-mutate echo. `setNextCommitOrigin`
+        // applies to the very next commit, and `commit()` consumes it.
+        this._doc.setNextCommitOrigin(MUTATE_COMMIT_ORIGIN);
+        this._doc.commit();
+    }
+    // Install / replace the local-op send hook; `null` detaches it.
+    //
+    // The hook is invoked synchronously from Loro's
+    // `subscribeLocalUpdates` callback, which fires immediately after
+    // `commit()` returns. The hook must be safe to call multiple times
+    // per `mutate()` call (a single mutation can produce multiple update
+    // batches if Loro splits them); each call gets its own clientOpId so
+    // the outstanding-op map stays correct.
+    /** @internal */
+    setLocalOpHook(hook) {
+        this._localOpHook = hook;
+        // Detach the underlying Loro subscriber when the hook is removed
+        // so a hook-free Document does not pay the per-commit callback
+        // cost. `_ensureLocalUpdatesSubscribed` re-attaches lazily.
+        if (!hook && this._unsubLocal) {
+            this._unsubLocal();
+            this._unsubLocal = null;
+        }
+    }
+    // Install / replace the transport's live-head-seq provider; `null`
+    // detaches it.
+    /** @internal */
+    setCurrentSeqProvider(provider) {
+        this._currentSeqProvider = provider;
+    }
+    // Install the historical-materialise fetcher used by
+    // `_checkoutVersion`. A Document without one rejects the checkout
+    // with a clear error.
+    /** @internal */
+    setCheckoutFetcher(fetcher) {
+        this._checkoutFetcher = fetcher;
+    }
+    /** @internal Whether a historical-materialise fetcher is installed, so a
+     * stream can tell whether it can preview (a guest line has none). */
+    _hasCheckoutFetcher() {
+        return this._checkoutFetcher !== null;
+    }
+    /** @internal Whether this Document is currently showing a historical
+     * preview rather than its live head. */
+    _isCheckedOut() {
+        return this._checkout !== null;
+    }
+    // Switch the Document to a historical version, in place. @internal
+    // (the hosted `history` command drives this). After the promise
+    // resolves, `doc.readOnly` is `true`,
+    // `doc.version` is the server's effective version (which may round
+    // down from the requested one when compaction has TTL'd the exact
+    // op), and `mutate` throws. `subscribe` fires once after the swap so
+    // the app's render loop redraws, and the app returns to live through
+    // the public `returnToHead()`.
+    //
+    // The live WS stream keeps applying remote ops to the underlying
+    // live Document in the background. `returnToHead()` clears the
+    // checkout in O(1); the live state is already current.
+    async _checkoutVersion(version) {
+        this._assertOpen();
+        if (this._isFrozen) {
+            throw new Error('_checkoutVersion: this Document was opened at a fixed version ' +
+                'and has no live channel.');
+        }
+        if (!Number.isInteger(version) || version < 0) {
+            throw new Error(`_checkoutVersion: invalid version ${version}`);
+        }
+        if (this._docId === null) {
+            throw new Error('_checkoutVersion: Document has no server identity');
+        }
+        if (this._branchId === null) {
+            throw new Error('_checkoutVersion: Document has no branch');
+        }
+        if (!this._checkoutFetcher) {
+            throw new Error('_checkoutVersion: no fetcher attached. Opened via the SDK factory?');
+        }
+        const generation = ++this._checkoutGeneration;
+        const { snapshotBytes, tailOpBlobs, effectiveVersion, streamSeqs } = await this._checkoutFetcher(this._docId, version, this._branchId);
+        if (this._closed || this._suspended)
+            return;
+        // A `returnToHead` or a newer `_checkoutVersion` fired while this fetch
+        // was in flight. Honour the latest intent: drop this stale result rather
+        // than clobbering the live head (or a newer checkout) the user asked for.
+        if (generation !== this._checkoutGeneration)
+            return;
+        this._checkoutStreamSeqs = streamSeqs ?? {};
+        // Materialise the preview into a fresh LoroDoc. The previous
+        // checkout's preview LoroDoc, if any, is freed.
+        const previewDoc = new LoroDoc();
+        if (snapshotBytes !== null)
+            previewDoc.import(snapshotBytes);
+        for (const blob of tailOpBlobs)
+            previewDoc.import(blob);
+        const previewRoot = previewDoc.getMap(this._rootKey);
+        const old = this._checkout;
+        this._checkout = {
+            previewDoc,
+            previewRoot,
+            version: effectiveVersion,
+        };
+        // Re-point the handles the app already holds at the preview doc and
+        // redraw them: the active source changed from the live doc to the
+        // preview, and an app renders off its `doc.map(key).subscribe(...)` /
+        // `doc.orderedMap(...)` handle (the primary read surface). Rebinding
+        // re-fires those subscribers with the historical container so the model
+        // updates in place, the same way a remote op or undo would. `doc.map` /
+        // `doc.list` reads follow the anchor, so they read the preview too.
+        this._rebindRootHandles(previewDoc);
+        // Free the previous preview only AFTER the rebind. `_rebindRootHandles`
+        // runs each active subscriber's `detach()`, which unsubscribes against the
+        // container captured at attach time (the OLD preview's); freeing first
+        // would run that detach against a freed LoroDoc. This is the same
+        // teardown-before-free order `close()` documents.
+        if (old && old.previewDoc !== this._doc) {
+            try {
+                old.previewDoc.free();
+            }
+            catch {
+                // ignore; already freed
+            }
+        }
+        this._fireSubscribers({ kind: 'checkout', version: effectiveVersion });
+        this._maybeFireUndoState();
+        // Preview every opened stream at the same point in time, so a
+        // partitioned document's history shows a consistent historical state
+        // across streams rather than a historical default over live streams.
+        await this._checkoutOpenStreams();
+    }
+    // Re-materialize each opened non-default stream at its seq recorded by the
+    // active preview's checkpoint. A stream with no recorded seq at this
+    // version (opened after the checkpoint, or before any checkpoint recorded
+    // one) returns to its own head, so it shows its earliest-known rather than
+    // a mismatched live state. Best-effort per stream: a stream whose inner
+    // has no checkout fetcher (a guest line, which has no token to fetch
+    // at-version) stays live. Failures are swallowed so one stream cannot
+    // break the doc-level preview.
+    async _checkoutOpenStreams() {
+        const seqs = this._checkoutStreamSeqs ?? {};
+        for (const [name, openPromise] of this._streamOpens) {
+            try {
+                const stream = await openPromise;
+                const lineId = this._streamManifest?.get(name)?.line_id;
+                const seq = lineId !== undefined ? seqs[lineId] : undefined;
+                await stream._previewAt(seq);
+            }
+            catch {
+                // A stream that failed to open or preview is left as-is.
+            }
+        }
+    }
+    /**
+     * Return to the live head. After this resolves, `readOnly` is
+     * `false`, `version` is `null`, `toJSON()` reads the live state,
+     * and `mutate` is accepted again. The live state has been kept
+     * current by the WS transport while the checkout was active, so
+     * there is no fetch involved. `subscribe` fires once.
+     *
+     * Kept as a method (not `_`-prefixed) only so the version-preview banner
+     * (`mountToolbar` / `mountHeader` / `mountVersionPreview`), which lives in
+     * the same package, calls it by name.
+     * @internal
+     */
+    returnToHead() {
+        this._assertOpen();
+        if (this._isFrozen) {
+            throw new Error('returnToHead: this Document was opened at a fixed version ' +
+                'and has no live channel to return to.');
+        }
+        // Bump first, unconditionally: a checkout fetch may be in flight with
+        // `_checkout` still null, and this is the signal that supersedes it when
+        // it resolves.
+        this._checkoutGeneration += 1;
+        if (this._checkout === null)
+            return;
+        const old = this._checkout;
+        this._checkout = null;
+        // Re-point the app's handles back at the live doc and redraw them,
+        // symmetrically with the checkout path, so the model returns to the live
+        // state in place.
+        this._rebindRootHandles(this._doc);
+        // Free the preview only after the rebind: `_rebindRootHandles` detaches
+        // each subscriber against the preview container it was attached to, so
+        // freeing first would be a use-after-free (see `_checkoutVersion`).
+        if (old.previewDoc !== this._doc) {
+            try {
+                old.previewDoc.free();
+            }
+            catch {
+                // ignore
+            }
+        }
+        this._fireSubscribers({ kind: 'return-to-head' });
+        this._maybeFireUndoState();
+        // Return every opened stream to its live head too, symmetric with the
+        // checkout path. Fire-and-forget (returnToHead is synchronous and has no
+        // fetch): a stream not previewing is a no-op.
+        this._checkoutStreamSeqs = null;
+        for (const openPromise of this._streamOpens.values()) {
+            void openPromise
+                .then((stream) => stream._previewAt(undefined))
+                .catch(() => {
+                // A stream that failed to open has nothing to return.
+            });
+        }
+    }
+    // Re-point every cached root handle at the corresponding container in
+    // `source` (the live doc or a checkout preview) and resync its subscribers.
+    // The app holds these same handle objects, so this is what makes a version
+    // checkout / return redraw the model without the app re-acquiring handles.
+    // `getMap` / `getList` are get-or-create, so a container absent in the
+    // preview resolves to an empty one and its subscribers redraw to empty.
+    _rebindRootHandles(source) {
+        // Two passes, not one per handle: rebind every anchor to the new source
+        // first, then resync. A composed handle can read a sibling root while
+        // firing (the ordered map reads its order list during its map redraw), so
+        // every anchor must already point at the new source before any handle
+        // fires, or the redraw reads a half-swapped map/order pair.
+        for (const entry of this._rootHandles.values()) {
+            if (entry.kind === 'map') {
+                rebindRootMapAnchor(entry.handle, source.getMap(entry.key));
+            }
+            else {
+                rebindRootListAnchor(entry.handle, source.getList(entry.key));
+            }
+        }
+        for (const entry of this._rootHandles.values()) {
+            resyncRootHandle(entry.handle);
+        }
+    }
+    /**
+     * Fork a new branch from a historical version and switch to it. Drives
+     * the hosted version-preview bar's "Branch from here".
+     * @internal
+     */
+    _forkFromVersion(fromVersion, name) {
+        return this._commandMenu.forkFromVersion(fromVersion, name);
+    }
+    // ---------------------------------------------------------------------
+    // Branches
+    // ---------------------------------------------------------------------
+    // Internal: the current branch's display name when the doc is on a
+    // NON-default branch, else null. The SDK's own chrome (the toolbar
+    // branch chip, the page title) reads this to tell the user they are on
+    // a branch. @internal
+    _currentBranchName() {
+        const branchId = this._branchId;
+        const defaultBranchId = this._branchCtl.defaultBranchId;
+        if (!branchId || !defaultBranchId || branchId === defaultBranchId) {
+            return null;
+        }
+        return (this._branchCtl.branches.find((b) => b.branch_id === branchId)?.name ??
+            null);
+    }
+    // Internal: the doc's default-branch id once the list has loaded, else
+    // null. The session's URL sync reads this to keep `?branch=` off the
+    // URL for the default branch. Not app-facing.
+    /** @internal */
+    _defaultBranchId() {
+        return this._branchCtl.defaultBranchId;
+    }
+    // Internal: set the branches list. Fires `doc.subscribe` if the
+    // value changed.
+    /** @internal */
+    _setBranches(branches, defaultBranchId) {
+        this._branchCtl.set(branches, defaultBranchId);
+    }
+    // Install the branch provider (HTTP capability); `null` detaches it.
+    // Wired by the SDK factory; the hosted branch chrome reaches the wire
+    // through this controller.
+    /** @internal */
+    setBranchProvider(provider) {
+        this._branchCtl.setProvider(provider);
+    }
+    // Internal: re-fetch the branches list. Called by the factory on open
+    // (to populate the name the chip renders) and by the hosted branch
+    // dialog after a mutation. Not app-facing.
+    /** @internal */
+    async _refreshBranches() {
+        return this._branchCtl.refresh();
+    }
+    // ---------------------------------------------------------------------
+    // Thumbnail auto-capture
+    // ---------------------------------------------------------------------
+    // Register a canvas the SDK screenshots as the document's
+    // thumbnail. Capture is debounced after each local edit; remote
+    // edits and read-only / checkout state do not trigger a capture
+    // (a viewer or a passive collaborator never re-uploads someone
+    // else's frame). Pass the canvas element directly, or a getter
+    // for apps that build / rebuild it lazily.
+    //
+    // Returns an unregister handle. Re-registering replaces; the
+    // previous canvas is forgotten.
+    useCanvas(source) {
+        // Arm the lazy Loro subscriber so local-commit events reach the
+        // capture collaborator's `schedule()`. Idempotent.
+        this._ensureLoroSubscribed();
+        return this._thumbnails.useCanvas(source);
+    }
+    // Install the thumbnail upload hook; `null` detaches.
+    /** @internal */
+    setThumbnailUploader(uploader) {
+        this._thumbnails.setUploader(uploader);
+    }
+    // Install the checkpoint-create hook; `null` detaches.
+    /** @internal */
+    setCheckpointCreator(creator) {
+        this._checkpoints.setCreator(creator);
+    }
+    // Install the drive-push hook; `null` detaches.
+    /** @internal */
+    setDrivePusher(pusher) {
+        this._drivePusher = pusher;
+    }
+    // Install the drive-resolve hook; `null` detaches. Mirrors
+    // `setDrivePusher`.
+    /** @internal */
+    setDriveResolver(resolver) {
+        this._driveResolver = resolver;
+    }
+    // Install the source-blob fetch hook. Mirrors `setDrivePusher`.
+    /** @internal */
+    setSourceBlobFetcher(fetcher) {
+        this._sourceBlobFetcher = fetcher;
+    }
+    // Publish this document's current state back to its drive source.
+    // Lets an app code one line on save / on a commit button to make its
+    // edits visible to people working outside Brass on the same source:
+    //
+    //   await doc.pushToDrive({ message: 'Wall move' });
+    //
+    // The platform publishes the doc's current state, overwriting the
+    // source (unknown drive fields preserved), and marks its own write so
+    // the inbound change-event drops it (no echo loop). It does not merge
+    // concurrent drive-side edits. Throws on auth / link / write
+    // failures; resolves with the new external ref and the published
+    // entity count.
+    async pushToDrive(input) {
+        this._assertOpen();
+        if (this._docId === null) {
+            throw new Error('pushToDrive: Document has no server identity');
+        }
+        if (this._drivePusher === null) {
+            throw new Error('pushToDrive: no pusher attached. Opened via the SDK factory?');
+        }
+        return await this._drivePusher(input ?? {});
+    }
+    // Resolve a `behind` / `diverged` drive-linked doc by opening the
+    // hosted resolution surface, so an app can offer pull (take the source)
+    // / keep both alongside the publish-over that `pushToDrive` does:
+    //
+    //   if (doc.driveStatus?.state === 'diverged') await doc.resolveDrive();
+    //
+    // Unlike `pushToDrive`, the resolution can mint a NEW mirror doc that
+    // takes over the drive link (take-source trashes this doc, keep-both
+    // detaches it into a standalone fork). For a session-backed app the
+    // SDK re-opens onto that new doc automatically (the resolver routes it
+    // through the same `openSiblingDoc` path the history fork uses); the
+    // returned `newDocId` lets a multi-doc app do its own switch. Resolves
+    // with the outcome, or `null` when the user dismissed the dialog.
+    // Throws when there is no doc identity or no resolver is attached.
+    async resolveDrive() {
+        this._assertOpen();
+        if (this._docId === null) {
+            throw new Error('resolveDrive: Document has no server identity');
+        }
+        if (this._driveResolver === null) {
+            throw new Error('resolveDrive: no resolver attached. Opened via the SDK factory?');
+        }
+        return await this._driveResolver();
+    }
+    // Fetch the original file behind an opaque-blob document: a short-lived
+    // presigned GET plus the file's name / content type / size. An app that
+    // knows the format fetches the bytes from `url`, parses them, and writes
+    // the structured content into this document through the normal handle
+    // surface (`doc.map('instances').mutate(...)`):
+    //
+    //   const src = await doc.sourceBlob();
+    //   const bytes = new Uint8Array(await (await fetch(src.url)).arrayBuffer());
+    //   const records = parseMyFormat(bytes); // app's own parser
+    //   doc.map('instances').mutate((m) => { for (const r of records) m[r.id] = r; });
+    //
+    // A source file is a set of one or more streams: `src.streams` lists
+    // every stream (primary first, so a single-stream file has one entry),
+    // each with its own URL, so a multi-stream format (a glTF with its
+    // `.bin` buffer) fetches only the streams it needs.
+    //
+    // Rejects with a `BrassError` when the document is not a stored opaque
+    // blob (it has no original file to hand back) or the caller cannot
+    // reach it (both 404).
+    async sourceBlob() {
+        this._assertOpen();
+        if (this._docId === null) {
+            throw new Error('sourceBlob: Document has no server identity');
+        }
+        if (this._sourceBlobFetcher === null) {
+            throw new Error('sourceBlob: no fetcher attached. Opened via the SDK factory?');
+        }
+        return await this._sourceBlobFetcher();
+    }
+    // ---------------------------------------------------------------------
+    // Streams
+    // ---------------------------------------------------------------------
+    // Stream wiring, installed by the SDK open factory; `null` on
+    // offline / test docs (stream methods then throw with a clear
+    // message). The manifest cache maps stream name -> info; opens are
+    // cached per name so `doc.stream('hvac')` is one join + subscribe
+    // however many times it is called.
+    _streamRuntime = null;
+    _streamManifest = null;
+    _streamOpens = new Map();
+    _ownStream = null;
+    // Which stream this Document's own handles read. An open names a stream
+    // and the usual one has a default, so `default` is a name here rather
+    // than a case: opening at `geometry` makes `doc.map(...)` read geometry
+    // and `doc.stream('geometry')` resolve to this Document.
+    _openedStreamName = DEFAULT_STREAM_NAME;
+    // Install the stream runtime; `null` detaches. Mirrors `setDrivePusher`.
+    /** @internal */
+    setStreamRuntime(runtime) {
+        this._streamRuntime = runtime;
+    }
+    /** @internal Name the stream this Document was opened at. Set by the SDK
+     *  open factory; defaults to `default`. */
+    setOpenedStreamName(name) {
+        this._openedStreamName = name;
+    }
+    /** The stream this Document's own handles read. */
+    get openedStream() {
+        return this._openedStreamName;
+    }
+    // Open one stream of this document, by name. Only the streams an app
+    // touches are downloaded, imported, and subscribed, so a partitioned
+    // document opens at the cost of what is used, not its total size:
+    //
+    //   const hvac = await doc.stream('hvac');
+    //   const records = hvac.orderedMap('instances', 'instance_order');
+    //
+    // The name this Document was opened at (`'default'` unless the open said
+    // otherwise) resolves to its own state, the same containers
+    // `doc.map(...)` reads, with no network. That is what lets code iterate
+    // stream names over partitioned and unpartitioned documents with one
+    // path. Repeat calls return the same open (one join + subscribe per
+    // stream per Document).
+    //
+    // Opening READS. A name the document does not hold rejects rather than
+    // being created, so code that only reads cannot mint a stream by
+    // probing for one; `getOrCreateStream` is the call that writes.
+    stream(name) {
+        // Sync method returning a Promise: reject rather than throw, so a
+        // caller chaining `.catch()` without `await` still sees the failure.
+        if (!this._isLive) {
+            return Promise.reject(new Error('Document is closed'));
+        }
+        // The stream this Document already IS. No network: its state is the
+        // state these handles read.
+        if (name === this._openedStreamName) {
+            this._ownStream ??= new DocumentStream(name, this, false);
+            return Promise.resolve(this._ownStream);
+        }
+        const cached = this._streamOpens.get(name);
+        if (cached)
+            return cached;
+        const runtime = this._streamRuntime;
+        if (runtime === null) {
+            return Promise.reject(new Error('stream: no runtime attached. Opened via the SDK factory?'));
+        }
+        const open = (async () => {
+            const info = await this._resolveStreamInfo(runtime, name);
+            if (!info) {
+                throw new Error(`This document has no stream named "${name}". ` +
+                    `doc.getOrCreateStream(${JSON.stringify(name)}) makes one.`);
+            }
+            // Only a CRDT stream opens as live collaborative state. Any other
+            // value fails loudly here rather than joining a line that is not
+            // one, so a format added after this SDK shipped is refused by the
+            // version that cannot read it.
+            if (info.format !== 'crdt') {
+                throw new Error(`Stream "${name}" has format "${info.format}", which this ` +
+                    'SDK version cannot open as a live stream.');
+            }
+            const inner = await runtime.openLine(info.line_id);
+            const stream = new DocumentStream(name, inner, true);
+            // Opened while a version preview is active: bring the new stream to
+            // the same point in time rather than showing it live under a
+            // historical default.
+            if (this._checkout !== null) {
+                await stream._previewAt(this._checkoutStreamSeqs?.[info.line_id]);
+            }
+            return stream;
+        })();
+        this._streamOpens.set(name, open);
+        // A failed open (network, deleted stream) must not poison the cache:
+        // drop it so the next call retries.
+        open.catch(() => {
+            if (this._streamOpens.get(name) === open)
+                this._streamOpens.delete(name);
+        });
+        return open;
+    }
+    // Open the document's stream of that name, making it when the document
+    // does not hold it yet. This is the call that WRITES: `stream` only
+    // reads, so no read path can bring a stream into being.
+    //
+    // Two collaborators reaching for the same name converge on one stream
+    // rather than one of them failing, so an app reaches for the stream it
+    // expects on every open without checking first.
+    async getOrCreateStream(name) {
+        this._assertOpen();
+        // The stream this Document already IS needs no create: it exists by the
+        // time the document is open. Asking the server would spend a
+        // branch-write budget on a reach whose answer is already in hand, which
+        // matters because an app loops its declared stream names on every open.
+        if (name === this._openedStreamName)
+            return this.stream(name);
+        const runtime = this._streamRuntime;
+        if (runtime === null) {
+            throw new Error('getOrCreateStream: no runtime attached. Opened via the SDK factory?');
+        }
+        let info;
+        try {
+            info = await runtime.create(name);
+        }
+        catch (err) {
+            // Losing the create means someone else made this stream between our
+            // read and our write, which is the same outcome we wanted, so resolve
+            // theirs. Recognising the loss by re-reading rather than by matching a
+            // status code keeps the app out of the race entirely: a rejection that
+            // is NOT the race (no permission, doc gone) finds no stream and
+            // rethrows untouched.
+            const existing = await this._resolveStreamInfo(runtime, name);
+            if (!existing)
+                throw err;
+            info = existing;
+        }
+        (this._streamManifest ??= new Map()).set(info.name, info);
+        return this.stream(info.name);
+    }
+    // Every stream the document holds, `default` included (it is an ordinary
+    // manifest entry). Fetches fresh so a stream a collaborator just created
+    // is visible.
+    async listStreams() {
+        this._assertOpen();
+        const runtime = this._streamRuntime;
+        if (runtime === null) {
+            throw new Error('listStreams: no runtime attached. Opened via the SDK factory?');
+        }
+        const streams = await runtime.list();
+        this._streamManifest = new Map(streams.map((s) => [s.name, s]));
+        return streams;
+    }
+    async _resolveStreamInfo(runtime, name) {
+        const cached = this._streamManifest?.get(name);
+        if (cached)
+            return cached;
+        const streams = await runtime.list();
+        this._streamManifest = new Map(streams.map((s) => [s.name, s]));
+        return this._streamManifest.get(name);
+    }
+    // Close every opened stream's own transport + state. Streams opened
+    // while this Document was live do not outlive it.
+    _closeStreams() {
+        for (const open of this._streamOpens.values()) {
+            void open.then((s) => s._close()).catch(() => {
+                // A failed open has nothing to close.
+            });
+        }
+        this._streamOpens.clear();
+        this._streamManifest = null;
+    }
+    // Seal a deliberate checkpoint on this document's version-
+    // history timeline. Compaction snapshots continue to appear as
+    // no-action fallback markers, so an app that never calls this still
+    // gets a usable history.
+    //
+    // Anchors to `doc.currentSeq` synchronously, so a concurrent
+    // editor's op landing mid-call cannot shift the anchor. Pass an
+    // explicit `version` to seal at a different point in history (the
+    // server validates it's `<=` the branch's live head).
+    async createCheckpoint() {
+        return this._checkpoints.create();
+    }
+    // Configure the implicit auto-checkpoint debounce. Default is 60s
+    // after the last local edit; pass `0` to disable. Apps in test
+    // contexts (deterministic clocks) or apps with a different "natural
+    // pause" rhythm (a slow turn-based tool, a CAD modeler with multi-
+    // second operations) tune this. Returning the prior value lets a
+    // test or scoped override restore.
+    setAutoCheckpointIntervalMs(intervalMs) {
+        return this._checkpoints.setAutoIntervalMs(intervalMs);
+    }
+    // ---------------------------------------------------------------------
+    // File-menu commands (per-doc)
+    // ---------------------------------------------------------------------
+    // The doc's display name. `null` on offline / test docs.
+    get name() {
+        return this._name;
+    }
+    // Internal: set the cached name. Fires a `'commands'` subscribe
+    // event so apps re-render the menu trigger without an app-side
+    // refresh.
+    /** @internal */
+    _setName(name) {
+        if (this._name === name)
+            return;
+        this._name = name;
+        this._fireSubscribers({ kind: 'commands' });
+    }
+    /** @internal */
+    setHostedUiProvider(provider) {
+        this._commandMenu.setHostedUiProvider(provider);
+    }
+    // The per-doc file menu, as data. Each Document carries its own list
+    // with its own `running` state; multi-doc apps render one menu per
+    // pane. The app filters by `surface` ('menu' | 'toolbar') to place
+    // each command into its own chrome.
+    get commands() {
+        return this._commandMenu.commands;
+    }
+    // Invoke a command by id. A convenience for keyboard shortcuts
+    // (`Ctrl-Z` -> `doc.run('undo')`). No-op for an unknown id.
+    async run(commandId) {
+        return this._commandMenu.run(commandId);
+    }
+    // Optional error sink for the doc's built-in commands. `null` falls
+    // back to `console.error`.
+    /** @internal */
+    setErrorReporter(reporter) {
+        this._errorReporter = reporter;
+        this._commandMenu.setErrorReporter(reporter);
+    }
+    _reportError(err) {
+        if (this._errorReporter)
+            this._errorReporter(err);
+        else
+            console.error('[Brass]', err);
+    }
+    // Fire all `subscribe` listeners with a synthetic event. Used for
+    // metadata-only changes (checkout, return-to-head, branch switch,
+    // branches list update, saving count change, commands change)
+    // that don't originate from a Loro commit but still need the app
+    // to re-read state. Apps typically ignore the event arg and just
+    // call `toJSON()` in the handler; the discriminant is there for
+    // the rare consumer that wants to branch on the reason.
+    _fireSubscribers(event) {
+        this._ensureLoroSubscribed();
+        this._subs.emit(event);
+    }
+    // Saving indicator: number of locally-issued ops not yet acked by
+    // the server. Reactive: `subscribe` fires when this count changes
+    // (an op is sent or an `op_ack` lands). Apps bind directly inside
+    // the subscribe handler:
+    //
+    //   doc.subscribe(() => {
+    //     savingEl.textContent =
+    //       doc.savingCount === 0 ? 'All changes saved'
+    //                             : `Saving ${doc.savingCount} change${doc.savingCount === 1 ? '' : 's'}...`;
+    //   });
+    get savingCount() {
+        return this._outstandingByClientId.size;
+    }
+    // Internal: forget an outstanding op once the server has acked it.
+    // Returns true if the clientOpId was tracked (lets the caller detect
+    // a stale ack).
+    /** @internal */
+    resolveOutstandingOp(clientOpId) {
+        const wasTracked = this._outstandingByClientId.delete(clientOpId);
+        // Release this chunk from the resync-push loop guard once its op is
+        // acked: the pushed op is now in the log, so the next handshake's
+        // tail covers it and a fresh push is welcome (it would be a genuine
+        // new hole, not a re-push of this one). The guard fully reopens only
+        // once every chunk of the push has drained.
+        this._resyncPushClientOpIds.delete(clientOpId);
+        if (wasTracked)
+            this._fireSubscribers({ kind: 'saving-count' });
+        return wasTracked;
+    }
+    // Internal: forget an outstanding op the server TERMINALLY rejected (an
+    // `op_rejected` frame: the op can never be accepted, e.g. it exceeded the
+    // server's op-blob cap), as opposed to `resolveOutstandingOp`'s success. The
+    // transport clears its resend timer; this drops the tracker entry so
+    // `savingCount` stops counting a dead op, and surfaces the failure so the
+    // app can react (the optimistic local commit stays applied but never
+    // persists, so the app's cue is to reload). Returns true if it was tracked.
+    /** @internal */
+    _failOutstandingOp(clientOpId, message) {
+        const wasTracked = this._outstandingByClientId.delete(clientOpId);
+        this._resyncPushClientOpIds.delete(clientOpId);
+        if (wasTracked) {
+            this._fireSubscribers({ kind: 'saving-count' });
+            this._reportError(new Error(message));
+        }
+        return wasTracked;
+    }
+    _ensureLocalUpdatesSubscribed() {
+        if (this._unsubLocal)
+            return;
+        if (!this._localOpHook)
+            return;
+        // Loro's `subscribeLocalUpdates` fires after every local commit
+        // with the op-blob bytes for that commit. Importing a remote op
+        // does NOT trigger this callback, so we don't risk feeding the
+        // same op back to the server in a loop.
+        this._unsubLocal = this._doc.subscribeLocalUpdates((bytes) => {
+            const hook = this._localOpHook;
+            if (!hook)
+                return;
+            // Copy: Loro reuses its internal buffer across callback calls in
+            // some builds. Hand the consumer a stable view so the eventual
+            // WS send sees the correct bytes regardless of when the send
+            // actually flushes (the WS client may queue the frame).
+            const copy = new Uint8Array(bytes.byteLength);
+            copy.set(bytes);
+            const clientOpId = hook(copy);
+            this._outstandingByClientId.set(clientOpId, copy);
+            // The local mutate has already fired `subscribe` (the Loro
+            // event), but `savingCount` just incremented; fire one more
+            // synthetic event so a subscribe handler bound on `savingCount`
+            // sees the change.
+            this._fireSubscribers({ kind: 'saving-count' });
+        });
+    }
+    // Lazy-attach the underlying LoroDoc subscriber. **Do not** wire this
+    // in the constructor or before the initial snapshot import: with a
+    // subscriber attached, snapshot-import of a 50k doc takes ~8.5 s
+    // because Loro walks the full event tree to deliver per-container
+    // deltas. Lazy-attach drops 50k cold-load to ~280 ms.
+    _ensureLoroSubscribed() {
+        // Never re-attach after close: `close()` nulls `_unsubLoro` and then
+        // frees the underlying LoroDoc, so subscribing here would call into freed
+        // WASM. Not every `_fireSubscribers` caller is transport-driven or
+        // guarded: `_setName` runs from an open-time `refreshName(...).then(...)` with no
+        // liveness re-check, and a default-branch `close()` frees the doc
+        // immediately (no park), so a name fetch resolving after close reaches
+        // here on a freed doc. The `_unsubLoro` short-circuit alone does not cover
+        // it: close set it to null.
+        if (this._closed)
+            return;
+        if (this._unsubLoro)
+            return;
+        this._unsubLoro = this._doc.subscribe((event) => {
+            // One channel: every event reaches every subscriber, whatever
+            // produced it. The app reconciles by value and reads the cause off
+            // the event only when it has a non-render reason to.
+            this._subs.emit(event);
+            const isLocalCommit = event.by === 'local';
+            this._maybeFireUndoState();
+            // A local commit (mutate / undo / redo) schedules a debounced
+            // thumbnail capture, when the app has registered a canvas via
+            // `useCanvas`. Remote ops never trigger a capture: a viewer or
+            // a passive collaborator must not re-upload a screenshot of
+            // someone else's edit.
+            if (isLocalCommit) {
+                this._thumbnails.schedule();
+                // Same reasoning for the implicit auto-checkpoint: only the
+                // peer that made the edit seals the marker. Without this an
+                // N-way session would write N redundant CHECKPOINT# rows per
+                // idle period.
+                this._checkpoints.scheduleAuto();
+            }
+        });
+    }
+    // Subscribe to document events. Returns an unsubscribe handle.
+    // Lazy-attaches the underlying Loro subscriber on first call so
+    // construction stays cheap.
+    //
+    // `cb` fires for EVERY change, whatever produced it: a local `mutate()`,
+    // a remote `import`, `undo`, `redo`, `checkout`, and the SDK's synthetic
+    // metadata events (saving-count, branches, commands). One channel; the
+    // app re-reads / reconciles in the handler and branches on the event only
+    // when it needs the cause. CRDT-origin events keep their Loro shape and
+    // carry `by` / `origin` so the cause is recoverable; the engine-neutral
+    // `origin.source` lives on the handle surface.
+    subscribe(cb) {
+        this._assertOpen();
+        this._ensureLoroSubscribed();
+        return this._subs.on(cb);
+    }
+    // Subscribe to changes in undo/redo enabled state. Fires once
+    // synchronously on registration with the current values, then
+    // again whenever either value flips (after a local mutate, an
+    // undo / redo, or a remote import that landed an op of this
+    // peer's). The push covers local mutates, which the regular
+    // `subscribe(cb)` suppresses as local echo, so a button bound
+    // here stays current while the user types, regardless of what
+    // produced the change.
+    //
+    // Returns an unsubscribe handle. The callback is invoked with
+    // `{ canUndo, canRedo }`; only fires when at least one value
+    // differs from the prior fire.
+    //
+    // Wire it once in your editor bind step:
+    //
+    //   const stop = doc.subscribeUndoState(({ canUndo, canRedo }) => {
+    //     undoBtn.disabled = !canUndo;
+    //     redoBtn.disabled = !canRedo;
+    //   });
+    //
+    // Lifecycle: throws on a closed Document; cleared on close /
+    // suspend like every other app-side subscriber.
+    subscribeUndoState(cb) {
+        this._assertOpen();
+        this._ensureLoroSubscribed();
+        this._undoStateSubs.add(cb);
+        // Fire immediately with current state so the consumer does
+        // not need separate initial-paint code. Capture the values
+        // BEFORE registering as the baseline, so the first underlying
+        // event fires the subscriber only when the value actually
+        // changes from this initial fire.
+        const state = {
+            canUndo: this.canUndo(),
+            canRedo: this.canRedo(),
+        };
+        this._lastCanUndo = state.canUndo;
+        this._lastCanRedo = state.canRedo;
+        try {
+            cb(state);
+        }
+        catch {
+            // A throwing initial callback must not strand the registration;
+            // returning the unsub handle lets the app recover.
+        }
+        return () => {
+            this._undoStateSubs.delete(cb);
+        };
+    }
+    // Internal: fire `_undoStateSubs` if canUndo / canRedo flipped.
+    // Called from `_ensureLoroSubscribed`'s event dispatch.
+    _maybeFireUndoState() {
+        if (this._undoStateSubs.size === 0)
+            return;
+        const canUndo = this.canUndo();
+        const canRedo = this.canRedo();
+        if (canUndo === this._lastCanUndo && canRedo === this._lastCanRedo) {
+            return;
+        }
+        this._lastCanUndo = canUndo;
+        this._lastCanRedo = canRedo;
+        const state = { canUndo, canRedo };
+        for (const cb of this._undoStateSubs) {
+            try {
+                cb(state);
+            }
+            catch {
+                // A throwing subscriber must not affect the others.
+            }
+        }
+    }
+    // Register a callback that fires exactly once when the server
+    // tells this Document its underlying doc has been evicted (today:
+    // soft-delete via the hosted Delete tab or the underlying
+    // `DELETE /documents/:docId` API; future: revoked membership,
+    // organization deletion cascade). Late-attached listeners fire
+    // synchronously on registration if the gone event already happened.
+    //
+    // The Document is NOT auto-closed; callers may want to render a
+    // "the document was deleted" overlay before closing. Disable any
+    // pending mutations in the listener and call `close()` when ready.
+    // Mutations after `_markGone` still mutate the local CRDT and call
+    // the `LocalOpHook`, but the server will reject those op frames
+    // (the SUB# row was evicted at fanout time); the SDK consumer
+    // sees the rejection via the underlying transport's error channel.
+    onGone(cb) {
+        // Guard like `subscribe` / `subscribeUndoState`: `_suspend` clears these
+        // signals' listeners so a stale handle from a parked session does not
+        // receive the next session's events. Without this throw a listener wired
+        // onto a closed/suspended handle would attach and survive into the resumed
+        // open (which reuses the same cached Document), the exact cross-session
+        // leak `_suspend` sets out to prevent.
+        this._assertOpen();
+        return this._gone.on(cb);
+    }
+    // The latest opaque work-status for this document, or `null` when no
+    // slow server-side work is in flight. An app renders `message`
+    // verbatim, draws a bar from `progress` when present, and shows a
+    // waiting state while `pending`. When a freshly-opened drive-linked
+    // doc is still hydrating, `open()` surfaces the initial `pending`
+    // status here; subsequent phases arrive via `onStatus`.
+    get status() {
+        return this._workStatus.status;
+    }
+    // Subscribe to opaque work-status updates. The callback fires on
+    // every phase the server pushes; when `status.pending` flips to
+    // `false` the work is terminal (a success the app reacts to by
+    // re-opening the doc to load the now-available content, or a failure
+    // whose `message` the app shows). Fires once on attach with the
+    // current status when one is already known, so a late subscriber is
+    // not stranded. Returns an unsubscribe.
+    //
+    // The app must not parse `message` or infer phases from it: the
+    // server owns the wording and the lifecycle. This surface exists so
+    // the app can *display* progress, not understand it.
+    onStatus(cb) {
+        // See `onGone`: guard the cross-session listener leak.
+        this._assertOpen();
+        return this._workStatus.on(cb);
+    }
+    // Internal: store the latest status and fire listeners. Not
+    // one-shot: every phase re-emits. A terminal status (`pending:
+    // false`) is retained so a late `onStatus` subscriber still sees the
+    // final state.
+    /** @internal */
+    _emitStatus(status) {
+        // A late reload/reconcile closure that resolved after `close()` must not
+        // re-emit onto a torn-down doc (its undo stack is freed below in `close`).
+        if (this._closed)
+            return;
+        this._workStatus.emit(status);
+        // A blocking work-status is one of the inputs to `canUndo` / `canRedo`
+        // (via `_isLoadLocked`), so a status that engages or releases the load
+        // lock flips the undo/redo availability with no accompanying commit.
+        // Refresh the undo-state notifier here so a subscribeUndoState-bound
+        // button tracks the lock, not only CRDT edits.
+        this._maybeFireUndoState();
+    }
+    // The current drive sync state of this document, or `null` when the
+    // doc is not linked to a drive source. The read-side companion to
+    // `doc.pushToDrive(...)`: an app reads `canPush` / `state` to decide
+    // whether to surface a "Publish" affordance, and renders the
+    // server-authored `label` / `detail` as the wording. Seeded on open
+    // (for a drive-linked doc) and kept live as edits, refreshes, and
+    // pushes move the state.
+    get driveStatus() {
+        return this._driveStatus.status;
+    }
+    // Subscribe to drive sync-state changes. Fires once on attach with
+    // the current state when one is already known, then on every change
+    // (an edit flipping the doc to `ahead`, a push re-syncing it, the
+    // source moving it to `behind`). De-duped server-state-side: a
+    // METADATA change that did not move the sync state does not re-fire.
+    // Returns an unsubscribe.
+    //
+    // As with `onStatus`, the app must not parse `label` / `detail`: the
+    // server owns the wording. Branch only on `state` / `canPush`.
+    onDriveStatus(cb) {
+        // See `onGone`: guard the cross-session listener leak.
+        this._assertOpen();
+        return this._driveStatus.on(cb);
+    }
+    // Internal: store the latest drive state and fire listeners,
+    // skipping a no-op re-emit.
+    /** @internal */
+    _emitDriveStatus(status) {
+        if (this._closed)
+            return;
+        this._driveStatus.emit(status);
+    }
+    // Internal: mark the doc evicted. Idempotent (multiple frames arrive
+    // for the same doc when both `doc:<id>` and `presence:doc:<id>`
+    // topics fan out; we collapse them so the user-side `onGone`
+    // listener fires exactly once).
+    /** @internal */
+    _markGone(reason) {
+        // An evicted doc's outstanding local ops can never ack (the transport
+        // cancels their resend timers on `doc_gone`), so stop counting them as
+        // "saving": without this the doc renders "no longer available" and
+        // "Saving N changes…" at once until `close()`.
+        if (this._outstandingByClientId.size > 0) {
+            this._outstandingByClientId.clear();
+            this._resyncPushClientOpIds.clear();
+            this._fireSubscribers({ kind: 'saving-count' });
+        }
+        this._gone.mark(reason);
+    }
+    // Plain-JS projection of the current state.
+    toJSON() {
+        // When in checkout, read from the preview LoroDoc so the app
+        // renders the historical state. Returning to head clears
+        // `_checkout` and reads go back to the live `_doc`.
+        const source = this._checkout !== null ? this._checkout.previewDoc : this._doc;
+        return source.toJSON();
+    }
+    /**
+     * Snapshot bytes; inverse of `openFromSnapshot`, for round-trip tests.
+     * @internal
+     */
+    _exportSnapshot() {
+        return this._doc.export({ mode: 'snapshot' });
+    }
+    // Durability handshake (see `wireDocTransport`'s `doc_init` handler).
+    //
+    // Run the handshake and push the missing slice if there is one. Shared
+    // by the `doc_init` (reconnect) path and the `doc_ops_dropped`
+    // (prompt-notification) path, so the loop guard lives here rather than
+    // in either caller. No-op when the durable frontier already covers the
+    // local doc, while a prior resync push is still unacked, or when the
+    // missing slice is too large to ship as one op (see the cap below).
+    /** @internal */
+    maybeResyncPush(persistedSnapshotVersionVector, durableTailBlobs) {
+        // `computeResyncPush` reads `this._doc.version()` / `export()`; refuse on a
+        // closed (freed) doc so a late `doc_ops_dropped` / periodic-reverify
+        // closure can't touch freed WASM.
+        if (this._closed)
+            return;
+        // Loop guard: skip while any chunk of a prior push is still unacked,
+        // so a flurry of reconnects cannot re-push the same missing slice.
+        for (const id of this._resyncPushClientOpIds) {
+            if (this._outstandingByClientId.has(id))
+                return;
+        }
+        const chunks = this.computeResyncPush(persistedSnapshotVersionVector, durableTailBlobs);
+        if (chunks === null)
+            return;
+        for (const chunk of chunks) {
+            const id = this.injectLocalUpdate(chunk);
+            if (id !== null)
+                this._resyncPushClientOpIds.add(id);
+        }
+    }
+    // Given the server's persisted snapshot version vector and the op
+    // blobs the server is also serving on the join tail, decide whether
+    // this client holds CRDT knowledge the durable server state lacks,
+    // and if so return the update blob that fills exactly those holes.
+    //
+    // The durable frontier is the snapshot's version vector advanced by
+    // every tail op the server delivered (those ops are durable in the
+    // log even though no snapshot has absorbed them yet). Comparing the
+    // local doc against the SNAPSHOT vector alone would falsely flag the
+    // whole durable tail as missing and push it back on every join, which
+    // then grows the log and loops; folding the tail in is what keeps the
+    // handshake a no-op in the common "server already has everything"
+    // case. `decodeImportBlobMeta` reads each blob's end vector from its
+    // header without a full import, so this stays cheap.
+    //
+    // Returns the chunks to resync-push, or null when the durable state
+    // already covers everything local holds (or a malformed vector / tail
+    // blob, which degrades the handshake to a no-op and warns rather than
+    // throwing out of the frame handler that drives the live transport).
+    //
+    // The common case is one chunk: an `update` export from the durable
+    // frontier carries only the missing ops plus their dependencies, never
+    // the whole history, and a realistic gap is far under the per-frame
+    // cap. When the missing slice exceeds the cap (a BIM-sized edit set:
+    // a geometry import or bulk parametric change discarded then healed, or
+    // a large offline divergence on reconnect), it is split into multiple
+    // chunks via `updates-in-range` spans, each under the cap, so even a
+    // large divergence heals instead of being skipped. Import is idempotent
+    // and order-independent (Loro buffers a chunk whose dependency is in a
+    // sibling chunk until it arrives), so the chunks need no ordering.
+    /** @internal */
+    computeResyncPush(persistedSnapshotVersionVector, durableTailBlobs) {
+        let durable;
+        try {
+            durable = VersionVector.decode(persistedSnapshotVersionVector);
+            for (const blob of durableTailBlobs) {
+                const meta = decodeImportBlobMeta(blob, false);
+                durable = mergeVersionVectors(durable, meta.partialEndVersionVector);
+            }
+        }
+        catch (err) {
+            console.warn('[Brass] durability handshake skipped: could not decode the persisted version vector or a tail op blob', err);
+            return null;
+        }
+        const local = this._doc.version();
+        const cmp = local.compare(durable);
+        // `compare` returns -1/0 when local is at or behind the durable
+        // frontier (nothing to push), 1 when local is strictly ahead, and
+        // undefined when the two are concurrent (local holds ops the server
+        // lacks AND vice versa). Push in the ahead and concurrent cases; the
+        // export from `durable` carries only the local-only ops either way.
+        if (cmp !== undefined && cmp <= 0)
+            return null;
+        // Common case: the whole missing slice fits in one frame. Keep this
+        // path byte-identical to a plain `update` export so the no-chunking
+        // case is unchanged.
+        const full = this._doc.export({ mode: 'update', from: durable });
+        if (full.byteLength <= RESYNC_PUSH_MAX_BYTES)
+            return [full];
+        // Large divergence: split the per-peer missing ranges into chunks.
+        return this.chunkMissingSlice(local, durable);
+    }
+    // The per-peer ranges local holds beyond `durable`, as half-open
+    // [from, to) counter ranges. `export({ mode: 'update', from })` covers
+    // exactly these ops; we re-express them as `updates-in-range` spans so
+    // they can be split.
+    missingRanges(local, durable) {
+        const durableMap = durable.toJSON();
+        const ranges = [];
+        for (const [peer, to] of local.toJSON()) {
+            const from = durableMap.get(peer) ?? 0;
+            if (to > from)
+                ranges.push({ peer, from, to });
+        }
+        return ranges;
+    }
+    // Recursively export the given ranges as one `updates-in-range` blob,
+    // splitting by op count until each blob is under the per-frame cap. An
+    // irreducible single op (one that alone exceeds the cap) is emitted up
+    // to the hard ceiling, or skipped with a warning beyond it so the loop
+    // never wedges on an un-sendable frame.
+    chunkMissingSlice(local, durable) {
+        const pack = (ranges) => {
+            const total = ranges.reduce((n, r) => n + (r.to - r.from), 0);
+            if (total === 0)
+                return [];
+            const blob = this._doc.export({
+                mode: 'updates-in-range',
+                spans: ranges.map((r) => ({
+                    id: { peer: r.peer, counter: r.from },
+                    len: r.to - r.from,
+                })),
+            });
+            if (blob.byteLength <= RESYNC_PUSH_MAX_BYTES)
+                return [blob];
+            if (total === 1) {
+                // A single op that cannot be split further.
+                if (blob.byteLength <= RESYNC_PUSH_HARD_MAX_BYTES)
+                    return [blob];
+                console.warn(`[Brass] durability resync skipped one op of ${blob.byteLength} bytes, over the ${RESYNC_PUSH_HARD_MAX_BYTES}-byte single-frame ceiling. The rest of the slice still heals; this op heals on a future snapshot-based recovery.`);
+                return [];
+            }
+            const [first, second] = splitRangesByLength(ranges, total);
+            return [...pack(first), ...pack(second)];
+        };
+        return pack(this.missingRanges(local, durable));
+    }
+    // Feed an op blob into the local-op send path as if it were a fresh
+    // local commit: ship it through the transport's send hook (which mints
+    // a client_op_id, sends the frame, and arms the retry tracker) and
+    // record it in the outstanding-op map so `savingCount` reflects it and
+    // its `op_ack` resolves it. Used by the resync push, whose blob is an
+    // export rather than a Loro-emitted local update, so it does not arrive
+    // through `subscribeLocalUpdates`. Returns the minted client_op_id, or
+    // null when no send hook is wired (offline / test path).
+    /** @internal */
+    injectLocalUpdate(blob) {
+        this._ensureLocalUpdatesSubscribed();
+        const hook = this._localOpHook;
+        if (!hook)
+            return null;
+        const copy = new Uint8Array(blob.byteLength);
+        copy.set(blob);
+        const clientOpId = hook(copy);
+        this._outstandingByClientId.set(clientOpId, copy);
+        this._fireSubscribers({ kind: 'saving-count' });
+        return clientOpId;
+    }
+    // Internal: park the Document in the SDK cache. Clears app-side
+    // listeners so a stale handle from this session does not receive
+    // events from the next session, but keeps the LoroDoc,
+    // UndoController, outstanding-op map, and the underlying WS subscribe
+    // alive. `mutate()` and `subscribe()` throw while suspended; the next
+    // `openDocumentById` for the same (docId, branchId) calls `_resume()`
+    // and the user gets a fresh session over the same state. App code
+    // calls `close()`, not this method.
+    /** @internal */
+    _suspend() {
+        if (this._closed || this._suspended)
+            return;
+        this._suspended = true;
+        // A pending auto-checkpoint would otherwise fire against a parked
+        // Document and silently no-op via the scheduler's guard.
+        // Cancelling here keeps the timer count clean across long-lived
+        // caches and avoids the no-op fetch flush.
+        this._checkpoints.cancelAuto();
+        this._subs.clear();
+        this._undoStateSubs.clear();
+        this._gone.clearListeners();
+        this._workStatus.clearListeners();
+        this._driveStatus.clearListeners();
+        // Presence subscribes its OWN WS topic and keeps it alive across a park
+        // (resume does not re-create the controller), so drop its app-side
+        // change listeners here the same way as the sets above: a parked doc
+        // must not fire the app's `presence.on('change')` callback on remote
+        // cursor frames for a doc the app has closed. `leave()` would be wrong,
+        // it terminally unsubscribes and the resume path never rebuilds it.
+        this.presence?._suspendListeners();
+        // Tear down the app-side handle subscriptions, THEN drop the caches.
+        // A handle subscribes DIRECTLY to its Loro container (`handles.ts`
+        // `_attachChange`), not through `_unsubLoro`, and a parked doc keeps
+        // applying remote ops to those live containers (the WS stays attached),
+        // so a subscription an app registered before `close()` would keep firing
+        // the app's callback on a doc it has closed. Detaching first stops that;
+        // fresh handles are minted on resume + next access.
+        for (const entry of this._rootHandles.values()) {
+            teardownRootHandle(entry.handle);
+        }
+        this._rootHandles.clear();
+        // Drop the ordered-map cache too. Each wrapper holds the specific root
+        // map / list handles it was built from; leaving it while the root caches
+        // are cleared would strand those delegates outside `_rebindRootHandles`,
+        // so a later version checkout would not rebind them and the ordered map
+        // would keep reading live-head state during a historical preview.
+        this._orderedMapHandles.clear();
+    }
+    // Internal: pair of `_suspend`. The SDK calls this when handing a
+    // cached Document to a new openDocumentById call. App code does
+    // not invoke this directly.
+    /** @internal */
+    _resume() {
+        this._suspended = false;
+        // Pair of the `_suspend` presence gate: reopen the presence controller's
+        // outbound path and re-advertise this client's cursor on the resumed open.
+        // `_suspend` only closed the gate; without this the parked doc's presence
+        // would stay silent for the life of the resumed session.
+        this.presence?._resumeListeners();
+    }
+    // Internal: whether the Document is currently parked. The SDK's
+    // open-document layer reads this to gate transport-level work
+    // (an op-stream frame arriving for a non-parked, non-closed doc
+    // routes normally; for a parked doc the WS is still attached and
+    // the frame applies to state but does not run app-side callbacks).
+    /** @internal */
+    get _isSuspended() {
+        return this._suspended;
+    }
+    close() {
+        if (this._closed)
+            return;
+        this._closeStreams();
+        this._closed = true;
+        this._suspended = false;
+        if (this._unsubLoro) {
+            this._unsubLoro();
+            this._unsubLoro = null;
+        }
+        if (this._unsubLocal) {
+            this._unsubLocal();
+            this._unsubLocal = null;
+        }
+        if (this._undo) {
+            this._undo.free();
+            this._undo = null;
+        }
+        this._thumbnails.cancel();
+        this._checkpoints.cancelAuto();
+        this._localOpHook = null;
+        this._currentSeqProvider = null;
+        this._outstandingByClientId.clear();
+        this._resyncPushClientOpIds.clear();
+        this._subs.clear();
+        this._undoStateSubs.clear();
+        // Drop the signal listeners too, mirroring `_suspend()`. Their frames
+        // can no longer fire once the transport is torn down, but clearing
+        // them keeps `close()` from retaining an app's callbacks (and the
+        // closures they hold) for the Document's remaining lifetime.
+        this._gone.clearListeners();
+        this._workStatus.clearListeners();
+        this._driveStatus.clearListeners();
+        // Detach handle subscriptions before freeing the doc (below): a handle's
+        // per-container Loro subscription outlives the cache reference, and
+        // `_doc.free()` must not run with subscriptions still attached.
+        for (const entry of this._rootHandles.values()) {
+            teardownRootHandle(entry.handle);
+        }
+        this._rootHandles.clear();
+        this._orderedMapHandles.clear();
+        // Free a live historical-checkout preview: it is a distinct LoroDoc
+        // (allocated by `_checkoutVersion`), so closing while previewing without a
+        // prior `returnToHead()` would otherwise leak its WASM heap. The guard
+        // mirrors `_checkoutVersion` / `returnToHead`: the frozen cold-link case
+        // has `previewDoc === _doc`, where `_doc.free()` below already covers it
+        // and an unguarded free would double-free.
+        if (this._checkout && this._checkout.previewDoc !== this._doc) {
+            try {
+                this._checkout.previewDoc.free();
+            }
+            catch {
+                // ignore; already freed
+            }
+        }
+        this._checkout = null;
+        // Loro's WASM has a `free()` to drop the heap-allocated doc state.
+        // Calling it after `close()` invalidates the doc, which is what we
+        // want; future mutate/subscribe calls throw above.
+        this._doc.free();
+    }
+}
+//# sourceMappingURL=documents.js.map