lib0 1.0.0-rc.15 → 1.0.0-rc.17

package/dist/delta/delta.d.ts

@@ -15,19 +15,24 @@ 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
  */
 /**
  * @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', value: any, prevValue?: any, attribution?: Attribution } | { type: 'delete', prevValue?: any, attribution?: Attribution } | { type: 'modify', value: DeltaJSON }} DeltaAttrOpJSON
+ * @typedef {{ type: 'insert', value: any, prevValue?: any, attribution?: Attribution } | { type: 'delete', prevValue?: any, attribution?: Attribution } | { type: 'modify', value: DeltaJSON, attribution?: Attribution }} DeltaAttrOpJSON
  */
 /**
  * @typedef {TextOp|InsertOp<any>|DeleteOp|RetainOp|ModifyOp<any>} ChildrenOpAny
@@ -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,13 +485,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?} attribution
      */
-    constructor(key: K, delta: Modifier);
+    constructor(key: K, delta: Modifier, attribution: Attribution | null);
     /**
      * @readonly
      * @type {K}
@@ -456,6 +504,11 @@ export class ModifyAttrOp<Modifier extends DeltaAny = DeltaAny, K extends string
      * @type {Modifier}
      */
     readonly value: Modifier;
+    /**
+     * @readonly
+     * @type {Attribution?}
+     */
+    readonly attribution: Attribution | null;
     /**
      * @type {string|null}
      */
@@ -474,6 +527,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 +543,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 +608,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 +680,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]
@@ -668,9 +757,10 @@ 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
      * @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>;
     /**
@@ -687,11 +777,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 +820,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 +862,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>;
@@ -779,6 +898,7 @@ export function random<Conf_1 extends DeltaConf>(gen: prng.PRNG, $d: s.Schema<De
     source?: DeltaAny | null | undefined;
     minChildOps?: number | undefined;
     maxChildOps?: number | undefined;
+    attribution?: boolean | undefined;
 }): DeltaBuilder<Conf_1>;
 /**
  * @overload
@@ -796,13 +916,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
@@ -922,11 +1042,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";
@@ -960,6 +1088,7 @@ export type DeltaAttrOpJSON = {
 } | {
     type: "modify";
     value: DeltaJSON;
+    attribution?: Attribution;
 };
 export type ChildrenOpAny = TextOp | InsertOp<any> | DeleteOp | RetainOp | ModifyOp<any>;
 export type AttrOpAny = SetAttrOp<any> | DeleteAttrOp<any> | ModifyAttrOp;
@@ -987,8 +1116,8 @@ export type DeltaConf = {
  */
 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 {
@@ -1079,6 +1208,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
  */
@@ -1198,7 +1388,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

package/dist/delta/position.d.ts

@@ -0,0 +1,65 @@
+/**
+ * A single step of a {@link Pos} path: a `string` attribute key, or a `number` content index.
+ *
+ * @typedef {string|number} PosStep
+ */
+/**
+ * A location in a delta tree. `path` descends from the node the position is relative to and ends in
+ * the terminal (a trailing-number cursor gap, or a trailing-string attribute leaf). `assoc` is the
+ * gravity at a boundary: `-1` binds to the preceding content, `1` to the following content. `attrs` is
+ * optional immutable user data carried with the position (e.g. an RDT's clientID/user metadata); it is
+ * stored on the {@link import('./delta.js').createMark mark} when the position is written with
+ * {@link import('./delta.js').DeltaBuilder#addMark} and read back by {@link marksToPositions}.
+ *
+ * @typedef {{ path: Array<PosStep>, assoc: -1|1, attrs?: object|null }} Pos
+ */
+/**
+ * A {@link Pos} tagged with the unique id of a stored {@link import('./delta.js').createMark mark} —
+ * what {@link marksToPositions} returns (its `attrs` is the mark's stored metadata). Add marks with
+ * {@link import('./delta.js').DeltaBuilder#addMark}.
+ *
+ * @typedef {{ id: string } & Pos} MarkPos
+ */
+/**
+ * Schema for a {@link Pos}.
+ *
+ * @type {s.Schema<Pos>}
+ */
+export const $pos: s.Schema<Pos>;
+export function create(path: Array<PosStep>, assoc?: -1 | 1, attrs?: object | null): Pos;
+export function equals(a: Pos | MarkPos, b: Pos | MarkPos): boolean;
+/**
+ * Schema for a {@link MarkPos}.
+ *
+ * @type {s.Schema<MarkPos>}
+ */
+export const $markPos: s.Schema<MarkPos>;
+export function marksToPositions(d: delta.DeltaAny): Array<MarkPos>;
+/**
+ * A single step of a {@link Pos} path: a `string` attribute key, or a `number` content index.
+ */
+export type PosStep = string | number;
+/**
+ * A location in a delta tree. `path` descends from the node the position is relative to and ends in
+ * the terminal (a trailing-number cursor gap, or a trailing-string attribute leaf). `assoc` is the
+ * gravity at a boundary: `-1` binds to the preceding content, `1` to the following content. `attrs` is
+ * optional immutable user data carried with the position (e.g. an RDT's clientID/user metadata); it is
+ * stored on the {@link import ('./delta.js').createMark mark} when the position is written with
+ * {@link import ('./delta.js').DeltaBuilder#addMark} and read back by {@link marksToPositions}.
+ */
+export type Pos = {
+    path: Array<PosStep>;
+    assoc: -1 | 1;
+    attrs?: object | null;
+};
+/**
+ * A {@link Pos} tagged with the unique id of a stored {@link import ('./delta.js').createMark mark} —
+ * what {@link marksToPositions} returns (its `attrs` is the mark's stored metadata). Add marks with
+ * {@link import ('./delta.js').DeltaBuilder#addMark}.
+ */
+export type MarkPos = {
+    id: string;
+} & Pos;
+import * as s from '../schema.js';
+import * as delta from './delta.js';
+//# sourceMappingURL=position.d.ts.map