smartrte-core 0.2.1 → 1.0.0-beta.2

package/dist/foundation/diff/documentDiff.js

@@ -0,0 +1,148 @@
+import { isTextNode } from "../identity.js";
+import { diffTextRuns } from "./textDiff.js";
+const indexById = (document) => {
+    const index = new Map();
+    const visit = (node, parentId, path) => {
+        index.set(node.id, { node, parentId, path });
+        (node.children || []).forEach((child, childIndex) => {
+            if (!isTextNode(child))
+                visit(child, node.id, [...path, childIndex]);
+        });
+    };
+    visit(document, null, []);
+    return index;
+};
+/**
+ * Every `SmartElementNode` keeps a stable id across split/merge/move/type-
+ * change/undo (Phase 8c collab-readiness gate, assertion 1). That turns the
+ * structural half of a document diff into a hash-map join - id present in
+ * both/only-before/only-after - instead of a generic tree-alignment problem
+ * a Myers/patience-style algorithm would otherwise be needed to solve.
+ * `SmartTextNode` has no id, so text content is the one place a real
+ * (word-level, see textDiff.ts) diff algorithm is still needed.
+ */
+export const diffDocuments = (before, after, schema) => {
+    const beforeIndex = indexById(before);
+    const afterIndex = indexById(after);
+    const removed = [];
+    beforeIndex.forEach((entry, id) => {
+        if (afterIndex.has(id))
+            return;
+        // Only the topmost removed root is reported - a removed id whose
+        // parent id is itself removed is part of that parent's own subtree.
+        if (entry.parentId && !afterIndex.has(entry.parentId))
+            return;
+        removed.push({ kind: "removed", nodeId: id, node: entry.node, parentId: entry.parentId, path: [...entry.path] });
+    });
+    const added = [];
+    afterIndex.forEach((entry, id) => {
+        if (beforeIndex.has(id))
+            return;
+        if (entry.parentId && !beforeIndex.has(entry.parentId))
+            return;
+        added.push({ kind: "added", nodeId: id, node: entry.node, parentId: entry.parentId, path: [...entry.path] });
+    });
+    const changed = [];
+    beforeIndex.forEach((beforeEntry, id) => {
+        const afterEntry = afterIndex.get(id);
+        if (!afterEntry)
+            return;
+        const entry = {};
+        if (beforeEntry.parentId !== afterEntry.parentId) {
+            entry.move = {
+                fromParentId: beforeEntry.parentId, toParentId: afterEntry.parentId,
+                fromPath: [...beforeEntry.path], toPath: [...afterEntry.path],
+            };
+        }
+        else if (beforeEntry.parentId) {
+            const move = sameParentMove(beforeEntry.parentId, beforeIndex, afterIndex, id);
+            if (move)
+                entry.move = move;
+        }
+        if (beforeEntry.node.type !== afterEntry.node.type) {
+            entry.typeChange = { before: beforeEntry.node.type, after: afterEntry.node.type };
+        }
+        const attrsDiff = diffAttrs(beforeEntry.node.attrs || {}, afterEntry.node.attrs || {});
+        if (attrsDiff.length) {
+            entry.attrsChange = { before: beforeEntry.node.attrs || {}, after: afterEntry.node.attrs || {}, changedKeys: attrsDiff };
+        }
+        if (isInlineOwner(beforeEntry.node, schema) && isInlineOwner(afterEntry.node, schema)) {
+            const segments = diffTextRuns(textRunsOf(beforeEntry.node), textRunsOf(afterEntry.node));
+            if (segments.some((segment) => segment.op !== "equal"))
+                entry.contentChange = segments;
+        }
+        if (entry.move || entry.typeChange || entry.attrsChange || entry.contentChange) {
+            changed.push({ kind: "changed", nodeId: id, ...entry });
+        }
+    });
+    return { added, removed, changed };
+};
+/**
+ * Detects a same-parent reorder without false-positives from mere sibling
+ * insertion/removal: only ids that were - and still are - direct children
+ * of this exact parent on both sides are considered, and their retained-
+ * only order is compared via LCS. A retained id inside that LCS kept its
+ * relative order (even if its numeric index shifted because siblings were
+ * added/removed around it) and is not reported as moved.
+ */
+const sameParentMove = (parentId, beforeIndex, afterIndex, nodeId) => {
+    const beforeParent = beforeIndex.get(parentId);
+    const afterParent = afterIndex.get(parentId);
+    if (!beforeParent || !afterParent)
+        return undefined;
+    const beforeChildIds = (beforeParent.node.children || []).filter((child) => !isTextNode(child)).map((child) => child.id);
+    const afterChildIds = (afterParent.node.children || []).filter((child) => !isTextNode(child)).map((child) => child.id);
+    const oldOrder = beforeChildIds.filter((id) => afterIndex.get(id)?.parentId === parentId);
+    const newOrder = afterChildIds.filter((id) => beforeIndex.get(id)?.parentId === parentId);
+    const lcs = lcsIds(oldOrder, newOrder);
+    if (lcs.has(nodeId))
+        return undefined;
+    const before = beforeIndex.get(nodeId);
+    const after = afterIndex.get(nodeId);
+    return { fromParentId: parentId, toParentId: parentId, fromPath: [...before.path], toPath: [...after.path] };
+};
+const lcsIds = (before, after) => {
+    const n = before.length;
+    const m = after.length;
+    const dp = Array.from({ length: n + 1 }, () => new Array(m + 1).fill(0));
+    for (let i = n - 1; i >= 0; i -= 1) {
+        for (let j = m - 1; j >= 0; j -= 1) {
+            dp[i][j] = before[i] === after[j] ? dp[i + 1][j + 1] + 1 : Math.max(dp[i + 1][j], dp[i][j + 1]);
+        }
+    }
+    const kept = new Set();
+    let i = 0;
+    let j = 0;
+    while (i < n && j < m) {
+        if (before[i] === after[j] && dp[i][j] === dp[i + 1][j + 1] + 1) {
+            kept.add(before[i]);
+            i += 1;
+            j += 1;
+        }
+        else if (dp[i + 1][j] >= dp[i][j + 1])
+            i += 1;
+        else
+            j += 1;
+    }
+    return kept;
+};
+const diffAttrs = (before, after) => {
+    const keys = new Set([...Object.keys(before), ...Object.keys(after)]);
+    return [...keys].filter((key) => JSON.stringify(before[key]) !== JSON.stringify(after[key]));
+};
+/** Mirrors the inline-content-owner predicate in canonicalEditorRuntime.ts's firstTextSelection, reused here for consistency rather than a second definition of the same concept. */
+const isInlineOwner = (node, schema) => {
+    const children = node.children || [];
+    return children.every((child) => isTextNode(child) || schema.nodes[child.type]?.group === "inline");
+};
+/**
+ * Flattens an inline owner's children into `{text, marks}` runs for word-
+ * level diffing. Inline atomic children (e.g. inline images/formulas) are
+ * intentionally not represented here - only text is word-diffed; a change
+ * limited entirely to an inline atom within otherwise-unchanged text will
+ * not surface as a `contentChange`. Documented scope limit, not a silent
+ * gap: such a change is still visible via the atom's own `added`/`removed`
+ * entry if it's inserted/removed outright.
+ */
+const textRunsOf = (node) => (node.children || []).filter((child) => isTextNode(child))
+    .map((child) => ({ text: child.text, marks: (child.marks || []) }));

