edytor 0.0.11 → 0.1.0-next.16

package/dist/crdt/rangeDelete.d.ts

@@ -0,0 +1,85 @@
+/**
+ * Range deletion between two positions — one prepared document operation
+ * (R6) whose merge is the document's `canMerge` (R5). The rules are the
+ * `del.range.*` rows of `docs/editor-delete-contract.md`:
+ *
+ * - the head keeps `[0, start)`, the tail keeps `[end, len)`, and every
+ *   block strictly between them in document order dies;
+ * - the head dies iff its prefix is empty (never for a replacement,
+ *   `del.range.replace`, nor when nothing else would be left to hold the
+ *   caret, `del.range.whole-doc`: the head is kept, emptied, with its id,
+ *   type and data, so peers deleting the same range keep the same block)
+ *   and the tail then keeps its id; the tail dies iff
+ *   its suffix is empty; otherwise the tail's suffix merges into the head
+ *   when `canMerge(tail, head)` allows it (`del.range.island-seal`) — an end
+ *   at the tail's start included: the seam between them is deleted;
+ * - what follows the range end survives: the dying tail's children and the
+ *   later siblings inside every container the range dies through take the
+ *   topmost such container's slot, unless that would cross an island seal —
+ *   then those containers stay (`del.range.outside-survives`);
+ * - a container (a list: the document's `isContainer`) never dies because
+ *   the range starts before it: it keeps what follows the range end, like
+ *   the keys (`del.merge.container`); it dies only when it loses every
+ *   child and holds no text of its own — the document's `emptiable`, the
+ *   keys' rule (`del.range.empty-container`, ZW-05). An island that renders
+ *   no content dies when it loses every child too, except a `lines` island
+ *   (a code block) the range lies in: its head is then kept, emptied
+ *   (`del.range.island-kept`);
+ * - what a range rescues takes the kind it shows in its new slot (the
+ *   document's `settle`: a paragraph rescued into a list is its item);
+ * - blocks the view hides (a closed toggle's body) are not in the range:
+ *   they go only with a block that goes, so a surviving head keeps its
+ *   hidden children, unless it is kept only to hold the caret; a dying
+ *   closed tail's body takes its place, shown (`del.range.hidden-body`);
+ * - the plan's `at` is where the caret lands (`del.range.caret`).
+ */
+import type { BlockId, Destination } from './placement/model.js';
+import type { Plan, PlanStep, Prepared } from './edytor-doc.js';
+/** A position in one document version: a block and a display offset (R4). */
+export type DocPosition = {
+    block: BlockId;
+    offset: number;
+};
+/** What range deletion reads from the document and the step writers it composes. */
+export type RangeDeleteContext = {
+    ref: (id: BlockId) => BlockId;
+    refused: Prepared;
+    plan: (ids: readonly BlockId[], writes: PlanStep[]) => Plan;
+    order: () => {
+        ids: readonly BlockId[];
+        at: ReadonlyMap<BlockId, number>;
+    };
+    positionOf: (id: BlockId) => Destination | null;
+    /** Display ancestors, nearest first (the root excluded). */
+    ancestorsOf: (id: BlockId) => BlockId[];
+    childrenIds: (parent: BlockId | null) => BlockId[];
+    displayLength: (id: BlockId) => number;
+    /** Live, with its own content node. */
+    contentTarget: (id: BlockId) => boolean;
+    rendersContent: (id: BlockId) => boolean;
+    canMerge: (from: BlockId, into: BlockId) => boolean;
+    isIsland: (id: BlockId) => boolean;
+    /** An island declared `lines` (a code block): it holds only lines. */
+    isLines: (id: BlockId) => boolean;
+    move: (ids: BlockId[], parent: BlockId | null, index: number) => PlanStep[];
+    /** A block that shows only its children: a list, a table row, a column. */
+    isContainer: (id: BlockId) => boolean;
+    /** A container that goes once it loses every child (it holds no text of its own). */
+    emptiable: (id: BlockId) => boolean;
+    /** The kind steps for `from`'s children `kids` landing under `parent` (island and container rules). */
+    settle: (from: BlockId | null, kids: readonly BlockId[], parent: BlockId | null) => PlanStep[];
+    remove: (id: BlockId, kept: readonly BlockId[]) => PlanStep;
+};
+/**
+ * What the view knows of a range (view state the document does not hold):
+ * whether it hides a block, and, given `removed`, whether the block stays
+ * hidden once those go (a removed closed toggle's children take its place, shown).
+ */
+export type RangeView = {
+    hidden?: (id: BlockId, removed?: ReadonlySet<BlockId>) => boolean;
+};
+/** `deleteRange` and `replaceRange` (the head kept), prepared. */
+export declare const rangeDeleteOps: (c: RangeDeleteContext) => {
+    deleteRange: (from: DocPosition, to: DocPosition, view?: RangeView) => Prepared;
+    replaceRange: (from: DocPosition, to: DocPosition, view?: RangeView) => Prepared;
+};

