@brass-build/client 0.4.1 → 0.5.0

package/dist/handles.js

@@ -5,8 +5,9 @@
 // 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 { LoroMovableList, LoroMap, isContainer, } from './wasm-runtime.js';
-import { PAGE_TAG, UNPAGED_MAX_RECORDS, PAGE_KEYS_FIELD, assertUsableRecordKey, classifyStoreKey, decodePageKeys, decodePageRecords, decodeRecordValue, encodePage, flattenPagedLookup, isReservedKey, overlayKeyFor, packWholeValue, parseSessionPageKey, repackRecord, parsePatchKey, patchKeyFor, applyRecordPatches, recordsPerPage, sampleBodyBytes, sessionPageKey, tombstoneKeyFor, unpackRecord, } from './record-paging.js';
+import { PAGE_TAG, UNPAGED_MAX_RECORDS, PAGE_KEYS_FIELD, BODY_FIELD, TAG_FIELD, assertUsableRecordKey, classifyStoreKey, decodePageKeys, decodePageRecords, decodeRecordValue, encodePage, flattenPagedLookup, isPagedMarkerEntry, isReservedKey, overlayKeyFor, packWholeValue, parseSessionPageKey, repackRecord, parsePatchKey, patchKeyFor, applyRecordPatches, recordsPerPage, sampleBodyBytes, sessionPageKey, tombstoneKeyFor, unpackRecord, } from './record-paging.js';
 import { MutateBatcher } from './mutate-batching.js';
