smartrte-core 0.2.0 → 1.0.0-beta.1

package/dist/foundation/operations.js

@@ -0,0 +1,568 @@
+import { assertUniqueNodeIds, cloneNode, isTextNode } from "./identity.js";
+import { nodeAtPath, samePath } from "./positions.js";
+import { canonicalMarkOrder } from "./marks/canonical.js";
+const sameValue = (left, right) => JSON.stringify(left) === JSON.stringify(right);
+const parentAndIndex = (document, pos) => {
+    const parent = nodeAtPath(document, pos.path);
+    if (!parent || isTextNode(parent) || !parent.children)
+        throw new Error("Operation position does not resolve to a container.");
+    if (!Number.isInteger(pos.offset) || pos.offset < 0 || pos.offset > parent.children.length)
+        throw new Error("Operation child offset is out of bounds.");
+    return { parent, index: pos.offset };
+};
+/**
+ * Transaction-local copy-on-write tree. A node is copied at most once in one
+ * operation batch; unchanged siblings retain reference identity. This identity
+ * guarantee is the memoization contract for scope indexing and DOM rendering.
+ */
+class PathCopySession {
+    constructor(input) {
+        this.input = input;
+        this.copies = new WeakMap();
+        this.mutable = new WeakSet();
+        this.root = input;
+    }
+    document() { return this.root; }
+    node(path) { return nodeAtPath(this.root, path); }
+    copy(node) {
+        if (this.mutable.has(node))
+            return node;
+        const existing = this.copies.get(node);
+        if (existing)
+            return existing;
+        const draft = { ...node, ...(node.children ? { children: [...node.children] } : {}) };
+        this.copies.set(node, draft);
+        this.mutable.add(draft);
+        return draft;
+    }
+    container(path) {
+        let current = this.copy(this.root);
+        this.root = current;
+        for (const index of path) {
+            const children = current.children;
+            const child = children?.[index];
+            if (!child || isTextNode(child))
+                throw new Error("Container path does not resolve to an element.");
+            const next = this.copy(child);
+            children[index] = next;
+            current = next;
+        }
+        return current;
+    }
+    replace(path, replacement) {
+        if (!path.length) {
+            if (isTextNode(replacement) || replacement.type !== "doc")
+                throw new Error("Document root replacement must be a doc node.");
+            this.root = replacement;
+            return;
+        }
+        const parent = this.container(path.slice(0, -1));
+        const index = path[path.length - 1];
+        if (!parent.children || index < 0 || index >= parent.children.length)
+            throw new Error("Replacement index is out of bounds.");
+        parent.children[index] = replacement;
+    }
+}
+const marksKey = (marks) => JSON.stringify(canonicalMarkOrder(marks));
+const normalizeInline = (children) => {
+    const result = [];
+    children.forEach((node) => {
+        if (isTextNode(node) && !node.text)
+            return;
+        if (isTextNode(node) && node.marks?.length)
+            node = { ...node, marks: canonicalMarkOrder(node.marks) };
+        const previous = result[result.length - 1];
+        if (isTextNode(node) && previous && isTextNode(previous) && marksKey(previous.marks) === marksKey(node.marks)) {
+            result[result.length - 1] = { ...previous, text: previous.text + node.text };
+        }
+        else
+            result.push(node);
+    });
+    return result;
+};
+const splitInlineAt = (children, offset) => {
+    if (!Number.isInteger(offset) || offset < 0)
+        throw new Error("Inline offset is invalid.");
+    const before = [];
+    const after = [];
+    let consumed = 0;
+    let split = false;
+    children.forEach((node) => {
+        if (split)
+            return after.push(node);
+        const size = isTextNode(node) ? node.text.length : 1;
+        if (offset > consumed + size) {
+            before.push(node);
+            consumed += size;
+            return;
+        }
+        const local = offset - consumed;
+        if (isTextNode(node)) {
+            if (local > 0)
+                before.push({ ...node, text: node.text.slice(0, local) });
+            if (local < size)
+                after.push({ ...node, text: node.text.slice(local) });
+        }
+        else {
+            if (local === 0)
+                after.push(node);
+            else if (local === 1)
+                before.push(node);
+            else
+                throw new Error("Atomic inline offset is invalid.");
+        }
+        split = true;
+        consumed += size;
+    });
+    if (!split && offset !== consumed)
+        throw new Error("Inline offset is out of bounds.");
+    return [before, after];
+};
+const inlineContainer = (document, pos) => {
+    const node = nodeAtPath(document, pos.path);
+    if (!node || isTextNode(node) || !node.children) {
+        throw new Error("Text operation must target an inline container.");
+    }
+    return node;
+};
+const insertText = (session, pos, text, marks) => {
+    const container = inlineContainer(session.document(), pos);
+    const [before, after] = splitInlineAt(container.children || [], pos.offset);
+    const inserted = text ? [{ type: "text", text, ...(marks?.length ? { marks: structuredClone(marks) } : {}) }] : [];
+    const draft = session.container(pos.path);
+    draft.children = normalizeInline([...before, ...inserted, ...after]);
+};
+const deleteText = (session, pos, text) => {
+    const container = inlineContainer(session.document(), pos);
+    const [before, tail] = splitInlineAt(container.children || [], pos.offset);
+    const [removed, after] = splitInlineAt(tail, text.length);
+    const actual = removed.map((node) => isTextNode(node) ? node.text : "\uFFFC").join("");
+    if (actual !== text)
+        throw new Error(`deleteText payload does not match document content.`);
+    const draft = session.container(pos.path);
+    draft.children = normalizeInline([...before, ...after]);
+};
+const applyMark = (session, range, mark, add) => {
+    const comparePath = (left, right) => {
+        const length = Math.min(left.length, right.length);
+        for (let index = 0; index < length; index += 1)
+            if (left[index] !== right[index])
+                return left[index] - right[index];
+        return left.length - right.length;
+    };
+    if (comparePath(range.from.path, range.to.path) > 0 || (samePath(range.from.path, range.to.path) && range.from.offset > range.to.offset)) {
+        throw new Error("Mark operation range must be normalized from/to.");
+    }
+    const paths = [];
+    const visit = (node, path) => {
+        if (isTextNode(node))
+            return;
+        if (samePath(path, range.from.path) && samePath(path, range.to.path))
+            paths.push(path);
+        else if ((node.type === "paragraph" || node.type === "heading") &&
+            comparePath(path, range.from.path) >= 0 && comparePath(path, range.to.path) <= 0)
+            paths.push(path);
+        node.children?.forEach((child, index) => visit(child, [...path, index]));
+    };
+    visit(session.document(), []);
+    paths.forEach((path) => {
+        const container = inlineContainer(session.document(), { path, offset: 0 });
+        const size = (container.children || []).reduce((total, child) => total + (isTextNode(child) ? child.text.length : 1), 0);
+        const start = samePath(path, range.from.path) ? range.from.offset : 0;
+        const end = samePath(path, range.to.path) ? range.to.offset : size;
+        const [before, tail] = splitInlineAt(container.children || [], start);
+        const [middle, after] = splitInlineAt(tail, end - start);
+        const changed = middle.map((node) => {
+            if (!isTextNode(node))
+                return node;
+            const marks = node.marks || [];
+            if (add) {
+                if (marks.some((candidate) => sameValue(candidate, mark)))
+                    return node;
+                return { ...node, marks: canonicalMarkOrder([...marks, structuredClone(mark)]) };
+            }
+            const next = marks.filter((candidate) => !sameValue(candidate, mark));
+            return { ...node, ...(next.length ? { marks: next } : { marks: undefined }) };
+        });
+        const draft = session.container(path);
+        draft.children = normalizeInline([...before, ...changed, ...after]);
+    });
+};
+const applyToSession = (session, operation) => {
+    const document = session.document();
+    if (operation.type === "insertNode") {
+        const { parent, index } = parentAndIndex(document, operation.pos);
+        const draft = session.container(operation.pos.path);
+        draft.children = [...(parent.children || []).slice(0, index), cloneNode(operation.node), ...(parent.children || []).slice(index)];
+    }
+    else if (operation.type === "removeNode") {
+        const { parent, index } = parentAndIndex(document, operation.pos);
+        const existing = parent.children?.[index];
+        if (!existing || !sameValue(existing, operation.node))
+            throw new Error("removeNode payload does not match document node.");
+        const draft = session.container(operation.pos.path);
+        draft.children = [...(parent.children || []).slice(0, index), ...(parent.children || []).slice(index + 1)];
+    }
+    else if (operation.type === "replaceNode") {
+        const { parent, index } = parentAndIndex(document, operation.pos);
+        if (!sameValue(parent.children?.[index], operation.before))
+            throw new Error("replaceNode before payload does not match document node.");
+        const draft = session.container(operation.pos.path);
+        draft.children = (parent.children || []).map((node, nodeIndex) => nodeIndex === index ? cloneNode(operation.after) : node);
+    }
+    else if (operation.type === "moveNode") {
+        const source = parentAndIndex(document, operation.from);
+        const moving = source.parent.children?.[source.index];
+        if (!moving || isTextNode(moving) || moving.id !== operation.nodeId)
+            throw new Error("moveNode source does not match nodeId.");
+        const sourceDraft = session.container(operation.from.path);
+        sourceDraft.children = [...(source.parent.children || []).slice(0, source.index), ...(source.parent.children || []).slice(source.index + 1)];
+        const destination = parentAndIndex(session.document(), operation.to);
+        const destinationDraft = session.container(operation.to.path);
+        destinationDraft.children = [...(destination.parent.children || []).slice(0, destination.index), moving, ...(destination.parent.children || []).slice(destination.index)];
+    }
+    else if (operation.type === "splitNode") {
+        const targetPath = operation.pos.path.slice(0, operation.pos.path.length - operation.depth);
+        const target = session.node(targetPath);
+        if (!target || isTextNode(target) || !target.children)
+            throw new Error("splitNode target must be a container.");
+        if (operation.pos.offset < 0 || operation.pos.offset > target.children.length)
+            throw new Error("splitNode offset is out of bounds.");
+        const left = { ...target, children: target.children.slice(0, operation.pos.offset) };
+        const right = { ...target, id: operation.newId, children: target.children.slice(operation.pos.offset) };
+        const parentPath = targetPath.slice(0, -1);
+        const index = targetPath[targetPath.length - 1];
+        const parent = session.node(parentPath);
+        if (!parent || isTextNode(parent) || !parent.children)
+            throw new Error("splitNode parent is invalid.");
+        const draft = session.container(parentPath);
+        draft.children = [...parent.children.slice(0, index), left, right, ...parent.children.slice(index + 1)];
+    }
+    else if (operation.type === "mergeNode") {
+        const parent = session.node(operation.pos.path);
+        if (!parent || isTextNode(parent) || !parent.children)
+            throw new Error("mergeNode parent is invalid.");
+        const rightIndex = operation.pos.offset;
+        const left = parent.children[rightIndex - 1];
+        const right = parent.children[rightIndex];
+        if (!left || !right || isTextNode(left) || isTextNode(right) || right.id !== operation.retiredId)
+            throw new Error("mergeNode nodes are invalid.");
+        const comparable = (node) => {
+            const { id: _id, children: _children, ...rest } = node;
+            return rest;
+        };
+        if (!sameValue(comparable(left), comparable(right)) || operation.splitOffset !== (left.children || []).length) {
+            throw new Error("mergeNode requires structurally compatible siblings and the exact split offset.");
+        }
+        const merged = { ...left, children: [...(left.children || []), ...(right.children || [])] };
+        const draft = session.container(operation.pos.path);
+        draft.children = [...parent.children.slice(0, rightIndex - 1), merged, ...parent.children.slice(rightIndex + 1)];
+    }
+    else if (operation.type === "setNodeAttributes") {
+        const target = session.node(operation.pos.path);
+        if (!target || isTextNode(target) || !sameValue(target.attrs || {}, operation.before))
+            throw new Error("setNodeAttributes before payload does not match.");
+        // Reassign in place rather than destructure-then-respread: the latter
+        // always re-adds `attrs` as the object's last key, silently reordering
+        // it even when only the value changed. sameValue elsewhere compares
+        // nodes via JSON.stringify, which is key-order sensitive - a later
+        // replaceNode/removeNode whose `before` payload was captured pre-reorder
+        // would then fail to match an otherwise-identical node. See
+        // docs/bugs/setnodeattributes-reorders-keys-breaking-exact-match.md.
+        const next = { ...target };
+        if (Object.keys(operation.after).length)
+            next.attrs = structuredClone(operation.after);
+        else
+            delete next.attrs;
+        session.replace(operation.pos.path, next);
+    }
+    else if (operation.type === "setNodeType") {
+        const target = session.node(operation.pos.path);
+        if (!target || isTextNode(target) || target.type !== operation.before || !sameValue(target.attrs || {}, operation.beforeAttrs)) {
+            throw new Error("setNodeType before payload does not match.");
+        }
+        session.replace(operation.pos.path, {
+            type: operation.after,
+            id: target.id,
+            ...(Object.keys(operation.afterAttrs).length ? { attrs: structuredClone(operation.afterAttrs) } : {}),
+            ...(target.children ? { children: target.children } : {}),
+        });
+    }
+    else if (operation.type === "insertText")
+        insertText(session, operation.pos, operation.text, operation.marks);
+    else if (operation.type === "deleteText")
+        deleteText(session, operation.pos, operation.text);
+    else if (operation.type === "addMark")
+        applyMark(session, operation.range, operation.mark, true);
+    else
+        applyMark(session, operation.range, operation.mark, false);
+    return operation.type === "insertNode" || operation.type === "replaceNode" || operation.type === "splitNode";
+};
+export const applyOperation = (input, operation) => {
+    const session = new PathCopySession(input);
+    const identityChanged = applyToSession(session, operation);
+    const document = session.document();
+    if (identityChanged)
+        assertUniqueNodeIds(document);
+    return document;
+};
+export const invertOperation = (operation) => {
+    if (operation.type === "insertNode")
+        return { type: "removeNode", pos: operation.pos, node: cloneNode(operation.node) };
+    if (operation.type === "removeNode")
+        return { type: "insertNode", pos: operation.pos, node: cloneNode(operation.node) };
+    if (operation.type === "replaceNode")
+        return { ...operation, before: cloneNode(operation.after), after: cloneNode(operation.before) };
+    if (operation.type === "moveNode")
+        return { ...operation, from: operation.to, to: operation.from };
+    if (operation.type === "splitNode") {
+        const targetPath = operation.pos.path.slice(0, operation.pos.path.length - operation.depth);
+        return { type: "mergeNode", pos: { path: targetPath.slice(0, -1), offset: targetPath[targetPath.length - 1] + 1 }, depth: operation.depth, retiredId: operation.newId, splitOffset: operation.pos.offset };
+    }
+    if (operation.type === "mergeNode") {
+        const leftPath = [...operation.pos.path, operation.pos.offset - 1];
+        return { type: "splitNode", pos: { path: leftPath, offset: operation.splitOffset }, depth: operation.depth, newId: operation.retiredId };
+    }
+    if (operation.type === "setNodeAttributes")
+        return { ...operation, before: structuredClone(operation.after), after: structuredClone(operation.before) };
+    if (operation.type === "setNodeType")
+        return {
+            ...operation,
+            before: operation.after,
+            after: operation.before,
+            beforeAttrs: structuredClone(operation.afterAttrs),
+            afterAttrs: structuredClone(operation.beforeAttrs),
+        };
+    if (operation.type === "insertText")
+        return { type: "deleteText", pos: operation.pos, text: operation.text, ...(operation.marks ? { marks: structuredClone(operation.marks) } : {}) };
+    if (operation.type === "deleteText")
+        return { type: "insertText", pos: operation.pos, text: operation.text, ...(operation.marks ? { marks: structuredClone(operation.marks) } : {}) };
+    if (operation.type === "addMark")
+        return { type: "removeMark", range: operation.range, mark: structuredClone(operation.mark) };
+    return { type: "addMark", range: operation.range, mark: structuredClone(operation.mark) };
+};
+export const applyOperations = (document, operations) => {
+    const session = new PathCopySession(document);
+    let identityChanged = false;
+    operations.forEach((operation) => { identityChanged = applyToSession(session, operation) || identityChanged; });
+    const result = session.document();
+    if (identityChanged)
+        assertUniqueNodeIds(result);
+    return result;
+};
+export const invertOperations = (operations) => [...operations].reverse().map(invertOperation);
+const shiftPath = (pos, parent, delta) => {
+    if (!samePath(pos.path.slice(0, parent.path.length), parent.path) || pos.path.length <= parent.path.length)
+        return pos;
+    const path = [...pos.path];
+    const index = path[parent.path.length];
+    if (index >= parent.offset)
+        path[parent.path.length] += delta;
+    return { ...pos, path };
+};
+export const mapPosThroughOperation = (pos, operation, bias = 1) => {
+    if (operation.type === "insertNode") {
+        if (samePath(pos.path, operation.pos.path) && pos.offset === operation.pos.offset)
+            return { pos: { ...pos, offset: pos.offset + (bias > 0 ? 1 : 0) }, deleted: false };
+        // A second position/operation at the *same* parent, past the insertion
+        // point, needs its own offset bumped directly - shiftPath only handles a
+        // position strictly *deeper* than the insertion point (pos.path.length >
+        // parent.path.length), so a same-depth sibling reference (e.g. another
+        // insertNode's own .pos.offset into the identical array) fell through
+        // unshifted. removeNode's branch below already has this same-path check;
+        // insertNode's was missing it - see the TP1 property test that caught
+        // this (two sibling insertNode ops at offsets 2 and 5 diverged depending
+        // on transform order).
+        if (samePath(pos.path, operation.pos.path) && pos.offset > operation.pos.offset)
+            return { pos: { ...pos, offset: pos.offset + 1 }, deleted: false };
+        return { pos: shiftPath(pos, operation.pos, 1), deleted: false };
+    }
+    if (operation.type === "removeNode") {
+        const removedPath = [...operation.pos.path, operation.pos.offset];
+        if (samePath(pos.path.slice(0, removedPath.length), removedPath))
+            return { pos: { path: [...operation.pos.path], offset: operation.pos.offset }, deleted: true };
+        if (samePath(pos.path, operation.pos.path) && pos.offset > operation.pos.offset)
+            return { pos: { ...pos, offset: pos.offset - 1 }, deleted: false };
+        return { pos: shiftPath(pos, operation.pos, -1), deleted: false };
+    }
+    if (operation.type === "replaceNode") {
+        const replaced = [...operation.pos.path, operation.pos.offset];
+        if (samePath(pos.path.slice(0, replaced.length), replaced)
+            && !isTextNode(operation.before) && !isTextNode(operation.after)
+            && operation.before.id === operation.after.id) {
+            const relative = pos.path.slice(replaced.length);
+            let owner = operation.before;
+            for (const index of relative)
+                owner = !owner || isTextNode(owner) ? undefined : owner.children?.[index];
+            if (owner && !isTextNode(owner)) {
+                const find = (node, id, path = []) => {
+                    if (!isTextNode(node) && node.id === id)
+                        return path;
+                    if (isTextNode(node))
+                        return null;
+                    for (let index = 0; index < (node.children?.length || 0); index += 1) {
+                        const found = find(node.children[index], id, [...path, index]);
+                        if (found)
+                            return found;
+                    }
+                    return null;
+                };
+                const nextRelative = find(operation.after, owner.id);
+                if (nextRelative)
+                    return { pos: { path: [...replaced, ...nextRelative], offset: pos.offset }, deleted: false };
+            }
+        }
+        return samePath(pos.path.slice(0, replaced.length), replaced)
+            ? { pos: { path: [...operation.pos.path], offset: operation.pos.offset + (bias > 0 ? 1 : 0) }, deleted: true }
+            : { pos, deleted: false };
+    }
+    if (operation.type === "moveNode") {
+        const sourcePath = [...operation.from.path, operation.from.offset];
+        if (samePath(pos.path.slice(0, sourcePath.length), sourcePath)) {
+            return { pos: { ...pos, path: [...operation.to.path, operation.to.offset, ...pos.path.slice(sourcePath.length)] }, deleted: false };
+        }
+        const removed = mapPosThroughOperation(pos, { type: "removeNode", pos: operation.from, node: { type: "unknown", id: operation.nodeId } }, bias);
+        return mapPosThroughOperation(removed.pos, { type: "insertNode", pos: operation.to, node: { type: "unknown", id: operation.nodeId } }, bias);
+    }
+    if (operation.type === "splitNode") {
+        const targetPath = operation.pos.path.slice(0, operation.pos.path.length - operation.depth);
+        const parentPath = targetPath.slice(0, -1);
+        const targetIndex = targetPath[targetPath.length - 1];
+        // Exact-tie case (bias>0 mirrors insertNode's/insertText's own tie
+        // handling above): two concurrent splitNode ops at the identical
+        // boundary had no resolution at all before this - pos.offset ===
+        // operation.pos.offset satisfied neither this branch (originally
+        // `>` only) nor any other, silently falling through to "unchanged" at
+        // the bottom of this function, which produced a swapped-identity
+        // divergence (found via a TP1 property test: whichever split ends up
+        // empty differs depending on transform order). Merging the tie into
+        // this existing shift condition, rather than adding a separate branch,
+        // keeps the same formula for both the tie and the already-correct
+        // greater-than case.
+        if (samePath(pos.path, targetPath) && (pos.offset > operation.pos.offset || (pos.offset === operation.pos.offset && bias > 0))) {
+            return { pos: { path: [...parentPath, targetIndex + 1], offset: pos.offset - operation.pos.offset }, deleted: false };
+        }
+        if (samePath(pos.path, parentPath) && pos.offset > targetIndex) {
+            return { pos: { ...pos, offset: pos.offset + 1 }, deleted: false };
+        }
+        if (samePath(pos.path.slice(0, parentPath.length), parentPath) && pos.path.length > parentPath.length && pos.path[parentPath.length] > targetIndex) {
+            const path = [...pos.path];
+            path[parentPath.length] += 1;
+            return { pos: { ...pos, path }, deleted: false };
+        }
+        if (samePath(pos.path.slice(0, targetPath.length), targetPath) && pos.path.length > targetPath.length) {
+            const childIndex = pos.path[targetPath.length];
+            if (childIndex >= operation.pos.offset) {
+                return { pos: { ...pos, path: [...parentPath, targetIndex + 1, childIndex - operation.pos.offset, ...pos.path.slice(targetPath.length + 1)] }, deleted: false };
+            }
+        }
+    }
+    if (operation.type === "mergeNode") {
+        const rightPath = [...operation.pos.path, operation.pos.offset];
+        const leftPath = [...operation.pos.path, operation.pos.offset - 1];
+        if (samePath(pos.path, rightPath)) {
+            return { pos: { path: leftPath, offset: operation.splitOffset + pos.offset }, deleted: false };
+        }
+        if (samePath(pos.path.slice(0, rightPath.length), rightPath) && pos.path.length > rightPath.length) {
+            return { pos: { ...pos, path: [...leftPath, operation.splitOffset + pos.path[rightPath.length], ...pos.path.slice(rightPath.length + 1)] }, deleted: false };
+        }
+        if (samePath(pos.path, operation.pos.path) && pos.offset > operation.pos.offset) {
+            return { pos: { ...pos, offset: pos.offset - 1 }, deleted: false };
+        }
+        if (samePath(pos.path.slice(0, operation.pos.path.length), operation.pos.path) && pos.path.length > operation.pos.path.length && pos.path[operation.pos.path.length] > operation.pos.offset) {
+            const path = [...pos.path];
+            path[operation.pos.path.length] -= 1;
+            return { pos: { ...pos, path }, deleted: false };
+        }
+    }
+    if (operation.type === "insertText" && samePath(pos.path, operation.pos.path)) {
+        if (pos.offset > operation.pos.offset || (pos.offset === operation.pos.offset && bias > 0))
+            return { pos: { ...pos, offset: pos.offset + operation.text.length }, deleted: false };
+    }
+    if (operation.type === "deleteText" && samePath(pos.path, operation.pos.path)) {
+        const end = operation.pos.offset + operation.text.length;
+        if (pos.offset > operation.pos.offset && pos.offset <= end)
+            return { pos: { ...pos, offset: operation.pos.offset }, deleted: true };
+        if (pos.offset > end)
+            return { pos: { ...pos, offset: pos.offset - operation.text.length }, deleted: false };
+    }
+    return { pos: { path: [...pos.path], offset: pos.offset }, deleted: false };
+};
+/**
+ * `tieBreakBias` only affects the exact-tie case (operation's own structural
+ * position coincides exactly with `through`'s insertion point - e.g. two
+ * concurrent insertNode ops at the identical offset) - every other case's
+ * bias is unaffected. Defaults to 1 (through's content sorts first),
+ * preserving this function's existing, already-tested behavior exactly for
+ * every caller that doesn't pass it. A concurrent-rebase caller should
+ * derive this from a total order over the two operations' authors (e.g.
+ * lexicographic authorId comparison) so both transform directions agree:
+ * mapOperation(A, B, {tieBreakBias: A-sorts-first ? -1 : 1}) and
+ * mapOperation(B, A, {tieBreakBias: B-sorts-first ? -1 : 1}) must reach the
+ * same final order regardless of which one is "operation" and which is
+ * "through". This does not affect the addMark/removeMark range-endpoint
+ * biases below (-1/+1), which serve an unrelated purpose (range-growth
+ * semantics at an insertion boundary) and are deliberately left hardcoded.
+ */
+export const mapOperation = (operation, through, options = {}) => {
+    // tieBreakBias only overrides the default when this is a genuine tie
+    // between two operations of the *same* kind competing for the identical
+    // insertion point (insertNode-vs-insertNode, insertText-vs-insertText).
+    // For every other pairing (e.g. removeNode vs. insertNode at a
+    // numerically coincidental offset), the default (1) is always correct
+    // regardless of authorship - removeNode identifies its target by node
+    // identity, not by an ordering competition, so "which one sorts first"
+    // has no meaning there; forcing the override through anyway (confirmed
+    // via a TP1 property test) shifted a removeNode's target to the wrong
+    // slot depending on which author happened to sort first.
+    const isGenuineTie = operation.type === through.type && (operation.type === "insertNode" || operation.type === "insertText" || operation.type === "splitNode");
+    const structuralBias = isGenuineTie ? options.tieBreakBias ?? 1 : 1;
+    const map = (pos, bias = structuralBias) => mapPosThroughOperation(pos, through, bias);
+    if (operation.type === "insertNode" || operation.type === "removeNode" || operation.type === "replaceNode") {
+        // removeNode/replaceNode's `.pos` addresses an *occupied* slot (the
+        // node currently there); insertNode's `.pos` addresses a *gap* (the
+        // boundary before an index) - two structurally different meanings that
+        // happen to share the same {path, offset} shape. `mapPosThroughOperation`
+        // is generic pure position arithmetic with no idea which convention a
+        // given `pos` follows, so an exact-offset coincidence between the two
+        // conventions is not a real "same target" match (confirmed via a TP1
+        // property test: an insertNode and a removeNode at the identical offset
+        // are two unrelated actions - "insert before index 4" and "remove index
+        // 4" - not a conflict over the same node). This check is therefore
+        // scoped here, at the one call site that actually knows both
+        // operations' real types, rather than inside the shared, type-blind
+        // position mapper - only removeNode-vs-removeNode/replaceNode (both
+        // occupied-slot semantics) can mean "the exact same node," e.g. two
+        // concurrent removeNode ops targeting the identical node.
+        if (operation.type !== "insertNode" && (through.type === "removeNode" || through.type === "replaceNode")
+            && samePath(operation.pos.path, through.pos.path) && operation.pos.offset === through.pos.offset) {
+            return null;
+        }
+        const result = map(operation.pos);
+        return result.deleted ? null : { ...operation, pos: result.pos };
+    }
+    if (operation.type === "moveNode") {
+        const from = map(operation.from);
+        const to = map(operation.to);
+        return from.deleted ? null : { ...operation, from: from.pos, to: to.pos };
+    }
+    if (operation.type === "splitNode" || operation.type === "mergeNode" || operation.type === "setNodeAttributes" || operation.type === "setNodeType" || operation.type === "insertText" || operation.type === "deleteText") {
+        const result = map(operation.pos);
+        return result.deleted ? null : { ...operation, pos: result.pos };
+    }
+    const from = map(operation.range.from, -1);
+    // `to` used to hardcode bias=1 ("an insertion exactly at this boundary
+    // grows the range to include it"), which disagreed with insertText's own,
+    // separately-established ground truth: applyToSession's insertText (via
+    // splitInlineAt, ~line 96-104 above) puts a plain-marks insertion at an
+    // exact run boundary on the *following* side, never absorbing the
+    // preceding run's marks - confirmed via docs/bugs/
+    // addmark-boundary-bias-inconsistent-with-inserttext.md's TP1 test, which
+    // found the two conventions genuinely diverged (not just "look different
+    // but agree"). bias=-1 matches that existing, unexamined-until-now
+    // resolution: a mark's own `to` endpoint does not grow to include a
+    // same-offset insertion, exactly as insertText itself never grows the
+    // preceding run to include new unmarked text.
+    const to = map(operation.range.to, -1);
+    return from.deleted && to.deleted ? null : { ...operation, range: { from: from.pos, to: to.pos } };
+};

