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

package/{types → dist}/delta/delta.d.ts

@@ -1,4 +1,17 @@
 /**
+ * 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
@@ -13,21 +26,36 @@
  */
 export const $attribution: s.Schema<Attribution>;
 /**
- * @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
  */
 /**
  * @typedef {{
  *   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
  */
 /**
  * @typedef {TextOp|InsertOp<any>|DeleteOp|RetainOp|ModifyOp<any>} ChildrenOpAny
@@ -42,13 +70,31 @@ export const $attribution: s.Schema<Attribution>;
  * @type {s.Schema<DeltaAttrOpJSON>}
  */
 export const $deltaMapChangeJson: s.Schema<DeltaAttrOpJSON>;
+/**
+ * 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: string, format: FormattingAttributes | null, attribution: Attribution | null);
+    constructor(insert: string, format: Formats | null, attribution: Attribution | null);
     /**
      * @readonly
      * @type {string}
@@ -56,15 +102,14 @@ export class TextOp extends list.ListNode {
     readonly insert: string;
     /**
      * @readonly
-     * @type {FormattingAttributes|null}
+     * @type {Formats|null}
      */
-    readonly format: FormattingAttributes | null;
+    readonly format: Formats | null;
     attribution: Attribution | null;
     /**
      * @type {string?}
      */
     _fingerprint: string | null;
-    get $type(): s.Schema<TextOp>;
     /**
      * @param {string} newVal
      */
