lib0 1.0.0-rc.14 → 1.0.0-rc.16

package/dist/delta/delta.d.ts

@@ -15,12 +15,17 @@ export const $attribution: s.Schema<Attribution>;
 /**
  * @typedef {{ [key: string]: any }} FormattingAttributes
  */
+/**
+ * @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
  */
 /**
@@ -57,6 +62,8 @@ export const $deltaMapChangeJson: s.Schema<DeltaAttrOpJSON>;
  *   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 {
     /**
@@ -102,9 +109,13 @@ 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
@@ -113,6 +124,7 @@ 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 {
     /**
@@ -167,9 +179,15 @@ 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
@@ -178,6 +196,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 {
     /**
@@ -209,17 +228,22 @@ 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
+     * cloned delete carries no prevValue).
      * @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
@@ -263,7 +287,14 @@ 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
@@ -274,6 +305,7 @@ 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 {
     /**
@@ -323,9 +355,13 @@ 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
@@ -335,6 +371,7 @@ 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> {
     /**
@@ -379,13 +416,16 @@ 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>;
@@ -398,6 +438,7 @@ 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> {
     /**
@@ -429,6 +470,11 @@ 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>>;
     /**
@@ -439,6 +485,7 @@ 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> {
     /**
@@ -474,6 +521,8 @@ 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>;
@@ -488,15 +537,17 @@ 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<Delta<any>>>;
+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>>;
 export const $deleteAttrOp: s.Schema<DeleteAttrOp<any>>;
-export const $anyAttrOp: s.Schema<SetAttrOp<any, any> | DeleteAttrOp<any, string | number> | ModifyAttrOp<any, string>>;
+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<
@@ -551,6 +602,14 @@ 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 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]
@@ -615,6 +674,30 @@ export class DeltaBuilder<Conf extends DeltaConf = {}, FixedConf extends boolean
     modify<NewContent extends Extract<DeltaConfGetAllowedChildren<Conf, FixedConf>, Delta | DeltaData<any, any, any, any> | DeltaBuilder>>(modify: NewContent, formatting?: FormattingAttributes | 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]
@@ -687,11 +770,14 @@ export class DeltaBuilder<Conf extends DeltaConf = {}, FixedConf extends boolean
      * attribute). Any kind of `delete` op might be considered a bug. A final delta is not idempotent.
      *
      * @param {Delta<Conf>?} other
-     * @param {{ final?: boolean }} opts -- (experimental)
+     * @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 }?: {
+    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
@@ -727,9 +813,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>> {
     /**
@@ -764,7 +855,28 @@ export class $Delta<Conf extends DeltaConf> extends s.Schema<Delta<Conf>> {
         }>;
     };
 }
-export function $delta<DeltaConf extends ReadableDeltaConf = {}>({ name, attrs, children, text, formats, recursiveChildren: recursive }: DeltaConf): s.Schema<Delta<ReadDeltaConf<DeltaConf>>>;
+/**
+ * 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<Delta<any>>;
 export const $deltaBuilderAny: s.Schema<DeltaBuilderAny>;
@@ -796,13 +908,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
@@ -818,8 +930,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
@@ -827,8 +938,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;
@@ -839,14 +951,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;
 }>;
@@ -890,8 +1002,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
@@ -899,13 +1010,14 @@ 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>>): Delta<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 diffChangesetWithSeparator(changeset: Array<{
     index: number;
     remove: Array<any>;
@@ -922,11 +1034,19 @@ export type Attribution = {
 export type FormattingAttributes = {
     [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";
@@ -979,9 +1099,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 {
@@ -1034,7 +1161,7 @@ export type ReadDeltaConf<DConfSpec extends ReadableDeltaConf> = [DConfSpec exte
     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] ? PrettifyDeltaConf<(import("../ts.js").TypeIsAny<NodeName_1, {}, {
+} ? 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;
@@ -1048,7 +1175,15 @@ export type ReadDeltaConf<DConfSpec extends ReadableDeltaConf> = [DConfSpec exte
     recursiveChildren: true;
 } ? {
     recursiveChildren: true;
-} : {})) extends infer DC extends DeltaConf ? DC : never> : never;
+} : {}))>> : 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;
+};
 import * as s from '../schema.js';
 import * as list from '../list.js';
 import * as equalityTrait from '../trait/equality.js';
@@ -1064,6 +1199,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
  */
@@ -1079,6 +1275,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
@@ -1174,7 +1379,68 @@ declare class DeltaData<Name extends string, Attrs extends { [K in string | numb
      * 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