package/dist/foundation/diff/index.d.ts

@@ -0,0 +1,3 @@
+export * from "./types.js";
+export * from "./documentDiff.js";
+export * from "./textDiff.js";

package/dist/foundation/diff/index.js

@@ -0,0 +1,3 @@
+export * from "./types.js";
+export * from "./documentDiff.js";
+export * from "./textDiff.js";

package/dist/foundation/diff/textDiff.d.ts

@@ -0,0 +1,12 @@
+import type { SmartMark } from "../types.js";
+import type { TextDiffSegment } from "./types.js";
+export interface TextRun {
+    readonly text: string;
+    readonly marks: readonly SmartMark[];
+}
+/**
+ * Diffs two sequences of `{text, marks}` runs (the flattened inline content
+ * of one node) at word granularity. A token never spans a run boundary, so
+ * it can never straddle two different mark sets by construction.
+ */
+export declare const diffTextRuns: (before: readonly TextRun[], after: readonly TextRun[]) => TextDiffSegment[];

package/dist/foundation/diff/textDiff.js

@@ -0,0 +1,114 @@
+import { canonicalMarkOrder, markKey } from "../marks/canonical.js";
+/**
+ * Word-boundary tokenizer: each token is a run of non-whitespace plus its
+ * own trailing whitespace (leading whitespace with no preceding word, e.g.
+ * at the very start of a run, becomes its own token). Deliberately not
+ * further split on punctuation - this project's diff is word-granularity,
+ * not a linguistic tokenizer. Gluing whitespace onto its word rather than
+ * treating every space as an independent token matters for LCS matching
+ * below: an isolated whitespace token can spuriously "match" between two
+ * otherwise-unrelated words (e.g. "alpha beta" -> "gamma delta" sharing
+ * nothing but a space), fragmenting what should read as one clean
+ * delete+insert into delete/insert/equal(" ")/delete/insert.
+ */
+const tokenize = (text) => text.length ? text.match(/\S+\s*|^\s+/g) || [] : [];
+const tokensOf = (runs) => runs.flatMap((run) => tokenize(run.text).map((text) => ({ text, marks: run.marks })));
+const marksSignature = (marks) => canonicalMarkOrder(marks).map(markKey).join("|");
+const sameMarks = (left, right) => marksSignature(left) === marksSignature(right);
+/**
+ * A token's trailing whitespace is glued on for *display* (see `tokenize`
+ * above) but must not affect whether two tokens count as "the same word"
+ * for matching - the very same word carries different trailing whitespace
+ * depending only on whether another word happens to follow it in that
+ * particular text (a word at the end of "before" has no trailing space;
+ * the identical word gains one the moment "after" adds a word behind it).
+ * Comparing raw `.text` would make that purely incidental difference
+ * block an otherwise-correct match.
+ */
+const matchKey = (token) => token.text.trimEnd();
+/**
+ * Longest common subsequence over token match-keys (marks are compared
+ * separately, after alignment - see `sameMarks` below) via plain O(n*m)
+ * dynamic programming. Inputs here are bounded to one inline-content
+ * owner's word count (a paragraph/heading/cell), not a whole document, so
+ * Myers' O(ND) is unneeded complexity for this project's actual scale;
+ * revisit only if a real profile shows otherwise.
+ */
+const lcsSteps = (before, after) => {
+    const n = before.length;
+    const m = after.length;
+    const dp = Array.from({ length: n + 1 }, () => new Array(m + 1).fill(0));
+    for (let i = n - 1; i >= 0; i -= 1) {
+        for (let j = m - 1; j >= 0; j -= 1) {
+            dp[i][j] = matchKey(before[i]) === matchKey(after[j])
+                ? dp[i + 1][j + 1] + 1
+                : Math.max(dp[i + 1][j], dp[i][j + 1]);
+        }
+    }
+    const steps = [];
+    let i = 0;
+    let j = 0;
+    while (i < n && j < m) {
+        if (matchKey(before[i]) === matchKey(after[j]) && dp[i][j] === dp[i + 1][j + 1] + 1) {
+            steps.push({ op: "match", before: before[i], after: after[j] });
+            i += 1;
+            j += 1;
+        }
+        else if (dp[i + 1][j] >= dp[i][j + 1]) {
+            steps.push({ op: "delete", token: before[i] });
+            i += 1;
+        }
+        else {
+            steps.push({ op: "insert", token: after[j] });
+            j += 1;
+        }
+    }
+    while (i < n) {
+        steps.push({ op: "delete", token: before[i] });
+        i += 1;
+    }
+    while (j < m) {
+        steps.push({ op: "insert", token: after[j] });
+        j += 1;
+    }
+    return steps;
+};
+/** Coalesces adjacent steps of the same kind (and, for match/markChange, the same mark signature) into one segment - one token per LCS step would be needlessly fragmented for a UI. */
+const coalesce = (steps) => {
+    const segments = [];
+    for (const step of steps) {
+        if (step.op === "match") {
+            const changed = !sameMarks(step.before.marks, step.after.marks);
+            const last = segments[segments.length - 1];
+            if (changed) {
+                if (last?.op === "markChange" && sameMarks(last.before, step.before.marks) && sameMarks(last.after, step.after.marks)) {
+                    segments[segments.length - 1] = { ...last, text: last.text + step.after.text };
+                }
+                else {
+                    segments.push({ op: "markChange", text: step.after.text, before: step.before.marks, after: step.after.marks });
+                }
+            }
+            else if (last?.op === "equal" && sameMarks(last.marks, step.after.marks)) {
+                segments[segments.length - 1] = { ...last, text: last.text + step.after.text };
+            }
+            else {
+                segments.push({ op: "equal", text: step.after.text, marks: step.after.marks });
+            }
+            continue;
+        }
+        const last = segments[segments.length - 1];
+        if (last?.op === step.op && sameMarks(last.marks, step.token.marks)) {
+            segments[segments.length - 1] = { ...last, text: last.text + step.token.text };
+        }
+        else {
+            segments.push({ op: step.op, text: step.token.text, marks: step.token.marks });
+        }
+    }
+    return segments;
+};
+/**
+ * Diffs two sequences of `{text, marks}` runs (the flattened inline content
+ * of one node) at word granularity. A token never spans a run boundary, so
+ * it can never straddle two different mark sets by construction.
+ */
+export const diffTextRuns = (before, after) => coalesce(lcsSteps(tokensOf(before), tokensOf(after)));

