smartrte-react 0.3.4 → 1.0.0-beta.1

package/dist/adapters/shadowMode.d.ts

@@ -1,4 +1,4 @@
-import { type CommandContext, type SmartCommand, type SmartEditorState, type SmartTransaction } from "smartrte-core";
+import { type LegacyCommandContext, type SmartCommand, type SmartEditorState, type LegacySmartTransaction } from "smartrte-core/legacy";
 export interface ShadowComparison {
     commandId: string;
     matches: boolean;
@@ -15,9 +15,9 @@ export declare const reportShadowDifference: (comparison: ShadowComparison) => v
  */
 export declare const runShadowCommand: <Input>(args: {
     command: SmartCommand<Input>;
-    context: CommandContext;
+    context: LegacyCommandContext;
     input?: Input;
     state: SmartEditorState;
     legacyHtml: string;
     serialize: (state: SmartEditorState) => string;
-}) => SmartTransaction | null;
+}) => LegacySmartTransaction | null;

package/dist/adapters/shadowMode.js

@@ -1,4 +1,4 @@
-import { applyTransaction, normalizeCompatibilityHtml, } from "smartrte-core";
+import { applyTransaction, normalizeCompatibilityHtml, } from "smartrte-core/legacy";
 import { isShadowModeFlagEnabled } from "./internalFlags.js";
 const semanticHtml = (html) => normalizeCompatibilityHtml(html)
     .replace(/<(\/?)b(?=[\s>])/g, "<$1strong")

package/dist/canonicalEditorRuntime.d.ts