package/dist/crdt/rangeDelete.js

@@ -0,0 +1,126 @@
+/** `deleteRange` and `replaceRange` (the head kept), prepared. */
+export const rangeDeleteOps = (c) => {
+    // `headSpent`: a whole-doc retry keeps the head, but what it hid goes as if it went.
+    const prepare = (keepHead, headSpent = false) => (from, to, view = {}) => {
+        // A position names shown text: a live block that renders its own content.
+        const holds = (id) => c.contentTarget(id) && c.rendersContent(id);
+        const pos = (p) => {
+            const block = c.ref(p.block);
+            const len = holds(block) ? c.displayLength(block) : -1;
+            return { block, offset: Math.max(0, Math.min(p.offset, len)) };
+        };
+        let [s, e] = [pos(from), pos(to)];
+        if (!holds(s.block) || !holds(e.block))
+            return c.refused;
+        const { ids, at } = c.order();
+        if (at.get(s.block) > at.get(e.block) || (s.block === e.block && s.offset > e.offset))
+            [s, e] = [e, s];
+        const S = s.block;
+        const E = e.block;
+        if (S === E) {
+            const length = e.offset - s.offset;
+            const writes = length > 0 ? [{ op: 'deleteText', id: S, offset: s.offset, length }] : [];
+            return { ...c.plan([S], writes), at: s };
+        }
+        const parent = (id) => c.ancestorsOf(id)[0] ?? null;
+        const chain = c.ancestorsOf(E);
+        // What the view hides once `removed` go (nothing: as it is now).
+        const hiddenOnce = (removed) => {
+            const set = new Set(removed);
+            return (id) => !!view.hidden?.(id, set);
+        };
+        const headDies = !keepHead && s.offset === 0;
+        // What the view hides is not in the range: it goes only with a block that goes,
+        // a dying head's body included.
+        const hidden = hiddenOnce(headDies || headSpent ? [S] : []);
+        const between = ids.slice(at.get(S) + 1, at.get(E)).filter((id) => !hidden(id));
+        const lenE = c.displayLength(E);
+        const tailDies = e.offset === lenE;
+        const merges = !headDies && !tailDies && c.canMerge(E, S);
+        const tailGone = tailDies || merges;
+        // E's ancestors the range starts before die unless the rescue would cross an island.
+        // A container (a list) is not one: it dies only when the range empties it, and
+        // keeps its later items like the keys do (`del.merge.container`, DR-crdt-4).
+        const partial = chain.filter((a) => (a === (headDies ? S : null) || between.includes(a)) && !c.isContainer(a));
+        const top = partial.at(-1);
+        const sealed = top !== undefined && chain.slice(0, chain.indexOf(top) + 1).some(c.isIsland);
+        const spared = new Set(sealed ? chain : []);
+        const doomed = new Set(between.filter((id) => !spared.has(id) && !chain.includes(id)));
+        if (!sealed)
+            partial.forEach((a) => doomed.add(a));
+        if (headDies && !spared.has(S))
+            doomed.add(S);
+        if (tailDies)
+            doomed.add(E);
+        // Rescue what follows the range end right after the topmost dying container's slot
+        // (after, not at it: a concurrent delete of S revives a merged E above them, UW-20).
+        const home = sealed || top === undefined ? (tailGone ? E : undefined) : top;
+        const rescued = home === undefined ? [] : tailGone ? c.childrenIds(E) : [E];
+        for (let cur = E; home !== undefined && cur !== home; cur = parent(cur)) {
+            const sibs = c.childrenIds(parent(cur));
+            rescued.push(...sibs.slice(sibs.indexOf(cur) + 1));
+        }
+        const dest = home === undefined || rescued.length === 0 ? null : c.positionOf(home);
+        // A container (or an island that renders nothing) losing every child dies too.
+        const gone = (id) => doomed.has(id) || (merges && id === E);
+        const dies = (id) => c.emptiable(id) || (c.isIsland(id) && !c.rendersContent(id));
+        const emptied = (id) => {
+            if (id === null || gone(id) || !dies(id) || id === dest?.parent)
+                return;
+            if (!c.childrenIds(id).every(gone))
+                return;
+            doomed.add(id);
+            emptied(parent(id));
+        };
+        [...doomed, ...(merges ? [E] : [])].forEach((id) => emptied(parent(id)));
+        // A range inside one `lines` island never removes it: the head stays, emptied
+        // (a code block's Mod+A, `del.range.island-kept`).
+        const island = c.ancestorsOf(S).find(c.isIsland);
+        const linesIsland = island !== undefined && c.isLines(island);
+        if (!keepHead && linesIsland && doomed.has(island) && chain.includes(island))
+            return prepare(true, headDies)(from, to, view);
+        const lenS = c.displayLength(S);
+        const writes = [];
+        if (!doomed.has(S) && lenS > s.offset)
+            writes.push({ op: 'deleteText', id: S, offset: s.offset, length: lenS - s.offset });
+        if (!gone(E) && e.offset > 0)
+            writes.push({ op: 'deleteText', id: E, offset: 0, length: e.offset });
+        if (dest !== null) {
+            writes.push(...c.move(rescued, dest.parent, dest.index + 1));
+            // Each shows the kind of its new slot (an island's line, a list's item leave theirs).
+            for (const id of rescued)
+                writes.push(...c.settle(parent(id), [id], dest.parent));
+        }
+        if (merges) {
+            // The whole tail merges, then its cut prefix goes: E's own text is never written.
+            writes.push({ op: 'mergeBlocks', from: E, into: S, at: s.offset, length: lenE });
+            if (e.offset > 0)
+                writes.push({ op: 'deleteText', id: S, offset: s.offset, length: e.offset });
+        }
+        const kept = [...rescued, ...(merges ? [E] : [])];
+        for (const id of doomed)
+            if (!doomed.has(parent(id)))
+                writes.push(c.remove(id, kept));
+        const caret = (() => {
+            if (!doomed.has(S))
+                return s;
+            if (!gone(E))
+                return { block: E, offset: 0 };
+            const survives = (id) => id === null || rescued.includes(id) || (!gone(id) && survives(parent(id)));
+            // Shown once the plan runs: a dying closed tail's rescued body is.
+            const hiddenAfter = hiddenOnce([...doomed, ...(merges ? [E] : [])]);
+            const shown = (id) => survives(id) && holds(id) && !hiddenAfter(id);
+            // Before the tail: blocks a sealed rescue spared between S and E count too.
+            const prev = ids.slice(0, at.get(E)).findLast(shown);
+            if (prev !== undefined)
+                return { block: prev, offset: c.displayLength(prev) };
+            const next = ids.slice(at.get(E) + 1).find(shown);
+            return next === undefined ? null : { block: next, offset: 0 };
+        })();
+        // Nothing else left to hold the caret: the head stays, emptied (whole-doc).
+        if (caret === null)
+            return prepare(true, headDies)(from, to, view);
+        return { ...c.plan([caret.block], writes), at: caret };
+    };
+    return { deleteRange: prepare(false), replaceRange: prepare(true) };
+};

