lib0 1.0.0-rc.19 → 1.0.0-rc.20

package/dist/delta/delta.d.ts

@@ -631,6 +631,7 @@ export class Delta<Conf extends DeltaConf = {}> extends DeltaData<DeltaConfGetNa
 }
 export function slice<Conf_1 extends DeltaConf>(d: Delta<Conf_1>, start?: number, end?: number, currNode?: ChildrenOpAny | null): DeltaBuilder<Conf_1>;
 export function clone<D extends DeltaAny>(d: D): D extends Delta<infer Conf_1> ? DeltaBuilder<Conf_1> : never;
+export function cloneDeep<Conf_1 extends DeltaConf>(d: Delta<Conf_1>): DeltaBuilder<Conf_1>;
 export function cloneShallow<D extends DeltaAny>(d: D): D extends Delta<infer Conf_1> ? DeltaBuilder<Conf_1> : never;
 export function _mergeChildWithPrev(d: DeltaBuilderAny, op: InsertOp<any> | RetainOp | DeleteOp<any> | TextOp | ModifyOp<any>): boolean;
 export function _splitChildAt(d: DeltaBuilderAny, op: ChildrenOpAny, offset: number): ChildrenOpAny;
@@ -1244,6 +1245,15 @@ export type DiffOptions = {
      * (`(d1, d2) => d1.name === d2.name`). Called as `compare(fromNode, toNode)`.
      */
     compare?: ((d1: DeltaAny, d2: DeltaAny) => boolean) | undefined;
+    /**
+     * 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).
+     */
+    clone?: boolean | undefined;
 };
 import * as s from '../schema.js';
 import * as list from '../list.js';

package/dist/delta/rdt/delta.d.ts

@@ -1,32 +1,32 @@
-export function deltaRDT<D extends delta.DeltaAny>($delta: Schema<D>): DeltaRDT<D>;
+export function deltaRDT<Conf extends delta.DeltaConf>($delta: Schema<delta.Delta<Conf>>): DeltaRDT<Conf>;
 export type Schema<T> = import("../../schema.js").Schema<T>;
-export type RDT<D extends delta.DeltaAny> = import("../rdt.js").RDT<D>;
+export type RDT<Conf extends delta.DeltaConf> = import("../rdt.js").RDT<Conf>;
 import * as delta from '../delta.js';
 /**
  * @template T
  * @typedef {import('../../schema.js').Schema<T>} Schema
  */
 /**
- * @template {delta.DeltaAny} D
- * @typedef {import('../rdt.js').RDT<D>} RDT
+ * @template {delta.DeltaConf} Conf
+ * @typedef {import('../rdt.js').RDT<Conf>} RDT
  */
 /**
  * An in-memory RDT whose state is the accumulated delta. Calling `applyDelta` merges the incoming delta
  * into `state` (via {@link delta.DeltaBuilder#apply}) and re-emits it as a `'delta'`.
  *
- * @template {delta.DeltaAny} D
- * @implements {RDT<D>}
- * @extends {ObservableV2<{ delta: (delta: D) => void, destroy: (rdt: DeltaRDT<D>) => void }>}
+ * @template {delta.DeltaConf} Conf
+ * @implements {RDT<Conf>}
+ * @extends {ObservableV2<{ delta: (delta: delta.Delta<Conf>, origin: any) => void, destroy: (rdt: DeltaRDT<Conf>) => void }>}
  */
