smartrte-react 0.3.5 → 1.0.0-beta.2

package/dist/canonicalEditorRuntime.d.ts

@@ -1,4 +1,5 @@
-import { type CanonicalInputPipeline, type ClipboardDiagnosticReport, type CanonicalSubtreeRenderer, type FoundationEditor, type PersistedEditorDocument, type SmartMark, type SmartOperation, type SmartSelection, type SmartTransaction } from "smartrte-core/foundation";
+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;
@@ -22,6 +23,14 @@ export interface SmartEditorHandle {
     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;
@@ -37,6 +46,17 @@ export interface CanonicalEditorRuntimeOptions {
     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 {
@@ -49,6 +69,7 @@ export declare class CanonicalEditorRuntime implements SmartEditorHandle {
     private onChange?;
     private onHtmlChange?;
     private readonly onClipboardDiagnostic?;
+    private readonly contentVisibility;
     private htmlChangeTimer;
     private pendingHtmlDocument;
     constructor(options?: CanonicalEditorRuntimeOptions);
@@ -67,6 +88,37 @@ export declare class CanonicalEditorRuntime implements SmartEditorHandle {
     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;

package/dist/canonicalEditorRuntime.js

@@ -1,4 +1,5 @@
-import { createFoundationEditor, applyOperations, createInputPipeline, createSubtreeRenderer, createTransactionMap, foundationSchema, isTextNode, parseCanonicalListHtml, serializeCanonicalListHtml, } from "smartrte-core/foundation";
+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) {
@@ -29,7 +30,11 @@ const firstTextSelection = (document) => {
             return null;
         const spec = foundationSchema.nodes[node.type];
         const children = node.children || [];
-        if (spec?.group === "block" && (children.length === 0 || children.every((child) => isTextNode(child) || foundationSchema.nodes[child.type]?.group === "inline")))
+        // 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]);
@@ -78,15 +83,22 @@ export class CanonicalEditorRuntime {
         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;
@@ -124,7 +136,7 @@ export class CanonicalEditorRuntime {
             return;
         this.unmount();
         this.root = root;
-        this.renderer = createSubtreeRenderer(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);
@@ -251,7 +263,14 @@ export class CanonicalEditorRuntime {
             addToHistory: opts.addToHistory ?? true,
             ...(opts.historyGroup ? { historyGroup: opts.historyGroup } : {}),
         });
-        this.focus();
+        // 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 {
@@ -268,6 +287,44 @@ export class CanonicalEditorRuntime {
         });
         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 }; }
 }

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 {};

package/dist/components/CanonicalAuthorityEditor.d.ts

@@ -1,19 +1,53 @@
 import React from "react";
 import { type PersistedEditorDocument, type ClipboardDiagnosticReport } from "smartrte-core/foundation";
 import type { MediaProvider } from "../mediaProvider.js";
+import type { VersionProvider } from "../versionProvider.js";
+import type { CommentProvider } from "../commentProvider.js";
+import type { SuggestionProvider } from "../suggestionProvider.js";
 import { type MediaPickerComponent } from "./MediaPicker.js";
+import type { EditorCapabilityPreset } from "../capabilityPresets.js";
 import { CanonicalEditorRuntime, type SmartEditorChange, type SmartEditorHandle } from "../canonicalEditorRuntime.js";
 export interface CanonicalAuthorityEditorProps {
     /** Initial value only. Later replacements must use SmartEditorHandle.replaceValue. */
     defaultValue?: string | PersistedEditorDocument;
+    /**
+     * Which built-in plugins this instance is constructed with - see
+     * capabilityPresets.ts. Construction-time only, matching `defaultValue`'s
+     * own uncontrolled-after-mount contract (the underlying runtime is
+     * created once and retained; changing this prop on an already-mounted
+     * instance has no effect). Defaults to "full" - every existing consumer
+     * that never sets this is unaffected.
+     */
+    preset?: EditorCapabilityPreset;
     onChange?: (change: SmartEditorChange) => void;
     /** Transitional serialization callback for hosts that still persist HTML. */
     onHtmlChange?: (html: string) => void;
     onClipboardDiagnostic?: (report: ClipboardDiagnosticReport) => void;
     /** Host-owned upload/search/remove boundary for canonical media insertion. */
     mediaProvider?: MediaProvider;
-    /** Replaceable picker; the default only selects a local file. */
+    /** Replaceable picker; the default only selects a local file. Used for video/audio, and for images when mediaManager is false. */
     mediaPicker?: MediaPickerComponent;
+    /**
+     * Phase 11.5 §2.1: a library/search/duplicate-detection picker for
+     * images, replacing the bare file-input default. Defaults to true
+     * (MediaManager, adapted via mediaManagerAdapterFrom) whenever
+     * mediaProvider is supplied; set to false to keep the simple mediaPicker
+     * for images too.
+     */
+    mediaManager?: boolean;
+    /** Host-owned save/list/load/remove boundary for document version history. Absent hides the version-history toolbar button entirely, mirroring mediaProvider's absent-disables-the-feature contract. */
+    versionProvider?: VersionProvider;
+    /** Host-owned save/list/remove boundary for comment threads. Absent hides the comment toolbar buttons and markers entirely, mirroring versionProvider's absent-disables-the-feature contract. */
+    commentProvider?: CommentProvider;
+    /**
+     * Host-owned save/list/remove boundary for *structural* suggestions only
+     * (see suggestionProvider.ts) - inline suggestions need no provider since
+     * they are marks embedded in the document itself. Absent hides the
+     * suggestion toolbar buttons, markers, and panel entirely.
+     */
+    suggestionProvider?: SuggestionProvider;
+    /** Attributed to new comment replies and suggestions. Defaults to "anonymous" when absent. */
+    authorId?: string;
     placeholder?: string;
     minHeight?: number | string;
     maxHeight?: number | string;