package/dist/foundation/diff/types.d.ts

@@ -0,0 +1,74 @@
+import type { Attrs, SmartMark, SmartNode } from "../types.js";
+/**
+ * A word-granularity diff segment within one inline-content owner's flattened
+ * text. Word, not character: character-level diffing fragments on every
+ * keystroke-sized edit and is visually noisy for review UI; word-level is
+ * what every comparable tool (Word, Google Docs) renders track-changes at.
+ * A run whose text matches on both sides but whose marks don't is reported
+ * as `markChange`, not a delete+insert of identical text.
+ */
+export type TextDiffSegment = {
+    readonly op: "equal";
+    readonly text: string;
+    readonly marks: readonly SmartMark[];
+} | {
+    readonly op: "insert";
+    readonly text: string;
+    readonly marks: readonly SmartMark[];
+} | {
+    readonly op: "delete";
+    readonly text: string;
+    readonly marks: readonly SmartMark[];
+} | {
+    readonly op: "markChange";
+    readonly text: string;
+    readonly before: readonly SmartMark[];
+    readonly after: readonly SmartMark[];
+};
+/** A node id present in `after` but not `before`. Only topmost added roots are reported - a node whose parent id is itself newly-added is part of that parent's own subtree, not a separate entry. */
+export interface AddedNodeChange {
+    readonly kind: "added";
+    readonly nodeId: string;
+    readonly node: SmartNode;
+    readonly parentId: string | null;
+    readonly path: number[];
+}
+/** A node id present in `before` but not `after`. Only topmost removed roots are reported, mirroring `AddedNodeChange`. */
+export interface RemovedNodeChange {
+    readonly kind: "removed";
+    readonly nodeId: string;
+    readonly node: SmartNode;
+    readonly parentId: string | null;
+    readonly path: number[];
+}
+/**
+ * A node id present in both trees with at least one difference. Carries
+ * whichever of `move`/`typeChange`/`attrsChange`/`contentChange` actually
+ * differ on one entry per id, rather than separate flat entries per change
+ * kind - a renderer needs one lookup per node id, not a correlation step.
+ */
+export interface ChangedNodeChange {
+    readonly kind: "changed";
+    readonly nodeId: string;
+    readonly move?: {
+        readonly fromParentId: string | null;
+        readonly toParentId: string | null;
+        readonly fromPath: number[];
+        readonly toPath: number[];
+    };
+    readonly typeChange?: {
+        readonly before: string;
+        readonly after: string;
+    };
+    readonly attrsChange?: {
+        readonly before: Attrs;
+        readonly after: Attrs;
+        readonly changedKeys: readonly string[];
+    };
+    readonly contentChange?: readonly TextDiffSegment[];
+}
+export interface DocumentDiff {
+    readonly added: readonly AddedNodeChange[];
+    readonly removed: readonly RemovedNodeChange[];
+    readonly changed: readonly ChangedNodeChange[];
+}

