@brass-build/client 0.2.0 → 0.4.0

package/dist/documents.js

@@ -8,14 +8,15 @@
 //   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 { LoroDoc, LoroMap, VersionVector, decodeImportBlobMeta, } from './wasm-runtime.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 { GoneSignal, WorkStatusSignal, DriveStatusSignal, DrivePublishTargetSignal, } from './document-signals.js';
 import { ThumbnailCapture, } from './document-thumbnail-capture.js';
 import { CheckpointScheduler, } from './document-checkpoints.js';
+import { whenSaved } from './when-saved.js';
 import { BranchController, } from './document-branches.js';
 import { releaseUnsavedWork, trackUnsavedWork } from './unload-guard.js';
 import { CommandMenu, } from './document-commands.js';
@@ -24,6 +25,31 @@ 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';
+// Loro names a container's type in its id (`cid:root-notes:Map`), so the kind
+// comes off the enumeration itself and costs no read. A type this package
+// cannot hand anyone a handle for, and cannot describe as text either, is
+// left out rather than guessed at, so every entry a reader gets is one they
+// can act on.
+function rootKindOf(containerId) {
+    const type = containerId.slice(containerId.lastIndexOf(':') + 1);
+    if (type === 'Map')
+        return 'map';
+    if (type === 'MovableList' || type === 'List')
+        return 'list';
+    if (type === 'Text')
+        return 'text';
+    return null;
+}
+// Maps count entries, lists and text count length. Both are the container's
+// own counter rather than a projection of what it holds.
+function rootIsEmpty(container) {
+    const sized = container;
+    if (typeof sized.size === 'number')
+        return sized.size === 0;
+    if (typeof sized.length === 'number')
+        return sized.length === 0;
+    return false;
+}
 // 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
@@ -51,6 +77,26 @@ function changeSourceOf(event) {
         return 'redo';
     return 'local';
 }
+// Whether a text container stores `value` unchanged. Loro's text is UTF-8, so
+// an unpaired surrogate is stored as U+FFFD and what the document holds is
+// not the string that was written. Scanned here rather than through
+// `String.prototype.isWellFormed`, which is younger than the browsers this
+// package runs in.
+function storedVerbatim(value) {
+    for (let i = 0; i < value.length; i += 1) {
+        const unit = value.charCodeAt(i);
+        if (unit < 0xd800 || unit > 0xdfff)
+            continue;
+        // A trailing surrogate reached before its lead is unpaired by itself.
+        if (unit > 0xdbff)
+            return false;
+        i += 1;
+        const low = i < value.length ? value.charCodeAt(i) : 0;
+        if (low < 0xdc00 || low > 0xdfff)
+            return false;
+    }
+    return true;
+}
 // 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`).
@@ -60,11 +106,10 @@ function changeSourceOf(event) {
 // 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.
+// thousands of ops written one after another against the same document.
+// Measured, a 40 MB divergence healed in 16 KB chunks overwhelmed that
+// document's write path and left the join a tail it refused to serve. The
+// same divergence at this size is tens of ops.
 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
@@ -244,10 +289,11 @@ const READ_ONLY_MESSAGES = {
     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.',
+    capacity: 'Stream is read-only: it reached the largest size the platform can keep. ' +
+        'Reopen it to keep working from the saved state.',
+    no_connection: 'Document is read-only: it opened with no live connection, so a change ' +
+        'would stay on this device.',
 };
-// 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;
@@ -341,9 +387,24 @@ export class Document {
             this._fireSubscribers({ kind: 'branches' });
         },
     });
+    // The version of the newest picture the server holds of this document, or
+    // `null` for none. Seeded from the join and moved by this instance's own
+    // uploads; a picture older than the document's head is what arms the seed
+    // trigger, so a placeholder taken before the content arrived is replaced
+    // once it does.
+    _thumbnailVersion = null;
     _thumbnails = new ThumbnailCapture({
-        isCaptureAllowed: () => this._isLive && this._checkout === null,
+        // `_forcedReadOnly` and not the whole `readOnly`: the server refuses a
+        // thumbnail from a reader it will not take writes from, so a capture
+        // there costs a request and a warn to be told so. The load lock is the
+        // other half of `readOnly` and must NOT gate this, because a document
+        // still hydrating is exactly the one the seed watch is armed for, and
+        // the arm happens while that lock is still on.
+        isCaptureAllowed: () => this._isLive && this._checkout === null && !this._forcedReadOnly,
         isAttached: () => this._isLive,
+        onCaptured: () => {
+            this._thumbnailVersion = this.currentSeq ?? 0;
+        },
     });
     _checkpoints = new CheckpointScheduler({
         docId: () => this._docId,
@@ -354,6 +415,7 @@ export class Document {
             if (this._undo)
                 this._undo.sealStep();
         },
+        whenLocalOpsSaved: () => whenSaved(this),
     });
     // Drive push hook. `null` on the offline / test path; `pushToDrive`
     // then throws with a clear message rather than silently dropping.