package/dist/foundation/plugin/builtins.d.ts

@@ -0,0 +1,10 @@
+import type { FoundationPlugin } from "./types.js";
+/**
+ * One FoundationPlugin per built-in feature family. Each is filled in as
+ * that family is converted (Phase 10 tasks: marks -> list -> block ->
+ * table -> atom) - wrapping its existing, already-tested command functions
+ * with the required description/examples metadata, not rewriting them.
+ * Families not yet converted still contribute their schema (so foundationSchema
+ * stays complete) with an empty command set.
+ */
+export declare const builtInPlugins: readonly FoundationPlugin[];

package/dist/foundation/plugin/builtins.js

@@ -0,0 +1,27 @@
+import { blockNodeSpecs } from "../block/schema.js";
+import { blockPluginCommands, blockPluginShortcuts, blockToolbarContributions } from "../block/plugin.js";
+import { listNodeSpecs } from "../list/schema.js";
+import { listPluginCommands, listPluginShortcuts } from "../list/plugin.js";
+import { tableNodeSpecs } from "../table/schema.js";
+import { tablePluginCommands, tableContextMenuContributions } from "../table/plugin.js";
+import { atomNodeSpecs } from "../atom/schema.js";
+import { atomPluginCommands } from "../atom/plugin.js";
+import { markPluginCommands, markToolbarContributions, inlineMarkSpecs } from "../marks/plugin.js";
+/**
+ * One FoundationPlugin per built-in feature family. Each is filled in as
+ * that family is converted (Phase 10 tasks: marks -> list -> block ->
+ * table -> atom) - wrapping its existing, already-tested command functions
+ * with the required description/examples metadata, not rewriting them.
+ * Families not yet converted still contribute their schema (so foundationSchema
+ * stays complete) with an empty command set.
+ */
+export const builtInPlugins = [
+    {
+        id: "marks", version: "1.0.0", schema: { marks: inlineMarkSpecs }, commands: markPluginCommands,
+        toolbar: markToolbarContributions,
+    },
+    { id: "list", version: "1.0.0", schema: { nodes: listNodeSpecs }, commands: listPluginCommands, keyboardShortcuts: listPluginShortcuts },
+    { id: "block", version: "1.0.0", schema: { nodes: blockNodeSpecs }, commands: blockPluginCommands, toolbar: blockToolbarContributions, keyboardShortcuts: blockPluginShortcuts },
+    { id: "table", version: "1.0.0", schema: { nodes: tableNodeSpecs }, commands: tablePluginCommands, contextMenu: tableContextMenuContributions },
+    { id: "atom", version: "1.0.0", schema: { nodes: atomNodeSpecs }, commands: atomPluginCommands },
+];

