@brass-build/client 0.1.0 → 0.2.0

package/dist/documents.js

@@ -9,14 +9,15 @@
 //      `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 { PAGING_COMMIT_ORIGIN, UndoController } from './undo.js';
+import { createOrderedMapHandle, createRootListHandle, createRootMapHandle, rebindRootListAnchor, rebindRootMapAnchor, resyncRootHandle, snapshotRootMapKeys, teardownRootHandle, } from './handles.js';
+import { flattenPagedLookup, isPagedMarker, META_KEY, pagedRootKey, } from './record-paging.js';
+import { MAX_OP_BLOB_CHARS } from './ws-frame-limit.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 { releaseUnsavedWork, trackUnsavedWork } from './unload-guard.js';
 import { CommandMenu, } from './document-commands.js';
 import { DocumentStream } from './document-streams.js';
 import { createEmitter } from './emitter.js';
@@ -42,8 +43,6 @@ 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)
@@ -52,19 +51,35 @@ function changeSourceOf(event) {
         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
+// Per-chunk cap on a blob this Document pushes as several ops: a durability
+// resync's missing slice (`computeResyncPush`) and a local commit no write
+// budget bounded (`splitLocalUpdate`).
+//
+// Each chunk goes out through the same local-op hook an ordinary commit
+// uses, so the transport picks itself by size and a chunk this large takes
+// the HTTP op write. Sizing the chunk to a WebSocket frame instead is what
+// makes a heal the most expensive write the SDK performs: the slice a bulk
+// write leaves behind is the whole document, and at frame size that is
+// thousands of ops, each one landing on the document's single storage
+// partition at exactly the size that stays inline on its row. Measured, a
+// 40 MB divergence healed in 16 KB chunks throttled the partition and left
+// the join a tail it refused to serve. The same divergence at this size is
+// tens of ops whose bytes go to the bucket instead.
+const RESYNC_PUSH_MAX_BYTES = 512 * 1024;
+// Hard ceiling for a single irreducible op (one Loro op, unsplittable),
+// beyond which the chunk 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;
+//
+// Skipping drops an edit the server never received, so this sits at exactly
+// what the write path can carry rather than at what a frame holds. Base64
+// turns B raw bytes into ceil(B/3)*4 characters, so the last raw size whose
+// encoding still fits the durable cap is three quarters of it. Derived
+// rather than written out, because the two have to move together and a
+// literal here would let the ceiling drift above what the server accepts,
+// which turns a heal into silent loss. A blob this large travels through
+// the staged upload rather than a request body, a path the write already
+// takes on its own size.
+const RESYNC_PUSH_HARD_MAX_BYTES = Math.floor((MAX_OP_BLOB_CHARS * 3) / 4);
 // 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.
@@ -79,57 +94,157 @@ function mergeVersionVectors(a, b) {
     }
     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);