@@ -418,6 +480,11 @@ export class Document {
     // 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;
+    // Set when this document was opened expecting a live transport that was not
+    // available. A write then changes local state and reaches no server, so the
+    // first one is reported rather than dropped in silence.
+    _transportExpected = false;
+    _transportUnavailableReported = false;
     _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,
@@ -430,6 +497,14 @@ export class Document {
     // next session). `_resume()`
     // flips the flag back when the SDK hands the Doc to a new open() call.
     _suspended = false;
+    // How many times this instance has been handed to an open. The park cache
+    // hands the SAME Document back on a reopen, so "this document is open" is
+    // not one interval per instance and a per-instance mark cannot say which
+    // open it was made in. Anything that spends a once-per-open budget on a
+    // Document (the import runner's one attempt) records this alongside its
+    // mark and re-reads it, so a reopen is a new open rather than the old one
+    // continuing.
+    _openEpoch = 0;
     // 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.
@@ -462,6 +537,9 @@ export class Document {
     // 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();
+    // Where this document could be published when it mirrors nothing yet.
+    // Seeded from the open, emptied once it becomes a mirror.
+    _drivePublishTarget = new DrivePublishTargetSignal();
     // Document-scoped presence. `null` until the WS transport is wired
     // on, and on the offline / test path where there is no transport.
     presence = null;
@@ -590,6 +668,126 @@ export class Document {
     // Built over the same `map(mapKey)` / `list(orderKey)` handles, so the
     // paged-store presentation and subscriptions carry through.
     _orderedMapHandles = new Map();
+    /**
+     * A handle on the top-level text container at `key`, which `roots()` reports
+     * as kind `'text'`.
+     *
+     * Cached per key, so `doc.text('x') === doc.text('x')` holds as it does for
+     * `doc.map`, and a subscriber registered through one keeps firing across a
+     * version checkout.
+     */
+    text(key) {
+        this._assertOpen();
+        const cacheKey = `text:${key}`;
+        const existing = this._rootHandles.get(cacheKey);
+        if (existing)
+            return existing.handle;
+        const owner = this._handleOwner;
+        const activeSource = () => this._checkout !== null ? this._checkout.previewDoc : this._doc;
+        // Reads and writes resolve the active source per call, so a checkout
+        // needs no rebinding for them. A SUBSCRIPTION cannot work that way: it
+        // anchors a listener to one container, and a checkout preview is a
+        // different LoroDoc, so the anchor has to be moved. That is what makes
+        // this handle cached and registered like a map or a list, rather than a
+        // fresh object per call: the app holds the object the rebind reaches.
+        let anchor = activeSource().getText(key);
+        const subscribers = new Set();
+        let detach = null;
+        // The string this handle's own `update` has just written, armed only
+        // across the synchronous window in which `commit` fires the Loro
+        // subscriber. Materializing a text container is the one cost here that
+        // grows with a document's accumulated edit history rather than with its
+        // length, and `update` has already paid it once to diff against, so a
+        // fanout that materialized again would double the per-keystroke cost of
+        // exactly the field the README teaches. Anything else, a remote op or a
+        // checkout, finds it null and materializes.
+        let justWrote = null;
+        const fanout = (origin) => {
+            // Read for the local write alone. A change from any other source
+            // describes a container this handle did not write, so its value comes
+            // from the container even while a local write is arming one.
+            const value = (origin?.source === 'local' ? justWrote : null) ?? anchor.toString();
+            // Fired off a snapshot: a subscriber may unsubscribe (or register
+            // another) while it runs, and the set it is iterating is the one that
+            // changes underneath it.
+            const current = Array.from(subscribers);
+            for (const cb of current)
+                cb(value, origin);
+        };
+        const attach = () => {
+            if (detach !== null || subscribers.size === 0)
+                return;
+            detach = anchor.subscribe((event) => {
+                fanout({ source: owner.originOf(event) });
+            });
+        };
+        const handle = {
+            read: () => {
+                owner.assertReadable();
+                return activeSource().getText(key).toString();
+            },
+            update: (next) => {
+                owner.assertWritable();
+                owner.ensureLocalUpdatesSubscribed();
+                activeSource().getText(key).update(next);
+                // Armed after the write, so the container already holds `next` for
+                // every subscriber the commit reaches, and cleared however the
+                // commit returns: outside this window the fanout has no way to know
+                // the value is still current, and reads it. Armed only for a string
+                // the container holds verbatim, so a subscriber is never handed a
+                // value the document and its peers disagree with.
+                justWrote = storedVerbatim(next) ? next : null;
+                try {
+                    owner.commitMutate();
+                }
+                finally {
+                    justWrote = null;
+                }
+            },
+            subscribe: (cb) => {
+                owner.assertReadable();
+                subscribers.add(cb);
+                attach();
+                // No origin: a registration fire describes no authored transition,
+                // matching what a map subscriber's first fire carries.
+                cb(anchor.toString(), undefined);
+                return () => {
+                    subscribers.delete(cb);
+                    if (subscribers.size === 0 && detach !== null) {
+                        detach();
+                        detach = null;
+                    }
+                };
+            },
+            _rebind: (next) => {
+                if (detach !== null) {
+                    detach();
+                    detach = null;
+                }
+                anchor = next;
+                attach();
+            },
+            // A checkout or a return to head swaps the container rather than
+            // writing into it, so the catch-up fire carries no origin.
+            _resync: () => {
+                fanout(undefined);
+            },
+            // Detach the container subscription and forget the callbacks behind it,
+            // as a map or a list handle does: the Document drops its handle cache
+            // here, so an app still holding this one subscribes onto a handle
+            // nothing else reaches, and every callback registered before the park
+            // would come back with it.
+            _teardown: () => {
+                if (detach !== null) {
+                    detach();
+                    detach = null;
+                }
+                subscribers.clear();
+            },
+        };
+        this._rootHandles.set(cacheKey, { kind: 'text', key, handle });
+        return handle;
+    }
     orderedMap(mapKey, orderKey) {
         this._assertOpen();
         const cacheKey = `${mapKey}\u0000${orderKey}`;
@@ -825,6 +1023,11 @@ export class Document {
         // doc still imports.
         if (this._closed)
             return;
+        // Arm the seed BEFORE the import, because this is the moment the content
+        // arrives and the Loro subscriber cannot be relied on to report it: it is
+        // attached lazily, so a document whose content lands before the session has
+        // bound its canvas has nobody subscribed and the import fires nothing.
+        this._armSeedIfPictureIsStale();
         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
@@ -1218,12 +1421,18 @@ export class Document {
             if (entry.kind === 'map') {
                 rebindRootMapAnchor(entry.handle, source.getMap(entry.key));
             }
-            else {
+            else if (entry.kind === 'list') {
                 rebindRootListAnchor(entry.handle, source.getMovableList(entry.key));
             }
+            else {
+                entry.handle._rebind(source.getText(entry.key));
+            }
         }
         for (const entry of this._rootHandles.values()) {
-            resyncRootHandle(entry.handle);
+            if (entry.kind === 'text')
+                entry.handle._resync();
+            else
+                resyncRootHandle(entry.handle);
         }
     }
     /**
@@ -1300,6 +1509,21 @@ export class Document {
     setThumbnailUploader(uploader) {
         this._thumbnails.setUploader(uploader);
     }
+    // Tell the document which version the server's picture of it depicts, from
+    // the join, and start a seed watch when that picture is behind the content.
+    /** @internal */
+    _setThumbnailVersion(version) {
+        this._thumbnailVersion = version;
+        this._armSeedIfPictureIsStale();
+    }
+    // A picture at or above the head depicts what the document currently holds.
+    _armSeedIfPictureIsStale() {
+        const head = this.currentSeq ?? 0;
+        if (this._thumbnailVersion !== null && this._thumbnailVersion >= head) {
+            return;
+        }
+        this._thumbnails.armSeed();
+    }
     // Install the checkpoint-create hook; `null` detaches.
     /** @internal */
     setCheckpointCreator(creator) {
@@ -1365,11 +1589,11 @@ export class Document {
         }
         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(...)`):
+    // Fetch the file a document was uploaded as: 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());
@@ -1381,9 +1605,8 @@ export class Document {
     // 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).
+    // Rejects with a `BrassError` when the document holds no such file, or
+    // the caller cannot reach it (both 404).
     async sourceBlob() {
         this._assertOpen();
         if (this._docId === null) {
@@ -1480,11 +1703,24 @@ export class Document {
             }
             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], true);
+            try {
+                // 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], true);
+                }
+            }
+            catch (err) {
+                // The line is joined and subscribed by now, and a rejected open is
+                // dropped from the cache so the next call opens a second one. Nothing
+                // else holds this Document, and nothing else would ever close it: the
+                // parent closes the streams it has, and a stream whose open failed is
+                // not one of them. So the failure disposes what it is abandoning,
+                // rather than leaving a line applying remote ops for the life of the
+                // page.
+                stream._close();
+                throw err;
             }
             return stream;
         })();
@@ -1675,6 +1911,37 @@ export class Document {
         this._errorReporter = reporter;
         this._commandMenu.setErrorReporter(reporter);
     }
+    // Called by the factory when a document is opened with no live transport,
+    // which outside tests means `wsBaseUrl` was left unset. Marking it is what
+    // separates that from the snapshot reads and test stubs that legitimately
+    // have no transport and must stay quiet.
+    /** @internal */
+    markTransportUnavailable() {
+        this._transportExpected = true;
+    }
+    // A write on such a document reaches nothing: local state changes, the
+    // reader sees their edit, and no server ever hears about it, so the edit is
+    // gone on the next open with no failure anywhere. This is what makes that
+    // observable. Once per document, because the condition holds for as long as
+    // the document is open and repeating it per keystroke buries it.
+    _reportTransportUnavailable() {
+        if (!this._transportExpected)
+            return;
+        if (this._transportUnavailableReported)
+            return;
+        this._transportUnavailableReported = true;
+        // Lock the document as well as reporting it. The write that reached this
+        // point stays local, exactly as `unsaved` describes for a refused one, so
+        // the same gate closes: an app that disables on `readOnly` stops offering
+        // an editor that cannot save, and a later `mutate` throws a sentence
+        // naming the reason instead of succeeding into nothing. The lock lands
+        // after this write's own gate has passed, so the first one still runs
+        // locally and only what follows it is refused.
+        this._markReadOnly('no_connection');
+        this._reportError(new Error('This document has no live connection, so edits stay on this device and ' +
+            'reach no one else. Pass wsBaseUrl to Brass.init alongside the other ' +
+            'base URLs: naming any one of them leaves wsBaseUrl unset.'));
+    }
     _reportError(err) {
         if (this._errorReporter)
             this._errorReporter(err);
@@ -1749,8 +2016,9 @@ export class Document {
      * 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.
+     * @internal Read on demand by 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?.() ?? {
@@ -1946,8 +2214,10 @@ export class Document {
     _ensureLocalUpdatesSubscribed() {
         if (this._unsubLocal)
             return;
-        if (!this._localOpHook)
+        if (!this._localOpHook) {
+            this._reportTransportUnavailable();
             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
@@ -2039,9 +2309,9 @@ export class Document {
             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.
+            // `useCanvas`. The debounce is for the peer that drew the change, so
+            // it is local-only: a passive collaborator re-uploading a screenshot
+            // of someone else's edit is what a per-op capture would be.
             if (isLocalCommit) {
                 this._thumbnails.schedule();
                 // Same reasoning for the implicit auto-checkpoint: only the
@@ -2050,6 +2320,18 @@ export class Document {
                 // idle period.
                 this._checkpoints.scheduleAuto();
             }
+            else {
+                // Content arriving with no local commit behind it is what an import
+                // looks like from here, and it moves the head past whatever picture
+                // the document has. This DOES reach a reader who drew none of it,
+                // which the debounce above deliberately does not: an import runs on
+                // whichever client claimed it, so gating the seed on local authorship
+                // would leave the documents that most need a picture without one.
+                // Every such reader captures the same document at the same version,
+                // and the targeted snapshot each upload enqueues is idempotent on
+                // that version, so the concurrent seeds resolve themselves.
+                this._armSeedIfPictureIsStale();
+            }
         });
     }
     // Subscribe to document events. Returns an unsubscribe handle.
@@ -2245,6 +2527,49 @@ export class Document {
         if (this._closed)
             return;
         this._driveStatus.emit(status);
+        // A document that has become a mirror publishes through its link from
+        // now on, so the create-an-artifact offer goes with the arrival of the
+        // status that replaces it.
+        this._drivePublishTarget.set(null);
+    }
+    // Whether this document's export runs in THIS app, which is what decides
+    // whether a push carries bytes. Not on `driveStatus`: it is a fact about
+    // the caller rather than about the document, and it is all an app is told
+    // about the exporter, never which app it is when it is not this one.
+    _exportsHere = false;
+    /** @internal */
+    get _exportRunsHere() {
+        return this._exportsHere;
+    }
+    /** @internal */
+    _setExportRunsHere(runsHere) {
+        this._exportsHere = runsHere;
+    }
+    // Internal: where this document can be published while it mirrors nothing.
+    /** @internal */
+    get _publishTarget() {
+        return this._drivePublishTarget.target;
+    }
+    /** @internal */
+    _setPublishTarget(target) {
+        if (this._closed)
+            return;
+        this._drivePublishTarget.set(target);
+    }
+    // Internal: how the publish of a document that mirrors nothing is going.
+    /** @internal */
+    get _publishState() {
+        return this._drivePublishTarget.state;
+    }
+    /** @internal */
+    _emitPublishState(state) {
+        if (this._closed)
+            return;
+        this._drivePublishTarget.setState(state);
+    }
+    /** @internal */
+    _onPublishState(cb) {
+        return this._drivePublishTarget.onState(cb);
     }
     // Internal: mark the doc evicted. Idempotent (multiple frames arrive
     // for the same doc when both `doc:<id>` and `presence:doc:<id>`
@@ -2263,6 +2588,45 @@ export class Document {
         }
         this._gone.mark(reason);
     }
+    /**
+     * The top-level collections of the stream this document is open at, keyed
+     * as it keys them, each naming the kind of handle that reads it.
+     *
+     * A partitioned document keeps its collections per stream, so this is the
+     * open stream's answer rather than every stream's. `listStreams` names the
+     * rest, and `stream.roots()` asks one of them the same question.
+     *
+     * `map` / `list` are get-or-create, and taking the wrong kind for a key
+     * materializes a second container beside the real one, so read this before
+     * taking a handle on a key you are unsure of. A collection holding nothing
+     * is not listed, which is what keeps a handle taken but never written from
+     * appearing as one.
+     *
+     * The cost is the number of collections rather than the size of the
+     * document. In checkout, it describes the version being previewed.
+     */
+    roots() {
+        this._assertNotClosed();
+        const source = this._checkout !== null ? this._checkout.previewDoc : this._doc;
+        const found = [];
+        for (const [key, containerId] of Object.entries(source.getShallowValue())) {
+            const kind = rootKindOf(containerId);
+            if (kind === null)
+                continue;
+            // Reading the container's own count, rather than its value, is what
+            // keeps this off the projection: an empty collection is skipped without
+            // anything being decoded.
+            const container = source.getContainerById(containerId);
+            if (container === undefined || rootIsEmpty(container))
+                continue;
+            found.push([key, kind]);
+        }
+        // Loro reports roots in registration order, which is an accident of who
+        // wrote what first. Inserting in key order makes a reader's iteration
+        // stable across opens.
+        found.sort((a, b) => (a[0] < b[0] ? -1 : a[0] > b[0] ? 1 : 0));
+        return Object.fromEntries(found);
+    }
     // Plain-JS projection of the current state.
     toJSON() {
         this._assertNotClosed();
@@ -2496,7 +2860,7 @@ export class Document {
     // 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.
+    // still lands as one very large write against the document.
     //
     // 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
@@ -2580,6 +2944,7 @@ export class Document {
         this._gone.clearListeners();
         this._workStatus.clearListeners();
         this._driveStatus.clearListeners();
+        this._drivePublishTarget.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
@@ -2595,7 +2960,10 @@ export class Document {
         // 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);
+            if (entry.kind === 'text')
+                entry.handle._teardown();
+            else
+                teardownRootHandle(entry.handle);
         }
         this._rootHandles.clear();
         // Drop the ordered-map cache too. Each wrapper holds the specific root
@@ -2611,6 +2979,7 @@ export class Document {
     /** @internal */
     _resume() {
         this._suspended = false;
+        this._openEpoch += 1;
         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.
@@ -2627,6 +2996,12 @@ export class Document {
     get _isSuspended() {
         return this._suspended;
     }
+    /** @internal Which open this Document is currently in (see `_openEpoch`).
+     *  Read by anything holding a per-open mark on a Document, since a park hit
+     *  hands the same instance to the next open. */
+    get _openGeneration() {
+        return this._openEpoch;
+    }
     close() {
         if (this._closed)
             return;
@@ -2645,7 +3020,7 @@ export class Document {
             this._undo.free();
             this._undo = null;
         }
-        this._thumbnails.cancel();
+        this._thumbnails.destroy();
         this._checkpoints.cancelAuto();
         this._localOpHook = null;
         this._currentSeqProvider = null;
@@ -2661,11 +3036,15 @@ export class Document {
         this._gone.clearListeners();
         this._workStatus.clearListeners();
         this._driveStatus.clearListeners();
+        this._drivePublishTarget.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);
+            if (entry.kind === 'text')
+                entry.handle._teardown();
+            else
+                teardownRootHandle(entry.handle);
         }
         this._rootHandles.clear();
         this._orderedMapHandles.clear();