lib0 1.0.0-rc.2 → 1.0.0-rc.21

package/src/delta/delta.js

@@ -1,6 +1,21 @@
 /**
  * @beta this API is about to change
  *
+ * ## Consumer API
+ *
+ * This module exports a large surface, but a consumer only needs a handful of it:
+ * - **build / apply / inspect:** {@link create} (the constructor) and the {@link DeltaBuilder} methods
+ *   it returns (`insert`/`delete`/`retain`/`modify`/`setAttr`/`addMark`/…, `apply`, `rebase`, `done`);
+ *   {@link clone}, {@link slice}, {@link diff}, {@link inverse}, and `toJSON`/`equals`/`isEmpty` on the result.
+ * - **schemas:** {@link $delta} (define a typed delta schema) and {@link $deltaAny} (the catch-all).
+ * - **types:** `Delta`, `DeltaBuilder`, `DeltaAny`, `DeltaConf` for annotations.
+ *
+ * Everything else is `@internal` plumbing: the `*Op` classes and `$*Op` schema sentinels exist for the
+ * transformer layer's V8-stable dispatch (do not construct them); the `*RootMark*` helpers,
+ * {@link cloneShallow}, {@link random}, the merge helpers, and the remaining `$*` schemas are for
+ * cross-module / custom-transformer use, not application code. The other `DeltaConf*` typedefs are the
+ * inference machinery behind the fluent builder's typed chain — never named directly.
+ *
  * ## Mutability
  *
  * Deltas are mutable by default. But references are often shared, by marking a Delta as "done". You
@@ -22,8 +37,22 @@ import * as encoding from '../encoding.js'
 import * as buffer from '../buffer.js'
 import * as patience from '../diff/patience.js'
 import * as prng from '../prng.js'
+import * as rand from '../random.js'
 
 /**
+ * Provenance metadata on a content/attr op: *who/what* inserted, deleted, or formatted it. The canonical
+ * shape below is a convention — apply/diff/equality treat attribution as an **opaque** object (never branching
+ * on these field names), so custom keys flow through — with ONE exception: the nested `format` key merges per
+ * inner key (one level), so applying `{format:{italic:[…]}}` *adds* italic while keeping a pre-existing
+ * `{format:{bold:[…]}}`, and `{format:{bold:null}}` removes just that inner key (an emptied `format` is
+ * dropped). Every other key is flat/wholesale. The `format`/`formatAt` part exists only on
+ * children (content ops), never on node attribute ops. As an *update value* on `retain`/`modify`/`*Attr`,
+ * attribution uses the same unified tri-state as {@link Formats} (`undefined` skip / `null`
+ * clear / `{k:v}` set / `{k:null}` remove) — see the delta `readme.md` "Formats & Attributions". The blanket
+ * `null`-clear channel caveat on {@link Formats} applies here too; note `rebase` does not
+ * reconcile attribution at all (concurrent attribution edits don't converge), so prefer deterministic
+ * attribution assignment outside of concurrent editing.
+ *
  * @typedef {{
  *   insert?: string[]
  *   insertAt?: number
@@ -47,7 +76,21 @@ export const $attribution = /* @__PURE__ */(() => s.$object({
 }))()
 
 /**
- * @typedef {{ [key: string]: any }} FormattingAttributes
+ * Rich-text formatting attributes (`{ bold: true, … }`). As an *update value* on `retain`/`modify` it is a
+ * unified tri-state (identical to {@link Attribution}): `undefined`/omitted = skip, `null` = clear all,
+ * `{k:v}` = set, `{k:null}` = remove key — see the delta `readme.md` "Formats & Attributions".
+ *
+ * ⚠️ **Blanket `null` clear is a local-only utility — never send it over a channel.** A `null` clear carries
+ * no key information, so it cannot be reconciled key-by-key under `rebase`: a clear *always wins* a concurrent
+ * edit (priority-independent — that is what makes it converge), which silently DROPS the other side's set. For
+ * collaborative / transmitted data, clear keys individually with `{k:null}` removals instead — those reconcile
+ * by priority and converge without data loss (this is what {@link diff} emits and what the rebase fuzz uses).
+ *
+ * @typedef {{ [key: string]: any }} Formats
+ */
+
+/**
+ * @typedef {{ id: string, key: number|string, assoc: 1|-1, attrs?: object }} MarkJSON
  */
 
 /**
@@ -55,16 +98,18 @@ export const $attribution = /* @__PURE__ */(() => s.$object({
  *   type: 'delta',
  *   name?: string,
  *   attrs?: { [Key in string|number]: DeltaAttrOpJSON },
- *   children?: Array<DeltaListOpJSON>
+ *   children?: Array<DeltaListOpJSON>,
+ *   marks?: Array<MarkJSON>,
+ *   deleteMarks?: Array<string>
  * }} DeltaJSON
  */
 
 /**
- * @typedef {{ type: 'insert', insert: string|Array<any>, format?: { [key: string]: any }, attribution?: Attribution } | { delete: number } | { type: 'retain', retain: number, format?: { [key:string]: any }, attribution?: Attribution } | { type: 'modify', value: object }} DeltaListOpJSON
+ * @typedef {{ type: 'insert', insert: string|Array<any>, format?: { [key: string]: any }, attribution?: Attribution } | { delete: number } | { type: 'retain', retain: number, format?: { [key:string]: any }|null, attribution?: Attribution|null } | { type: 'modify', value: object, format?: { [key:string]: any }|null, attribution?: Attribution|null }} DeltaListOpJSON
  */
 
 /**
- * @typedef {{ type: 'insert', value: any, prevValue?: any, attribution?: Attribution } | { type: 'delete', prevValue?: any, attribution?: Attribution } | { type: 'modify', value: DeltaJSON }} DeltaAttrOpJSON
+ * @typedef {{ type: 'insert', value: any, attribution?: Attribution } | { type: 'delete', attribution?: Attribution } | { type: 'modify', value: DeltaJSON, attribution?: Attribution|null }} DeltaAttrOpJSON
  */
 
 /**
@@ -83,17 +128,182 @@ export const $attribution = /* @__PURE__ */(() => s.$object({
  * @type {s.Schema<DeltaAttrOpJSON>}
  */
 export const $deltaMapChangeJson = /* @__PURE__ */(() => s.$union(
-  s.$object({ type: s.$literal('insert'), value: s.$any, prevValue: s.$any.optional, attribution: $attribution.optional }),
-  s.$object({ type: s.$literal('modify'), value: s.$any }),
-  s.$object({ type: s.$literal('delete'), prevValue: s.$any.optional, attribution: $attribution.optional })
+  s.$object({ type: s.$literal('insert'), value: s.$any, attribution: $attribution.optional }),
+  s.$object({ type: s.$literal('modify'), value: s.$any, attribution: $attribution.optional }),
+  s.$object({ type: s.$literal('delete'), attribution: $attribution.optional })
 ))()
 
 /**
- * @template {{[key:string]: any} | null} Attrs
+ * @template {{[key:string]: any} | null | undefined} Attrs
  * @param {Attrs} attrs
  * @return {Attrs}
  */
 const _cloneAttrs = attrs => attrs == null ? attrs : { ...attrs }
+/**
+ * Shallow per-key tri-state merge of `update` into `base` (the usual `format`-dimension semantics, also reused
+ * as the inner step of {@link mergeAttr}). Per key: `undefined` skips, `null` removes, anything else sets.
+ * `resolve` true (data semantics) applies a `null` removal by deleting the key; false (instruction semantics)
+ * keeps the `null` verbatim so it still removes when the instruction is later applied. When `resolve` is true
+ * the `base` is canonicalised too — a `{k:null}` already present in `base` has nothing to clear on settled
+ * data, so it is dropped rather than copied through. (The used-context call sites pass pre-resolved
+ * companions — see {@link resolveUsedData} — so for them this is a no-op safety net; it matters for the
+ * apply/diff paths that merge instructions onto stored values.)
+ *
+ * @param {{[k:string]:any}|null|undefined} base
+ * @param {{[k:string]:any}} update
+ * @param {boolean} resolve
+ * @return {{[k:string]:any}}
+ */
+const mergeShallow = (base, update, resolve) => {
+  const r = /** @type {{[k:string]:any}} */ ({})
+  // copy base; when resolving, drop any `{k:null}` removal already in base (settled data carries no `null` leaf)
+  if (s.$objectAny.check(base)) for (const k in base) { if (!resolve || base[k] !== null) r[k] = base[k] }
+  for (const k in update) {
+    const v = update[k]
+    if (v === undefined) continue // skip this key
+    else if (v !== null) r[k] = v // set this key
+    else if (resolve) delete r[k] // data: apply the removal
+    else r[k] = null // instruction: keep the `null` removal verbatim for later
+  }
+  return r
+}
+/**
+ * Merge for the `attribution` dimension: the usual shallow tri-state ({@link mergeShallow}) **except** the
+ * `format` key — attribution's one structured sub-field — is itself merged per inner key (one level only, same
+ * tri-state). This realises "first merge the formats, then merge the whole attribution". The nesting applies to
+ * the `format` key alone; every other attribution key (`insert`/`delete` arrays, the `*At` numbers, …) stays a
+ * leaf. An emptied `format` is dropped (a settled attribution never stores `format: {}`). When `resolve` is
+ * true the `base` is canonicalised too (see {@link mergeShallow}): a `{k:null}` leaf in `base`, and a
+ * `{innerK:null}` inside `base.format`, have nothing to clear on settled data, so they are dropped — an
+ * emptied `base.format` is removed. This collapses a `useAttribution({format:{bold:null}})`-style context on
+ * a data op instead of storing the removal.
+ *
+ * @param {{[k:string]:any}|null|undefined} base
+ * @param {{[k:string]:any}} update
+ * @param {boolean} resolve see {@link mergeShallow}
+ * @return {{[k:string]:any}}
+ */
+const mergeAttr = (base, update, resolve) => {
+  // copy base; when resolving, canonicalise it — drop a `{k:null}` leaf and resolve `base.format`'s own
+  // inner removals (dropping an emptied `format`). On an instruction merge (`!resolve`) base is copied verbatim.
+  const r = /** @type {{[k:string]:any}} */ ({})
+  if (s.$objectAny.check(base)) {
+    for (const k in base) {
+      const bv = base[k]
+      if (resolve && bv === null) continue // drop a base leaf removal
+      if (resolve && k === 'format' && s.$objectAny.check(bv)) {
+        const f = mergeShallow(bv, {}, true) // resolve base.format's own `{innerK:null}` removals
+        if (!object.isEmpty(f)) r[k] = f // drop an emptied format
+      } else r[k] = bv
+    }
+  }
+  for (const k in update) {
+    const v = update[k]
+    if (v === undefined) continue // skip this key
+    else if (k === 'format' && s.$objectAny.check(v)) { // the one nested key: merge per inner key (one level)
+      const sub = mergeShallow(r[k], v, resolve)
+      if (object.isEmpty(sub)) delete r[k] // emptied format ⇒ drop the key
+      else r[k] = sub
+    } else if (v !== null) r[k] = v // set leaf
+    else if (resolve) delete r[k] // data: apply the removal
+    else r[k] = null // instruction: keep the `null` removal verbatim for later
+  }
+  return r
+}
+/**
+ * Resolve a retain's tri-state `format`/`attribution` instruction against an EMPTY base — used by a
+ * `final` (materializing) apply for a retain that extends beyond existing content: a `{k:null}` removal or
+ * a `null` clear has nothing to act on, so it collapses to `undefined` (skip); a set survives. `deep`
+ * selects the attribution merge (its nested `format` key merges one level, {@link mergeAttr}) vs. the
+ * shallow `format` merge ({@link mergeShallow}).
+ *
+ * @param {{[k:string]:any}|null|undefined} arg
+ * @param {boolean} deep
+ * @return {{[k:string]:any}|undefined}
+ */
+const resolveBeyond = (arg, deep) => {
+  if (arg == null) return undefined // undefined = skip; null = clear-all with nothing to clear = no-op
+  const m = deep ? mergeAttr(undefined, arg, true) : mergeShallow(undefined, arg, true)
+  return object.isEmpty(m) ? undefined : m
+}
+/**
+ * Resolve a `used*` context (set via {@link DeltaBuilder#useFormats}/`useAttribution`) for **data**
+ * consumption: settled data stores canonical values only
+ * (no `null` leaves — see {@link combineData}), while the slot itself keeps removal instructions
+ * verbatim for the instruction ops it governs. Returns the SAME object when it is already canonical
+ * (the common case — provenance contexts carry no removals), so every data op under one context shares
+ * one interned object; otherwise strips the removals ONCE into a shared copy (`{}` collapses to `null`).
+ * Never called per op — {@link DeltaBuilder#_getUsedFormatsData} caches the result per context object.
+ *
+ * @param {{[k:string]:any}|null} used
+ * @param {boolean} deep `true` for the `attribution` dimension (its `format` key resolves one level
+ *   deeper via {@link mergeAttr}); `false` for `format` (shallow, {@link mergeShallow})
+ * @return {{[k:string]:any}|null}
+ */
+const resolveUsedData = (used, deep) => {
+  if (used === null) return null
+  let empty = true
+  let canonical = true
+  for (const k in used) {
+    empty = false
+    const v = used[k]
+    if (v === null) { canonical = false; break } // a top-level removal (incl. `format: null`)
+    if (deep && k === 'format' && s.$objectAny.check(v)) {
+      // mirror mergeAttr's resolve-mode base handling: an emptied `format` is dropped on data, and an
+      // inner `{k:null}` removal is stripped — either makes the context non-canonical for data ops
+      let formatCanonical = false // empty `format: {}` ⇒ non-canonical
+      for (const ik in v) {
+        if (v[ik] === null) { formatCanonical = false; break }
+        formatCanonical = true
+      }
+      if (!formatCanonical) { canonical = false; break }
+    }
+  }
+  if (empty) return null
+  if (canonical) return used
+  const m = deep ? mergeAttr(used, {}, true) : mergeShallow(used, {}, true)
+  return object.isEmpty(m) ? null : m
+}
+/**
+ * Combine a builder's `used*` context with a per-call format/attribution argument for an
+ * **instruction** op (`retain`/`modify`/`modifyAttr`) under the unified tri-state: `undefined` — or an
+ * empty object, an empty update — inherits the context BY IDENTITY (no traversal, no copy; contexts
+ * are interned); `null` clears (ignoring the context); a non-empty object merges over the context,
+ * keeping `{k:null}` removals verbatim so they still remove when the instruction is later applied.
+ * An empty result is a no-op → `undefined` (skip).
+ *
+ * @param {{[k:string]:any}|null} used the raw context slot (removal instructions intact)
+ * @param {{[k:string]:any}|null|undefined} arg
+ * @param {boolean} deep `true` for the `attribution` dimension (its `format` key merges per inner key via
+ *   {@link mergeAttr}); `false` for `format` (shallow, {@link mergeShallow}).
+ * @return {{[k:string]:any}|null|undefined}
+ */
+const combineInstr = (used, arg, deep) => {
+  if (arg === null) return null // explicit clear — must precede the isEmpty check (object.isEmpty(null) is true)
+  if (arg === undefined || object.isEmpty(arg)) return used === null || object.isEmpty(used) ? undefined : used
+  const r = deep ? mergeAttr(used, arg, false) : mergeShallow(used, arg, false)
+  return object.isEmpty(r) ? undefined : r
+}
+/**
+ * Combine for a **data** op (`insert`/`text`/`setAttr`/`deleteAttr`): the stored value is a canonical
+ * object or `null` ("none") — never a `{k:null}` removal, there is nothing to remove on settled data.
+ * `usedData` is the builder's RESOLVED context companion ({@link resolveUsedData}, cached by
+ * {@link DeltaBuilder#_getUsedFormatsData}) and thus already canonical (`null` or a non-empty
+ * no-`null` object), so `undefined` — or an empty object, an empty update — inherits it BY IDENTITY
+ * (no traversal, no copy); `null` clears; a non-empty object merges over it, resolving the argument's
+ * own `{k:null}` removals. `{}` results collapse to `null`.
+ *
+ * @param {{[k:string]:any}|null} usedData
+ * @param {{[k:string]:any}|null|undefined} arg
+ * @param {boolean} deep see {@link combineInstr}
+ * @return {{[k:string]:any}|null}
+ */
+const combineData = (usedData, arg, deep) => {
+  if (arg === null) return null // explicit clear — must precede the isEmpty check (object.isEmpty(null) is true)
+  if (arg === undefined || object.isEmpty(arg)) return usedData
+  const r = deep ? mergeAttr(usedData, arg, true) : mergeShallow(usedData, arg, true)
+  return object.isEmpty(r) ? null : /** @type {{[k:string]:any}} */ (r)
+}
 /**
  * @template {any} MaybeDelta
  * @param {MaybeDelta} maybeDelta
@@ -101,10 +311,28 @@ const _cloneAttrs = attrs => attrs == null ? attrs : { ...attrs }
  */
 const _markMaybeDeltaAsDone = maybeDelta => $deltaAny.check(maybeDelta) ? /** @type {MaybeDelta} */ (maybeDelta.done()) : maybeDelta
 
+/**
+ * Invariants shared by all op classes below (TextOp, InsertOp, DeleteOp,
+ * RetainOp, ModifyOp, SetAttrOp, DeleteAttrOp, ModifyAttrOp):
+ *
+ * - **Only code inside `delta.js` may mutate op fields.** External consumers
+ *   treat ops as immutable; structural fields are JSDoc-annotated `@readonly`
+ *   to reinforce this. Mutation is permitted only while the owning Delta is
+ *   not `done` — every builder entry point routes through `modDeltaCheck`
+ *   to enforce this at runtime.
+ * - **Any mutation of a fingerprinted field MUST null `_fingerprint`.** The
+ *   fingerprint is a lazy cache; if it has already been computed and the
+ *   underlying data changes without invalidating it, every subsequent
+ *   fingerprint read (and any `diff` / equality check that relies on it) is
+ *   wrong. Fields covered: insert, delete, retain, format, attribution,
+ *   value, key.
+ *
+ * @internal not part of the consumer API — a content op; build deltas via {@link create}/{@link DeltaBuilder}.
+ */
 export class TextOp extends list.ListNode {
   /**
    * @param {string} insert
-   * @param {FormattingAttributes|null} format
+   * @param {Formats|null} format
    * @param {Attribution?} attribution
    */
   constructor (insert, format, attribution) {
@@ -117,7 +345,7 @@ export class TextOp extends list.ListNode {
     this.insert = insert
     /**
      * @readonly
-     * @type {FormattingAttributes|null}
+     * @type {Formats|null}
      */
     this.format = format
     this.attribution = attribution
@@ -127,10 +355,6 @@ export class TextOp extends list.ListNode {
     this._fingerprint = null
   }
 
-  get $type () {
-    return $textOp
-  }
-
   /**
    * @param {string} newVal
    */
@@ -156,6 +380,7 @@ export class TextOp extends list.ListNode {
       encoding.writeVarUint(encoder, 0) // textOp type: 0
       encoding.writeVarString(encoder, this.insert)
       encoding.writeAny(encoder, this.format)
+      encoding.writeAny(encoder, this.attribution)
     })))
   }
 
@@ -184,24 +409,34 @@ export class TextOp extends list.ListNode {
    * @param {TextOp} other
    */
   [equalityTrait.EqualityTraitSymbol] (other) {
-    return fun.equalityDeep(this.insert, other.insert) && fun.equalityDeep(this.format, other.format) && fun.equalityDeep(this.attribution, other.attribution)
+    return $textOp.check(other) &&
+      fun.equalityDeep(this.insert, other.insert) &&
+      (
+        (object.isEmpty(this.format) && object.isEmpty(other.format)) || fun.equalityDeep(this.format, other.format)
+      ) &&
+      fun.equalityDeep(this.attribution, other.attribution)
   }
 
   /**
+   * @param {number} [start]
+   * @param {number} [end]
+   * @param {boolean} [_markAsDone] accepted for a uniform children-op `clone` signature; ignored (text
+   * holds no nested deltas to freeze).
    * @return {TextOp}
    */
-  clone (start = 0, end = this.length) {
+  clone (start = 0, end = this.length, _markAsDone = true) {
     return new TextOp(this.insert.slice(start, end), _cloneAttrs(this.format), _cloneAttrs(this.attribution))
   }
 }
 
 /**
  * @template {any} ArrayContent
+ * @internal not part of the consumer API — a content op; build deltas via {@link create}/{@link DeltaBuilder}.
  */
 export class InsertOp extends list.ListNode {
   /**
    * @param {Array<ArrayContent>} insert
-   * @param {FormattingAttributes|null} format
+   * @param {Formats|null} format
    * @param {Attribution?} attribution
    */
   constructor (insert, format, attribution) {
@@ -213,7 +448,7 @@ export class InsertOp extends list.ListNode {
     this.insert = insert
     /**
      * @readonly
-     * @type {FormattingAttributes?}
+     * @type {Formats?}
      */
     this.format = format
     /**
@@ -227,18 +462,17 @@ export class InsertOp extends list.ListNode {
     this._fingerprint = null
   }
 
-  get $type () {
-    return $insertOp
-  }
-
+  /* c8 ignore start */
   /**
-   * @param {ArrayContent} newVal
+   * @param {ArrayContent} _newVal
    */
-  _updateInsert (newVal) {
-    // @ts-ignore
-    this.insert = newVal
-    this._fingerprint = null
+  _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'}
@@ -278,6 +512,7 @@ export class InsertOp extends list.ListNode {
         encoding.writeVarString(encoder, fingerprintTrait.fingerprint(/** @type {any} */ (ins)))
       })
       encoding.writeAny(encoder, this.format)
+      encoding.writeAny(encoder, this.attribution)
     })))
   }
 
@@ -305,19 +540,32 @@ export class InsertOp extends list.ListNode {
    * @param {InsertOp<ArrayContent>} other
    */
   [equalityTrait.EqualityTraitSymbol] (other) {
-    return fun.equalityDeep(this.insert, other.insert) && fun.equalityDeep(this.format, other.format) && fun.equalityDeep(this.attribution, other.attribution)
+    return $insertOp.check(other) &&
+      fun.equalityDeep(this.insert, other.insert) &&
+      (
+        (object.isEmpty(this.format) && object.isEmpty(other.format)) || fun.equalityDeep(this.format, other.format)
+      ) &&
+      fun.equalityDeep(this.attribution, other.attribution)
   }
 
   /**
+   * @param {number} [start]
+   * @param {number} [end]
+   * @param {boolean} [markAsDone] freeze the cloned child deltas (the default — a shared clone must be
+   * immutable). Pass `false` only when the caller is the SOLE owner of the cloned range (a *move*, e.g.
+   * `splitHere` which `_splice`s the range out of the source), so the content can stay mutable and is
+   * not re-cloned on the next modify (see {@link modValue}).
    * @return {InsertOp<ArrayContent>}
    */
-  clone (start = 0, end = this.length) {
-    return new InsertOp(this.insert.slice(start, end).map(_markMaybeDeltaAsDone), _cloneAttrs(this.format), _cloneAttrs(this.attribution))
+  clone (start = 0, end = this.length, markAsDone = true) {
+    const insert = this.insert.slice(start, end)
+    return new InsertOp(markAsDone ? insert.map(_markMaybeDeltaAsDone) : insert, _cloneAttrs(this.format), _cloneAttrs(this.attribution))
   }
 }
 
 /**
  * @template {DeltaConf} [Conf={}]
+ * @internal not part of the consumer API — a content op; build deltas via {@link create}/{@link DeltaBuilder}.
  */
 export class DeleteOp extends list.ListNode {
   /**
@@ -326,20 +574,12 @@ export class DeleteOp extends list.ListNode {
   constructor (len) {
     super()
     this.delete = len
-    /**
-     * @type {Delta<Conf>?}
-     */
-    this.prevValue = null
     /**
      * @type {string|null}
      */
     this._fingerprint = null
   }
 
-  get $type () {
-    return $deleteOp
-  }
-
   /**
    * @return {'delete'}
    */
@@ -348,7 +588,7 @@ export class DeleteOp extends list.ListNode {
   }
 
   get length () {
-    return 0
+    return this.delete
   }
 
   get fingerprint () {
@@ -365,7 +605,6 @@ export class DeleteOp extends list.ListNode {
    * @param {number} len
    */
   _splice (_offset, len) {
-    this.prevValue = /** @type {any} */ (this.prevValue ? slice(this.prevValue, _offset, len) : null)
     this._fingerprint = null
     this.delete -= len
     return this
@@ -382,24 +621,29 @@ export class DeleteOp extends list.ListNode {
    * @param {DeleteOp} other
    */
   [equalityTrait.EqualityTraitSymbol] (other) {
-    return this.delete === other.delete
+    return $deleteOp.check(other) && this.delete === other.delete
   }
 
   /**
-   * @param {number} start
-   * @param {number} end
+   * @param {number} [start]
+   * @param {number} [end]
+   * @param {boolean} [_markAsDone] accepted for a uniform children-op `clone` signature; ignored (a
+   * delete holds no nested content).
    * @return {DeleteOp}
    */
-  clone (start = 0, end = this.delete) {
+  clone (start = 0, end = this.delete, _markAsDone = true) {
     return new DeleteOp(end - start)
   }
 }
 
+/**
+ * @internal not part of the consumer API — a content op; build deltas via {@link create}/{@link DeltaBuilder}.
+ */
 export class RetainOp extends list.ListNode {
   /**
    * @param {number} retain
-   * @param {FormattingAttributes|null} format
-   * @param {Attribution?} attribution
+   * @param {Formats|null|undefined} format tri-state: `undefined` skip / `null` clear / object merge
+   * @param {Attribution|null|undefined} attribution tri-state: `undefined` skip / `null` clear / object merge
    */
   constructor (retain, format, attribution) {
     super()
@@ -410,12 +654,12 @@ export class RetainOp extends list.ListNode {
     this.retain = retain
     /**
      * @readonly
-     * @type {FormattingAttributes?}
+     * @type {Formats|null|undefined}
      */
     this.format = format
     /**
      * @readonly
-     * @type {Attribution?}
+     * @type {Attribution|null|undefined}
      */
     this.attribution = attribution
     /**
@@ -424,10 +668,6 @@ export class RetainOp extends list.ListNode {
     this._fingerprint = null
   }
 
-  get $type () {
-    return $retainOp
-  }
-
   /**
    * @return {'retain'}
    */
@@ -444,6 +684,7 @@ export class RetainOp extends list.ListNode {
       encoding.writeVarUint(encoder, 3) // retainOp type: 3
       encoding.writeVarUint(encoder, this.retain)
       encoding.writeAny(encoder, this.format)
+      encoding.writeAny(encoder, this.attribution)
     })))
   }
 
@@ -465,17 +706,30 @@ export class RetainOp extends list.ListNode {
    */
   toJSON () {
     const { retain, format, attribution } = this
-    return object.assign({ type: /** @type {'retain'} */ ('retain'), retain }, format ? { format } : {}, attribution != null ? { attribution } : {})
+    // retain is an instruction op: emit `null` (clear) distinctly from `undefined` (skip / omitted)
+    return object.assign({ type: /** @type {'retain'} */ ('retain'), retain }, format !== undefined ? { format } : {}, attribution !== undefined ? { attribution } : {})
   }
 
   /**
    * @param {RetainOp} other
    */
   [equalityTrait.EqualityTraitSymbol] (other) {
-    return this.retain === other.retain && fun.equalityDeep(this.format, other.format) && fun.equalityDeep(this.attribution, other.attribution)
+    return $retainOp.check(other) &&
+      this.retain === other.retain &&
+      (
+        (object.isEmpty(this.format) && object.isEmpty(other.format)) || fun.equalityDeep(this.format, other.format)
+      ) &&
+      fun.equalityDeep(this.attribution, other.attribution)
   }
 
-  clone (start = 0, end = this.retain) {
+  /**
+   * @param {number} [start]
+   * @param {number} [end]
+   * @param {boolean} [_markAsDone] accepted for a uniform children-op `clone` signature; ignored (retain
+   * holds no nested deltas).
+   * @return {RetainOp}
+   */
+  clone (start = 0, end = this.retain, _markAsDone = true) {
     return new RetainOp(end - start, _cloneAttrs(this.format), _cloneAttrs(this.attribution))
   }
 }
@@ -484,12 +738,13 @@ export class RetainOp extends list.ListNode {
  * Delta that can be applied on a YType Embed
  *
  * @template {Delta} [DTypes=DeltaAny]
+ * @internal not part of the consumer API — a content op; build deltas via {@link create}/{@link DeltaBuilder}.
  */
 export class ModifyOp extends list.ListNode {
   /**
    * @param {DTypes} delta
-   * @param {FormattingAttributes|null} format
-   * @param {Attribution?} attribution
+   * @param {Formats|null|undefined} format tri-state: `undefined` skip / `null` clear / object merge
+   * @param {Attribution|null|undefined} attribution tri-state: `undefined` skip / `null` clear / object merge
    */
   constructor (delta, format, attribution) {
     super()
@@ -500,12 +755,12 @@ export class ModifyOp extends list.ListNode {
     this.value = delta
     /**
      * @readonly
-     * @type {FormattingAttributes?}
+     * @type {Formats|null|undefined}
      */
     this.format = format
     /**
      * @readonly
-     * @type {Attribution?}
+     * @type {Attribution|null|undefined}
      */
     this.attribution = attribution
     /**
@@ -514,10 +769,6 @@ export class ModifyOp extends list.ListNode {
     this._fingerprint = null
   }
 
-  get $type () {
-    return $modifyOp
-  }
-
   /**
    * @return {'modify'}
    */
@@ -533,27 +784,21 @@ export class ModifyOp extends list.ListNode {
    * @type {DeltaBuilderAny}
    */
   get _modValue () {
-    /**
-     * @type {any}
-     */
-    const d = this.value
-    this._fingerprint = null
-    if (d.isDone) {
-      // @ts-ignore
-      return (this.value = clone(d))
-    }
-    return d
+    return modValue(this)
   }
 
   get fingerprint () {
-    // don't cache fingerprint because we don't know when delta changes
     return this._fingerprint || (this._fingerprint = buffer.toBase64(encoding.encode(encoder => {
       encoding.writeVarUint(encoder, 4) // modifyOp type: 4
       encoding.writeVarString(encoder, this.value.fingerprint)
       encoding.writeAny(encoder, this.format)
+      encoding.writeAny(encoder, this.attribution)
     })))
   }
 
+  /* c8 ignore start */
+  // ModifyOp has length 1, so callers never pass offset>0 or len>0 — splitHere
+  // is a no-op for length-1 ops. Kept for the structural _splice contract.
   /**
    * Remove a part of the operation (similar to Array.splice)
    *
@@ -563,42 +808,57 @@ export class ModifyOp extends list.ListNode {
   _splice (_offset, _len) {
     return this
   }
+  /* c8 ignore stop */
 
   /**
    * @return {DeltaListOpJSON}
    */
   toJSON () {
     const { value, attribution, format } = this
-    return object.assign({ type: /** @type {'modify'} */ ('modify'), value: value.toJSON() }, format ? { format } : {}, attribution != null ? { attribution } : {})
+    // modify is an instruction op: emit `null` (clear) distinctly from `undefined` (skip / omitted)
+    return object.assign(
+      { type: /** @type {'modify'} */ ('modify'), value: value.toJSON() },
+      format !== undefined ? { format } : {},
+      attribution !== undefined ? { attribution } : {}
+    )
   }
 
   /**
    * @param {ModifyOp<any>} other
    */
   [equalityTrait.EqualityTraitSymbol] (other) {
-    return this.value[equalityTrait.EqualityTraitSymbol](other.value) && fun.equalityDeep(this.format, other.format) && fun.equalityDeep(this.attribution, other.attribution)
+    return $modifyOp.check(other) &&
+      this.value[equalityTrait.EqualityTraitSymbol](other.value) &&
+      (
+        (object.isEmpty(this.format) && object.isEmpty(other.format)) || fun.equalityDeep(this.format, other.format)
+      ) &&
+      fun.equalityDeep(this.attribution, other.attribution)
   }
 
   /**
+   * @param {number} [_start] ignored (a modify is atomic); accepted for a uniform children-op signature.
+   * @param {number} [_end] ignored.
+   * @param {boolean} [markAsDone] freeze the cloned value (default); `false` shares it mutable — see
+   * {@link InsertOp#clone}. The op itself is still a fresh node; only its `value` is consumed.
    * @return {ModifyOp<DTypes>}
    */
-  clone () {
-    return new ModifyOp(/** @type {DTypes} */ (this.value.done()), _cloneAttrs(this.format), _cloneAttrs(this.attribution))
+  clone (_start = 0, _end = 1, markAsDone = true) {
+    return new ModifyOp(/** @type {DTypes} */ (markAsDone ? this.value.done() : this.value), _cloneAttrs(this.format), _cloneAttrs(this.attribution))
   }
 }
 
 /**
  * @template {any} [V=any]
  * @template {string|number} [K=any]
+ * @internal not part of the consumer API — an attribute op; build deltas via {@link create}/{@link DeltaBuilder}.
  */
 export class SetAttrOp {
   /**
    * @param {K} key
    * @param {V} value
-   * @param {V|undefined} prevValue
    * @param {Attribution?} attribution
    */
-  constructor (key, value, prevValue, attribution) {
+  constructor (key, value, attribution) {
     /**
      * @readonly
      * @type {K}
@@ -609,11 +869,6 @@ export class SetAttrOp {
      * @type {V}
      */
     this.value = value
-    /**
-     * @readonly
-     * @type {V|undefined}
-     */
-    this.prevValue = prevValue
     /**
      * @readonly
      * @type {Attribution?}
@@ -625,10 +880,6 @@ export class SetAttrOp {
     this._fingerprint = null
   }
 
-  get $type () {
-    return $setAttrOp
-  }
-
   /**
    * @return {'insert'}
    */
@@ -638,16 +889,7 @@ export class SetAttrOp {
    * @type {DeltaBuilderAny}
    */
   get _modValue () {
-    /**
-     * @type {any}
-     */
-    const v = this.value
-    this._fingerprint = null
-    if ($deltaAny.check(v) && v.isDone) {
-      // @ts-ignore
-      return (this.value = clone(v))
-    }
-    return v
+    return modValue(this)
   }
 
   get fingerprint () {
@@ -661,53 +903,55 @@ export class SetAttrOp {
         encoding.writeUint8(encoder, 1)
         encoding.writeAny(encoder, /** @type {any} */ (this.value))
       }
+      encoding.writeAny(encoder, this.attribution)
     })))
   }
 
   toJSON () {
     const v = this.value
     const attribution = this.attribution
-    return object.assign({
+    return object.assign(
+      {
         type: this.type,
         value: $deltaAny.check(v) ? v.toJSON() : v
       },
       attribution != null ? { attribution } : {}
-    )}
+    )
+  }
 
   /**
    * @param {SetAttrOp<V>} other
    */
   [equalityTrait.EqualityTraitSymbol] (other) {
-    return this.key === other.key && fun.equalityDeep(this.value, other.value) && fun.equalityDeep(this.attribution, other.attribution)
+    return $setAttrOp.check(other) && this.key === other.key && fun.equalityDeep(this.value, other.value) && fun.equalityDeep(this.attribution, other.attribution)
   }
 
   /**
+   * Full (frozen) clone. A `move` apply reuses the source op instead of cloning, so there is no
+   * shared-mutable variant — see {@link DeltaBuilder#apply}.
+   *
    * @return {SetAttrOp<V,K>}
    */
   clone () {
-    return new SetAttrOp(this.key, _markMaybeDeltaAsDone(this.value), _markMaybeDeltaAsDone(this.prevValue), _cloneAttrs(this.attribution))
+    return new SetAttrOp(this.key, _markMaybeDeltaAsDone(this.value), _cloneAttrs(this.attribution))
   }
 }
 
 /**
  * @template [V=any]
  * @template {string|number} [K=string|number]
+ * @internal not part of the consumer API — an attribute op; build deltas via {@link create}/{@link DeltaBuilder}.
  */
 export class DeleteAttrOp {
   /**
    * @param {K} key
-   * @param {V|undefined} prevValue
    * @param {Attribution?} attribution
    */
-  constructor (key, prevValue, attribution) {
+  constructor (key, attribution) {
     /**
      * @type {K}
      */
     this.key = key
-    /**
-     * @type {V|undefined}
-     */
-    this.prevValue = prevValue
     this.attribution = attribution
     /**
      * @type {string|null}
@@ -715,10 +959,6 @@ export class DeleteAttrOp {
     this._fingerprint = null
   }
 
-  get $type () {
-    return $deleteAttrOp
-  }
-
   /**
    * @type {'delete'}
    */
@@ -730,6 +970,7 @@ export class DeleteAttrOp {
     return this._fingerprint || (this._fingerprint = buffer.toBase64(encoding.encode(encoder => {
       encoding.writeVarUint(encoder, 6) // map delete type: 6
       encoding.writeAny(encoder, this.key)
+      encoding.writeAny(encoder, this.attribution)
     })))
   }
 
@@ -738,7 +979,7 @@ export class DeleteAttrOp {
    */
   toJSON () {
     const {
-      type, attribution,
+      type, attribution
     } = this
     return object.assign(
       { type },
@@ -750,24 +991,31 @@ export class DeleteAttrOp {
    * @param {DeleteAttrOp<V>} other
    */
   [equalityTrait.EqualityTraitSymbol] (other) {
-    return this.key === other.key && fun.equalityDeep(this.attribution, other.attribution)
+    return $deleteAttrOp.check(other) && this.key === other.key && fun.equalityDeep(this.attribution, other.attribution)
   }
 
+  /**
+   * Full (frozen) clone; a `move` apply reuses the source op instead — see {@link DeltaBuilder#apply}.
+   *
+   * @return {DeleteAttrOp<V,K>}
+   */
   clone () {
-    return new DeleteAttrOp(this.key, _markMaybeDeltaAsDone(this.prevValue), _cloneAttrs(this.attribution))
+    return new DeleteAttrOp(this.key, _cloneAttrs(this.attribution))
   }
 }
 
 /**
  * @template {DeltaAny} [Modifier=DeltaAny]
  * @template {string|number} [K=string]
+ * @internal not part of the consumer API — an attribute op; build deltas via {@link create}/{@link DeltaBuilder}.
  */
 export class ModifyAttrOp {
   /**
    * @param {K} key
    * @param {Modifier} delta
+   * @param {Attribution|null|undefined} attribution tri-state: `undefined` skip / `null` clear / object merge
    */
-  constructor (key, delta) {
+  constructor (key, delta, attribution) {
     /**
      * @readonly
      * @type {K}
@@ -778,16 +1026,17 @@ export class ModifyAttrOp {
      * @type {Modifier}
      */
     this.value = delta
+    /**
+     * @readonly
+     * @type {Attribution|null|undefined}
+     */
+    this.attribution = attribution
     /**
      * @type {string|null}
      */
     this._fingerprint = null
   }
 
-  get $type () {
-    return $modifyAttrOp
-  }
-
   /**
    * @type {'modify'}
    */
@@ -798,6 +1047,7 @@ export class ModifyAttrOp {
       encoding.writeVarUint(encoder, 7) // map modify type: 7
       encoding.writeAny(encoder, this.key)
       encoding.writeVarString(encoder, this.value.fingerprint)
+      encoding.writeAny(encoder, this.attribution)
     })))
   }
 
@@ -805,50 +1055,51 @@ export class ModifyAttrOp {
    * @return {DeltaBuilder}
    */
   get _modValue () {
-    this._fingerprint = null
-    if (this.value.isDone) {
-      // @ts-ignore
-      this.value = /** @type {any} */ (clone(this.value))
-    }
-    // @ts-ignore
-    return this.value
+    return modValue(this)
   }
 
   /**
    * @return {DeltaAttrOpJSON}
    */
   toJSON () {
-    return {
-      type: this.type,
-      value: this.value.toJSON()
-    }
+    const attribution = this.attribution
+    return object.assign(
+      {
+        type: this.type,
+        value: this.value.toJSON()
+      },
+      // modifyAttr applies its attribution as an instruction: emit `null` (clear) distinctly from skip
+      attribution !== undefined ? { attribution } : {}
+    )
   }
 
   /**
    * @param {ModifyAttrOp<Modifier>} other
    */
   [equalityTrait.EqualityTraitSymbol] (other) {
-    return this.key === other.key && this.value[equalityTrait.EqualityTraitSymbol](other.value)
+    return $modifyAttrOp.check(other) && this.key === other.key && this.value[equalityTrait.EqualityTraitSymbol](other.value) && fun.equalityDeep(this.attribution, other.attribution)
   }
 
   /**
+   * Full (frozen) clone; a `move` apply reuses the source op instead — see {@link DeltaBuilder#apply}.
+   *
    * @return {ModifyAttrOp<Modifier,K>}
    */
   clone () {
-    return new ModifyAttrOp(this.key, /** @type {Modifier} */ (this.value.done()))
+    return new ModifyAttrOp(this.key, /** @type {Modifier} */ (this.value.done()), _cloneAttrs(this.attribution))
   }
 }
 
-export const $insertOp = /** @type {s.Schema<InsertOp<any>>} */ (s.$type('insertOp'))
-export const $modifyOp = /** @type {s.Schema<ModifyOp>} */ (s.$type('modifyOp'))
-export const $textOp = /** @type {s.Schema<TextOp>} */ (s.$type('textOp'))
-export const $deleteOp = /** @type {s.Schema<DeleteOp<any>>} */ (s.$type('deleteOp'))
-export const $retainOp = /** @type {s.Schema<RetainOp>} */ (s.$type('retainOp'))
+export const $insertOp = /** @type {s.Schema<InsertOp<any>>} */ (InsertOp.prototype.$type = /** @type {s.Schema<InsertOp<any>>} */ (s.$type('d:insertOp', InsertOp)))
+export const $modifyOp = ModifyOp.prototype.$type = s.$type('d:modifyOp', ModifyOp)
+export const $textOp = TextOp.prototype.$type = s.$type('d:textOp', TextOp)
+export const $deleteOp = /** @type {s.Schema<DeleteOp<any>>} */ (DeleteOp.prototype.$type = s.$type('d:deleteOp', DeleteOp))
+export const $retainOp = RetainOp.prototype.$type = s.$type('d:retainOp', RetainOp)
 export const $anyOp = s.$union($insertOp, $deleteOp, $textOp, $modifyOp)
 
-export const $setAttrOp = /** @type {s.Schema<SetAttrOp<any>>} */ (s.$type('setAttrOp'))
-export const $modifyAttrOp = /** @type {s.Schema<ModifyAttrOp<any,string|number>>} */ (s.$type('modifyAttrOp'))
-export const $deleteAttrOp = /** @type {s.Schema<DeleteAttrOp<any,string|number>>} */ (s.$type('deleteAttrOp'))
+export const $setAttrOp = /** @type {s.Schema<SetAttrOp<any>>} */ (SetAttrOp.prototype.$type =/** @type {s.Schema<SetAttrOp<any>>} */ (s.$type('d:setAttrOp', SetAttrOp)))
+export const $modifyAttrOp = /** @type {s.Schema<ModifyAttrOp<any>>} */ (ModifyAttrOp.prototype.$type = /** @type {s.Schema<ModifyAttrOp<any>>} */ (s.$type('d:modifyAttrOp', ModifyAttrOp)))
+export const $deleteAttrOp = /** @type {s.Schema<DeleteAttrOp<any>>} */ (DeleteAttrOp.prototype.$type = /** @type {s.Schema<DeleteAttrOp<any>>} */ (s.$type('d:deleteAttrOp', DeleteAttrOp)))
 export const $anyAttrOp = s.$union($setAttrOp, $deleteAttrOp, $modifyAttrOp)
 
 /**
@@ -863,7 +1114,7 @@ export const $setAttrOpWith = $content => s.$custom(o => $setAttrOp.check(o) &&
  * @param {s.Schema<Content>} $content
  * @return {s.Schema<InsertOp<Content>>}
  */
-export const $insertOpWith = $content => s.$custom(o => $insertOp.check(o) && $content.check(o.insert.every(ins => $content.check(ins))))
+export const $insertOpWith = $content => s.$custom(o => $insertOp.check(o) && o.insert.every(ins => $content.check(ins)))
 
 /**
  * @template {DeltaAny} Modify
@@ -892,6 +1143,94 @@ export const $modifyAttrOpWith = $content => s.$custom(o => $modifyAttrOp.check(
  * @typedef {{ [K in (keyof NewAttrs | keyof Attrs)]: (unknown extends Attrs[K] ? never : Attrs[K]) | (unknown extends NewAttrs[K] ? never : NewAttrs[K]) }} MergeAttrs
  */
 
+/**
+ * A cursor/selection anchor stored inside a delta tree (see {@link import('./position.js').marksToPositions}).
+ *
+ * - `key` — the *terminal* step of the position: a content offset (number) or an attribute key
+ *   (string) within the node that holds the mark.
+ * - `id` — a unique, user-defined identifier.
+ * - `assoc` — the gravity at a boundary (left `-1` / right `1`).
+ * - `attrs` — optional user-supplied data carried with the mark **by reference**: the same
+ *   object is shared across the mark, its `copy`/`clone`s, `toJSON`, and every `MarkPos` from
+ *   `marksToPositions`, so the caller must treat it as immutable (do not mutate it after attaching).
+ *
+ * A `Mark` is **immutable** — never mutate one in place; to "move" a mark, replace it with a fresh
+ * `Mark` via {@link Mark#copy} (the {@link Marks} set keys by id, so re-adding the same id replaces
+ * it). Immutability lets a `Mark` be shared freely across a delta and its clones. The class is not
+ * exported — construct via {@link createMark} and validate via {@link $mark}.
+ */
+class Mark {
+  /**
+   * @param {number|string} key
+   * @param {string} [id] unique id; defaults to a fresh GUID
+   * @param {1|-1} [assoc] gravity at a boundary; defaults to right (`1`)
+   * @param {object?} [attrs] optional user data, stored by reference; treat as immutable
+   */
+  constructor (key, id = rand.uuidv4(), assoc = 1, attrs = null) {
+    /**
+     * @readonly
+     * @type {number|string}
+     */
+    this.key = key
+    /**
+     * @readonly
+     * @type {string}
+     */
+    this.id = id
+    /**
+     * @readonly
+     * @type {1|-1}
+     */
+    this.assoc = assoc
+    /**
+     * @readonly
+     * @type {object?}
+     */
+    this.attrs = attrs
+  }
+
+  /**
+   * A copy of this mark, optionally at a different `key` (used to "move" an otherwise-immutable mark).
+   *
+   * @param {number|string} [key]
+   * @return {Mark}
+   */
+  copy (key = this.key) {
+    return new Mark(key, this.id, this.assoc, this.attrs)
+  }
+
+  /**
+   * @return {MarkJSON}
+   */
+  toJSON () {
+    return this.attrs === null
+      ? { id: this.id, key: this.key, assoc: this.assoc }
+      : { id: this.id, key: this.key, assoc: this.assoc, attrs: this.attrs }
+  }
+
+  /**
+   * @param {Mark} other
+   */
+  [equalityTrait.EqualityTraitSymbol] (other) {
+    return $mark.check(other) && this.id === other.id && this.key === other.key && this.assoc === other.assoc && fun.equalityDeep(this.attrs, other.attrs)
+  }
+}
+
+export const $mark = /** @type {s.Schema<Mark>} */ (Mark.prototype.$type = s.$type('d:mark', Mark))
+
+/**
+ * Create a {@link Mark} (use this instead of `new Mark(...)`). `id` defaults to a fresh GUID, `assoc`
+ * to right gravity (`1`), `attrs` to `null`. A `Mark` is stored on a delta node's own
+ * {@link Marks} set (see {@link DeltaBuilder#addMark}).
+ *
+ * @param {number|string} key
+ * @param {string} [id]
+ * @param {1|-1} [assoc]
+ * @param {object?} [attrs]
+ * @return {Mark}
+ */
+export const createMark = (key, id, assoc, attrs) => new Mark(key, id, assoc, attrs)
+
 /**
  * @typedef {Delta<any>} DeltaAny
  */
@@ -910,6 +1249,16 @@ export const $modifyAttrOpWith = $content => s.$custom(o => $modifyAttrOp.check(
  * @property {boolean} [DeltaConf.recursiveAttrs=false]
  */
 
+/**
+ * Coerce a computed conf to provably satisfy the `DeltaConf` constraint. Declaration emit re-checks
+ * type arguments eagerly, so a deeply-computed conf (mapped/recursive) passed to `Delta<…>` /
+ * `Transformer<…>` must be wrapped here: the conditional exposes `DeltaConf` as its upper bound,
+ * letting the constraint resolve without forcing TS to expand the (self-referential) body.
+ *
+ * @template T
+ * @typedef {T extends infer DC extends DeltaConf ? DC : never} AsDeltaConf
+ */
+
 /**
  * @template {DeltaConf} Conf
  * @typedef {Conf extends {name:infer Name} ? (unknown extends Name ? any : (Exclude<Name,undefined>)) : any} DeltaConfGetName
@@ -1004,6 +1353,9 @@ class DeltaData {
      * >}
      */
     this.children = /** @type {any} */ (list.create())
+    /**
+     * All child-ops sizes combined. Note that delete-ops also have a length
+     */
     this.childCnt = 0
     /**
      * @type {any}
@@ -1014,6 +1366,39 @@ class DeltaData {
      */
     this._fingerprint = null
     this.isDone = false
+    /**
+     * Is the final document and does not contain delete, modify, or retain ops.
+     */
+    this.isFinal = false
+    /**
+     * Leaf {@link Mark marks} whose cursor sits in THIS node (in a settled delta), or the marks to ADD
+     * to the target node (in a change delta). Local/ephemeral cursor state — NOT part of the document
+     * fingerprint or equality. `null` when there are none. See {@link Marks}.
+     *
+     * @type {Marks?}
+     */
+    this.marks = null
+    /**
+     * Mark ids to DELETE (tombstones). Only present in a (non-settled) change delta — like a
+     * `DeleteAttrOp`, a deletion is dropped from a final delta (a materialized document carries none, at
+     * any depth). `null` when there are none. Marks follow *last-writer-wins*, treating each op as an
+     * absolute per-id assignment (present vs absent): adding a mark cancels a pending delete of the same
+     * id ({@link addMarkTo}) and a delete cancels a present add ({@link deleteMarkTo}), so a node never
+     * holds both an add and a delete for one id. {@link deleteMarkTo} is the sole writer of this set
+     * (and `addMarkTo`'s mirror); see {@link applyMarkOps}.
+     *
+     * @type {Set<string>?}
+     */
+    this.deleteMarks = null
+    /**
+     * Conservative "this subtree might hold a {@link Mark}" flag (own {@link DeltaData#marks} or any
+     * descendant's). Set `true` when a mark is introduced and OR-propagated up to every ancestor; it is
+     * **never** decremented (removal leaves it conservatively `true`). {@link
+     * import('./position.js').marksToPositions} is the sole resetter: it prunes subtrees where this is
+     * `false` (a guaranteed-empty subtree) and lazily clears a stale `true` to `false` when a descended
+     * subtree turns out to hold none. `false` therefore *guarantees* no marks; `true` only *maybe*.
+     */
+    this.maybeHasMarks = false
   }
 }
 
@@ -1027,12 +1412,11 @@ class DeltaData {
  * >}
  */
 export class Delta extends DeltaData {
-  get $type () { return $deltaAny }
   /**
    * @type {string}
    */
   get fingerprint () {
-    return this._fingerprint || (this._fingerprint = buffer.toBase64(encoding.encode(encoder => {
+    return this._fingerprint || (this._fingerprint = buffer.toBase64(rabin.fingerprint(rabin.StandardIrreducible32, encoding.encode(encoder => {
       encoding.writeUint32(encoder, 0xf2ae5680) // "magic number" that ensures that different types of content don't yield the same fingerprint
       encoding.writeAny(encoder, this.name)
       /**
@@ -1059,8 +1443,7 @@ export class Delta extends DeltaData {
       for (const child of this.children) {
         encoding.writeVarString(encoder, child.fingerprint)
       }
-      return buffer.toBase64(rabin.fingerprint(rabin.StandardIrreducible128, encoding.toUint8Array(encoder)))
-    })))
+    }))))
   }
 
   [fingerprintTrait.FingerprintTraitSymbol] () {
@@ -1068,7 +1451,7 @@ export class Delta extends DeltaData {
   }
 
   isEmpty () {
-    return object.isEmpty(this.attrs) && list.isEmpty(this.children)
+    return object.isEmpty(this.attrs) && list.isEmpty(this.children) && (this.marks === null || this.marks.size === 0) && (this.deleteMarks === null || this.deleteMarks.size === 0)
   }
 
   /**
@@ -1094,7 +1477,9 @@ export class Delta extends DeltaData {
       { type: /** @type {'delta'} */ ('delta') },
       (name != null ? { name } : {}),
       (object.isEmpty(attrs) ? {} : { attrs }),
-      (children.length > 0 ? { children } : {})
+      (children.length > 0 ? { children } : {}),
+      (this.marks !== null && this.marks.size > 0 ? { marks: [...this.marks].sort(compareMarksById).map(m => m.toJSON()) } : {}),
+      (this.deleteMarks !== null && this.deleteMarks.size > 0 ? { deleteMarks: [...this.deleteMarks].sort() } : {})
     )
   }
 
@@ -1113,6 +1498,7 @@ export class Delta extends DeltaData {
   [equalityTrait.EqualityTraitSymbol] (other) {
     // @todo it is only necessary to compare finrerprints OR do a deep equality check (remove
     // childCnt as well)
+    // marks are local/ephemeral cursor state and intentionally NOT part of document identity
     return this.name === other.name && fun.equalityDeep(this.attrs, other.attrs) && fun.equalityDeep(this.children, other.children) && this.childCnt === other.childCnt
   }
 
@@ -1142,7 +1528,7 @@ export class Delta extends DeltaData {
     if (!this.isDone) {
       this.isDone = markAsDone
       const cs = this.children
-      for (let end = cs.end; end !== null && $retainOp.check(end) && end.format == null && end.attribution == null; end = cs.end) {
+      for (let end = cs.end; end !== null && $retainOp.check(end) && end.format === undefined && end.attribution === undefined; end = cs.end) {
         this.childCnt -= end.length
         list.popEnd(cs)
       }
@@ -1162,6 +1548,7 @@ export class Delta extends DeltaData {
 export const slice = (d, start = 0, end = d.childCnt, currNode = d.children.start) => {
   const cpy = /** @type {DeltaAny} */ (new DeltaBuilder(d.name, d.$schema))
   cpy.origin = d.origin
+  const sliceStart = start // `start` is mutated by the walk below; keep the original for clamping marks
   // copy attrs
   for (const op of d.attrs) {
     // @ts-ignore
@@ -1196,6 +1583,31 @@ export const slice = (d, start = 0, end = d.childCnt, currNode = d.children.star
     remainingLen -= math.min(currNode.length, remainingLen)
   }
   cpy.childCnt = slicedLen - remainingLen
+  // copy marks (only if the subtree maybe has any). A full clone (the `clone` path) copies this node's
+  // own marks verbatim — a change delta's number-keyed root marks point into the TARGET's coordinate
+  // and may sit beyond the change's own (often empty) content, so they must not be clamped. A genuine
+  // partial slice instead clamps number-keyed marks to the sliced range (rebasing `key -= start`).
+  // String/attr marks ride with the copied attrs; child marks ride on the cloned children. The
+  // `maybeHasMarks` flag is copied (conservative); a change-only deleteMarks list is copied wholesale.
+  if (d.maybeHasMarks) {
+    if (d.marks !== null) {
+      const fullCopy = sliceStart === 0 && end >= d.childCnt
+      const cpyMarks = new Marks()
+      for (const m of d.marks) {
+        if (fullCopy || typeof m.key !== 'number') {
+          cpyMarks.add(m)
+        } else if (m.key >= sliceStart && m.key <= end) {
+          cpyMarks.add(m.copy(m.key - sliceStart))
+        }
+      }
+      if (cpyMarks.size > 0) cpy.marks = cpyMarks
+    }
+    cpy.maybeHasMarks = true
+  }
+  // a bulk copy of an already-disjoint source onto a fresh `cpy` (not a conflict-resolving write, so it
+  // bypasses the deleteMarkTo/addMarkTo primitives): `d`'s marks/deleteMarks are disjoint by id, and
+  // clamping only ever drops marks, so `cpy` stays disjoint
+  if (d.deleteMarks !== null) cpy.deleteMarks = new Set(d.deleteMarks)
   // @ts-ignore
   return cpy
 }
@@ -1208,20 +1620,186 @@ export const slice = (d, start = 0, end = d.childCnt, currNode = d.children.star
 export const clone = d => /** @type {any} */ (slice(d, 0, d.childCnt))
 
 /**
- * Try merging this op with the previous op
- * @param {list.List<any>} parent
+ * Deep-clone a value that may be a nested delta: a fresh {@link cloneDeep} of it when it is a delta,
+ * otherwise the value unchanged (plain JSON content is treated as immutable and shared).
+ *
+ * @param {any} v
+ * @return {any}
+ */
+const _cloneMaybeDeltaDeep = v => $deltaAny.check(v) ? cloneDeep(v) : v
+
+/**
+ * Deep-clone one content (child) op for {@link cloneDeep}: a fresh op whose nested deltas (an insert's
+ * delta content, a modify's value) are themselves deep-cloned. `format`/`attribution` objects are
+ * retained (shared) — they are always copied before being mutated (see {@link cloneDeep}). Ops without a
+ * nested delta (`text`/`retain`/`delete`) use `op.clone()`.
+ *
+ * @param {ChildrenOpAny} op
+ * @return {ChildrenOpAny}
+ */
+const _cloneChildOpDeep = op =>
+  $insertOp.check(op)
+    ? new InsertOp(op.insert.map(_cloneMaybeDeltaDeep), op.format, op.attribution)
+    : ($modifyOp.check(op)
+        ? new ModifyOp(cloneDeep(op.value), op.format, op.attribution)
+        : op.clone())
+
+/**
+ * Deep-clone one attribute op for {@link cloneDeep} — the attribute-dimension mirror of
+ * {@link _cloneChildOpDeep}: a `setAttr`'s value and a `modifyAttr`'s value may be nested
+ * deltas and are deep-cloned.
+ *
+ * @param {AttrOpAny} op
+ * @return {AttrOpAny}
+ */
+const _cloneAttrOpDeep = op =>
+  $setAttrOp.check(op)
+    ? new SetAttrOp(op.key, _cloneMaybeDeltaDeep(op.value), op.attribution)
+    : ($modifyAttrOp.check(op)
+        ? new ModifyAttrOp(op.key, cloneDeep(op.value), op.attribution)
+        // the only remaining attr op is a deleteAttr
+        : new DeleteAttrOp(op.key, op.attribution))
+
+/**
+ * A **deep** clone of `d`: like {@link clone}, but every nested delta — an insert's delta content, a
+ * `modify`/`modifyAttr` value, a delta-valued attribute — is itself recursively cloned into a fresh,
+ * **mutable** node, instead of being frozen (`done`) and shared as {@link clone} does. The result and
+ * its whole subtree are therefore independently editable.
+ *
+ * ## What is cloned, and when to reach for this
+ *
+ * A delta owns two kinds of nested state, treated differently on purpose:
+ * - **Ops and (nested) deltas are cloned.** They carry structure edited *in place* — `apply`/`rebase`
+ *   splice op lists and mutate op fields — so a shared copy would be corrupted by a later edit of either
+ *   side.
+ * - **`format`/`attribution` objects and plain JSON insert values are retained (shared).** They are
+ *   always *copied before being changed* (a format/attribution update allocates a new object — see
+ *   {@link mergeAttr}), so sharing them is safe and avoids needless allocation.
+ *
+ * {@link clone} suffices for the common case because a delta is only ever edited through `apply`/`rebase`,
+ * which re-clone a `done` nested delta the first time they touch it (see {@link InsertOp#_modValue}) — the
+ * shared, frozen children are never mutated in place. Reach for `cloneDeep` when a nested delta will be
+ * **manipulated directly** instead of via `apply`/`rebase` — most notably by a
+ * {@link import('./transformer/core.js').Transformer transformer}, which walks and mutates a delta's
+ * ops/children in place. A `done` (frozen) delta must always be cloned before such direct manipulation
+ * (a plain `apply`/`rebase` handles the freeze itself, so it needs no pre-clone).
+ *
+ * @template {DeltaConf} Conf
+ * @param {Delta<Conf>} d
+ * @return {DeltaBuilder<Conf>}
+ */
+export const cloneDeep = d => {
+  const cpy = /** @type {DeltaAny} */ (new DeltaBuilder(d.name, d.$schema))
+  cpy.origin = d.origin
+  cpy.isFinal = d.isFinal
+  for (const op of d.attrs) {
+    // @ts-ignore dynamic attr key (the same limitation `slice` suppresses when copying attrs)
+    cpy.attrs[op.key] = _cloneAttrOpDeep(op)
+  }
+  for (const op of d.children) {
+    list.pushEnd(cpy.children, _cloneChildOpDeep(op))
+  }
+  cpy.childCnt = d.childCnt
+  // marks ride along verbatim — a full clone never clamps number-keyed root marks, and Mark objects are
+  // immutable so they are shared (mirrors slice's full-copy path); a change delta's deleteMarks is copied.
+  if (d.maybeHasMarks) {
+    if (d.marks !== null) {
+      const cpyMarks = new Marks()
+      for (const m of d.marks) cpyMarks.add(m)
+      if (cpyMarks.size > 0) cpy.marks = cpyMarks
+    }
+    cpy.maybeHasMarks = true
+  }
+  if (d.deleteMarks !== null) cpy.deleteMarks = new Set(d.deleteMarks)
+  return /** @type {any} */ (cpy)
+}
+
+/**
+ * A *shallow* clone of `d`: a fresh {@link DeltaBuilder} carrying `d`'s name, attribute ops, and own
+ * (root) marks — but **no children**. Content-transforming
+ * {@link import('./transformer/core.js').Transformer transformers} (e.g. `children`, `value`) rebuild
+ * the child list themselves yet must keep this node's own marks; the marks of nested children ride
+ * along on the children the caller rebuilds. The `maybeHasMarks` flag is copied from `d` (conservative)
+ * and the builder OR-propagates the flag as the caller appends children. Because mark-carrying lives
+ * here in the shared primitive, a transformer that builds its output via {@link cloneShallow} cannot
+ * silently drop the node's marks.
+ *
+ * @template {DeltaAny} D
+ * @param {D} d
+ * @return {D extends Delta<infer Conf> ? DeltaBuilder<Conf> : never}
+ * @internal transformer plumbing — drops children; consumers use {@link clone}.
+ */
+export const cloneShallow = d => {
+  const cpy = /** @type {DeltaAny} */ (new DeltaBuilder(d.name, d.$schema))
+  cpy.origin = d.origin
+  for (const op of d.attrs) {
+    // @ts-ignore (dynamic attr key — the same limitation slice suppresses when copying attrs)
+    cpy.attrs[op.key] = /** @type {any} */ (op.clone())
+  }
+  // root marks / deleteMarks (a delete-mark-only change has no marks but must still ride); `cpy` is
+  // fresh, so merging onto it is a plain copy
+  if (d.marks !== null || d.deleteMarks !== null) mergeRootMarks(cpy, d)
+  // carry the conservative flag (covers attr-value marks even when this node has no root marks of its
+  // own); the builder OR-propagates it further as the caller appends the rebuilt children
+  cpy.maybeHasMarks = d.maybeHasMarks
+  // @ts-ignore
+  return cpy
+}
+
+/**
+ * Make an op's modify `value` mutable for in-place editing: clear the op's cached fingerprint and, when
+ * the value is a `done` delta, replace it with a mutable clone. Shared by the `_modValue` getters of
+ * {@link ModifyOp}, {@link ModifyAttrOp}, and {@link SetAttrOp}; the `$deltaAny` guard lets a scalar
+ * `SetAttrOp` value pass through untouched.
+ *
+ * @param {{ value: any, _fingerprint: string|null }} op
+ * @return {any}
+ */
+const modValue = op => {
+  op._fingerprint = null
+  const v = op.value
+  if ($deltaAny.check(v) && v.isDone) op.value = clone(v)
+  return op.value
+}
+
+/*
+ * --- @internal low-level mutation API for a delta's children list ---
+ *
+ * These are the ONLY sanctioned way to structurally edit `d.children` in place. Each keeps the cached
+ * invariant `d.childCnt === Σ op.length` correct and resets the op's `_fingerprint`. Never mutate
+ * `op.retain` / `op.delete` / `op.insert`, call `list.*`, or touch `d.childCnt` directly from outside
+ * delta.js — go through these so the count (which `EqualityTraitSymbol` compares) never drifts.
+ *
+ * Cursor pattern (used by {@link DeltaBuilder#apply}, {@link DeltaBuilder#rebase}, and
+ * `transformer/conform.js`): walk the target with `(op, offset)`; {@link _splitChildAt} before inserting
+ * in the middle of an op so the cursor sits on a boundary; {@link _mergeChildWithPrev} after edits to
+ * coalesce adjacent same-kind runs. `_growRun` / `_spliceInsert` extend an existing run *without* a split,
+ * which keeps same-kind insertion (e.g. typing into a pass-through run) non-fragmenting.
+ */
+
+/**
+ * Coalesce `op` into its previous sibling when they are the same kind with equal format/attribution,
+ * removing `op`. `d.childCnt` is unchanged (the length moves to the previous op). Returns `true` when it
+ * merged — so a caller holding a cursor on `op` can move it onto the surviving previous op.
+ *
+ * @param {DeltaBuilderAny} d
  * @param {InsertOp<any>|RetainOp|DeleteOp<any>|TextOp|ModifyOp<any>} op
+ * @return {boolean}
  */
-const tryMergeWithPrev = (parent, op) => {
+export const _mergeChildWithPrev = (d, op) => {
   const prevOp = op.prev
   if (
     prevOp?.constructor !== op.constructor ||
+    $modifyOp.check(op) ||
     (
-      (!$deleteOp.check(op) && !$modifyOp.check(op)) && (!fun.equalityDeep(op.format, /** @type {InsertOp<any>} */ (prevOp).format) || !fun.equalityDeep(op.attribution, /** @type {InsertOp<any>} */ (prevOp).attribution))
+      !$deleteOp.check(op) && (
+        !fun.equalityDeep(op.format, /** @type {InsertOp<any>} */ (prevOp).format) ||
+        !fun.equalityDeep(op.attribution, /** @type {InsertOp<any>} */ (prevOp).attribution)
+      )
     )
   ) {
     // constructor mismatch or format/attribution mismatch
-    return
+    return false
   }
   // can be merged
   if ($insertOp.check(op)) {
@@ -1233,31 +1811,126 @@ const tryMergeWithPrev = (parent, op) => {
     /** @type {DeleteOp<any>} */ (prevOp).delete += op.delete
   } else if ($textOp.check(op)) {
     /** @type {TextOp} */ (prevOp)._updateInsert(/** @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()
   }
-  list.remove(parent, op)
+  /* c8 ignore stop */
+  list.remove(d.children, op)
+  return true
 }
 
 /**
- * Ensures that the delta can be edited. clears _fingerprint cache.
+ * Split `op` at `offset`, leaving `op` = `[0, offset)` and a fresh right node `[offset, op.length)`
+ * inserted immediately after it; returns the right node. `d.childCnt` is unchanged (net-zero). The clone
+ * uses `markAsDone=false` because the right node is `_splice`d out of `op` here, so it is the sole owner.
+ * Caller guarantees `0 < offset < op.length`.
  *
- * @param {any} d
+ * @param {DeltaBuilderAny} d
+ * @param {ChildrenOpAny} op
+ * @param {number} offset
+ * @return {ChildrenOpAny}
  */
-const modDeltaCheck = d => {
-  if (d.isDone) {
-    /**
-     * You tried to modify a delta after it has been marked as "done".
-     */
-    throw error.create("Readonly Delta can't be modified")
-  }
-  d._fingerprint = null
+export const _splitChildAt = (d, op, offset) => {
+  const right = /** @type {ChildrenOpAny} */ (op.clone(offset, op.length, false))
+  op._splice(offset, op.length - offset)
+  list.insertBetween(d.children, op, op.next || null, right)
+  return right
 }
 
 /**
- * @template {DeltaConf} [Conf={}]
- * @template {boolean} [FixedConf=false]
- * @extends {Delta<Conf>}
+ * Insert `op` into `d.children` immediately before `ref` (or push at the end when `ref == null`);
+ * `d.childCnt += op.length`. Does not coalesce — call {@link _mergeChildWithPrev} afterwards if needed.
+ *
+ * @param {DeltaBuilderAny} d
+ * @param {ChildrenOpAny?} ref
+ * @param {ChildrenOpAny} op
+ * @return {ChildrenOpAny}
+ */
+export const _insertChild = (d, ref, op) => {
+  list.insertBetween(d.children, ref == null ? d.children.end : ref.prev, ref, op)
+  d.childCnt += op.length
+  return op
+}
+
+/**
+ * Remove child `op` entirely; `d.childCnt -= op.length`.
+ *
+ * @param {DeltaBuilderAny} d
+ * @param {ChildrenOpAny} op
+ */
+export const _removeChild = (d, op) => {
+  d.childCnt -= op.length
+  list.remove(d.children, op)
+}
+
+/**
+ * Drop `len` positions from `op` starting at `offset` (`op._splice`); `d.childCnt -= len`. Does not remove
+ * an emptied op — the caller decides (call {@link _removeChild} when `op.length === 0`), because removal is
+ * usually entangled with the caller's own cursor advance. Retain/Delete ignore `offset` (uniform runs);
+ * Insert drops `insert[offset, offset+len)`.
+ *
+ * @param {DeltaBuilderAny} d
+ * @param {ChildrenOpAny} op
+ * @param {number} offset
+ * @param {number} len
+ */
+export const _shrinkChild = (d, op, offset, len) => {
+  op._splice(offset, len)
+  d.childCnt -= len
+}
+
+/**
+ * Grow a Retain or Delete run `op` by `n` positions in place (the invariant-safe form of `op.retain += n`);
+ * `d.childCnt += n`. Use to extend an existing same-kind run without a split.
+ *
+ * @param {DeltaBuilderAny} d
+ * @param {RetainOp|DeleteOp<any>} op
+ * @param {number} n
+ */
+export const _growRun = (d, op, n) => {
+  // reason: RetainOp.retain / DeleteOp.delete are @readonly for consumers; the @internal mutators grow them in place, just as _splice shrinks them
+  // @ts-ignore
+  if ($retainOp.check(op)) op.retain += n; else op.delete += n
+  op._fingerprint = null
+  d.childCnt += n
+}
+
+/**
+ * Splice `elems` into an Insert run `op` at `offset` in place; `d.childCnt += elems.length`.
+ *
+ * @param {DeltaBuilderAny} d
+ * @param {InsertOp<any>} op
+ * @param {number} offset
+ * @param {Array<any>} elems
+ */
+export const _spliceInsert = (d, op, offset, elems) => {
+  op.insert.splice(offset, 0, ...elems)
+  op._fingerprint = null
+  d.childCnt += elems.length
+}
+
+/**
+ * Ensures that the delta can be edited. clears _fingerprint cache.
+ *
+ * @param {DeltaBuilderAny} d
+ */
+const modDeltaCheck = d => {
+  if (d.isDone) {
+    /**
+     * You tried to modify a delta after it has been marked as "done".
+     */
+    throw error.create("Readonly Delta can't be modified")
+  }
+  d._fingerprint = null
+}
+
+/**
+ * @template {DeltaConf} [Conf={}]
+ * @template {boolean} [FixedConf=false]
+ * @extends {Delta<Conf>}
  */
 export class DeltaBuilder extends Delta {
   /**
@@ -1267,49 +1940,119 @@ export class DeltaBuilder extends Delta {
   constructor (name, $schema) {
     super(name, $schema)
     /**
-     * @type {FormattingAttributes?}
+     * @type {Formats?}
      */
-    this.usedAttributes = null
+    this._usedFormats = null
     /**
      * @type {Attribution?}
      */
-    this.usedAttribution = null
+    this._usedAttribution = null
+    /**
+     * Resolved data-companion cache for the `used*` contexts ({@link resolveUsedData}): what data
+     * ops inherit instead of the raw context. `undefined` = stale, recomputed on the next data-op
+     * consumption ({@link DeltaBuilder#_getUsedFormatsData}) — {@link DeltaBuilder#useFormats} & co
+     * clear it whenever they swap the context (which is why the public slots are read-only).
+     *
+     * @type {Formats|null|undefined}
+     */
+    this._usedFormatsData = undefined
+    /**
+     * @type {Attribution|null|undefined}
+     */
+    this._usedAttributionData = undefined
   }
 
   /**
+   * The ambient formats context inherited by subsequent ops. Read-only: set it via
+   * {@link DeltaBuilder#useFormats} / {@link DeltaBuilder#updateUsedFormats}, which also invalidate
+   * the cached data companion — a direct overwrite would leave it stale.
+   *
+   * @return {Formats?}
+   */
+  get usedFormats () { return this._usedFormats }
+
+  /**
+   * The ambient attribution context inherited by subsequent ops. Read-only — see
+   * {@link DeltaBuilder#usedFormats}; set it via {@link DeltaBuilder#useAttribution} /
+   * {@link DeltaBuilder#updateUsedAttribution}.
+   *
+   * @return {Attribution?}
+   */
+  get usedAttribution () { return this._usedAttribution }
+
+  /**
+   * Set the ambient attribution context inherited by subsequent ops (`undefined`/empty dim args).
+   * The object is interned — instruction ops store it, and data ops store its resolved companion
+   * ({@link resolveUsedData}), BY REFERENCE. Never mutate it after setting; pass a fresh object
+   * instead (same invariant as the objects stored on ops).
+   *
    * @param {Attribution?} attribution
    */
   useAttribution (attribution) {
     modDeltaCheck(this)
-    this.usedAttribution = attribution
+    if (this._usedAttribution !== attribution) {
+      this._usedAttribution = attribution
+      this._usedAttributionData = undefined // clear the data companion — recomputed on next consumption
+    }
     return this
   }
 
   /**
-   * @param {FormattingAttributes?} attributes
+   * Set the ambient formats context inherited by subsequent ops (`undefined`/empty dim args). The
+   * object is interned — see {@link DeltaBuilder#useAttribution}: never mutate it after setting.
+   *
+   * @param {Formats?} attributes
    * @return {this}
    */
-  useAttributes (attributes) {
+  useFormats (attributes) {
     modDeltaCheck(this)
-    this.usedAttributes = attributes
+    if (this._usedFormats !== attributes) {
+      this._usedFormats = attributes
+      this._usedFormatsData = undefined // clear the data companion — recomputed on next consumption
+    }
     return this
   }
 
+  /**
+   * The `usedFormats` context resolved for data-op consumption ({@link resolveUsedData}): the slot
+   * object itself when it carries no `{k:null}` removals, one shared stripped copy otherwise.
+   * Cached until the context is swapped — no per-op traversal.
+   *
+   * @return {Formats?}
+   */
+  _getUsedFormatsData () {
+    const d = this._usedFormatsData
+    return d !== undefined ? d : (this._usedFormatsData = /** @type {Formats?} */ (resolveUsedData(this._usedFormats, false)))
+  }
+
+  /**
+   * See {@link DeltaBuilder#_getUsedFormatsData} — the `usedAttribution` analogue (its `format` key
+   * resolves one level deeper).
+   *
+   * @return {Attribution?}
+   */
+  _getUsedAttributionData () {
+    const d = this._usedAttributionData
+    return d !== undefined ? d : (this._usedAttributionData = /** @type {Attribution?} */ (resolveUsedData(this._usedAttribution, true)))
+  }
+
   /**
    * @param {string} name
    * @param {any} value
    */
-  updateUsedAttributes (name, value) {
+  updateUsedFormats (name, value) {
     modDeltaCheck(this)
     if (value == null) {
-      this.usedAttributes = object.assign({}, this.usedAttributes)
-      delete this.usedAttributes?.[name]
-      if (object.isEmpty(this.usedAttributes)) {
-        this.usedAttributes = null
+      this._usedFormats = object.assign({}, this._usedFormats)
+      delete this._usedFormats?.[name]
+      if (object.isEmpty(this._usedFormats)) {
+        this._usedFormats = null
       }
-    } else if (!fun.equalityDeep(this.usedAttributes?.[name], value)) {
-      this.usedAttributes = object.assign({}, this.usedAttributes)
-      this.usedAttributes[name] = value
+      this._usedFormatsData = undefined // clear the data companion — recomputed on next consumption
+    } else if (!fun.equalityDeep(this._usedFormats?.[name], value)) {
+      this._usedFormats = object.assign({}, this._usedFormats)
+      this._usedFormats[name] = value
+      this._usedFormatsData = undefined // clear the data companion — recomputed on next consumption
     }
     return this
   }
@@ -1322,14 +2065,16 @@ export class DeltaBuilder extends Delta {
   updateUsedAttribution (name, value) {
     modDeltaCheck(this)
     if (value == null) {
-      this.usedAttribution = object.assign({}, this.usedAttribution)
-      delete this.usedAttribution?.[name]
-      if (object.isEmpty(this.usedAttribution)) {
-        this.usedAttribution = null
+      this._usedAttribution = object.assign({}, this._usedAttribution)
+      delete this._usedAttribution?.[name]
+      if (object.isEmpty(this._usedAttribution)) {
+        this._usedAttribution = null
       }
-    } else if (!fun.equalityDeep(this.usedAttribution?.[name], value)) {
-      this.usedAttribution = object.assign({}, this.usedAttribution)
-      this.usedAttribution[name] = value
+      this._usedAttributionData = undefined // clear the data companion — recomputed on next consumption
+    } else if (!fun.equalityDeep(this._usedAttribution?.[name], value)) {
+      this._usedAttribution = object.assign({}, this._usedAttribution)
+      this._usedAttribution[name] = value
+      this._usedAttributionData = undefined // clear the data companion — recomputed on next consumption
     }
     return this
   }
@@ -1337,27 +2082,27 @@ export class DeltaBuilder extends Delta {
   /**
    * @template {(FixedConf extends true ? never : (Array<any>|string)) | (DeltaConfGetChildren<Conf> extends infer Children ? (Children extends never ? never : Array<Children>) : never) | DeltaConfGetText<Conf>} NewContent
    * @param {NewContent} insert
-   * @param {FormattingAttributes?} [formatting]
+   * @param {Formats?} [formatting]
    * @param {Attribution?} [attribution]
    * @return {DeltaBuilder<FixedConf extends true ? Conf : DeltaConfOverwrite<Conf,
    * (Exclude<NewContent,string> extends never ? {} : {
    *   children: Exclude<NewContent,string>[number]|DeltaConfGetChildren<Conf>
    * }) & (Extract<NewContent,string> extends never ? {} : { text: true })>, FixedConf>}
    */
-  insert (insert, formatting = null, attribution = null) {
+  insert (insert, formatting, attribution) {
     modDeltaCheck(this)
-    const mergedAttributes = mergeAttrs(this.usedAttributes, formatting)
-    const mergedAttribution = mergeAttrs(this.usedAttribution, attribution)
+    const mergedFormats = combineData(this._getUsedFormatsData(), formatting, false)
+    const mergedAttribution = combineData(this._getUsedAttributionData(), attribution, true)
     /**
      * @param {TextOp | InsertOp<any>} lastOp
      */
-    const checkMergedEquals = lastOp => (mergedAttributes === lastOp.format || fun.equalityDeep(mergedAttributes, lastOp.format)) && (mergedAttribution === lastOp.attribution || fun.equalityDeep(mergedAttribution, lastOp.attribution))
+    const checkMergedEquals = lastOp => (mergedFormats === lastOp.format || fun.equalityDeep(mergedFormats, lastOp.format)) && (mergedAttribution === lastOp.attribution || fun.equalityDeep(mergedAttribution, lastOp.attribution))
     const end = this.children.end
     if (s.$string.check(insert)) {
       if ($textOp.check(end) && checkMergedEquals(end)) {
         end._updateInsert(end.insert + insert)
       } else if (insert.length > 0) {
-        list.pushEnd(this.children, new TextOp(insert, object.isEmpty(mergedAttributes) ? null : mergedAttributes, object.isEmpty(mergedAttribution) ? null : mergedAttribution))
+        list.pushEnd(this.children, new TextOp(insert, mergedFormats, mergedAttribution))
       }
       this.childCnt += insert.length
     } else if (arr.isArray(insert)) {
@@ -1366,42 +2111,83 @@ export class DeltaBuilder extends Delta {
         end.insert.push(...insert)
         end._fingerprint = null
       } else if (insert.length > 0) {
-        list.pushEnd(this.children, new InsertOp(insert.slice() /* ensures that we don't reuse an existing array */, object.isEmpty(mergedAttributes) ? null : mergedAttributes, object.isEmpty(mergedAttribution) ? null : mergedAttribution))
+        list.pushEnd(this.children, new InsertOp(insert.slice() /* ensures that we don't reuse an existing array */, mergedFormats, mergedAttribution))
       }
       this.childCnt += insert.length
+      // inserting pre-marked content brings its subtree marks along (as apply's insert path does)
+      this.maybeHasMarks ||= elemsMaybeHaveMarks(insert)
     }
     return /** @type {any} */ (this)
   }
 
   /**
-   * @template {Extract<DeltaConfGetAllowedChildren<Conf, FixedConf>,Delta>} NewContent
+   * @template {Extract<DeltaConfGetAllowedChildren<Conf, FixedConf>,Delta|DeltaData<any,any,any,any>|DeltaBuilder>} NewContent
    * @param {NewContent} modify
-   * @param {FormattingAttributes?} formatting
-   * @param {Attribution?} attribution
+   * @param {Formats?} [formatting] tri-state: omit/`undefined` skip, `null` clear, `{k:v}`/`{k:null}` set/remove
+   * @param {Attribution?} [attribution] tri-state: omit/`undefined` skip, `null` clear, `{k:v}`/`{k:null}` set/remove
    * @return {DeltaBuilder<DeltaConfOverwrite<Conf, {children: DeltaConfGetChildren<Conf>|NewContent}>, FixedConf>}
    */
-  modify (modify, formatting = null, attribution = null) {
+  modify (modify, formatting, attribution) {
     modDeltaCheck(this)
-    const mergedAttributes = mergeAttrs(this.usedAttributes, formatting)
-    const mergedAttribution = mergeAttrs(this.usedAttribution, attribution)
-    list.pushEnd(this.children, new ModifyOp(modify, object.isEmpty(mergedAttributes) ? null : mergedAttributes, object.isEmpty(mergedAttribution) ? null : mergedAttribution))
+    const mergedFormats = combineInstr(this.usedFormats, formatting, false)
+    const mergedAttribution = combineInstr(this.usedAttribution, attribution, true)
+    list.pushEnd(this.children, new ModifyOp(modify, mergedFormats, mergedAttribution))
     this.childCnt += 1
+    // the modify target carries marks in its subtree (own root marks + nested) - flag conservatively
+    this.maybeHasMarks ||= modify.maybeHasMarks
     return /** @type {any} */ (this)
   }
 
+  /**
+   * Add a cursor/selection {@link Mark} at `pos` — a {@link import('./position.js').Pos}: a `path` of
+   * content-index / attribute-key steps plus an `assoc` and optional immutable `attrs` (user data
+   * carried with the mark). Returns `this` for chaining (like every other builder method). Pass an
+   * explicit `id` to reference the mark later — re-adding the same `id` replaces it (e.g. to move a
+   * cursor or update its `attrs`) and {@link DeltaBuilder#removeMark} deletes it; an anonymous one-shot
+   * mark gets a fresh GUID otherwise.
+   *
+   * @param {import('./position.js').Pos} pos
+   * @param {string} [id]
+   * @return {this}
+   */
+  addMark (pos, id = rand.uuidv4()) {
+    // apply with the default `final = this.isFinal` (do NOT force `{ final: true }`): a fresh change
+    // builder is non-final so a sibling `removeMark` stays transmittable; a final doc collects nothing
+    this.apply(/** @type {Delta<Conf>} */ (markChange(pos, id, false)))
+    return this
+  }
+
+  /**
+   * Remove the mark with `id`, located via `pos` (the position it was added at). On a settled document
+   * that holds the mark this removes it in place; on a fresh/markless builder it records a transmittable
+   * `deleteMarks` change (symmetric to {@link DeltaBuilder#addMark}), so
+   * `delta.create().removeMark(pos, id)` yields the delete-mark change to apply / rebase / transmit.
+   *
+   * @param {import('./position.js').Pos} pos
+   * @param {string} id
+   * @return {this}
+   */
+  removeMark (pos, id) {
+    // apply with the default `final = this.isFinal` (do NOT force `{ final: true }`): on a non-final
+    // change builder this records a transmittable `deleteMarks`; on a final doc it only removes in place
+    this.apply(/** @type {Delta<Conf>} */ (markChange(pos, id, true)))
+    return this
+  }
+
   /**
    * @param {number} len
-   * @param {FormattingAttributes?} [format]
+   * @param {Formats?} [format]
    * @param {Attribution?} [attribution]
    */
-  retain (len, format = null, attribution = null) {
-    modDeltaCheck(this)
-    const mergedFormats = mergeAttrs(this.usedAttributes, format)
-    const mergedAttribution = mergeAttrs(this.usedAttribution, attribution)
+  retain (len, format, attribution) {
+    modDeltaCheck(this) // this clears _fingerprint
+    const mergedFormats = combineInstr(this.usedFormats, format, false)
+    const mergedAttribution = combineInstr(this.usedAttribution, attribution, true)
     const lastOp = /** @type {RetainOp|InsertOp<any>} */ (this.children.end)
     if ($retainOp.check(lastOp) && fun.equalityDeep(mergedFormats, lastOp.format) && fun.equalityDeep(mergedAttribution, lastOp.attribution)) {
       // @ts-ignore
       lastOp.retain += len
+      lastOp._fingerprint = null
     } else if (len > 0) {
       list.pushEnd(this.children, new RetainOp(len, mergedFormats, mergedAttribution))
     }
@@ -1417,6 +2203,7 @@ export class DeltaBuilder extends Delta {
     const lastOp = /** @type {DeleteOp<any>|InsertOp<any>} */ (this.children.end)
     if ($deleteOp.check(lastOp)) {
       lastOp.delete += len
+      lastOp._fingerprint = null
     } else if (len > 0) {
       list.pushEnd(this.children, new DeleteOp(len))
     }
@@ -1429,29 +2216,30 @@ export class DeltaBuilder extends Delta {
    * @template {DeltaConfGetAllowedAttrs<Conf, FixedConf>[Key]} Val
    * @param {Key} key
    * @param {Val} val
-   * @param {Attribution?} attribution
-   * @param {Val|undefined} [prevValue]
+   * @param {Attribution?} [attribution] provenance for this attr (data: object or `null`/none)
    * @return {DeltaBuilder<DeltaConfOverwrite<Conf,{attrs:AddToAttrs<DeltaConfGetAttrs<Conf>,Key,Val>}>, FixedConf>}
    */
-  setAttr (key, val, attribution = null, prevValue) {
+  setAttr (key, val, attribution) {
     modDeltaCheck(this)
     // @ts-ignore
     this.attrs[key] /** @type {any} */ =
-      (new SetAttrOp(/** @type {any} */ (key), val, prevValue, mergeAttrs(this.usedAttribution, attribution)))
+      (new SetAttrOp(/** @type {any} */ (key), val, combineData(this._getUsedAttributionData(), attribution, true)))
+    // a delta-valued attribute carries marks in its subtree - flag conservatively (never decremented)
+    if ($deltaAny.check(val)) this.maybeHasMarks ||= val.maybeHasMarks
     return /** @type {any} */ (this)
   }
 
   /**
    * @template {DeltaConfGetAllowedAttrs<Conf, FixedConf>} NewAttrs
    * @param {NewAttrs} attrs
-   * @param {Attribution?} attribution
+   * @param {Attribution?} [attribution] provenance applied to each set attr (data: object or `null`/none)
    * @return {DeltaBuilder<DeltaConfOverwrite<
    *   Conf,
    *   { attrs: MergeAttrs<DeltaConfGetAttrs<Conf>,NewAttrs> }
    *   >, FixedConf>
    * }
    */
-  setAttrs (attrs, attribution = null) {
+  setAttrs (attrs, attribution) {
     modDeltaCheck(this)
     for (const k in attrs) {
       this.setAttr(/** @type {any} */ (k), /** @type {any} */ (attrs)[/** @type {any} */ (k)], attribution)
@@ -1462,17 +2250,18 @@ export class DeltaBuilder extends Delta {
   /**
    * @template {Extract<keyof DeltaConfGetAllowedAttrs<Conf, FixedConf>,string|number>} Key
    * @param {Key} key
-   * @param {Attribution?} attribution
-   * @param {any} [prevValue]
+   * @param {Attribution?} [attribution] provenance for the deletion (data: object or `null`/none)
    * @return {DeltaBuilder<DeltaConfOverwrite<Conf, {
    *   attrs: AddToAttrs<DeltaConfGetAttrs<Conf>,Key,never>
    * }>, FixedConf>}
    */
-  deleteAttr (key, attribution = null, prevValue) {
+  deleteAttr (key, attribution) {
     modDeltaCheck(this)
+    // dropping a delta-valued attribute drops its subtree's marks; the conservative `maybeHasMarks` flag
+    // is left as-is (never decremented - marksToPositions self-corrects it)
     // @ts-ignore
     this.attrs[key] /** @type {any} */ =
-      (new DeleteAttrOp(/** @type {any} */ (key), prevValue, mergeAttrs(this.usedAttribution, attribution)))
+      (new DeleteAttrOp(/** @type {any} */ (key), combineData(this._getUsedAttributionData(), attribution, true)))
     return /** @type {any} */ (this)
   }
 
@@ -1481,41 +2270,79 @@ export class DeltaBuilder extends Delta {
    * @template {Extract<DeltaConfGetAllowedAttrs<Conf, FixedConf>[Key],DeltaAny>} D
    * @param {Key} key
    * @param {D} modify
+   * @param {Attribution?} [attribution] tri-state instruction merged onto the target attr op: omit/`undefined` skip, `null` clear, `{k:v}`/`{k:null}` set/remove
    * @return {DeltaBuilder<DeltaConfOverwrite<Conf,{attrs:AddToAttrs<DeltaConfGetAttrs<Conf>,Key,D>}>, FixedConf>}
    */
-  modifyAttr (key, modify) {
+  modifyAttr (key, modify, attribution) {
     modDeltaCheck(this)
-    this.attrs[key] = /** @type {any} */ (new ModifyAttrOp(key, modify))
+    const mergedAttribution = combineInstr(this.usedAttribution, attribution, true)
+    this.attrs[key] = /** @type {any} */ (new ModifyAttrOp(key, modify, mergedAttribution))
+    // the modify value carries marks in its subtree - flag conservatively (never decremented)
+    this.maybeHasMarks ||= /** @type {DeltaAny} */ (modify).maybeHasMarks
     return /** @type {any} */ (this)
   }
 
   /**
-   * @param {Delta<Conf>} other
+   * Apply other delta on this op. The result is the merged op of both of them.
+   *
+   * a.apply(b.apply(c))
+   *
+   * is equivalent to
+   *
+   * a.apply(b).apply(c)
+   *
+   * If `final = true`, we consider this delta the final state and drop deleteAttrOps from
+   * attributes. (E.g. if `otherOp` deletes an attribute, this op will simply not have the
+   * attribute). Any kind of `delete` op might be considered a bug. A final delta is not idempotent.
+   *
+   * @param {Delta<Conf>?} other
+   * @param {{ final?: boolean, move?: boolean }} [opts] `move`: the caller donates `other` (it is not
+   * read again), so its content is consumed (shared mutable) rather than frozen-cloned — see {@link
+   * InsertOp#clone}. UNSAFE if the caller keeps using `other`.
+   * @return {DeltaBuilder<Conf>}
    */
-  apply (other) {
+  apply (other, { final = this.isFinal, move = false } = {}) {
+    if (other == null) return this
     modDeltaCheck(this)
     this.$schema?.expect(other)
+    // `move`: the caller donates `other` (it must not be read again), so content is consumed (shared
+    // mutable) instead of frozen-cloned — no `done()` and no re-clone on a later modify. UNSAFE if the
+    // caller keeps using `other`. `!move` is the default everywhere (today's behavior).
+    const keep = !move
     // apply attrs
     for (const op of other.attrs) {
       // @ts-ignore
       const c = /** @type {SetAttrOp<any,any>|DeleteAttrOp<any>|ModifyAttrOp<any,any>} */ (this.attrs[op.key])
       if ($modifyAttrOp.check(op)) {
         if ($deltaAny.check(c?.value)) {
-          c._modValue.apply(op.value)
+          const tgt = c._modValue
+          tgt.apply(op.value, { final, move })
+          this.maybeHasMarks ||= tgt.maybeHasMarks // flag the attr subtree's marks up
+          // modifyAttr carries a tri-state attribution update for the target attr op (merge/clear/skip)
+          if (applyDim(c, 'attribution', op.attribution)) {
+            /** @type {any} */ (c)._fingerprint = null
+          }
         } else {
-          // then this is a simple modify
+          // then this is a simple modify (the attribute did not previously hold a delta)
           // @ts-ignore
-          this.attrs[op.key] = op.clone()
+          this.attrs[op.key] = move ? op : op.clone()
+          this.maybeHasMarks ||= op.value.maybeHasMarks // flag any marks the new modify value carries
         }
       } else if ($setAttrOp.check(op)) {
+        // a delta-valued attribute carries marks in its subtree - flag conservatively (never decremented)
+        if ($deltaAny.check(op.value)) this.maybeHasMarks ||= op.value.maybeHasMarks
         // @ts-ignore
-        op.prevValue = c?.value
-        // @ts-ignore
-        this.attrs[op.key] = op.clone()
+        this.attrs[op.key] = move ? op : op.clone()
       } else if ($deleteAttrOp.check(op)) {
-        op.prevValue = c?.value
-        // @ts-ignore
-        delete this.attrs[op.key]
+        // removing a delta-valued attribute drops its subtree's marks; the conservative `maybeHasMarks`
+        // flag is left as-is (never decremented - marksToPositions self-corrects it)
+        if (final) {
+          // @ts-ignore
+          delete this.attrs[op.key]
+        } else {
+          // @ts-ignore
+          this.attrs[op.key] = move ? op : op.clone()
+        }
       }
     }
     // apply children
@@ -1523,6 +2350,9 @@ export class DeltaBuilder extends Delta {
      * @type {ChildrenOpAny?}
      */
     let opsI = this.children.start
+    if ($deleteOp.check(opsI)) {
+      opsI = opNextUndeleted(opsI)
+    }
     let offset = 0
     /**
      * At the end, we will try to merge this op, and op.next op with their respective previous op.
@@ -1534,154 +2364,239 @@ export class DeltaBuilder extends Delta {
      */
     const maybeMergeable = []
     /**
-     * @template {InsertOp<any>|RetainOp|DeleteOp|TextOp|ModifyOp<any>|null} OP
-     * @param {OP} op
-     * @return {OP}
+     * Schedule an op to be merged later
+     * @param {ChildrenOpAny?} op
+     * @return {ChildrenOpAny}
      */
     const scheduleForMerge = op => {
       op && maybeMergeable.push(op)
-      return op
+      return /** @type {any} */ (op)
+    }
+
+    /**
+     * Split opsI at the current offset - ensuring that we can insert safely at the current position
+     */
+    const splitHere = () => {
+      if (offset > 0 && opsI != null) {
+        opsI = scheduleForMerge(_splitChildAt(this, opsI, offset))
+        offset = 0
+      }
+    }
+    /**
+     * @param {ChildrenOpAny} op
+     */
+    const insertClonedOp = op => {
+      splitHere()
+      // `move` re-parents the source op directly (it is donated); else clone with `keep`. Freshly
+      // built `new DeleteOp(...)` callers are unaliased, so moving them is likewise safe.
+      _insertChild(this, opsI, scheduleForMerge(move ? op : op.clone(0, op.length, keep)))
+      // inserting pre-marked content (e.g. a node that already carries a cursor) brings its marks along
+      if ($insertOp.check(op)) this.maybeHasMarks ||= elemsMaybeHaveMarks(op.insert)
     }
-    other.children.forEach(op => {
+    // manual iteration (not `for..of`): a `move` apply re-parents the source op into `this.children`,
+    // rewiring its `.next`; capture the successor first so the walk stays on `other`'s chain.
+    for (let op = /** @type {ChildrenOpAny?} */ (other.children.start), nextOp = op; op != null; op = nextOp) {
+      nextOp = op.next
+      // defensive: the per-branch logic below resets opsI/offset whenever it
+      // consumes an op exactly. This guard catches any path that forgets to.
+      /* c8 ignore start */
+      if (opsI?.length === offset) {
+        opsI = opNextUndeleted(opsI)
+        offset = 0
+      }
+      /* c8 ignore stop */
       if ($textOp.check(op) || $insertOp.check(op)) {
-        if (offset === 0) {
-          list.insertBetween(this.children, opsI == null ? this.children.end : opsI.prev, opsI, scheduleForMerge(op.clone()))
-        } else {
-          // @todo inmplement "splitHelper" and "insertHelper" - I'm splitting all the time and
-          // forget to update opsI
-          if (opsI == null) error.unexpectedCase()
-          const cpy = scheduleForMerge(opsI.clone(offset))
-          opsI._splice(offset, opsI.length - offset)
-          list.insertBetween(this.children, opsI, opsI.next || null, cpy)
-          list.insertBetween(this.children, opsI, cpy || null, scheduleForMerge(op.clone()))
-          opsI = cpy
-          offset = 0
-        }
-        this.childCnt += op.insert.length
+        insertClonedOp(op)
       } else if ($retainOp.check(op)) {
         let retainLen = op.length
-
-        if (offset > 0 && opsI != null && op.format != null && !$deleteOp.check(opsI) && !object.every(op.format, (v, k) => fun.equalityDeep(v, /** @type {InsertOp<any>|RetainOp|ModifyOp} */ (opsI).format?.[k] || null))) {
+        // split the current op when this retain carries a format and/or attribution instruction
+        // (`!== undefined`) that differs from what the existing op holds — both unified tri-state. The
+        // split must fire on any differing instruction (incl. a `{k:null}` removal or a `null` clear), not
+        // just one that would change a *data* target: it marks the boundary between the already-advanced
+        // (skipped) prefix and the region this op formats, so the update can't bleed into the prefix.
+        if (offset > 0 && opsI != null && !$deleteOp.check(opsI) && (
+          (op.format !== undefined && !fun.equalityDeep(/** @type {InsertOp<any>|RetainOp|ModifyOp} */ (opsI).format, op.format)) ||
+          (op.attribution !== undefined && !fun.equalityDeep(/** @type {any} */ (opsI).attribution, op.attribution))
+        )) {
           // need to split current op
-          const cpy = scheduleForMerge(opsI.clone(offset))
-          opsI._splice(offset, opsI.length - offset)
-          list.insertBetween(this.children, opsI, opsI.next || null, cpy)
-          opsI = cpy
-          offset = 0
+          splitHere()
         }
-
         while (opsI != null && opsI.length - offset <= retainLen) {
-          op.format != null && updateOpFormat(opsI, op.format)
+          if (op.format !== undefined || op.attribution !== undefined) {
+            updateOpFormat(opsI, op.format, op.attribution)
+            scheduleForMerge(opsI)
+          }
           retainLen -= opsI.length - offset
-          opsI = opsI?.next || null
+          opsI = opNextUndeleted(opsI)
           offset = 0
         }
-
         if (opsI != null) {
-          if (op.format != null && retainLen > 0) {
-            // split current op and apply format
-            const cpy = scheduleForMerge(opsI.clone(retainLen))
-            opsI._splice(retainLen, opsI.length - retainLen)
-            list.insertBetween(this.children, opsI, opsI.next || null, cpy)
-            updateOpFormat(opsI, op.format)
-            opsI = cpy
+          if ((op.format !== undefined || op.attribution !== undefined) && retainLen > 0) {
+            // accumulate onto the existing offset — the else-branch below uses
+            // `offset += retainLen`, and we must agree with it when prior
+            // iterations have advanced offset into opsI without splitting (e.g.
+            // a format-less retain followed by a same-format retain).
+            offset += retainLen
+            splitHere()
+            updateOpFormat(/** @type {ChildrenOpAny} */ (opsI.prev), op.format, op.attribution)
+            scheduleForMerge(opsI.prev)
           } else {
             offset += retainLen
           }
         } else if (retainLen > 0) {
-          list.pushEnd(this.children, scheduleForMerge(new RetainOp(retainLen, op.format, op.attribution)))
-          this.childCnt += retainLen
+          // append the retain beyond existing content. On a NON-final/instruction apply keep it verbatim —
+          // a `null` (clear) format/attribution here is a meaningful change op (e.g. a format/attribution
+          // diff applied onto an as-yet-empty change delta). On a FINAL (materializing) apply the
+          // removal/clear has nothing to act on, so resolve it away ({@link resolveBeyond}): a `{k:null}`
+          // removal or `null` clear collapses to `undefined`, a set survives. We still append the (possibly
+          // now-bare) retain so a following op stays positioned; done() trims it iff it is trailing.
+          const fmt = final ? resolveBeyond(op.format, false) : op.format
+          const attr = final ? resolveBeyond(op.attribution, true) : op.attribution
+          _insertChild(this, null, scheduleForMerge(new RetainOp(retainLen, fmt, attr)))
         }
       } else if ($deleteOp.check(op)) {
         let remainingLen = op.delete
         while (remainingLen > 0) {
           if (opsI == null) {
-            list.pushEnd(this.children, scheduleForMerge(new DeleteOp(remainingLen)))
-            this.childCnt += remainingLen
+            _insertChild(this, null, scheduleForMerge(new DeleteOp(remainingLen)))
             break
-          } else if ($deleteOp.check(opsI)) {
-            const delLen = opsI.length - offset
-            // the same content can't be deleted twice, remove duplicated deletes
-            if (delLen >= remainingLen) {
+          } else if ($retainOp.check(opsI)) { // retain ⇒ splice retain, insert delete
+            const delLen = math.min(opsI.length - offset, remainingLen)
+            _shrinkChild(this, opsI, offset, delLen)
+            if (opsI.length === 0) {
+              _removeChild(this, opsI)
+              opsI = opNextUndeleted(opsI)
+              offset = 0
+            }
+            if (opsI?.length === offset) {
+              opsI = opNextUndeleted(opsI)
               offset = 0
-              opsI = opsI.next
-            } else {
-              offset += remainingLen
             }
+            insertClonedOp(new DeleteOp(delLen))
             remainingLen -= delLen
-          } else { // insert / embed / retain / modify ⇒ replace
+          } else if ($modifyOp.check(opsI)) { // modify ⇒ delete the source position it stands for
+            // a modify op addresses an underlying source position (retain + change), so deleting it
+            // must emit a DeleteOp for that position - exactly like the retain case above. (The
+            // insert/embed branch below instead just cancels the inserted content, because that
+            // content is new and has no source position to delete.)
+            _removeChild(this, opsI)
+            opsI = opNextUndeleted(opsI)
+            offset = 0
+            insertClonedOp(new DeleteOp(1))
+            remainingLen -= 1
+          } else if (!$deleteOp.check(opsI)) { // insert / embed ⇒ replace
             // case1: delete o fully
             // case2: delete some part of beginning
             // case3: delete some part of end
             // case4: delete some part of center
             const delLen = math.min(opsI.length - offset, remainingLen)
-            this.childCnt -= delLen
+            // deleting content drops any marks in the removed embeds; the conservative `maybeHasMarks`
+            // flag is left as-is (never decremented - marksToPositions self-corrects it)
             if (opsI.length === delLen) {
-              // case 1
+              // case 1: delete opsI fully
+              _removeChild(this, opsI)
+              scheduleForMerge(opsI = opNextUndeleted(opsI))
               offset = 0
-              scheduleForMerge(opsI.next)
-              list.remove(this.children, opsI)
-              opsI = opsI.next
             } else if (offset === 0) {
-              // case 2
-              offset = 0
-              opsI._splice(0, delLen)
+              // case 2: delete from the beginning
+              _shrinkChild(this, opsI, offset, delLen)
             } else if (offset + delLen === opsI.length) {
-              // case 3
-              opsI._splice(offset, delLen)
+              // case 3: delete to the end
+              _shrinkChild(this, opsI, offset, delLen)
+              opsI = opNextUndeleted(opsI)
               offset = 0
-              opsI = opsI.next
             } else {
-              // case 4
-              opsI._splice(offset, delLen)
+              // case 4: delete from the center
+              _shrinkChild(this, opsI, offset, delLen)
             }
             remainingLen -= delLen
+          /* c8 ignore start */
+          } else {
+            // unreachable: opsI was already typed as retain | non-delete-content | delete above
+            error.unexpectedCase()
           }
+          /* c8 ignore stop */
         }
       } else if ($modifyOp.check(op)) {
-        if (opsI == null) {
-          list.pushEnd(this.children, op.clone())
-          this.childCnt += 1
-          return
+        if (opsI != null && (op.format !== undefined || op.attribution !== undefined) && (!$deleteOp.check(opsI) && !$retainOp.check(opsI))) { // retain handles splitting seperately, without copying attrs
+          splitHere()
+          if (opsI.length > 1) {
+            offset = 1
+            splitHere()
+            opsI = /** @type {InsertOp<any>} */ (opsI.prev)
+          }
+          // at this point, opsI is guaranteed to be !deleteOp && !retainOp and of length 1
+          updateOpFormat(opsI, op.format, op.attribution)
+          scheduleForMerge(opsI)
         }
-        if ($modifyAttrOp.check(opsI)) {
-          opsI._modValue.apply(/** @type {any} */ (op.value))
+        if (opsI == null) {
+          _insertChild(this, null, move ? op : op.clone(0, 1, keep))
+          this.maybeHasMarks ||= /** @type {DeltaAny} */ (op.value).maybeHasMarks // a freshly-inserted modify brings its value's root marks
+        } else if ($modifyOp.check(opsI)) {
+          const tgt = opsI._modValue
+          tgt.apply(/** @type {any} */ (op.value), { final, move })
+          this.maybeHasMarks ||= tgt.maybeHasMarks // flag the child subtree's marks up (incl. the value's own root marks)
+          opsI = opNextUndeleted(opsI)
         } else if ($insertOp.check(opsI)) {
-          opsI._modValue(offset).apply(op.value)
-        } else if ($retainOp.check(opsI)) {
-          if (offset > 0) {
-            const cpy = scheduleForMerge(opsI.clone(0, offset)) // skipped len
-            opsI._splice(0, offset) // new remainder
-            list.insertBetween(this.children, opsI.prev, opsI, cpy) // insert skipped len
+          const tgt = opsI._modValue(offset)
+          tgt.apply(op.value, { final, move })
+          this.maybeHasMarks ||= tgt.maybeHasMarks // flag the child subtree's marks up (incl. the value's own root marks)
+          if (opsI.length === ++offset) {
+            opsI = opNextUndeleted(opsI)
             offset = 0
           }
-          list.insertBetween(this.children, opsI.prev, opsI, scheduleForMerge(op.clone())) // insert skipped len
+        } else if ($retainOp.check(opsI)) {
+          splitHere()
+          const insertModOp = scheduleForMerge(move ? op : op.clone(0, 1, keep))
+          this.maybeHasMarks ||= /** @type {DeltaAny} */ (op.value).maybeHasMarks // the inserted modify brings its value's root marks
+          ;(opsI.format !== undefined || opsI.attribution !== undefined) && updateOpFormat(insertModOp, opsI.format, opsI.attribution)
+          // the modify replaces one retain position with a length-1 modify (net childCnt: +1 here, -1 below)
+          _insertChild(this, opsI, insertModOp)
           if (opsI.length === 1) {
-            list.remove(this.children, opsI)
+            _removeChild(this, opsI)
+            opsI = opNextUndeleted(opsI)
+            offset = 0
           } else {
-            opsI._splice(0, 1)
+            _shrinkChild(this, opsI, 0, 1)
             scheduleForMerge(opsI)
           }
-        } else if ($deleteOp.check(opsI)) {
-          // nop
+        /* c8 ignore start */
         } else {
+          // remaining branches: opsI is deleteOp or something unknown
+          // both branches are unreachable today: opNextUndeleted skips
+          // delete ops, so opsI is never a delete during iteration; and the four
+          // branches above exhaust the other op kinds. The deleteOp branch is
+          // kept as a defensive no-op (drops a modify that lands in a deleted
+          // region) rather than a throw.
           error.unexpectedCase()
         }
       } else {
         error.unexpectedCase()
       }
-    })
-    maybeMergeable.forEach(op => {
+      /* c8 ignore stop */
+    }
+    // iterate backwards, to ensure that we merge all content
+    for (let i = maybeMergeable.length - 1; i >= 0; i--) {
+      const op = maybeMergeable[i]
       // check if this is still integrated
-      if (op.prev?.next === op) {
-        tryMergeWithPrev(this.children, op)
-        op.next && tryMergeWithPrev(this.children, op.next)
+      if (op.prev != null ? op.prev.next === op : this.children.start === op) {
+        op.prev && _mergeChildWithPrev(this, op)
+        op.next && _mergeChildWithPrev(this, op.next)
       }
-    })
+    }
+    // marks: shift this node's own leaf marks by the change, then fold in root-level mark adds/deletes
+    // (child subtree marks already flagged `maybeHasMarks` incrementally above)
+    shiftMarksByChange(this, other)
+    // pass `final` so a materializing apply (e.g. a deltaRDT's final state) applies deletes in place
+    // but collects no pending `deleteMarks`; a non-final change delta still records them (transmittable)
+    applyMarkOps(this, other.marks, other.deleteMarks, final)
     return this
   }
 
   /**
+   * Rebase this op against a concurrent op. We can apply this op on a doc that already applied
+   * `other` op.
+   *
    * @param {DeltaAny} other
    * @param {boolean} priority
    */
@@ -1720,9 +2635,12 @@ export class DeltaBuilder extends Delta {
           // @ts-ignore
           delete this.attrs[otherOp.key]
         }
+      /* c8 ignore start */
       } else {
+        // unreachable: attr ops are exhaustively setAttr | deleteAttr | modifyAttr
         error.unexpectedCase()
       }
+      /* c8 ignore stop */
     }
     /**
      * Rebase children.
@@ -1749,10 +2667,9 @@ export class DeltaBuilder extends Delta {
          * - insert: transform based on priority
          * - retain/delete/modify: transform next op against other
          */
-        if ($insertOp.check(otherChild) || $modifyOp.check(otherChild) || $textOp.check(otherChild)) {
+        if ($insertOp.check(otherChild) || $textOp.check(otherChild)) {
           if (!priority) {
-            list.insertBetween(this.children, currChild.prev, currChild, new RetainOp(otherChild.length, null, null))
-            this.childCnt += otherChild.length
+            _insertChild(this, currChild, new RetainOp(otherChild.length, undefined, undefined))
             // curr is transformed against other, transform curr against next
             otherOffset = otherChild.length
           } else {
@@ -1773,16 +2690,18 @@ export class DeltaBuilder extends Delta {
         if ($insertOp.check(otherChild) || $textOp.check(otherChild)) {
           // @todo: with all list changes (retain insertions, removal), try to merge the surrounding
           // ops later
-          list.insertBetween(this.children, currChild.prev, currChild, new RetainOp(otherChild.length, null, null))
-          this.childCnt += otherChild.length
+          _insertChild(this, currChild, new RetainOp(otherChild.length, undefined, undefined))
           // curr is transformed against other, transform curr against next
           otherOffset = otherChild.length
         } else {
           if ($modifyOp.check(otherChild)) {
-            /** @type {any} */ (currChild.value).rebase(otherChild, priority)
+            // _modValue (not .value) — ModifyOp.clone() marks its inner delta
+            // as `done`, so a cloned ModifyOp can only be rebased after the
+            // _modValue getter lazy-clones it back to mutable. This recursion also reconciles the
+            // value's own root marks (via rebaseRootMarks), so a nested mark needs no special handling.
+            currChild._modValue.rebase(otherChild.value, priority)
           } else if ($deleteOp.check(otherChild)) {
-            list.remove(this.children, currChild)
-            this.childCnt -= 1
+            _removeChild(this, currChild)
           }
           currOffset += 1
           otherOffset += 1
@@ -1796,25 +2715,66 @@ export class DeltaBuilder extends Delta {
          * - insert: split curr op and insert retain
          */
         if ($retainOp.check(otherChild) || $modifyOp.check(otherChild)) {
+          // Format reconciliation over the [currOffset..currOffset+maxCommonLen] overlap. Split currChild
+          // around the overlap so the prefix/suffix keep their original format and only the middle piece
+          // changes. Three rules:
+          //  1. A blanket `null` clear ALWAYS wins, priority-independent (this is what lets it converge — both
+          //     rebase orderings agree the overlap ends up cleared, at the cost of dropping a concurrent set;
+          //     hence `null` is a local-only utility, see the `Formats` docs). currChild's own
+          //     `null` clear is left untouched (it wins); if *other* clears, currChild concedes its whole format.
+          //  2. Otherwise (both per-key objects) priority decides: priority=true is a no-op (currChild wins);
+          //     for !priority currChild concedes any key otherChild also writes (a `{k:null}` removal is just
+          //     such a key, so per-key removals reconcile here and converge without data loss — the recommended
+          //     way to clear).
+          //  3. otherChild `undefined` (skip) never changes currChild.
+          if ($retainOp.check(currChild) && currChild.format !== null) {
+            let changed = false
+            /** @type {Formats|null|undefined} */
+            let newFormat
+            if (otherChild.format === null) {
+              // other clears all → clear wins → currChild concedes its entire format
+              if (currChild.format !== undefined) { newFormat = undefined; changed = true }
+            } else if (!priority && currChild.format != null && otherChild.format != null) {
+              /** @type {Formats} */
+              const stripped = {}
+              for (const k in currChild.format) {
+                if (k in otherChild.format) changed = true
+                else stripped[k] = currChild.format[k]
+              }
+              if (changed) newFormat = object.isEmpty(stripped) ? undefined : stripped
+            }
+            if (changed) {
+              // split off the suffix [currOffset+maxCommonLen..length] if any
+              if (currOffset + maxCommonLen < currChild.length) {
+                _splitChildAt(this, currChild, currOffset + maxCommonLen)
+              }
+              // split off the prefix [0..currOffset] if any: currChild becomes the [currOffset..] suffix
+              if (currOffset > 0) {
+                currChild = _splitChildAt(this, currChild, currOffset)
+                currOffset = 0
+              }
+              // currChild now spans exactly the overlap. A conceded format is `undefined` (skip / no format
+              // change), NOT `null` (which would CLEAR the format on apply).
+              /** @type {any} */ (currChild).format = newFormat
+              currChild._fingerprint = null
+            }
+          }
           currOffset += maxCommonLen
           otherOffset += maxCommonLen
         } else if ($deleteOp.check(otherChild)) {
-          if ($retainOp.check(currChild)) {
-            // @ts-ignore
-            currChild.retain -= maxCommonLen
-          } else if ($deleteOp.check(currChild)) {
-            currChild.delete -= maxCommonLen
-          }
-          this.childCnt -= maxCommonLen
-        } else { // insert/text.check(currOp)
+          // currChild is Retain | Delete here (outer branch); shrink it by the overlap
+          _shrinkChild(this, currChild, currOffset, maxCommonLen)
+          // advance other so subsequent currChild ops see what comes AFTER this
+          // delete; without this we'd loop against the same delete forever and
+          // never reach other's later inserts.
+          otherOffset += maxCommonLen
+        } else { // insert/text.check(otherChild)
           if (currOffset > 0) {
-            const leftPart = currChild.clone(currOffset)
-            list.insertBetween(this.children, currChild.prev, currChild, leftPart)
-            currChild._splice(currOffset, currChild.length - currOffset)
+            // split currChild so the cursor sits on the boundary; continue on the [currOffset..] suffix
+            currChild = _splitChildAt(this, currChild, currOffset)
             currOffset = 0
           }
-          list.insertBetween(this.children, currChild.prev, currChild, new RetainOp(otherChild.length, null, null))
-          this.childCnt += otherChild.length
+          _insertChild(this, currChild, new RetainOp(otherChild.length, undefined, undefined))
           otherOffset = otherChild.length
         }
       }
@@ -1827,6 +2787,13 @@ export class DeltaBuilder extends Delta {
         otherOffset = 0
       }
     }
+    // marks: reconcile this node's own root mark ops against the concurrent change (also shifting and,
+    // where an anchor was deleted, converting an add to a delete). No count to maintain: `maybeHasMarks`
+    // is conservative (rebase only drops/reconciles marks, never adds), so a stale `true` is harmless
+    // and marksToPositions self-corrects it.
+    if (this.marks !== null || this.deleteMarks !== null) {
+      rebaseRootMarks(this, other, priority)
+    }
     return this
   }
 
@@ -1857,43 +2824,576 @@ export class DeltaBuilder extends Delta {
    * >, FixedConf>}
    */
   append (other) {
-    const children = this.children
-    const prevLast = children.end
+    const prevLast = this.children.end
     // @todo Investigate. Above is a typescript issue. It is necessary to cast OtherDelta to a Delta first before
     // inferring type, otherwise Children will contain Text.
     for (const child of other.children) {
-      list.pushEnd(children, child.clone())
+      _insertChild(this, null, child.clone())
     }
-    this.childCnt += other.childCnt
-    prevLast?.next && tryMergeWithPrev(children, prevLast.next)
+    // appended children may carry marks in their subtrees - flag conservatively
+    this.maybeHasMarks ||= other.maybeHasMarks
+    prevLast?.next && _mergeChildWithPrev(this, prevLast.next)
     // @ts-ignore
     return this
   }
 }
 
 /**
- * @param {ChildrenOpAny} op
- * @param {{[k:string]:any}} formatUpdate
- */
-const updateOpFormat = (op, formatUpdate) => {
-  if (!$deleteOp.check(op)) {
-    // apply formatting attributes
-    for (const k in formatUpdate) {
-      const v = formatUpdate[k]
-      if (v != null || $retainOp.check(op)) {
-        // never modify formats
-        /** @type {any} */ (op).format = object.assign({}, op.format, { [k]: v })
-      } else if (op.format != null) {
-        const { [k]: _, ...rest } = op.format
-        ;/** @type {any} */ (op).format = rest
+ * Apply one tri-state dimension update (`format` or `attribution`) to `op[field]` and report whether it
+ * changed. `undefined` = skip; `null` = clear all keys; an object merges per-key (`{k:v}` sets, `{k:null}`
+ * removes key `k`). `format` and `attribution` are handled identically (the unified model).
+ *
+ * On an **instruction** op (`retain`/`modify`) the merge is kept verbatim — a `{k:null}` removal and a
+ * `null` clear must survive so they still apply when this op is later consumed (an empty merge result `{}`
+ * is a no-op → `undefined`/skip). On a **data** op (`insert`/`text`/attr op) the merge is resolved against
+ * the stored value (empty → `null`/none). (Limitation: a `null` clear already present on an instruction op
+ * does not compose with a subsequent set into a single op — only the set survives. The diff never produces
+ * this; it would need arbitrary clear-then-set change composition.)
+ *
+ * @param {_OpAny} op
+ * @param {'format'|'attribution'} field
+ * @param {{[k:string]:any}|null|undefined} update
+ * @return {boolean} whether `op[field]` was touched
+ */
+const applyDim = (op, field, update) => {
+  if (update === undefined) return false
+  if (update === null) {
+    /** @type {any} */ (op)[field] = null // clear all
+  } else if ($retainOp.check(op) || $modifyOp.check(op)) {
+    // instruction op: keep the merge verbatim (preserves `{k:null}` removals to apply later). Attribution
+    // additionally merges its nested `format` key one level (see {@link mergeAttr}); format stays shallow.
+    const cur = /** @type {any} */ (op)[field]
+    const merged = field === 'attribution' ? mergeAttr(cur, update, false) : object.assign({}, cur, update)
+    ;/** @type {any} */ (op)[field] = object.isEmpty(merged) ? undefined : merged
+  } else if (field === 'attribution') {
+    // data op, attribution: resolve per key; the nested `format` key merges one level (see {@link mergeAttr})
+    const merged = mergeAttr(/** @type {any} */ (op)[field], update, true)
+    ;/** @type {any} */ (op)[field] = object.isEmpty(merged) ? null : merged
+  } else {
+    // data op (format): resolve per-key against the stored value (`{k:v}` sets, `{k:null}` removes, `{k:undefined}` skips)
+    let f = /** @type {any} */ (op)[field]
+    for (const k in update) {
+      const v = update[k]
+      if (v === undefined) continue // skip this key
+      if (v === null) { // remove this key (no-op when the stored value is already `null`)
+        if (f !== null) {
+          const { [k]: _, ...rest } = f
+          f = object.isEmpty(rest) ? null : rest
+        }
+      } else { // set this key
+        f = object.assign({}, f, { [k]: v })
       }
     }
+    /** @type {any} */ (op)[field] = f
+  }
+  return true
+}
+
+/**
+ * Compute the tri-state update that turns stored value `aVal` into `bVal` (used by {@link diff} for both
+ * `format` and `attribution`): `undefined` when unchanged (skip), `null` when fully cleared, else a
+ * per-key object (`{k:v}` for changed/added keys, `{k:null}` for removed keys). With `deep` (attribution),
+ * the nested `format` key is diffed one level deeper so it round-trips through {@link mergeAttr}'s per-inner-key
+ * merge instead of a wholesale replace.
+ *
+ * @param {{[k:string]:any}|null|undefined} aVal
+ * @param {{[k:string]:any}|null|undefined} bVal
+ * @param {boolean} deep `true` for `attribution` (recurse its `format` key), `false` for `format` (shallow)
+ * @return {{[k:string]:any}|null|undefined}
+ */
+const diffDim = (aVal, bVal, deep) => {
+  if (fun.equalityDeep(aVal, bVal)) return undefined
+  if ((bVal === null || bVal === undefined || object.isEmpty(bVal)) && (deep || aVal == null)) {
+    return null // fully cleared: attribution (`deep`) clears wholesale; format with no prior keys has nothing to enumerate
+  }
+  /** @type {{[k:string]:any}} */
+  const u = {}
+  for (const k in bVal) {
+    if (!fun.equalityDeep(bVal[k], aVal?.[k] ?? null)) {
+      // attribution's nested `format` diffs one level deeper (mirrors mergeAttr); everything else is wholesale
+      u[k] = deep && k === 'format' && s.$objectAny.check(bVal[k]) && s.$objectAny.check(aVal?.[k])
+        ? diffDim(aVal[k], bVal[k], false)
+        : bVal[k]
+    }
+  }
+  // removed keys. For `format` (shallow) a full clear enumerates one `{k:null}` per prior key instead of a
+  // wholesale `format:null` — individual clears rebase without clobbering concurrently-added formats.
+  // (`for..in` is a no-op when `aVal` is nullish; `k in bVal` is guarded against a nullish `bVal`.)
+  for (const k in aVal) { if (bVal == null || !(k in bVal)) u[k] = null }
+  return u
+}
+
+/**
+ * Apply a `format` and/or `attribution` update to an op (both unified tri-state — see {@link applyDim}).
+ * `format`/`attribution` are fingerprinted, so any change nulls the op's `_fingerprint`.
+ *
+ * @param {ChildrenOpAny} op
+ * @param {{[k:string]:any}|null|undefined} formatUpdate
+ * @param {{[k:string]:any}|null|undefined} attributionUpdate
+ */
+const updateOpFormat = (op, formatUpdate, attributionUpdate) => {
+  if ($deleteOp.check(op)) return
+  const changedF = applyDim(op, 'format', formatUpdate)
+  const changedA = applyDim(op, 'attribution', attributionUpdate)
+  if (changedF || changedA) {
+    /** @type {any} */ (op)._fingerprint = null
+  }
+}
+
+/**
+ * @param {ChildrenOpAny?} op
+ */
+const opNextUndeleted = op => {
+  op = op?.next || null
+  while (op != null && $deleteOp.check(op)) {
+    op = op.next
+  }
+  return op
+}
+
+/**
+ * Total order on marks by their (unique) id, used to sort a mark list deterministically (e.g. in
+ * {@link Delta#toJSON}).
+ *
+ * @param {Mark} a
+ * @param {Mark} b
+ */
+const compareMarksById = (a, b) => a.id < b.id ? -1 : 1
+
+/**
+ * Position-step order for a mark's `key`, mirroring the fingerprint key sort (see {@link Delta#fingerprint}):
+ * numbers (child indices) first, ascending; then string (attribute) keys, lexicographically.
+ *
+ * @param {number|string} a
+ * @param {number|string} b
+ */
+const cmpKey = (a, b) =>
+  s.$number.check(a) ? (s.$number.check(b) ? a - b : -1) : s.$number.check(b) ? 1 : (a < b ? -1 : a > b ? 1 : 0)
+
+/**
+ * Total order over the marks of one node: by position-step {@link cmpKey}, tie-broken by the (unique)
+ * id so the order is fully deterministic even when two cursors share a key. Used by {@link sortMarks}.
+ *
+ * @param {Mark} a
+ * @param {Mark} b
+ */
+const cmpMarkKey = (a, b) => cmpKey(a.key, b.key) || (a.id < b.id ? -1 : a.id > b.id ? 1 : 0)
+
+/**
+ * Sort a {@link Marks} set in place into its canonical {@link cmpMarkKey} order and return it. Called
+ * lazily whenever the set is iterated, so every reader (e.g.
+ * {@link import('./position.js').marksToPositions}) sees one deterministic, position-ordered sequence
+ * regardless of the order marks were added in. Order is not part of a delta's identity, so reordering
+ * is safe even on a `done` delta.
+ *
+ * @param {Marks} marks
+ */
+const sortMarks = marks => { marks._marks.sort(cmpMarkKey); return marks }
+
+/**
+ * The set of leaf {@link Mark marks} on a single delta node, deduplicated by id (so adding the same id
+ * again replaces it). An internal data-shape class (never a public/`new`-from-outside class): every
+ * mutation goes through its methods, so a stored {@link Mark} is treated as immutable and is never
+ * manipulated in place — to "move" a mark you replace it with a fresh `Mark`. {@link clone}/{@link
+ * slice} copy the set so a `done` delta's marks are never mutated through a shared reference. Marks are
+ * local/ephemeral cursor state
+ * and not part of a delta's identity, so this set has no fingerprint/equality of its own.
+ */
+class Marks {
+  constructor () {
+    /**
+     * @type {Array<Mark>}
+     */
+    this._marks = []
+  }
+
+  get size () { return this._marks.length }
+
+  /**
+   * Add or replace `mark` (by id). Returns `true` if it was added as a new mark, `false` if it
+   * replaced an existing one with the same id.
+   *
+   * @param {Mark} mark
+   * @return {boolean}
+   */
+  add (mark) {
+    const i = this._marks.findIndex(m => m.id === mark.id)
+    if (i < 0) {
+      this._marks.push(mark)
+      return true
+    }
+    this._marks[i] = mark
+    return false
+  }
+
+  /**
+   * Remove the mark with `id`. Returns `true` if a mark was present and removed, `false` if absent.
+   *
+   * @param {string} id
+   * @return {boolean}
+   */
+  delete (id) {
+    const i = this._marks.findIndex(m => m.id === id)
+    if (i < 0) return false
+    this._marks.splice(i, 1)
+    return true
+  }
+
+  [Symbol.iterator] () { sortMarks(this); return this._marks[Symbol.iterator]() }
+}
+
+/**
+ * Whether any delta element in `insert` maybe carries a mark in its subtree (short-circuits). Used to
+ * OR-propagate the conservative {@link DeltaData#maybeHasMarks} flag when content is inserted.
+ *
+ * @param {Array<any>} insert
+ * @return {boolean}
+ */
+const elemsMaybeHaveMarks = insert => insert.some(el => $deltaAny.check(el) && el.maybeHasMarks)
+
+/**
+ * Add (or replace) a {@link Mark} on `node`, flagging {@link DeltaData#maybeHasMarks}. Adding a mark
+ * cancels any pending delete of the same id on `node` (so a node never holds both an add and a delete
+ * for one id — the add wins), keeping the apply path consistent with rebase's add-vs-delete rule.
+ *
+ * @param {DeltaAny} node
+ * @param {Mark} mark
+ */
+const addMarkTo = (node, mark) => {
+  const marks = node.marks ?? new Marks()
+  marks.add(mark)
+  node.marks = marks
+  node.maybeHasMarks = true
+  if (node.deleteMarks !== null) {
+    node.deleteMarks.delete(mark.id)
+    if (node.deleteMarks.size === 0) node.deleteMarks = null
+  }
+}
+
+/**
+ * Mirror of {@link addMarkTo}: assert mark `id` is *absent* on `node` (last-writer-wins). Strips a
+ * present add of `id` (a delete cancels a pending add — newest wins), then, only for a CHANGE delta
+ * (`record`, i.e. a non-final apply), records the transmittable tombstone in `deleteMarks`. A
+ * final/materializing apply passes `record === false`: the mark is removed in place but no tombstone is
+ * collected (a final delta carries none — see {@link DeltaData#deleteMarks}). The `maybeHasMarks` flag is
+ * intentionally left as-is (never decremented - {@link import('./position.js').marksToPositions}
+ * self-corrects it). Together with `addMarkTo` these are the only two writers of `marks`/`deleteMarks`,
+ * so a node can never hold both an add and a delete for one id.
+ *
+ * @param {DeltaAny} node
+ * @param {string} id
+ * @param {boolean} record whether to keep a transmittable `deleteMarks` tombstone (`= !final`)
+ */
+const deleteMarkTo = (node, id, record) => {
+  if (node.marks !== null) {
+    node.marks.delete(id)
+    if (node.marks.size === 0) node.marks = null
+  }
+  if (record) {
+    const dm = node.deleteMarks ?? new Set()
+    dm.add(id)
+    node.deleteMarks = dm
+  }
+}
+
+/**
+ * Apply mark add/delete ops to `target` (flagging `target.maybeHasMarks` on add). `addMarks` may be a
+ * {@link Marks} set or a plain array; `deleteMarks` is a set of ids. The two id-keyed primitives
+ * {@link deleteMarkTo}/{@link addMarkTo} are the only writers of `marks`/`deleteMarks`, so a node can
+ * never end holding both for one id. Deletes are processed before adds so that a single change carrying
+ * both for one id resolves to *add wins* (the add re-runs last and strips the just-recorded tombstone),
+ * matching the rebase policy. `final` marks a document-materializing apply (propagated from
+ * {@link DeltaBuilder#apply}, defaulting to `this.isFinal`): a settled document removes a present mark in
+ * place but records no tombstone, while a non-final change delta records the delete (passed as
+ * `record = !final`) so `create().removeMark(pos, id)` stays transmittable.
+ *
+ * @param {DeltaAny} target
+ * @param {Iterable<Mark>?} addMarks
+ * @param {Set<string>?} deleteMarks
+ * @param {boolean} final whether this is a final (document-materializing) apply
+ */
+const applyMarkOps = (target, addMarks, deleteMarks, final) => {
+  if (deleteMarks !== null) {
+    for (const id of deleteMarks) deleteMarkTo(target, id, !final)
+  }
+  if (addMarks !== null) {
+    for (const m of addMarks) addMarkTo(target, m)
+  }
+}
+
+/**
+ * Re-key `node`'s *root* marks in place: each mark's `key` is mapped through `mapKey` (return `null` to
+ * drop it, an unchanged key to keep it, or a new key to move it). Used after a full {@link clone} by an
+ * attribute-renaming transformer so a mark on a renamed attribute follows the rename (and a mark on a
+ * dropped attribute is dropped). `node.maybeHasMarks` is left set (conservative; never decremented).
+ *
+ * @param {DeltaAny} node
+ * @param {(key: number|string) => number|string|null} mapKey
+ * @internal transformer plumbing (used by mark-carrying transformers), not consumer API.
+ */
+export const remapRootMarks = (node, mapKey) => {
+  const marks = node.marks
+  if (marks === null) return
+  for (const m of [...marks]) {
+    const k = mapKey(m.key)
+    if (k === m.key) continue
+    deleteMarkTo(node, m.id, false) // relocate a present mark: strip it, but synthesize no tombstone
+    if (k !== null) addMarkTo(node, m.copy(k))
   }
 }
 
+/**
+ * Add (or replace, by id) a single root {@link Mark} on `node`, flagging `node.maybeHasMarks`. The
+ * public wrapper of the internal `addMarkTo`, used by the restructuring
+ * {@link import('./transformer/core.js').Transformer transformers} (`inline`, `project`) to place a
+ * mark at a position they compute themselves.
+ *
+ * @param {DeltaAny} node
+ * @param {Mark} mark
+ * @internal transformer plumbing (used by `inline`/`project`), not consumer API.
+ */
+export const addRootMark = (node, mark) => addMarkTo(node, mark)
+
+/**
+ * Mark id `id` as deleted on `node` (the mirror of {@link addRootMark}): the public wrapper of the
+ * internal {@link deleteMarkTo} with `record === true`, used by the restructuring
+ * {@link import('./transformer/core.js').Transformer transformers} (`inline`, `project`) to carry a mark
+ * *delete* (which is id-keyed, so it needs no position) onto the node they build. Strips a present add of
+ * the same id (last-writer-wins) so the node never holds both.
+ *
+ * @param {DeltaAny} node
+ * @param {string} id
+ * @internal transformer plumbing (used by `inline`/`project`), not consumer API.
+ */
+export const deleteRootMark = (node, id) => deleteMarkTo(node, id, true)
+
+/**
+ * Merge `source`'s *root* marks onto `target`, mapping each add mark's `key` through `mapKey` (return
+ * `null` to drop it, a new key to move it via {@link Mark#copy}). `source`'s `deleteMarks` are merged
+ * verbatim through {@link deleteMarkTo} — a delete is keyed only by its (cross-side-stable) id, so it
+ * maps in either direction and strips a conflicting add on `target` (last-writer-wins, never both). Safe
+ * to call repeatedly to accumulate marks from several sources onto one target (e.g.
+ * {@link import('./transformer/inline.js') inline} lifting the marks of every spliced node onto the
+ * flattened parent), and — onto a fresh target — to copy a node's marks across a key remapping (e.g.
+ * {@link cloneShallow}, and the `attr` transformer following an attribute rename). `target.maybeHasMarks`
+ * is flagged for the added marks; marks inside copied delta-valued attributes/children are flagged when
+ * the caller appends them via the builder (and {@link cloneShallow} copies the flag wholesale).
+ *
+ * @param {DeltaAny} target
+ * @param {DeltaAny} source
+ * @param {(key: number|string) => number|string|null} [mapKey]
+ * @internal transformer plumbing (used by `inline`/`attr`/`cloneShallow`), not consumer API.
+ */
+export const mergeRootMarks = (target, source, mapKey = k => k) => {
+  if (source.marks !== null) {
+    for (const m of source.marks) {
+      const k = mapKey(m.key)
+      if (k !== null) addMarkTo(target, k === m.key ? m : m.copy(k))
+    }
+  }
+  if (source.deleteMarks !== null) {
+    for (const id of source.deleteMarks) deleteMarkTo(target, id, true)
+  }
+}
+
+/**
+ * Map a number `key` (a content offset) of a leaf mark on a node through the content ops of `change`,
+ * returning its new offset. An insert before the key pushes it right (tie-broken at the exact offset by
+ * `assoc`). A delete covering the key applies *collapse-to-cut*: the mark slides to the cut point
+ * (`newPos`) — i.e. to *before* any replacement text inserted there — instead of being dropped, so a
+ * cursor whose content is deleted survives at the deletion site. `oldPos` walks the pre-change doc and
+ * `newPos` the post-change doc *independently* — `key` is never mutated, so an insert past the key is
+ * always compared against the mark's original offset even after earlier deletes shifted the content.
+ *
+ * NOTE: collapse-to-cut is intentionally NOT confluent under concurrent {@link DeltaBuilder#rebase} — a
+ * deletion maps a whole range to one point, losing where in the range the cursor was, so a concurrent
+ * insert there lands on different sides on the two replays. Marks are therefore treated as local /
+ * ephemeral cursor state, excluded from a delta's identity ({@link Delta#fingerprint} / equality); only
+ * the document *content* is guaranteed to converge.
+ *
+ * @param {DeltaAny} change
+ * @param {number} key
+ * @param {1|-1} assoc
+ * @return {number}
+ */
+const shiftMarkKey = (change, key, assoc) => {
+  let oldPos = 0
+  let newPos = 0
+  for (const op of change.children) {
+    if ($retainOp.check(op) || $modifyOp.check(op)) {
+      const n = op.length
+      if (key < oldPos + n) return newPos + (key - oldPos) // mark falls inside this retained run
+      oldPos += n
+      newPos += n
+    } else if ($insertOp.check(op) || $textOp.check(op)) {
+      if (oldPos < key || (oldPos === key && assoc === 1)) newPos += op.length
+    } else if ($deleteOp.check(op)) {
+      const n = op.delete
+      // mark lies in [oldPos, oldPos+n) — its content is being deleted ⇒ collapse to the cut point
+      if (key < oldPos + n) return newPos
+      // right boundary with LEFT gravity anchors to the last deleted char ⇒ also collapses to the cut
+      // (n > 0 guards the degenerate delete(0) rebase can emit, which deletes nothing)
+      if (n > 0 && key === oldPos + n && assoc === -1) return newPos
+      oldPos += n
+    }
+  }
+  return newPos + (key - oldPos)
+}
+
+/**
+ * Shift `node`'s own number-keyed leaf marks by the content ops of `change`, collapsing any covered by a
+ * delete to the cut point (see {@link shiftMarkKey}). Attribute-key (string) marks are untouched.
+ *
+ * @param {DeltaAny} node
+ * @param {DeltaAny} change
+ */
+const shiftMarksByChange = (node, change) => {
+  const marks = node.marks
+  if (marks === null) return
+  /** @type {Array<Mark>} */
+  const shifted = []
+  for (const m of marks) {
+    if (typeof m.key === 'number') {
+      const nk = shiftMarkKey(change, m.key, m.assoc)
+      if (nk !== m.key) shifted.push(m.copy(nk)) // a fresh Mark — never mutate in place
+    }
+  }
+  // re-add shifted marks under their (unchanged) ids ⇒ replace in place (the flag stays set)
+  for (const m of shifted) marks.add(m)
+}
+
+/**
+ * Collect the ids of a {@link Marks} set, a plain {@link Mark} array, or an id array (any may be
+ * `null`) into a `Set`, used for the by-id conflict checks during {@link DeltaBuilder#rebase}.
+ *
+ * @param {Iterable<Mark|string>?} marksOrIds
+ * @return {Set<string>}
+ */
+const markIdSet = marksOrIds => {
+  /** @type {Set<string>} */
+  const ids = new Set()
+  if (marksOrIds !== null) {
+    for (const x of marksOrIds) ids.add(typeof x === 'string' ? x : x.id)
+  }
+  return ids
+}
+
+/**
+ * Core mark reconciliation for one node level during {@link DeltaBuilder#rebase}. `adds` are this
+ * side's mark adds (with keys) and `deletes` its delete ids; `otherAddIds`/`otherDelIds` are the
+ * concurrent side's ids and `otherContent` the delta whose content ops shift surviving number keys.
+ *
+ * Rules (each by mark id): add-vs-add → `priority` decides; add-vs-delete → the add wins (a re-placed
+ * cursor is not killed by a stale removal); delete-vs-delete → the duplicate is dropped. A surviving
+ * number-keyed add is shifted by `otherContent`, collapsing to the cut point if its content was
+ * concurrently deleted (see {@link shiftMarkKey}). Cursor positions are best-effort, not guaranteed to
+ * converge (marks are excluded from the document's identity); only content convergence is guaranteed.
+ *
+ * @param {Iterable<Mark>} adds
+ * @param {Array<string>} deletes
+ * @param {Set<string>} otherAddIds
+ * @param {Set<string>} otherDelIds
+ * @param {DeltaAny} otherContent
+ * @param {boolean} priority
+ * @return {{ adds: Array<Mark>, deletes: Array<string> }}
+ */
+const rebaseMarkOps = (adds, deletes, otherAddIds, otherDelIds, otherContent, priority) => {
+  /** @type {Array<Mark>} */
+  const keptAdds = []
+  /** @type {Array<string>} */
+  const delIds = deletes.slice()
+  for (const m of adds) {
+    if (!priority && otherAddIds.has(m.id)) continue // lost an add-vs-add conflict
+    if (typeof m.key === 'number') {
+      const nk = shiftMarkKey(otherContent, m.key, m.assoc) // collapses to the cut if its content was deleted
+      keptAdds.push(nk === m.key ? m : m.copy(nk))
+    } else {
+      keptAdds.push(m)
+    }
+  }
+  // a delete survives only where the other side neither re-adds (add wins) nor already deletes (dedup)
+  /** @type {Set<string>} */
+  const seen = new Set()
+  /** @type {Array<string>} */
+  const keptDels = []
+  for (const id of delIds) {
+    if (!seen.has(id) && !otherAddIds.has(id) && !otherDelIds.has(id)) {
+      seen.add(id)
+      keptDels.push(id)
+    }
+  }
+  return { adds: keptAdds, deletes: keptDels }
+}
+
+/**
+ * Reconcile a node's own root mark add/delete ops against a concurrent change `other` during
+ * {@link DeltaBuilder#rebase}, rebuilding `node.marks`/`node.deleteMarks` from {@link rebaseMarkOps}.
+ * `maybeHasMarks` is left set (conservative; marksToPositions self-corrects a now-empty subtree).
+ *
+ * @param {DeltaAny} node
+ * @param {DeltaAny} other
+ * @param {boolean} priority
+ */
+const rebaseRootMarks = (node, other, priority) => {
+  const { adds, deletes } = rebaseMarkOps(
+    node.marks !== null ? [...node.marks] : [],
+    node.deleteMarks !== null ? [...node.deleteMarks] : [],
+    markIdSet(other.marks), markIdSet(other.deleteMarks), other, priority
+  )
+  // rebuild both fields wholesale from rebaseMarkOps's provably-disjoint output (concurrent reconciliation
+  // keeps its deliberate add-wins rule, NOT the apply path's last-writer-wins; not a primitive write)
+  if (adds.length === 0) {
+    node.marks = null
+  } else {
+    const m = new Marks()
+    for (const x of adds) m.add(x)
+    node.marks = m
+  }
+  node.deleteMarks = deletes.length === 0 ? null : new Set(deletes)
+}
+
+/**
+ * Build a change delta that adds (or, with `isDelete`, removes) the mark for `pos`. The descent is a
+ * `retain`/`modify`/`modifyAttr` chain re-derived from `pos.path`; the mark always rides on the **leaf
+ * delta's own marks** (root marks). Each interior step just wraps the next level in a `modify`
+ * (content index) or `modifyAttr` (attribute key) — apply/rebase carry the wrapped value's root marks
+ * onto/through the target for free.
+ *
+ * @param {import('./position.js').Pos} pos
+ * @param {string} id
+ * @param {boolean} isDelete
+ * @return {DeltaBuilderAny}
+ */
+const markChange = (pos, id, isDelete) => {
+  const path = pos.path
+  // a mark anchors at the terminal step of its path (a content offset or attribute key); the root
+  // position `[]` has no terminal and cannot carry a mark - reject it instead of recursing forever
+  if (path.length === 0) throw error.create('cannot place a mark at the root position (empty path): a mark needs a terminal content-offset or attribute-key step')
+  const mark = isDelete ? null : createMark(path[path.length - 1], id, pos.assoc, pos.attrs ?? null)
+  /**
+   * @param {number} i
+   * @return {DeltaBuilderAny}
+   */
+  const build = i => {
+    if (i === path.length - 1) {
+      // leaf reached: carry the mark on the delta's own marks
+      const d = /** @type {DeltaBuilderAny} */ (create())
+      if (mark === null) deleteMarkTo(d, id, true) // a change delta records the transmittable delete
+      else addMarkTo(d, mark)
+      return d
+    }
+    const step = path[i]
+    return s.$string.check(step)
+      ? /** @type {DeltaBuilderAny} */ (create()).modifyAttr(step, build(i + 1))
+      : /** @type {DeltaBuilderAny} */ (create()).retain(step).modify(build(i + 1))
+  }
+  return build(0)
+}
+
 /**
  * @template {DeltaConf} Conf
  * @extends {s.Schema<Delta<Conf>>}
+ * @internal use the {@link $delta} factory; this class is exported only for the `$$delta` predicate.
  */
 export class $Delta extends s.Schema {
   /**
@@ -1932,8 +3432,10 @@ export class $Delta extends s.Schema {
   check (o, err = undefined) {
     const { $name, $attrs, $children, hasText, $formats } = this.shape
     if (!$deltaAny.check(o, err)) {
+      /* c8 ignore next */
       err?.extend(null, 'Delta', o?.constructor.name, 'Constructor match failed')
     } else if (o.name != null && !$name.check(o.name, err)) {
+      /* c8 ignore next */
       err?.extend('Delta.name', $name.toString(), o.name, 'Unexpected node name')
     } else if (list.toArray(o.children).some(c => (!hasText && $textOp.check(c)) || (hasText && $textOp.check(c) && c.format != null && !$formats.check(c.format)) || ($insertOp.check(c) && !c.insert.every(ins => $children.check(ins))))) {
       err?.extend('Delta.children', '', '', 'Children don\'t match the schema')
@@ -1947,47 +3449,96 @@ export class $Delta extends s.Schema {
 }
 
 /**
- * @template {s.Schema<string>|string|Array<string>} [NodeNameSchema=s.Schema<any>]
- * @template {s.Schema<{ [key: string|number]: any }>|{ [key:string|number]:any }} [AttrsSchema=s.Schema<{}>]
- * @template {any} [ChildrenSchema=s.Schema<never>]
- * @template {boolean} [HasText=false]
- * @template {boolean} [RecursiveChildren=false]
- * @template {{ [k:string]:any }} [Formats={[k:string]:any}]
- * @param {object} opts
- * @param {NodeNameSchema?} [opts.name]
- * @param {AttrsSchema?} [opts.attrs] What key-value pairs are included.
- * @param {ChildrenSchema?} [opts.children] The type of content in `insertOp`
- * @param {HasText} [opts.text] Whether this delta contains text using `textOp`
- * @param {Formats} [opts.formats]
- * @param {RecursiveChildren} [opts.recursiveChildren]
- * @return {[s.ReadSchemaUnwrapped<NodeNameSchema>,s.ReadSchemaUnwrapped<AttrsSchema>,s.ReadSchemaUnwrapped<ChildrenSchema>] extends [infer NodeName, infer Attrs, infer Children] ? s.Schema<Delta<PrettifyDeltaConf<(import('../ts.js').TypeIsAny<NodeName, {}, { name: NodeName }> &
- *   ({} extends Attrs ? {} : { attrs: Attrs }) &
- *   ([Children] extends [never] ? {} : { children: Children }) &
- *   (HasText extends false ? {} : { text: HasText }) &
- *   (RecursiveChildren extends false ? {} : { recursiveChildren: RecursiveChildren })) extends infer DC extends DeltaConf ? DC : never>>> : never}
- */
-export const $delta = ({ name, attrs, children, text, formats, recursiveChildren: recursive }) => /** @type {any} */ (new $Delta(
-  /** @type {any} */ (name == null ? s.$any : s.$(name)),
-  /** @type {any} */ (attrs == null ? s.$object({}) : s.$(attrs)),
-  /** @type {any} */ (children == null ? s.$never : s.$(children)),
-  text ?? false,
-  recursive ?? false,
-  formats == null ? s.$any : s.$(formats)
-))
+ * @typedef {{
+ *   name?: s.Schema<string>|string|Array<string>,
+ *   attrs?: s.Schema<{ [key: string|number]: any }>|{ [key:string|number]:any },
+ *   children?: any,
+ *   text?: boolean,
+ *   recursiveChildren?: boolean,
+ *   formats?: { [k:string]: any }
+ * }} ReadableDeltaConf
+ */
+
+/**
+ * Transforms a ReadableDeltaConf (the input shape of `$delta(spec)`) to a DeltaConf.
+ * @template {ReadableDeltaConf} DConfSpec
+ * @typedef {[
+ *   DConfSpec extends {name: infer N} ? s.ReadSchemaUnwrapped<N> : any,
+ *   DConfSpec extends {attrs: infer A} ? s.ReadSchemaUnwrapped<A> : {},
+ *   DConfSpec extends {children: infer C} ? s.ReadSchemaUnwrapped<C> : never
+ * ] extends [infer NodeName, infer Attrs, infer Children]
+ *   ? AsDeltaConf<PrettifyDeltaConf<(
+ *       import('../ts.js').TypeIsAny<NodeName, {}, { name: NodeName }> &
+ *       ([keyof Attrs] extends [never] ? {} : { attrs: Attrs }) &
+ *       ([Children] extends [never] ? {} : { children: Children }) &
+ *       (DConfSpec extends {text: true} ? { text: true } : {}) &
+ *       (DConfSpec extends {recursiveChildren: true} ? { recursiveChildren: true } : {})
+ *     )>>
+ *   : never
+ * } ReadDeltaConf
+ */
+
+/**
+ * Name-first form: a string-literal `name` as the first argument is preserved as a literal type
+ * (generic argument inference), so callers don't need `s.$literal('x')` / `@type {const}` to keep the
+ * node name literal. The remaining options follow in `opts`.
+ *
+ * @template {string} Name
+ * @template {Omit<ReadableDeltaConf, 'name'>} [Opts={}]
+ * @overload
+ * @param {Name} name
+ * @param {Opts} [opts]
+ * @return {s.Schema<Delta<ReadDeltaConf<Opts & { name: Name }>>>}
+ */
+/**
+ * @template {ReadableDeltaConf} [Conf={}]
+ * @overload
+ * @param {Conf} opts
+ * @return {s.Schema<Delta<ReadDeltaConf<Conf>>>}
+ */
+/**
+ * @param {ReadableDeltaConf|string} optsOrName
+ * @param {Omit<ReadableDeltaConf, 'name'>} [opts]
+ * @return {any}
+ */
+export const $delta = (optsOrName, opts) => {
+  const { name, attrs, children, text, formats, recursiveChildren: recursive } =
+    s.$string.check(optsOrName) ? { ...opts, name: optsOrName } : optsOrName
+  return /** @type {any} */ (new $Delta(
+    /** @type {any} */ (name == null ? s.$any : s.$(name)),
+    /** @type {any} */ (attrs == null ? s.$object({}) : s.$(attrs)),
+    /** @type {any} */ (children == null ? s.$never : s.$(children)),
+    text ?? false,
+    recursive ?? false,
+    formats == null ? s.$any : s.$(formats)
+  ))
+}
 
 export const $$delta = /* @__PURE__ */s.$constructedBy($Delta)
 
-export const $deltaAny = /** @type {s.Schema<DeltaAny>} */ (/* @__PURE__ */s.$type('delta'))
+export const $deltaAny = /** @type {s.Schema<Delta<any>>} */ (Delta.prototype.$type = s.$type('d:delta', Delta))
 export const $deltaBuilderAny = /** @type {s.Schema<DeltaBuilderAny>} */ (/* @__PURE__ */s.$custom(o => $deltaAny.check(o) && !o.isDone))
 
 /**
- * Helper function to merge attribution and attributes. The latter input "wins".
+ * Helper function to merge attribution and attributes. The latter input "wins". The nested `format` key is
+ * merged per inner key (one level — see {@link mergeAttr}); every other key is replaced wholesale.
+ *
+ * @template {{ [key: string]: any }} T
+ * @param {T | null} a
+ * @param {T | null} b
+ */
+export const mergeAttributions = (a, b) => a == null
+  ? b
+  : (b == null ? a : /** @type {T} */ (mergeAttr(a, b, true)))
+
+/**
+ * Helper function to merge formats. The latter input "wins".
  *
  * @template {{ [key: string]: any }} T
  * @param {T | null} a
  * @param {T | null} b
  */
-export const mergeAttrs = (a, b) => object.isEmpty(a)
+export const mergeFormats = (a, b) => object.isEmpty(a)
   ? (object.isEmpty(b) ? null : b)
   : (object.isEmpty(b) ? a : object.assign({}, a, b))
 
@@ -2003,33 +3554,163 @@ export const mergeDeltas = (a, b) => {
     c.apply(b)
     return /** @type {any} */ (c)
   }
-  return a == null ? b : (a || null)
+  return /** @type {D} */ (a || b || null)
+}
+
+/**
+ * The node (child delta) at child-position `pos` of `source`, or `null` when `pos` lands on a text
+ * run or a non-delta child. Lets {@link random} target an existing node with a `modify` op.
+ *
+ * @param {DeltaAny} source
+ * @param {number} pos
+ * @return {DeltaAny?}
+ */
+const childNodeAt = (source, pos) => {
+  let p = 0
+  for (const op of source.children) {
+    if ($textOp.check(op)) {
+      if (pos < p + op.insert.length) return null
+      p += op.insert.length
+    } else if ($insertOp.check(op)) {
+      for (const el of op.insert) {
+        if (p === pos) return $deltaAny.check(el) ? el : null
+        p++
+      }
+    }
+  }
+  /* c8 ignore start */
+  // the sole caller passes pos < source.childCnt (sourceLen >= 1), so a node or text run always
+  // resolves first; this guards an out-of-range pos defensively.
+  return null
+  /* c8 ignore stop */
+}
+
+/**
+ * "Find the child schema for this node": the `$Delta` schemas within `$children` (a single schema or
+ * any member of a union) that accept `node`. Only `$Delta` members can drive a recursive `random`
+ * modify, so non-delta children (numbers, strings, `$any`) and non-matching names are dropped.
+ *
+ * @param {s.Schema<any>} $children
+ * @param {DeltaAny} node
+ * @return {Array<s.Schema<DeltaAny>>}
+ */
+const matchingNodeSchemas = ($children, node) => (s.$$union.check($children) ? $children.shape : [$children])
+  .filter($c => $$delta.check($c) && $c.check(node))
+
+/**
+ * Random {@link Attribution} for fuzz tests. There is no schema for attributions; the canonical shape is
+ * `(insert|delete + …At)` intersected with an optional format part. The format part exists only on
+ * children (content ops), never on node attribute ops. Sometimes returns `undefined` (skip) or `null`
+ * (clear). The optional `format` part carries a random non-empty subset of the format names, so two random
+ * attributions differ in which inner `format` keys they carry — exercising the per-inner-key set/remove/merge
+ * of {@link mergeAttr}/{@link diffDim} on the diff round-trip.
+ *
+ * @param {prng.PRNG} gen
+ * @param {boolean} withFormat include the children-only `format`/`formatAt` part
+ * @return {Attribution|null|undefined}
+ */
+const randomAttribution = (gen, withFormat) => {
+  const r = prng.uint32(gen, 0, 5)
+  if (r <= 2) return undefined // ~half: skip (no attribution change)
+  if (r === 3) return null // clear all attribution
+  const user = () => [prng.oneOf(gen, ['alice', 'bob', 'carol'])]
+  /** @type {Attribution} */
+  const attribution = prng.bool(gen)
+    ? { insert: user(), insertAt: prng.uint32(gen, 0, 100) }
+    : { delete: user(), deleteAt: prng.uint32(gen, 0, 100) }
+  if (withFormat && prng.bool(gen)) {
+    // a random non-empty subset of format names (never an empty `format`, per the storage invariant)
+    /** @type {Record<string, string[]>} */
+    const format = {}
+    for (const name of ['bold', 'italic', 'under']) { if (prng.bool(gen)) format[name] = user() }
+    if (!object.isEmpty(format)) {
+      attribution.format = format
+      attribution.formatAt = prng.uint32(gen, 0, 100)
+    }
+  }
+  return attribution
 }
 
 /**
  * @template {DeltaConf} Conf
  * @param {prng.PRNG} gen
  * @param {s.Schema<Delta<Conf>>} $d
+ * @param {object} conf
+ * @param {DeltaAny?} [conf.source]
+ * @param {number} [conf.minChildOps]
+ * @param {number} [conf.maxChildOps]
+ * @param {boolean} [conf.attribution] generate random attributions (off by default; consumes no PRNG
+ * draws when off, so existing seeds are unaffected). Rebase does not converge attributions, so leave
+ * this off for rebase-convergence fuzzing and enable it for diff fuzzing.
  * @return {DeltaBuilder<Conf>}
  */
-export const random = (gen, $d) => {
+export const random = (gen, $d, conf = {}) => {
+  const { source = null, minChildOps = 1, maxChildOps = 9, attribution = false } = conf
+  let sourceLen = source == null ? 0 : source.childCnt
   const { $name, $attrs, $children, hasText, $formats: $formats_ } = /** @type {$Delta<any>} */ (/** @type {any} */ ($d)).shape
   const d = s.$$any.check($name) ? create($deltaAny) : create(s.random(gen, $name), $deltaAny)
   const $formats = s.$$any.check($formats_) ? s.$null : $formats_
-  prng.bool(gen) && d.setAttrs(s.random(gen, $attrs))
-  for (let i = prng.uint32(gen, 0, 5); i > 0; i--) {
-    if (hasText && prng.bool(gen)) {
-      d.insert(prng.word(gen), s.random(gen, $formats))
-    } else if (!s.$$never.check($children)) {
-      /**
-       * @type {Array<any>}
-       */
-      const ins = []
-      let insN = prng.int32(gen, 0, 5)
-      while (insN--) {
-        ins.push(s.random(gen, $children))
+  const genAttribution = /** @param {boolean} withFormat */ withFormat => attribution ? randomAttribution(gen, withFormat) : undefined
+  // set random attrs (node attribute ops carry the insert/delete part of an attribution only — no format part)
+  prng.bool(gen) && d.setAttrs(s.random(gen, $attrs, random), genAttribution(false))
+  // delete a single attr
+  if (source && !object.isEmpty(source.attrs) && prng.bool(gen)) {
+    d.deleteAttr(prng.oneOf(gen, object.keys(source.attrs)), genAttribution(false))
+  }
+  for (let i = prng.uint32(gen, minChildOps, maxChildOps); i > 0; i--) {
+    /**
+     * @type {Array<function():void>}
+     */
+    const possibleOps = []
+    if (hasText) {
+      possibleOps.push(() => {
+        d.insert(prng.oneOf(gen, ['a', 'b', ' ', '\n', '.']), s.random(gen, $formats), genAttribution(true))
+      })
+    }
+    if (!s.$$never.check($children)) {
+      possibleOps.push(() => {
+        /**
+         * @type {Array<any>}
+         */
+        const ins = []
+        let insN = prng.int32(gen, 0, 5)
+        while (insN--) {
+          ins.push(s.random(gen, $children, random))
+        }
+        d.insert(ins, s.random(gen, $formats), genAttribution(true))
+      })
+    }
+    if (sourceLen > 0) {
+      possibleOps.push(() => {
+        const len = prng.uint32(gen, 1, sourceLen)
+        sourceLen -= len
+        d.delete(len)
+      })
+      possibleOps.push(() => {
+        const len = prng.uint32(gen, 1, sourceLen)
+        sourceLen -= len
+        // a retain's format is a skip (`undefined`) or a per-key set object — never a blanket `null` clear
+        // ($null formats coerce to skip). Blanket clears are a local-only utility and discouraged on a
+        // channel (they "win" a rebase, dropping concurrent edits — see Formats); the diff fuzz
+        // already exercises the recommended per-key `{k:null}` removals (which converge without data loss).
+        d.retain(len, prng.bool(gen) ? undefined : (s.random(gen, $formats) ?? undefined), genAttribution(true))
+      })
+      // if the op we currently point at is a node, it's also a choice to modify it: find the child
+      // schema that matches the node and recursively generate a change against it.
+      const src = /** @type {DeltaAny} */ (source)
+      const node = childNodeAt(src, src.childCnt - sourceLen)
+      const $nodeMatches = node != null ? matchingNodeSchemas($children, node) : []
+      if ($nodeMatches.length > 0) {
+        possibleOps.push(() => {
+          d.modify(random(gen, prng.oneOf(gen, $nodeMatches), { source: node }), undefined, genAttribution(true))
+          sourceLen -= 1
+        })
       }
-      d.insert(ins, s.random(gen, $formats))
+    }
+    if (possibleOps.length > 0) {
+      prng.oneOf(gen, possibleOps)()
+    } else {
+      break
     }
   }
   return /** @type {any} */ (d)
@@ -2047,11 +3728,11 @@ export const random = (gen, $d) => {
  */
 /**
  * @template {string} NodeName
- * @template {DeltaConf} Conf
+ * @template {s.Schema<DeltaAny>} Schema
  * @overload
  * @param {NodeName} nodeName
- * @param {s.Schema<Delta<Conf>>} schema
- * @return {DeltaBuilder<Conf, true>}
+ * @param {Schema} schema
+ * @return {Schema extends s.Schema<Delta<infer Conf>> ? DeltaBuilder<Conf, true> : never}
  */
 /**
  * @template {s.Schema<DeltaAny>} Schema
@@ -2067,8 +3748,7 @@ export const random = (gen, $d) => {
  * @param {NodeName} nodeName
  * @param {Attrs} attrs
  * @param {Children} [children]
- * @return {DeltaBuilder<{
- *   name: NodeName,
+ * @return {DeltaBuilder<(NodeName extends string ? { name: NodeName } : {}) & {
  *   attrs: Attrs extends null ? {} : Attrs,
  *   children: Extract<Children,Array<any>> extends Array<infer Ac> ? (unknown extends Ac ? never : Ac) : never,
  *   text: Extract<Children,string> extends never ? false : true
@@ -2097,8 +3777,7 @@ export const create = (nodeNameOrSchema, attrsOrSchema, children) => {
  * @overload
  * @param {NodeName} nodeName
  * @param {...Array<Children>} children
- * @return {DeltaBuilder<{
- *   name: NodeName,
+ * @return {DeltaBuilder<(NodeName extends string ? { name: NodeName } : {}) & {
  *   children: Extract<Children,Array<any>> extends Array<infer Ac> ? (unknown extends Ac ? never : Ac) : never,
  *   text: Extract<Children,string> extends never ? false : true
  * }>}
@@ -2132,8 +3811,7 @@ export const create = (nodeNameOrSchema, attrsOrSchema, children) => {
  * @param {NodeName} nodeName
  * @param {Attrs} attrs
  * @param {...Array<Children>} children
- * @return {DeltaBuilder<{
- *   name: NodeName,
+ * @return {DeltaBuilder<(NodeName extends string ? { name: NodeName } : {}) & {
  *   attrs: Attrs extends null ? {} : Attrs,
  *   children: Extract<Children,Array<any>> extends Array<infer Ac> ? (unknown extends Ac ? never : Ac) : never,
  *   text: Extract<Children,string> extends never ? false : true
@@ -2156,17 +3834,84 @@ export const from = (...args) => {
   return d
 }
 
+class _DiffStringWrapper {
+  /**
+   * @param {string} str
+   */
+  constructor (str) {
+    this.str = str
+    /**
+     * @type {string?}
+     */
+    this._fingerprint = null
+  }
+
+  [fingerprintTrait.FingerprintTraitSymbol] () {
+    return this._fingerprint || (this._fingerprint = fingerprintTrait.fingerprint(this.str))
+  }
+}
+
+/*
+ * Delta Diffing approach - optimized for performance and creating readable deltas. You can only
+ * diff insertions (InsertOp & TextOp) not delete ops.
+ *
+ * # Children
+ * Diff content first and then figure out the necessary formatting updates
+ * 1. find common prefix & suffix
+ * 2. slice center to fresh delta. split content by coarse regex ($insert ops are split into
+ * individual items)
+ * 3. patience diff on split content and receive set of splice ops
+ * 4. on each splice op: perform another patience diff with a granular regex on strings
+ * 5. reassemble deltas recursively
+ * 6. apply content diff on original delta and find necessary formatting updates
+ * 7. merge content diff and formatting updates
+ */
+
 /**
+ * @typedef {object} DiffOptions
+ * @property {(d1: DeltaAny, d2: DeltaAny) => boolean} [compare] Predicate deciding when two nodes
+ * are paired into a `modify` (vs. replaced wholesale). Defaults to comparing names
+ * (`(d1, d2) => d1.name === d2.name`). Called as `compare(fromNode, toNode)`.
+ * @property {boolean} [clone=false] By default `diff` does **not** produce a fully fresh delta: wherever
+ * it emits content from `d2` — a wholesale-inserted child node, or a delta-valued attribute — it *shares*
+ * that nested delta by reference, so the result aliases `d2`'s subtrees. Set `true` to
+ * {@link cloneDeep deep-clone} every such delta (children **and** attributes) as it is included in the
+ * output, yielding a result that shares no structure with `d2` (and is safe to hand to something that
+ * manipulates deltas in place, e.g. a transformer).
+ */
+
+/**
+ * Compute a delta that, when applied to `d1`, produces `d2`. Only the children and attributes of
+ * `d1` and `d2` are compared; the top-level node names of `d1` and `d2` are *not*. Diffing
+ * `<div>a</div>` against `<span>a</span>` is valid and yields an empty diff — they have the same
+ * children and attributes, so as far as `diff` is concerned they are equal at the level it cares
+ * about. The top-level name is treated as a document-type marker, not as diffable content.
+ *
+ * Names *are* compared on children: a child node whose name changes between `d1` and `d2` is
+ * replaced wholesale (delete + insert), not converted into a `modify` op. Same-name child nodes
+ * at aligned positions are paired and recursed into via `modify`.
+ *
+ * Pairing is decided by `options.compare`, which defaults to comparing names
+ * (`(d1, d2) => d1.name === d2.name`). Supply a stricter predicate to tighten the granularity —
+ * e.g. to also require their first child to match — in which case nodes that don't satisfy it are
+ * replaced wholesale instead. `options` is forwarded to every child diff, so the chosen granularity
+ * applies consistently all the way down the tree. `compare` is always called as
+ * `compare(fromNode, toNode)` (the node from `d1` first).
+ *
+ * NOTE: `diff` compares **content only** — it short-circuits on the {@link Delta#fingerprint}, which
+ * excludes marks. Two states that differ *only* in their marks diff to an empty change, so cursor marks
+ * do NOT cross a `diff` (e.g. a `Binding`'s initial-state sync). Marks survive on the live
+ * `apply`/`rebase`/transform path; carrying them across a diff-based boundary needs a separate channel.
+ *
  * @template {DeltaConf} Conf
  * @param {Delta<Conf>} d1
  * @param {NoInfer<Delta<Conf>>} d2
- * @return {DeltaBuilder<Conf>}
+ * @param {DiffOptions} [options]
+ * @return {Delta<Conf>}
  */
-export const diff = (d1, d2) => {
-  /**
-   * @type {DeltaBuilderAny}
-   */
-  const d = create()
+export const diff = (d1, d2, options = {}) => {
+  const d = create(d1.name === d2.name ? d1.name : null, $deltaAny)
+  const compare = options?.compare ?? defaultCompare
   if (d1.fingerprint !== d2.fingerprint) {
     /**
      * @type {ChildrenOpAny?}
@@ -2184,6 +3929,8 @@ export const diff = (d1, d2) => {
      * @type {ChildrenOpAny?}
      */
     let right2 = d2.children.end
+    // whether we need to diff formatting
+    let formattingOrAttributionNeedsDiff = false
     let commonPrefixOffset = 0
     // perform a patience sort
     // 1) remove common prefix and suffix
@@ -2194,177 +3941,397 @@ export const diff = (d1, d2) => {
       left1 = left1.next
       left2 = left2.next
     }
-    while (right1 !== null && right1 !== left1 && right1.fingerprint === right2?.fingerprint) {
-      right1 = right1.prev
-      right2 = right2.prev
+    if (left1 !== null && left2 !== null) {
+      while (right1 !== null && right2 !== null && right1 !== left1 && right2 !== left2 && right1.fingerprint === right2.fingerprint) {
+        right1 = right1.prev
+        right2 = right2.prev
+      }
     }
     /**
-     * @type {Array<ChildrenOpAny>}
+     * @type {Array<fingerprintTrait.Fingerprintable>}
      */
-    const ops1 = []
+    const cs1 = []
     /**
-     * @type {Array<ChildrenOpAny>}
+     * @type {Array<fingerprintTrait.Fingerprintable>}
      */
-    const ops2 = []
-    while (left1 !== null && left1 !== right1?.next) {
-      ops1.push(left1)
-      left1 = left1.next
-    }
-    while (left2 !== null && left2 !== right2?.next) {
-      ops2.push(left2)
-      left2 = left2.next
+    const cs2 = []
+    // if right is null, then we already matched everything
+    if (right1 != null) {
+      while (left1 !== null && left1 !== right1.next) {
+        if ($textOp.check(left1)) {
+          cs1.push(left1.insert)
+        } else if ($insertOp.check(left1)) {
+          cs1.push(...left1.insert.map(ins => typeof ins === 'string' ? new _DiffStringWrapper(ins) : ins))
+        } else {
+          throw error.create('[lib0/delta] diffing deletes unsupported')
+        }
+        formattingOrAttributionNeedsDiff ||= left1.format != null || left1.attribution != null
+        left1 = left1.next
+      }
     }
-    const fprints1 = ops1.map(op => op.fingerprint)
-    const fprints2 = ops2.map(op => op.fingerprint)
-    const changeset = patience.diff(fprints1, fprints2)
-    d.retain(commonPrefixOffset)
-    for (let i = 0, lastIndex1 = 0, currIndexOffset2 = 0; i < changeset.length; i++) {
-      const change = changeset[i]
-      d.retain(change.index - lastIndex1)
-      // insert minimal diff at curred position in d
-      /**
-       *
-       * @todo it would be better if these would be slices of delta (an actual delta)
-       *
-       * @param {ChildrenOpAny[]} opsIs
-       * @param {ChildrenOpAny[]} opsShould
-       */
-      const diffAndApply = (opsIs, opsShould) => {
-        const d = create($deltaAny)
-        // @todo unoptimized implementation. Convert content to array and diff that based on
-        // generated fingerprints. We probably could do better and cache more information.
-        // - benchmark
-        // - cache fingerprints in ops
-        /**
-         * @type {Array<string|DeltaAny|fingerprintTrait.Fingerprintable>}
-         */
-        const isContent = opsIs.flatMap(op => $insertOp.check(op) ? op.insert : ($textOp.check(op) ? op.insert.split('') : error.unexpectedCase()))
-        /**
-         * @type {Array<string|DeltaAny|fingerprintTrait.Fingerprintable>}
-         */
-        const shouldContent = opsShould.flatMap(op => $insertOp.check(op) ? op.insert : ($textOp.check(op) ? op.insert.split('') : error.unexpectedCase()))
-        const isContentFingerprinted = isContent.map(c => s.$string.check(c) ? c : fingerprintTrait.fingerprint(c))
-        const shouldContentFingerprinted = shouldContent.map(c => s.$string.check(c) ? c : fingerprintTrait.fingerprint(c))
-        const hasFormatting = opsIs.some(op => !$deleteOp.check(op) && op.format != null) || opsShould.some(op => !$deleteOp.check(op) && op.format != null)
-        /**
-         * @type {{ index: number, insert: Array<string|DeltaAny|fingerprintTrait.Fingerprintable>, remove: Array<string|DeltaAny|fingerprintTrait.Fingerprintable> }[]}
-         */
-        const cdiff = patience.diff(isContentFingerprinted, shouldContentFingerprinted)
-        // overwrite fingerprinted content with actual content
-        for (let i = 0, adj = 0; i < cdiff.length; i++) {
-          const cd = cdiff[i]
-          cd.remove = isContent.slice(cd.index, cd.index + cd.remove.length)
-          cd.insert = shouldContent.slice(cd.index + adj, cd.index + adj + cd.insert.length)
-          adj += cd.insert.length - cd.remove.length
+    if (right2 != null) {
+      while (left2 !== null && left2 !== right2.next) {
+        if ($textOp.check(left2)) {
+          cs2.push(left2.insert)
+        } else if ($insertOp.check(left2)) {
+          cs2.push(...left2.insert.map(ins => typeof ins === 'string' ? new _DiffStringWrapper(ins) : ins))
+        /* c8 ignore start */
+        } else {
+          // unreachable for valid diff inputs (delete on the rhs would already
+          // have been rejected via the `[lib0/delta] diffing deletes unsupported`
+          // path above)
+          error.unexpectedCase()
         }
-        for (let i = 0, lastIndex = 0; i < cdiff.length; i++) {
-          const cd = cdiff[i]
-          d.retain(cd.index - lastIndex)
-          lastIndex = cd.index
-          let cdii = 0
-          let cdri = 0
-          // try to match as much content as possible, preferring to skip over non-deltas
-          for (; cdii < cd.insert.length && cdri < cd.remove.length;) {
-            const a = cd.insert[cdii]
-            const b = cd.remove[cdri]
-            if ($deltaAny.check(a) && $deltaAny.check(b) && a.name === b.name) {
-              d.modify(diff(b, a))
-              cdii++
-              cdri++
-            } else if ($deltaAny.check(b)) {
-              d.insert(s.$string.check(a) ? a : [a])
-              cdii++
-            } else {
-              d.delete(1)
-              cdri++
-            }
+        /* c8 ignore stop */
+        formattingOrAttributionNeedsDiff ||= left2.format != null || left2.attribution != null
+        left2 = left2.next
+      }
+    }
+    const changeset1 = [{
+      index: commonPrefixOffset,
+      insert: cs2,
+      remove: cs1
+    }]
+    // split by line
+    const changeset2 = diffChangesetWithSeparator(changeset1, /[\n]+/g)
+    // split by alphanumerics and others
+    const changeset3 = diffChangesetWithSeparator(changeset2, patience.smartSplitRegex)
+    // split all
+    const changeset4 = diffChangesetWithSeparator(changeset3, /./g)
+    applyChangesetToDelta(d, changeset4, compare, options)
+    if (formattingOrAttributionNeedsDiff) {
+      const formattingDiff = create()
+      // update opsIs with content diff. then we can figure out the formatting diff.
+      const originalUpdated = clone(d1)
+      originalUpdated.apply(/** @type {DeltaAny} */ (d))
+      let bOffset = 0
+      // update a to match b
+      let a = /** @type {InsertOp<any>|TextOp|null} */ (originalUpdated.children.start)
+      let b = /** @type {InsertOp<any>|TextOp|null} */ (d2.children.start)
+      let aOffset = 0
+      while (a != null && b != null) {
+        if (!$deleteOp.check(b) && !$deleteOp.check(a)) {
+          const aFormat = a.format
+          const bFormat = b.format
+          const minForward = math.min(b.length - bOffset, a.length - aOffset)
+          aOffset += minForward
+          bOffset += minForward
+          // format and attribution diff identically (unified tri-state — see diffDim):
+          // undefined = unchanged (skip), null = cleared, else a per-key `{k:v}`/`{k:null}` update
+          const fupdate = diffDim(aFormat, bFormat, false)
+          const attributionUpdate = diffDim(a.attribution, b.attribution, true)
+          if (fupdate === undefined && attributionUpdate === undefined) {
+            formattingDiff.retain(minForward)
+          } else {
+            formattingDiff.retain(minForward, fupdate, attributionUpdate)
           }
-          for (; cdii < cd.insert.length; cdii++) {
-            const a = cd.insert[cdii]
-            d.insert(s.$string.check(a) ? a : [a])
+          // update offset and iterators
+          if (bOffset >= b.length) {
+            b = b.next
+            bOffset = 0
           }
-          d.delete(cd.remove.length - cdri)
-        }
-        // create the diff for formatting
-        if (hasFormatting) {
-          const formattingDiff = create()
-          // update opsIs with content diff. then we can figure out the formatting diff.
-          const isUpdated = create($deltaAny)
-          // copy opsIs to fresh delta
-          opsIs.forEach(op => {
-            isUpdated.childCnt += op.length
-            list.pushEnd(isUpdated.children, op.clone())
-          })
-          isUpdated.apply(d)
-          let shouldI = 0
-          let shouldOffset = 0
-          let isOp = isUpdated.children.start
-          let isOffset = 0
-          while (shouldI < opsShould.length && isOp != null) {
-            const shouldOp = opsShould[shouldI]
-            if (!$deleteOp.check(shouldOp) && !$deleteOp.check(isOp)) {
-              const isFormat = isOp.format
-              const minForward = math.min(shouldOp.length - shouldOffset, isOp.length - isOffset)
-              shouldOffset += minForward
-              isOffset += minForward
-              if (fun.equalityDeep(shouldOp.format, isFormat)) {
-                formattingDiff.retain(minForward)
-              } else {
-                /**
-                 * @type {FormattingAttributes}
-                 */
-                const fupdate = {}
-                shouldOp.format != null && object.forEach(shouldOp.format, (v, k) => {
-                  if (!fun.equalityDeep(v, isFormat?.[k] || null)) {
-                    fupdate[k] = v
-                  }
-                })
-                isFormat && object.forEach(isFormat, (_, k) => {
-                  if (shouldOp?.format?.[k] === undefined) {
-                    fupdate[k] = null
-                  }
-                })
-                formattingDiff.retain(minForward, fupdate)
-              }
-              // update offset and iterators
-              if (shouldOffset >= shouldOp.length) {
-                shouldI++
-                shouldOffset = 0
-              }
-              if (isOffset >= isOp.length) {
-                isOp = isOp.next
-                isOffset = 0
-              }
-            }
+          if (aOffset >= a.length) {
+            a = a.next
+            aOffset = 0
           }
-          d.apply(formattingDiff)
+        /* c8 ignore start */
+        } else {
+          // unreachable: by this point both a and b are insert/text (deletes
+          // were rejected upstream and `originalUpdated` is the result of an
+          // apply, which keeps inserts only).
+          error.unexpectedCase()
         }
-        return d
+        /* c8 ignore stop */
       }
-      const subd = diffAndApply(ops1.slice(change.index, change.index + change.remove.length), ops2.slice(change.index + currIndexOffset2, change.index + currIndexOffset2 + change.insert.length))
-      d.append(subd)
-      lastIndex1 = change.index + change.remove.length
-      currIndexOffset2 += change.insert.length - change.remove.length
+      // @todo instead of applying, we want to first exec d, then formattingDiff - we need a merge
+      // function!
+      d.apply(formattingDiff)
     }
     for (const attr2 of d2.attrs) {
+      const key = attr2.key
       // @ts-ignore
-      const attr1 = d1.attrs[attr2.key]
+      const attr1 = d1.attrs[key]
       if (attr1 == null || (attr1.fingerprint !== attr2.fingerprint)) {
         /* c8 ignore else */
         if ($setAttrOp.check(attr2)) {
-          d.setAttr(attr2.key, attr2.value)
+          const prevVal = attr1?.value
+          const nextVal = attr2.value
+          if ($deltaAny.check(prevVal) && $deltaAny.check(nextVal) && compare(prevVal, nextVal)) {
+            // modifyAttr carries the *incremental* attribution update (apply merges it onto the target attr
+            // op's attribution); the inner diff updates its value.
+            // reason: diffDim returns an opaque update (a `{k:null}` removal isn't a canonical Attribution),
+            // while modifyAttr's param is typed Attribution for API ergonomics
+            d.modifyAttr(key, diff(prevVal, nextVal, options), /** @type {Attribution|null|undefined} */ (diffDim(attr1?.attribution, attr2.attribution, true)))
+          } else {
+            // setAttr replaces the whole attr, so it carries the new attribution as data (object-or-none).
+            // `nextVal` is shared from `d2`; deep-clone it when the caller wants an independent result.
+            d.setAttr(key, options.clone ? _cloneMaybeDeltaDeep(nextVal) : nextVal, attr2.attribution)
+          }
+        /* c8 ignore start */
         } else {
-          /* c8 ignore next 2 */
           error.unexpectedCase()
         }
+        /* c8 ignore stop */
       }
     }
-    for (const attr1 of d1.attrs) {
+    for (const { key } of d1.attrs) {
       // @ts-ignore
-      if (d2.attrs[attr1.key] == null) {
-        d.deleteAttr(attr1.key)
+      if (d2.attrs[key] == null) {
+        d.deleteAttr(key)
       }
     }
   }
-  return /** @type {any} */ (d.done(false))
+  return d.done(false)
+}
+
+/**
+ * The tri-state update that undoes a `format`/`attribution` instruction `update` against the stored
+ * value `stored` (object or `null`/none) it was applied to: applying the result after `update` restores
+ * `stored`. Merge the instruction onto `stored` the way an apply resolves it ({@link applyDim}), then
+ * diff the merged result back to `stored` ({@link diffDim}). `undefined` (skip) inverts to `undefined`.
+ *
+ * @param {{[k:string]:any}|null|undefined} stored
+ * @param {{[k:string]:any}|null|undefined} update
+ * @param {boolean} deep `true` for the `attribution` dimension (its `format` key merges per inner key —
+ *   see {@link mergeAttr}); `false` for `format` (shallow)
+ * @return {{[k:string]:any}|null|undefined}
+ */
+const inverseDim = (stored, update, deep) => {
+  if (update === undefined) return undefined
+  const merged = update === null ? null : (deep ? mergeAttr(stored, update, true) : mergeShallow(stored, update, true))
+  return diffDim(object.isEmpty(merged) ? null : merged, stored ?? null, deep)
+}
+
+/**
+ * Compute a delta that undoes `d` — a change that was applied to the settled document state `base`
+ * (inserts and set attributes only, e.g. an RDT's final state): `base.apply(d).apply(inverse(d, base))`
+ * equals `base`. Inspired by Quill's `Delta#invert`, `base` supplies what the change alone doesn't
+ * carry: deleted content is re-inserted from `base` (with its stored format/attribution), an
+ * overwritten or deleted attribute is restored to its `base` value, and an inverted `retain`/`modify`
+ * instruction is diffed against the `base` op's stored format/attribution.
+ *
+ * Content only: marks are local/ephemeral cursor state and are not inverted (mirroring {@link diff}).
+ * Like {@link diff}, the result *shares* re-inserted children and restored attribute values with `base`.
+ *
+ * The round-trip holds for changes whose content-consuming ops (`retain`/`delete`/`modify`) stay within
+ * `base`'s bounds. Beyond-base ops degrade gracefully: following ops stay positioned, but there is no
+ * stored content to restore — and what a final apply *materializes* beyond content (e.g. a format set
+ * kept as a trailing formatted retain, or an appended modify) cannot be removed by any change, so such
+ * a change is not fully undone.
+ *
+ * @template {DeltaConf} Conf
+ * @param {DeltaAny} d
+ * @param {Delta<Conf>} base
+ * @return {Delta<Conf>}
+ */
+export const inverse = (d, base) => {
+  const inv = create(d.name === base.name ? d.name : null, $deltaAny)
+  for (const op of d.attrs) {
+    const baseOp = /** @type {AttrOpAny|undefined} */ ((/** @type {any} */ (base.attrs))[op.key])
+    if ($modifyAttrOp.check(op) && $setAttrOp.check(baseOp) && $deltaAny.check(baseOp.value)) {
+      // the modify edited base's nested delta in place: undo it there, and undo the attribution
+      // instruction it merged onto the attr op
+      inv.modifyAttr(op.key, inverse(op.value, baseOp.value), /** @type {Attribution?} */ (inverseDim(baseOp.attribution, op.attribution, true)))
+    } else if ($setAttrOp.check(baseOp)) {
+      // a set/delete (or a modify that replaced a non-delta value) overwrote a settled attr:
+      // restore value + attribution from base
+      inv.setAttr(op.key, baseOp.value, baseOp.attribution)
+    } else if (!$deleteAttrOp.check(op)) {
+      // a set/modify introduced an attr base didn't have: undo by deleting it
+      inv.deleteAttr(op.key)
+    } // else: deleted an attr base didn't have — nothing to restore
+  }
+  // walk base's children alongside d's ops: an insert consumes no base positions; retain/delete/modify
+  // consume their length in base coordinates
+  let baseOp = /** @type {ChildrenOpAny?} */ (base.children.start)
+  let baseOffset = 0
+  /**
+   * Advance the base cursor by `len`, reporting each traversed chunk `(op, start, end)` (stored
+   * format/attribution are uniform per op, so per-op chunks are exact); returns the length that
+   * extends beyond base's content.
+   *
+   * @param {number} len
+   * @param {(op: TextOp|InsertOp<any>, start: number, end: number) => void} f
+   */
+  const forBase = (len, f) => {
+    while (len > 0 && baseOp != null) {
+      const chunk = math.min(len, baseOp.length - baseOffset)
+      f(/** @type {TextOp|InsertOp<any>} */ (baseOp), baseOffset, baseOffset + chunk)
+      len -= chunk
+      baseOffset += chunk
+      if (baseOffset === baseOp.length) {
+        baseOp = baseOp.next
+        baseOffset = 0
+      }
+    }
+    return len
+  }
+  for (const op of d.children) {
+    if ($textOp.check(op) || $insertOp.check(op)) {
+      inv.delete(op.length)
+    } else if ($retainOp.check(op)) {
+      const rest = forBase(op.retain, (bop, start, end) => {
+        inv.retain(end - start, inverseDim(bop.format, op.format, false), /** @type {Attribution?} */ (inverseDim(bop.attribution, op.attribution, true)))
+      })
+      // beyond base there is no stored content to restore — keep following ops positioned (see the
+      // beyond-base note in the fn docs)
+      rest > 0 && inv.retain(rest)
+    } else if ($modifyOp.check(op)) {
+      if (baseOp == null) {
+        // a modify beyond base edited no stored content — keep the position (mirrors retain-beyond)
+        inv.retain(1)
+      } else {
+        const bop = /** @type {InsertOp<any>} */ (baseOp)
+        const node = /** @type {DeltaAny} */ (bop.insert[baseOffset])
+        inv.modify(inverse(/** @type {DeltaAny} */ (op.value), node), inverseDim(bop.format, op.format, false), /** @type {Attribution?} */ (inverseDim(bop.attribution, op.attribution, true)))
+        forBase(1, () => {})
+      }
+    } else if ($deleteOp.check(op)) {
+      // re-insert the deleted base content with its stored format/attribution
+      forBase(op.delete, (bop, start, end) => {
+        inv.insert(bop.insert.slice(start, end), bop.format, bop.attribution)
+      })
+    }
+  }
+  return inv.done(false)
+}
+
+/**
+ * Default pairing predicate for {@link diff}: two delta nodes are paired (and recursed into via
+ * `modify`) when their names match.
+ *
+ * @param {DeltaAny} d1
+ * @param {DeltaAny} d2
+ */
+const defaultCompare = (d1, d2) => d1.name === d2.name
+
+/**
+ * @param {string|any} c
+ */
+const contentLen = c => typeof c === 'string' ? c.length : 1
+
+/**
+ * Apply removes from c.remove to d, mutating c.remove to exclude the applied items
+ *
+ * @param {DeltaBuilderAny} d
+ * @param {Array<any>} crem
+ * @param {number} len
+ */
+const applyRemoves = (d, crem, len) => { len > 0 && d.delete(crem.splice(0, len).map(contentLen).reduce(math.add, 0)) }
+/**
+ * Apply inserts from c.insert to d, mutating c.insert to exclude the applied items. A wholesale-inserted
+ * child is a nested delta shared from `d2`; deep-clone it when `cloneChildren` (the diff's `clone` option)
+ * so the result aliases nothing in `d2` (see {@link DiffOptions}).
+ *
+ * @param {DeltaBuilderAny} d
+ * @param {Array<any>} cins
+ * @param {number} len
+ * @param {boolean} [cloneChildren]
+ */
+const applyInserts = (d, cins, len, cloneChildren) => { len > 0 && cins.splice(0, len).forEach(ins => d.insert(typeof ins === 'string' ? ins : [ins instanceof _DiffStringWrapper ? ins.str : (cloneChildren ? _cloneMaybeDeltaDeep(ins) : ins)])) }
+
+/**
+ * @param {DeltaBuilderAny} d
+ * @param {Array<{ index: number, remove: Array<any>, insert: Array<any> }>} changeset
+ * @param {(d1: DeltaAny, d2: DeltaAny) => boolean} compare
+ * @param {DiffOptions} options
+ */
+const applyChangesetToDelta = (d, changeset, compare, options) => {
+  for (let ci = 0, lastIndex = 0; ci < changeset.length; ci++) {
+    const c = changeset[ci]
+    d.retain(c.index - lastIndex)
+    lastIndex = c.index + c.remove.map(contentLen).reduce(math.add, 0)
+    // @todo do patience diff on the delta-names, then perform maximum number of mods instead of
+    // insert/delete
+    while (true) {
+      const cremoveDeltaIndex = c.remove.findIndex(cc => $deltaAny.check(cc))
+      if (cremoveDeltaIndex < 0) break
+      const cremoveDelta = c.remove[cremoveDeltaIndex]
+      const cinsertDeltaIndex = c.insert.findIndex(cc => $deltaAny.check(cc) && compare(cremoveDelta, cc))
+      if (cinsertDeltaIndex < 0) {
+        applyRemoves(d, c.remove, cremoveDeltaIndex + 1)
+        continue
+      }
+      applyRemoves(d, c.remove, cremoveDeltaIndex)
+      applyInserts(d, c.insert, cinsertDeltaIndex, options.clone)
+      d.modify(diff(c.remove[0], c.insert[0], options))
+      c.remove.splice(0, 1)
+      c.insert.splice(0, 1)
+    }
+    applyRemoves(d, c.remove, c.remove.length)
+    applyInserts(d, c.insert, c.insert.length, options.clone)
+  }
+  return d
+}
+
+/**
+ * @param {Array<{ index: number, remove: Array<any>, insert: Array<any> }>} changeset
+ * @param {RegExp} separator
+ */
+export const diffChangesetWithSeparator = (changeset, separator) => {
+  /**
+   * @type {Array<any>}
+   */
+  const next = []
+  changeset.forEach(change => {
+    // @todo actually split here
+    const cs1 = splitContentArrayByRegexp(change.remove, separator)
+    const cs2 = splitContentArrayByRegexp(change.insert, separator)
+    const fp1 = cs1.map(c => typeof c === 'string' ? c : fingerprintTrait.fingerprint(c))
+    const fp2 = cs2.map(c => typeof c === 'string' ? c : fingerprintTrait.fingerprint(c))
+    const changesetF = patience.diff(fp1, fp2)
+    const nextChangeset = fillFingerprintDiffFromContent(changesetF, cs1, cs2)
+    let prevDiffIndex = 0
+    let nextChangeIndex = change.index
+    // adjust indexes for actual content length and add results to `next`
+    nextChangeset.forEach(c => {
+      // adjust equal content
+      for (; prevDiffIndex < c.index; prevDiffIndex += 1) {
+        nextChangeIndex += contentLen(cs1[prevDiffIndex])
+      }
+      // need to adjust index with the actual length of the previous items
+      c.index = nextChangeIndex
+      next.push(c)
+    })
+  })
+  return next
+}
+
+/**
+ * @param {Array<any>} cs
+ * @param {RegExp} regexp
+ */
+const splitContentArrayByRegexp = (cs, regexp) => {
+  /**
+   * @type {Array<any>}
+   */
+  const res = []
+  cs.forEach(c => {
+    if (typeof c === 'string') {
+      res.push(...patience.splitByRegexp(c, regexp, true))
+    } else {
+      res.push(c)
+    }
+  })
+  return res
+}
+
+/**
+ * @template C
+ * @param {Array<{ index: number, remove: Array<string>, insert: Array<string> }>} changeset
+ * @param {Array<C>} is
+ * @param {Array<C>} should
+ * @return {Array<{ index: number, remove: Array<C>, insert: Array<C> }>}
+ */
+const fillFingerprintDiffFromContent = (changeset, is, should) => {
+  // overwrite fingerprinted content with actual content
+  for (let i = 0, adj = 0; i < changeset.length; i++) {
+    const cd = changeset[i]
+    // @ts-ignore
+    cd.remove = is.slice(cd.index, cd.index + cd.remove.length)
+    // @ts-ignore
+    cd.insert = should.slice(cd.index + adj, cd.index + adj + cd.insert.length)
+    adj += cd.insert.length - cd.remove.length
+  }
+  return /** @type {any} */ (changeset)
 }