@@ -87,9 +132,14 @@ export class TextOp extends list.ListNode {
      */
     toJSON(): DeltaListOpJSON;
     /**
+     * @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?: number, end?: number): TextOp;
+    clone(start?: number, end?: number, _markAsDone?: boolean): TextOp;
+    $type: s.Schema<TextOp>;
     /**
      * @param {TextOp} other
      */
@@ -97,14 +147,15 @@ export class TextOp extends list.ListNode {
 }
 /**
  * @template {any} ArrayContent
+ * @internal not part of the consumer API — a content op; build deltas via {@link create}/{@link DeltaBuilder}.
  */
 export class InsertOp<ArrayContent extends unknown> extends list.ListNode {
     /**
      * @param {Array<ArrayContent>} insert
-     * @param {FormattingAttributes|null} format
+     * @param {Formats|null} format
      * @param {Attribution?} attribution
      */
-    constructor(insert: Array<ArrayContent>, format: FormattingAttributes | null, attribution: Attribution | null);
+    constructor(insert: Array<ArrayContent>, format: Formats | null, attribution: Attribution | null);
     /**
      * @readonly
      * @type {Array<ArrayContent>}
@@ -112,9 +163,9 @@ export class InsertOp<ArrayContent extends unknown> extends list.ListNode {
     readonly insert: Array<ArrayContent>;
     /**
      * @readonly
-     * @type {FormattingAttributes?}
+     * @type {Formats?}
      */
-    readonly format: FormattingAttributes | null;
+    readonly format: Formats | null;
     /**
      * @readonly
      * @type {Attribution?}
@@ -124,11 +175,10 @@ export class InsertOp<ArrayContent extends unknown> extends list.ListNode {
      * @type {string?}
      */
     _fingerprint: string | null;
-    get $type(): s.Schema<InsertOp<any>>;
     /**
-     * @param {ArrayContent} newVal
+     * @param {ArrayContent} _newVal
      */
-    _updateInsert(newVal: ArrayContent): void;
+    _updateInsert(_newVal: ArrayContent): void;
     /**
      * @return {'insert'}
      */
@@ -152,9 +202,16 @@ export class InsertOp<ArrayContent extends unknown> extends list.ListNode {
      */
     toJSON(): DeltaListOpJSON;
     /**
+     * @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?: number, end?: number): InsertOp<ArrayContent>;
+    clone(start?: number, end?: number, markAsDone?: boolean): InsertOp<ArrayContent>;
+    $type: s.Schema<InsertOp<any>>;
     /**
      * @param {InsertOp<ArrayContent>} other
      */
@@ -162,6 +219,7 @@ export class InsertOp<ArrayContent extends unknown> extends list.ListNode {
 }
 /**
  * @template {DeltaConf} [Conf={}]
+ * @internal not part of the consumer API — a content op; build deltas via {@link create}/{@link DeltaBuilder}.
  */
 export class DeleteOp<Conf extends DeltaConf = {}> extends list.ListNode {
     /**
@@ -169,15 +227,10 @@ export class DeleteOp<Conf extends DeltaConf = {}> extends list.ListNode {
      */
     constructor(len: number);
     delete: number;
-    /**
-     * @type {Delta<Conf>?}
-     */
-    prevValue: Delta<Conf> | null;
     /**
      * @type {string|null}
      */
     _fingerprint: string | null;
-    get $type(): s.Schema<DeleteOp<any>>;
     /**
      * @return {'delete'}
      */
@@ -196,23 +249,29 @@ export class DeleteOp<Conf extends DeltaConf = {}> extends list.ListNode {
      */
     toJSON(): DeltaListOpJSON;
     /**
-     * @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?: number, end?: number): DeleteOp;
+    clone(start?: number, end?: number, _markAsDone?: boolean): DeleteOp;
+    $type: s.Schema<DeleteOp<any>>;
     /**
      * @param {DeleteOp} other
      */
     [equalityTrait.EqualityTraitSymbol](other: DeleteOp): boolean;
 }
+/**
+ * @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: number, format: FormattingAttributes | null, attribution: Attribution | null);
+    constructor(retain: number, format: Formats | null | undefined, attribution: Attribution | null | undefined);
     /**
      * @readonly
      * @type {number}
@@ -220,19 +279,18 @@ export class RetainOp extends list.ListNode {
     readonly retain: number;
     /**
      * @readonly
-     * @type {FormattingAttributes?}
+     * @type {Formats|null|undefined}
      */
-    readonly format: FormattingAttributes | null;
+    readonly format: Formats | null | undefined;
     /**
      * @readonly
-     * @type {Attribution?}
+     * @type {Attribution|null|undefined}
      */
-    readonly attribution: Attribution | null;
+    readonly attribution: Attribution | null | undefined;
     /**
      * @type {string|null}
      */
     _fingerprint: string | null;
-    get $type(): s.Schema<RetainOp>;
     /**
      * @return {'retain'}
      */
@@ -250,7 +308,15 @@ export class RetainOp extends list.ListNode {
      * @return {DeltaListOpJSON}
      */
     toJSON(): DeltaListOpJSON;
-    clone(start?: number, end?: number): RetainOp;
+    /**
+     * @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?: number, end?: number, _markAsDone?: boolean): RetainOp;
+    $type: s.Schema<RetainOp>;
     /**
      * @param {RetainOp} other
      */
@@ -260,14 +326,15 @@ 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<DTypes extends Delta = DeltaAny> 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: DTypes, format: FormattingAttributes | null, attribution: Attribution | null);
+    constructor(delta: DTypes, format: Formats | null | undefined, attribution: Attribution | null | undefined);
     /**
      * @readonly
      * @type {DTypes}
@@ -275,19 +342,18 @@ export class ModifyOp<DTypes extends Delta = DeltaAny> extends list.ListNode {
     readonly value: DTypes;
     /**
      * @readonly
-     * @type {FormattingAttributes?}
+     * @type {Formats|null|undefined}
      */
-    readonly format: FormattingAttributes | null;
+    readonly format: Formats | null | undefined;
     /**
      * @readonly
-     * @type {Attribution?}
+     * @type {Attribution|null|undefined}
      */
-    readonly attribution: Attribution | null;
+    readonly attribution: Attribution | null | undefined;
     /**
      * @type {string|null}
      */
     _fingerprint: string | null;
-    get $type(): s.Schema<ModifyOp<DeltaAny>>;
     /**
      * @return {'modify'}
      */
@@ -310,9 +376,14 @@ export class ModifyOp<DTypes extends Delta = DeltaAny> extends list.ListNode {
      */
     toJSON(): DeltaListOpJSON;
     /**
+     * @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(): ModifyOp<DTypes>;
+    clone(_start?: number, _end?: number, markAsDone?: boolean): ModifyOp<DTypes>;
+    $type: s.Schema<ModifyOp<Delta<any>>>;
     /**
      * @param {ModifyOp<any>} other
      */
@@ -321,15 +392,15 @@ export class ModifyOp<DTypes extends Delta = DeltaAny> extends list.ListNode {
 /**
  * @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<V extends unknown = any, K extends string | number = any> {
     /**
      * @param {K} key
      * @param {V} value
-     * @param {V|undefined} prevValue
      * @param {Attribution?} attribution
      */
-    constructor(key: K, value: V, prevValue: V | undefined, attribution: Attribution | null);
+    constructor(key: K, value: V, attribution: Attribution | null);
     /**
      * @readonly
      * @type {K}
@@ -340,11 +411,6 @@ export class SetAttrOp<V extends unknown = any, K extends string | number = any>
      * @type {V}
      */
     readonly value: V;
-    /**
-     * @readonly
-     * @type {V|undefined}
-     */
-    readonly prevValue: V | undefined;
     /**
      * @readonly
      * @type {Attribution?}
@@ -354,7 +420,6 @@ export class SetAttrOp<V extends unknown = any, K extends string | number = any>
      * @type {string|null}
      */
     _fingerprint: string | null;
-    get $type(): s.Schema<SetAttrOp<any, any>>;
     /**
      * @return {'insert'}
      */
@@ -366,16 +431,20 @@ export class SetAttrOp<V extends unknown = any, K extends string | number = any>
     get fingerprint(): string;
     toJSON(): {
         type: "insert";
-        value: DeltaJSON | V;
+        value: V | DeltaJSON;
     } & ({
         attribution: Attribution;
     } | {
         attribution?: undefined;
     });
     /**
+     * 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(): SetAttrOp<V, K>;
+    $type: s.Schema<SetAttrOp<any, any>>;
     /**
      * @param {SetAttrOp<V>} other
      */
@@ -384,28 +453,23 @@ export class SetAttrOp<V extends unknown = any, K extends string | number = any>
 /**
  * @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<V = any, K extends string | number = string | number> {
     /**
      * @param {K} key
-     * @param {V|undefined} prevValue
      * @param {Attribution?} attribution
      */
-    constructor(key: K, prevValue: V | undefined, attribution: Attribution | null);
+    constructor(key: K, attribution: Attribution | null);
     /**
      * @type {K}
      */
     key: K;
-    /**
-     * @type {V|undefined}
-     */
-    prevValue: V | undefined;
     attribution: Attribution | null;
     /**
      * @type {string|null}
      */
     _fingerprint: string | null;
-    get $type(): s.Schema<DeleteAttrOp<any, string | number>>;
     /**
      * @type {'delete'}
      */
@@ -416,7 +480,13 @@ export class DeleteAttrOp<V = any, K extends string | number = string | number>
      * @return {DeltaAttrOpJSON}
      */
     toJSON(): DeltaAttrOpJSON;
+    /**
+     * Full (frozen) clone; a `move` apply reuses the source op instead — see {@link DeltaBuilder#apply}.
+     *
+     * @return {DeleteAttrOp<V,K>}
+     */
     clone(): DeleteAttrOp<V, K>;
+    $type: s.Schema<DeleteAttrOp<any, string | number>>;
     /**
      * @param {DeleteAttrOp<V>} other
      */
@@ -425,13 +495,15 @@ export class DeleteAttrOp<V = any, K extends string | number = string | number>
 /**
  * @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<Modifier extends DeltaAny = DeltaAny, K extends string | number = string> {
     /**
      * @param {K} key
      * @param {Modifier} delta
+     * @param {Attribution|null|undefined} attribution tri-state: `undefined` skip / `null` clear / object merge
      */
-    constructor(key: K, delta: Modifier);
+    constructor(key: K, delta: Modifier, attribution: Attribution | null | undefined);
     /**
      * @readonly
      * @type {K}
@@ -442,11 +514,15 @@ export class ModifyAttrOp<Modifier extends DeltaAny = DeltaAny, K extends string
      * @type {Modifier}
      */
     readonly value: Modifier;
+    /**
+     * @readonly
+     * @type {Attribution|null|undefined}
+     */
+    readonly attribution: Attribution | null | undefined;
     /**
      * @type {string|null}
      */
     _fingerprint: string | null;
-    get $type(): s.Schema<ModifyAttrOp<any, string | number>>;
     /**
      * @type {'modify'}
      */
@@ -461,28 +537,33 @@ export class ModifyAttrOp<Modifier extends DeltaAny = DeltaAny, K extends string
      */
     toJSON(): DeltaAttrOpJSON;
     /**
+     * Full (frozen) clone; a `move` apply reuses the source op instead — see {@link DeltaBuilder#apply}.
+     *
      * @return {ModifyAttrOp<Modifier,K>}
      */
     clone(): ModifyAttrOp<Modifier, K>;
+    $type: s.Schema<ModifyAttrOp<any, string>>;
     /**
      * @param {ModifyAttrOp<Modifier>} other
      */
     [equalityTrait.EqualityTraitSymbol](other: ModifyAttrOp<Modifier>): boolean;
 }
 export const $insertOp: s.Schema<InsertOp<any>>;
-export const $modifyOp: s.Schema<ModifyOp>;
+export const $modifyOp: s.Schema<ModifyOp<Delta<any>>>;
 export const $textOp: s.Schema<TextOp>;
 export const $deleteOp: s.Schema<DeleteOp<any>>;
 export const $retainOp: s.Schema<RetainOp>;
-export const $anyOp: s.Schema<TextOp | InsertOp<any> | DeleteOp<any> | ModifyOp<DeltaAny>>;
+export const $anyOp: s.Schema<DeleteOp<any> | TextOp | InsertOp<any> | ModifyOp<Delta<any>>>;
 export const $setAttrOp: s.Schema<SetAttrOp<any>>;
-export const $modifyAttrOp: s.Schema<ModifyAttrOp<any, string | number>>;
-export const $deleteAttrOp: s.Schema<DeleteAttrOp<any, string | number>>;
-export const $anyAttrOp: s.Schema<SetAttrOp<any, any> | DeleteAttrOp<any, string | number> | ModifyAttrOp<any, string | number>>;
+export const $modifyAttrOp: s.Schema<ModifyAttrOp<any>>;
+export const $deleteAttrOp: s.Schema<DeleteAttrOp<any>>;
+export const $anyAttrOp: s.Schema<ModifyAttrOp<any, string> | SetAttrOp<any, any> | DeleteAttrOp<any, string | number>>;
 export function $setAttrOpWith<Content extends fingerprintTrait.Fingerprintable>($content: s.Schema<Content>): s.Schema<SetAttrOp<Content>>;
 export function $insertOpWith<Content extends fingerprintTrait.Fingerprintable>($content: s.Schema<Content>): s.Schema<InsertOp<Content>>;
 export function $modifyOpWith<Modify extends DeltaAny>($content: s.Schema<Modify>): s.Schema<ModifyOp<Modify>>;
 export function $modifyAttrOpWith<Modify extends DeltaAny>($content: s.Schema<Modify>): s.Schema<ModifyAttrOp<Modify>>;
+export const $mark: s.Schema<Mark>;
+export function createMark(key: number | string, id?: string, assoc?: 1 | -1, attrs?: object | null): Mark;
 /**
  * @template {DeltaConf} [Conf={}]
  * @extends {DeltaData<
@@ -505,7 +586,6 @@ export class Delta<Conf extends DeltaConf = {}> extends DeltaData<DeltaConfGetNa
      * @param {s.Schema<Delta<any>>?} $schema
      */
     constructor(name: string | null, $schema: s.Schema<Delta<any>> | null);
-    get $type(): s.Schema<DeltaAny>;
     /**
      * @type {string}
      */
@@ -528,6 +608,7 @@ export class Delta<Conf extends DeltaConf = {}> extends DeltaData<DeltaConfGetNa
      * @return {Delta<Conf>}
      */
     done(markAsDone?: boolean): Delta<Conf>;
+    $type: s.Schema<Delta<any>>;
     [fingerprintTrait.FingerprintTraitSymbol](): string;
     /**
      * @param {any} other
@@ -537,6 +618,15 @@ 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;
+export function _insertChild(d: DeltaBuilderAny, ref: ChildrenOpAny | null, op: ChildrenOpAny): ChildrenOpAny;
+export function _removeChild(d: DeltaBuilderAny, op: ChildrenOpAny): void;
+export function _shrinkChild(d: DeltaBuilderAny, op: ChildrenOpAny, offset: number, len: number): void;
+export function _growRun(d: DeltaBuilderAny, op: RetainOp | DeleteOp<any>, n: number): void;
+export function _spliceInsert(d: DeltaBuilderAny, op: InsertOp<any>, offset: number, elems: Array<any>): void;
 /**
  * @template {DeltaConf} [Conf={}]
  * @template {boolean} [FixedConf=false]
@@ -549,27 +639,79 @@ export class DeltaBuilder<Conf extends DeltaConf = {}, FixedConf extends boolean
      */
     constructor(name: string | null, $schema: s.Schema<Delta<Conf>> | null);
     /**
-     * @type {FormattingAttributes?}
+     * @type {Formats?}
      */
-    usedAttributes: FormattingAttributes | null;
+    _usedFormats: Formats | null;
     /**
      * @type {Attribution?}
      */
-    usedAttribution: Attribution | null;
+    _usedAttribution: Attribution | 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}
+     */
+    _usedFormatsData: Formats | null | undefined;
+    /**
+     * @type {Attribution|null|undefined}
+     */
+    _usedAttributionData: Attribution | null | 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(): Formats | null;
+    /**
+     * 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(): Attribution | null;
     /**
+     * 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: Attribution | null): 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: FormattingAttributes | null): this;
+    useFormats(attributes: Formats | null): 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(): Formats | null;
+    /**
+     * See {@link DeltaBuilder#_getUsedFormatsData} — the `usedAttribution` analogue (its `format` key
+     * resolves one level deeper).
+     *
+     * @return {Attribution?}
+     */
+    _getUsedAttributionData(): Attribution | null;
     /**
      * @param {string} name
      * @param {any} value
      */
-    updateUsedAttributes(name: string, value: any): this;
+    updateUsedFormats(name: string, value: any): this;
     /**
      * @template {keyof Attribution} NAME
      * @param {NAME} name
@@ -579,34 +721,58 @@ export class DeltaBuilder<Conf extends DeltaConf = {}, FixedConf extends boolean
     /**
      * @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<NewContent extends (FixedConf extends true ? never : (Array<any> | string)) | (DeltaConfGetChildren<Conf> extends infer Children_1 ? (Children_1 extends never ? never : Array<Children_1>) : never) | DeltaConfGetText<Conf>>(insert: NewContent, formatting?: FormattingAttributes | null, attribution?: Attribution | null): DeltaBuilder<FixedConf extends true ? Conf : DeltaConfOverwrite<Conf, (Exclude<NewContent, string> extends never ? {} : {
+    insert<NewContent extends (FixedConf extends true ? never : (Array<any> | string)) | (DeltaConfGetChildren<Conf> extends infer Children_1 ? (Children_1 extends never ? never : Array<Children_1>) : never) | DeltaConfGetText<Conf>>(insert: NewContent, formatting?: Formats | null, attribution?: Attribution | null): 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>;
     /**
-     * @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<NewContent extends Extract<DeltaConfGetAllowedChildren<Conf, FixedConf>, Delta>>(modify: NewContent, formatting?: FormattingAttributes | null, attribution?: Attribution | null): DeltaBuilder<DeltaConfOverwrite<Conf, {
+    modify<NewContent extends Extract<DeltaConfGetAllowedChildren<Conf, FixedConf>, Delta | DeltaData<any, any, any, any> | DeltaBuilder>>(modify: NewContent, formatting?: Formats | null, attribution?: Attribution | null): DeltaBuilder<DeltaConfOverwrite<Conf, {
         children: DeltaConfGetChildren<Conf> | NewContent;
     }>, FixedConf>;
+    /**
+     * 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: import("./position.js").Pos, id?: string): 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: import("./position.js").Pos, id: string): this;
     /**
      * @param {number} len
-     * @param {FormattingAttributes?} [format]
+     * @param {Formats?} [format]
      * @param {Attribution?} [attribution]
      */
-    retain(len: number, format?: FormattingAttributes | null, attribution?: Attribution | null): this;
+    retain(len: number, format?: Formats | null, attribution?: Attribution | null): this;
     /**
      * @param {number} len
      */
@@ -616,17 +782,16 @@ export class DeltaBuilder<Conf extends DeltaConf = {}, FixedConf extends boolean
      * @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 extends Extract<keyof DeltaConfGetAllowedAttrs<Conf, FixedConf>, string | number>, Val extends DeltaConfGetAllowedAttrs<Conf, FixedConf>[Key]>(key: Key, val: Val, attribution?: Attribution | null, prevValue?: Val | undefined): DeltaBuilder<DeltaConfOverwrite<Conf, {
+    setAttr<Key extends Extract<keyof DeltaConfGetAllowedAttrs<Conf, FixedConf>, string | number>, Val extends DeltaConfGetAllowedAttrs<Conf, FixedConf>[Key]>(key: Key, val: Val, attribution?: Attribution | null): DeltaBuilder<DeltaConfOverwrite<Conf, {
         attrs: AddToAttrs<DeltaConfGetAttrs<Conf>, Key, Val>;
     }>, FixedConf>;
     /**
      * @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> }
@@ -639,13 +804,12 @@ export class DeltaBuilder<Conf extends DeltaConf = {}, FixedConf extends boolean
     /**
      * @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 extends Extract<keyof DeltaConfGetAllowedAttrs<Conf, FixedConf>, string | number>>(key: Key, attribution?: Attribution | null, prevValue?: any): DeltaBuilder<DeltaConfOverwrite<Conf, {
+    deleteAttr<Key extends Extract<keyof DeltaConfGetAllowedAttrs<Conf, FixedConf>, string | number>>(key: Key, attribution?: Attribution | null): DeltaBuilder<DeltaConfOverwrite<Conf, {
         attrs: AddToAttrs<DeltaConfGetAttrs<Conf>, Key, never>;
     }>, FixedConf>;
     /**
@@ -653,16 +817,39 @@ export class DeltaBuilder<Conf extends DeltaConf = {}, FixedConf extends boolean
      * @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 extends DeltaConfGetAllowedAttrs<Conf, FixedConf> extends infer As ? { [K in keyof As]: Extract<As[K], DeltaAny> extends never ? never : K; }[keyof As] : never, D extends Extract<DeltaConfGetAllowedAttrs<Conf, FixedConf>[Key], DeltaAny>>(key: Key, modify: D): DeltaBuilder<DeltaConfOverwrite<Conf, {
+    modifyAttr<Key extends DeltaConfGetAllowedAttrs<Conf, FixedConf> extends infer As ? { [K in keyof As]: Extract<As[K], DeltaAny> extends never ? never : K; }[keyof As] : never, D extends Extract<DeltaConfGetAllowedAttrs<Conf, FixedConf>[Key], DeltaAny>>(key: Key, modify: D, attribution?: Attribution | null): DeltaBuilder<DeltaConfOverwrite<Conf, {
         attrs: AddToAttrs<DeltaConfGetAttrs<Conf>, Key, D>;
     }>, FixedConf>;
     /**
-     * @param {Delta<Conf>} other
-     */
-    apply(other: Delta<Conf>): this;
-    /**
+     * 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: Delta<Conf> | null, { final, move }?: {
+        final?: boolean;
+        move?: boolean;
+    }): DeltaBuilder<Conf>;
+    /**
+     * 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
      */
@@ -693,9 +880,14 @@ export class DeltaBuilder<Conf extends DeltaConf = {}, FixedConf extends boolean
         text: true;
     } : never)>, FixedConf>;
 }
+export function remapRootMarks(node: DeltaAny, mapKey: (key: number | string) => number | string | null): void;
+export function addRootMark(node: DeltaAny, mark: Mark): void;
+export function deleteRootMark(node: DeltaAny, id: string): void;
+export function mergeRootMarks(target: DeltaAny, source: DeltaAny, mapKey?: (key: number | string) => number | string | null): void;
 /**
  * @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<Conf extends DeltaConf> extends s.Schema<Delta<Conf>> {
     /**
@@ -730,40 +922,44 @@ export class $Delta<Conf extends DeltaConf> extends s.Schema<Delta<Conf>> {
         }>;
     };
 }
-export function $delta<NodeNameSchema extends s.Schema<string> | string | Array<string> = s.Schema<any>, AttrsSchema extends s.Schema<{
-    [key: string | number]: any;
-}> | {
-    [key: string | number]: any;
-} = s.Schema<{}>, ChildrenSchema extends unknown = s.Schema<never>, HasText extends boolean = false, RecursiveChildren extends boolean = false, Formats extends {
-    [k: string]: any;
-} = {
-    [k: string]: any;
-}>({ name, attrs, children, text, formats, recursiveChildren: recursive }: {
-    name?: NodeNameSchema | null | undefined;
-    attrs?: AttrsSchema | null | undefined;
-    children?: ChildrenSchema | null | undefined;
-    text?: HasText | undefined;
-    formats?: Formats | undefined;
-    recursiveChildren?: RecursiveChildren | undefined;
-}): [s.ReadSchemaUnwrapped<NodeNameSchema>, s.ReadSchemaUnwrapped<AttrsSchema>, s.ReadSchemaUnwrapped<ChildrenSchema>] extends [infer NodeName_1, infer Attrs_1, infer Children_1] ? s.Schema<Delta<PrettifyDeltaConf<(import("../ts.js").TypeIsAny<NodeName_1, {}, {
-    name: NodeName_1;
-}> & ({} extends Attrs_1 ? {} : {
-    attrs: Attrs_1;
-}) & ([Children_1] extends [never] ? {} : {
-    children: Children_1;
-}) & (HasText extends false ? {} : {
-    text: HasText;
-}) & (RecursiveChildren extends false ? {} : {
-    recursiveChildren: RecursiveChildren;
-})) extends infer DC extends DeltaConf ? DC : never>>> : never;
+/**
+ * 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 }>>>}
+ */
+export function $delta<Name extends string, Opts extends Omit<ReadableDeltaConf, "name"> = {}>(name: Name, opts?: Opts | undefined): s.Schema<Delta<ReadDeltaConf<Opts & {
+    name: Name;
+}>>>;
+/**
+ * @template {ReadableDeltaConf} [Conf={}]
+ * @overload
+ * @param {Conf} opts
+ * @return {s.Schema<Delta<ReadDeltaConf<Conf>>>}
+ */
+export function $delta<Conf extends ReadableDeltaConf = {}>(opts: Conf): s.Schema<Delta<ReadDeltaConf<Conf>>>;
 export const $$delta: s.Schema<$Delta<DeltaConf>>;
-export const $deltaAny: s.Schema<DeltaAny>;
+export const $deltaAny: s.Schema<Delta<any>>;
 export const $deltaBuilderAny: s.Schema<DeltaBuilderAny>;
-export function mergeAttrs<T extends {
+export function mergeAttributions<T extends {
+    [key: string]: any;
+}>(a: T | null, b: T | null): T | null;
+export function mergeFormats<T extends {
     [key: string]: any;
 }>(a: T | null, b: T | null): T | null;
 export function mergeDeltas<D extends DeltaAny | null>(a: D, b: D): D;
-export function random<Conf_1 extends DeltaConf>(gen: prng.PRNG, $d: s.Schema<Delta<Conf_1>>): DeltaBuilder<Conf_1>;
+export function random<Conf_1 extends DeltaConf>(gen: prng.PRNG, $d: s.Schema<Delta<Conf_1>>, conf?: {
+    source?: DeltaAny | null | undefined;
+    minChildOps?: number | undefined;
+    maxChildOps?: number | undefined;
+    attribution?: boolean | undefined;
+}): DeltaBuilder<Conf_1>;
 /**
  * @overload
  * @return {DeltaBuilder<{}>}
@@ -780,13 +976,13 @@ export function create<NodeName extends string | null>(nodeName: NodeName): Delt
 } : {}>;
 /**
  * @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}
  */
-export function create<NodeName extends string | null, Conf extends DeltaConf>(nodeName: NodeName, schema: s.Schema<Delta<Conf>>): DeltaBuilder<Conf, true>;
+export function create<NodeName extends string | null, Schema extends s.Schema<DeltaAny>>(nodeName: NodeName, schema: Schema): Schema extends s.Schema<Delta<infer Conf_1>> ? DeltaBuilder<Conf_1, true> : never;
 /**
  * @template {s.Schema<DeltaAny>} Schema
  * @overload
@@ -802,8 +998,7 @@ export function create<Schema extends s.Schema<DeltaAny>>(schema: Schema): Schem
  * @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
@@ -811,8 +1006,9 @@ export function create<Schema extends s.Schema<DeltaAny>>(schema: Schema): Schem
  */
 export function create<NodeName extends string | null, Attrs extends {
     [k: string | number]: any;
-} | null, Children extends Array<any> | string = never>(nodeName: NodeName, attrs: Attrs, children?: Children | undefined): DeltaBuilder<{
+} | null, Children extends Array<any> | string = never>(nodeName: NodeName, attrs: Attrs, children?: Children | undefined): 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;
@@ -823,14 +1019,14 @@ export function create<NodeName extends string | null, Attrs extends {
  * @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
  * }>}
  */
-export function from<NodeName extends string | null, Children extends Array<any> | string = never>(nodeName: NodeName, ...children: Array<Children>[]): DeltaBuilder<{
+export function from<NodeName extends string | null, Children extends Array<any> | string = never>(nodeName: NodeName, ...children: Array<Children>[]): 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;
 }>;
@@ -874,8 +1070,7 @@ export function from<Attrs extends {
  * @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
@@ -883,13 +1078,34 @@ export function from<Attrs extends {
  */
 export function from<NodeName extends string | null, Attrs extends {
     [k: string | number]: any;
-} | null, Children extends Array<any> | string = never>(nodeName: NodeName, attrs: Attrs, ...children: Array<Children>[]): DeltaBuilder<{
+} | null, Children extends Array<any> | string = never>(nodeName: NodeName, attrs: Attrs, ...children: Array<Children>[]): 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;
 }>;
-export function diff<Conf_1 extends DeltaConf>(d1: Delta<Conf_1>, d2: NoInfer<Delta<Conf_1>>): DeltaBuilder<Conf_1>;
+export function diff<Conf_1 extends DeltaConf>(d1: Delta<Conf_1>, d2: NoInfer<Delta<Conf_1>>, options?: DiffOptions): Delta<Conf_1>;
+export function inverse<Conf_1 extends DeltaConf>(d: DeltaAny, base: Delta<Conf_1>): Delta<Conf_1>;
+export function diffChangesetWithSeparator(changeset: Array<{
+    index: number;
+    remove: Array<any>;
+    insert: Array<any>;
+}>, separator: RegExp): any[];
+/**
+ * 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.
+ */
 export type Attribution = {
     insert?: string[];
     insertAt?: number;
@@ -898,14 +1114,33 @@ export type Attribution = {
     format?: Record<string, string[]>;
     formatAt?: number;
 };
-export type 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).
+ */
+export type Formats = {
     [key: string]: any;
 };
+export type MarkJSON = {
+    id: string;
+    key: number | string;
+    assoc: 1 | -1;
+    attrs?: object;
+};
 export type DeltaJSON = {
     type: "delta";
     name?: string;
     attrs?: { [Key in string | number]: DeltaAttrOpJSON; };
     children?: Array<DeltaListOpJSON>;
+    marks?: Array<MarkJSON>;
+    deleteMarks?: Array<string>;
 };
 export type DeltaListOpJSON = {
     type: "insert";
@@ -921,24 +1156,27 @@ export type DeltaListOpJSON = {
     retain: number;
     format?: {
         [key: string]: any;
-    };
-    attribution?: Attribution;
+    } | null;
+    attribution?: Attribution | null;
 } | {
     type: "modify";
     value: object;
+    format?: {
+        [key: string]: any;
+    } | null;
+    attribution?: Attribution | null;
 };
 export type DeltaAttrOpJSON = {
     type: "insert";
     value: any;
-    prevValue?: any;
     attribution?: Attribution;
 } | {
     type: "delete";
-    prevValue?: any;
     attribution?: Attribution;
 } | {
     type: "modify";
     value: DeltaJSON;
+    attribution?: Attribution | null;
 };
 export type ChildrenOpAny = TextOp | InsertOp<any> | DeleteOp | RetainOp | ModifyOp<any>;
 export type AttrOpAny = SetAttrOp<any> | DeleteAttrOp<any> | ModifyAttrOp;
@@ -958,9 +1196,16 @@ export type DeltaConf = {
     recursiveChildren?: boolean | undefined;
     recursiveAttrs?: boolean | undefined;
 };
+/**
+ * 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.
+ */
+export type AsDeltaConf<T> = T extends infer DC extends DeltaConf ? DC : never;
 export type DeltaConfGetName<Conf_1 extends DeltaConf> = Conf_1 extends {
-    name: infer Name;
-} ? (unknown extends Name ? any : (Exclude<Name, undefined>)) : any;
+    name: infer Name_1;
+} ? (unknown extends Name_1 ? any : (Exclude<Name_1, undefined>)) : any;
 export type DeltaConfGetChildren<Conf_1 extends DeltaConf> = (Conf_1 extends {
     children: infer Children_1;
 } ? (unknown extends Children_1 ? any : Children_1) : never) | (Conf_1 extends {
@@ -990,6 +1235,61 @@ export type DeltaConfigGetRecursiveAttrs<Conf_1 extends DeltaConf> = Conf_1 exte
 export type _SanifyDelta<V> = V extends never ? never : (import("../ts.js").TypeIsAny<V, any, V extends Delta<infer Conf_1> ? Delta<Conf_1> : V>);
 export type PrettifyDeltaConf<Conf_1 extends DeltaConf> = import("../ts.js").Prettify<{ [K in keyof Conf_1]: K extends "attrs" ? import("../ts.js").Prettify<{ [KA in keyof Conf_1[K]]: _SanifyDelta<Conf_1[K][KA]>; }, 1> : (K extends "children" ? _SanifyDelta<Conf_1[K]> : Conf_1[K]); }, 1>;
 export type DeltaConfOverwrite<D1 extends DeltaConf, D2> = (import("../ts.js").TypeIsAny<D1, any, PrettifyDeltaConf<{ [K in (keyof D1 | keyof D2)]: K extends keyof D2 ? D2[K] : (K extends keyof D1 ? D1[K] : never); }>> & {}) extends infer DC extends DeltaConf ? DC : never;
+export type ReadableDeltaConf = {
+    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;
+    };
+};
+/**
+ * Transforms a ReadableDeltaConf (the input shape of `$delta(spec)`) to a DeltaConf.
+ */
+export type ReadDeltaConf<DConfSpec extends ReadableDeltaConf> = [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_1, infer Attrs_1, infer Children_1] ? AsDeltaConf<PrettifyDeltaConf<(import("../ts.js").TypeIsAny<NodeName_1, {}, {
+    name: NodeName_1;
+}> & ([keyof Attrs_1] extends [never] ? {} : {
+    attrs: Attrs_1;
+}) & ([Children_1] extends [never] ? {} : {
+    children: Children_1;
+}) & (DConfSpec extends {
+    text: true;
+} ? {
+    text: true;
+} : {}) & (DConfSpec extends {
+    recursiveChildren: true;
+} ? {
+    recursiveChildren: true;
+} : {}))>> : never;
+export type DiffOptions = {
+    /**
+     * 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)`.
+     */
+    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';
 import * as equalityTrait from '../trait/equality.js';
@@ -1005,6 +1305,67 @@ import * as fingerprintTrait from '../trait/fingerprint.js';
  * @template {{[Key in string|number|symbol]: any}} NewAttrs
  * @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}.
+ */
+declare 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: number | string, id?: string, assoc?: 1 | -1, attrs?: object | null);
+    /**
+     * @readonly
+     * @type {number|string}
+     */
+    readonly key: number | string;
+    /**
+     * @readonly
+     * @type {string}
+     */
+    readonly id: string;
+    /**
+     * @readonly
+     * @type {1|-1}
+     */
+    readonly assoc: 1 | -1;
+    /**
+     * @readonly
+     * @type {object?}
+     */
+    readonly attrs: object | null;
+    /**
+     * 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?: number | string): Mark;
+    /**
+     * @return {MarkJSON}
+     */
+    toJSON(): MarkJSON;
+    $type: s.Schema<Mark>;
+    /**
+     * @param {Mark} other
+     */
+    [equalityTrait.EqualityTraitSymbol](other: Mark): boolean;
+}
 /**
  * @typedef {Delta<any>} DeltaAny
  */
@@ -1020,6 +1381,15 @@ import * as fingerprintTrait from '../trait/fingerprint.js';
  * @property {boolean} [DeltaConf.recursiveChildren=false]
  * @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
@@ -1098,6 +1468,9 @@ declare class DeltaData<Name extends string, Attrs extends { [K in string | numb
      * >}
      */
     children: list.List<(Text extends true ? (RetainOp | TextOp | DeleteOp<any>) : never) | (RetainOp | InsertOp<Children> | DeleteOp<any> | (Delta extends Children ? ModifyOp<Extract<Children, Delta>> : never))>;
+    /**
+     * All child-ops sizes combined. Note that delete-ops also have a length
+     */
     childCnt: number;
     /**
      * @type {any}
@@ -1108,7 +1481,72 @@ declare class DeltaData<Name extends string, Attrs extends { [K in string | numb
      */
     _fingerprint: string | null;
     isDone: boolean;
+    /**
+     * Is the final document and does not contain delete, modify, or retain ops.
+     */
+    isFinal: boolean;
+    /**
+     * 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?}
+     */
+    marks: 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>?}
+     */
+    deleteMarks: Set<string> | 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*.
+     */
+    maybeHasMarks: boolean;
 }
 import * as prng from '../prng.js';
+/**
+ * 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.
+ */
+declare class Marks {
+    /**
+     * @type {Array<Mark>}
+     */
+    _marks: Array<Mark>;
+    get size(): number;
+    /**
+     * 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: Mark): boolean;
+    /**
+     * Remove the mark with `id`. Returns `true` if a mark was present and removed, `false` if absent.
+     *
+     * @param {string} id
+     * @return {boolean}
+     */
+    delete(id: string): boolean;
+    [Symbol.iterator](): ArrayIterator<Mark>;
+}
 export {};
 //# sourceMappingURL=delta.d.ts.map