@@ -0,0 +1,129 @@
+import { type CanonicalInputPipeline, type ClipboardDiagnosticReport, type CanonicalSubtreeRenderer, type DocumentVersion, type FoundationEditor, type PersistedEditorDocument, type SmartMark, type SmartOperation, type SmartSelection, type SmartTransaction } from "smartrte-core/foundation";
+import { type EditorCapabilityPreset } from "./capabilityPresets.js";
+export interface SmartEditorCheckpoint {
+    envelope: PersistedEditorDocument;
+    selection: SmartSelection;
+    storedMarks?: SmartMark[];
+    savedRevision: number;
+}
+export interface SmartEditorChange {
+    revision: number;
+    documentChanged: boolean;
+    transaction: SmartTransaction;
+}
+export interface SmartEditorHandle {
+    getValue(): PersistedEditorDocument;
+    replaceValue(doc: PersistedEditorDocument, opts?: {
+        keepSelection?: boolean;
+    }): void;
+    isDirty(): boolean;
+    markSaved(revision: number): void;
+    getRevision(): number;
+    focus(): void;
+    executeOperations(operations: readonly SmartOperation[], opts?: ExecuteOperationsOptions): void;
+    createCheckpoint(): SmartEditorCheckpoint;
+    restoreCheckpoint(checkpoint: SmartEditorCheckpoint): void;
+    saveVersion(opts?: SaveVersionOptions): DocumentVersion;
+    restoreVersion(version: DocumentVersion, opts?: {
+        keepSelection?: boolean;
+    }): void;
+}
+export interface SaveVersionOptions {
+    label?: string;
+    authorId?: string;
+}
+export interface ExecuteOperationsOptions {
+    historyGroup?: string;
+    addToHistory?: boolean;
+    /** Keep structural commands anchored to the same stable inline-owner IDs. */
+    preserveSelectionById?: boolean;
+    /** Put the caret in a newly-created inline owner after the operation. */
+    selectionOwnerId?: string;
+    selectionOffset?: number;
+}
+export interface CanonicalEditorRuntimeOptions {
+    initialValue?: string | PersistedEditorDocument;
+    onChange?: (change: SmartEditorChange) => void;
+    onHtmlChange?: (html: string) => void;
+    onClipboardDiagnostic?: (report: ClipboardDiagnosticReport) => void;
+    /**
+     * Renderer-integrated content-visibility (Phase 11 Tier 3, opt-in,
+     * default off) - only applies content-visibility:auto to a top-level
+     * block the renderer's own diff already proved untouched this render
+     * pass and that isn't the actively-selected block. See
+     * surface/renderer.ts's syncContentVisibility for why this differs from
+     * the disproven naive per-block experiment.
+     */
+    contentVisibility?: boolean;
+    /** Which built-in plugins this instance is constructed with - see capabilityPresets.ts. Defaults to "full" (every plugin), matching this runtime's only behavior before this option existed. */
+    preset?: EditorCapabilityPreset;
+}
+/** Persistent, React-independent owner for one product editor instance. */
+export declare class CanonicalEditorRuntime implements SmartEditorHandle {
+    readonly editor: FoundationEditor;
+    private root;
+    private renderer;
+    private pipeline;
+    private unsubscribe;
+    private savedRevision;
+    private onChange?;
+    private onHtmlChange?;
+    private readonly onClipboardDiagnostic?;
+    private readonly contentVisibility;
+    private htmlChangeTimer;
+    private pendingHtmlDocument;
+    constructor(options?: CanonicalEditorRuntimeOptions);
+    setCallbacks(onChange?: (change: SmartEditorChange) => void, onHtmlChange?: (html: string) => void): void;
+    private scheduleHtmlChange;
+    mount(root: HTMLElement): void;
+    unmount(): void;
+    getValue(): PersistedEditorDocument;
+    replaceValue(doc: PersistedEditorDocument, opts?: {
+        keepSelection?: boolean;
+    }): void;
+    isDirty(): boolean;
+    markSaved(revision: number): void;
+    getRevision(): number;
+    focus(): void;
+    executeOperations(operations: readonly SmartOperation[], opts?: ExecuteOperationsOptions): void;
+    createCheckpoint(): SmartEditorCheckpoint;
+    restoreCheckpoint(checkpoint: SmartEditorCheckpoint): void;
+    /**
+     * A pure read of current state, like `createCheckpoint` - never touches
+     * the undo stack, never a `transact()` call. The runtime doesn't call a
+     * `VersionProvider` itself (same division as `mediaProvider.upload`
+     * being called directly from the React component, not the runtime) -
+     * this just builds the payload a caller then hands to a provider.
+     */
+    saveVersion(opts?: SaveVersionOptions): DocumentVersion;
+    /**
+     * Reuses `replaceValue` (the same "load a full snapshot" mechanism
+     * `restoreCheckpoint` already uses) rather than replaying the version as
+     * a sequence of operations - a version can be arbitrarily old, and
+     * `replaceState` already validates/repairs an incoming document the same
+     * way loading any document does. Deliberately does NOT reuse the
+     * version's own stored `revision`: `replaceState` sets the live
+     * revision counter to whatever it's given verbatim, so restoring an old
+     * version's envelope as-is would roll a monotonic counter backward -
+     * colliding with `StaleTransactionError`'s bookkeeping and this
+     * runtime's own `isDirty()` comparison. Always re-stamps to
+     * `currentRevision + 1` instead. Not undoable, same as checkpoint
+     * restore today (`replaceState`'s emitted transaction always sets
+     * `addToHistory: false`). Per the Phase 12a spec's explicit
+     * recommendation, restore is non-destructive of version history at the
+     * UI layer: the caller (`VersionHistoryPanel`) saves a new version
+     * recording the restored state immediately after calling this, rather
+     * than this method silently discarding anything - the version list only
+     * ever grows, never rewrites.
+     */
+    restoreVersion(version: DocumentVersion, opts?: {
+        keepSelection?: boolean;
+    }): void;
+    /** Instrumentation for product-path composition and takeover tests. */
+    get surface(): {
+        root: HTMLElement;
+        renderer: CanonicalSubtreeRenderer;
+        pipeline: CanonicalInputPipeline;
+    };
+}
+export declare const createCanonicalEditorRuntime: (options?: CanonicalEditorRuntimeOptions) => CanonicalEditorRuntime;

package/dist/canonicalEditorRuntime.js

