smartrte-core 0.2.1 → 1.0.0-beta.2

package/dist/foundation/editor.js

@@ -0,0 +1,398 @@
+import { createNodeId, isTextNode } from "./identity.js";
+import { popRedo, popUndo, recordHistory, createHistory, rebaseHistoryNodeAttributes } from "./history.js";
+import { runNormalization } from "./normalization.js";
+import { applyOperations } from "./operations.js";
+import { createTransactionMap } from "./mapping.js";
+import { resolvePos } from "./positions.js";
+import { foundationRegistry, foundationSchema, repair, restoreUnknownMarks, restoreUnknownNodes, validate } from "./schema.js";
+import { applyTransactionAtomic, RebaseConflictError, ResyncRequiredError } from "./transactions.js";
+import { rebaseTransaction } from "./collab/rebase.js";
+import { FoundationScopeIndex } from "./scope/resolveScope.js";
+import { migrateNewlineTextToHardBreaks } from "./marks/hardBreak.js";
+import { canonicalMarkOrder, createMarkNormalizer, marksAtInsertion } from "./marks/index.js";
+import { createEditableBoundaryNormalizer, editableBoundaryOperations } from "./boundaries.js";
+export class TransactionBuilder {
+    constructor(selectionBefore, storedMarks) {
+        this.selectionBefore = selectionBefore;
+        this.operations = [];
+        /** True when the caller intentionally set the post-transaction marks. */
+        /** @internal Transaction assembly uses this to distinguish an explicit clear from the default. */
+        this.storedMarksExplicit = false;
+        this.selectionAfter = structuredClone(selectionBefore);
+        this.storedMarksAfter = structuredClone(storedMarks);
+    }
+    insertNode(position, node) {
+        this.operations.push({ type: "insertNode", pos: position.pos, node: structuredClone(node) });
+    }
+    removeNode(position, node) {
+        this.operations.push({ type: "removeNode", pos: position.pos, node: structuredClone(node) });
+    }
+    replaceNode(position, before, after) {
+        this.operations.push({ type: "replaceNode", pos: position.pos, before: structuredClone(before), after: structuredClone(after) });
+    }
+    moveNode(from, to, nodeId) {
+        this.operations.push({ type: "moveNode", from: from.pos, to: to.pos, nodeId });
+    }
+    splitNode(position, depth, newId = createNodeId()) {
+        this.operations.push({ type: "splitNode", pos: position.pos, depth, newId });
+    }
+    mergeNode(position, depth, retiredId, splitOffset) {
+        this.operations.push({ type: "mergeNode", pos: position.pos, depth, retiredId, splitOffset });
+    }
+    setNodeAttributes(position, before, after) {
+        this.operations.push({ type: "setNodeAttributes", pos: position.pos, before: structuredClone(before), after: structuredClone(after) });
+    }
+    setNodeType(position, before, after, beforeAttrs, afterAttrs) {
+        this.operations.push({
+            type: "setNodeType",
+            pos: position.pos,
+            before,
+            after,
+            beforeAttrs: structuredClone(beforeAttrs),
+            afterAttrs: structuredClone(afterAttrs),
+        });
+    }
+    insertText(position, text, marks) {
+        this.operations.push({ type: "insertText", pos: position.pos, text, ...(marks?.length ? { marks: structuredClone(marks) } : {}) });
+    }
+    deleteText(position, text, marks) {
+        this.operations.push({ type: "deleteText", pos: position.pos, text, ...(marks?.length ? { marks: structuredClone(marks) } : {}) });
+    }
+    addMark(range, mark) {
+        this.operations.push({ type: "addMark", range: structuredClone(range), mark: structuredClone(mark) });
+    }
+    removeMark(range, mark) {
+        this.operations.push({ type: "removeMark", range: structuredClone(range), mark: structuredClone(mark) });
+    }
+    setSelection(selection) {
+        this.selectionAfter = structuredClone(selection);
+    }
+    setStoredMarks(marks) {
+        this.storedMarksExplicit = true;
+        this.storedMarksAfter = structuredClone(marks);
+    }
+}
+const mapSelectionThroughBoundaryOperations = (selection, operations) => {
+    if (!operations.length)
+        return selection;
+    const map = createTransactionMap(operations);
+    // A node selection's head is the boundary immediately after the selected
+    // node. When a caret paragraph is inserted at that boundary, biasing the
+    // head forward would skip the new line and make ArrowRight manufacture a
+    // second paragraph. Keep both node-selection endpoints on the original
+    // side of the inserted boundary.
+    if (selection.type === "node")
+        return {
+            ...selection,
+            anchor: map.map(selection.anchor, -1),
+            head: map.map(selection.head, -1),
+        };
+    return map.mapSelection(selection);
+};
+export class FoundationEditor {
+    constructor(options) {
+        this.activeBuilder = null;
+        this.listeners = new Set();
+        this.semanticIndex = new FoundationScopeIndex();
+        this.lastNormalization = 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.
+         */
+        this.revisionLog = [];
+        this.schema = options.schema || foundationSchema;
+        this.commands = options.commands || foundationRegistry.commands;
+        this.keyboardShortcuts = options.keyboardShortcuts || foundationRegistry.keyboardShortcuts;
+        this.contextMenu = options.contextMenu || foundationRegistry.contextMenu;
+        const candidate = options.document.type === "doc"
+            ? options.document
+            : { type: "doc", id: createNodeId(), children: [options.document] };
+        const migrated = migrateNewlineTextToHardBreaks(candidate);
+        const repaired = repair(migrated.document, this.schema);
+        // Symmetric with repair() above: an `unknown`/`unknown-mark` node whose
+        // recorded originalType this schema *does* recognize (e.g. a
+        // previously plugin-disabled table, now loading into a schema with the
+        // table plugin re-enabled) restores losslessly - a no-op for every
+        // other document, since restoreUnknownNodes/Marks only ever act on a
+        // matching originalType. See docs/bugs/disable-safety-restore-never-wired.md.
+        const restored = restoreUnknownMarks(restoreUnknownNodes(repaired.doc, this.schema), this.schema);
+        const boundaryOperations = editableBoundaryOperations(restored, this.schema);
+        const boundedDocument = boundaryOperations.length ? applyOperations(restored, boundaryOperations) : restored;
+        const boundedSelection = mapSelectionThroughBoundaryOperations(options.selection, boundaryOperations);
+        const errors = validate(boundedDocument, this.schema);
+        if (errors.length)
+            throw new Error(`Initial document is invalid: ${errors[0].message}`);
+        resolvePos(boundedDocument, boundedSelection.anchor);
+        resolvePos(boundedDocument, boundedSelection.head);
+        this.current = {
+            schemaVersion: this.schema.version,
+            revision: options.revision ?? 0,
+            document: boundedDocument,
+            selection: structuredClone(boundedSelection),
+            ...(options.storedMarks?.length ? { storedMarks: canonicalMarkOrder(options.storedMarks) } : {}),
+        };
+        this.normalizers = [createEditableBoundaryNormalizer(), createMarkNormalizer(), ...(options.normalizers || [])];
+        this.historyOptions = {
+            historyLimit: options.historyLimit,
+            historyByteLimit: options.historyByteLimit,
+            coalescenceWindowMs: options.coalescenceWindowMs,
+        };
+        this.currentHistory = createHistory({
+            limit: options.historyLimit,
+            byteLimit: options.historyByteLimit,
+            coalescenceWindowMs: options.coalescenceWindowMs,
+        });
+        this.revisionLogLimit = Math.max(1, Math.floor(options.revisionLogLimit ?? 500));
+    }
+    get state() { return structuredClone(this.current); }
+    get history() { return structuredClone(this.currentHistory); }
+    /** Readonly canonical references for memoized renderers and indexes. */
+    get document() { return this.current.document; }
+    get selection() { return structuredClone(this.current.selection); }
+    get storedMarks() { return this.current.storedMarks; }
+    /**
+     * 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.
+     */
+    notify(transaction) {
+        if (!this.listeners.size)
+            return;
+        const state = {
+            schemaVersion: this.current.schemaVersion,
+            revision: this.current.revision,
+            document: this.current.document,
+            selection: structuredClone(this.current.selection),
+            ...(this.current.storedMarks ? { storedMarks: structuredClone(this.current.storedMarks) } : {}),
+        };
+        this.listeners.forEach((listener) => listener(structuredClone(transaction), state));
+    }
+    /**
+     * 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, options) {
+        const migrated = migrateNewlineTextToHardBreaks(envelope.document);
+        const repaired = repair(migrated.document, this.schema);
+        // See the matching comment in the constructor above.
+        const restored = restoreUnknownMarks(restoreUnknownNodes(repaired.doc, this.schema), this.schema);
+        const boundaryOperations = editableBoundaryOperations(restored, this.schema);
+        const boundedDocument = boundaryOperations.length ? applyOperations(restored, boundaryOperations) : restored;
+        const boundedSelection = mapSelectionThroughBoundaryOperations(options.selection, boundaryOperations);
+        const errors = validate(boundedDocument, this.schema);
+        if (errors.length)
+            throw new Error(`Replacement document is invalid: ${errors[0].message}`);
+        resolvePos(boundedDocument, boundedSelection.anchor);
+        resolvePos(boundedDocument, boundedSelection.head);
+        const before = this.current;
+        this.current = {
+            schemaVersion: this.schema.version,
+            revision: envelope.revision,
+            document: boundedDocument,
+            selection: structuredClone(boundedSelection),
+            ...(options.storedMarks?.length ? { storedMarks: canonicalMarkOrder(options.storedMarks) } : {}),
+        };
+        if (options.resetHistory !== false) {
+            this.currentHistory = createHistory({
+                limit: this.historyOptions.historyLimit,
+                byteLimit: this.historyOptions.historyByteLimit,
+                coalescenceWindowMs: this.historyOptions.coalescenceWindowMs,
+            });
+        }
+        // The revision counter is jumping to a new, unrelated baseline
+        // (envelope.revision, not before.revision + 1) - nothing in the old log
+        // could ever be correctly composed with transactions issued against
+        // this new baseline, so it's discarded rather than carried forward.
+        this.revisionLog = [];
+        const replacement = {
+            id: createNodeId(),
+            baseRevision: before.revision,
+            operations: [],
+            selectionBefore: structuredClone(before.selection),
+            selectionAfter: structuredClone(boundedSelection),
+            ...(before.storedMarks ? { storedMarksBefore: structuredClone(before.storedMarks) } : {}),
+            ...(options.storedMarks?.length ? { storedMarksAfter: canonicalMarkOrder(options.storedMarks) } : {}),
+            metadata: { source: "api", timestamp: Date.now(), addToHistory: false },
+        };
+        this.notify(replacement);
+        return replacement;
+    }
+    resolveScope(request, selection = this.current.selection) {
+        return this.semanticIndex.resolve(this.current.document, selection, request, this.schema);
+    }
+    get positions() { return this.semanticIndex.positions(this.current.document, this.schema); }
+    resolve(position) {
+        return resolvePos(this.current.document, position.pos, position.affinity);
+    }
+    transact(callback, options = {}) {
+        if (this.activeBuilder) {
+            const result = callback(this.activeBuilder);
+            if (result && typeof result.then === "function")
+                throw new Error("A transaction cannot remain open across await.");
+            return null;
+        }
+        const builder = new TransactionBuilder(this.current.selection, this.current.storedMarks);
+        this.activeBuilder = builder;
+        try {
+            const result = callback(builder);
+            if (result && typeof result.then === "function")
+                throw new Error("A transaction cannot remain open across await.");
+        }
+        finally {
+            this.activeBuilder = null;
+        }
+        if (builder.operations.length && !builder.storedMarksExplicit && !builder.operations.every((operation) => operation.type === "insertText" && (!this.current.storedMarks?.length
+            || JSON.stringify(canonicalMarkOrder(operation.marks)) === JSON.stringify(canonicalMarkOrder(this.current.storedMarks))))) {
+            builder.setStoredMarks(undefined);
+        }
+        const transaction = {
+            id: createNodeId(),
+            baseRevision: this.current.revision,
+            operations: builder.operations,
+            selectionBefore: structuredClone(builder.selectionBefore),
+            selectionAfter: structuredClone(builder.selectionAfter),
+            ...(this.current.storedMarks ? { storedMarksBefore: structuredClone(this.current.storedMarks) } : {}),
+            ...(builder.storedMarksAfter ? { storedMarksAfter: structuredClone(builder.storedMarksAfter) } : {}),
+            metadata: {
+                source: options.source || "api",
+                timestamp: options.timestamp ?? Date.now(),
+                ...(options.historyGroup ? { historyGroup: options.historyGroup } : {}),
+                addToHistory: options.addToHistory ?? builder.operations.length > 0,
+                ...(options.compositionId ? { compositionId: options.compositionId } : {}),
+                ...(options.authorId ? { authorId: options.authorId } : {}),
+            },
+        };
+        this.dispatch(transaction);
+        return transaction;
+    }
+    /**
+     * 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) {
+        const behindBy = this.current.revision - sinceRevision;
+        if (behindBy < 0)
+            return null;
+        if (behindBy > this.revisionLog.length)
+            return null;
+        return structuredClone(this.revisionLog.slice(this.revisionLog.length - behindBy));
+    }
+    dispatch(input) {
+        if (input.baseRevision !== this.current.revision) {
+            const missed = this.getTransactionsSince(input.baseRevision);
+            if (missed === null)
+                throw new ResyncRequiredError(this.current.revision);
+            const rebased = rebaseTransaction(input, missed, this.current.revision);
+            if (rebased.kind === "conflict")
+                throw new RebaseConflictError(rebased.reasons);
+            if (rebased.kind === "resync-required")
+                throw new ResyncRequiredError(rebased.atRevision);
+            if (rebased.kind === "dropped")
+                return;
+            input = rebased.transaction;
+        }
+        const historyAttributeUpdates = input.metadata.addToHistory ? [] : input.operations.flatMap((operation) => {
+            if (operation.type !== "setNodeAttributes")
+                return [];
+            const node = operation.pos.path.reduce((current, part) => current && !isTextNode(current) ? current.children?.[part] : undefined, this.current.document);
+            return node && !isTextNode(node) ? [{ nodeId: node.id, before: operation.before, after: operation.after }] : [];
+        });
+        const afterUserOperations = applyOperations(this.current.document, input.operations);
+        const normalization = runNormalization({
+            document: afterUserOperations,
+            originatingOperations: input.operations,
+            schema: this.schema,
+            normalizers: this.normalizers,
+        });
+        this.lastNormalization = normalization;
+        const normalizedSelection = normalization.operations.length
+            ? createTransactionMap(normalization.operations).mapSelection(input.selectionAfter)
+            : input.selectionAfter;
+        const transaction = {
+            ...structuredClone(input),
+            operations: [...structuredClone(input.operations), ...normalization.operations],
+            selectionAfter: normalizedSelection,
+        };
+        const envelope = applyTransactionAtomic(this.current, transaction, this.schema);
+        this.current = {
+            ...envelope,
+            selection: structuredClone(transaction.selectionAfter),
+            storedMarks: structuredClone(transaction.storedMarksAfter),
+        };
+        this.currentHistory = recordHistory(this.currentHistory, transaction);
+        historyAttributeUpdates.forEach((update) => {
+            this.currentHistory = rebaseHistoryNodeAttributes(this.currentHistory, update.nodeId, update.before, update.after);
+        });
+        // Recorded regardless of addToHistory (unlike currentHistory/undo) -
+        // this log exists to rebase *other* incoming transactions, which needs
+        // every committed change, not just the user-undoable ones.
+        this.revisionLog.push(transaction);
+        if (this.revisionLog.length > this.revisionLogLimit)
+            this.revisionLog.splice(0, this.revisionLog.length - this.revisionLogLimit);
+        this.notify(transaction);
+    }
+    typeText(text, options = {}) {
+        const resolved = resolvePos(this.current.document, this.current.selection.head);
+        const marks = this.current.storedMarks || marksAtInsertion(this.current.document, resolved.pos, this.schema);
+        return this.transact((transaction) => {
+            transaction.insertText(resolved, text, marks);
+            const next = { path: [...resolved.pos.path], offset: resolved.pos.offset + text.length };
+            transaction.setSelection({ type: "text", anchor: next, head: next });
+        }, { ...options, source: "input", addToHistory: true });
+    }
+    setSelection(selection, options = {}) {
+        return this.transact((transaction) => {
+            transaction.setSelection(selection);
+            transaction.setStoredMarks(undefined);
+        }, { ...options, addToHistory: false });
+    }
+    setStoredMarks(marks, options = {}) {
+        // `marks?.length ? ... : undefined` used to collapse an explicitly-passed
+        // *empty* array down to `undefined` - indistinguishable, downstream, from
+        // "no override, infer from surrounding text" (marksAtInsertion). That
+        // silently defeated toggling the last active mark off at a collapsed
+        // cursor: marksAtInsertion's inclusive-boundary rule re-includes the mark
+        // from the text just typed, so the very next keystroke was re-marked
+        // regardless of the explicit toggle-off. An explicit `[]` must survive as
+        // a real (truthy) empty array so `editor.storedMarks || marksAtInsertion(...)`
+        // resolves to `[]`, not the fallback.
+        return this.transact((transaction) => transaction.setStoredMarks(marks !== undefined ? canonicalMarkOrder(marks) : undefined), {
+            ...options, addToHistory: false,
+        });
+    }
+    undo() {
+        const popped = popUndo(this.currentHistory);
+        if (!popped)
+            return false;
+        const inverse = { ...structuredClone(popped.entry.inverse), baseRevision: this.current.revision };
+        const envelope = applyTransactionAtomic(this.current, inverse, this.schema);
+        this.current = { ...envelope, selection: structuredClone(inverse.selectionAfter), storedMarks: structuredClone(inverse.storedMarksAfter) };
+        this.currentHistory = popped.history;
+        this.notify(inverse);
+        return true;
+    }
+    redo() {
+        const popped = popRedo(this.currentHistory);
+        if (!popped)
+            return false;
+        const forward = { ...structuredClone(popped.entry.forward), baseRevision: this.current.revision, metadata: { ...popped.entry.forward.metadata, addToHistory: false } };
+        const envelope = applyTransactionAtomic(this.current, forward, this.schema);
+        this.current = { ...envelope, selection: structuredClone(forward.selectionAfter), storedMarks: structuredClone(forward.storedMarksAfter) };
+        this.currentHistory = popped.history;
+        this.notify(forward);
+        return true;
+    }
+    subscribe(listener) {
+        this.listeners.add(listener);
+        return () => this.listeners.delete(listener);
+    }
+}
+export const createFoundationEditor = (options) => new FoundationEditor(options);

package/dist/foundation/formats/codec.d.ts

@@ -0,0 +1,45 @@
+import type { SmartDocument, SmartNode } from "../types.js";
+export type FormatId = "html" | "markdown" | "docx" | "pdf";
+export type FormatFidelityLevel = "full" | "semantic" | "lossy" | "unsupported";
+export interface ParseContext {
+    readonly format: FormatId;
+}
+export interface SerializeContext {
+    readonly format: FormatId;
+}
+/**
+ * The per-feature, per-format contract Phase 9 SS2.2 formalizes. Each of the
+ * five foundation features (list, marks, block, table, atom) declares one of
+ * these per format it participates in, rather than a single serializer
+ * containing scattered per-feature type checks.
+ *
+ * `parse`/`serialize` operate on a single feature's node(s) - they are the
+ * semantic mapping rule for "what does this feature mean in this format",
+ * not a whole-document driver. Whole-document assembly (correct ordering
+ * and nesting across all five features together) is a separate concern,
+ * owned by the format's top-level codec (see packages/core/src/foundation/
+ * formats/docx/export.ts, pdf/format.ts, and list/formats.ts's
+ * serializeCanonicalListHtml/serializeCanonicalListMarkdown for HTML/MD).
+ * This mirrors an existing split already present before this contract was
+ * formalized: packages/core/src/foundation/{list,marks,block,table,atom}/
+ * formats.ts already contain canonical*To{Docx,Pdf}* functions with exactly
+ * this per-feature, single-node shape, originally written for fixture-based
+ * fidelity verification (see SS2.3) rather than production document assembly.
+ */
+export interface FeatureFormatCodec<TFeature extends string = string> {
+    readonly feature: TFeature;
+    readonly format: FormatId;
+    readonly fidelity: FormatFidelityLevel;
+    /** Human-readable justification for the fidelity level - required, not decorative (see fidelity.ts's test enforcement). */
+    readonly note: string;
+    parse?: (input: unknown, ctx: ParseContext) => SmartNode | SmartNode[] | null;
+    serialize?: (node: SmartNode, ctx: SerializeContext) => unknown;
+    /** Applied when this feature's fidelity for this format is `lossy` or `unsupported` and no better representation exists. */
+    fallback?: (node: SmartNode) => SmartNode | null;
+}
+/** Whole-document entry points a format must provide, independent of any single feature. */
+export interface DocumentFormatCodec {
+    readonly format: FormatId;
+    parseDocument?: (input: unknown, ctx: ParseContext) => SmartDocument;
+    serializeDocument?: (document: SmartDocument, ctx: SerializeContext) => unknown;
+}

package/dist/foundation/formats/codec.js

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

package/dist/foundation/formats/docx/export.d.ts

@@ -0,0 +1,4 @@
+import type { SmartDocument } from "../../types.js";
+export declare const DOCX_MEDIA_TYPE = "application/vnd.openxmlformats-officedocument.wordprocessingml.document";
+export declare const smartDocumentToDocxXml: (document: SmartDocument) => string;
+export declare const exportDocxDocument: (document: SmartDocument) => Promise<Blob>;