smartrte-react 0.3.3 → 0.3.5

package/dist/components/ClassicEditorAuthority.d.ts

@@ -0,0 +1,38 @@
+import React from "react";
+import { type PersistedEditorDocument } from "smartrte-core/foundation";
+import { type CanonicalAuthorityContext } from "../canonicalAuthorityFlag.js";
+import type { SmartEditorChange, SmartEditorHandle } from "../canonicalEditorRuntime.js";
+import type { MediaProvider } from "../mediaProvider.js";
+import type { MediaPickerComponent } from "./MediaPicker.js";
+import { type CanonicalAuthorityEditorProps } from "./CanonicalAuthorityEditor.js";
+import { type ClassicEditorProps as LegacyClassicEditorProps } from "./ClassicEditor.js";
+export type ClassicEditorProps = Omit<LegacyClassicEditorProps, "value" | "onChange"> & {
+    /** Initial-only under canonical authority. Use replaceValue for external changes. */
+    defaultValue?: string | PersistedEditorDocument;
+    /** Legacy HTML value. Ignored after canonical construction. */
+    value?: string;
+    onChange?: ((change: SmartEditorChange) => void) | ((html: string) => void);
+    onHtmlChange?: (html: string) => void;
+    canonicalAuthority?: boolean;
+    authorityContext?: CanonicalAuthorityContext;
+    mediaProvider?: MediaProvider;
+    mediaPicker?: MediaPickerComponent;
+    onRuntime?: CanonicalAuthorityEditorProps["onRuntime"];
+};
+/**
+ * Uncontrolled by default in canonical mode. The runtime flag supplies a
+ * reversible legacy path during rollout; direct prop override has precedence.
+ */
+export declare const ClassicEditor: React.ForwardRefExoticComponent<Omit<LegacyClassicEditorProps, "value" | "onChange"> & {
+    /** Initial-only under canonical authority. Use replaceValue for external changes. */
+    defaultValue?: string | PersistedEditorDocument;
+    /** Legacy HTML value. Ignored after canonical construction. */
+    value?: string;
+    onChange?: ((change: SmartEditorChange) => void) | ((html: string) => void);
+    onHtmlChange?: (html: string) => void;
+    canonicalAuthority?: boolean;
+    authorityContext?: CanonicalAuthorityContext;
+    mediaProvider?: MediaProvider;
+    mediaPicker?: MediaPickerComponent;
+    onRuntime?: CanonicalAuthorityEditorProps["onRuntime"];
+} & React.RefAttributes<SmartEditorHandle>>;

package/dist/components/ClassicEditorAuthority.js