+function rangeOpCount(ranges) {
+    return ranges.reduce((n, r) => n + (r.to - r.from), 0);
+}
+// Split half-open per-peer counter ranges in two after `at` ops, splitting at
+// most one range across the boundary. Order is preserved.
+function splitRangesAt(ranges, at) {
     const first = [];
     const second = [];
     let acc = 0;
     for (const r of ranges) {
         const len = r.to - r.from;
-        if (acc >= half) {
+        if (acc >= at) {
             second.push(r);
         }
-        else if (acc + len <= half) {
+        else if (acc + len <= at) {
             first.push(r);
             acc += len;
         }
         else {
-            const splitAt = r.from + (half - acc);
+            const splitAt = r.from + (at - acc);
             first.push({ peer: r.peer, from: r.from, to: splitAt });
             second.push({ peer: r.peer, from: splitAt, to: r.to });
-            acc = half;
+            acc = at;
         }
     }
     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;
+// Split into two halves by op count. `total` must be >= 2 so both halves are
+// non-empty (the caller handles total === 1 as the irreducible single-op case).
+function splitRangesByLength(ranges, total) {
+    return splitRangesAt(ranges, Math.floor(total / 2));
+}
+// Split into `parts` pieces of roughly equal op count, in order.
+//
+// A caller that already knows the whole range's byte size can name the number
+// of pieces it wants instead of discovering it by halving, which costs one
+// export per level and re-exports the same ops at every level: an 8 MB commit
+// takes 31 exports to reach sixteen chunks by halving and 16 by naming them.
+// The pieces are still measured afterwards, so an uneven commit that leaves a
+// piece over the cap is split further from there.
+function splitRangesEvenly(ranges, parts) {
+    let rest = [...ranges];
+    let remaining = rangeOpCount(rest);
+    if (parts <= 1 || remaining <= parts)
+        return [rest];
+    const out = [];
+    for (let left = parts; left > 1; left -= 1) {
+        const at = Math.floor(remaining / left);
+        if (at < 1)
+            break;
+        const [first, second] = splitRangesAt(rest, at);
+        out.push(first);
+        rest = second;
+        remaining -= at;
+    }
+    out.push(rest);
+    return out.filter((piece) => rangeOpCount(piece) > 0);
+}
+// The `meta` root a document's paged marker lives in, or `null` while the
+// document has none.
+//
+// The marker is read on every root-map read, edit and keyed lookup, and a
+// reader that answers from a copy taken earlier is what puts paged-shaped keys
+// into a store whose marker says unpaged, or reads a root a peer paged as its
+// raw page entries. Answering off the live container instead makes both
+// impossible: a peer's write lands in that same container, so the next read
+// sees it, with no invalidation to get right.
+//
+// What is remembered per document is the resolved CONTAINER, and only once the
+// root exists. A root handle reads through to the document's current state, so
+// holding one keeps the value live: a peer's import and a checkout both land
+// on the same container the cell already points at.
+//
+// Holding it is also what keeps this off the leak. Every `getMap` mints a new
+// wasm-bindgen handle that dropping does not reclaim (the same fact `pageValue`
+// and `entryExists` free around), and this resolves on every root-map read,
+// edit and keyed lookup, so minting per call retains ~145 bytes each for the
+// length of the session. One handle per document is a bounded cost instead.
+//
+// Resolution goes through `getByPath` rather than `getMap`, which is
+// get-or-create and would materialize an empty `meta` on a document that has
+// none (in the wire shape of every unpaged document, and as a local write on a
+// read-only open). Its cost tracks the document's container count, and it is
+// paid once per document.
+const metaRoots = new WeakMap();
+function metaRoot(source) {
+    let cell = metaRoots.get(source);
+    if (cell === undefined) {
+        cell = { map: null };
+        metaRoots.set(source, cell);
+    }
+    if (cell.map === null) {
+        const found = source.getByPath(META_KEY);
+        if (!(found instanceof LoroMap))
+            return null;
+        cell.map = found;
+    }
+    return cell.map;
+}
+/** The `meta` root, creating it if `source` has none, and remembering it so
+ *  later reads resolve without minting a second handle. */
+function metaRootOrCreate(source) {
+    const existing = metaRoot(source);
+    if (existing !== null)
+        return existing;
+    const created = source.getMap(META_KEY);
+    metaRoots.set(source, { map: created });
+    return created;
+}
+/** Whether one root map is paged. Same predicate the record-store readers
+ *  use, so the SDK handle path and those readers cannot disagree. */
+function readRootPaged(source, rootKey) {
+    return isPagedMarker(metaRoot(source)?.get(pagedRootKey(rootKey)));
 }
-// 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;
+/** Whether a root's JSON is the keyed lookup a record store flattens. A root
+ *  that projects to a list or a scalar cannot hold pages whatever `meta`
+ *  says, so it is handed back untouched. */
+function isRootLookup(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
 }
+// Mark `rootKey` paged, under a `meta` key of its own. Written ONCE and never
+// revised: pages are addressed by session and index, so nothing downstream
+// needs to know how many there are or how much the store grows afterwards.
+//
+// A key per root is what lets two peers page two different roots at the same
+// time. One entry naming every paged root would have to be read, extended and
+// written back whole, and the losing side of that race takes its root's marker
+// with it (see `PAGED_ROOT_PREFIX`); two keys merge.
+//
+// The marker commits on its own, under an origin the undo stack excludes, and
+// `commitPending` lands whatever the running mutation has written so far
+// first. Two properties ride on that. Peers and the server never see a page
+// without the marker that says how to read it, because the marker's op
+// precedes every op carrying a page. And nothing an app authored is taken out
+// of the undo stack with it: a commit carrying both would exclude the records
+// as well as the marker.
+function pageRoot(source, rootKey, commitPending) {
+    if (readRootPaged(source, rootKey))
+        return;
+    commitPending();
+    metaRootOrCreate(source).set(pagedRootKey(rootKey), true);
+    source.setNextCommitOrigin(PAGING_COMMIT_ORIGIN);
+    source.commit();
+}
+const READ_ONLY_MESSAGES = {
+    link: 'Document is read-only: it was opened via a view-only share link.',
+    grant: 'Document is read-only: you have view-only access to it.',
+    app: 'Document is read-only: this app is not permitted to edit it.',
+    unsaved: 'Document is read-only: a change could not be saved, so this copy holds ' +
+        'work the platform does not. Brass is replacing it with the platform copy.',
+};
 // Public Document class. Wraps a LoroDoc; exposes mutate / subscribe /
 // toJSON / close. Construction is cheap: the Loro subscriber attaches
 // lazily (see `_ensureLoroSubscribed`).
@@ -164,13 +279,15 @@ export class Document {
     // 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.
+    // is a version-pinned open with no live channel): the Document keeps a
+    // live WS subscription and applies incoming remote ops, but local
+    // `mutate` is rejected, so the reader sees edits stream in while being
+    // unable to write. Set at open from the join's `can_edit` (a viewer's
+    // grant, a view-only link), and latched on afterwards by
+    // `_markReadOnly` when the server refuses a write on the same grounds.
     _forcedReadOnly;
-    _root;
-    _entities;
+    // Which refusal `_forcedReadOnly` stands for, so `mutate` names it.
+    _readOnlyReason;
     // 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
@@ -184,7 +301,9 @@ export class Document {
     // 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: () => { } });
+    _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
@@ -314,6 +433,9 @@ export class Document {
     // 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.
+    // Readable from the SDK's own layers (the client's open-document set
+    // gates on it) rather than only from inside this class.
+    /** @internal */
     get _isLive() {
         return !this._closed && !this._suspended;
     }
@@ -321,17 +443,32 @@ export class Document {
         if (!this._isLive)
             throw new Error('Document is closed');
     }
+    // `close()` releases the CRDT state, so a read after it reaches released
+    // memory and fails with whatever the engine says about that. Reads are gated
+    // on this rather than on `_assertOpen` because a parked Document still holds
+    // its state and answers from it.
+    _assertNotClosed() {
+        if (this._closed)
+            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();
+    // Inbound work ended without delivering content, so this doc holds
+    // nothing and stays locked. See `_emitStatus` for how it is derived.
+    _loadFailed = false;
     // 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;
+    // A Document owns the LoroDoc it wraps, so it is built through the factories
+    // below (or `documentFromEngine`, for in-repo tooling that brings its own).
+    // Owning construction is what lets this class declare an engine-neutral
+    // surface: app code holds a Document, never the doc underneath it.
     constructor(loroDoc, options) {
         this._doc = loroDoc;
         this._rootKey = options?.rootKey ?? 'entities';
@@ -355,12 +492,15 @@ export class Document {
             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.
+        // `readOnly` on a live (non-version) open is a forced read-only: a
+        // reader the server will not accept writes from, whether because their
+        // grant is view-only or because the link they came through is. A
+        // version open is already frozen, so it does not also need the flag.
         this._forcedReadOnly = options?.readOnly === true && initialVersion === null;
-        this._root = loroDoc.getMap(this._rootKey);
-        this._entities = wrapLoroMapProxy(this._root);
+        this._readOnlyReason = options?.readOnlyReason ?? 'link';
+        // Materialize the root container, so a document nothing has written to
+        // still carries its root in the shape a reader opens it with.
+        loroDoc.getMap(this._rootKey);
         this._undo = new UndoController(this._doc, options?.undo);
     }
     // ---- Typed container handles (the primary read/write/subscribe surface) --
@@ -378,6 +518,14 @@ export class Document {
     // rebinds and each suspend / close tears down every root handle in a single
     // traversal.
     _rootHandles = new Map();
+    // Names the pages this Document's writes may occupy. A page is one value,
+    // so two writers appending to the same page container would resolve
+    // last-writer-wins and lose one writer's records; the token is what keeps
+    // their key spaces apart. Loro's peer id is already unique per open, which
+    // is exactly the scope wanted.
+    get _pagingSessionToken() {
+        return this._doc.peerIdStr;
+    }
     // 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
@@ -397,29 +545,30 @@ export class Document {
         // `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).
+        // handle's anchor to the preview doc, and the page state must come
+        // from that same doc or a read takes the wrong path for the state it is
+        // looking at (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);
+        // EVERY root map gets the providers, because a `meta` key of its own is
+        // what names a paged root: a root with no such key reads as unpaged, which
+        // is the answer `meta` and `header` want anyway. Naming one root here
+        // instead would make paging a property of a reserved key rather than of a
+        // collection, so a map an app owns could never be paged however large it
+        // grew.
+        const activeSource = () => this._checkout !== null ? this._checkout.previewDoc : this._doc;
+        const handle = createRootMapHandle(loroMap, this._handleOwner, {
+            isPaged: () => readRootPaged(activeSource(), key),
+            page: () => {
+                pageRoot(this._doc, key, this._handleOwner.commitMutate);
+            },
+            sessionToken: () => this._pagingSessionToken,
+            stateVersion: () => activeSource().frontiers(),
+        });
         this._rootHandles.set(cacheKey, { kind: 'map', key, handle });
         return handle;
     }
-    // Get a handle for a top-level LoroList at `key`.
+    // Get a handle for a top-level LoroMovableList at `key`.
     list(key) {
         this._assertOpen();
         const cacheKey = `list:${key}`;
@@ -427,7 +576,7 @@ export class Document {
         if (existing)
             return existing.handle;
         const source = this._checkout !== null ? this._checkout.previewDoc : this._doc;
-        const loroList = source.getList(key);
+        const loroList = source.getMovableList(key);
         const handle = createRootListHandle(loroList, this._handleOwner);
         this._rootHandles.set(cacheKey, { kind: 'list', key, handle });
         return handle;
@@ -461,14 +610,25 @@ export class Document {
         if (this._handleOwnerCache)
             return this._handleOwnerCache;
         this._handleOwnerCache = {
+            assertReadable: () => {
+                this._assertNotClosed();
+            },
             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._versionBrowsing) {
+                    throw new Error('Document is read-only: the reader is browsing its versions. ' +
+                        'Close the version bar to edit.');
+                }
                 if (this._forcedReadOnly) {
-                    throw new Error('Document is read-only: it was opened via a view-only share link.');
+                    throw new Error(READ_ONLY_MESSAGES[this._readOnlyReason]);
+                }
+                if (this._loadFailed) {
+                    throw new Error('Document is read-only: its content could not be prepared ' +
+                        '(see `doc.status`). Reopen it to try again.');
                 }
                 if (this._isLoadLocked()) {
                     throw new Error('Document is still loading its content; wait for the load to ' +
@@ -502,11 +662,14 @@ export class Document {
     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.
+    // True when this reader cannot write to the document right now:
+    // `mutate` throws and edit affordances should be disabled. It covers a
+    // view-only grant, a view-only share link, a historical version showing
+    // (a checkout), and a document whose content is still loading or could
+    // not be loaded. Reactive in every one of those: `subscribe` fires when
+    // it changes, so an app binds it directly inside the subscribe handler
+    // and follows a grant the server withdraws mid-session as well as a
+    // checkout the reader entered.
     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
@@ -516,19 +679,48 @@ export class Document {
         // `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());
+        // Browsing versions locks the document at the live head as well as at an
+        // earlier one. Stepping moves between the points history KEEPS, and an
+        // edit at the head makes no such point, so an edit made under the open
+        // bar puts the reader's own newest work somewhere the bar cannot travel
+        // to: Back then steps past it to the newest marker, and the way forward
+        // is a different number of presses from the way back. Reading history
+        // and writing it are separate modes, and the bar carries the Close that
+        // leaves this one.
+        return (this._forcedReadOnly ||
+            this._checkout !== null ||
+            this._versionBrowsing ||
+            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
+    // ops, and true again once that work ends without content
+    // (`_loadFailed`): a doc nothing could prepare is empty, and an edit
+    // there writes ops into a document the app is about to be told could not
+    // be opened. 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() {
+        if (this._loadFailed)
+            return true;
         const s = this._workStatus.status;
         return s?.pending === true && s.blocking !== false;
     }
+    /**
+     * Whether inbound work on this document ended without content. The SDK's
+     * session reads it to report the open as failed rather than binding an
+     * empty document as ready.
+     * @internal
+     */
+    get _contentLoadFailed() {
+        return this._loadFailed;
+    }
+    /** @internal The `doc_gone` reason this Document has seen, or `null`. */
+    get _goneReason() {
+        return this._gone.reason;
+    }
     /**
      * The historical version this Document shows, or `null` for a live
      * (head) open. Reactive alongside `readOnly`. The number is the
@@ -589,6 +781,15 @@ export class Document {
     static create(options) {
         return new Document(new LoroDoc(), options);
     }
+    /**
+     * Wrap a LoroDoc the caller already holds. `documentFromEngine` is the typed
+     * entry point; this seam stays `unknown` so `documents.ts` declares an
+     * engine-neutral surface.
+     * @internal
+     */
+    static _fromEngine(engine, options) {
+        return new Document(engine, 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
@@ -615,8 +816,8 @@ export class Document {
     }
     // 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.
+    // snapshot mid-session. Persistence is server-authoritative: the server
+    // decides when a fresh snapshot supersedes the local history.
     /** @internal */
     _applySnapshot(snapshot) {
         // See `applyRemoteOp`: refuse the import on a closed (freed) doc so a late
@@ -733,9 +934,9 @@ export class Document {
     // 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:
+    // `E` defaults to `EntityProxy` (the untyped Record<string, unknown>) so an
+    // app that has not described its entity shape still gets a working mutate.
+    // Apps with a typed entity shape pass it as a type argument:
     //
     //   doc.mutate<MyEntity>((d) => {
     //     d.entities[id] = myTypedEntity;
@@ -745,39 +946,16 @@ export class Document {
     // 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.
+    //
+    // `d.entities` is the root map's handle under a plain-object surface, so
+    // the two reach one collection: a record a paged store holds reads and
+    // edits here exactly as it does through `doc.map(rootKey)`, and a write
+    // large enough to cross the paging threshold takes the paged shape from
+    // either.
     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),
+        this.map(this._rootKey).mutate((entities) => {
+            fn({ entities });
         });
-        // 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.
     //
@@ -821,6 +999,12 @@ export class Document {
     _isCheckedOut() {
         return this._checkout !== null;
     }
+    /** @internal Whether this Document is pinned to the version it was opened
+     * at, with no live channel behind it. Stepping and returning to the head
+     * both throw on that shape, so the SDK's version bar offers neither. */
+    get _isVersionPinned() {
+        return this._isFrozen;
+    }
     // Switch the Document to a historical version, in place. @internal
     // (the hosted `history` command drives this). After the promise
     // resolves, `doc.readOnly` is `true`,
@@ -870,6 +1054,11 @@ export class Document {
             previewDoc.import(blob);
         const previewRoot = previewDoc.getMap(this._rootKey);
         const old = this._checkout;
+        // Snapshot the handles' keys before the active-source pointer moves (see
+        // `_snapshotRootHandleKeys`). Nothing between here and `_rebindRootHandles`
+        // may return early, or the snapshot would outlive its swap and be diffed
+        // against an unrelated later one.
+        this._snapshotRootHandleKeys();
         this._checkout = {
             previewDoc,
             previewRoot,
@@ -896,29 +1085,38 @@ export class Document {
                 // ignore; already freed
             }
         }
-        this._fireSubscribers({ kind: 'checkout', version: effectiveVersion });
+        this._fireSubscribers({ kind: 'history', 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();
+        await this._checkoutOpenStreams(generation);
     }
     // 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
+    // one) has no historical state it can show, so it is held read-only for the
+    // duration rather than left live and writable under a historical default. 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() {
+    async _checkoutOpenStreams(generation) {
         const seqs = this._checkoutStreamSeqs ?? {};
         for (const [name, openPromise] of this._streamOpens) {
             try {
                 const stream = await openPromise;
+                // Every stream costs an await, so the reader can have stepped
+                // somewhere else, or back to the live head, since the previous one.
+                // The document's own swap is guarded the same way, and this loop
+                // running on past it is what leaves a partitioned document showing
+                // two moments at once: the document at the version the reader asked
+                // for, and whichever streams a superseded run still reached at its
+                // own.
+                if (generation !== this._checkoutGeneration)
+                    return;
                 const lineId = this._streamManifest?.get(name)?.line_id;
                 const seq = lineId !== undefined ? seqs[lineId] : undefined;
-                await stream._previewAt(seq);
+                await stream._previewAt(seq, true);
             }
             catch {
                 // A stream that failed to open or preview is left as-is.
@@ -946,10 +1144,13 @@ export class Document {
         // 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;
+        const generation = (this._checkoutGeneration += 1);
         if (this._checkout === null)
             return;
         const old = this._checkout;
+        // Symmetric with `_checkoutVersion`: snapshot before the active-source
+        // pointer moves, and return early nowhere between here and the rebind.
+        this._snapshotRootHandleKeys();
         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
@@ -974,12 +1175,33 @@ export class Document {
         this._checkoutStreamSeqs = null;
         for (const openPromise of this._streamOpens.values()) {
             void openPromise
-                .then((stream) => stream._previewAt(undefined))
+                .then((stream) => {
+                // Each stream is reached a turn or more later, so a checkout the
+                // reader started in the meantime owns the document by now and this
+                // return would drag its streams back to the live head under it.
+                if (generation !== this._checkoutGeneration)
+                    return;
+                return stream._previewAt(undefined);
+            })
                 .catch(() => {
                 // A stream that failed to open has nothing to return.
             });
         }
     }
+    // Capture every root map handle's key set for the resync's removed-key diff,
+    // while the handles still describe the outgoing source. This is a phase of
+    // its own, ahead of `_rebindRootHandles`, because a handle resolves its
+    // container from its anchor but its paging state from this Document's active
+    // source: both must still name the outgoing source when the keys are read,
+    // and the caller moves the active-source pointer between the two calls.
+    // Callers must not return early in that window; a snapshot left unconsumed
+    // would be diffed against a later, unrelated swap.
+    _snapshotRootHandleKeys() {
+        for (const entry of this._rootHandles.values()) {
+            if (entry.kind === 'map')
+                snapshotRootMapKeys(entry.handle);
+        }
+    }
     // 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
@@ -997,7 +1219,7 @@ export class Document {
                 rebindRootMapAnchor(entry.handle, source.getMap(entry.key));
             }
             else {
-                rebindRootListAnchor(entry.handle, source.getList(entry.key));
+                rebindRootListAnchor(entry.handle, source.getMovableList(entry.key));
             }
         }
         for (const entry of this._rootHandles.values()) {
@@ -1099,11 +1321,8 @@ export class Document {
     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' });
+    // Publish this document's current state back to its drive source,
+    // driving the hosted toolbar's publish control.
     //
     // The platform publishes the doc's current state, overwriting the
     // source (unknown drive fields preserved), and marks its own write so
@@ -1111,6 +1330,7 @@ export class Document {
     // concurrent drive-side edits. Throws on auth / link / write
     // failures; resolves with the new external ref and the published
     // entity count.
+    /** @internal */
     async pushToDrive(input) {
         this._assertOpen();
         if (this._docId === null) {
@@ -1122,10 +1342,9 @@ export class Document {
         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();
+    // hosted resolution surface, which offers pull (take the source) / keep
+    // both alongside the publish-over that `pushToDrive` does. Driven by the
+    // hosted toolbar.
     //
     // Unlike `pushToDrive`, the resolution can mint a NEW mirror doc that
     // takes over the drive link (take-source trashes this doc, keep-both
@@ -1135,6 +1354,7 @@ export class Document {
     // 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.
+    /** @internal */
     async resolveDrive() {
         this._assertOpen();
         if (this._docId === null) {
@@ -1185,6 +1405,9 @@ export class Document {
     _streamRuntime = null;
     _streamManifest = null;
     _streamOpens = new Map();
+    // The subset of `_streamOpens` that has resolved, so a park reaches them
+    // without waiting on a microtask. Kept in step with the map above.
+    _openStreams = 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
@@ -1261,14 +1484,30 @@ export class Document {
             // 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]);
+                await stream._previewAt(this._checkoutStreamSeqs?.[info.line_id], true);
             }
             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(() => {
+        // Hold the RESOLVED stream too. A park has to reach the streams
+        // synchronously (an app's `close()` returns before any microtask runs, and
+        // a remote op landing in between would still call the app back), and a
+        // promise cannot be read that way. An open still in flight when the park
+        // happens resolves into a parked document, so it is parked on arrival.
+        void open.then((stream) => {
+            if (this._streamOpens.get(name) !== open)
+                return;
+            this._openStreams.set(name, stream);
+            // `savingCount` counts this stream from here on, so an indicator bound
+            // to the document has to hear the stream's writes land.
+            stream._inner._observeSavingCount(() => {
+                this._fireSubscribers({ kind: 'saving-count' });
+            });
+            if (this._suspended)
+                stream._suspend();
+        }, () => {
+            // A failed open (network, deleted stream) must not poison the cache:
+            // drop it so the next call retries.
             if (this._streamOpens.get(name) === open)
                 this._streamOpens.delete(name);
         });
@@ -1336,14 +1575,45 @@ export class Document {
     // Close every opened stream's own transport + state. Streams opened
     // while this Document was live do not outlive it.
     _closeStreams() {
+        // A stream that has already opened closes IN THIS CALL, for the reason the
+        // park reaches them through this map: `close()` returns to the app before
+        // any microtask runs, so a stream closed on a `.then` spends the rest of
+        // that turn taking writes and calling the app back while `doc.mutate` on
+        // the same document already refuses. A write in that window reaches a
+        // transport about to be torn down and is never persisted.
+        for (const stream of this._openStreams.values()) {
+            stream._inner._observeSavingCount(null);
+            stream._close();
+        }
+        // An open still in flight has no Document to close yet, so it closes on
+        // arrival. A stream reached both ways is closed twice, which is a no-op.
         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._openStreams.clear();
         this._streamManifest = null;
     }
+    // Park / unpark the streams opened off this document, alongside the
+    // document's own park.
+    //
+    // A non-default stream is its own Document, which nothing else suspends: it
+    // keeps its transport, so an app holding `await doc.stream(name)` across
+    // `doc.close()` would go on receiving remote-op callbacks and could still
+    // write through the stream, while `doc.mutate` correctly throws. That is the
+    // cross-session callback a park exists to stop, plus a write path around the
+    // closed check. The default stream's inner IS this document, which owns its
+    // own lifecycle, so `_ownsInner` gates this exactly as it gates the close.
+    _setStreamsSuspended(suspended) {
+        for (const stream of this._openStreams.values()) {
+            if (suspended)
+                stream._suspend();
+            else
+                stream._resume();
+        }
+    }
     // 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
@@ -1411,6 +1681,13 @@ export class Document {
         else
             console.error('[Brass]', err);
     }
+    /** @internal Report a failure from the SDK's own chrome (the version
+     * bar's intents) through the same sink the built-in commands use, so a
+     * refused checkout reaches the app's `onError` rather than being dropped
+     * on the way back to a surface that only shows the reader a state. */
+    _reportChromeError(err) {
+        this._reportError(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)
@@ -1419,20 +1696,118 @@ export class Document {
     // call `toJSON()` in the handler; the discriminant is there for
     // the rare consumer that wants to branch on the reason.
     _fireSubscribers(event) {
+        // Every change to the outstanding-op map reports itself here, which
+        // makes this the one place the unload guard has to hear about un-acked
+        // work (`close()` releases the doc outright).
+        if (event.kind === 'saving-count') {
+            // Own ops rather than `savingCount`: a stream's inner Document registers
+            // itself, so the registry's total already carries one entry per stream.
+            trackUnsavedWork(this, this._outstandingByClientId.size);
+            this._savingCountObserver?.();
+        }
         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:
+    // Told when this Document's outstanding-op count moves, so a parent
+    // Document's `savingCount` covers the streams it has open and its
+    // subscribers fire when a stream's writes land. One observer, because a
+    // stream's inner Document is opened by, and belongs to, exactly one parent.
+    _savingCountObserver = null;
+    /** @internal */
+    _observeSavingCount(observer) {
+        this._savingCountObserver = observer;
+    }
+    // Saving indicator: number of locally-issued ops not yet acked by the
+    // server, across this document's own state and every stream it has open. A
+    // partitioned document keeps its bulk on its streams, so a count that named
+    // the default stream alone reports "All changes saved" over a stream still
+    // writing. Reactive: `subscribe` fires when this count changes (an op is
+    // sent or an `op_ack` lands, on any of them). 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'}...`;
     //   });
+    //
+    // Only this count aggregates. `readOnly` and `atCapacity` gate `doc.mutate`,
+    // which writes this document's own state, so folding another stream's
+    // refusal into them would close an editor over a stream taking writes;
+    // `stream.readOnly` / `stream.atCapacity` answer for one stream.
+    // Supplied by the doc transport, which holds the sync state this reports.
+    // Absent until a transport is wired (a read-only or detached Document),
+    // where the honest answer is that nothing is outstanding.
+    _diagnosticsProvider = null;
+    /** @internal */
+    _setDiagnosticsProvider(provider) {
+        this._diagnosticsProvider = provider;
+    }
+    /**
+     * How this document's sync is going, as the client sees it: how much is
+     * outstanding, how long it has been, over which transport, across how many
+     * reconnects, and under which correlator, which is what separates a
+     * connection that is answering nothing from one that is merely behind.
+     *
+     * @internal Telemetry for Brass's own surfaces. An app reads `savingCount`
+     * to know a save is outstanding, and the SDK resolves a stuck one itself.
+     */
+    diagnostics() {
+        const own = this._diagnosticsProvider?.() ?? {
+            unackedOps: 0,
+            oldestUnackedMs: 0,
+            oldestClientOpId: null,
+            reconnects: 0,
+            lastAckAgeMs: null,
+            inFlightBytes: 0,
+            httpOpsInFlight: 0,
+            healRounds: 0,
+            hidden: false,
+        };
+        // Cover the streams this document opened, the way `savingCount` does: a
+        // reader watching a save waits on the document, and which line an op was
+        // written to is not something they can act on. The work counters add
+        // up and the waiting ones take the longest wait, so the answer is about
+        // the oldest edit anywhere in the document.
+        //
+        // The connection counters are the parent's alone rather than a fold,
+        // because every line rides one socket, so reconnects and page
+        // visibility are one fact about the client and not one per line.
+        for (const stream of this._openStreams.values()) {
+            const line = stream._inner.diagnostics();
+            own.unackedOps += line.unackedOps;
+            own.inFlightBytes += line.inFlightBytes;
+            own.httpOpsInFlight += line.httpOpsInFlight;
+            own.healRounds = Math.max(own.healRounds, line.healRounds);
+            // Take the stream's op when it waited longer, and also when this
+            // document has none of its own: a strict comparison against a zero
+            // wait leaves the fold reporting outstanding work while naming no op
+            // to go looking for, which is the field the rest hangs off.
+            if (line.oldestClientOpId !== null &&
+                (own.oldestClientOpId === null ||
+                    line.oldestUnackedMs > own.oldestUnackedMs)) {
+                own.oldestUnackedMs = line.oldestUnackedMs;
+                own.oldestClientOpId = line.oldestClientOpId;
+            }
+        }
+        return own;
+    }
     get savingCount() {
+        let total = this._ownSavingCount;
+        // `_openStreams` holds the streams that opened their own line. The stream
+        // this Document IS wraps `this`, and is not in it, so nothing is counted
+        // twice.
+        for (const stream of this._openStreams.values()) {
+            total += stream._inner.savingCount;
+        }
+        return total;
+    }
+    // The ops issued against THIS line, which is what a stream reports for
+    // itself: `doc.stream('default')` wraps this Document, so a default stream
+    // reading the aggregate would report a sibling stream's writes as its own
+    // and stand at "saving" while its own line has nothing outstanding.
+    /** @internal */
+    get _ownSavingCount() {
         return this._outstandingByClientId.size;
     }
     // Internal: forget an outstanding op once the server has acked it.
@@ -1449,8 +1824,52 @@ export class Document {
         this._resyncPushClientOpIds.delete(clientOpId);
         if (wasTracked)
             this._fireSubscribers({ kind: 'saving-count' });
+        // An ack is proof the branch is taking writes again, which is the only
+        // thing that can clear the capacity latch. A full branch refuses every
+        // op, so no ack can arrive while the refusal stands; that is what makes
+        // this evidence rather than a guess, and what keeps it from clearing a
+        // state the next write would re-enter.
+        if (this._atCapacity) {
+            this._atCapacity = false;
+            this._fireSubscribers({ kind: 'capacity' });
+        }
         return wasTracked;
     }
+    // Internal: turn this Document read-only because the server refused a
+    // write on the reader's authority rather than on the op. It lands on
+    // `readOnly` because that is the gate an app already renders, so a grant
+    // withdrawn mid-session closes the editor with no new signal to learn.
+    // One-way: the socket resolves write authority when it subscribes, so a
+    // grant restored afterwards is refused by the server too until the
+    // connection recycles, and a reopen is what picks the wider grant up.
+    /** @internal */
+    _markReadOnly(reason) {
+        if (this._forcedReadOnly)
+            return;
+        this._forcedReadOnly = true;
+        this._readOnlyReason = reason;
+        this._fireSubscribers({ kind: 'commands' });
+        this._maybeFireUndoState();
+    }
+    /**
+     * Return this copy to what the platform holds, discarding anything it
+     * refused. A refused change stays drawn on the copy that made it and
+     * nowhere else, and no local operation removes it (a CRDT merges rather
+     * than replaces, and an undo inverts an operation instead of discarding
+     * it), so the only state holding exactly what the platform has is one
+     * built from it.
+     *
+     * The session closes this document and opens the same id again, so a
+     * `session.subscribe` handler rebinds the way it does on any document
+     * switch.
+     *
+     * @internal The SDK drives this itself on the one refusal that reaches it,
+     * telling the reader first, because an app that renders nothing for it is
+     * exactly the case that must not leave someone on a diverged copy.
+     */
+    reload() {
+        this._markGone('moved');
+    }
     // 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
@@ -1459,15 +1878,71 @@ export class Document {
     // 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) {
+    _failOutstandingOp(clientOpId, message, 
+    // Whether the app hears about this one. A refusal that describes the
+    // DOCUMENT answers every op in flight at once, so reporting per op tells
+    // the reader the same thing as many times as they happened to have
+    // unacked writes, which on a bulk write is dozens. The caller reports it
+    // once instead; the op still leaves the tracker either way, because
+    // `savingCount` has to fall whether or not anyone is told.
+    opts = {}) {
         const wasTracked = this._outstandingByClientId.delete(clientOpId);
         this._resyncPushClientOpIds.delete(clientOpId);
         if (wasTracked) {
             this._fireSubscribers({ kind: 'saving-count' });
-            this._reportError(new Error(message));
+            if (opts.report !== false)
+                this._reportError(new Error(message));
         }
         return wasTracked;
     }
+    // Internal: whether this op is one the durability handshake pushed, rather
+    // than one the app wrote. The transport reads it to tell a refusal the heal
+    // itself provoked from one that arrived on its own, which is what keeps a
+    // refused heal chunk from re-arming the heal that sent it.
+    /** @internal */
+    _isResyncPushOp(clientOpId) {
+        return this._resyncPushClientOpIds.has(clientOpId);
+    }
+    _atCapacity = false;
+    /**
+     * Whether the document has stopped accepting new changes because it has
+     * reached the largest size the platform can keep.
+     *
+     * Read from the server's refusal of a write rather than predicted locally,
+     * so it turns true at the first edit that does not land, and back to false
+     * on the first edit that does. Both directions are evidence: a full branch
+     * refuses every op, so an ack cannot arrive while the refusal stands.
+     *
+     * Edits keep applying to the local copy while it is true, which is what
+     * lets the app show the reader what they did alongside the fact that it is
+     * not saved; the copy is discarded on reload.
+     *
+     * An app reads this to stop offering work that would only be refused (a
+     * bulk import, a generate pass) and to say so once, instead of surfacing one
+     * error per rejected op.
+     */
+    get atCapacity() {
+        return this._atCapacity;
+    }
+    // Internal: record the capacity verdict from a server refusal. Idempotent.
+    // Cleared again by `resolveOutstandingOp`, so a branch whose compaction
+    // seals it back under the ceiling reaches the open reader through the next
+    // write that lands rather than only through a reload.
+    /**
+     * Returns whether this call is the one that flipped it, which is what lets
+     * the transport report the refusal exactly once. Every op in flight draws
+     * the same refusal, and a bulk write has as many of those as it has unacked
+     * writes, so the flip is the only moment worth telling the app about.
+     *
+     * @internal
+     */
+    _markAtCapacity() {
+        if (this._atCapacity)
+            return false;
+        this._atCapacity = true;
+        this._fireSubscribers({ kind: 'capacity' });
+        return true;
+    }
     _ensureLocalUpdatesSubscribed() {
         if (this._unsubLocal)
             return;
@@ -1487,15 +1962,46 @@ export class Document {
             // 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' });
+            const chunks = this.splitLocalUpdate(copy);
+            if (chunks === null) {
+                this._shipLocalOp(copy);
+                return;
+            }
+            // In order: each chunk continues the one before it, so a peer applying
+            // them out of sequence holds the tail unapplied until the gap closes.
+            for (const chunk of chunks)
+                this._shipLocalOp(chunk);
         });
     }
+    // Hand one op blob to the transport and count it as unsaved, or keep it
+    // local when the server has evicted this document.
+    //
+    // A gone document still takes edits by design: it stays open so the app can
+    // render its own "no longer available" state, and the person may keep
+    // interacting until they navigate. Those edits have nowhere to land. The
+    // transport dropped its retry machinery on `doc_gone`, and the frame would
+    // ship onto a subscription the server evicted and come back as a `forbidden`
+    // that describes nothing the app did. Counting them is the part that shows:
+    // each one adds to `savingCount` for a save that cannot happen, so the doc
+    // reports "no longer available" and "Saving 3 changes..." together and
+    // re-arms the leave-site prompt `_markGone` just released.
+    //
+    // Returns the minted `client_op_id`, or null when the op stayed local.
+    _shipLocalOp(copy) {
+        const hook = this._localOpHook;
+        if (!hook)
+            return null;
+        if (this._gone.reason !== null)
+            return null;
+        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' });
+        return clientOpId;
+    }
     // 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
@@ -1518,7 +2024,17 @@ export class Document {
             // 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);
+            //
+            // What reaches a subscriber is this SDK's own `{ kind, source }`, not
+            // the engine's event object. An app that receives the engine's shape
+            // can read its internals (container ids, peer ids, the raw diff) and
+            // build on them, which pins the storage engine through a surface that
+            // never promised it. The cause survives as `source`, the same
+            // engine-neutral vocabulary the handle surface reports.
+            this._subs.emit({
+                kind: 'change',
+                source: changeSourceOf(event),
+            });
             const isLocalCommit = event.by === 'local';
             this._maybeFireUndoState();
             // A local commit (mutate / undo / redo) schedules a debounced
@@ -1541,12 +2057,12 @@ export class Document {
     // 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.
+    // a remote op, `undo`, `redo`, a history move, and the SDK's own metadata
+    // events (saving-count, branches, commands). One channel; the app re-reads
+    // / reconciles in the handler and branches on `event.kind` only when it
+    // needs the cause. A content change arrives as
+    // `{ kind: 'change', source }`, carrying the same engine-neutral `source`
+    // the handle surface reports.
     subscribe(cb) {
         this._assertOpen();
         this._ensureLoroSubscribed();
@@ -1632,10 +2148,10 @@ export class Document {
     // 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.
+    // Mutations after `_markGone` still mutate the local CRDT, and stay
+    // local: `_shipLocalOp` keeps them off the transport and out of
+    // `savingCount`, so this one notice is what the app hears about the
+    // eviction rather than a refusal per later edit.
     onGone(cb) {
         // Guard like `subscribe` / `subscribeUndoState`: `_suspend` clears these
         // signals' listeners so a stale handle from a parked session does not
@@ -1676,11 +2192,20 @@ export class Document {
     // false`) is retained so a late `onStatus` subscriber still sees the
     // final state.
     /** @internal */
-    _emitStatus(status) {
+    _emitStatus(status, opts) {
         // 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;
+        // Terminal work that still reports itself as locking editing is inbound
+        // work that ended without content: the platform clears the status when
+        // hydration / extraction succeeds, so what it reports terminally is a
+        // failure. Anything else means the doc is either loading or holds what
+        // it has.
+        this._loadFailed =
+            opts?.contentLoaded !== true &&
+                status.pending === false &&
+                status.blocking === true;
         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
@@ -1690,10 +2215,10 @@ export class Document {
         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
+    // doc is not linked to a drive source. An app reads `state` / `canPush`
+    // to tell the reader they have unpublished edits, and renders the
+    // server-authored `label` / `detail` as the wording; publishing itself
+    // is the hosted toolbar's control. Seeded on open
     // (for a drive-linked doc) and kept live as edits, refreshes, and
     // pushes move the state.
     get driveStatus() {
@@ -1740,11 +2265,27 @@ export class Document {
     }
     // Plain-JS projection of the current state.
     toJSON() {
+        this._assertNotClosed();
         // 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();
+        const json = source.toJSON();
+        // A paged root holds its records inside page entries beside the store's
+        // own edit bookkeeping, so flatten it to the same record lookup
+        // `doc.map(root).read()` hands back: a serializer and a whole-document
+        // renderer read this surface, and a store that crossed the paging
+        // threshold has to reach them as records. Every root is asked, because a
+        // root no handle was ever taken on is paged by the same rule as one that
+        // was; a root the marker does not name comes back as loro produced it.
+        for (const [rootKey, value] of Object.entries(json)) {
+            if (!isRootLookup(value))
+                continue;
+            if (!readRootPaged(source, rootKey))
+                continue;
+            json[rootKey] = flattenPagedLookup(value, true);
+        }
+        return json;
     }
     /**
      * Snapshot bytes; inverse of `openFromSnapshot`, for round-trip tests.
@@ -1761,27 +2302,35 @@ export class Document {
     // 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).
+    //
+    // The return value says whether the caller may stop asking. `covered`
+    // means the durable frontier holds everything local does, so the
+    // handshake is finished; every other outcome leaves the doc diverged and
+    // is the caller's cue to run the handshake again once the push settles.
     /** @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;
+            return 'closed';
         // 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;
+                return 'in-flight';
         }
         const chunks = this.computeResyncPush(persistedSnapshotVersionVector, durableTailBlobs);
-        if (chunks === null)
-            return;
+        if (chunks === 'covered')
+            return 'covered';
+        if (chunks === 'undecodable')
+            return 'undecodable';
         for (const chunk of chunks) {
             const id = this.injectLocalUpdate(chunk);
             if (id !== null)
                 this._resyncPushClientOpIds.add(id);
         }
+        return 'pushed';
     }
     // Given the server's persisted snapshot version vector and the op
     // blobs the server is also serving on the join tail, decide whether
@@ -1798,10 +2347,13 @@ export class Document {
     // 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).
+    // Returns the chunks to resync-push, `'covered'` when the durable state
+    // already holds everything local does, or `'undecodable'` for 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. `'undecodable'` is distinct from `'covered'` because it says
+    // nothing about whether the doc has diverged, so a caller healing a known
+    // divergence must keep asking.
     //
     // The common case is one chunk: an `update` export from the durable
     // frontier carries only the missing ops plus their dependencies, never
@@ -1813,6 +2365,44 @@ export class Document {
     // 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.
+    /**
+     * Whether the durable snapshot holds changes by an author this doc has never
+     * heard from.
+     *
+     * Every author a client can hear from reaches it as ops, so a peer present
+     * in the durable frontier and absent from the local doc after the tail has
+     * applied is one whose changes exist only inside the snapshot. That is the
+     * platform having rewritten how the document stores what it stores
+     * (compaction's patch fold is the one thing that does this), which a client
+     * cannot merge with and cannot undo across: its undo stack inverts the
+     * operations it made, and the values those operations wrote now live
+     * somewhere else.
+     *
+     * The answer drives a re-import, which is the existing recovery for exactly
+     * this shape (`_applySnapshot` drops both stacks, so undo reports itself
+     * unavailable instead of silently reverting nothing).
+     *
+     * @internal
+     */
+    _snapshotHasUnseenAuthor(persistedSnapshotVersionVector) {
+        if (this._closed)
+            return false;
+        let durable;
+        try {
+            durable = VersionVector.decode(persistedSnapshotVersionVector);
+        }
+        catch {
+            // Undecodable says nothing, and the durability handshake already warns
+            // about it on the same frame.
+            return false;
+        }
+        const local = this._doc.version().toJSON();
+        for (const [peer, counter] of durable.toJSON()) {
+            if (counter > 0 && !local.has(peer))
+                return true;
+        }
+        return false;
+    }
     /** @internal */
     computeResyncPush(persistedSnapshotVersionVector, durableTailBlobs) {
         let durable;
@@ -1825,7 +2415,7 @@ export class Document {
         }
         catch (err) {
             console.warn('[Brass] durability handshake skipped: could not decode the persisted version vector or a tail op blob', err);
-            return null;
+            return 'undecodable';
         }
         const local = this._doc.version();
         const cmp = local.compare(durable);
@@ -1835,7 +2425,7 @@ export class Document {
         // 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;
+            return 'covered';
         // 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.
@@ -1860,35 +2450,96 @@ export class Document {
         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)
+    // splitting by op count until each blob is under the per-chunk cap.
+    //
+    // `dropOversizedSingle` decides what happens to an irreducible op (one that
+    // alone exceeds the cap and the hard ceiling). A resync drops it with a
+    // warning so the loop never wedges on an un-sendable frame while the rest
+    // of the slice heals. A local commit keeps it: it is an edit the app just
+    // made and nothing else will carry it, so it goes to the write path, which
+    // reports the refusal to the app rather than losing it silently.
+    chunkRanges(ranges, dropOversizedSingle) {
+        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];
+            if (!dropOversizedSingle)
                 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 [];
+            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 [
+            ...this.chunkRanges(first, dropOversizedSingle),
+            ...this.chunkRanges(second, dropOversizedSingle),
+        ];
+    }
+    chunkMissingSlice(local, durable) {
+        return this.chunkRanges(this.missingRanges(local, durable), true);
+    }
+    // A local commit re-exported as several op blobs, or null to ship it whole.
+    //
+    // `mutate` bounds what one commit carries by committing as it goes, but a
+    // commit Loro makes for itself takes no such budget: `redo` replays a whole
+    // undo step, so a bulk write that correctly split into many ops comes back
+    // as one op the size of the entire write. Past `MAX_OP_BLOB_CHARS` that op
+    // is refused outright and the redone edit never persists, and below it, it
+    // still lands as a single large row on the document's one storage partition.
+    //
+    // The ops already exist, so the only lever left is which spans they ship in.
+    // The blob names the counter range it covers, and re-exporting a sub-range
+    // is what the durability resync already does, so the chunks are ordinary ops
+    // a peer applies in sequence.
+    //
+    // Splitting is abandoned unless EVERY chunk comes in under the cap. A commit
+    // holding one value nothing can split (a mesh, a large embedded body) would
+    // otherwise ship as a small chunk that lands and an irreducible one that the
+    // write path refuses, which puts a record on the server missing the field
+    // that made it large and leaves the two copies permanently apart. Whole, its
+    // refusal covers the whole edit and the app is told once.
+    splitLocalUpdate(blob) {
+        if (blob.byteLength <= RESYNC_PUSH_MAX_BYTES)
+            return null;
+        let ranges;
+        try {
+            const meta = decodeImportBlobMeta(blob, false);
+            const start = meta.partialStartVersionVector.toJSON();
+            ranges = [];
+            for (const [peer, to] of meta.partialEndVersionVector.toJSON()) {
+                const from = start.get(peer) ?? 0;
+                if (to > from)
+                    ranges.push({ peer, from, to });
             }
-            const [first, second] = splitRangesByLength(ranges, total);
-            return [...pack(first), ...pack(second)];
-        };
-        return pack(this.missingRanges(local, durable));
+        }
+        catch {
+            // An undecodable blob is one this cannot describe in spans. Shipping it
+            // whole is what happens without this path at all.
+            return null;
+        }
+        const total = rangeOpCount(ranges);
+        if (total < 2)
+            return null;
+        // The blob's own size names how many pieces to ask for, so the split does
+        // not rediscover that by halving.
+        const parts = Math.min(total, Math.ceil(blob.byteLength / RESYNC_PUSH_MAX_BYTES));
+        const chunks = splitRangesEvenly(ranges, parts).flatMap((piece) => this.chunkRanges(piece, false));
+        if (chunks.length < 2)
+            return null;
+        if (chunks.some((c) => c.byteLength > RESYNC_PUSH_MAX_BYTES))
+            return null;
+        return chunks;
     }
     // 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
@@ -1901,15 +2552,9 @@ export class Document {
     /** @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;
+        return this._shipLocalOp(copy);
     }
     // Internal: park the Document in the SDK cache. Clears app-side
     // listeners so a stale handle from this session does not receive
@@ -1924,6 +2569,7 @@ export class Document {
         if (this._closed || this._suspended)
             return;
         this._suspended = true;
+        this._setStreamsSuspended(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
@@ -1965,6 +2611,7 @@ export class Document {
     /** @internal */
     _resume() {
         this._suspended = false;
+        this._setStreamsSuspended(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
@@ -2004,6 +2651,7 @@ export class Document {
         this._currentSeqProvider = null;
         this._outstandingByClientId.clear();
         this._resyncPushClientOpIds.clear();
+        releaseUnsavedWork(this);
         this._subs.clear();
         this._undoStateSubs.clear();
         // Drop the signal listeners too, mirroring `_suspend()`. Their frames