@@ -0,0 +1,331 @@
+import { createFoundationEditor, applyOperations, createInputPipeline, createNodeId, createSubtreeRenderer, createTransactionMap, foundationSchema, isTextNode, parseCanonicalListHtml, serializeCanonicalListHtml, } from "smartrte-core/foundation";
+import { capabilityPresetRegistry } from "./capabilityPresets.js";
+const nodeAtPath = (root, path) => {
+    let node = root;
+    for (const index of path) {
+        if (isTextNode(node) || !node.children?.[index])
+            return null;
+        node = node.children[index];
+    }
+    return node;
+};
+const pathOfNode = (root, nodeId, path = []) => {
+    if (!isTextNode(root) && root.id === nodeId)
+        return path;
+    if (isTextNode(root))
+        return null;
+    for (let index = 0; index < (root.children?.length || 0); index += 1) {
+        const found = pathOfNode(root.children[index], nodeId, [...path, index]);
+        if (found)
+            return found;
+    }
+    return null;
+};
+const inlineWidth = (node) => isTextNode(node)
+    ? node.text.length
+    : node.children?.reduce((width, child) => width + (isTextNode(child) ? child.text.length : 1), 0) ?? 0;
+const firstTextSelection = (document) => {
+    const visit = (node, path) => {
+        if (isTextNode(node))
+            return null;
+        const spec = foundationSchema.nodes[node.type];
+        const children = node.children || [];
+        // Atomic nodes (e.g. block_image) never accept a text caret inside them,
+        // even when they report an empty children array - only a genuine
+        // text-content container (an empty or all-inline block) is a valid
+        // first-text-selection target.
+        if (spec?.group === "block" && !spec.atomic && (children.length === 0 || children.every((child) => isTextNode(child) || foundationSchema.nodes[child.type]?.group === "inline")))
+            return { path, offset: 0 };
+        for (let index = 0; index < children.length; index += 1) {
+            const found = visit(children[index], [...path, index]);
+            if (found)
+                return found;
+        }
+        return null;
+    };
+    const pos = visit(document, []) || { path: [], offset: 0 };
+    return { type: "text", anchor: pos, head: pos };
+};
+const envelopeFrom = (value) => {
+    if (typeof value === "object" && value)
+        return structuredClone(value);
+    const document = parseCanonicalListHtml(typeof value === "string" ? value : "<p></p>");
+    return { schemaVersion: foundationSchema.version, revision: 0, document };
+};
+const sameOperations = (transaction) => transaction.operations.length > 0;
+const cellIdAt = (document, position) => {
+    const node = nodeAtPath(document, position.path);
+    return node && !isTextNode(node) && node.type === "table_cell" ? node.id : null;
+};
+const cellSelectionIn = (document, anchorId, headId) => {
+    const anchorPath = pathOfNode(document, anchorId) || pathOfNode(document, headId);
+    const headPath = pathOfNode(document, headId) || anchorPath;
+    if (!anchorPath || !headPath)
+        return null;
+    const anchor = nodeAtPath(document, anchorPath);
+    const head = nodeAtPath(document, headPath);
+    if (!anchor || isTextNode(anchor) || anchor.type !== "table_cell"
+        || !head || isTextNode(head) || head.type !== "table_cell")
+        return null;
+    return {
+        type: "cell",
+        anchor: { path: anchorPath, offset: 0 },
+        head: { path: headPath, offset: head.children?.length || 0 },
+    };
+};
+/** Persistent, React-independent owner for one product editor instance. */
+export class CanonicalEditorRuntime {
+    constructor(options = {}) {
+        this.root = null;
+        this.renderer = null;
+        this.pipeline = null;
+        this.unsubscribe = null;
+        this.htmlChangeTimer = null;
+        this.pendingHtmlDocument = null;
+        const envelope = envelopeFrom(options.initialValue);
+        // "full" (the default) intentionally passes no schema/commands/etc., so
+        // FoundationEditor's own defaulting (`options.schema || foundationSchema`)
+        // applies - every existing consumer who never sets `preset` is
+        // byte-for-byte unaffected by this option existing.
+        const registry = options.preset && options.preset !== "full" ? capabilityPresetRegistry(options.preset) : null;
+        this.editor = createFoundationEditor({
+            document: envelope.document,
+            revision: envelope.revision,
+            selection: firstTextSelection(envelope.document),
+            ...(registry ? { schema: registry.schema, commands: registry.commands, keyboardShortcuts: registry.keyboardShortcuts, contextMenu: registry.contextMenu } : {}),
+        });
+        this.savedRevision = envelope.revision;
+        this.onChange = options.onChange;
+        this.onHtmlChange = options.onHtmlChange;
+        this.onClipboardDiagnostic = options.onClipboardDiagnostic;
+        this.contentVisibility = options.contentVisibility === true;
+    }
+    setCallbacks(onChange, onHtmlChange) {
+        this.onChange = onChange;
+        this.onHtmlChange = onHtmlChange;
+    }
+    scheduleHtmlChange(document) {
+        if (!this.onHtmlChange)
+            return;
+        this.pendingHtmlDocument = document;
+        const view = this.root?.ownerDocument.defaultView;
+        if (this.htmlChangeTimer !== null) {
+            if (view)
+                view.clearTimeout(this.htmlChangeTimer);
+            else
+                globalThis.clearTimeout(this.htmlChangeTimer);
+        }
+        const flush = () => {
+            this.htmlChangeTimer = null;
+            const pending = this.pendingHtmlDocument;
+            this.pendingHtmlDocument = null;
+            if (pending && this.onHtmlChange)
+                this.onHtmlChange(serializeCanonicalListHtml(pending, { clean: true }));
+        };
+        if (view) {
+            // Transitional HTML serialization is intentionally debounced outside the
+            // typing frame. The canonical onChange contract remains per transaction.
+            this.htmlChangeTimer = view.setTimeout(flush, 250);
+        }
+        else {
+            this.htmlChangeTimer = setTimeout(flush, 250);
+        }
+    }
+    mount(root) {
+        if (this.root === root && this.pipeline && this.renderer)
+            return;
+        this.unmount();
+        this.root = root;
+        this.renderer = createSubtreeRenderer(root, { contentVisibility: this.contentVisibility });
+        this.pipeline = createInputPipeline(this.editor, this.renderer, root, { onClipboardDiagnostic: this.onClipboardDiagnostic });
+        this.unsubscribe = this.editor.subscribe((transaction, state) => {
+            this.renderer?.render(this.editor.document, this.editor.selection);
+            this.onChange?.({ revision: state.revision, documentChanged: sameOperations(transaction), transaction });
+            if (sameOperations(transaction))
+                this.scheduleHtmlChange(state.document);
+        });
+    }
+    unmount() {
+        this.unsubscribe?.();
+        this.unsubscribe = null;
+        this.pipeline?.destroy();
+        this.pipeline = null;
+        this.renderer?.destroy();
+        this.renderer = null;
+        const view = this.root?.ownerDocument.defaultView;
+        if (this.htmlChangeTimer !== null) {
+            if (view)
+                view.clearTimeout(this.htmlChangeTimer);
+            else
+                globalThis.clearTimeout(this.htmlChangeTimer);
+        }
+        this.htmlChangeTimer = null;
+        this.pendingHtmlDocument = null;
+        this.root?.replaceChildren();
+        this.root = null;
+    }
+    getValue() {
+        const state = this.editor.state;
+        return { schemaVersion: state.schemaVersion, revision: state.revision, document: state.document };
+    }
+    replaceValue(doc, opts = {}) {
+        let selection = firstTextSelection(doc.document);
+        if (opts.keepSelection) {
+            const current = this.editor.selection;
+            const owner = nodeAtPath(this.editor.document, current.head.path);
+            if (owner && !isTextNode(owner)) {
+                const find = (node, path) => {
+                    if (!isTextNode(node) && node.id === owner.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], [...path, index]);
+                        if (found)
+                            return found;
+                    }
+                    return null;
+                };
+                const path = find(doc.document, []);
+                if (path) {
+                    const replacementOwner = nodeAtPath(doc.document, path);
+                    const offset = Math.min(current.head.offset, inlineWidth(replacementOwner));
+                    const pos = { path, offset };
+                    selection = { type: "text", anchor: pos, head: pos };
+                }
+            }
+        }
+        this.editor.replaceState(doc, { selection });
+    }
+    isDirty() { return this.editor.state.revision !== this.savedRevision; }
+    markSaved(revision) {
+        if (revision > this.editor.state.revision)
+            throw new Error("Cannot mark a future revision as saved.");
+        this.savedRevision = revision;
+    }
+    getRevision() { return this.editor.state.revision; }
+    focus() { this.root?.focus(); }
+    executeOperations(operations, opts = {}) {
+        if (!operations.length)
+            return;
+        const beforeSelection = this.editor.selection;
+        let selection = createTransactionMap(operations).mapSelection(beforeSelection);
+        if (opts.selectionOwnerId || opts.preserveSelectionById) {
+            const beforeDocument = this.editor.document;
+            const preview = applyOperations(beforeDocument, operations);
+            const beforeCellAnchor = beforeSelection.type === "cell" ? cellIdAt(beforeDocument, beforeSelection.anchor) : null;
+            const beforeCellHead = beforeSelection.type === "cell" ? cellIdAt(beforeDocument, beforeSelection.head) : null;
+            let preservedCellSelection = false;
+            if (opts.preserveSelectionById && beforeCellAnchor && beforeCellHead) {
+                // Structural table commands may retire the head cell (merge) while
+                // preserving the anchor. Keep the selection on the surviving cell so
+                // the next table command still has an unambiguous scope.
+                const mappedCells = cellSelectionIn(preview, beforeCellAnchor, beforeCellHead);
+                if (mappedCells) {
+                    selection = mappedCells;
+                    preservedCellSelection = true;
+                }
+            }
+            const point = (pos, forcedId) => {
+                const beforeOwner = nodeAtPath(beforeDocument, pos.path);
+                const ownerId = forcedId || (!beforeOwner || isTextNode(beforeOwner) ? undefined : beforeOwner.id);
+                if (!ownerId)
+                    return null;
+                const path = pathOfNode(preview, ownerId);
+                if (!path)
+                    return null;
+                const owner = nodeAtPath(preview, path);
+                if (!owner)
+                    return null;
+                return { path, offset: Math.min(forcedId ? opts.selectionOffset ?? 0 : pos.offset, inlineWidth(owner)) };
+            };
+            if (preservedCellSelection) {
+                // The cell selection was mapped above; do not reinterpret its
+                // structural endpoints as a text selection.
+            }
+            else if (opts.selectionOwnerId) {
+                const caret = point(beforeSelection.head, opts.selectionOwnerId);
+                if (caret)
+                    selection = { type: "text", anchor: caret, head: caret };
+            }
+            else {
+                const anchor = point(beforeSelection.anchor);
+                const head = point(beforeSelection.head);
+                if (anchor && head)
+                    selection = { ...beforeSelection, anchor, head };
+            }
+        }
+        this.editor.transact((builder) => {
+            builder.operations.push(...operations);
+            builder.setSelection(selection);
+        }, {
+            source: "toolbar",
+            addToHistory: opts.addToHistory ?? true,
+            ...(opts.historyGroup ? { historyGroup: opts.historyGroup } : {}),
+        });
+        // Skipped for a non-history (preview) operation: focusing the main
+        // editor surface would steal keyboard/pointer focus away from whatever
+        // UI is driving the preview (e.g. ColorPickerPopover's native color
+        // input mid-drag) on every single preview frame - breaking Escape-to-
+        // cancel and, in a real browser, potentially interrupting the drag
+        // itself. A real, history-eligible commit still focuses as before.
+        if (opts.addToHistory ?? true)
+            this.focus();
+    }
+    createCheckpoint() {
+        return {
+            envelope: this.getValue(),
+            selection: this.editor.selection,
+            ...(this.editor.storedMarks?.length ? { storedMarks: [...structuredClone(this.editor.storedMarks)] } : {}),
+            savedRevision: this.savedRevision,
+        };
+    }
+    restoreCheckpoint(checkpoint) {
+        this.editor.replaceState(checkpoint.envelope, {
+            selection: checkpoint.selection,
+            storedMarks: checkpoint.storedMarks,
+        });
+        this.savedRevision = checkpoint.savedRevision;
+    }
+    /**
+     * A pure read of current state, like `createCheckpoint` - never touches
+     * the undo stack, never a `transact()` call. The runtime doesn't call a
+     * `VersionProvider` itself (same division as `mediaProvider.upload`
+     * being called directly from the React component, not the runtime) -
+     * this just builds the payload a caller then hands to a provider.
+     */
+    saveVersion(opts = {}) {
+        return { id: createNodeId(), createdAt: Date.now(), envelope: this.getValue(), ...(opts.label ? { label: opts.label } : {}), ...(opts.authorId ? { authorId: opts.authorId } : {}) };
+    }
+    /**
+     * Reuses `replaceValue` (the same "load a full snapshot" mechanism
+     * `restoreCheckpoint` already uses) rather than replaying the version as
+     * a sequence of operations - a version can be arbitrarily old, and
+     * `replaceState` already validates/repairs an incoming document the same
+     * way loading any document does. Deliberately does NOT reuse the
+     * version's own stored `revision`: `replaceState` sets the live
+     * revision counter to whatever it's given verbatim, so restoring an old
+     * version's envelope as-is would roll a monotonic counter backward -
+     * colliding with `StaleTransactionError`'s bookkeeping and this
+     * runtime's own `isDirty()` comparison. Always re-stamps to
+     * `currentRevision + 1` instead. Not undoable, same as checkpoint
+     * restore today (`replaceState`'s emitted transaction always sets
+     * `addToHistory: false`). Per the Phase 12a spec's explicit
+     * recommendation, restore is non-destructive of version history at the
+     * UI layer: the caller (`VersionHistoryPanel`) saves a new version
+     * recording the restored state immediately after calling this, rather
+     * than this method silently discarding anything - the version list only
+     * ever grows, never rewrites.
+     */
+    restoreVersion(version, opts = {}) {
+        const restamped = {
+            schemaVersion: version.envelope.schemaVersion,
+            revision: this.getRevision() + 1,
+            document: version.envelope.document,
+        };
+        this.replaceValue(restamped, opts);
+    }
+    /** Instrumentation for product-path composition and takeover tests. */
+    get surface() { return { root: this.root, renderer: this.renderer, pipeline: this.pipeline }; }
+}
+export const createCanonicalEditorRuntime = (options = {}) => new CanonicalEditorRuntime(options);