package/dist/crdt/schema.d.ts

@@ -0,0 +1,96 @@
+/**
+ * Schema names — the one table (O20): every root key, node role and attr name
+ * a document carries, plus the generation stamp written on `meta`. A
+ * dependency-free leaf, so every model layer reads it without importing the
+ * facade module.
+ */
+import type { EngineNode } from './engine-api.js';
+/** A replicated value that is a node (a block, its content, claims or `at` map, an atom). */
+export declare const isNodeLike: (v: unknown) => v is EngineNode;
+/** Flat block registry root: blockId → node('block') (`SCHEMA.roots.registry`). */
+export declare const REGISTRY_KEY = "blocks";
+/** Version/manifest record root (`SCHEMA.roots.meta`). */
+export declare const META_ROOT_KEY = "meta";
+/** Attribution metadata root (`SCHEMA.roots.attribution`). */
+export declare const ATTRIBUTION_ROOT = "attribution";
+/** U1 per-block attribution root — `b/<blockId>` records (`SCHEMA.roots.blockAttribution`). */
+export declare const BLOCK_ATTR_ROOT = "blockattr";
+/**
+ * Per-writer text delete marks (`text/deletes.ts`): one record per text
+ * delete, naming the characters it deleted; its writer is the record's
+ * engine client. In the history's scope, so an undo removes the undoer's
+ * own mark and a redo writes it again.
+ */
+export declare const TEXT_DELETES_ROOT = "textdel";
+/**
+ * Restoration records (`text/deletes.ts`): which characters an undo's copies
+ * restore, one attr per record (keyed by its writer and clock). Outside the
+ * history's scope: a record is never removed.
+ */
+export declare const RESTORED_ROOT = "restored";
+/**
+ * The document's own data (`crdt/data.ts`): its leaves, as a block's. In the
+ * history's scope.
+ */
+export declare const DOC_DATA_ROOT = "docdata";
+/** Named node roles (`SCHEMA.nodes`). */
+export declare const BLOCK_NODE = "block";
+export declare const CONTENT_NODE = "content";
+export declare const CLAIMS_NODE = "claims";
+export declare const AT_NODE = "at";
+export declare const INLINE_NODE = "inline";
+/** Attr keys on a block node (`SCHEMA.blockAttrs`). */
+export declare const ID = "id";
+export declare const TYPE = "type";
+/** A block's or atom's whole data: the legacy layer, read under the leaves and exploded by the first patch. */
+export declare const DATA = "data";
+/** A data leaf: `d/` and its path, RFC 6901 escaped (`crdt/data.ts`). */
+export declare const DATA_LEAF_PREFIX = "d/";
+/**
+ * Incarnation nonce (O23, §2.1): which creation of a (recyclable) block id a
+ * node is — and which stream boundary `{s, n}` starts the block's stream.
+ * Written at creation (random from the `rand` seam, derived from the seed
+ * hash for seeded blocks) and re-minted, derived from the dead incarnation,
+ * when a streamless block gets its own text; replicated, so an undo/redo copy
+ * of the node carries it and every replica agrees on the incarnation.
+ */
+export declare const NONCE = "n";
+/**
+ * Per-writer delete marks (R3): `del.<writer>: true`. A block is deleted iff
+ * any mark is live, so an undo removes only the undoer's own mark.
+ */
+export declare const DEL_PREFIX = "del.";
+export declare const hasDeleteMark: (node: {
+    attrKeys(): IterableIterator<string>;
+}) => boolean;
+/**
+ * Per-writer withdraw marks (`hist.undo.withdraw`): `wd.<writer>: true`, what
+ * an undo of the block's creation writes instead of deleting the node. A
+ * withdrawn block without a delete mark is visible while it holds content
+ * (a live unit in its stream, or a visible child), hidden otherwise.
+ */
+export declare const WITHDRAW_PREFIX = "wd.";
+export declare const hasWithdrawMark: (node: {
+    attrKeys(): IterableIterator<string>;
+}) => boolean;
+/** U1 `lastChangedBy` LWW attr (`SCHEMA.blockAttrs.lastChanged`). */
+export declare const LAST_CHANGED_ATTR = "l";
+export declare const CONTENT = "content";
+/** Ordered merge claims `{m: blockId}` (R2). */
+export declare const CLAIMS = "claims";
+export declare const AT = "at";
+/** `b/<blockId>` record-key prefix on the `blockattr` root. */
+export declare const REC_PREFIX = "b/";
+/** The schema generation stamped on the `meta` root (`v`) and its manifest name (`schema`). */
+export declare const SCHEMA: {
+    readonly version: 4;
+    readonly name: "edytor-doc";
+    readonly roots: {
+        readonly registry: "blocks";
+        readonly meta: "meta";
+    };
+    readonly metaAttrs: {
+        readonly version: "v";
+        readonly schema: "schema";
+    };
+};