@@ -0,0 +1,49 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { forwardRef, useRef, useSyncExternalStore } from "react";
+import { foundationSchema, parseCanonicalListHtml, serializeCanonicalListHtml } from "smartrte-core/foundation";
+import { canonicalAuthorityFlag } from "../canonicalAuthorityFlag.js";
+import { CanonicalAuthorityEditor } from "./CanonicalAuthorityEditor.js";
+import { LegacyClassicEditor } from "./ClassicEditor.js";
+/**
+ * Uncontrolled by default in canonical mode. The runtime flag supplies a
+ * reversible legacy path during rollout; direct prop override has precedence.
+ */
+export const ClassicEditor = forwardRef(function ClassicEditor(props, ref) {
+    useSyncExternalStore((listener) => canonicalAuthorityFlag.subscribe(listener), () => canonicalAuthorityFlag.getVersion(), () => canonicalAuthorityFlag.getVersion());
+    const enabled = canonicalAuthorityFlag.enabled(props.authorityContext, props.canonicalAuthority);
+    const latestEnvelope = useRef(typeof props.defaultValue === "object" ? props.defaultValue : undefined);
+    const latestHtml = useRef(typeof props.defaultValue === "string" ? props.defaultValue : props.value);
+    const runtime = useRef(null);
+    if (!enabled) {
+        if (runtime.current) {
+            // Capture once at the authority boundary, not once per keystroke. This is
+            // the ID-preserving rollback envelope; clean HTML remains the legacy view.
+            latestEnvelope.current = runtime.current.getValue();
+            latestHtml.current = serializeCanonicalListHtml(latestEnvelope.current.document, { clean: true });
+            runtime.current = null;
+        }
+        const { defaultValue, onHtmlChange, canonicalAuthority: _canonical, authorityContext: _context, onRuntime: _runtime, mediaProvider: _provider, mediaPicker: _picker, ...legacy } = props;
+        const value = latestEnvelope.current
+            // Internal rollback HTML retains stable IDs. External callbacks receive
+            // the clean representation below.
+            ? serializeCanonicalListHtml(latestEnvelope.current.document, { clean: false })
+            : latestHtml.current ?? (typeof props.value === "string" ? props.value : typeof defaultValue === "string" ? defaultValue : undefined);
+        return _jsx(LegacyClassicEditor, { ...legacy, value: value, onChange: (html) => {
+                const document = parseCanonicalListHtml(html);
+                latestEnvelope.current = {
+                    schemaVersion: foundationSchema.version,
+                    revision: (latestEnvelope.current?.revision || 0) + 1,
+                    document,
+                };
+                const cleanHtml = serializeCanonicalListHtml(document, { clean: true });
+                latestHtml.current = cleanHtml;
+                onHtmlChange?.(cleanHtml);
+                const callback = props.onChange;
+                callback?.(cleanHtml);
+            } });
+    }
+    const { value, canonicalAuthority: _canonical, authorityContext: _context, table: _table, media: _media, formula: _formula, features: _features, plugins: _plugins, formats: _formats, formatDefinitions: _definitions, mediaManager: _manager, fonts: _fonts, defaultFont: _font, preserveFontFamily: _preserveFont, preserveColors: _preserveColors, preserveDocxStyles: _preserveDocx, theme: _theme, showFontSize: _showFontSize, ...canonical } = props;
+    return _jsx(CanonicalAuthorityEditor, { ...canonical, ref: ref, defaultValue: latestEnvelope.current ?? latestHtml.current ?? props.defaultValue ?? value, onChange: (change) => {
+            props.onChange?.(change);
+        }, onHtmlChange: (html) => { latestHtml.current = html; props.onHtmlChange?.(html); }, onRuntime: (value) => { runtime.current = value; props.onRuntime?.(value); } });
+});

package/dist/components/MediaPicker.d.ts

@@ -0,0 +1,10 @@
+import React from "react";
+import type { MediaKind } from "../mediaProvider.js";
+export interface MediaPickerProps {
+    readonly kind: MediaKind;
+    readonly onPick: (file: File) => void;
+    readonly onCancel: () => void;
+}
+export type MediaPickerComponent = React.ComponentType<MediaPickerProps>;
+/** Small replaceable default; hosts can supply a library/search picker later. */
+export declare const DefaultMediaPicker: MediaPickerComponent;

package/dist/components/MediaPicker.js

@@ -0,0 +1,16 @@
+import { jsxs as _jsxs, jsx as _jsx } from "react/jsx-runtime";
+import { useRef } from "react";
+const acceptFor = (kind) => kind === "image" ? "image/*" : `${kind}/*`;
+/** Small replaceable default; hosts can supply a library/search picker later. */
+export const DefaultMediaPicker = ({ kind, onPick, onCancel }) => {
+    const inputRef = useRef(null);
+    return _jsx("div", { role: "dialog", "aria-label": `Choose ${kind}`, style: {
+            position: "fixed", inset: 0, zIndex: 90, display: "grid", placeItems: "center",
+            background: "var(--srte-modal-backdrop)",
+        }, children: _jsxs("div", { style: { background: "var(--srte-modal-bg)", color: "var(--srte-modal-text)", padding: 20, borderRadius: 10, minWidth: 280 }, children: [_jsxs("h3", { style: { marginTop: 0 }, children: ["Insert ", kind] }), _jsx("input", { ref: inputRef, autoFocus: true, type: "file", accept: acceptFor(kind), onChange: (event) => {
+                        const file = event.currentTarget.files?.[0];
+                        if (file)
+                            onPick(file);
+                        event.currentTarget.value = "";
+                    } }), _jsx("button", { type: "button", onClick: onCancel, children: "Cancel" })] }) });
+};