package/dist/capabilityPresets.d.ts

@@ -0,0 +1,27 @@
+import { type PluginRegistry } from "smartrte-core/foundation";
+/**
+ * A named, host-facing restriction of which built-in plugins an editor
+ * instance is constructed with - a small extension of Phase 10's existing
+ * plugin enable/disable mechanism (`createPluginRegistry`,
+ * `docs/PLUGIN_ARCHITECTURE.md`), not new architecture. `FoundationEditor`
+ * already accepted a custom `schema`/`commands`/`keyboardShortcuts`/
+ * `contextMenu` (`editor.ts`'s `FoundationEditorOptions`) since Phase 10 -
+ * nothing here builds new core capability, it just gives the react layer a
+ * convenient, named way to reach for it.
+ *
+ * This is an editor-construction-time, host/integrator-level setting - not
+ * end-user-facing toolbar customization. There is no UI for a person typing
+ * in the editor to change their own preset.
+ *
+ * Real-world driver: Sootr's question-style content (MCQ, Anomaly, PYEQ)
+ * deliberately excludes tables (`enableTable={false}` in every one of those
+ * call sites - see `docs/SOOTR_MIGRATION_READINESS.md` gap #3), while its
+ * study-material block editor wants everything. Two presets, not more,
+ * because that is the one dimension any real caller has ever needed to
+ * vary; nothing in this codebase's history has asked to disable media or
+ * formula independently of each other (they're both owned by the single
+ * "atom" plugin today, which would need splitting to support that -
+ * deliberately out of scope here, since nothing needs it yet).
+ */
+export type EditorCapabilityPreset = "simple" | "full";
+export declare const capabilityPresetRegistry: (preset: EditorCapabilityPreset) => PluginRegistry;