package/dist/crdt/schema.js

@@ -0,0 +1,79 @@
+/** A replicated value that is a node (a block, its content, claims or `at` map, an atom). */
+export const isNodeLike = (v) => v != null && typeof v.getAttr === 'function';
+/** Flat block registry root: blockId → node('block') (`SCHEMA.roots.registry`). */
+export const REGISTRY_KEY = 'blocks';
+/** Version/manifest record root (`SCHEMA.roots.meta`). */
+export const META_ROOT_KEY = 'meta';
+/** Attribution metadata root (`SCHEMA.roots.attribution`). */
+export const ATTRIBUTION_ROOT = 'attribution';
+/** U1 per-block attribution root — `b/<blockId>` records (`SCHEMA.roots.blockAttribution`). */
+export const BLOCK_ATTR_ROOT = 'blockattr';
+/**
+ * Per-writer text delete marks (`text/deletes.ts`): one record per text
+ * delete, naming the characters it deleted; its writer is the record's
+ * engine client. In the history's scope, so an undo removes the undoer's
+ * own mark and a redo writes it again.
+ */
+export const TEXT_DELETES_ROOT = 'textdel';
+/**
+ * Restoration records (`text/deletes.ts`): which characters an undo's copies
+ * restore, one attr per record (keyed by its writer and clock). Outside the
+ * history's scope: a record is never removed.
+ */
+export const RESTORED_ROOT = 'restored';
+/**
+ * The document's own data (`crdt/data.ts`): its leaves, as a block's. In the
+ * history's scope.
+ */
+export const DOC_DATA_ROOT = 'docdata';
+/** Named node roles (`SCHEMA.nodes`). */
+export const BLOCK_NODE = 'block';
+export const CONTENT_NODE = 'content';
+export const CLAIMS_NODE = 'claims';
+export const AT_NODE = 'at';
+export const INLINE_NODE = 'inline';
+/** Attr keys on a block node (`SCHEMA.blockAttrs`). */
+export const ID = 'id';
+export const TYPE = 'type';
+/** A block's or atom's whole data: the legacy layer, read under the leaves and exploded by the first patch. */
+export const DATA = 'data';
+/** A data leaf: `d/` and its path, RFC 6901 escaped (`crdt/data.ts`). */
+export const DATA_LEAF_PREFIX = 'd/';
+/**
+ * Incarnation nonce (O23, §2.1): which creation of a (recyclable) block id a
+ * node is — and which stream boundary `{s, n}` starts the block's stream.
+ * Written at creation (random from the `rand` seam, derived from the seed
+ * hash for seeded blocks) and re-minted, derived from the dead incarnation,
+ * when a streamless block gets its own text; replicated, so an undo/redo copy
+ * of the node carries it and every replica agrees on the incarnation.
+ */
+export const NONCE = 'n';
+/**
+ * Per-writer delete marks (R3): `del.<writer>: true`. A block is deleted iff
+ * any mark is live, so an undo removes only the undoer's own mark.
+ */
+export const DEL_PREFIX = 'del.';
+export const hasDeleteMark = (node) => [...node.attrKeys()].some((key) => key.startsWith(DEL_PREFIX));
+/**
+ * Per-writer withdraw marks (`hist.undo.withdraw`): `wd.<writer>: true`, what
+ * an undo of the block's creation writes instead of deleting the node. A
+ * withdrawn block without a delete mark is visible while it holds content
+ * (a live unit in its stream, or a visible child), hidden otherwise.
+ */
+export const WITHDRAW_PREFIX = 'wd.';
+export const hasWithdrawMark = (node) => [...node.attrKeys()].some((key) => key.startsWith(WITHDRAW_PREFIX));
+/** U1 `lastChangedBy` LWW attr (`SCHEMA.blockAttrs.lastChanged`). */
+export const LAST_CHANGED_ATTR = 'l';
+export const CONTENT = 'content';
+/** Ordered merge claims `{m: blockId}` (R2). */
+export const CLAIMS = 'claims';
+export const AT = 'at';
+/** `b/<blockId>` record-key prefix on the `blockattr` root. */
+export const REC_PREFIX = 'b/';
+/** The schema generation stamped on the `meta` root (`v`) and its manifest name (`schema`). */
+export const SCHEMA = {
+    version: 4,
+    name: 'edytor-doc',
+    roots: { registry: REGISTRY_KEY, meta: META_ROOT_KEY },
+    metaAttrs: { version: 'v', schema: 'schema' }
+};