package/dist/editorController.d.ts

@@ -0,0 +1,78 @@
+import type { SmartDocument, SmartEditorState, SmartRtePlugin, SmartSelection, SmartTransaction } from "smartrte-core";
+import { type DomCommandResult } from "./adapters/domCommandBridge.js";
+import { type DomBlockCommand } from "./adapters/domBlockCommandBridge.js";
+import { type DomInlineImageInput } from "./adapters/domInlineImageCommandBridge.js";
+import { type DomFormulaInput } from "./adapters/domInlineAtomCommandBridge.js";
+import { type DomTableCommand } from "./adapters/domTableCommandBridge.js";
+export interface DomEditorControllerSnapshot {
+    document: SmartDocument;
+    selection: SmartSelection | null;
+    html: string;
+}
+export interface DomEditorControllerChange {
+    commandId: string;
+    snapshot: DomEditorControllerSnapshot;
+}
+export type DomEditorControllerListener = (change: DomEditorControllerChange) => void;
+interface DomHistorySnapshot {
+    html: string;
+    selection: SmartSelection | null;
+    version: number;
+    canonical?: {
+        forward: SmartTransaction;
+        inverse: SmartTransaction;
+    };
+}
+/**
+ * Owns the canonical boundary between a contenteditable root and SmartDocument.
+ *
+ * React remains responsible for rendering UI and legacy DOM-only commands while
+ * model commands, document snapshots, serialization, and replacement flow
+ * through this controller.
+ */
+export declare class DomEditorController {
+    private root;
+    private plugins;
+    private readOnly;
+    private readonly listeners;
+    private readonly undoStack;
+    private readonly redoStack;
+    private historyLimit;
+    private mutationVersion;
+    private canonicalState;
+    bindRoot(root: HTMLElement | null): this;
+    configure(options: {
+        plugins?: readonly SmartRtePlugin[];
+        readOnly?: boolean;
+        historyLimit?: number;
+    }): this;
+    snapshot(): DomEditorControllerSnapshot | null;
+    getDocument(): SmartDocument;
+    getState(): SmartEditorState | null;
+    canExecute<Input>(commandId: string, input?: Input): boolean;
+    recordHistorySnapshot(html?: string): boolean;
+    discardLastHistorySnapshot(expectedHtml?: string): boolean;
+    restoreHistory(direction: "undo" | "redo"): DomHistorySnapshot | null;
+    historyStatus(): {
+        undo: number;
+        redo: number;
+        canonicalUndo: number;
+        canonicalRedo: number;
+    };
+    execute<Input>(commandId: string, input?: Input): DomCommandResult | null;
+    executeBlockCommand(blocks: readonly HTMLElement[], command: DomBlockCommand): HTMLElement[] | null;
+    executeChecklistItemCommand(list: HTMLElement, item: HTMLElement, checked?: boolean): HTMLElement | null;
+    insertInlineImage(input: DomInlineImageInput): HTMLImageElement | null;
+    updateInlineImage(image: HTMLImageElement, input: Omit<DomInlineImageInput, "src">): boolean;
+    insertFormula(input: DomFormulaInput): HTMLElement | null;
+    deleteInlineAtom(atom: HTMLElement): boolean;
+    executeTableCommand(table: HTMLTableElement, command: DomTableCommand): HTMLTableElement | null;
+    insertTable(rows: number, columns: number, headerRow?: boolean): HTMLTableElement | null;
+    removeTable(table: HTMLTableElement): boolean;
+    replaceDocument(document: SmartDocument, selection?: SmartSelection): boolean;
+    subscribe(listener: DomEditorControllerListener): () => boolean;
+    private emitLocalizedChange;
+    private promoteHistoryEntry;
+}
+export declare const createDomEditorController: () => DomEditorController;
+export {};