+import { pushBoundedSplice } from './subscriber-delivery.js';
 // ---- Plain-JS-proxy machinery, scoped per-container --------------------
 function isPlainObject(v) {
     return (v !== null &&
@@ -153,19 +154,41 @@ function assignList(target, value) {
     // same position, so the pair leaves the entry stored twice while `set`
     // leaves it stored once. That is the same reasoning `assignListPosition`
     // carries, and a whole-array assign is the write that reaches it most.
+    //
+    // The entries both ends share are left alone, and only the span between
+    // them is rewritten. Dropping the first of `[a, b]` is then a delete of `a`
+    // rather than `b` set into position 0 and the tail cut off, which matters
+    // when a peer undoes its own edit to `b` concurrently: the undo removes the
+    // `b` it wrote, and a set of `b` would put one back.
     const oldLen = target.length;
-    for (let i = 0; i < value.length; i++) {
+    let head = 0;
+    while (head < oldLen &&
+        head < value.length &&
+        samePlainValue(plainListItem(target, head), materializeContainers(value[head]))) {
+        head += 1;
+    }
+    let tail = 0;
+    while (tail < oldLen - head &&
+        tail < value.length - head &&
+        samePlainValue(plainListItem(target, oldLen - 1 - tail), materializeContainers(value[value.length - 1 - tail]))) {
+        tail += 1;
+    }
+    const oldMid = oldLen - head - tail;
+    const newMid = value.length - head - tail;
+    const shared = Math.min(oldMid, newMid);
+    for (let i = head; i < head + shared; i++) {
         const item = materializeContainers(value[i]);
-        if (i >= oldLen) {
-            insertListAt(target, i, item);
-            continue;
-        }
         if (samePlainValue(plainListItem(target, i), item))
             continue;
         assignListPosition(target, i, item);
     }
-    if (value.length < oldLen) {
-        target.delete(value.length, oldLen - value.length);
+    if (newMid > oldMid) {
+        for (let i = head + oldMid; i < head + newMid; i++) {
+            insertListAt(target, i, materializeContainers(value[i]));
+        }
+    }
+    else if (oldMid > newMid) {
+        target.delete(head + newMid, oldMid - newMid);
     }
 }
 /** Whether a position already holds this value, so assigning it writes
@@ -212,12 +235,21 @@ function insertListTail(target, rawItem) {
 // stored twice, and `set` leaves it stored once.
 function assignListPosition(target, idx, rawItem) {
     const item = materializeContainers(rawItem);
+    // A position already holding a container of the same kind is written in
+    // place, as `assignEntry` does for a map key. A fresh container at the
+    // position is a replace that a peer's concurrent replace of the same
+    // position does not merge with, so undoing either one restores its old
+    // container beside the other's instead of in its place, and the list
+    // comes out one element longer on every peer.
+    const existing = target.get(idx);
     if (isPlainObject(item)) {
-        const child = target.setContainer(idx, new LoroMap());
+        const child = existing instanceof LoroMap ? existing : target.setContainer(idx, new LoroMap());
         assignPlain(child, item);
     }
     else if (Array.isArray(item)) {
-        const child = target.setContainer(idx, new LoroMovableList());
+        const child = existing instanceof LoroMovableList
+            ? existing
+            : target.setContainer(idx, new LoroMovableList());
         assignList(child, item);
     }
     else {
@@ -297,7 +329,7 @@ function writeThroughBody(value, commit) {
 // `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, 
+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
@@ -307,10 +339,14 @@ batcher, divert,
 // reserved space the store's own bookkeeping occupies. True for a root map,
 // which is what can page; false inside a record, whose field names are the
 // app's own and constrained by nothing.
-guardKeys = false) {
+guardKeys = false, 
+// The root this map is, which decides whether it carries platform entries
+// the draft hides and refuses (`isPagedMarkerEntry`).
+rootKey = null) {
+    const hidden = (key) => isPagedMarkerEntry(rootKey, key);
     const handler = {
         get(_t, key) {
-            if (typeof key === 'symbol')
+            if (typeof key === 'symbol' || hidden(key))
                 return undefined;
             if (divert?.holds(key)) {
                 const held = divert.peek(key);
@@ -354,7 +390,7 @@ guardKeys = false) {
             if (typeof key === 'symbol')
                 return false;
             if (guardKeys)
-                assertUsableRecordKey(key);
+                assertUsableRecordKey(key, rootKey);
             // Before the write, so a commit it triggers seals the preceding
             // batch rather than splitting this record out of it.
             batcher?.record(value);
@@ -371,7 +407,7 @@ guardKeys = false) {
             if (typeof key === 'symbol')
                 return false;
             if (guardKeys)
-                assertUsableRecordKey(key);
+                assertUsableRecordKey(key, rootKey);
             batcher?.recordDelete(key);
             divert?.drop(key);
             loroMap.delete(key);
@@ -379,19 +415,20 @@ guardKeys = false) {
             return true;
         },
         has(_t, key) {
-            if (typeof key === 'symbol')
+            if (typeof key === 'symbol' || hidden(key))
                 return false;
             if (divert?.holds(key))
                 return true;
             return loroMap.get(key) !== undefined;
         },
         ownKeys() {
+            const stored = loroMap.keys().filter((key) => !hidden(key));
             if (!divert)
-                return loroMap.keys();
-            return [...new Set([...loroMap.keys(), ...divert.keys()])];
+                return stored;
+            return [...new Set([...stored, ...divert.keys()])];
         },
         getOwnPropertyDescriptor(_t, key) {
-            if (typeof key === 'symbol')
+            if (typeof key === 'symbol' || hidden(key))
                 return undefined;
             if (divert?.holds(key)) {
                 return {
@@ -723,8 +760,6 @@ batcher) {
     };
     return new Proxy([], handler);
 }
-const TAG_FIELD = 'type';
-const BODY_FIELD = 'params';
 // The record keys one page packs, read off the live container without
 // materialising its bodies. Two fields out of wasm rather than the whole
 // container: a store's bodies are its bulk, and an index build asks every page
@@ -1244,7 +1279,9 @@ function buildPagedDeltaIndex(m) {
     }
     return { pages, shadowed };
 }
-function unpagedMapDelta(m, depth, batch) {
+// Null when every key the batch touched is one `hidden` withholds, so a
+// subscriber is not handed an empty change for an edit it cannot see.
+function unpagedMapDelta(m, depth, batch, hidden) {
     const setKeys = new Set();
     const deleted = new Set();
     for (const ev of batch.events) {
@@ -1269,10 +1306,15 @@ function unpagedMapDelta(m, depth, batch) {
     }
     for (const key of deleted)
         setKeys.delete(key);
+    const touched = setKeys.size + deleted.size;
     const set = new Map();
     for (const key of setKeys)
-        set.set(key, plainEntry(m, key));
-    return { set, deleted: [...deleted] };
+        if (!hidden(key))
+            set.set(key, plainEntry(m, key));
+    const removed = [...deleted].filter((key) => !hidden(key));
+    if (touched > 0 && set.size === 0 && removed.length === 0)
+        return null;
+    return { set, deleted: removed };
 }
 /**
  * Read a changed page out to the records it holds, and name the ones it lost.
@@ -2367,23 +2409,23 @@ function trackEntryContainer(root, spec) {
 // 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.)
-/** Run a callback the SDK owns, without letting it break the caller. */
-/** Report a subscriber that threw, then carry on. One app callback failing
- *  must not break a registration or stop the other subscribers, but swallowing
- *  it leaves an app that stalled inside its own callback with nothing in the
- *  console to read. */
-function reportSubscriberThrow(err) {
-    console.error('[Brass] subscriber threw:', err);
-}
-function fireQuietly(cb) {
+/** Run an app callback without letting a throw break the caller. One app
+ *  callback failing must not break a registration or stop the other
+ *  subscribers, so the throw goes to `report` (the owner's
+ *  `reportSubscriberThrow`) and the walk carries on. */
+function fireQuietly(cb, report) {
     try {
         cb();
     }
     catch (err) {
-        reportSubscriberThrow(err);
+        report(err);
     }
 }
 class SubscriptionRegistry {
+    _report;
+    constructor(_report) {
+        this._report = _report;
+    }
     _subs = new Set();
     _settled = new Set();
     // Whether a whole-container delivery is in progress. Always false while a
@@ -2413,7 +2455,7 @@ class SubscriptionRegistry {
     onSettled(cb) {
         this._settled.add(cb);
         if (!this._delivering)
-            fireQuietly(cb);
+            fireQuietly(cb, this._report);
         return () => {
             this._settled.delete(cb);
         };
@@ -2424,7 +2466,7 @@ class SubscriptionRegistry {
         // before it is reached is never visited.
         const listeners = Array.from(this._settled);
         for (const cb of listeners)
-            fireQuietly(cb);
+            fireQuietly(cb, this._report);
     }
     // Fire the whole-container catch-up once, attach the per-container change
     // subscription, track the record, and return an idempotent unsubscribe.
@@ -2492,7 +2534,7 @@ function sameStateVersion(a, b) {
  * Every field is declared with an initialiser, so they all exist by the time
  * this runs and a later assignment keeps the descriptor this sets.
  */
-function hideOwnFields(handle) {
+export function hideOwnFields(handle) {
     for (const key of Object.keys(handle)) {
         Object.defineProperty(handle, key, { enumerable: false });
     }
@@ -2515,7 +2557,7 @@ class MapHandleImpl {
     // 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();
+    _registry = new SubscriptionRegistry((err) => this._owner.reportSubscriberThrow(err));
     // 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.
@@ -2524,13 +2566,28 @@ class MapHandleImpl {
     // taken before the container exists watches up this chain for the write
     // that creates it (`_nearestLiveContainer`).
     _parent;
-    constructor(anchor, owner, paging = null, parent = null) {
+    // The document root this handle is, or null for a composed handle. Decides
+    // which keys are the platform's own entries rather than the app's
+    // (`isPagedMarkerEntry`), which every read here hides.
+    _rootKey;
+    constructor(anchor, owner, paging = null, parent = null, rootKey = null) {
         this._anchor = anchor;
         this._owner = owner;
         this._paging = paging;
         this._parent = parent;
+        this._rootKey = rootKey;
         hideOwnFields(this);
     }
+    _hidden(key) {
+        return isPagedMarkerEntry(this._rootKey, key);
+    }
+    // An unpaged map's JSON without the platform's own entries.
+    _visible(json) {
+        for (const key of Object.keys(json))
+            if (this._hidden(key))
+                delete json[key];
+        return json;
+    }
     // The container at the top of this handle's composition chain: the root it
     // is composed off, which the document holds for its whole life (`getMap` is
     // get-or-create, and a root anchor always resolves). A composed handle's
@@ -2566,6 +2623,14 @@ class MapHandleImpl {
         const v = this._anchor.plain?.();
         return isPlainObject(v) ? v : undefined;
     }
+    /** Whether the plain body this handle is scoped to holds this entry itself.
+     *  The prototype chain is not part of a record, so a key an app never wrote
+     *  must not resolve through it. */
+    _plainHas(entryKey) {
+        const body = this._plainBody();
+        return (body !== undefined &&
+            Object.prototype.hasOwnProperty.call(body, entryKey));
+    }
     read() {
         this._owner.assertReadable();
         const m = this._anchor.resolve();
@@ -2575,7 +2640,7 @@ class MapHandleImpl {
         // paged or not.
         if (this._isPaged())
             return this._readPaged(m);
-        return m.toJSON();
+        return this._visible(m.toJSON());
     }
     // The whole-store read, which decodes every page. That walk answers the same
     // question a keyed read asks (which page holds which record), so the index
@@ -2592,9 +2657,18 @@ class MapHandleImpl {
     }
     get(entryKey) {
         this._owner.assertReadable();
+        if (this._hidden(entryKey))
+            return undefined;
         const m = this._anchor.resolve();
-        if (!m)
-            return this._plainBody()?.[entryKey];
+        if (!m) {
+            // One read of the body, not one per check: `_plainBody` resolves the
+            // anchor and reaches into wasm, and this runs on every keyed read.
+            const body = this._plainBody();
+            return body !== undefined &&
+                Object.prototype.hasOwnProperty.call(body, entryKey)
+                ? body[entryKey]
+                : undefined;
+        }
         if (this._isPaged()) {
             const pager = this._sessionPager(m);
             return recordFromPage(m, entryKey, this._pageMemo, pager.liveIndex, pager.patches(m));
@@ -2604,6 +2678,14 @@ class MapHandleImpl {
     keys() {
         return [...this.liveKeySet()];
     }
+    // Taken from one whole read: on a paged store that is the pass resolving
+    // every record against the patches and markers that shadow it, which a walk
+    // key by key would repeat per record.
+    *entries() {
+        const records = this.read();
+        for (const key of Object.keys(records))
+            yield [key, records[key]];
+    }
     /**
      * The keys this map holds, as a set, without materialising a record.
      *
@@ -2619,27 +2701,29 @@ class MapHandleImpl {
             return new Set(Object.keys(this._plainBody() ?? {}));
         if (this._isPaged())
             return this._sessionPager(m).ensureIndex(m).liveKeys();
-        return new Set(m.keys());
+        return new Set(m.keys().filter((key) => !this._hidden(key)));
     }
     has(entryKey) {
         this._owner.assertReadable();
+        if (this._hidden(entryKey))
+            return false;
         const m = this._anchor.resolve();
-        if (!m) {
-            const body = this._plainBody();
-            return body !== undefined && Object.prototype.hasOwnProperty.call(body, entryKey);
-        }
+        if (!m)
+            return this._plainHas(entryKey);
         if (this._isPaged())
             return this.get(entryKey) !== undefined;
         return entryExists(m, entryKey);
     }
-    mutate(fn) {
+    mutate(fn, options) {
         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.runMutate(options, () => {
+            // Commits as it goes past a size budget; see `mutate-batching.ts`.
+            this._runMutate(fn, new MutateBatcher(() => {
+                this._owner.commitMutate();
+            }));
             this._owner.commitMutate();
-        }));
-        this._owner.commitMutate();
+        });
     }
     // Run a mutate WITHOUT the commit pipeline (the caller owns
     // assertWritable / ensureLocalUpdatesSubscribed / commit). The seam the
@@ -2654,7 +2738,7 @@ class MapHandleImpl {
             return;
         }
         const divert = this._paging ? this._pagingDivert(m, batcher) : null;
-        const proxy = wrapLoroMapProxy(m, batcher, divert?.hooks, this._paging !== null);
+        const proxy = wrapLoroMapProxy(m, batcher, divert?.hooks, this._paging !== null, this._rootKey);
         fn(proxy);
         divert?.finish();
     }
@@ -2977,7 +3061,7 @@ class MapHandleImpl {
         }
         // One walk of an unpaged map, whose size the paging threshold bounds, and
         // no wasm handle minted per key the way a per-key read would.
-        const keys = new Set(m.keys());
+        const keys = new Set(m.keys().filter((key) => !this._hidden(key)));
         return (key) => keys.has(key);
     }
     // Fire a subscriber once with the whole map as `change.set`, so a
@@ -3003,7 +3087,7 @@ class MapHandleImpl {
             }, undefined, true);
         }
         catch (err) {
-            reportSubscriberThrow(err);
+            this._owner.reportSubscriberThrow(err);
         }
     }
     // Attach the change subscription for `cb`, returning its detach.
@@ -3077,13 +3161,15 @@ class MapHandleImpl {
             }
             const change = (index
                 ? pagedMapDelta(m, event, index, (key) => this.get(key))
-                : unpagedMapDelta(m, depth, event));
+                : unpagedMapDelta(m, depth, event, (key) => this._hidden(key)));
+            if (change === null)
+                return;
             const origin = { source: this._owner.originOf(event) };
             try {
                 cb(change, origin, false);
             }
             catch (err) {
-                reportSubscriberThrow(err);
+                this._owner.reportSubscriberThrow(err);
             }
         });
         return () => sub();
@@ -3216,7 +3302,7 @@ class MapHandleImpl {
         const direct = childAnchor(this._anchor, entryKey, ctor);
         if (this._paging === null)
             return direct;
-        assertUsableRecordKey(entryKey);
+        assertUsableRecordKey(entryKey, this._rootKey);
         const overlay = childAnchor(this._anchor, overlayKeyFor(entryKey), ctor);
         // Whether an edit written beside the pages is waiting to be folded over
         // this record. Asked only once a container has been found, since a record
@@ -3313,6 +3399,20 @@ class MapHandleImpl {
  * carry the position each edit lands at, so an app applies them in order and
  * is done; nothing about the cursor reaches it.
  */
+/** Whether position `at`, read after the first `count` splices, is one of the
+ *  elements those splices inserted. */
+function insertedBySplices(splices, count, at) {
+    let pos = at;
+    for (let i = count - 1; i >= 0; i--) {
+        const { at: start, removed, inserted } = splices[i];
+        if (pos < start)
+            continue;
+        if (pos < start + inserted.length)
+            return true;
+        pos += removed - inserted.length;
+    }
+    return false;
+}
 function splicesFromListDiff(diff) {
     const out = [];
     let at = 0;
@@ -3327,7 +3427,7 @@ function splicesFromListDiff(diff) {
         }
         if (part.insert !== undefined) {
             const inserted = part.insert.map(plainDiffItem);
-            out.push({ at, removed: 0, inserted });
+            pushBoundedSplice(out, { at, removed: 0, inserted });
             at += inserted.length;
         }
     }
@@ -3358,7 +3458,7 @@ class ListHandleImpl {
     _owner;
     // Active subscriptions, tracked so a version checkout can re-fire and
     // re-attach each one against the new container.
-    _registry = new SubscriptionRegistry();
+    _registry = new SubscriptionRegistry((err) => this._owner.reportSubscriberThrow(err));
     // See `MapHandleImpl._parent`.
     _parent;
     constructor(anchor, owner, parent = null) {
@@ -3385,14 +3485,39 @@ class ListHandleImpl {
         const l = this._anchor.resolve();
         return l ? l.length : (this._plainBody()?.length ?? 0);
     }
-    mutate(fn) {
+    get(index) {
+        this._owner.assertReadable();
+        if (!Number.isInteger(index) || index < 0)
+            return undefined;
+        const l = this._anchor.resolve();
+        if (!l)
+            return this._plainBody()?.[index];
+        if (index >= l.length)
+            return undefined;
+        const v = l.get(index);
+        if (!isContainer(v))
+            return v;
+        const container = v;
+        try {
+            return container.toJSON();
+        }
+        finally {
+            container.free();
+        }
+    }
+    *values() {
+        yield* this.read();
+    }
+    mutate(fn, options) {
         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.runMutate(options, () => {
+            // Commits as it goes past a size budget; see `mutate-batching.ts`.
+            this._runMutate(fn, new MutateBatcher(() => {
+                this._owner.commitMutate();
+            }));
             this._owner.commitMutate();
-        }));
-        this._owner.commitMutate();
+        });
     }
     // Run a list mutate without the commit pipeline; see
     // `MapHandleImpl._runMutate`. The ordered-map primitive drives this to
@@ -3405,7 +3530,7 @@ class ListHandleImpl {
         const proxy = wrapLoroListProxy(l, batcher);
         fn(proxy);
     }
-    // Fire the whole list as ONE splice replacing everything the subscriber was
+    // Fire the whole list as one change replacing everything the subscriber was
     // last told. Used for registration and for a checkout / return resync, which
     // describe no authored transition and so carry no origin.
     //
@@ -3419,10 +3544,12 @@ class ListHandleImpl {
         const held = this._held.get(cb) ?? 0;
         this._held.set(cb, inserted.length);
         try {
-            cb({ splices: [{ at: 0, removed: held, inserted }] });
+            const splices = [];
+            pushBoundedSplice(splices, { at: 0, removed: held, inserted });
+            cb({ splices });
         }
         catch (err) {
-            reportSubscriberThrow(err);
+            this._owner.reportSubscriberThrow(err);
         }
     }
     // Attach the change subscription for `cb`, returning its detach. A root
@@ -3446,11 +3573,30 @@ class ListHandleImpl {
     // Subscribe `cb` to one container's own changes; see
     // `MapHandleImpl._subscribeContainer`.
     _subscribeContainer(l, cb) {
+        const depth = containerDepth(l);
         const sub = l.subscribe((event) => {
-            const diff = event.events[0]?.diff.type === 'list'
-                ? event.events[0].diff.diff
-                : [];
-            const splices = splicesFromListDiff(diff);
+            const splices = [];
+            // An element held as a child container changes inside that container,
+            // which the list's own diff does not name. Each such element is
+            // reported as a replace of its position, read after the list's own
+            // splices so the index is the one the subscriber holds by then. An
+            // element those splices inserted already arrived as it now stands, so
+            // its own fields being written in the same commit adds no replace.
+            const touched = new Set();
+            for (const e of event.events) {
+                if (e.path.length === depth && e.diff.type === 'list') {
+                    splices.push(...splicesFromListDiff(e.diff.diff));
+                }
+                else if (e.path.length > depth && typeof e.path[depth] === 'number') {
+                    touched.add(e.path[depth]);
+                }
+            }
+            const listSplices = splices.length;
+            for (const at of [...touched].sort((x, y) => x - y)) {
+                if (at >= l.length || insertedBySplices(splices, listSplices, at))
+                    continue;
+                splices.push({ at, removed: 1, inserted: [plainListItem(l, at)] });
+            }
             let held = this._held.get(cb) ?? 0;
             for (const splice of splices)
                 held += splice.inserted.length - splice.removed;
@@ -3459,7 +3605,7 @@ class ListHandleImpl {
                 cb({ splices }, { source: this._owner.originOf(event) });
             }
             catch (err) {
-                reportSubscriberThrow(err);
+                this._owner.reportSubscriberThrow(err);
             }
         });
         return () => sub();
@@ -3591,6 +3737,10 @@ class OrderedMapHandleImpl {
     keys() {
         return sequenceOf(this._map.liveKeySet(), this._order.read());
     }
+    *entries() {
+        for (const { key, value } of this.ordered())
+            yield [key, value];
+    }
     ordered() {
         const records = this._map.read();
         const seen = new Set();
@@ -3723,9 +3873,14 @@ class OrderedMapHandleImpl {
         });
         return true;
     }
-    mutate(fn) {
+    mutate(fn, options) {
         this._owner.assertWritable();
         this._owner.ensureLocalUpdatesSubscribed();
+        this._owner.runMutate(options, () => {
+            this._mutateOrdered(fn);
+        });
+    }
+    _mutateOrdered(fn) {
         // 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
@@ -3931,8 +4086,8 @@ class OrderedMapHandleImpl {
 // 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, paging) {
-    return new MapHandleImpl(rootAnchor(root), owner, paging ?? null);
+export function createRootMapHandle(root, owner, paging, rootKey) {
+    return new MapHandleImpl(rootAnchor(root), owner, paging ?? null, null, rootKey ?? null);
 }
 export function createRootListHandle(root, owner) {
     return new ListHandleImpl(rootAnchor(root), owner);