package/dist/crdt/semantics.d.ts

@@ -0,0 +1,81 @@
+import type { BlockRole } from './edytor-doc.js';
+/** One kind's structural row — the fields of its `BlockDefinition` a document adopts. */
+export type KindSemantics = BlockRole & {
+    rendersContent?: boolean;
+    defaultChild?: string;
+};
+/** `richTextPlugin`'s structural rows (its other kinds are plain). */
+export declare const richTextKinds: {
+    divider: {
+        void: true;
+        rendersContent: false;
+    };
+    horizontalRule: {
+        void: true;
+        rendersContent: false;
+    };
+    'ordered-list': {
+        rendersContent: false;
+        defaultChild: string;
+    };
+    'unordered-list': {
+        rendersContent: false;
+        defaultChild: string;
+    };
+};
+/** `codePlugin`'s structural rows: the code block is an island of `codeLine`s (`lines`). */
+export declare const codeKinds: {
+    code: {
+        island: true;
+        lines: true;
+        rendersContent: false;
+        defaultChild: string;
+    };
+};
+/** `imagePlugin`'s structural rows: void, its only text is the caption. */
+export declare const imageKinds: {
+    image: {
+        void: true;
+    };
+};
+/**
+ * Kind tables (`type → row`) as one {@link DocumentSemanticsConfig}, deeply
+ * frozen: `semanticsOf({ embed: { void: true, rendersContent: false } })`.
+ * To add kinds to a bundled config, merge `roles`, `rendersContent` and
+ * `defaultChild` field by field
+ * (`roles: { ...defaultSemantics.roles, ...mine.roles }`, and so on): a
+ * top-level spread of two configs keeps only the last one's fields and
+ * drops the bundled void, island and default-child rows.
+ */
+export declare const semanticsOf: (...tables: Record<string, KindSemantics>[]) => {
+    roles: Record<string, BlockRole>;
+    rendersContent: Record<string, boolean>;
+    defaultChild: Record<string, string>;
+};
+/** `richTextPlugin`'s block roles, for `createDocument({ semantics })` and the room. */
+export declare const richTextSemantics: {
+    roles: Record<string, BlockRole>;
+    rendersContent: Record<string, boolean>;
+    defaultChild: Record<string, string>;
+};
+/** `codePlugin`'s block roles. */
+export declare const codeSemantics: {
+    roles: Record<string, BlockRole>;
+    rendersContent: Record<string, boolean>;
+    defaultChild: Record<string, string>;
+};
+/** `imagePlugin`'s block roles. */
+export declare const imageSemantics: {
+    roles: Record<string, BlockRole>;
+    rendersContent: Record<string, boolean>;
+    defaultChild: Record<string, string>;
+};
+/**
+ * The rich-text, code and image plugins' block roles together — what the
+ * room adopts by default and what a headless document passes explicitly.
+ */
+export declare const defaultSemantics: {
+    roles: Record<string, BlockRole>;
+    rendersContent: Record<string, boolean>;
+    defaultChild: Record<string, string>;
+};