package/dist/capabilityPresets.js

@@ -0,0 +1,21 @@
+import { baseSchema, builtInPlugins, createPluginRegistry, foundationSchema } from "smartrte-core/foundation";
+/** Plugin ids to exclude for each preset - "full" excludes nothing, matching today's only behavior exactly (so every existing consumer who never sets `preset` is 100% unaffected). */
+const PRESET_EXCLUDED_PLUGIN_IDS = {
+    simple: ["table"],
+    full: [],
+};
+/**
+ * Registries are real work to build (schema construction + validation, per
+ * `createPluginRegistry`) - computed once per preset at module load, not
+ * per editor instance, since the preset set is small and fixed.
+ */
+const registryCache = new Map();
+export const capabilityPresetRegistry = (preset) => {
+    const cached = registryCache.get(preset);
+    if (cached)
+        return cached;
+    const excluded = new Set(PRESET_EXCLUDED_PLUGIN_IDS[preset]);
+    const registry = createPluginRegistry(builtInPlugins.filter((plugin) => !excluded.has(plugin.id)), { baseSchema, schemaVersion: foundationSchema.version });
+    registryCache.set(preset, registry);
+    return registry;
+};

package/dist/collabTransport.d.ts

@@ -0,0 +1,66 @@
+import type { SmartSelection, SmartTransaction } from "smartrte-core/foundation";
+/**
+ * A remote collaborator's live cursor/selection, mirroring
+ * `DocumentVersion`'s "reuse the existing shape, add nothing new" approach:
+ * `selection` is the same `SmartSelection` the editor already tracks
+ * locally, so it can be mapped through a rebase with the exact same
+ * `mapOperation`-based machinery the annotation-range and comment
+ * primitives already use (`FoundationTransactionMap`), not a bespoke
+ * position type needing its own mapping logic.
+ *
+ * This is a data shape only - rendering a remote cursor from this
+ * (a colored caret, a name label, etc.) is host/UI work, the same boundary
+ * `MediaProvider` draws around actual upload UI: the package defines what
+ * a presence update *is*, not how it looks on screen.
+ */
+export interface PresenceUpdate {
+    readonly authorId: string;
+    readonly selection?: SmartSelection;
+    readonly lastActiveAt: number;
+}
+/**
+ * Host-owned realtime transport boundary, mirroring `MediaProvider`'s and
+ * `VersionProvider`'s shape and contract: the host implements the actual
+ * connection (WebSocket, WebRTC, long-polling, whatever - nothing here
+ * assumes a specific transport), the package never holds a socket or
+ * server credential itself. There is deliberately no shipped default
+ * implementation, exactly like `MediaProvider`/`VersionProvider` - when a
+ * host doesn't supply one, the editor behaves exactly as it does today:
+ * single-writer, `dispatch()`'s rebase path is never triggered because
+ * `baseRevision` always matches (see `FoundationEditor.dispatch`).
+ *
+ * This interface is Phase 12b-client's contract only - no implementation
+ * of it ships from this package. The actual server/socket work
+ * (12b-server/transport) is a separate effort building *against* this
+ * contract, not part of it.
+ */
+export interface CollabTransport {
+    /**
+     * Submit a local transaction. `accepted: false` (e.g. a server-side
+     * permissions check failing) is a distinct outcome from a rebase
+     * conflict - see `revision`, present only when accepted, for the
+     * transaction's resulting revision as recorded by the transport's own
+     * source of truth.
+     */
+    sendTransaction(transaction: SmartTransaction): Promise<{
+        accepted: boolean;
+        revision?: number;
+    }>;
+    /** Fires for every transaction the transport delivers from another author, in commit order. Returns an unsubscribe function. */
+    onRemoteTransaction(handler: (transaction: SmartTransaction, revision: number) => void): () => void;
+    /** Fires whenever another author's presence changes (selection moved, went idle, etc.). Returns an unsubscribe function. */
+    onPresenceUpdate(handler: (presence: PresenceUpdate) => void): () => void;
+    /** Broadcast this client's own presence. Fire-and-forget - unlike sendTransaction, presence has no durability or ordering guarantee to report back. */
+    sendPresence(update: PresenceUpdate): void;
+    /**
+     * Transactions committed since `sinceRevision`, oldest first - what a
+     * client needs to catch up after a disconnect, or what
+     * `FoundationEditor.dispatch`'s own rebase path would ask for if this
+     * editor's local revision log had already evicted that far back (see
+     * `FoundationEditorOptions.revisionLogLimit`). An empty array means
+     * nothing has changed since; the transport signaling "that revision no
+     * longer exists" (e.g. server-side history compaction) is a
+     * transport-specific error, not modeled here.
+     */
+    getRevisionHistory(sinceRevision: number): Promise<readonly SmartTransaction[]>;
+}