package/dist/editorController.js

@@ -0,0 +1,298 @@
+import { applyTransaction, invertTransaction } from "smartrte-core";
+import { createSmartEditor } from "smartrte-core";
+import { executeDomCommand } from "./adapters/domCommandBridge.js";
+import { executeDomBlockCommand, } from "./adapters/domBlockCommandBridge.js";
+import { executeDomChecklistItemCommand } from "./adapters/domChecklistCommandBridge.js";
+import { executeDomInlineImageCommand, executeDomInlineImageUpdate, } from "./adapters/domInlineImageCommandBridge.js";
+import { executeDomFormulaInsert, executeDomInlineAtomDelete, } from "./adapters/domInlineAtomCommandBridge.js";
+import { executeDomTableCommand, executeDomTableRemoval, } from "./adapters/domTableCommandBridge.js";
+import { restoreSelectionToDom, selectionFromDom } from "./adapters/domSelectionBridge.js";
+import { serializeSmartDocument, smartDocumentFromEditorRoot, smartDocumentFromHtml, } from "./adapters/domSmartDocument.js";
+/**
+ * Owns the canonical boundary between a contenteditable root and SmartDocument.
+ *
+ * React remains responsible for rendering UI and legacy DOM-only commands while
+ * model commands, document snapshots, serialization, and replacement flow
+ * through this controller.
+ */
+export class DomEditorController {
+    constructor() {
+        this.root = null;
+        this.plugins = [];
+        this.readOnly = false;
+        this.listeners = new Set();
+        this.undoStack = [];
+        this.redoStack = [];
+        this.historyLimit = 100;
+        this.mutationVersion = 0;
+        this.canonicalState = null;
+    }
+    bindRoot(root) {
+        this.root = root;
+        return this;
+    }
+    configure(options) {
+        if (options.plugins)
+            this.plugins = options.plugins;
+        if (options.readOnly !== undefined)
+            this.readOnly = options.readOnly;
+        if (options.historyLimit !== undefined) {
+            this.historyLimit = Math.max(1, Math.floor(options.historyLimit));
+        }
+        return this;
+    }
+    snapshot() {
+        if (!this.root)
+            return null;
+        const { document } = smartDocumentFromEditorRoot(this.root);
+        const selection = selectionFromDom(this.root, this.root.ownerDocument.defaultView?.getSelection() || null);
+        const snapshot = {
+            document,
+            selection,
+            html: serializeSmartDocument(document),
+        };
+        this.canonicalState = selection ? { document, selection } : null;
+        return snapshot;
+    }
+    getDocument() {
+        return this.snapshot()?.document || { type: "doc", children: [] };
+    }
+    getState() {
+        const snapshot = this.snapshot();
+        return snapshot?.selection
+            ? { document: snapshot.document, selection: snapshot.selection }
+            : null;
+    }
+    canExecute(commandId, input) {
+        if (!this.root || this.readOnly)
+            return false;
+        const state = this.getState();
+        if (!state)
+            return false;
+        return createSmartEditor({
+            state,
+            plugins: [...this.plugins],
+            readOnly: this.readOnly,
+        }).canExecute(commandId, input);
+    }
+    recordHistorySnapshot(html) {
+        if (!this.root || this.readOnly)
+            return false;
+        const snapshot = this.snapshot();
+        const entry = {
+            html: html ?? this.root.innerHTML,
+            selection: snapshot?.selection || null,
+            version: this.mutationVersion,
+        };
+        if (this.undoStack[this.undoStack.length - 1]?.html === entry.html)
+            return false;
+        this.undoStack.push(entry);
+        this.promoteHistoryEntry(entry, snapshot);
+        if (this.undoStack.length > this.historyLimit)
+            this.undoStack.shift();
+        this.redoStack.length = 0;
+        return true;
+    }
+    discardLastHistorySnapshot(expectedHtml) {
+        const latest = this.undoStack[this.undoStack.length - 1];
+        if (!latest || expectedHtml !== undefined && latest.html !== expectedHtml)
+            return false;
+        this.undoStack.pop();
+        return true;
+    }
+    restoreHistory(direction) {
+        if (!this.root || this.readOnly)
+            return null;
+        const from = direction === "undo" ? this.undoStack : this.redoStack;
+        const to = direction === "undo" ? this.redoStack : this.undoStack;
+        let entry;
+        while (from.length) {
+            const candidate = from.pop();
+            if (candidate.html !== this.root.innerHTML) {
+                entry = candidate;
+                break;
+            }
+        }
+        if (!entry)
+            return null;
+        const current = this.snapshot();
+        if (entry.canonical && current) {
+            const transaction = direction === "undo"
+                ? entry.canonical.inverse
+                : entry.canonical.forward;
+            this.canonicalState = applyTransaction({ document: current.document, selection: current.selection || { type: "all" } }, transaction);
+        }
+        to.push({
+            html: this.root.innerHTML,
+            selection: current?.selection || null,
+            canonical: entry.canonical,
+            version: this.mutationVersion,
+        });
+        this.root.innerHTML = entry.html;
+        this.mutationVersion += 1;
+        if (entry.selection)
+            restoreSelectionToDom(this.root, entry.selection);
+        return entry;
+    }
+    historyStatus() {
+        return {
+            undo: this.undoStack.length,
+            redo: this.redoStack.length,
+            canonicalUndo: this.undoStack.filter((entry) => entry.canonical).length,
+            canonicalRedo: this.redoStack.filter((entry) => entry.canonical).length,
+        };
+    }
+    execute(commandId, input) {
+        if (!this.root || this.readOnly)
+            return null;
+        const result = executeDomCommand({
+            root: this.root,
+            plugins: [...this.plugins],
+            commandId,
+            input,
+        });
+        if (!result)
+            return null;
+        this.emitLocalizedChange(commandId);
+        return result;
+    }
+    executeBlockCommand(blocks, command) {
+        if (!this.root || this.readOnly || blocks.some((block) => !this.root.contains(block))) {
+            return null;
+        }
+        const replacements = executeDomBlockCommand(blocks, command);
+        if (!replacements)
+            return null;
+        this.emitLocalizedChange(command.id);
+        return replacements;
+    }
+    executeChecklistItemCommand(list, item, checked) {
+        if (!this.root ||
+            this.readOnly ||
+            !this.root.contains(list) ||
+            !list.contains(item)) {
+            return null;
+        }
+        const result = executeDomChecklistItemCommand(list, item, checked);
+        if (!result)
+            return null;
+        this.emitLocalizedChange("checklist.set-checked");
+        return result;
+    }
+    insertInlineImage(input) {
+        if (!this.root || this.readOnly)
+            return null;
+        const image = executeDomInlineImageCommand(this.root, input);
+        if (!image)
+            return null;
+        this.emitLocalizedChange("image.insert-inline");
+        return image;
+    }
+    updateInlineImage(image, input) {
+        if (!this.root || this.readOnly || !this.root.contains(image))
+            return false;
+        if (!executeDomInlineImageUpdate(this.root, image, input))
+            return false;
+        this.emitLocalizedChange("image.update-inline");
+        return true;
+    }
+    insertFormula(input) {
+        if (!this.root || this.readOnly)
+            return null;
+        const formula = executeDomFormulaInsert(this.root, input);
+        if (!formula)
+            return null;
+        this.emitLocalizedChange("formula.insert");
+        return formula;
+    }
+    deleteInlineAtom(atom) {
+        if (!this.root || this.readOnly || !this.root.contains(atom))
+            return false;
+        const commandId = atom.hasAttribute("data-formula") ? "formula.delete" : "image.delete-inline";
+        if (!executeDomInlineAtomDelete(this.root, atom))
+            return false;
+        this.emitLocalizedChange(commandId);
+        return true;
+    }
+    executeTableCommand(table, command) {
+        if (!this.root || this.readOnly || !this.root.contains(table))
+            return null;
+        const replacement = executeDomTableCommand(table, command);
+        if (!replacement)
+            return null;
+        this.emitLocalizedChange(command.id);
+        return replacement;
+    }
+    insertTable(rows, columns, headerRow = false) {
+        if (!this.root || this.readOnly)
+            return null;
+        const snapshot = this.snapshot();
+        if (!snapshot?.selection || snapshot.selection.type !== "text")
+            return null;
+        const topLevelIndex = snapshot.selection.anchor.path[0];
+        if (!Number.isInteger(topLevelIndex))
+            return null;
+        const path = [Math.min(topLevelIndex + 1, snapshot.document.children.length)];
+        const result = this.execute("table.insert", { path, rows, columns, headerRow });
+        if (!result)
+            return null;
+        const candidate = this.root.children[path[0]];
+        if (candidate instanceof HTMLTableElement)
+            return candidate;
+        return candidate?.querySelector("table") || null;
+    }
+    removeTable(table) {
+        if (!this.root || this.readOnly || !this.root.contains(table))
+            return false;
+        if (!executeDomTableRemoval(table))
+            return false;
+        this.emitLocalizedChange("table.remove");
+        return true;
+    }
+    replaceDocument(document, selection) {
+        if (!this.root || this.readOnly)
+            return false;
+        this.root.innerHTML = serializeSmartDocument(document);
+        if (selection)
+            restoreSelectionToDom(this.root, selection);
+        return true;
+    }
+    subscribe(listener) {
+        this.listeners.add(listener);
+        return () => this.listeners.delete(listener);
+    }
+    emitLocalizedChange(commandId) {
+        const snapshot = this.snapshot();
+        if (snapshot) {
+            const latest = this.undoStack[this.undoStack.length - 1];
+            if (latest?.version === this.mutationVersion) {
+                this.promoteHistoryEntry(latest, snapshot, commandId);
+            }
+            this.mutationVersion += 1;
+            this.listeners.forEach((listener) => listener({ commandId, snapshot }));
+        }
+    }
+    promoteHistoryEntry(entry, after, commandId = "dom.canonical") {
+        if (!this.root || !after || entry.canonical || entry.html === this.root.innerHTML)
+            return;
+        const beforeDocument = smartDocumentFromHtml(entry.html, this.root.ownerDocument);
+        if (JSON.stringify(beforeDocument) === JSON.stringify(after.document))
+            return;
+        const beforeSelection = entry.selection || { type: "all" };
+        const afterSelection = after.selection || { type: "all" };
+        const forward = {
+            id: commandId,
+            source: "user",
+            operations: [{ type: "replaceNode", path: [], node: after.document }],
+            selectionBefore: beforeSelection,
+            selectionAfter: afterSelection,
+            addToHistory: true,
+            timestamp: Date.now(),
+        };
+        entry.canonical = {
+            forward,
+            inverse: invertTransaction({ document: beforeDocument, selection: beforeSelection }, forward),
+        };
+    }
+}
+export const createDomEditorController = () => new DomEditorController();

