lib0 1.0.0-rc.21 → 1.0.0-rc.23

package/dist/testing.d.ts

@@ -36,26 +36,33 @@ export class TestCase {
     get prng(): prng.PRNG;
 }
 export const repetitionTime: number;
-export function run(moduleName: string, name: string, f: (arg0: TestCase) => void | Promise<any>, i: number, numberOfTests: number): Promise<boolean>;
+export function run(moduleName: string, name: string, f: (tc: TestCase) => void | Promise<any>, i: number, numberOfTests: number): Promise<boolean>;
 export function describe(description: string, info?: string): void;
 export function info(info: string): void;
 export const printDom: (_createNode: () => Node) => void;
 export const printCanvas: (canvas: HTMLCanvasElement, height: number) => void;
-export function group(description: string, f: (...args: any[]) => void): void;
-export function groupAsync(description: string, f: (...args: any[]) => Promise<any>): Promise<void>;
-export function measureTime(message: string, f: (...args: any[]) => void): number;
-export function measureTimeAsync(message: string, f: (...args: any[]) => Promise<any>): Promise<number>;
+export function group(description: string, f: (...args: Array<any>) => void): void;
+export function groupAsync(description: string, f: (...args: Array<any>) => Promise<any>): Promise<void>;
+export function measureTime(message: string, f: (...args: Array<any>) => void): number;
+export function measureTimeAsync(message: string, f: (...args: Array<any>) => Promise<any>): Promise<number>;
 export function compareArrays<T>(as: Array<T>, bs: Array<T>, m?: string): boolean;
 export function compareStrings(a: string, b: string, m?: string): void;
 export function compareObjects<K, V>(a: any, b: any, m?: string): void;
-export function compare<T>(a: T, b: T, message?: string | null, customCompare?: (arg0: any, arg1: T, arg2: T, arg3: string, arg4: any) => boolean): boolean;
-export function assert<T>(property: T, message?: string | null): asserts property is NonNullable<T>;
-export function promiseRejected(f: (...args: any[]) => Promise<any>): Promise<void>;
-export function fails(f: (...args: any[]) => void): void;
-export function failsAsync(f: (...args: any[]) => Promise<any>): Promise<undefined>;
+export function compare<T>(a: T, b: T, message?: string | null, customCompare?: (constructor: any, a: T, b: T, path: string, compareValues: any) => boolean): boolean;
+/**
+ * `@type` (not `@param`/`@return`) is required — an assertion signature only narrows if the
+ * callee is declared with an explicit type annotation.
+ *
+ * @throws {TestError}
+ * @type {<T>(property: T, message?: string|null) => asserts property is NonNullable<T>}
+ */
+export const assert: <T>(property: T, message?: string | null) => asserts property is NonNullable<T>;
+export function promiseRejected(f: (...args: Array<any>) => Promise<any>): Promise<void>;
+export function fails(f: (...args: Array<any>) => void): void;
+export function failsAsync(f: (...args: Array<any>) => Promise<any>): Promise<undefined>;
 export function runTests(tests: {
     [x: string]: {
-        [x: string]: (arg0: TestCase) => any | Promise<any>;
+        [x: string]: (tc: TestCase) => any | Promise<any>;
     };
 }): Promise<boolean>;
 export function fail(reason: string): never;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "lib0",
-  "version": "1.0.0-rc.21",
+  "version": "1.0.0-rc.23",
   "description": "",
   "sideEffects": false,
   "type": "module",
@@ -332,9 +332,9 @@
   },
   "devDependencies": {
     "@types/node": "^26.0.0",
-    "c8": "^11.0.0",
+    "c8": "^12.0.0",
     "dpdm": "^4.0.1",
-    "jsdom": "^29.1.1",
+    "jsdom": "^30.0.1",
     "standard": "^17.1.0",
     "typescript": "^6.0.3"
   },

package/src/array.js

