@brass-build/client 0.1.0

package/dist/handles.js

@@ -0,0 +1,1375 @@
+// Typed container handles. A handle is a scoped reference to a container in
+// the CRDT doc; its `read` / `mutate` / `subscribe` only see (and only pay
+// for) that container.
+//
+// Engine-neutral: Loro events are translated to a minimal `Change` shape at
+// the handle boundary, so handle-only app code does not pin the SDK to Loro.
+import { LoroList, LoroMap, isContainer, } from 'loro-crdt';
+import { PAGE_TAG, decodePageBody, decodeRecordValue, encodePageBody, flattenPagedLookup, isPagingSchemeEditable, pageKeyFor, peekRecordTag, } from './record-paging.js';
+import { BrassError } from './errors.js';
+import { MutateBatcher } from './mutate-batching.js';
+// ---- Plain-JS-proxy machinery, scoped per-container --------------------
+function isPlainObject(v) {
+    return (v !== null &&
+        typeof v === 'object' &&
+        !Array.isArray(v) &&
+        v.constructor === Object);
+}
+// A value being assigned may be a live Loro container handle (a nested list
+// read back through `m[key].listField`, or a nested-map proxy). Re-inserting
+// an already-attached handle as a value corrupts it: it lands as an opaque
+// reference and is lost on the next snapshot. Materialize it to a deep plain
+// value first, so the assign path rebuilds it as a fresh container.
+function materializeContainers(v) {
+    return isContainer(v) ? v.toJSON() : v;
+}
+// Deep-plain conversion for structures stored as plain Loro VALUES: any
+// nested container handle or wrapped proxy materialises to pure JSON, and
+// `undefined` entries drop (the documented JSON-serialise semantics of
+// `mutate`).
+function toPlainDeep(v) {
+    if (isContainer(v))
+        return v.toJSON();
+    if (Array.isArray(v))
+        return v.map(toPlainDeep);
+    if (v !== null && typeof v === 'object') {
+        const out = {};
+        for (const [k, x] of Object.entries(v)) {
+            if (x !== undefined)
+                out[k] = toPlainDeep(x);
+        }
+        return out;
+    }
+    return v;
+}
+function assignPlain(target, value) {
+    // Recursively materialize nested objects / arrays as nested LoroMap /
+    // LoroList containers so the CRDT mirrors the JS shape. Clear keys not in
+    // `value` so assignment is a replace, not a merge (property-level patching
+    // uses `d.entities[id].x = ...`).
+    for (const k of target.keys()) {
+        if (!(k in value))
+            target.delete(k);
+    }
+    for (const [k, rawV] of Object.entries(value)) {
+        const v = materializeContainers(rawV);
+        // Plain-VALUE preservation (as in the proxy set trap): a key holding a
+        // plain object/array value (a record body) stays a value, never promoted.
+        const existingV = target.get(k);
+        if (existingV !== undefined &&
+            !isContainer(existingV) &&
+            typeof existingV === 'object' &&
+            existingV !== null &&
+            typeof v === 'object' &&
+            v !== null) {
+            target.set(k, toPlainDeep(v));
+            continue;
+        }
+        if (isPlainObject(v)) {
+            // Reuse an existing LoroMap at this key: a fresh `setContainer` mints a
+            // new container ID, which under Loro's UndoManager is a structural
+            // destroy+create that does NOT merge within the merge window. In-place
+            // field overwrites DO merge, which whole-entity-rewrites-at-drag-cadence
+            // expects.
+            const existing = target.get(k);
+            const sub = existing instanceof LoroMap
+                ? existing
+                : target.setContainer(k, new LoroMap());
+            assignPlain(sub, v);
+        }
+        else if (Array.isArray(v)) {
+            const existingList = target.get(k);
+            const sub = existingList instanceof LoroList
+                ? existingList
+                : target.setContainer(k, new LoroList());
+            assignList(sub, v);
+        }
+        else {
+            target.set(k, v);
+        }
+    }
+}
+function assignList(target, value) {
+    // Same rationale as the LoroMap reuse above: replace contents in place
+    // rather than minting a new LoroList, so adjacent commits collapse into one
+    // undo step.
+    const oldLen = target.length;
+    for (let i = 0; i < value.length; i++) {
+        const item = materializeContainers(value[i]);
+        if (isPlainObject(item)) {
+            if (i < oldLen)
+                target.delete(i, 1);
+            const child = target.insertContainer(i, new LoroMap());
+            assignPlain(child, item);
+        }
+        else if (Array.isArray(item)) {
+            // A nested list: rebuild as a child LoroList rather than inserting the
+            // array as an opaque value.
+            if (i < oldLen)
+                target.delete(i, 1);
+            const child = target.insertContainer(i, new LoroList());
+            assignList(child, item);
+        }
+        else {
+            if (i < oldLen) {
+                target.delete(i, 1);
+                target.insert(i, item);
+            }
+            else {
+                target.insert(i, item);
+            }
+        }
+    }
+    if (value.length < oldLen) {
+        target.delete(value.length, oldLen - value.length);
+    }
+}
+// Append one value at the tail (same plain-vs-container handling as the
+// indexed-set trap). The proxy's `push` fast-path uses this so a tail append
+// stays O(1) instead of the full-list replay.
+function insertListTail(target, rawItem) {
+    const idx = target.length;
+    const item = materializeContainers(rawItem);
+    if (isPlainObject(item)) {
+        const child = target.insertContainer(idx, new LoroMap());
+        assignPlain(child, item);
+    }
+    else if (Array.isArray(item)) {
+        const child = target.insertContainer(idx, new LoroList());
+        assignList(child, item);
+    }
+    else {
+        target.insert(idx, item);
+    }
+}
+// Exported because `Document.mutate` reuses the same proxy for its
+// `entities` root. Load-bearing: `getOwnPropertyDescriptor` does a single
+// `loroMap.get(key)` (O(1) per key, so `Object.keys()` is O(N)). Iterating
+// `loroMap.keys()` in the descriptor trap makes `Object.keys()` O(N^2) at
+// 50k entities (measured at >5 min of CPU before giving up).
+export function wrapLoroMapProxy(loroMap, 
+// Threaded into nested record proxies too, so a field edit counts. A
+// mutation can hold thousands of them (`m[id].params = ...` in a loop),
+// which reaches the same size a bulk write does while touching no
+// top-level key.
+batcher) {
+    const handler = {
+        get(_t, key) {
+            if (typeof key === 'symbol')
+                return undefined;
+            const v = loroMap.get(key);
+            if (isContainer(v)) {
+                // Present an engine-neutral view, never the raw container, so app
+                // code can't take a hard dependency on the CRDT engine. A LoroMap
+                // recurses into another proxy; a LoroList reads back via `toJSON`
+                // (not `toArray`, which is shallow and hands back live element
+                // handles that corrupt on reassignment; list editing goes through
+                // `parent.list(key).mutate(...)`). Other container types are outside
+                // the v1 portable surface, so project them via toJSON().
+                if (v instanceof LoroMap)
+                    return wrapLoroMapProxy(v, batcher);
+                if (v instanceof LoroList)
+                    return v.toJSON();
+                return v.toJSON();
+            }
+            return v;
+        },
+        set(_t, key, value) {
+            if (typeof key === 'symbol')
+                return false;
+            // Before the write, so a commit it triggers seals the preceding
+            // batch rather than splitting this record out of it.
+            batcher?.record(value);
+            const existing = loroMap.get(key);
+            // Plain-VALUE preservation: when the key holds a plain (non-container)
+            // object or array, the new structure is written as a plain value too,
+            // never promoted. This keeps a record body (`rec.params`, one JSON
+            // value whose whole-replace is the merge unit) a value across edits;
+            // promoting it would change the merge granularity and bloat the
+            // snapshot with per-element containers.
+            if (existing !== undefined &&
+                !isContainer(existing) &&
+                typeof existing === 'object' &&
+                existing !== null &&
+                typeof value === 'object' &&
+                value !== null) {
+                loroMap.set(key, toPlainDeep(value));
+                return true;
+            }
+            if (isPlainObject(value)) {
+                // Reuse the existing LoroMap (see `assignPlain`): a fresh
+                // `setContainer` is a destroy+create Loro won't merge across, so
+                // `entities[id] = {...}` at drag cadence accumulates one undo entry
+                // per frame instead of collapsing into the merge window.
+                const sub = existing instanceof LoroMap
+                    ? existing
+                    : loroMap.setContainer(key, new LoroMap());
+                assignPlain(sub, value);
+            }
+            else if (Array.isArray(value)) {
+                const sub = existing instanceof LoroList
+                    ? existing
+                    : loroMap.setContainer(key, new LoroList());
+                assignList(sub, value);
+            }
+            else {
+                loroMap.set(key, value);
+            }
+            return true;
+        },
+        deleteProperty(_t, key) {
+            if (typeof key === 'symbol')
+                return false;
+            batcher?.recordDelete();
+            loroMap.delete(key);
+            return true;
+        },
+        has(_t, key) {
+            if (typeof key === 'symbol')
+                return false;
+            return loroMap.get(key) !== undefined;
+        },
+        ownKeys() {
+            return loroMap.keys();
+        },
+        getOwnPropertyDescriptor(_t, key) {
+            if (typeof key === 'symbol')
+                return undefined;
+            // Single get per key. Do NOT iterate `loroMap.keys()` here: it makes
+            // Object.keys() O(N^2) at 50k entities.
+            const v = loroMap.get(key);
+            if (v === undefined)
+                return undefined;
+            return {
+                enumerable: true,
+                configurable: true,
+                writable: true,
+                value: v,
+            };
+        },
+    };
+    return new Proxy({}, handler);
+}
+// Array.prototype methods that mutate the array in place. Called on a list
+// mutate-proxy, their result is replayed into the LoroList; every other
+// method is a pure read that leaves the container untouched, so a `find` /
+// `findIndex` inside a mutate reads fields without rewriting the whole list.
+// `push` is fast-pathed natively above the generic fallback and never reaches
+// this set.
+const MUTATING_ARRAY_METHODS = new Set([
+    'pop',
+    'shift',
+    'unshift',
+    'splice',
+    'sort',
+    'reverse',
+    'fill',
+    'copyWithin',
+]);
+// An array-proxy for list mutators: index assignments, `.push` / `.splice`,
+// and length-set route into the underlying LoroList so the user writes
+// idiomatic JS. Reads delegate to a fresh snapshot per access so a sequence
+// of reads inside the mutator sees each write.
+function wrapLoroListProxy(loroList) {
+    const handler = {
+        get(_t, key) {
+            if (key === 'length')
+                return loroList.length;
+            if (typeof key === 'symbol') {
+                // `toJSON` (deep-plain), not `toArray` (shallow), so iterating the
+                // draft (`for (const c of l)`, `[...l]`) yields plain objects an app
+                // can read fields off, matching the array-method snapshot below.
+                return loroList.toJSON()[key];
+            }
+            if (typeof key === 'string' && /^\d+$/.test(key)) {
+                const idx = Number(key);
+                const v = loroList.get(idx);
+                if (isContainer(v)) {
+                    // Engine-neutral view only (see the map proxy's get trap).
+                    if (v instanceof LoroMap)
+                        return wrapLoroMapProxy(v);
+                    if (v instanceof LoroList)
+                        return v.toJSON();
+                    return v.toJSON();
+                }
+                return v;
+            }
+            // `push` is the hot path (the ordered-map primitive appends every new
+            // key through it; apps bulk-build lists with it), so append natively.
+            // The toArray + replay below is O(list) PER call, turning N appends
+            // into O(N^2) and faulting Loro at a few thousand keys; a tail insert
+            // is O(1).
+            if (key === 'push') {
+                return (...items) => {
+                    for (const item of items)
+                        insertListTail(loroList, item);
+                    return loroList.length;
+                };
+            }
+            // Remaining array methods: bind to a deep-plain `toJSON` snapshot so a
+            // callback reading an element's fields (`findIndex((c) => c.id === x)`,
+            // `find`, `filter`, `map`) sees plain objects, not the raw child
+            // containers `toArray` hands back (whose fields read undefined). A
+            // mutating method replays its result into the LoroList; a pure read
+            // does not, or a `find` inside a mutate would rewrite the whole list.
+            // Best-effort for v1; efficient mutation uses indexed assignment /
+            // length-set / `push`.
+            const arr = loroList.toJSON();
+            const val = arr[key];
+            if (typeof val === 'function') {
+                return (...args) => {
+                    const fn = val;
+                    const result = fn.apply(arr, args);
+                    if (MUTATING_ARRAY_METHODS.has(key))
+                        assignList(loroList, arr);
+                    return result;
+                };
+            }
+            return val;
+        },
+        set(_t, key, value) {
+            if (key === 'length') {
+                const newLen = Number(value);
+                const oldLen = loroList.length;
+                if (newLen < oldLen)
+                    loroList.delete(newLen, oldLen - newLen);
+                return true;
+            }
+            if (typeof key === 'string' && /^\d+$/.test(key)) {
+                const idx = Number(key);
+                const oldLen = loroList.length;
+                if (idx < oldLen) {
+                    loroList.delete(idx, 1);
+                }
+                if (isPlainObject(value)) {
+                    const child = loroList.insertContainer(idx, new LoroMap());
+                    assignPlain(child, value);
+                }
+                else if (Array.isArray(value)) {
+                    const child = loroList.insertContainer(idx, new LoroList());
+                    assignList(child, value);
+                }
+                else {
+                    loroList.insert(idx, value);
+                }
+                return true;
+            }
+            return false;
+        },
+    };
+    return new Proxy([], handler);
+}
+const TAG_FIELD = 'type';
+const BODY_FIELD = 'params';
+// A page entry on the live LoroMap is a CONTAINER, not a plain
+// `{ type, params }`, so it must be materialised before the page codec
+// (which expects plain values) reads its tag / body.
+function pageValue(m, key) {
+    const v = m.get(key);
+    if (v instanceof LoroMap)
+        return v.toJSON();
+    return v;
+}
+// Decode a live paged `instances` map to the flat `key -> { type, params }`
+// lookup. `toJSON` materialises the page containers to the plain shape the
+// shared `flattenPagedLookup` consumes, so page flattening lives in one place.
+// Only ever called on the handle's paged path (guarded by `_isPaged()` /
+// `_pageCount`), so the store is known paged. Pass `paged: true` rather than
+// re-deriving it from a tag scan.
+function flattenPagedMap(m) {
+    return flattenPagedLookup(m.toJSON(), true);
+}
+// Resolve a single record without flattening the whole store: hash the key
+// to its page, decode only that page, find the triple. Keeps a per-key `get`
+// proportional to one page, not the whole file.
+function recordFromPage(m, recordKey, pageCount) {
+    const page = pageValue(m, pageKeyFor(recordKey, pageCount));
+    if (peekRecordTag(page) !== PAGE_TAG)
+        return undefined;
+    for (const packed of decodePageBody(decodeRecordValue(page)?.body)) {
+        if (Array.isArray(packed) && packed[0] === recordKey) {
+            return { [TAG_FIELD]: packed[1], [BODY_FIELD]: packed[2] };
+        }
+    }
+    return undefined;
+}
+// ---- Change deltas (`{ delta: true }` map subscribers) ----------------
+//
+// A delta subscriber reports which keys changed since the previous fire so a
+// render loop patches O(changed) rather than re-reading the container.
+//
+// Unpaged: read it off Loro's diff. A value reassign / add / delete shows on
+// the map's own diff (`target === m.id`); a field edit fires on the record's
+// nested container, so the record's key is the first path segment under root.
+//
+// Paged: a record edit rewrites the whole page container, so the diff names
+// the changed PAGE. Recover record granularity with a per-subscription
+// page -> keys index, diffing a changed page's current keys against it; a
+// deleted record was in the prior key set and absent from the rewritten page.
+// The root key of a root container (`cid:root-<key>:Map`), else null. A field
+// edit is keyed by its first path segment under root, which only a root
+// record map can resolve; nested handles fall back to direct keys only.
+function rootKeyOf(m) {
+    const match = /^cid:root-(.+):Map$/.exec(m.id);
+    return match?.[1] ?? null;
+}
+// The record keys currently packed into one page, or null for a missing /
+// non-page entry. Seeds and advances the page index for delete detection.
+function pageRecordKeys(m, pageKey) {
+    const records = pageRecords(m, pageKey);
+    return records ? new Set(records.keys()) : null;
+}
+// Decode one page to its `key -> { type, params }` records in a single pass,
+// so a paged delta gets the changed records' VALUES from the same decode it
+// uses to find the changed keys (a second per-key decode would make a large
+// initial build O(records x page-size)).
+function pageRecords(m, pageKey) {
+    const page = pageValue(m, pageKey);
+    if (peekRecordTag(page) !== PAGE_TAG)
+        return null;
+    const records = new Map();
+    for (const packed of decodePageBody(decodeRecordValue(page)?.body)) {
+        if (Array.isArray(packed) && typeof packed[0] === 'string') {
+            records.set(packed[0], { [TAG_FIELD]: packed[1], [BODY_FIELD]: packed[2] });
+        }
+    }
+    return records;
+}
+// Materialise one unpaged map entry to a plain value (containers via
+// `toJSON`, scalars passthrough), so a delta carries the changed value
+// without a re-read.
+function entryValue(m, key) {
+    const v = m.get(key);
+    if (v instanceof LoroMap || v instanceof LoroList)
+        return v.toJSON();
+    return v;
+}
+function buildPageIndex(m) {
+    const index = new Map();
+    for (const pageKey of m.keys()) {
+        const keys = pageRecordKeys(m, pageKey);
+        if (keys)
+            index.set(pageKey, keys);
+    }
+    return index;
+}
+function unpagedMapDelta(m, rootKey, batch) {
+    const setKeys = new Set();
+    const deleted = new Set();
+    for (const ev of batch.events) {
+        if (ev.target === m.id) {
+            if (ev.diff.type !== 'map')
+                continue;
+            for (const [key, value] of Object.entries(ev.diff.updated)) {
+                if (value === undefined)
+                    deleted.add(key);
+                else
+                    setKeys.add(key);
+            }
+        }
+        else if (rootKey !== null) {
+            // A descendant event (a field edit on a record's nested container).
+            // Every batch event is within the root map's subtree, so the record's
+            // key is the path segment directly under root.
+            const key = ev.path[1];
+            if (typeof key === 'string')
+                setKeys.add(key);
+        }
+    }
+    for (const key of deleted)
+        setKeys.delete(key);
+    const set = new Map();
+    for (const key of setKeys)
+        set.set(key, entryValue(m, key));
+    return { set, deleted: [...deleted] };
+}
+function pagedMapDelta(m, batch, pageIndex) {
+    const set = new Map();
+    const deleted = new Set();
+    for (const ev of batch.events) {
+        if (ev.target !== m.id || ev.diff.type !== 'map')
+            continue;
+        for (const pageKey of Object.keys(ev.diff.updated)) {
+            const before = pageIndex.get(pageKey);
+            const after = pageRecords(m, pageKey);
+            if (after) {
+                for (const [key, value] of after)
+                    set.set(key, value);
+                pageIndex.set(pageKey, new Set(after.keys()));
+            }
+            else {
+                pageIndex.delete(pageKey);
+            }
+            if (before) {
+                for (const key of before) {
+                    if (!after || !after.has(key))
+                        deleted.add(key);
+                }
+            }
+        }
+    }
+    for (const key of deleted)
+        set.delete(key);
+    return { set, deleted: [...deleted] };
+}
+// Run a flat-draft `mutate` against a PAGED store. The draft proxies an
+// OVERLAY of in-batch changes (key -> record, or a tombstone for a delete);
+// reads consult the overlay first then the stored page, so an edit is
+// visible to later reads in the same `fn` as on an unpaged live proxy.
+// Afterwards only the touched pages are decoded, rewritten, and re-encoded,
+// so a single field edit rewrites a single page. A `pruneRefs` sweep that
+// iterates the whole draft is the only path that reads every page, the rare
+// structural-delete case already treated as O(file).
+function mutatePaged(m, pageCount, fn) {
+    // A paged store always carries a positive `meta.page_count`, so a
+    // non-positive count means the store is corrupt: the page layout can't be
+    // resolved and guessing would scramble which record lives where. Refuse
+    // rather than corrupt.
+    if (pageCount <= 0) {
+        throw new Error('Cannot edit a paged record store with no page_count.');
+    }
+    const TOMBSTONE = Symbol('deleted');
+    // In-batch changes: key -> new record, or TOMBSTONE when deleted. Absent
+    // means "unchanged, read from the page".
+    const overlay = new Map();
+    // The record a draft read should see: the overlay value if touched this
+    // batch, else the stored record (one page decode).
+    const currentRecord = (key) => {
+        if (overlay.has(key)) {
+            const v = overlay.get(key);
+            return v === TOMBSTONE ? undefined : v;
+        }
+        return recordFromPage(m, key, pageCount);
+    };
+    // Per-record sub-proxy: a field assignment writes through to the overlay
+    // record so a later read sees it and the page rewrite picks it up. Field
+    // reads return the deep-plain stored value, so spreading `{ ...rec.params }`
+    // never leaks a live handle.
+    const recordProxy = (key) => {
+        return new Proxy({}, {
+            get(_t, field) {
+                if (typeof field === 'symbol')
+                    return undefined;
+                const rec = currentRecord(key);
+                return rec ? rec[field] : undefined;
+            },
+            set(_t, field, value) {
+                if (typeof field === 'symbol')
+                    return false;
+                const base = { ...currentRecord(key) };
+                base[field] = toPlainDeep(value);
+                overlay.set(key, base);
+                return true;
+            },
+        });
+    };
+    const draft = new Proxy({}, {
+        get(_t, key) {
+            if (typeof key === 'symbol')
+                return undefined;
+            if (currentRecord(key) === undefined)
+                return undefined;
+            return recordProxy(key);
+        },
+        set(_t, key, value) {
+            if (typeof key === 'symbol')
+                return false;
+            overlay.set(key, toPlainDeep(value));
+            return true;
+        },
+        deleteProperty(_t, key) {
+            if (typeof key === 'symbol')
+                return false;
+            overlay.set(key, TOMBSTONE);
+            return true;
+        },
+        has(_t, key) {
+            if (typeof key === 'symbol')
+                return false;
+            return currentRecord(key) !== undefined;
+        },
+        ownKeys() {
+            // Stored keys plus added, minus deleted.
+            const keys = new Set(Object.keys(flattenPagedMap(m)));
+            for (const [k, v] of overlay) {
+                if (v === TOMBSTONE)
+                    keys.delete(k);
+                else
+                    keys.add(k);
+            }
+            return [...keys];
+        },
+        getOwnPropertyDescriptor(_t, key) {
+            if (typeof key === 'symbol')
+                return undefined;
+            if (currentRecord(key) === undefined)
+                return undefined;
+            return { enumerable: true, configurable: true, writable: true };
+        },
+    });
+    fn(draft);
+    if (overlay.size === 0)
+        return;
+    applyOverlay(m, pageCount, overlay, TOMBSTONE);
+}
+// Rewrite the pages the overlay touched: each is decoded once, untouched
+// records carried over, changed records re-stated (or dropped on a
+// tombstone), then re-encoded (or deleted if it ends empty).
+function applyOverlay(m, pageCount, overlay, tombstone) {
+    const touchedPages = new Set();
+    for (const key of overlay.keys()) {
+        touchedPages.add(pageKeyFor(key, pageCount));
+    }
+    for (const pageKey of touchedPages) {
+        const existing = pageValue(m, pageKey);
+        const triples = [];
+        // Carry over the page's untouched records.
+        if (peekRecordTag(existing) === PAGE_TAG) {
+            for (const packed of decodePageBody(decodeRecordValue(existing)?.body)) {
+                if (Array.isArray(packed) &&
+                    typeof packed[0] === 'string' &&
+                    !overlay.has(packed[0])) {
+                    triples.push(packed);
+                }
+            }
+        }
+        // Add the overlay's survivors that hash to this page.
+        for (const [key, rec] of overlay) {
+            if (rec === tombstone)
+                continue;
+            if (pageKeyFor(key, pageCount) !== pageKey)
+                continue;
+            const r = rec;
+            triples.push([key, String(r[TAG_FIELD] ?? ''), r[BODY_FIELD]]);
+        }
+        if (triples.length === 0) {
+            if (existing !== undefined)
+                m.delete(pageKey);
+            continue;
+        }
+        const page = m.setContainer(pageKey, new LoroMap());
+        page.set(TAG_FIELD, PAGE_TAG);
+        page.set(BODY_FIELD, encodePageBody(triples));
+    }
+}
+// A root anchor holds one container that a version checkout swaps in place
+// (`rebind`). Between rebinds `resolve()` returns the same instance, so the
+// per-container Loro subscription attaches to a stable identity. `LoroMap` and
+// `LoroList` roots share this; the kind is the type parameter.
+function rootAnchor(root) {
+    let current = root;
+    return {
+        resolve: () => current,
+        resolveOrCreate: () => current,
+        invalidate: () => { },
+        rebind: (next) => {
+            current = next;
+        },
+    };
+}
+// A child anchor resolves `parent[key]` lazily, then caches the container so
+// per-container subscribers attach to a stable instance. `ctor` selects the
+// container kind: a value of the wrong kind at the key reads as absent, and
+// `resolveOrCreate` mints one only inside a mutate context.
+function childAnchor(parent, key, ctor) {
+    // `invalidate` clears the cache on a source swap so the next resolve
+    // re-derives through the (rebound) parent.
+    let cached = null;
+    // A cached container is stale once it has been detached from the document
+    // (deleted from `parent[key]`), which happens on a delete-then-recreate of
+    // the key: the recreate mints a NEW container, so a cache holding the old
+    // one would read and subscribe against a dead container. `isDeleted()` is
+    // the cheap per-resolve check that keeps the cache without going stale;
+    // `invalidate()` still handles the source swap (checkout / resync).
+    const live = (c) => c !== null && !c.isDeleted();
+    return {
+        resolve: () => {
+            if (live(cached))
+                return cached;
+            cached = null;
+            const p = parent.resolve();
+            if (!p)
+                return null;
+            const v = p.get(key);
+            if (v instanceof ctor) {
+                cached = v;
+                return cached;
+            }
+            return null;
+        },
+        resolveOrCreate: () => {
+            if (live(cached))
+                return cached;
+            cached = null;
+            const p = parent.resolveOrCreate();
+            const v = p.get(key);
+            if (v instanceof ctor) {
+                cached = v;
+                return cached;
+            }
+            const created = p.setContainer(key, new ctor());
+            cached = created;
+            return created;
+        },
+        invalidate: () => {
+            cached = null;
+        },
+    };
+}
+// Shared per-container subscription bookkeeping for both handle kinds. Holds
+// the active { callback, detach } records so a version checkout can re-fire
+// and re-attach each against the swapped source, and a suspend / close can
+// detach them all. Each kind passes in its own whole-container fire and its
+// per-container change-attach; this owns only the record set and its
+// lifecycle. (The `createEmitter` primitive is a value-fanout with retain /
+// dedup, a different shape: it models no per-listener external resource, and
+// the Loro subscription each record must re-create on rebind is exactly
+// that.)
+class SubscriptionRegistry {
+    _subs = new Set();
+    // Fire the whole-container catch-up once, attach the per-container change
+    // subscription, track the record, and return an idempotent unsubscribe.
+    subscribe(cb, fireWhole, attach) {
+        fireWhole(cb);
+        const rec = { cb, detach: attach(cb) };
+        this._subs.add(rec);
+        return () => {
+            rec.detach();
+            this._subs.delete(rec);
+        };
+    }
+    // Re-fire every active subscriber with the whole current container and
+    // re-attach its change subscription to it (checkout / return-to-head).
+    resync(fireWhole, attach) {
+        for (const rec of this._subs) {
+            rec.detach();
+            fireWhole(rec.cb);
+            rec.detach = attach(rec.cb);
+        }
+    }
+    // Detach every active subscription and forget it (suspend / close).
+    teardown() {
+        for (const rec of this._subs)
+            rec.detach();
+        this._subs.clear();
+    }
+}
+class MapHandleImpl {
+    _anchor;
+    _owner;
+    // The store's page count (0 when unpaged). `null` for handles that can
+    // never be a record store's `instances` root (composed child handles, and
+    // doc-less roots), which skip the paged paths entirely.
+    _pageCount;
+    // The paging scheme of the record store this root maps, read the same way
+    // and at the same time as `_pageCount` (both off the active source's `meta`).
+    // `null` for any handle that is never a record store's `instances` root.
+    _pagingScheme;
+    _childMaps = new Map();
+    _childLists = new Map();
+    // Active subscriptions, tracked so a version checkout (which swaps the
+    // active source doc) can re-fire and re-attach each one against the new
+    // container.
+    _registry = new SubscriptionRegistry();
+    // Keys captured just before a rebind (`_rebindAnchor`), consumed by the
+    // matching `_resync` to report the keys the source swap removed. Null
+    // outside a rebind cycle, so a bare `_resync` reports no removals.
+    _priorKeys = null;
+    constructor(anchor, owner, pageCount = null, pagingScheme = null) {
+        this._anchor = anchor;
+        this._owner = owner;
+        this._pageCount = pageCount;
+        this._pagingScheme = pagingScheme;
+    }
+    // Whether the map is a PAGED record store. Defined by `meta.page_count`
+    // (set whenever the writer pages, never changed by a field edit), threaded
+    // in as `_pageCount` and read in O(1). MUST stay O(1): it is on the hot
+    // path of every `read` / `mutate` (twice per ordered-map edit), so scanning
+    // the map to peek tags would make a single field edit O(file).
+    _isPaged() {
+        return this._pageCount !== null && this._pageCount() > 0;
+    }
+    // Whether this build's page-key hash matches the scheme the store was
+    // written under. A per-key `get` hashes the key to its page (`pageKeyFor`),
+    // so a store written under a NEWER scheme (one that changed the hash) would
+    // be looked up in the wrong page and read back as absent. When this is
+    // false, the per-key read paths fall back to the hash-independent whole-store
+    // flatten (O(file), only on this rare newer-scheme read) so `get` / `has`
+    // agree with `read()` instead of silently reporting present records missing.
+    // The edit path refuses such a store loudly (`_runMutate`); reads stay
+    // best-effort. Absent / current-or-older scheme is a match.
+    _pageHashMatchesStore() {
+        return !this._pagingScheme || isPagingSchemeEditable(this._pagingScheme());
+    }
+    read() {
+        const m = this._anchor.resolve();
+        if (!m)
+            return {};
+        // A paged map flattens back to the flat lookup, so a read is identical
+        // paged or not.
+        if (this._isPaged())
+            return flattenPagedMap(m);
+        return m.toJSON();
+    }
+    get(entryKey) {
+        const m = this._anchor.resolve();
+        if (!m)
+            return undefined;
+        if (this._isPaged()) {
+            // A newer-scheme store hashes keys differently, so a per-page lookup
+            // would miss present records; flatten instead (see `_pageHashMatchesStore`).
+            if (!this._pageHashMatchesStore()) {
+                return flattenPagedMap(m)[entryKey];
+            }
+            // Decode only the key's page, so a per-key `get` stays proportional to
+            // one page.
+            return recordFromPage(m, entryKey, this._pageCount());
+        }
+        const v = m.get(entryKey);
+        if (v === undefined)
+            return undefined;
+        if (v instanceof LoroMap)
+            return v.toJSON();
+        if (v instanceof LoroList)
+            return v.toJSON();
+        return v;
+    }
+    keys() {
+        const m = this._anchor.resolve();
+        if (!m)
+            return [];
+        if (this._isPaged())
+            return Object.keys(flattenPagedMap(m));
+        return m.keys();
+    }
+    has(entryKey) {
+        const m = this._anchor.resolve();
+        if (!m)
+            return false;
+        if (this._isPaged())
+            return this.get(entryKey) !== undefined;
+        return m.get(entryKey) !== undefined;
+    }
+    mutate(fn) {
+        this._owner.assertWritable();
+        this._owner.ensureLocalUpdatesSubscribed();
+        // Commits as it goes past a size budget; see `mutate-batching.ts`.
+        this._runMutate(fn, new MutateBatcher(() => {
+            this._owner.commitMutate();
+        }));
+        this._owner.commitMutate();
+    }
+    // Run a mutate WITHOUT the commit pipeline (the caller owns
+    // assertWritable / ensureLocalUpdatesSubscribed / commit). The seam the
+    // ordered-map primitive drives so a map edit and its sibling order-list
+    // edit land in ONE commit (one undo step).
+    _runMutate(fn, batcher) {
+        const m = this._anchor.resolveOrCreate();
+        if (this._isPaged()) {
+            // A store written under a paging scheme this build does not implement
+            // would be mis-hashed by `pageKeyFor`, so an in-place edit would write a
+            // record into the wrong page. Refuse loudly rather than corrupt it; the
+            // read path stays best-effort (only a persisted edit can corrupt).
+            if (this._pagingScheme && !isPagingSchemeEditable(this._pagingScheme())) {
+                throw new BrassError('This document was saved in a newer storage format. Update this app to the latest @brass-build/client to edit it.', { status: 426 });
+            }
+            mutatePaged(m, this._pageCount(), fn);
+            return;
+        }
+        const proxy = wrapLoroMapProxy(m, batcher);
+        fn(proxy);
+    }
+    // Paged writes defer to `applyOverlay` at the end of the mutation, so an
+    // intermediate commit there would seal no records (and, on an ordered
+    // map, order entries for records not yet written). Their ops are bounded
+    // by page size anyway.
+    _canBatchMutate() {
+        return !this._isPaged();
+    }
+    // A predicate over the map's CURRENT stored key set, resolved ONCE so a
+    // caller checking many keys doesn't re-scan per key. The ordered-map
+    // primitive uses it to decide, per set, whether a key is new (and so must
+    // be appended to the order list) without paying O(map) per added key.
+    _existsChecker() {
+        const m = this._anchor.resolve();
+        if (!m)
+            return () => false;
+        if (this._isPaged()) {
+            // Newer-scheme store: the per-page hash would miss records, so resolve
+            // the whole flattened key set once (see `_pageHashMatchesStore`).
+            if (!this._pageHashMatchesStore()) {
+                const flat = flattenPagedMap(m);
+                return (key) => Object.prototype.hasOwnProperty.call(flat, key);
+            }
+            const pageCount = this._pageCount();
+            return (key) => recordFromPage(m, key, pageCount) !== undefined;
+        }
+        return (key) => m.get(key) !== undefined;
+    }
+    // Fire a subscriber once with the whole map as `change.set`, so a
+    // subscriber is ONE loop with no initial-vs-update branch and no
+    // `if (value)` guard (the footgun that left a view stale after an undo /
+    // remote delete emptied the container). Flagged `resync: true` and carries
+    // no `origin`: this is a whole-container catch-up (registration, or a
+    // checkout / return swapping the source), not an authored transition.
+    //
+    // `deleted` is empty for a registration fire (the subscriber holds no prior
+    // state). On a resync it carries the keys that were present before the
+    // source swap but are gone after it: a checkout to a version with fewer
+    // records must tell a delta-reconcile subscriber to drop those keys, or they
+    // linger as phantom records in the preview. `_resync` computes it.
+    _fireWhole(cb, deleted = []) {
+        try {
+            cb({ set: new Map(Object.entries(this.read())), deleted }, undefined, true);
+        }
+        catch {
+            // A throwing subscriber must not break registration / resync.
+        }
+    }
+    // Attach the per-container change subscription for `cb` to the CURRENT
+    // resolved container, returning its detach. The container instance is
+    // captured here (Loro's subscribe is per-container), so a source swap
+    // re-runs this against the new container.
+    _attachChange(cb) {
+        const m = this._anchor.resolve();
+        // If the container doesn't exist yet (a composed handle for a missing
+        // entry), only the whole-fire happens; the change subscription attaches
+        // once a later `doc.map(key)` / `mutate` materializes it. Root handles
+        // are always materialized (`getMap` is get-or-create).
+        if (!m)
+            return () => { };
+        // Paged delta needs prior page state to spot deleted records, so index
+        // the pages once now; the index advances on every fire or its next delete
+        // diff is wrong. Unpaged maps read their delta off the Loro diff.
+        const pageIndex = this._isPaged() ? buildPageIndex(m) : null;
+        const rootKey = rootKeyOf(m);
+        const sub = m.subscribe((event) => {
+            const change = (pageIndex
+                ? pagedMapDelta(m, event, pageIndex)
+                : unpagedMapDelta(m, rootKey, event));
+            const origin = { source: this._owner.originOf(event) };
+            try {
+                cb(change, origin, false);
+            }
+            catch {
+                // A throwing subscriber must not affect the others.
+            }
+        });
+        return () => sub();
+    }
+    subscribe(cb) {
+        // App subscribers see `(change, origin?)`; the internal re-sync flag is
+        // dropped here so it never leaks into the public surface.
+        return this._subscribeInternal((change, origin) => cb(change, origin));
+    }
+    // Internal: like `subscribe`, but the callback also receives whether the
+    // fire is a whole-container re-sync. Only the ordered-map wrapper uses it,
+    // to re-check `instance_order` on a source swap without inspecting `origin`.
+    _subscribeInternal(cb) {
+        return this._registry.subscribe(cb, (c) => this._fireWhole(c), (c) => this._attachChange(c));
+    }
+    // Re-point this ROOT handle to `next` (a container in the newly-active
+    // source doc) WITHOUT firing yet. Called by the Document on a version
+    // checkout / return-to-head. Snapshots the subtree's current keys first,
+    // before the anchor moves, so the subsequent `_resync` can report which keys
+    // the swap removed. Rebind and resync are two phases (see
+    // `_rebindRootHandles`) because the ordered map reads its sibling order list
+    // while firing its map: both anchors must already point at the new source
+    // when either fires, or the map redraw reads a half-swapped order list.
+    _rebindAnchor(next) {
+        this._snapshotPriorKeys();
+        this._anchor.rebind(next);
+    }
+    // Capture the current key set of this handle and its composed child maps,
+    // read against the CURRENT (pre-rebind) source, so `_resync` can diff it
+    // against the post-rebind source to find removed keys. Runs before the
+    // anchor moves; child maps resolve through this anchor, so they must be read
+    // now too.
+    _snapshotPriorKeys() {
+        this._priorKeys = new Set(Object.keys(this.read()));
+        for (const child of this._childMaps.values())
+            child._snapshotPriorKeys();
+    }
+    // Re-fire every active subscriber with the whole current container (plus the
+    // keys the source swap removed, from the pre-rebind snapshot) and re-attach
+    // its change subscription to it, then recurse into composed child handles
+    // (their anchors resolve through this one, so they already point at the new
+    // source; their subscriptions still need re-attaching). Idempotent and safe
+    // when there are no subscribers.
+    _resync() {
+        // Re-derive this handle's container from the (already-rebound) parent
+        // before reading or re-attaching: a child anchor caches its resolved
+        // container, and after a source swap that cache points at the old source.
+        // Prior keys were snapshotted pre-rebind, so this cannot lose them.
+        this._anchor.invalidate();
+        const prior = this._priorKeys;
+        this._priorKeys = null;
+        const currentKeys = new Set(Object.keys(this.read()));
+        const removed = prior
+            ? [...prior].filter((k) => !currentKeys.has(k))
+            : [];
+        this._registry.resync((c) => this._fireWhole(c, removed), (c) => this._attachChange(c));
+        for (const child of this._childMaps.values())
+            child._resync();
+        for (const child of this._childLists.values())
+            child._resync();
+    }
+    // Detach every active per-container subscription (this handle's and its
+    // composed children's) and forget them. The Document calls this when it
+    // suspends (parks) or closes: a parked doc keeps applying remote ops to its
+    // live containers, so a Loro subscription an app registered before `close()`
+    // would otherwise keep firing the app's callback on a doc it has closed.
+    _teardownSubs() {
+        this._registry.teardown();
+        for (const child of this._childMaps.values())
+            child._teardownSubs();
+        for (const child of this._childLists.values())
+            child._teardownSubs();
+    }
+    map(entryKey) {
+        let h = this._childMaps.get(entryKey);
+        if (!h) {
+            const anchor = childAnchor(this._anchor, entryKey, LoroMap);
+            h = new MapHandleImpl(anchor, this._owner);
+            this._childMaps.set(entryKey, h);
+        }
+        return h;
+    }
+    list(entryKey) {
+        let h = this._childLists.get(entryKey);
+        if (!h) {
+            const anchor = childAnchor(this._anchor, entryKey, LoroList);
+            h = new ListHandleImpl(anchor, this._owner);
+            this._childLists.set(entryKey, h);
+        }
+        return h;
+    }
+}
+class ListHandleImpl {
+    _anchor;
+    _owner;
+    // Active subscriptions, tracked so a version checkout can re-fire and
+    // re-attach each one against the new container.
+    _registry = new SubscriptionRegistry();
+    constructor(anchor, owner) {
+        this._anchor = anchor;
+        this._owner = owner;
+    }
+    read() {
+        const l = this._anchor.resolve();
+        if (!l)
+            return [];
+        return l.toJSON();
+    }
+    length() {
+        const l = this._anchor.resolve();
+        return l ? l.length : 0;
+    }
+    mutate(fn) {
+        this._owner.assertWritable();
+        this._owner.ensureLocalUpdatesSubscribed();
+        this._runMutate(fn);
+        this._owner.commitMutate();
+    }
+    // Run a list mutate without the commit pipeline; see
+    // `MapHandleImpl._runMutate`. The ordered-map primitive drives this to
+    // reconcile the order list in the same commit as the map edit.
+    _runMutate(fn) {
+        const l = this._anchor.resolveOrCreate();
+        const proxy = wrapLoroListProxy(l);
+        fn(proxy);
+    }
+    // Fire once (positional lists have no per-key delta, so a fire is a signal
+    // to re-read). Used for registration and for a checkout / return resync.
+    _fireWhole(cb) {
+        try {
+            cb();
+        }
+        catch {
+            // A throwing subscriber must not break registration / resync.
+        }
+    }
+    // Attach the per-container change subscription for `cb` to the CURRENT
+    // resolved container, returning its detach.
+    _attachChange(cb) {
+        // Same caveat as MapHandleImpl: the change subscription needs the
+        // container to exist. Root lists are materialized by `doc.list(key)`;
+        // nested lists need a prior mutate.
+        const l = this._anchor.resolve();
+        if (!l)
+            return () => { };
+        const sub = l.subscribe(() => this._fireWhole(cb));
+        return () => sub();
+    }
+    subscribe(cb) {
+        return this._registry.subscribe(cb, (c) => this._fireWhole(c), (c) => this._attachChange(c));
+    }
+    // Re-point this ROOT list handle to `next` without firing (see
+    // MapHandleImpl._rebindAnchor). Lists carry no per-key delta, so there is
+    // no prior-key snapshot to take; the resync fire is a re-read signal.
+    _rebindAnchor(next) {
+        this._anchor.rebind(next);
+    }
+    // Re-fire + re-attach every active subscriber against the current
+    // container (see MapHandleImpl._resync). Lists have no composed children,
+    // but a child list handle (`doc.map(k).list(j)`) has a cached anchor that a
+    // source swap leaves pointing at the old source, so invalidate it first.
+    _resync() {
+        this._anchor.invalidate();
+        this._registry.resync((c) => this._fireWhole(c), (c) => this._attachChange(c));
+    }
+    // Detach every active subscription and forget it (see
+    // MapHandleImpl._teardownSubs). Lists have no composed children.
+    _teardownSubs() {
+        this._registry.teardown();
+    }
+}
+// The ordered map composes a map handle and a list handle and keeps them in
+// lockstep. It reuses the concrete impls (not the interfaces) to drive their
+// no-commit `_runMutate` seams and the map's `_existsChecker`, so both halves
+// of a structural edit commit once. Built over the SAME handles
+// `doc.map(mapKey)` / `doc.list(orderKey)` return, so subscriptions stay
+// consistent.
+class OrderedMapHandleImpl {
+    _map;
+    _order;
+    _owner;
+    constructor(_map, _order, _owner) {
+        this._map = _map;
+        this._order = _order;
+        this._owner = _owner;
+    }
+    read() {
+        return this._map.read();
+    }
+    get(entryKey) {
+        return this._map.get(entryKey);
+    }
+    has(entryKey) {
+        return this._map.has(entryKey);
+    }
+    keys() {
+        // Filter to keys still in the map: the primitive keeps the two in step,
+        // but a hand-written or stale order list must not surface a key the map
+        // no longer has. Read the map ONCE (its bulk snapshot) and test
+        // membership against it, the same shape `ordered()` uses. A per-key
+        // `_existsChecker` predicate would re-decode a paged store's page once
+        // per record it holds (one gunzip per key, ~page-size times per page),
+        // and `subscribe` calls this on every structural move, so a single edit
+        // on a large paged doc would cost O(records) page decodes instead of
+        // O(pages).
+        const records = this._map.read();
+        return this._order
+            .read()
+            .filter((k) => Object.prototype.hasOwnProperty.call(records, k));
+    }
+    ordered() {
+        const records = this._map.read();
+        const out = [];
+        for (const key of this._order.read()) {
+            if (Object.prototype.hasOwnProperty.call(records, key)) {
+                out.push({ key, value: records[key] });
+            }
+        }
+        return out;
+    }
+    mutate(fn) {
+        this._owner.assertWritable();
+        this._owner.ensureLocalUpdatesSubscribed();
+        // Net structural effect: keys added (`added` iterates in insertion
+        // order, and a delete-then-re-set re-appends, matching the order list's
+        // append semantics) and removed. A field edit routes through the inner
+        // record sub-proxy and never trips the top-level set / delete traps, so
+        // it leaves the order list alone.
+        const added = new Set();
+        const removed = new Set();
+        // Run at each batch boundary, so a commit carries the map writes AND
+        // the order entries for those same records. Left to the end instead,
+        // the final commit carries every key at once: measured at 229 KB for a
+        // 20,000-record write, an oversized op of its own.
+        const reconcileOrder = () => {
+            if (added.size === 0 && removed.size === 0)
+                return;
+            this._order._runMutate((arr) => {
+                if (removed.size > 0) {
+                    const kept = arr.filter((k) => !removed.has(k));
+                    arr.length = 0;
+                    for (const k of kept)
+                        arr.push(k);
+                }
+                for (const k of added)
+                    arr.push(k);
+            });
+            added.clear();
+            removed.clear();
+        };
+        const batcher = this._map._canBatchMutate()
+            ? new MutateBatcher(() => {
+                reconcileOrder();
+                this._owner.commitMutate();
+            })
+            : null;
+        this._map._runMutate((inner) => {
+            // "is this key new" (and so must be appended to the order list) is O(1)
+            // per set; a repeat set of the same new key is guarded by `added`.
+            // `exists` reflects the key set at the start of the batch for a paged
+            // store (its writes are deferred to `applyOverlay`), but an UNPAGED
+            // proxy writes through to the live map immediately, so a key deleted
+            // earlier in this same batch reads as absent from `exists`. `removed`
+            // records exactly those keys, so "present before the batch" is
+            // `exists(k) || removed.has(k)`; consulting both keeps a delete-then-
+            // re-add of a pre-existing key from being mis-seen as a fresh add and
+            // appended to the order list a second time.
+            const exists = this._map._existsChecker();
+            const tracking = new Proxy({}, {
+                get: (_t, key) => typeof key === 'symbol'
+                    ? inner[key]
+                    : inner[key],
+                set: (_t, key, value) => {
+                    if (typeof key === 'symbol')
+                        return false;
+                    const k = key;
+                    if (!added.has(k) && !exists(k) && !removed.has(k)) {
+                        added.add(k);
+                    }
+                    // A re-add after a delete in the same batch cancels the delete.
+                    removed.delete(k);
+                    inner[k] = value;
+                    return true;
+                },
+                deleteProperty: (_t, key) => {
+                    if (typeof key === 'symbol')
+                        return false;
+                    const k = key;
+                    if (added.has(k)) {
+                        // Added and removed in one batch: it never reached the order
+                        // list, so just forget the addition.
+                        added.delete(k);
+                    }
+                    else if (exists(k)) {
+                        // Only track a removal that actually drops a key present in the
+                        // order list before this batch. `exists(k)` reads the key set at
+                        // batch start (paged defers writes; an unpaged key untouched so
+                        // far this batch reads its start state), so it is true only for a
+                        // genuinely-present key. Deleting a key that was already absent
+                        // must NOT enter `removed`: a later re-`set` of that key in the
+                        // same batch consults `removed.has(k)` to decide "re-add of a
+                        // pre-existing key" (skip the order append) vs "fresh add"
+                        // (append). A spurious `removed` entry makes the fresh add look
+                        // like a re-add, so the key lands in the record map but never in
+                        // `instance_order`, a silent divergence between the two.
+                        removed.add(k);
+                    }
+                    delete inner[k];
+                    return true;
+                },
+                has: (_t, key) => typeof key === 'symbol'
+                    ? false
+                    : key in inner,
+                ownKeys: () => Reflect.ownKeys(inner),
+                getOwnPropertyDescriptor: (_t, key) => Object.getOwnPropertyDescriptor(inner, key),
+            });
+            fn(tracking);
+        }, batcher ?? undefined);
+        reconcileOrder();
+        this._owner.commitMutate();
+    }
+    subscribe(cb) {
+        // Content (`set` / `deleted`) rides the map subscription. `order` is
+        // attached ONLY when the order moved; a field edit must not pay for a
+        // re-sequence. A move is detected in O(changed) by testing changed keys
+        // against a cached membership set; the ordered keys (O(order)) are read
+        // only on a move. `known` starts empty so the initial fire reads as an
+        // all-new move and carries the starting `order`.
+        //
+        // A `mutate` / remote delta only moves the order by changing the key set,
+        // which the cheap membership test catches. The exception is a
+        // whole-container re-sync (registration, or a checkout / return / hydrate
+        // swapping the source): it can present the SAME key set in a different
+        // `instance_order`, which the membership test cannot see. The fire tells
+        // us which it is (`resync`) directly, so on a re-sync we read the actual
+        // order (O(order), and these fires are rare) and treat only a genuine
+        // reorder as a move rather than every re-sync (else an empty registration
+        // and an unchanged-order checkout would both deliver a redundant `order`).
+        const known = new Set();
+        let lastOrder = [];
+        const sameOrder = (a, b) => a.length === b.length && a.every((k, i) => k === b[i]);
+        return this._map._subscribeInternal((change, origin, resync) => {
+            let moved = change.deleted.length > 0;
+            for (const key of change.set.keys())
+                if (!known.has(key))
+                    moved = true;
+            let orderKeys = null;
+            if (!moved && resync) {
+                orderKeys = this.keys();
+                if (!sameOrder(orderKeys, lastOrder))
+                    moved = true;
+            }
+            if (!moved) {
+                cb(change, origin);
+                return;
+            }
+            for (const key of change.deleted)
+                known.delete(key);
+            for (const key of change.set.keys())
+                known.add(key);
+            const order = orderKeys ?? this.keys();
+            lastOrder = order;
+            cb({ set: change.set, deleted: change.deleted, order }, origin);
+        });
+    }
+}
+// Factory functions called by the Document. App code reaches handles via
+// `doc.map(...)` / `doc.list(...)`.
+// `pageCount`, when supplied, lets the root map present a PAGED record store
+// transparently as a flat record map. The Document supplies it for every root
+// map; a non-paged map never consults it, so passing it to non-record roots
+// is harmless. Omitted means the handle only serves the plain unpaged shape.
+export function createRootMapHandle(root, owner, pageCount, pagingScheme) {
+    return new MapHandleImpl(rootAnchor(root), owner, pageCount ?? null, pagingScheme ?? null);
+}
+export function createRootListHandle(root, owner) {
+    return new ListHandleImpl(rootAnchor(root), owner);
+}
+// Re-point a ROOT handle to a container in a newly-active source doc and
+// resync its subscribers, in two phases. The Document calls these on a version
+// checkout / return-to-head so the handles an app already holds (its
+// `doc.map(key)` / `doc.list(key)` / `doc.orderedMap(...)` references) follow
+// the source swap and redraw, instead of being discarded and silently
+// detached. The cast is safe because this module is the only producer of these
+// interfaces.
+//
+// The two phases must be run across ALL root handles as two passes (rebind
+// every anchor, THEN resync every handle), not handle-by-handle, because a
+// composed handle can read a SIBLING root while firing: the ordered map reads
+// its order list during its map redraw. If the order list's anchor were still
+// on the old source when the map fired, the redraw would read a half-swapped
+// pair and drop the keys the order list had not caught up on.
+export function rebindRootMapAnchor(handle, next) {
+    handle._rebindAnchor(next);
+}
+export function rebindRootListAnchor(handle, next) {
+    handle._rebindAnchor(next);
+}
+// Re-fire + re-attach a root handle's subscribers against its current
+// container. Both concrete impls expose `_resync`, so one generic reaches
+// either kind; the cast is safe because this module is the only producer of
+// these handles.
+export function resyncRootHandle(handle) {
+    handle._resync();
+}
+// Detach a handle's live subscriptions (its own and its children's). The
+// Document calls this when it suspends (parks) or closes, so a subscription
+// registered before `close()` stops firing against the still-live containers
+// a parked doc keeps applying remote ops to. As with `resyncRootHandle`, one
+// generic reaches either kind.
+export function teardownRootHandle(handle) {
+    handle._teardownSubs();
+}
+// Bind a map handle and a list handle into an ordered map. The cast to the
+// concrete impls is safe because this module is the only producer of those
+// interfaces, and it lets the ordered map drive their no-commit seams.
+export function createOrderedMapHandle(map, order, owner) {
+    return new OrderedMapHandleImpl(map, order, owner);
+}
+//# sourceMappingURL=handles.js.map