package/dist/formatFidelity.d.ts

@@ -0,0 +1,14 @@
+export type FidelityFormat = "html" | "markdown" | "docx" | "pdf";
+export type FidelityLevel = "full" | "semantic" | "lossy" | "unsupported";
+export type FidelityFeature = "inline-marks" | "colors-fonts-sizes" | "headings-alignment" | "blockquote-code" | "lists" | "checklists" | "tables" | "links" | "images-media" | "formulas" | "special-characters";
+export interface FormatFidelityCapability {
+    level: FidelityLevel;
+    note: string;
+}
+export interface FeatureFidelityContract {
+    feature: FidelityFeature;
+    formats: Record<FidelityFormat, FormatFidelityCapability>;
+}
+/** Public, test-enforced compatibility contract for built-in document formats. */
+export declare const builtInFormatFidelity: readonly FeatureFidelityContract[];
+export declare const getFormatFidelity: (feature: FidelityFeature, format: FidelityFormat) => FormatFidelityCapability;

package/dist/formatFidelity.js

@@ -0,0 +1,107 @@
+const capability = (level, note) => ({
+    level,
+    note,
+});
+/** Public, test-enforced compatibility contract for built-in document formats. */
+export const builtInFormatFidelity = [
+    {
+        feature: "inline-marks",
+        formats: {
+            html: capability("full", "Canonical marks round-trip."),
+            markdown: capability("semantic", "Bold, italic, strike, code, and links round-trip; underline is lossy."),
+            docx: capability("semantic", "Supported Word run properties round-trip through the canonical importer."),
+            pdf: capability("lossy", "Visual emphasis is inferred from extracted font metadata."),
+        },
+    },
+    {
+        feature: "colors-fonts-sizes",
+        formats: {
+            html: capability("full", "Inline style marks round-trip."),
+            markdown: capability("unsupported", "Portable Markdown has no standard representation."),
+            docx: capability("semantic", "Colors and sizes are supported; font-family fidelity depends on importer styles."),
+            pdf: capability("lossy", "Font size/style are inferred; colors are extraction-dependent."),
+        },
+    },
+    {
+        feature: "headings-alignment",
+        formats: {
+            html: capability("full", "Levels, alignment, and indentation round-trip."),
+            markdown: capability("lossy", "Heading levels round-trip; alignment and indentation do not."),
+            docx: capability("semantic", "Heading styles, alignment, and indentation are emitted."),
+            pdf: capability("lossy", "Levels and alignment are inferred geometrically."),
+        },
+    },
+    {
+        feature: "blockquote-code",
+        formats: {
+            html: capability("full", "Canonical block structure round-trips."),
+            markdown: capability("semantic", "Portable blockquote and code syntax round-trip."),
+            docx: capability("lossy", "Structure is represented with paragraph styling."),
+            pdf: capability("lossy", "Export is visual and import reconstruction is heuristic."),
+        },
+    },
+    {
+        feature: "lists",
+        formats: {
+            html: capability("full", "Nested list structure and styles round-trip."),
+            markdown: capability("semantic", "Nested ordered and unordered structure round-trips; custom markers are lossy."),
+            docx: capability("semantic", "Nested lists export with native Word numbering definitions and level metadata."),
+            pdf: capability("lossy", "List structure is inferred from extracted markers."),
+        },
+    },
+    {
+        feature: "checklists",
+        formats: {
+            html: capability("full", "Checked state uses canonical data attributes."),
+            markdown: capability("semantic", "GFM task-list state round-trips."),
+            docx: capability("lossy", "Checklist semantics currently degrade to visible list content."),
+            pdf: capability("lossy", "Checklist semantics are visual only."),
+        },
+    },
+    {
+        feature: "tables",
+        formats: {
+            html: capability("full", "Spans, headers, colors, borders, and dimensions round-trip."),
+            markdown: capability("lossy", "GFM tables preserve text but not spans, dimensions, colors, or borders."),
+            docx: capability("semantic", "Table structure and column spans export; advanced layout remains partial."),
+            pdf: capability("lossy", "Export is visual and import uses column-position heuristics."),
+        },
+    },
+    {
+        feature: "links",
+        formats: {
+            html: capability("full", "Safe href and target semantics round-trip."),
+            markdown: capability("semantic", "Href and label round-trip; target metadata is lossy."),
+            docx: capability("semantic", "Links export as native external Word hyperlink relationships; target behavior is advisory."),
+            pdf: capability("lossy", "Links are visual text in the current print/export path."),
+        },
+    },
+    {
+        feature: "images-media",
+        formats: {
+            html: capability("semantic", "Images, audio, and video round-trip; host-only metadata may be lossy."),
+            markdown: capability("lossy", "Inline images round-trip; audio and video are unsupported."),
+            docx: capability("semantic", "Data-URL PNG, JPEG, and GIF images embed natively; remote and unsupported sources retain portable markers."),
+            pdf: capability("lossy", "Export is visual; semantic media import is unsupported."),
+        },
+    },
+    {
+        feature: "formulas",
+        formats: {
+            html: capability("full", "Formula source is stored canonically."),
+            markdown: capability("semantic", "Dollar-delimited formula source round-trips."),
+            docx: capability("semantic", "Formulas emit native OMML linear math and retain a hidden portable source marker for canonical round-trip."),
+            pdf: capability("lossy", "Rendered output is visual; source cannot be reconstructed reliably."),
+        },
+    },
+    {
+        feature: "special-characters",
+        formats: {
+            html: capability("full", "Unicode text round-trips."),
+            markdown: capability("full", "Unicode text round-trips."),
+            docx: capability("full", "Unicode text is emitted as Word text."),
+            pdf: capability("semantic", "Depends on font embedding and extractor Unicode maps."),
+        },
+    },
+];
+export const getFormatFidelity = (feature, format) => builtInFormatFidelity.find((entry) => entry.feature === feature).formats[format];