package/dist/collabTransport.js

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

package/dist/commentProvider.d.ts

@@ -0,0 +1,24 @@
+import type { CommentThread } from "smartrte-core/foundation";
+/**
+ * Host-owned comment-storage boundary, mirroring `VersionProvider`/
+ * `MediaProvider`'s shape and "the editor never persists anything itself"
+ * contract. Unlike `VersionProvider`, there is no separate cheap-listing
+ * projection: a `CommentThread` (an id, a range, a handful of short replies)
+ * is already small enough that a host's `list()` can return full threads
+ * directly, with no equivalent of `VersionProvider`'s envelope/entry split
+ * needed to avoid shipping large payloads up front.
+ *
+ * `save` both creates a new thread and persists an updated one (a reply
+ * added, `resolved` toggled) - the caller always passes the complete
+ * `CommentThread` it wants stored, so there is one code path for both,
+ * exactly like `CommentReply`'s own "one path for adding a message"
+ * decision in `foundation/comments/types.ts`. There is deliberately no
+ * shipped default implementation, exactly like `VersionProvider`/
+ * `MediaProvider` - when a host doesn't supply one, the comments feature is
+ * simply unavailable.
+ */
+export interface CommentProvider {
+    list(): Promise<readonly CommentThread[]>;
+    save(thread: CommentThread): Promise<void>;
+    remove(threadId: string): Promise<void>;
+}

package/dist/commentProvider.js

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