package/dist/crdt/semantics.js

@@ -0,0 +1,57 @@
+/** Freeze `value` and everything in it: the tables are shared by every document. */
+const frozen = (value) => {
+    if (value && typeof value === 'object' && !Object.isFrozen(value)) {
+        Object.freeze(value);
+        for (const inner of Object.values(value))
+            frozen(inner);
+    }
+    return value;
+};
+/** `richTextPlugin`'s structural rows (its other kinds are plain). */
+export const richTextKinds = frozen({
+    divider: { void: true, rendersContent: false },
+    horizontalRule: { void: true, rendersContent: false },
+    'ordered-list': { rendersContent: false, defaultChild: 'list-item' },
+    'unordered-list': { rendersContent: false, defaultChild: 'list-item' }
+});
+/** `codePlugin`'s structural rows: the code block is an island of `codeLine`s (`lines`). */
+export const codeKinds = frozen({
+    code: { island: true, lines: true, rendersContent: false, defaultChild: 'codeLine' }
+});
+/** `imagePlugin`'s structural rows: void, its only text is the caption. */
+export const imageKinds = frozen({ image: { void: true } });
+/**
+ * Kind tables (`type → row`) as one {@link DocumentSemanticsConfig}, deeply
+ * frozen: `semanticsOf({ embed: { void: true, rendersContent: false } })`.
+ * To add kinds to a bundled config, merge `roles`, `rendersContent` and
+ * `defaultChild` field by field
+ * (`roles: { ...defaultSemantics.roles, ...mine.roles }`, and so on): a
+ * top-level spread of two configs keeps only the last one's fields and
+ * drops the bundled void, island and default-child rows.
+ */
+export const semanticsOf = (...tables) => {
+    const semantics = {
+        roles: {},
+        rendersContent: {},
+        defaultChild: {}
+    };
+    for (const [type, { rendersContent, defaultChild, ...role }] of tables.flatMap(Object.entries)) {
+        semantics.roles[type] = role;
+        if (rendersContent !== undefined)
+            semantics.rendersContent[type] = rendersContent;
+        if (defaultChild !== undefined)
+            semantics.defaultChild[type] = defaultChild;
+    }
+    return frozen(semantics);
+};
+/** `richTextPlugin`'s block roles, for `createDocument({ semantics })` and the room. */
+export const richTextSemantics = semanticsOf(richTextKinds);
+/** `codePlugin`'s block roles. */
+export const codeSemantics = semanticsOf(codeKinds);
+/** `imagePlugin`'s block roles. */
+export const imageSemantics = semanticsOf(imageKinds);
+/**
+ * The rich-text, code and image plugins' block roles together — what the
+ * room adopts by default and what a headless document passes explicitly.
+ */
+export const defaultSemantics = semanticsOf(richTextKinds, codeKinds, imageKinds);