package/dist/formatRuntime.d.ts

@@ -0,0 +1,50 @@
+import type { SmartDocument } from "smartrte-core";
+export type BuiltInDocumentFormat = "html" | "markdown" | "docx" | "pdf";
+export type EditorDocumentFormat = BuiltInDocumentFormat | (string & {});
+export type EditorFormatConfig = Partial<Record<EditorDocumentFormat, boolean>>;
+export interface EditorFormatImportContext {
+    ownerDocument: Document;
+}
+export interface EditorFormatImportResult {
+    document: SmartDocument;
+    layoutHtml?: string;
+    preserveColors?: boolean;
+    preserveDocumentLayout?: boolean;
+}
+export type EditorFormatExportResult = {
+    kind: "text";
+    filename: string;
+    mediaType: string;
+    content: string;
+} | {
+    kind: "blob";
+    filename: string;
+    content: Blob;
+} | {
+    kind: "handled";
+};
+export interface EditorFormatExportContext {
+    ownerDocument: Document;
+    hostWindow: Window;
+}
+export interface EditorFormatDefinition {
+    id: EditorDocumentFormat;
+    label: string;
+    extension: string;
+    accept?: string;
+    canImport: boolean;
+    canExport: boolean;
+    confirmImportWhenNotEmpty?: boolean;
+    importFile?: (file: File, context: EditorFormatImportContext) => Promise<EditorFormatImportResult>;
+    exportDocument?: (document: SmartDocument, context: EditorFormatExportContext) => EditorFormatExportResult | Promise<EditorFormatExportResult>;
+}
+export interface EditorFormatRuntime {
+    formats: readonly EditorFormatDefinition[];
+    imports: readonly EditorFormatDefinition[];
+    exports: readonly EditorFormatDefinition[];
+    has: (format: string) => boolean;
+    get: (format: string) => EditorFormatDefinition | undefined;
+    canImport: (format: string) => boolean;
+    canExport: (format: string) => boolean;
+}
+export declare const createEditorFormatRuntime: (config?: EditorFormatConfig, replacements?: readonly EditorFormatDefinition[]) => EditorFormatRuntime;