package/dist/foundation/plugin/dispatch.d.ts

@@ -0,0 +1,33 @@
+import type { SmartOperation } from "../types.js";
+import type { KeyboardShortcutContribution } from "./types.js";
+export interface KeyLike {
+    readonly key: string;
+    readonly metaKey?: boolean;
+    readonly ctrlKey?: boolean;
+    readonly altKey?: boolean;
+    readonly shiftKey?: boolean;
+}
+/**
+ * Tries every key-matching shortcut contribution in priority order (ties
+ * broken by registration order, which is what PluginRegistry.keyboardShortcuts
+ * already provides), invoking `tryShortcut` for each and returning the
+ * first that actually produces operations.
+ *
+ * This is a fallback chain, not a static "one scope-kind owns this key"
+ * lookup, because ScopeKind alone cannot distinguish every case a real
+ * shortcut cares about (e.g. "inside a code block" and "inside a plain
+ * paragraph" are both "block-range" - see scope/resolveScope.ts). It
+ * reproduces surface/input.ts's actual current Tab precedence (code-block
+ * wins if applicable, then list unless inTable, then table/native
+ * fallthrough if nothing applies) by asking each candidate, in order,
+ * "does this genuinely apply here" via `tryShortcut` - which resolves the
+ * scope the contribution declares and runs its command - rather than by
+ * pre-filtering on a single precomputed scope-kind label. `scopeKinds` on
+ * a contribution remains meaningful as declared metadata for callers
+ * (which `resolveScope({want})` to attempt) and for doc generation, it's
+ * just no longer what this function filters by directly.
+ */
+export declare const resolveShortcut: (shortcuts: readonly KeyboardShortcutContribution[], event: KeyLike, tryShortcut: (shortcut: KeyboardShortcutContribution) => readonly SmartOperation[] | null) => {
+    shortcut: KeyboardShortcutContribution;
+    operations: readonly SmartOperation[];
+} | null;