-declare class DeltaRDT<D extends delta.DeltaAny> extends ObservableV2<{
-    delta: (delta: D) => void;
-    destroy: (rdt: DeltaRDT<D>) => void;
-}> implements RDT<D> {
+declare class DeltaRDT<Conf extends delta.DeltaConf> extends ObservableV2<{
+    delta: (delta: delta.Delta<Conf>, origin: any) => void;
+    destroy: (rdt: DeltaRDT<Conf>) => void;
+}> implements RDT<Conf> {
     /**
-     * @param {Schema<D>} $delta schema of the deltas this RDT produces
+     * @param {Schema<delta.Delta<Conf>>} $delta schema of the deltas this RDT produces
      */
-    constructor($delta: Schema<D>);
-    $delta: import("../../schema.js").Schema<D>;
+    constructor($delta: Schema<delta.Delta<Conf>>);
+    $delta: import("../../schema.js").Schema<delta.Delta<Conf>>;
     /**
      * @type {delta.DeltaBuilderAny?}
      */
@@ -36,17 +36,20 @@ declare class DeltaRDT<D extends delta.DeltaAny> extends ObservableV2<{
      * Merge an incoming delta into the current state and notify observers. Always returns `null`: this
      * RDT accepts every valid delta unchanged, so it never produces a fix.
      *
-     * @param {D} d
+     * @param {delta.Delta<Conf>} d
+     * @param {any} [origin] who produced the change; forwarded verbatim on the emitted `'delta'` event so
+     * listeners can recognise (and skip) changes they made themselves — see {@link RDT} “Origins”. Defaults
+     * to `null` (an anonymous/local change).
      * @return {null}
      */
-    applyDelta(d: D): null;
+    applyDelta(d: delta.Delta<Conf>, origin?: any): null;
     /**
      * The current state as a delta: the accumulated `state`, or an empty delta when nothing has been
      * applied yet.
      *
-     * @return {D}
+     * @return {delta.Delta<Conf>}
      */
-    get delta(): D;
+    get delta(): delta.Delta<Conf>;
 }
 import { ObservableV2 } from '../../observable.js';
 import * as mux from '../../mutex.js';

package/dist/delta/rdt/dom.d.ts

@@ -10,42 +10,50 @@ export const $domDelta: s.Schema<delta.Delta<{
     text: true;
     recursiveChildren: true;
 }>>;
-export function domRDT(dom: Element): DomRDT<DomDelta>;
+export function domRDT(dom: Element): DomRDT;
 export type Schema<T> = import("../../schema.js").Schema<T>;
-export type RDT<D extends delta.DeltaAny> = import("../rdt.js").RDT<D>;
-export type DomDelta = delta.Delta<{
+export type RDT<Conf extends delta.DeltaConf> = import("../rdt.js").RDT<Conf>;
+/**
+ * The {@link delta.DeltaConf} of the deltas a {@link DomRDT} produces/consumes (see {@link $domDelta}).
+ */
+export type DomConf = {
     name: string;
     attrs: {
         [key: string]: string;
     };
     text: true;
     recursiveChildren: true;
-}>;
+};
+export type DomDelta = delta.Delta<DomConf>;
 import * as delta from '../delta.js';
 import * as s from '../../schema.js';
 /**
- * @typedef {delta.Delta<{ name: string, attrs: { [key:string]: string }, text: true, recursiveChildren: true }>} DomDelta
+ * The {@link delta.DeltaConf} of the deltas a {@link DomRDT} produces/consumes (see {@link $domDelta}).
+ *
+ * @typedef {{ name: string, attrs: { [key:string]: string }, text: true, recursiveChildren: true }} DomConf
+ */
+/**
+ * @typedef {delta.Delta<DomConf>} DomDelta
  */
 /**
  * An RDT backed by a live DOM subtree. DOM mutations observed via `MutationObserver` are diffed
  * against the last-known state and emitted as deltas; incoming deltas are applied back onto the DOM.
  *
- * @template {DomDelta} [D=DomDelta]
- * @implements {RDT<D>}
- * @extends {ObservableV2<{ delta: (delta: D) => void, destroy: (rdt: DomRDT<D>) => void }>}
+ * @implements {RDT<DomConf>}
+ * @extends {ObservableV2<{ delta: (delta: delta.Delta<DomConf>, origin: any) => void, destroy: (rdt: DomRDT) => void }>}
  */
-declare class DomRDT<D extends DomDelta = DomDelta> extends ObservableV2<{
-    delta: (delta: D) => void;
-    destroy: (rdt: DomRDT<D>) => void;
-}> implements RDT<D> {
+declare class DomRDT extends ObservableV2<{
+    delta: (delta: delta.Delta<DomConf>, origin: any) => void;
+    destroy: (rdt: DomRDT) => void;
+}> implements RDT<DomConf> {
     /**
      * @param {Element} observedNode
      */
     constructor(observedNode: Element);
     /**
-     * @type {Schema<D>}
+     * @type {Schema<DomDelta>}
      */
-    $delta: Schema<D>;
+    $delta: Schema<DomDelta>;
     observedNode: Element;
     /**
      * Last-known DOM state. The observe path diffs the live DOM against this to compute the change to
@@ -74,16 +82,20 @@ declare class DomRDT<D extends DomDelta = DomDelta> extends ObservableV2<{
      * `d` rebased onto `b` is applied to the DOM, and `b` rebased onto `d` is returned as the fix so the
      * binding pipes it back through the transformer to the other side.
      *
-     * @param {D} d
-     * @return {D | null} the rebased local change (`b`), or `null` when there were no concurrent edits
+     * @param {delta.Delta<DomConf>} d
+     * @param {any} [origin] who produced `d`; forwarded verbatim on the emitted `'delta'` event so
+     * listeners can recognise (and skip) their own changes — see {@link RDT} “Origins”. Defaults to `null`
+     * (an anonymous/local change).
+     * @return {delta.DeltaBuilder<DomConf> | null} the rebased local change (`b`), or `null` when there
+     * were no concurrent edits
      */
-    applyDelta(d: D): D | null;
+    applyDelta(d: delta.Delta<DomConf>, origin?: any): delta.DeltaBuilder<DomConf> | null;
     /**
      * The current state as a delta: an "insert everything" delta describing the observed subtree.
      *
-     * @return {D}
+     * @return {delta.Delta<DomConf>}
      */
-    get delta(): D;
+    get delta(): delta.Delta<DomConf>;
 }
 import { ObservableV2 } from '../../observable.js';
 export {};

package/dist/delta/rdt.d.ts

@@ -11,17 +11,45 @@ export { deltaRDT } from "./rdt/delta.js";
  * transformer for it), exposes its current state as a delta via the `delta` getter, and accepts foreign
  * deltas via `applyDelta`.
  *
- * `applyDelta(d)` applies `d` and then, if the change would violate the RDT's own invariants, applies
- * a **fix** of its own (e.g. reversing part of `d`, or inserting missing content) and returns that fix
- * — `null` when none was needed. The fix is a regular change on this RDT, so a {@link Binding} maps it
- * onto the other side just like any other change. `applyDelta` also emits the *effective* change
+ * `applyDelta(d, origin)` applies `d` and then, if the change would violate the RDT's own invariants,
+ * applies a **fix** of its own (e.g. reversing part of `d`, or inserting missing content) and returns
+ * that fix — `null` when none was needed. The fix is a regular change on this RDT, so a {@link Binding}
+ * maps it onto the other side just like any other change. `applyDelta` also emits the *effective* change
  * (`d` together with the fix) on the `'delta'` channel.
  *
- * @template {import('./delta.js').DeltaAny} D
- * @typedef {import('../observable.js').ObservableV2<{ delta: (delta: D) => void, destroy: (rdt: RDT<D>) => void }> & {
- *   $delta: Schema<D>,
- *   delta: D,
- *   applyDelta: (delta: D) => D | null,
+ * ## Origins
+ *
+ * Every `'delta'` event carries a second argument, `origin` — an opaque `any` value (modelled after
+ * {@link https://docs.yjs.dev/api/transactions Yjs transaction origins}) that identifies **where the
+ * change came from**. Whoever produces the change sets it, and it is usually the producing instance
+ * itself: a communication provider, an editor binding, or the {@link Binding} that mapped the change
+ * over from the other side. A change an RDT observes locally (e.g. a `MutationObserver` firing on a DOM
+ * edit) uses that RDT itself as the origin.
+ *
+ * Origins let a listener tell **its own** changes apart from foreign ones so it can skip the ones it
+ * already knows about — a change it produced is not looped back to where it came from. The canonical use
+ * is a network provider: it tags every remote update it applies with itself (`rdt.applyDelta(update,
+ * this)`) and then ignores `'delta'` events whose `origin === this`, so it never re-broadcasts an update
+ * it just received. The `origin` argument to `applyDelta` is optional and defaults to `null` (an
+ * anonymous/local change); the emitted event always carries whatever value was supplied.
+ *
+ * ## `Delta` vs `DeltaBuilder`
+ *
+ * The interface is parameterized by a {@link import('./delta.js').DeltaConf DeltaConf} (like a
+ * {@link import('./transformer.js').Transformer transformer}). Almost everything it exposes is the
+ * *read* form — {@link import('./delta.js').Delta Delta} — because those values are **shared** and must
+ * not be mutated in place: `$delta` is the delta schema, the `delta` getter returns a state snapshot,
+ * `applyDelta` reads a change into the RDT, and the `'delta'` event payload is broadcast to every
+ * listener. The one *owned, mutable* form — {@link import('./delta.js').DeltaBuilder DeltaBuilder} — is
+ * the fix `applyDelta` returns to the {@link Binding}. The binding never mutates a shared read delta: it
+ * {@link import('./delta.js').cloneDeep deep-clones} every change into a private builder before the
+ * transformer rebases it (transformers manipulate deltas in place — see {@link Binding}).
+ *
+ * @template {import('./delta.js').DeltaConf} Conf
+ * @typedef {import('../observable.js').ObservableV2<{ delta: (delta: delta.Delta<Conf>, origin: any) => void, destroy: (rdt: RDT<Conf>) => void }> & {
+ *   $delta: Schema<delta.Delta<Conf>>,
+ *   delta: delta.Delta<Conf>,
+ *   applyDelta: (delta: delta.Delta<Conf>, origin?: any) => delta.DeltaBuilder<Conf> | null,
  *   destroy: () => void
  * }} RDT
  */
@@ -37,31 +65,39 @@ export const $rdt: Schema<RDT<any>>;
 /**
  * Connects two RDTs so that changes on either side are transformed and reflected on the other.
  *
- * @template {import('./delta.js').DeltaAny} DeltaA
+ * The {@link dt.Transformer transformer} it drives **manipulates deltas in place** (it splices op lists
+ * and rebases nodes directly, rather than only via `apply`/`rebase`) — a deliberate exception to the
+ * general rule that deltas are edited through `apply`/`rebase`. Consequently every change handed to it
+ * must be a privately-owned, fully-mutable delta, so the binding {@link delta.cloneDeep deep-clones}
+ * each incoming change (which is a shared read delta — an event payload or a snapshot) before the
+ * transformer touches it. See the initial-state sync below and {@link propagate}.
+ *
+ * @template {delta.DeltaConf} A
+ * @template {delta.DeltaConf} B
  */
-export class Binding<DeltaA extends import("./delta.js").DeltaAny> {
+export class Binding<A extends delta.DeltaConf, B extends delta.DeltaConf> {
     /**
-     * @param {RDT<DeltaA>} a
-     * @param {RDT<import('./delta.js').DeltaAny>} b
-     * @param {dt.TemplateFactory<any,any>} [template] a `$d => Template` factory; defaults to the
+     * @param {RDT<A>} a
+     * @param {RDT<B>} b
+     * @param {dt.TemplateFactory<A,B>} [template] a `$d => Template` factory; defaults to the
      * {@link dt.id identity} transformer. `bind` injects `a`'s schema, then materializes via `.init()`.
      */
-    constructor(a: RDT<DeltaA>, b: RDT<import("./delta.js").DeltaAny>, template?: dt.TemplateFactory<any, any>);
+    constructor(a: RDT<A>, b: RDT<B>, template?: dt.TemplateFactory<A, B>);
     /**
-     * @type {dt.Transformer<any,any>}
+     * @type {dt.Transformer<A,B>}
      */
-    t: dt.Transformer<any, any>;
+    t: dt.Transformer<A, B>;
     /**
-     * @type {RDT<any>}
+     * @type {RDT<A>}
      */
-    a: RDT<any>;
+    a: RDT<A>;
     /**
-     * @type {RDT<any>}
+     * @type {RDT<B>}
      */
-    b: RDT<any>;
+    b: RDT<B>;
     _mux: mux.mutex;
-    _achanged: (delta: any) => void;
-    _bchanged: (delta: any) => void;
+    _achanged: (delta: delta.Delta<A>, origin: any) => void;
+    _bchanged: (delta: delta.Delta<B>, origin: any) => void;
     /**
      * Tear the binding down: unsubscribe both sides' `'delta'` and `'destroy'` listeners so changes are no
      * longer propagated. Call this when you no longer need the two RDTs kept in sync. It is also invoked
@@ -69,7 +105,7 @@ export class Binding<DeltaA extends import("./delta.js").DeltaAny> {
      */
     destroy: () => void;
 }
-export function bind<DeltaA extends import("./delta.js").DeltaAny>(a: RDT<DeltaA>, b: RDT<import("./delta.js").DeltaAny>, template?: dt.TemplateFactory<any, any>): Binding<DeltaA>;
+export function bind<A extends delta.DeltaConf, B extends delta.DeltaConf>(a: RDT<A>, b: RDT<B>, template?: dt.TemplateFactory<A, B>): Binding<A, B>;
 export type Schema<T> = import("../schema.js").Schema<T>;
 /**
  * Abstract interface for a delta-based Replicated Data Type.
@@ -79,21 +115,50 @@ export type Schema<T> = import("../schema.js").Schema<T>;
  * transformer for it), exposes its current state as a delta via the `delta` getter, and accepts foreign
  * deltas via `applyDelta`.
  *
- * `applyDelta(d)` applies `d` and then, if the change would violate the RDT's own invariants, applies
- * a **fix** of its own (e.g. reversing part of `d`, or inserting missing content) and returns that fix
- * — `null` when none was needed. The fix is a regular change on this RDT, so a {@link Binding} maps it
- * onto the other side just like any other change. `applyDelta` also emits the *effective* change
+ * `applyDelta(d, origin)` applies `d` and then, if the change would violate the RDT's own invariants,
+ * applies a **fix** of its own (e.g. reversing part of `d`, or inserting missing content) and returns
+ * that fix — `null` when none was needed. The fix is a regular change on this RDT, so a {@link Binding}
+ * maps it onto the other side just like any other change. `applyDelta` also emits the *effective* change
  * (`d` together with the fix) on the `'delta'` channel.
+ *
+ * ## Origins
+ *
+ * Every `'delta'` event carries a second argument, `origin` — an opaque `any` value (modelled after
+ * {@link https://docs.yjs.dev/api/transactions Yjs transaction origins}) that identifies **where the
+ * change came from**. Whoever produces the change sets it, and it is usually the producing instance
+ * itself: a communication provider, an editor binding, or the {@link Binding} that mapped the change
+ * over from the other side. A change an RDT observes locally (e.g. a `MutationObserver` firing on a DOM
+ * edit) uses that RDT itself as the origin.
+ *
+ * Origins let a listener tell **its own** changes apart from foreign ones so it can skip the ones it
+ * already knows about — a change it produced is not looped back to where it came from. The canonical use
+ * is a network provider: it tags every remote update it applies with itself (`rdt.applyDelta(update,
+ * this)`) and then ignores `'delta'` events whose `origin === this`, so it never re-broadcasts an update
+ * it just received. The `origin` argument to `applyDelta` is optional and defaults to `null` (an
+ * anonymous/local change); the emitted event always carries whatever value was supplied.
+ *
+ * ## `Delta` vs `DeltaBuilder`
+ *
+ * The interface is parameterized by a {@link import ('./delta.js').DeltaConf DeltaConf} (like a
+ * {@link import ('./transformer.js').Transformer transformer}). Almost everything it exposes is the
+ * *read* form — {@link import ('./delta.js').Delta Delta} — because those values are **shared** and must
+ * not be mutated in place: `$delta` is the delta schema, the `delta` getter returns a state snapshot,
+ * `applyDelta` reads a change into the RDT, and the `'delta'` event payload is broadcast to every
+ * listener. The one *owned, mutable* form — {@link import ('./delta.js').DeltaBuilder DeltaBuilder} — is
+ * the fix `applyDelta` returns to the {@link Binding}. The binding never mutates a shared read delta: it
+ * {@link import ('./delta.js').cloneDeep deep-clones} every change into a private builder before the
+ * transformer rebases it (transformers manipulate deltas in place — see {@link Binding}).
  */
-export type RDT<D extends import("./delta.js").DeltaAny> = import("../observable.js").ObservableV2<{
-    delta: (delta: D) => void;
-    destroy: (rdt: RDT<D>) => void;
+export type RDT<Conf extends import("./delta.js").DeltaConf> = import("../observable.js").ObservableV2<{
+    delta: (delta: delta.Delta<Conf>, origin: any) => void;
+    destroy: (rdt: RDT<Conf>) => void;
 }> & {
-    $delta: Schema<D>;
-    delta: D;
-    applyDelta: (delta: D) => D | null;
+    $delta: Schema<delta.Delta<Conf>>;
+    delta: delta.Delta<Conf>;
+    applyDelta: (delta: delta.Delta<Conf>, origin?: any) => delta.DeltaBuilder<Conf> | null;
     destroy: () => void;
 };
+import * as delta from './delta.js';
 import * as dt from './transformer.js';
 import * as mux from '../mutex.js';
 export { $domDelta, domRDT } from "./rdt/dom.js";

package/dist/delta/transformer/core.d.ts

@@ -1,6 +1,21 @@
 export function $tresult<A extends import("../delta.js").DeltaConf, B extends import("../delta.js").DeltaConf>($a: s.Schema<import("../delta.js").Delta<A>>, $b: s.Schema<import("../delta.js").Delta<B>>): s.Schema<TransformResult<A, B>>;
 export function createTransformResult<DeltaA extends import("../delta.js").DeltaBuilderAny = delta.DeltaBuilderAny, DeltaB extends import("../delta.js").DeltaBuilderAny = delta.DeltaBuilderAny>(a: DeltaA | null, b: DeltaB | null): TransformResult<any, any>;
 /**
+ * A stateful, schema-bound mapper between changes of side A and side B, materialized from a
+ * {@link Template} via `init()`.
+ *
+ * ## Deltas are manipulated in place
+ *
+ * `apply`/`applyA`/`applyB` **mutate their input deltas directly** — they rebase nodes and splice op
+ * lists in place, and some transformers `apply(other, { move: true })` the input into an accumulator —
+ * rather than editing only through the copy-on-write `apply`/`rebase` surface. This is a deliberate
+ * exception to the general rule (a delta is normally edited only via `apply`/`rebase`, which re-clone
+ * frozen content on first touch); it keeps the transform allocation-free, but it means a transformer is
+ * an *owning* consumer of the delta it is given. **Callers must pass a privately-owned, fully-mutable
+ * delta** — never a shared or `done` (frozen) one. A caller holding a shared read delta must
+ * {@link import('../delta.js').cloneDeep deep-clone} it first (this is exactly what a
+ * {@link import('../rdt.js').Binding} does before routing a change through its transformer).
+ *
  * @template {import('../delta.js').DeltaConf} A
  * @template {import('../delta.js').DeltaConf} B
  */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "lib0",
-  "version": "1.0.0-rc.19",
+  "version": "1.0.0-rc.20",
   "description": "",
   "sideEffects": false,
   "type": "module",
@@ -331,7 +331,7 @@
     }
   },
   "devDependencies": {
-    "@types/node": "^25.5.2",
+    "@types/node": "^26.0.0",
     "c8": "^11.0.0",
     "dpdm": "^4.0.1",
     "jsdom": "^29.1.1",

package/src/delta/delta.js

@@ -1596,6 +1596,101 @@ export const slice = (d, start = 0, end = d.childCnt, currNode = d.children.star
  */
 export const clone = d => /** @type {any} */ (slice(d, 0, d.childCnt))
 
+/**
+ * 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 a clone keeps (`text`/`retain`/`delete` — `delete` drops its prevValue) 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/prevValue 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), _cloneMaybeDeltaDeep(op.prevValue), op.attribution)
+    : ($modifyAttrOp.check(op)
+        ? new ModifyAttrOp(op.key, cloneDeep(op.value), op.attribution)
+        // the only remaining attr op is a deleteAttr (its prevValue may be a nested delta)
+        : new DeleteAttrOp(op.key, _cloneMaybeDeltaDeep(op.prevValue), 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
@@ -3695,6 +3790,12 @@ class _DiffStringWrapper {
  * @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).
  */
 
 /**
@@ -3880,8 +3981,9 @@ export const diff = (d1, d2, options = {}) => {
             // 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)
-            d.setAttr(key, nextVal, attr2.attribution)
+            // 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 {
@@ -3923,13 +4025,16 @@ const contentLen = c => typeof c === 'string' ? c.length : 1
  */
 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
+ * 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) => { len > 0 && cins.splice(0, len).forEach(ins => d.insert(typeof ins === 'string' ? ins : [ins instanceof _DiffStringWrapper ? ins.str : ins])) }
+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
@@ -3954,13 +4059,13 @@ const applyChangesetToDelta = (d, changeset, compare, options) => {
         continue
       }
       applyRemoves(d, c.remove, cremoveDeltaIndex)
-      applyInserts(d, c.insert, cinsertDeltaIndex)
+      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)
+    applyInserts(d, c.insert, c.insert.length, options.clone)
   }
   return d
 }

package/src/delta/rdt/delta.js

@@ -2,8 +2,9 @@
  * # In-memory delta RDT
  *
  * {@link deltaRDT} creates an RDT (see `../rdt.js`) whose state is the accumulated delta. Calling
- * `applyDelta` merges the incoming delta into `state` and re-emits it as a `'delta'` event, so it can
- * be bound to any other RDT. It accepts every valid delta as-is, so it never returns a fix.
+ * `applyDelta(delta, origin)` merges the incoming delta into `state` and re-emits it (with the given
+ * {@link import('../rdt.js').RDT origin}) as a `'delta'` event, so it can be bound to any other RDT. It
+ * accepts every valid delta as-is, so it never returns a fix.
  *
  * `state` is kept as a **final** delta (`isFinal`): it represents the current document, so a `delete`
  * or `deleteAttr` removes the content/attribute outright instead of accumulating a delete-op marker.
@@ -22,21 +23,21 @@ import * as mux from '../../mutex.js'
  */
 
 /**
- * @template {delta.DeltaAny} D
- * @typedef {import('../rdt.js').RDT<D>} RDT
+ * @template {delta.DeltaConf} Conf
+ * @typedef {import('../rdt.js').RDT<Conf>} RDT
  */
 
 /**
  * An in-memory RDT whose state is the accumulated delta. Calling `applyDelta` merges the incoming delta
  * into `state` (via {@link delta.DeltaBuilder#apply}) and re-emits it as a `'delta'`.
  *
- * @template {delta.DeltaAny} D
- * @implements {RDT<D>}
- * @extends {ObservableV2<{ delta: (delta: D) => void, destroy: (rdt: DeltaRDT<D>) => void }>}
+ * @template {delta.DeltaConf} Conf
+ * @implements {RDT<Conf>}
+ * @extends {ObservableV2<{ delta: (delta: delta.Delta<Conf>, origin: any) => void, destroy: (rdt: DeltaRDT<Conf>) => void }>}
  */
 class DeltaRDT extends ObservableV2 {
   /**
-   * @param {Schema<D>} $delta schema of the deltas this RDT produces
+   * @param {Schema<delta.Delta<Conf>>} $delta schema of the deltas this RDT produces
    */
   constructor ($delta) {
     super()
@@ -52,10 +53,13 @@ class DeltaRDT extends ObservableV2 {
    * Merge an incoming delta into the current state and notify observers. Always returns `null`: this
    * RDT accepts every valid delta unchanged, so it never produces a fix.
    *
-   * @param {D} d
+   * @param {delta.Delta<Conf>} d
+   * @param {any} [origin] who produced the change; forwarded verbatim on the emitted `'delta'` event so
+   * listeners can recognise (and skip) changes they made themselves — see {@link RDT} “Origins”. Defaults
+   * to `null` (an anonymous/local change).
    * @return {null}
    */
-  applyDelta (d) {
+  applyDelta (d, origin = null) {
     if (d.isEmpty()) return null
     this._mux(() => {
       if (this.state == null) {
@@ -69,8 +73,9 @@ class DeltaRDT extends ObservableV2 {
     // emit AFTER releasing the mutex. When bound to a fix-producing RDT, that side's fix is mapped
     // back here and applied via a synchronous re-entrant `applyDelta` while this call is still on the
     // stack; with the emit inside the mutex that re-entrant mutation would be dropped. The binding's
-    // own mutex still breaks the echo loop.
-    this.emit('delta', [d])
+    // own mutex still breaks the echo loop. `d` is emitted as a shared read delta (the RDT only read it
+    // into `state`); a consumer that needs to mutate it deep-clones it first (see the `RDT` typedef).
+    this.emit('delta', [d, origin])
     return null
   }
 
@@ -78,10 +83,11 @@ class DeltaRDT extends ObservableV2 {
    * The current state as a delta: the accumulated `state`, or an empty delta when nothing has been
    * applied yet.
    *
-   * @return {D}
+   * @return {delta.Delta<Conf>}
    */
   get delta () {
-    return /** @type {any} */ (this.state ?? delta.create(this.$delta))
+    // `state` is a loosely-typed `DeltaBuilderAny`; narrow it to this RDT's read `Delta<Conf>` view.
+    return /** @type {delta.Delta<Conf>} */ (/** @type {unknown} */ (this.state ?? delta.create(this.$delta)))
   }
 
   destroy () {
@@ -93,7 +99,7 @@ class DeltaRDT extends ObservableV2 {
 /**
  * Create a {@link DeltaRDT} for deltas described by `$delta`.
  *
- * @template {delta.DeltaAny} D
- * @param {Schema<D>} $delta
+ * @template {delta.DeltaConf} Conf
+ * @param {Schema<delta.Delta<Conf>>} $delta
  */
 export const deltaRDT = $delta => new DeltaRDT($delta)

package/src/delta/rdt/dom.js

@@ -5,8 +5,9 @@
  *
  * {@link domRDT} creates an RDT (see `../rdt.js`) backed by a live DOM subtree. DOM mutations are
  * observed with a `MutationObserver`, turned into deltas (by diffing the new DOM state against the
- * last-known one) and emitted as `'delta'` events; incoming deltas are applied back onto the DOM.
- * This lets a DOM subtree be bound to any other RDT.
+ * last-known one) and emitted as `'delta'` events (with the RDT itself as their
+ * {@link import('../rdt.js').RDT origin}); incoming deltas are applied back onto the DOM. This lets a
+ * DOM subtree be bound to any other RDT.
  *
  * @module delta/rdt/dom
  */
@@ -24,8 +25,8 @@ import * as s from '../../schema.js'
  */
 
 /**
- * @template {delta.DeltaAny} D
- * @typedef {import('../rdt.js').RDT<D>} RDT
+ * @template {delta.DeltaConf} Conf
+ * @typedef {import('../rdt.js').RDT<Conf>} RDT
  */
 
 /**
@@ -177,16 +178,21 @@ const applyDeltaToDom = (el, d) => {
 export const $domDelta = /* @__PURE__ */ delta.$delta({ name: s.$string, attrs: s.$record(s.$string, s.$string), children: s.$never, text: true, recursiveChildren: true })
 
 /**
- * @typedef {delta.Delta<{ name: string, attrs: { [key:string]: string }, text: true, recursiveChildren: true }>} DomDelta
+ * The {@link delta.DeltaConf} of the deltas a {@link DomRDT} produces/consumes (see {@link $domDelta}).
+ *
+ * @typedef {{ name: string, attrs: { [key:string]: string }, text: true, recursiveChildren: true }} DomConf
+ */
+
+/**
+ * @typedef {delta.Delta<DomConf>} DomDelta
  */
 
 /**
  * An RDT backed by a live DOM subtree. DOM mutations observed via `MutationObserver` are diffed
  * against the last-known state and emitted as deltas; incoming deltas are applied back onto the DOM.
  *
- * @template {DomDelta} [D=DomDelta]
- * @implements {RDT<D>}
- * @extends {ObservableV2<{ delta: (delta: D) => void, destroy: (rdt: DomRDT<D>) => void }>}
+ * @implements {RDT<DomConf>}
+ * @extends {ObservableV2<{ delta: (delta: delta.Delta<DomConf>, origin: any) => void, destroy: (rdt: DomRDT) => void }>}
  */
 class DomRDT extends ObservableV2 {
   /**
@@ -195,7 +201,7 @@ class DomRDT extends ObservableV2 {
   constructor (observedNode) {
     super()
     /**
-     * @type {Schema<D>}
+     * @type {Schema<DomDelta>}
      */
     this.$delta = /** @type {any} */ ($domDelta)
     this.observedNode = observedNode
@@ -233,8 +239,9 @@ class DomRDT extends ObservableV2 {
    */
   _mutationHandler = mutations => {
     if (mutations.length === 0) return
-    const change = /** @type {D} */ (this._pull())
-    if (!change.isEmpty()) this.emit('delta', [change])
+    const change = this._pull()
+    // a locally-observed DOM edit: this RDT is the producer, so it is the origin (see {@link RDT})
+    if (!change.isEmpty()) this.emit('delta', [change, this])
   }
 
   /**
@@ -245,10 +252,14 @@ class DomRDT extends ObservableV2 {
    * `d` rebased onto `b` is applied to the DOM, and `b` rebased onto `d` is returned as the fix so the
    * binding pipes it back through the transformer to the other side.
    *
-   * @param {D} d
-   * @return {D | null} the rebased local change (`b`), or `null` when there were no concurrent edits
+   * @param {delta.Delta<DomConf>} d
+   * @param {any} [origin] who produced `d`; forwarded verbatim on the emitted `'delta'` event so
+   * listeners can recognise (and skip) their own changes — see {@link RDT} “Origins”. Defaults to `null`
+   * (an anonymous/local change).
+   * @return {delta.DeltaBuilder<DomConf> | null} the rebased local change (`b`), or `null` when there
+   * were no concurrent edits
    */
-  applyDelta (d) {
+  applyDelta (d, origin = null) {
     const b = this._pull()
     /** @type {DomDelta} */
     let toApply = d
@@ -266,19 +277,19 @@ class DomRDT extends ObservableV2 {
     // echo of our own write — draining the self-caused records here is what prevents it.
     this.observer.takeRecords()
     // Forward the effective change so a chained binding on the other side picks it up; the binding
-    // that fed us `d` swallows this re-emit via its own mutex (see ../rdt.js).
-    const effective = /** @type {D} */ (toApply)
-    this.emit('delta', [effective])
-    return /** @type {D?} */ (fix)
+    // that fed us `d` swallows this re-emit via its own mutex (see ../rdt.js). `fix` is a freshly
+    // rebased builder at runtime, returned as the owned change the binding maps on.
+    this.emit('delta', [toApply, origin])
+    return /** @type {delta.DeltaBuilder<DomConf>?} */ (fix)
   }
 
   /**
    * The current state as a delta: an "insert everything" delta describing the observed subtree.
    *
-   * @return {D}
+   * @return {delta.Delta<DomConf>}
    */
   get delta () {
-    return /** @type {D} */ (domToDelta(this.observedNode))
+    return domToDelta(this.observedNode)
   }
 
   destroy () {

package/src/delta/rdt.js

@@ -4,8 +4,9 @@
  * An **RDT** ("replicated data type") is any object that represents some state and communicates changes
  * to that state as {@link import('./delta.js').Delta deltas}. Every RDT is an
  * {@link import('../observable.js').ObservableV2 observable}:
- * - it **emits** a `'delta'` event carrying a delta whenever its own state changes, and
- * - it **accepts** foreign changes through `applyDelta(delta)`, which mutates its state to match.
+ * - it **emits** a `'delta'` event carrying a delta and its {@link RDT origin} whenever its own state
+ *   changes, and
+ * - it **accepts** foreign changes through `applyDelta(delta, origin)`, which mutates its state to match.
  *
  * Because the changes are deltas, two different representations of "the same" data can be kept in sync
  * even when their shapes differ. That is the job of a {@link Binding}: it connects two RDTs `a` and `b`
@@ -64,17 +65,45 @@ export { $domDelta, domRDT } from './rdt/dom.js'
  * transformer for it), exposes its current state as a delta via the `delta` getter, and accepts foreign
  * deltas via `applyDelta`.
  *
- * `applyDelta(d)` applies `d` and then, if the change would violate the RDT's own invariants, applies
- * a **fix** of its own (e.g. reversing part of `d`, or inserting missing content) and returns that fix
- * — `null` when none was needed. The fix is a regular change on this RDT, so a {@link Binding} maps it
- * onto the other side just like any other change. `applyDelta` also emits the *effective* change
+ * `applyDelta(d, origin)` applies `d` and then, if the change would violate the RDT's own invariants,
+ * applies a **fix** of its own (e.g. reversing part of `d`, or inserting missing content) and returns
+ * that fix — `null` when none was needed. The fix is a regular change on this RDT, so a {@link Binding}
+ * maps it onto the other side just like any other change. `applyDelta` also emits the *effective* change
  * (`d` together with the fix) on the `'delta'` channel.
  *
- * @template {import('./delta.js').DeltaAny} D
- * @typedef {import('../observable.js').ObservableV2<{ delta: (delta: D) => void, destroy: (rdt: RDT<D>) => void }> & {
- *   $delta: Schema<D>,
- *   delta: D,
- *   applyDelta: (delta: D) => D | null,
+ * ## Origins
+ *
+ * Every `'delta'` event carries a second argument, `origin` — an opaque `any` value (modelled after
+ * {@link https://docs.yjs.dev/api/transactions Yjs transaction origins}) that identifies **where the
+ * change came from**. Whoever produces the change sets it, and it is usually the producing instance
+ * itself: a communication provider, an editor binding, or the {@link Binding} that mapped the change
+ * over from the other side. A change an RDT observes locally (e.g. a `MutationObserver` firing on a DOM
+ * edit) uses that RDT itself as the origin.
+ *
+ * Origins let a listener tell **its own** changes apart from foreign ones so it can skip the ones it
+ * already knows about — a change it produced is not looped back to where it came from. The canonical use
+ * is a network provider: it tags every remote update it applies with itself (`rdt.applyDelta(update,
+ * this)`) and then ignores `'delta'` events whose `origin === this`, so it never re-broadcasts an update
+ * it just received. The `origin` argument to `applyDelta` is optional and defaults to `null` (an
+ * anonymous/local change); the emitted event always carries whatever value was supplied.
+ *
+ * ## `Delta` vs `DeltaBuilder`
+ *
+ * The interface is parameterized by a {@link import('./delta.js').DeltaConf DeltaConf} (like a
+ * {@link import('./transformer.js').Transformer transformer}). Almost everything it exposes is the
+ * *read* form — {@link import('./delta.js').Delta Delta} — because those values are **shared** and must
+ * not be mutated in place: `$delta` is the delta schema, the `delta` getter returns a state snapshot,
+ * `applyDelta` reads a change into the RDT, and the `'delta'` event payload is broadcast to every
+ * listener. The one *owned, mutable* form — {@link import('./delta.js').DeltaBuilder DeltaBuilder} — is
+ * the fix `applyDelta` returns to the {@link Binding}. The binding never mutates a shared read delta: it
+ * {@link import('./delta.js').cloneDeep deep-clones} every change into a private builder before the
+ * transformer rebases it (transformers manipulate deltas in place — see {@link Binding}).
+ *
+ * @template {import('./delta.js').DeltaConf} Conf
+ * @typedef {import('../observable.js').ObservableV2<{ delta: (delta: delta.Delta<Conf>, origin: any) => void, destroy: (rdt: RDT<Conf>) => void }> & {
+ *   $delta: Schema<delta.Delta<Conf>>,
+ *   delta: delta.Delta<Conf>,
+ *   applyDelta: (delta: delta.Delta<Conf>, origin?: any) => delta.DeltaBuilder<Conf> | null,
  *   destroy: () => void
  * }} RDT
  */
@@ -101,47 +130,62 @@ export const $rdt = /** @type {Schema<RDT<any>>} */ (/* @__PURE__ */ s.$custom(o
  * `ta` / `tb` are changes that have ALREADY been applied to `a` / `b` (an incoming `'delta'`, or a fix
  * returned by a previous `applyDelta`). Each is mapped onto the other side via the transformer —
  * `apply` rebases the two against each other — and the mapped results are applied, which may yield
- * further RDT fixes. We repeat until neither side reports a fix.
- *
- * @param {Binding<any>} binding
- * @param {any} ta change already applied on `a` (or `null`)
- * @param {any} tb change already applied on `b` (or `null`)
+ * further RDT fixes. We repeat until neither side reports a fix. Every change it applies to either side
+ * uses the `binding` itself as its {@link RDT origin} — from each side's perspective the binding is what
+ * produced the mapped change.
+ *
+ * `ta`/`tb` are shared read deltas (an event payload, or a fix that was also written into the producing
+ * RDT's state), so they are {@link delta.cloneDeep deep-cloned} into private builders before the
+ * transformer — which rebases its inputs in place — touches them (see {@link Binding}).
+ *
+ * @template {delta.DeltaConf} A
+ * @template {delta.DeltaConf} B
+ * @param {Binding<A,B>} binding
+ * @param {any} ta change already applied on `a` — a shared read delta (event payload or a fix), or `null`
+ * @param {any} tb change already applied on `b` — a shared read delta (event payload or a fix), or `null`
  */
 const propagate = (binding, ta, tb) => {
   while ((ta != null && !ta.isEmpty()) || (tb != null && !tb.isEmpty())) {
-    const tres = binding.t.apply(dt.createTransformResult(ta, tb))
-    ta = tres.a != null ? binding.a.applyDelta(tres.a) : null
-    tb = tres.b != null ? binding.b.applyDelta(tres.b) : null
+    const tres = binding.t.apply(dt.createTransformResult(
+      ta != null ? delta.cloneDeep(ta) : null,
+      tb != null ? delta.cloneDeep(tb) : null
+    ))
+    ta = tres.a != null ? binding.a.applyDelta(tres.a, binding) : null
+    tb = tres.b != null ? binding.b.applyDelta(tres.b, binding) : null
   }
 }
 
 /**
  * Connects two RDTs so that changes on either side are transformed and reflected on the other.
  *
- * @template {import('./delta.js').DeltaAny} DeltaA
+ * The {@link dt.Transformer transformer} it drives **manipulates deltas in place** (it splices op lists
+ * and rebases nodes directly, rather than only via `apply`/`rebase`) — a deliberate exception to the
+ * general rule that deltas are edited through `apply`/`rebase`. Consequently every change handed to it
+ * must be a privately-owned, fully-mutable delta, so the binding {@link delta.cloneDeep deep-clones}
+ * each incoming change (which is a shared read delta — an event payload or a snapshot) before the
+ * transformer touches it. See the initial-state sync below and {@link propagate}.
+ *
+ * @template {delta.DeltaConf} A
+ * @template {delta.DeltaConf} B
  */
 export class Binding {
   /**
-   * @param {RDT<DeltaA>} a
-   * @param {RDT<import('./delta.js').DeltaAny>} b
-   * @param {dt.TemplateFactory<any,any>} [template] a `$d => Template` factory; defaults to the
+   * @param {RDT<A>} a
+   * @param {RDT<B>} b
+   * @param {dt.TemplateFactory<A,B>} [template] a `$d => Template` factory; defaults to the
    * {@link dt.id identity} transformer. `bind` injects `a`'s schema, then materializes via `.init()`.
    */
-  constructor (a, b, template = dt.id) {
+  constructor (a, b, template = /** @type {dt.TemplateFactory<A,B>} */ (dt.id)) {
     /**
-     * @type {dt.Transformer<any,any>}
+     * @type {dt.Transformer<A,B>}
      */
     this.t = template(a.$delta).init()
-    // reason: the `'delta'` channel carries `Delta` values while the transformer is typed for the
-    // mutable `DeltaBuilder` it consumes/produces, and the binding is generic over both sides; typing
-    // the internal handles as `RDT<any>` lets changes pass through the transformer without unsound
-    // cross-casts, while `bind`/the constructor keep precise public signatures.
     /**
-     * @type {RDT<any>}
+     * @type {RDT<A>}
      */
     this.a = a
     /**
-     * @type {RDT<any>}
+     * @type {RDT<B>}
      */
     this.b = b
     this._mux = mux.createMutex()
@@ -157,10 +201,17 @@ export class Binding {
     // time are NOT transferred to `b` here; marks ride only on subsequent live `applyA`/`applyB`.
     // Wrapped in the mutex so these `applyDelta` calls don't echo back through the listeners above.
     this._mux(() => {
-      const tres = this.t.applyA(this.a.delta)
-      const fa = tres.a ? this.a.applyDelta(tres.a) : null
-      const diffB = tres.b ? delta.diff(/** @type {delta.DeltaAny} */ (this.b.delta), tres.b) : null
-      const fb = diffB ? this.b.applyDelta(diffB) : null
+      // `a.delta` is a shared read snapshot (for an in-memory RDT it IS the live state, whose nested
+      // children are frozen `done`), so DEEP-clone it into a private, fully-mutable builder before the
+      // transformer — which rebases its input in place — projects it. A shallow `clone` would still share
+      // those frozen children and corrupt / fail on the live state (see `delta.cloneDeep`).
+      const tres = this.t.applyA(delta.cloneDeep(this.a.delta))
+      const fa = tres.a ? this.a.applyDelta(tres.a, this) : null
+      // `diff` shares nested children with `tres.b` by default, and `tres.b` is a (possibly stateful)
+      // transformer's output that may still alias its internal state — so `clone` keeps the diff
+      // independent, since it is then applied into `b` (which freezes it) and propagated onward.
+      const diffB = tres.b ? delta.diff(this.b.delta, tres.b, { clone: true }) : null
+      const fb = diffB ? this.b.applyDelta(diffB, this) : null
       propagate(this, fa, fb)
     })
   }
@@ -184,11 +235,12 @@ export class Binding {
  * {@link Binding#destroy} on the returned binding to stop syncing (it also self-destroys when either RDT
  * emits `'destroy'`).
  *
- * @template {import('./delta.js').DeltaAny} DeltaA
- * @param {RDT<DeltaA>} a
- * @param {RDT<import('./delta.js').DeltaAny>} b
- * @param {dt.TemplateFactory<any,any>} [template] a `$d => Template` factory (e.g. `dt.id` or
+ * @template {delta.DeltaConf} A
+ * @template {delta.DeltaConf} B
+ * @param {RDT<A>} a
+ * @param {RDT<B>} b
+ * @param {dt.TemplateFactory<A,B>} [template] a `$d => Template` factory (e.g. `dt.id` or
  * `$d => dt.renameAttrs($d, {a:'b'})`)
- * @return {Binding<DeltaA>}
+ * @return {Binding<A,B>}
  */
 export const bind = (a, b, template) => new Binding(a, b, template)

package/src/delta/transformer/core.js

@@ -89,6 +89,21 @@ export const $tresult = ($a, $b) => /** @type {any} */ (s.$instanceOf(TransformR
 export const createTransformResult = (a, b) => new TransformResult(a, b)
 
 /**
+ * A stateful, schema-bound mapper between changes of side A and side B, materialized from a
+ * {@link Template} via `init()`.
+ *
+ * ## Deltas are manipulated in place
+ *
+ * `apply`/`applyA`/`applyB` **mutate their input deltas directly** — they rebase nodes and splice op
+ * lists in place, and some transformers `apply(other, { move: true })` the input into an accumulator —
+ * rather than editing only through the copy-on-write `apply`/`rebase` surface. This is a deliberate
+ * exception to the general rule (a delta is normally edited only via `apply`/`rebase`, which re-clone
+ * frozen content on first touch); it keeps the transform allocation-free, but it means a transformer is
+ * an *owning* consumer of the delta it is given. **Callers must pass a privately-owned, fully-mutable
+ * delta** — never a shared or `done` (frozen) one. A caller holding a shared read delta must
+ * {@link import('../delta.js').cloneDeep deep-clone} it first (this is exactly what a
+ * {@link import('../rdt.js').Binding} does before routing a change through its transformer).
+ *
  * @template {import('../delta.js').DeltaConf} A
  * @template {import('../delta.js').DeltaConf} B
  */