package/dist/foundation/diff/types.js

@@ -0,0 +1 @@
+export {};

package/dist/foundation/editor.d.ts

@@ -0,0 +1,138 @@
+import { type NormalizationRun } from "./normalization.js";
+import type { Attrs, NormalizerRegistration, PersistedEditorDocument, ResolvedPos, SmartHistory, SmartMark, SmartNode, SmartOperation, SmartRange, SmartSchema, SmartSelection, SmartTransaction } from "./types.js";
+import type { PositionLookup, ScopeRequest, ScopeResult } from "./scope/types.js";
+import type { ContextMenuContribution, KeyboardShortcutContribution, PluginCommand } from "./plugin/types.js";
+export interface FoundationEditorState extends PersistedEditorDocument {
+    selection: SmartSelection;
+    storedMarks?: SmartMark[];
+}
+export interface TransactOptions {
+    source?: SmartTransaction["metadata"]["source"];
+    timestamp?: number;
+    historyGroup?: string;
+    addToHistory?: boolean;
+    compositionId?: string;
+    authorId?: string;
+}
+export declare class TransactionBuilder {
+    readonly selectionBefore: SmartSelection;
+    readonly operations: SmartOperation[];
+    selectionAfter: SmartSelection;
+    storedMarksAfter?: SmartMark[];
+    /** True when the caller intentionally set the post-transaction marks. */
+    /** @internal Transaction assembly uses this to distinguish an explicit clear from the default. */
+    storedMarksExplicit: boolean;
+    constructor(selectionBefore: SmartSelection, storedMarks?: SmartMark[]);
+    insertNode(position: ResolvedPos, node: SmartNode): void;
+    removeNode(position: ResolvedPos, node: SmartNode): void;
+    replaceNode(position: ResolvedPos, before: SmartNode, after: SmartNode): void;
+    moveNode(from: ResolvedPos, to: ResolvedPos, nodeId: string): void;
+    splitNode(position: ResolvedPos, depth: number, newId?: string): void;
+    mergeNode(position: ResolvedPos, depth: number, retiredId: string, splitOffset: number): void;
+    setNodeAttributes(position: ResolvedPos, before: Attrs, after: Attrs): void;
+    setNodeType(position: ResolvedPos, before: string, after: string, beforeAttrs: Attrs, afterAttrs: Attrs): void;
+    insertText(position: ResolvedPos, text: string, marks?: SmartMark[]): void;
+    deleteText(position: ResolvedPos, text: string, marks?: SmartMark[]): void;
+    addMark(range: SmartRange, mark: SmartMark): void;
+    removeMark(range: SmartRange, mark: SmartMark): void;
+    setSelection(selection: SmartSelection): void;
+    setStoredMarks(marks: SmartMark[] | undefined): void;
+}
+export interface FoundationEditorOptions {
+    document: SmartNode;
+    selection: SmartSelection;
+    revision?: number;
+    schema?: SmartSchema;
+    /** Defaults to the built-in registry's commands - a custom plugin list's registry.commands should be passed here to keep it in sync with a custom `schema`. */
+    commands?: ReadonlyMap<string, PluginCommand>;
+    /** Defaults to the built-in registry's keyboardShortcuts, for the same reason as `commands`. */
+    keyboardShortcuts?: readonly KeyboardShortcutContribution[];
+    /** Defaults to the built-in registry's contextMenu, for the same reason as `commands`. */
+    contextMenu?: readonly ContextMenuContribution[];
+    normalizers?: readonly NormalizerRegistration[];
+    historyLimit?: number;
+    historyByteLimit?: number;
+    coalescenceWindowMs?: number;
+    storedMarks?: readonly SmartMark[];
+    /**
+     * How many committed transactions to retain for rebasing an incoming
+     * transaction whose baseRevision is behind current (Phase 12b-client -
+     * without a real transport, single-writer usage never falls behind, so
+     * this never matters). Unbounded retention isn't viable for a long-lived
+     * session; a transaction behind this window fails with
+     * ResyncRequiredError rather than attempting a partial rebase.
+     */
+    revisionLogLimit?: number;
+}
+export interface ReplaceFoundationStateOptions {
+    selection: SmartSelection;
+    storedMarks?: readonly SmartMark[];
+    /** External replacement starts a new history epoch by default. */
+    resetHistory?: boolean;
+}
+export declare class FoundationEditor {
+    readonly schema: SmartSchema;
+    readonly commands: ReadonlyMap<string, PluginCommand>;
+    readonly keyboardShortcuts: readonly KeyboardShortcutContribution[];
+    readonly contextMenu: readonly ContextMenuContribution[];
+    private current;
+    private currentHistory;
+    private readonly normalizers;
+    private activeBuilder;
+    private listeners;
+    private readonly semanticIndex;
+    private readonly historyOptions;
+    lastNormalization: NormalizationRun | null;
+    /**
+     * Every committed transaction since this instance was created or last
+     * replaceState'd, oldest first, bounded to `revisionLogLimit` - the
+     * "missed operations" source for rebasing an incoming stale transaction
+     * (see dispatch()). Index i holds the transaction that advanced the
+     * document from revision (current.revision - revisionLog.length + i) to
+     * the next.
+     */
+    private revisionLog;
+    private readonly revisionLogLimit;
+    constructor(options: FoundationEditorOptions);
+    get state(): FoundationEditorState;
+    get history(): SmartHistory;
+    /** Readonly canonical references for memoized renderers and indexes. */
+    get document(): FoundationEditorState["document"];
+    get selection(): SmartSelection;
+    get storedMarks(): readonly SmartMark[] | undefined;
+    /**
+     * Commit listeners receive the canonical readonly document reference. This
+     * preserves the structural-sharing memoization contract and avoids cloning
+     * the complete document once per listener on every keystroke.
+     */
+    private notify;
+    /**
+     * Replaces the canonical envelope without recreating the editor instance.
+     * This is an explicit host revision boundary, never a response to a prop diff.
+     */
+    replaceState(envelope: PersistedEditorDocument, options: ReplaceFoundationStateOptions): SmartTransaction;
+    resolveScope(request: ScopeRequest, selection?: SmartSelection): ScopeResult;
+    get positions(): PositionLookup;
+    resolve(position: {
+        pos: ResolvedPos["pos"];
+        affinity?: ResolvedPos["affinity"];
+    }): ResolvedPos;
+    transact(callback: (transaction: TransactionBuilder) => unknown, options?: TransactOptions): SmartTransaction | null;
+    /**
+     * Transactions committed since revision `sinceRevision`, oldest first -
+     * the same source `dispatch()` itself uses to rebase an incoming stale
+     * transaction, exposed so a host-implemented CollabTransport can answer
+     * `getRevisionHistory` without this editor needing to know anything about
+     * transports. Returns null when `sinceRevision` is older than what this
+     * instance retained (see `revisionLogLimit`) - the caller must resync.
+     */
+    getTransactionsSince(sinceRevision: number): readonly SmartTransaction[] | null;
+    dispatch(input: SmartTransaction): void;
+    typeText(text: string, options?: Omit<TransactOptions, "source">): SmartTransaction | null;
+    setSelection(selection: SmartSelection, options?: Omit<TransactOptions, "addToHistory">): SmartTransaction | null;
+    setStoredMarks(marks: readonly SmartMark[] | undefined, options?: Omit<TransactOptions, "addToHistory">): SmartTransaction | null;
+    undo(): boolean;
+    redo(): boolean;
+    subscribe(listener: (transaction: SmartTransaction, state: FoundationEditorState) => void): () => void;
+}
+export declare const createFoundationEditor: (options: FoundationEditorOptions) => FoundationEditor;