package/dist/crdt/structs.d.ts

@@ -0,0 +1,106 @@
+/**
+ * Vendor-internal struct access — the ONE place Edytor code reaches into
+ * the engine's struct store (`doc.store.clients`) and walks structs by id
+ * set. Centralizing these reads keeps the blast radius of a vendored
+ * engine upgrade in one module: when an internal is renamed or reshaped,
+ * the fail-fast checks below break loudly at upgrade time instead of
+ * silently disabling run invalidation or history lineage (the old
+ * optional-chained reads turned a rename into a silent no-op).
+ *
+ * The engine surface is injected (`Y: EngineApi`) like every other bound
+ * module — this file never imports vendor `.js`.
+ */
+import type { EngineApi, EngineDoc } from './engine-api.js';
+/**
+ * Structural shape of one store struct (Item | GC | Skip) — the subset
+ * Edytor reads. `redone`/`keep` are local-only bits (never serialized).
+ */
+export type StoreStruct = {
+    id: {
+        client: number;
+        clock: number;
+    };
+    length: number;
+    deleted: boolean;
+    /** `null` for sequence items; an attr name for map-entry items. */
+    parentSub: string | null;
+    parent: unknown;
+    right?: StoreStruct | null;
+    countable?: boolean;
+    keep?: boolean;
+    redone?: {
+        client: number;
+        clock: number;
+    } | null;
+};
+/**
+ * The engine's IdSet shape (insertSet/deleteSet): per-client range lists —
+ * each `{clock, len}` covers a contiguous struct run in that client's
+ * store list.
+ */
+export type IdSetLike = {
+    clients: Map<number, {
+        getIds(): {
+            clock: number;
+            len: number;
+        }[];
+    }>;
+    has(client: number, clock: number): boolean;
+};
+/**
+ * The doc's struct store — vendor-internal (`doc.store.clients`).
+ * FAIL-FAST: a missing store means the doc is not a vendored-engine doc
+ * (or the vendored layout changed) — either way the only honest response
+ * is a descriptive throw, never a silent fallback.
+ */
+export declare const clientsOf: (doc: EngineDoc) => Map<number, StoreStruct[]>;
+/**
+ * The struct covering `clock` in a client's clock-sorted struct list, or
+ * `null` when no struct contains it. Wraps the vendor's `findIndexSS`
+ * binary search — which THROWS on a miss — into the null-on-miss
+ * convention callers use.
+ */
+export declare const structAt: (Y: EngineApi, structs: readonly StoreStruct[], clock: number) => StoreStruct | null;
+/**
+ * Walk every struct an IdSet covers, invoking `fn` per struct in
+ * (client, clock) order. IdSet ranges are item-aligned (they record whole
+ * structs), so an overlapping struct is a covered struct — the walk never
+ * splits.
+ *
+ * `fn` returning `false` halts the walk early (caller-side short-circuit).
+ *
+ * Returns `false` when coverage was INCOMPLETE — a client's struct list
+ * was missing or a range start could not be located — so the caller can
+ * fall back to an all-consumers/opaque answer instead of trusting a
+ * partial walk. `clientsOf` throws first when the store itself is absent.
+ */
+export declare const walkIdSetStructs: (Y: EngineApi, doc: EngineDoc, idSet: IdSetLike, fn: (struct: StoreStruct) => boolean | void) => boolean;
+/**
+ * The id the local `redone` chain leads `id` to: the copy an undo or redo
+ * on THIS replica re-created of a deleted item (redo copies chain), or `id`
+ * itself. Replica-dependent by design: only the replica that ran the
+ * history command has the chain.
+ */
+export declare const followRedone: (Y: EngineApi, doc: EngineDoc, id: {
+    client: number;
+    clock: number;
+}) => {
+    client: number;
+    clock: number;
+};
+/**
+ * Forget `node`'s search markers (vendor-internal `_searchMarker`, P4): a
+ * write made through items directly (a delete or `redoItem`, not the node's
+ * own insert/delete methods) leaves their indices stale — the engine's undo
+ * drops them the same way after a pop.
+ */
+export declare const dropSearchMarkers: (node: unknown) => void;
+/** The clock `client`'s next struct gets in `doc`. */
+export declare const nextClock: (doc: EngineDoc, client: number) => number;
+/**
+ * Whether `doc` holds updates it cannot integrate yet (vendor-internal
+ * `store.pendingStructs`/`pendingDs`): an out-of-order delivery can apply
+ * a delete whose replacement is still pending, so an attr may read
+ * undefined until the missing update arrives.
+ */
+export declare const holdsPending: (doc: EngineDoc) => boolean;