@@ -108,7 +108,7 @@ export const flatten = arr => fold(arr, /** @type {Array<ELEM>} */ ([]), (acc, v
 /**
  * @template T
  * @param {number} len
- * @param {function(number, Array<T>):T} f
+ * @param {(index: number, arr: Array<T>) => T} f
  * @return {Array<T>}
  */
 export const unfold = (len, f) => {
@@ -124,7 +124,7 @@ export const unfold = (len, f) => {
  * @template RESULT
  * @param {Array<T>} arr
  * @param {RESULT} seed
- * @param {function(RESULT, T, number):RESULT} folder
+ * @param {(acc: RESULT, val: T, index: number) => RESULT} folder
  */
 export const fold = (arr, seed, folder) => arr.reduce(folder, seed)
 
@@ -145,7 +145,7 @@ export const unique = arr => from(set.from(arr))
  * @template T
  * @template M
  * @param {ArrayLike<T>} arr
- * @param {function(T):M} mapper
+ * @param {(val: T) => M} mapper
  * @return {Array<T>}
  */
 export const uniqueBy = (arr, mapper) => {
@@ -170,10 +170,10 @@ export const uniqueBy = (arr, mapper) => {
 
 /**
  * @template {ArrayLike<any>} ARR
- * @template {function(ARR extends ArrayLike<infer T> ? T : never, number, ARR):any} MAPPER
+ * @template {(val: ARR extends ArrayLike<infer T> ? T : never, index: number, arr: ARR) => any} MAPPER
  * @param {ARR} arr
  * @param {MAPPER} mapper
- * @return {Array<MAPPER extends function(...any): infer M ? M : never>}
+ * @return {Array<MAPPER extends ((...args: Array<any>) => infer M) ? M : never>}
  */
 export const map = (arr, mapper) => {
   /**

package/src/broadcastchannel.js

@@ -24,7 +24,7 @@ import * as storage from './storage.js'
 
 /**
  * @typedef {Object} Channel
- * @property {Set<function(any, any):any>} Channel.subs
+ * @property {Set<(data: any, origin: any) => any>} Channel.subs
  * @property {any} Channel.bc
  */
 
@@ -41,7 +41,7 @@ class LocalStoragePolyfill {
   constructor (room) {
     this.room = room
     /**
-     * @type {null|function({data:Uint8Array}):void}
+     * @type {null|((e: {data:Uint8Array}) => void)}
      */
     this.onmessage = null
     /**
@@ -96,7 +96,7 @@ const getChannel = room =>
  *
  * @function
  * @param {string} room
- * @param {function(any, any):any} f
+ * @param {(data: any, origin: any) => any} f
  */
 export const subscribe = (room, f) => {
   getChannel(room).subs.add(f)
@@ -108,7 +108,7 @@ export const subscribe = (room, f) => {
  *
  * @function
  * @param {string} room
- * @param {function(any, any):any} f
+ * @param {(data: any, origin: any) => any} f
  */
 export const unsubscribe = (room, f) => {
   const channel = getChannel(room)

package/src/cache.js

@@ -173,7 +173,7 @@ export const remove = (cache, key) => {
  *
  * @param {Cache<K, V>} cache
  * @param {K} key
- * @param {function():Promise<V>} init
+ * @param {() => Promise<V>} init
  * @param {boolean} removeNull Optional argument that automatically removes values that resolve to null/undefined from the cache.
  * @return {Promise<V> | V}
  */

package/src/decoding.js

@@ -460,7 +460,7 @@ export const readBigInt64 = decoder => /** @type {any} */ (readFromDataView(deco
 export const readBigUint64 = decoder => /** @type {any} */ (readFromDataView(decoder, 8)).getBigUint64(0, false)
 
 /**
- * @type {Array<function(Decoder):any>}
+ * @type {Array<(decoder: Decoder) => any>}
  */
 const readAnyLookupTable = [
   decoder => undefined, // CASE 127: undefined
@@ -508,7 +508,7 @@ export const readAny = decoder => readAnyLookupTable[127 - readUint8(decoder)](d
 export class RleDecoder extends Decoder {
   /**
    * @param {Uint8Array} uint8Array
-   * @param {function(Decoder):T} reader
+   * @param {(decoder: Decoder) => T} reader
    */
   constructor (uint8Array, reader) {
     super(uint8Array)

package/src/delta/delta.js

@@ -355,15 +355,6 @@ export class TextOp extends list.ListNode {
     this._fingerprint = null
   }
 
-  /**
-   * @param {string} newVal
-   */
-  _updateInsert (newVal) {
-    // @ts-ignore
-    this.insert = newVal
-    this._fingerprint = null
-  }
-
   /**
    * @return {'insert'}
    */
@@ -462,18 +453,6 @@ export class InsertOp extends list.ListNode {
     this._fingerprint = null
   }
 
-  /* c8 ignore start */
-  /**
-   * @param {ArrayContent} _newVal
-   */
-  _updateInsert (_newVal) {
-    // Mirror of TextOp._updateInsert; not currently called on InsertOp because
-    // adjacent inserts are merged in-place via `end.insert.push(...)`. Kept for
-    // parity with TextOp's API.
-    error.unexpectedCase() // throw if called
-  }
-  /* c8 ignore stop */
-
   /**
    * @return {'insert'}
    */
@@ -1437,7 +1416,7 @@ export class Delta extends DeltaData {
       })
       encoding.writeVarUint(encoder, keys.length)
       for (const key of keys) {
-        encoding.writeVarString(encoder, /** @type {any} */ (this.attrs[/** @type {keyof Attrs} */ (key)]).fingerprint)
+        encoding.writeVarString(encoder, /** @type {any} */ (this.attrs[/** @type {keyof typeof this.attrs} */ (key)]).fingerprint)
       }
       encoding.writeVarUint(encoder, this.children.len)
       for (const child of this.children) {
@@ -1810,13 +1789,15 @@ export const _mergeChildWithPrev = (d, op) => {
   } else if ($deleteOp.check(op)) {
     /** @type {DeleteOp<any>} */ (prevOp).delete += op.delete
   } else if ($textOp.check(op)) {
-    /** @type {TextOp} */ (prevOp)._updateInsert(/** @type {TextOp} */ (prevOp).insert + op.insert)
+    // @ts-ignore
+    /** @type {TextOp} */ (prevOp).insert += op.insert
   /* c8 ignore start */
   } else {
     // unreachable: the constructor check at the top of the function already
     // limits `op` to one of the four kinds tested above
     error.unexpectedCase()
   }
+  prevOp._fingerprint = null
   /* c8 ignore stop */
   list.remove(d.children, op)
   return true
@@ -2100,7 +2081,9 @@ export class DeltaBuilder extends Delta {
     const end = this.children.end
     if (s.$string.check(insert)) {
       if ($textOp.check(end) && checkMergedEquals(end)) {
-        end._updateInsert(end.insert + insert)
+        // @ts-ignore
+        end.insert += insert
+        end._fingerprint = null
       } else if (insert.length > 0) {
         list.pushEnd(this.children, new TextOp(insert, mergedFormats, mergedAttribution))
       }
@@ -3659,7 +3642,7 @@ export const random = (gen, $d, conf = {}) => {
   }
   for (let i = prng.uint32(gen, minChildOps, maxChildOps); i > 0; i--) {
     /**
-     * @type {Array<function():void>}
+     * @type {Array<() => void>}
      */
     const possibleOps = []
     if (hasText) {
@@ -3818,7 +3801,11 @@ export const create = (nodeNameOrSchema, attrsOrSchema, children) => {
  * }>}
  */
 /**
- * @param {Array<string|null|{[K:string|number]:any}|Array<any>>} args
+ * `...X` (not `Array<X>`) is the rest-parameter form — `@param {Array<X>} args` declares a single
+ * array-typed parameter, which makes the overloads above incompatible with this signature. TS only
+ * cross-checks overloads against the implementation for function declarations, so it stayed silent.
+ *
+ * @param {...(string|null|{[K:string|number]:any}|Array<any>)} args
  * @return {DeltaBuilder<{}>}
  */
 export const from = (...args) => {

package/src/delta/rdt/dom.js

@@ -3,11 +3,12 @@
 /**
  * # DOM delta RDT
  *
- * {@link domRDT} creates an RDT (see `../rdt.js`) backed by a live DOM subtree. DOM mutations are
- * observed with a `MutationObserver`, turned into deltas (by diffing the new DOM state against the
- * last-known one) and emitted as `'delta'` events (with the RDT itself as their
- * {@link import('../rdt.js').RDT origin}); incoming deltas are applied back onto the DOM. This lets a
- * DOM subtree be bound to any other RDT.
+ * {@link domRDT} creates an RDT (see `../rdt.js`) backed by a live DOM subtree. A `MutationObserver`
+ * reports which nodes changed; the mirror ({@link DomRDT#_state}) is reconciled *incrementally* — only
+ * the changed paths are re-read from the DOM, every unchanged subtree is reused by reference (via the
+ * {@link DomRDT#_nodes} `WeakMap`), and the rebuilt tree is diffed against the previous mirror to emit a
+ * minimal `'delta'` (with the RDT itself as its {@link import('../rdt.js').RDT origin}). Incoming deltas
+ * are applied back onto the DOM. This lets a DOM subtree be bound to any other RDT.
  *
  * @module delta/rdt/dom
  */
@@ -30,30 +31,15 @@ import * as s from '../../schema.js'
  */
 
 /**
- * Recursively convert a DOM node into a {@link DomDelta} (an "insert everything" delta describing the
- * node, its attributes, and its subtree).
+ * A shared, never-mutated empty `onPath` set for the initial full read (see {@link reconcile}), where an
+ * empty `_nodes` map means nothing is reused anyway.
  *
- * @param {Node} domNode
- * @return {DomDelta}
+ * @type {Set<Node>}
  */
-const domToDelta = domNode => {
-  if (dom.$element.check(domNode)) {
-    const d = delta.create(domNode.nodeName.toLowerCase())
-    for (let i = 0; i < domNode.attributes.length; i++) {
-      const attr = /** @type {Attr} */ (domNode.attributes.item(i))
-      d.setAttr(attr.nodeName, attr.value)
-    }
-    domNode.childNodes.forEach(child => {
-      d.insert(dom.$text.check(child) ? (child.textContent ?? '') : [domToDelta(child)])
-    })
-    return /** @type {DomDelta} */ (d)
-  }
-  /* c8 ignore next */ // defensive: only element nodes are ever rendered/observed
-  error.unexpectedCase()
-}
+const EMPTY_ON_PATH = new Set()
 
 /**
- * Render a {@link DomDelta} into a fresh DOM element (the inverse of {@link domToDelta}).
+ * Render a {@link DomDelta} into a fresh DOM element (the inverse of {@link reconcile}).
  *
  * @param {DomDelta} d
  * @return {Element}
@@ -187,9 +173,143 @@ export const $domDelta = /* @__PURE__ */ delta.$delta({ name: s.$string, attrs:
  * @typedef {delta.Delta<DomConf>} DomDelta
  */
 
+// The mirror is maintained by these module-private functions (kept as functions, not methods, per the
+// lib0 style guide — methods are reserved for the duck-typed RDT interface: `applyDelta`/`delta`/
+// `destroy`). Each takes the {@link DomRDT} whose `_state`/`_nodes`/`observedNode` it reads or advances.
+
+/**
+ * Reconcile `node` against the DOM, reusing subtrees by reference. When `node` is not on the dirty
+ * `onPath` and is already mapped in `rdt._nodes`, its existing mirror subtree is returned unread;
+ * otherwise the node's shell (name + attributes + child list) is rebuilt — text children become an
+ * `insert` of their content (adjacent text coalesces, normalising `splitText`), element children recurse
+ * — and re-registered in `rdt._nodes`. Purely constructive: it never mutates an existing mirror node,
+ * only allocates fresh shells and shares unchanged subtrees.
+ *
+ * @param {DomRDT} rdt
+ * @param {Node} node
+ * @param {Set<Node>} onPath dirty elements ∪ their ancestors up to the observed root
+ * @return {DomDelta}
+ */
+const reconcile = (rdt, node, onPath) => {
+  if (!onPath.has(node) && rdt._nodes.has(node)) {
+    return /** @type {DomDelta} */ (rdt._nodes.get(node))
+  }
+  if (dom.$element.check(node)) {
+    const d = delta.create(node.nodeName.toLowerCase())
+    for (let i = 0; i < node.attributes.length; i++) {
+      const attr = /** @type {Attr} */ (node.attributes.item(i))
+      d.setAttr(attr.nodeName, attr.value)
+    }
+    node.childNodes.forEach(child => {
+      d.insert(dom.$text.check(child) ? (child.textContent ?? '') : [reconcile(rdt, child, onPath)])
+    })
+    rdt._nodes.set(node, /** @type {DomDelta} */ (d))
+    return /** @type {DomDelta} */ (d)
+  }
+  /* c8 ignore next */ // defensive: only element nodes are ever rendered/observed
+  error.unexpectedCase()
+}
+
+/**
+ * The set of elements whose OWN content (attributes, character data, or child list) a mutation batch
+ * changed: a `characterData` record dirties the text node's parent, every other record its target.
+ * Targets no longer under the observed root (removed in this same batch) are dropped — their removal is
+ * captured by a surviving ancestor's `childList` record.
+ *
+ * @param {DomRDT} rdt
+ * @param {MutationRecord[]} records
+ * @return {Set<Element>}
+ */
+const dirtyElements = (rdt, records) => {
+  /** @type {Set<Element>} */
+  const dirty = new Set()
+  for (const r of records) {
+    const el = r.type === 'characterData' ? r.target.parentNode : r.target
+    // `contains` is reflexive, so it admits the observed root itself and drops disconnected targets
+    if (el != null && dom.$element.check(el) && rdt.observedNode.contains(el)) {
+      dirty.add(el)
+    }
+  }
+  return dirty
+}
+
+/**
+ * The dirty elements together with all their ancestors up to (and including) the observed root — the
+ * nodes whose shells {@link reconcile} must rebuild (everything off this path is reused).
+ *
+ * @param {DomRDT} rdt
+ * @param {Set<Element>} dirty
+ * @return {Set<Node>}
+ */
+const computeOnPath = (rdt, dirty) => {
+  /** @type {Set<Node>} */
+  const onPath = new Set()
+  for (const el of dirty) {
+    /** @type {Node?} */
+    let p = el
+    while (p != null && !onPath.has(p)) {
+      onPath.add(p)
+      if (p === rdt.observedNode) break
+      p = p.parentNode
+    }
+  }
+  return onPath
+}
+
 /**
- * An RDT backed by a live DOM subtree. DOM mutations observed via `MutationObserver` are diffed
- * against the last-known state and emitted as deltas; incoming deltas are applied back onto the DOM.
+ * Reconcile the mirror against the DOM described by `records`, returning the freshly-rebuilt root — or
+ * `null` when nothing relevant changed (in which case no `rdt._nodes` entries were touched, so the
+ * caller may safely leave `rdt._state` as-is).
+ *
+ * @param {DomRDT} rdt
+ * @param {MutationRecord[]} records
+ * @return {DomDelta?}
+ */
+const reconcileFromRecords = (rdt, records) => {
+  const dirty = dirtyElements(rdt, records)
+  if (dirty.size === 0) return null
+  return reconcile(rdt, rdt.observedNode, computeOnPath(rdt, dirty))
+}
+
+/**
+ * Reconcile against the DOM described by `records` and return the change to emit (the diff of the
+ * previous mirror against the rebuilt one), advancing `rdt._state`. Returns an empty delta when nothing
+ * relevant changed.
+ *
+ * @param {DomRDT} rdt
+ * @param {MutationRecord[]} records
+ * @return {DomDelta}
+ */
+const pull = (rdt, records) => {
+  const fresh = reconcileFromRecords(rdt, records)
+  if (fresh == null) return /** @type {DomDelta} */ (delta.create())
+  // `clone: true` is REQUIRED here (not merely an optimisation as on a throwaway diff): `fresh` becomes
+  // the persistent `_state`, so the emitted change must share none of its subtrees — a consumer that
+  // freezes/mutates a shared child would otherwise corrupt the live mirror.
+  const change = /** @type {DomDelta} */ (delta.diff(rdt._state, fresh, { clone: true }))
+  // MUST commit: `reconcile` already re-pointed `rdt._nodes` at the rebuilt shells, so keeping the old
+  // `_state` would desync it. (Skipping is safe only when nothing was reconciled — the `fresh == null`
+  // short-circuit above.)
+  rdt._state = fresh
+  return change
+}
+
+/**
+ * The `MutationObserver` callback: reconcile the batch and, if it produced a change, emit it with the
+ * RDT itself as origin (a locally-observed DOM edit is produced by this RDT — see {@link RDT}).
+ *
+ * @param {DomRDT} rdt
+ * @param {MutationRecord[]} mutations
+ */
+const mutationHandler = (rdt, mutations) => {
+  const change = pull(rdt, mutations)
+  if (!change.isEmpty()) rdt.emit('delta', [change, rdt])
+}
+
+/**
+ * An RDT backed by a live DOM subtree. DOM mutations observed via `MutationObserver` reconcile the
+ * mirror incrementally (re-reading only changed paths, reusing unchanged subtrees by reference) and the
+ * resulting minimal diff is emitted as a delta; incoming deltas are applied back onto the DOM.
  *
  * @implements {RDT<DomConf>}
  * @extends {ObservableV2<{ delta: (delta: delta.Delta<DomConf>, origin: any) => void, destroy: (rdt: DomRDT) => void }>}
@@ -206,44 +326,30 @@ class DomRDT extends ObservableV2 {
     this.$delta = /** @type {any} */ ($domDelta)
     this.observedNode = observedNode
     /**
-     * Last-known DOM state. The observe path diffs the live DOM against this to compute the change to
-     * emit, then advances it; `applyDelta` re-syncs it after mutating the DOM.
+     * Maps each observed DOM node to its mirror delta node in {@link DomRDT#_state}. A {@link reconcile}
+     * reuses an unchanged subtree by reference (skipping its DOM read) via this map; entries for removed
+     * nodes are reclaimed automatically.
+     *
+     * @type {WeakMap<Node, DomDelta>}
+     */
+    this._nodes = new WeakMap()
+    /**
+     * The live delta mirror of the observed subtree, maintained incrementally. A reconcile rebuilds only
+     * the changed paths and swaps this whole root (see {@link pull}); it is never mutated in place, so a
+     * mirror handed out by {@link DomRDT#delta} stays a valid immutable snapshot.
      *
      * @type {DomDelta}
      */
-    this._state = domToDelta(observedNode)
-    this.observer = new MutationObserver(this._mutationHandler)
+    this._state = reconcile(this, observedNode, EMPTY_ON_PATH)
+    this.observer = new MutationObserver(mutations => mutationHandler(this, mutations))
     this.observer.observe(observedNode, {
       subtree: true,
       childList: true,
       attributes: true,
-      characterDataOldValue: true
+      characterData: true
     })
   }
 
-  /**
-   * Pull the local DOM changes accumulated since the last sync as a delta (by diffing the live DOM
-   * against `_state`), advancing `_state` to the current DOM.
-   *
-   * @return {DomDelta}
-   */
-  _pull () {
-    const next = domToDelta(this.observedNode)
-    const change = delta.diff(this._state, next)
-    this._state = next
-    return change
-  }
-
-  /**
-   * @param {MutationRecord[]} mutations
-   */
-  _mutationHandler = mutations => {
-    if (mutations.length === 0) return
-    const change = this._pull()
-    // a locally-observed DOM edit: this RDT is the producer, so it is the origin (see {@link RDT})
-    if (!change.isEmpty()) this.emit('delta', [change, this])
-  }
-
   /**
    * Apply a foreign delta onto the DOM.
    *
@@ -257,10 +363,12 @@ class DomRDT extends ObservableV2 {
    * listeners can recognise (and skip) their own changes — see {@link RDT} “Origins”. Defaults to `null`
    * (an anonymous/local change).
    * @return {delta.DeltaBuilder<DomConf> | null} the rebased local change (`b`), or `null` when there
-   * were no concurrent edits
+   * were no concurrent edits. A binding maps a returned fix back onto the other side with the
+   * `correction` origin (see `../rdt.js`)
    */
   applyDelta (d, origin = null) {
-    const b = this._pull()
+    // Drain + diff any pending local edits (their async MutationObserver callback may not have fired).
+    const b = pull(this, this.observer.takeRecords())
     /** @type {DomDelta} */
     let toApply = d
     /** @type {DomDelta?} */
@@ -272,10 +380,13 @@ class DomRDT extends ObservableV2 {
       fix = bOnD.isEmpty() ? null : bOnD
     }
     applyDeltaToDom(this.observedNode, toApply)
-    this._state = domToDelta(this.observedNode)
-    // MutationObserver callbacks are async, so the Binding's (synchronous) mutex cannot suppress the
-    // echo of our own write — draining the self-caused records here is what prevents it.
-    this.observer.takeRecords()
+    // Re-sync `_state` from the DOM our own write produced, reconciling from its self-caused records
+    // (taken here — MutationObserver callbacks are async, so the Binding's synchronous mutex cannot
+    // suppress this echo; draining the records is what prevents it). We reconcile rather than
+    // `_state.apply(toApply)` because apply's copy-on-write would re-clone nodes out of `_nodes`, and
+    // its inserted nodes carry no mapping — the DOM (incl. its text coalescing) is the authority.
+    const fresh = reconcileFromRecords(this, this.observer.takeRecords())
+    if (fresh != null) this._state = fresh
     // Forward the effective change so a chained binding on the other side picks it up; the binding
     // that fed us `d` swallows this re-emit via its own mutex (see ../rdt.js). `fix` is a freshly
     // rebased builder at runtime, returned as the owned change the binding maps on.
@@ -284,12 +395,14 @@ class DomRDT extends ObservableV2 {
   }
 
   /**
-   * The current state as a delta: an "insert everything" delta describing the observed subtree.
+   * The current state as a delta: the live mirror ({@link DomRDT#_state}), an "insert everything" delta
+   * describing the observed subtree. A shared read snapshot — consumers clone before mutating (see
+   * {@link RDT}); the mirror is never mutated in place, so a returned snapshot stays valid.
    *
    * @return {delta.Delta<DomConf>}
    */
   get delta () {
-    return domToDelta(this.observedNode)
+    return this._state
   }
 
   destroy () {