superdoc 2.2.0 → 2.3.0

package/dist/superdoc/src/core/editor-runtime/types.d.ts

@@ -0,0 +1,405 @@
+/** A structured-clone / JSON-safe primitive. */
+export type RuntimeJsonPrimitive = string | number | boolean | null;
+/** A structured-clone / JSON-safe value. */
+export type RuntimeJsonValue = RuntimeJsonPrimitive | RuntimeJsonValue[] | {
+    [key: string]: RuntimeJsonValue;
+};
+/** A structured-clone / JSON-safe object. */
+export type RuntimeJsonObject = {
+    [key: string]: RuntimeJsonValue;
+};
+/** Which editing architecture backs a mounted runtime. */
+export type EditorRuntimeKind = 'v2';
+/** Opaque, registry-unique identifier for a mounted runtime. */
+export type EditorRuntimeId = string;
+/** Shell-owned document mode shared across editor runtimes. */
+export type EditorRuntimeDocumentMode = 'editing' | 'suggesting' | 'viewing';
+/**
+ * Shell-level lifecycle state. Mirrors the current v2 editor host state machine
+ * so the contract can describe v2 outcomes without importing v2 host types.
+ */
+export type EditorRuntimeState = 'opening' | 'blocked' | 'review-ready' | 'editing-ready' | 'saving' | 'disposed' | 'failed';
+/**
+ * An opaque, structured-clone-safe handle to a runtime-owned position or range.
+ *
+ * The shell may store a token and send it back to the runtime that created it,
+ * but must NEVER read `payload` internals, and must never construct a token to
+ * mean a document location. The runtime may wrap an `SDPosition` or another
+ * private handle; non-serializable internals stay in an
+ * adapter-private map keyed by `tokenId`.
+ *
+ * Tokens are self-validating for staleness: a runtime that cannot prove a token
+ * is current (via `revision`/epoch/map entry) must reject with
+ * `stale-position-token`, and a runtime handed a token minted by a different
+ * runtime must reject with `wrong-runtime-token`.
+ */
+export interface EditorRuntimePositionToken {
+    /** Runtime that minted this token. A different runtime must reject it. */
+    readonly runtimeId: EditorRuntimeId;
+    /** Adapter-private map key. Opaque to the shell. */
+    readonly tokenId: string;
+    /** Adapter-private staleness discriminator (revision/epoch). Opaque to the shell. */
+    readonly revision: string | number;
+    /**
+     * Optional structured-clone-safe carrier. Present so tokens survive
+     * `postMessage`/`structuredClone`. The shell must not read fields from it.
+     */
+    readonly payload?: RuntimeJsonObject;
+}
+/**
+ * Shell-level, capability-scoped command kinds. This is intentionally NOT the
+ * full editor command catalog: it is the coarse set the shared shell needs, grouped
+ * by capability. Adapters expand each kind into concrete editor operations.
+ * Detailed per-domain command signatures (comments, tracked changes, AI) are
+ * owned by later adapter plans; only the coarse routing shape lives here.
+ */
+export type EditorRuntimeCommand = {
+    kind: 'text.insert';
+    text: string;
+    at?: EditorRuntimePositionToken;
+} | {
+    kind: 'text.replace';
+    text: string;
+    range?: EditorRuntimePositionToken;
+} | {
+    kind: 'text.deleteBackward';
+} | {
+    kind: 'text.deleteForward';
+} | {
+    kind: 'text.paste';
+    text: string;
+    html?: string;
+} | {
+    kind: 'history.undo';
+} | {
+    kind: 'history.redo';
+} | {
+    kind: 'structural.splitBlock';
+} | {
+    kind: 'structural.indent';
+} | {
+    kind: 'structural.outdent';
+} | {
+    kind: 'formatting.applyMark';
+    mark: string;
+    value?: RuntimeJsonValue;
+} | {
+    kind: 'formatting.applyParagraph';
+    properties: RuntimeJsonObject;
+} | {
+    kind: 'comments.create';
+    text: string;
+    range?: EditorRuntimePositionToken;
+} | {
+    kind: 'comments.resolve';
+    commentId: string;
+} | {
+    kind: 'comments.reopen';
+    commentId: string;
+} | {
+    kind: 'comments.delete';
+    commentId: string;
+} | {
+    kind: 'comments.reply';
+    parentCommentId: string;
+    text: string;
+} | {
+    kind: 'comments.edit';
+    commentId: string;
+    text: string;
+} | {
+    kind: 'trackedChanges.accept';
+    id: string;
+} | {
+    kind: 'trackedChanges.reject';
+    id: string;
+} | {
+    kind: 'trackedChanges.acceptAll';
+} | {
+    kind: 'trackedChanges.rejectAll';
+} | {
+    kind: 'trackedChanges.setAuthoringMode';
+    mode: 'direct' | 'tracked';
+};
+/** The discriminant kind of an {@link EditorRuntimeCommand}. */
+export type EditorRuntimeCommandKind = EditorRuntimeCommand['kind'];
+/**
+ * Reason a command made no change. Kept distinct from rejection so the shell can
+ * tell "valid command, nothing to do" from "command refused".
+ */
+export type EditorRuntimeNoopReason = 'nothing-to-undo' | 'nothing-to-redo' | 'no-effect' | 'already-applied' | 'empty-selection';
+/**
+ * Neutral rejection codes. Adapters map their concrete codes onto this
+ * set; the shared contract must not import concrete runtime code unions.
+ */
+export type EditorRuntimeRejectionCode = 'runtime-not-ready' | 'host-saving' | 'capability-unsupported' | 'command-unsupported' | 'selection-unsupported' | 'target-unsupported' | 'document-readonly' | 'command-failed' | 'stale-position-token' | 'wrong-runtime-token' | 'author-required' | 'selection-invalidated' | 'review-command-unavailable';
+/**
+ * Named command outcome. Mutations are async and return this envelope; the shell
+ * must always await it. `receipt`/`result`/`failure` are opaque  -  receipt-driven
+ * cache and position invalidation stay inside the runtime/adapter. The shell
+ * must not inspect these to invalidate document state.
+ */
+export type EditorRuntimeCommandResult = {
+    status: 'committed';
+    receipt?: unknown;
+} | {
+    status: 'history-committed';
+    result?: unknown;
+} | {
+    status: 'noop';
+    reason: EditorRuntimeNoopReason;
+} | {
+    status: 'history-noop';
+    reason: EditorRuntimeNoopReason;
+    result?: unknown;
+} | {
+    status: 'receipt-failure';
+    failure?: unknown;
+} | {
+    status: 'rejected';
+    reason: EditorRuntimeRejectionCode;
+    detail?: string;
+};
+/**
+ * Neutral selection snapshot. Anchor/focus endpoints are opaque position tokens.
+ * `text` is the selected text the shell already reads synchronously today.
+ */
+export interface EditorRuntimeSelectionSnapshot {
+    /** True when anchor and focus differ (a non-collapsed range). */
+    readonly isRange: boolean;
+    /** True when the selection is empty/collapsed or absent. */
+    readonly isEmpty: boolean;
+    /** Selected text, synchronous read. Empty string when collapsed/absent. */
+    readonly text: string;
+    /** Opaque anchor endpoint, when the runtime can mint one. */
+    readonly anchor?: EditorRuntimePositionToken;
+    /** Opaque focus endpoint, when the runtime can mint one. */
+    readonly focus?: EditorRuntimePositionToken;
+}
+/**
+ * Synchronous find/search session snapshot. Backs `SuperDoc.search(...)` and
+ * `goToSearchResult(...)` shell computeds, which must not become async in
+ * current implementation.
+ */
+export interface EditorRuntimeFindSessionSnapshot {
+    /** Whether a search session is currently active. */
+    readonly active: boolean;
+    /** Current query string, or empty when no session. */
+    readonly query: string;
+    /** Total match count for the current query. */
+    readonly matchCount: number;
+    /** Active match index, or -1 when there is no active match. */
+    readonly activeMatchIndex: number;
+}
+/** Toolbar state snapshot. Shape is intentionally permissive in current implementation. */
+export interface EditorRuntimeToolbarState {
+    /** Marks/commands currently active for the selection. */
+    readonly activeMarks: readonly string[];
+    /** Marks/commands disabled in the current context. */
+    readonly disabled: readonly string[];
+    /** Optional shell-readable extra state, JSON-safe. */
+    readonly extra?: RuntimeJsonObject;
+}
+/** Page/layout metrics snapshot. */
+export interface EditorRuntimeLayoutSnapshot {
+    /** Total page count, when paginated. */
+    readonly pageCount: number;
+    /** Current page (1-based), when known. */
+    readonly currentPage: number;
+    /** Current zoom as a percent (100 = unscaled). */
+    readonly zoom: number;
+}
+/** Coarse runtime snapshot the shell can read without subscribing. */
+export interface EditorRuntimeSnapshot {
+    readonly id: EditorRuntimeId;
+    readonly kind: EditorRuntimeKind;
+    readonly documentId: string;
+    readonly state: EditorRuntimeState;
+    readonly documentMode: EditorRuntimeDocumentMode;
+    /** Stable reason string when `state` is `blocked` or `failed`. */
+    readonly reason?: string;
+    readonly capabilities: EditorRuntimeCapabilities;
+}
+export interface EditorRuntimeFocusOptions {
+    /** Restore the previous selection on focus when available. */
+    readonly restoreSelection?: boolean;
+    /** Prevent scrolling the focus target into view. */
+    readonly preventScroll?: boolean;
+}
+export interface EditorRuntimeSaveOptions {
+    /** Optional adapter-defined save hint, JSON-safe. */
+    readonly hint?: RuntimeJsonObject;
+}
+export interface EditorRuntimeExportOptions {
+    /** Optional adapter-defined export hint, JSON-safe. */
+    readonly hint?: RuntimeJsonObject;
+    /** Public comment export policy forwarded by `SuperDoc.export(...)`. */
+    readonly commentsType?: 'external' | 'clean';
+    /** Export finalization flag forwarded by `SuperDoc.export(...)`. */
+    readonly isFinalDoc?: boolean;
+    /** Optional field-highlight color forwarded by `SuperDoc.export(...)`. */
+    readonly fieldsHighlightColor?: string | null;
+}
+/**
+ * A navigation/reveal target. Positions are opaque tokens; page/comment targets
+ * are shell-level identifiers.
+ */
+export type EditorRuntimeNavigationTarget = {
+    kind: 'position';
+    position: EditorRuntimePositionToken;
+} | {
+    kind: 'page';
+    page: number;
+} | {
+    kind: 'comment';
+    commentId: string;
+} | {
+    kind: 'search-result';
+    matchIndex: number;
+};
+export interface RuntimeLifecycleCapabilities {
+    readonly canFocus: boolean;
+    readonly canDispose: boolean;
+}
+export interface RuntimeSelectionCapabilities {
+    /** Runtime can report selected text synchronously. */
+    readonly canReadSelectedText: boolean;
+    /** Runtime can report a selection snapshot synchronously. */
+    readonly canReadSelectionSnapshot: boolean;
+    /** Runtime can mint opaque position tokens for the current selection. */
+    readonly canMintPositionTokens: boolean;
+}
+export interface RuntimeCommandCapabilities {
+    /** Whether dispatch is accepted at all in the current state. */
+    readonly canDispatch: boolean;
+    /** Command kinds the runtime currently supports. */
+    readonly supportedCommands: readonly EditorRuntimeCommandKind[];
+}
+export interface RuntimeFindReplaceCapabilities {
+    readonly supported: boolean;
+    /** Runtime exposes a synchronous find-session snapshot. */
+    readonly hasSyncSessionSnapshot: boolean;
+    readonly canReplace: boolean;
+}
+export interface RuntimeAiCapabilities {
+    readonly supported: boolean;
+}
+export interface RuntimeCommentCapabilities {
+    readonly supported: boolean;
+    /** Whether comment mutation is currently allowed (e.g. author present). */
+    readonly canMutate: boolean;
+}
+export interface RuntimeTrackedChangeCapabilities {
+    readonly supported: boolean;
+    readonly canDecide: boolean;
+    readonly canToggleAuthoring: boolean;
+}
+export interface RuntimeToolbarCapabilities {
+    readonly supported: boolean;
+    /** Runtime emits `toolbar-state-change` events. */
+    readonly emitsStateChange: boolean;
+}
+export interface RuntimeLayoutCapabilities {
+    readonly supported: boolean;
+    /** Runtime exposes a synchronous layout snapshot. */
+    readonly hasSyncSnapshot: boolean;
+}
+export interface RuntimeZoomCapabilities {
+    readonly supported: boolean;
+    readonly min: number;
+    readonly max: number;
+}
+export interface RuntimeNavigationCapabilities {
+    readonly supported: boolean;
+    /** Navigation target kinds the runtime can reveal. */
+    readonly targets: readonly EditorRuntimeNavigationTarget['kind'][];
+}
+export interface RuntimePersistenceCapabilities {
+    readonly canSave: boolean;
+    readonly canExportDocx: boolean;
+}
+/**
+ * Grouped capability descriptor. Required groups (lifecycle, selection,
+ * commands, layout, zoom, navigation, persistence) are always present; optional
+ * domain groups are present only when the runtime offers them.
+ */
+export interface EditorRuntimeCapabilities {
+    readonly lifecycle: RuntimeLifecycleCapabilities;
+    readonly selection: RuntimeSelectionCapabilities;
+    readonly commands: RuntimeCommandCapabilities;
+    readonly layout: RuntimeLayoutCapabilities;
+    readonly zoom: RuntimeZoomCapabilities;
+    readonly navigation: RuntimeNavigationCapabilities;
+    readonly persistence: RuntimePersistenceCapabilities;
+    readonly findReplace?: RuntimeFindReplaceCapabilities;
+    readonly ai?: RuntimeAiCapabilities;
+    readonly comments?: RuntimeCommentCapabilities;
+    readonly trackedChanges?: RuntimeTrackedChangeCapabilities;
+    readonly toolbar?: RuntimeToolbarCapabilities;
+}
+/**
+ * Runtime-owned events. The registry (the editor runtime boundary) owns active-runtime changes;
+ * the runtime owns editor-specific state. Events carry shell-level snapshots,
+ * not raw ProseMirror or v2 session objects.
+ */
+export type EditorRuntimeEvent = {
+    type: 'selection-change';
+    selection: EditorRuntimeSelectionSnapshot;
+} | {
+    type: 'capabilities-change';
+    capabilities: EditorRuntimeCapabilities;
+} | {
+    type: 'toolbar-state-change';
+    state: EditorRuntimeToolbarState;
+} | {
+    type: 'layout-change';
+    layout: EditorRuntimeLayoutSnapshot;
+} | {
+    type: 'state-change';
+    state: EditorRuntimeState;
+} | {
+    type: 'disposed';
+};
+export type EditorRuntimeListener = (event: EditorRuntimeEvent) => void;
+export type EditorRuntimeUnsubscribe = () => void;
+/**
+ * The shell-owned editor runtime contract. Implementable by the current
+ * internal v2 host/facade without importing v2 host types into this
+ * shared module.
+ *
+ * Mutating operations return Promises (callers always await). Runtime-owned
+ * snapshot reads (`getSelectedText`, `getSelectionSnapshot`,
+ * `getFindSessionSnapshot`, `getToolbarState`, `getLayoutSnapshot`) are
+ * synchronous so they can back existing synchronous shell APIs and Vue
+ * computeds without forcing them async in current implementation.
+ */
+export interface EditorRuntime {
+    readonly id: EditorRuntimeId;
+    readonly kind: EditorRuntimeKind;
+    readonly documentId: string;
+    /** The mounted root element, used for event-target → runtime resolution. */
+    readonly root: HTMLElement;
+    getCapabilities(): EditorRuntimeCapabilities;
+    getSnapshot(): EditorRuntimeSnapshot;
+    setDocumentMode(mode: EditorRuntimeDocumentMode): void;
+    getDocumentMode(): EditorRuntimeDocumentMode;
+    /**
+     * Temporary compatibility path backing `SuperDoc.activeEditor`,
+     * `doc.getEditor()`, and existing public-ish callers. The v2 runtime returns
+     * its facade. New shell behavior must not route through this projection.
+     */
+    getLegacyEditorProjection?(): unknown;
+    focus(options?: EditorRuntimeFocusOptions): Promise<boolean>;
+    dispose(): void | Promise<void>;
+    dispatch(command: EditorRuntimeCommand): Promise<EditorRuntimeCommandResult>;
+    getSelectedText(): string;
+    getSelectionSnapshot(): EditorRuntimeSelectionSnapshot | null;
+    getFindSessionSnapshot?(): EditorRuntimeFindSessionSnapshot | null;
+    getToolbarState?(): EditorRuntimeToolbarState | null;
+    getLayoutSnapshot(): EditorRuntimeLayoutSnapshot | null;
+    save(options?: EditorRuntimeSaveOptions): Promise<ArrayBuffer>;
+    exportDocx(options?: EditorRuntimeExportOptions): Promise<ArrayBuffer>;
+    setZoom(percent: number): Promise<EditorRuntimeCommandResult>;
+    reveal(target: EditorRuntimeNavigationTarget): Promise<EditorRuntimeCommandResult>;
+    subscribe(listener: EditorRuntimeListener): EditorRuntimeUnsubscribe;
+}

package/dist/superdoc/src/core/editor-runtime/v2/v2-editor-runtime-adapter.d.ts

@@ -0,0 +1,185 @@
+import { EditorRuntime, EditorRuntimeDocumentMode, EditorRuntimeId, EditorRuntimeState } from '../index.js';
+type HostLifecycleState = EditorRuntimeState | 'ready';
+type HostCommandKind = 'text.insert' | 'text.replace' | 'text.deleteBackward' | 'text.deleteForward' | 'text.pastePlain' | 'history.undo' | 'history.redo' | 'structural.enter' | 'structural.listIndent' | 'structural.listOutdent' | string;
+interface HostCommandSupportRecordLike {
+    readonly command: HostCommandKind | string;
+    readonly status: 'supported' | 'unsupported';
+    readonly rejectionCode?: string | null;
+    readonly reason?: string | null;
+    readonly detail?: string | null;
+    readonly enabled?: boolean;
+}
+interface HostSelectionStateLike {
+    readonly anchor: unknown;
+    readonly focus: unknown;
+}
+interface HostSelectionControllerLike {
+    getSnapshot(): HostSelectionStateLike | null;
+    subscribe(listener: (snapshot: HostSelectionStateLike | null) => void): () => void;
+}
+interface HostHandlesLike {
+    readonly editing: {
+        readonly selection: HostSelectionControllerLike;
+    } | null;
+}
+interface HostEditableSubsetSnapshotLike {
+    readonly editingMounted: boolean;
+    readonly commands: readonly HostCommandSupportRecordLike[];
+}
+interface HostSnapshotLike {
+    readonly state: HostLifecycleState;
+    readonly documentMode: EditorRuntimeDocumentMode;
+    readonly reason?: string;
+    readonly detail?: string;
+    readonly commentCommandsReason?: 'author-required' | null;
+    readonly editableSubset: HostEditableSubsetSnapshotLike;
+}
+interface HostDispatchRejectionLike {
+    readonly code: string;
+    readonly detail?: string;
+}
+type HostDispatchResultLike = {
+    readonly status: 'committed';
+    readonly receipt?: unknown;
+} | {
+    readonly status: 'history-committed';
+    readonly result?: unknown;
+} | {
+    readonly status: 'history-noop';
+    readonly result?: {
+        readonly reason?: string;
+    };
+} | {
+    readonly status: 'receipt-failure';
+    readonly failure?: unknown;
+} | {
+    readonly status: 'rejected';
+    readonly rejection: HostDispatchRejectionLike;
+};
+type MaybePromise<T> = T | Promise<T>;
+type HostCommandLike = {
+    readonly kind: 'text.insert';
+    readonly text: string;
+} | {
+    readonly kind: 'text.replace';
+    readonly text: string;
+} | {
+    readonly kind: 'text.deleteBackward';
+} | {
+    readonly kind: 'text.deleteForward';
+} | {
+    readonly kind: 'text.pastePlain';
+    readonly text: string;
+} | {
+    readonly kind: 'history.undo';
+} | {
+    readonly kind: 'history.redo';
+} | {
+    readonly kind: 'structural.enter';
+} | {
+    readonly kind: 'structural.listIndent';
+} | {
+    readonly kind: 'structural.listOutdent';
+};
+interface DocumentFacadeReceiptLike {
+    readonly success?: boolean;
+    readonly failure?: unknown;
+}
+interface DocumentFacadeHistoryResultLike {
+    readonly noop?: boolean;
+    readonly reason?: string;
+}
+interface DocumentFacadeSelectionInfoLike {
+    readonly empty?: boolean;
+    readonly target?: unknown;
+}
+interface DocumentFacadeLike {
+    readonly comments?: {
+        create?(input: {
+            text: string;
+            target?: unknown;
+            parentCommentId?: string;
+        }): MaybePromise<DocumentFacadeReceiptLike>;
+        patch?(input: {
+            commentId: string;
+            text?: string;
+            status?: 'resolved' | 'active';
+        }): MaybePromise<DocumentFacadeReceiptLike>;
+        delete?(input: {
+            commentId: string;
+        }): MaybePromise<DocumentFacadeReceiptLike>;
+    };
+    readonly trackChanges?: {
+        decide?(input: {
+            decision: 'accept' | 'reject';
+            target: {
+                kind: 'id';
+                id: string;
+            } | {
+                kind: 'all';
+            };
+        }): MaybePromise<DocumentFacadeReceiptLike>;
+    };
+    readonly history?: {
+        undo?(): MaybePromise<DocumentFacadeHistoryResultLike>;
+        redo?(): MaybePromise<DocumentFacadeHistoryResultLike>;
+    };
+    readonly selection?: {
+        current?(input?: {
+            includeText?: boolean;
+        }): MaybePromise<DocumentFacadeSelectionInfoLike>;
+    };
+}
+type DocumentFacadeResultLike = {
+    readonly available: true;
+    readonly doc: DocumentFacadeLike;
+} | {
+    readonly available: false;
+    readonly reason?: string;
+};
+interface HostPageMetricsSnapshotLike {
+    readonly pages: readonly unknown[];
+    readonly zoom: {
+        readonly percent: number;
+    };
+}
+interface HostSetZoomResultLike {
+    readonly status: 'ok' | 'rejected';
+    readonly reason?: string;
+}
+interface HostFocusHandleLike {
+    focus?(options?: unknown): boolean | void | Promise<boolean | void>;
+}
+interface HostMountHandleLike {
+    readonly focus: HostFocusHandleLike | null;
+}
+interface ModeAwareHostLike {
+    getSnapshot(): HostSnapshotLike;
+    subscribe(listener: (snapshot: HostSnapshotLike) => void): () => void;
+    getDocumentMode(): EditorRuntimeDocumentMode;
+    setDocumentMode(mode: EditorRuntimeDocumentMode): void;
+    dispatch(command: HostCommandLike): Promise<HostDispatchResultLike>;
+    save(options?: {
+        format?: 'docx';
+        commentExportMode?: 'preserve' | 'strip';
+    }): Promise<ArrayBuffer>;
+    dispose(): Promise<void>;
+    getHandles(): HostHandlesLike;
+    getDocumentFacade?(): DocumentFacadeResultLike;
+    getPageMetricsSnapshot(): HostPageMetricsSnapshotLike;
+    subscribePageMetrics?(listener: (snapshot: HostPageMetricsSnapshotLike) => void): () => void;
+    setZoom(percent: number): HostSetZoomResultLike;
+}
+export interface V2EditorRuntimeAdapterOptions {
+    readonly id: EditorRuntimeId;
+    readonly documentId: string;
+    readonly root: HTMLElement;
+    readonly host: ModeAwareHostLike;
+    readonly getLegacyEditorProjection?: () => unknown;
+    readonly onUnregister?: (id: EditorRuntimeId) => void;
+}
+export declare function createV2EditorRuntimeAdapter(options: V2EditorRuntimeAdapterOptions): {
+    runtime: EditorRuntime;
+    attachMountHandle(handle: HostMountHandleLike | null): void;
+};
+export {};

package/dist/superdoc/src/core/editor-runtime/v2/v2-session-shortcut-routes.d.ts

@@ -0,0 +1,47 @@
+/**
+ * The narrow slice of the public Document API facade (`activeEditor.doc`) the
+ * reference shortcuts route through. Every method is optional so capability is
+ * detected per facade rather than assumed.
+ */
+interface ReferenceDocumentApi {
+    selection?: {
+        current?: (input?: unknown) => unknown;
+    };
+    toc?: {
+        list?: () => unknown;
+        update?: (input: unknown) => unknown;
+    };
+    fields?: {
+        list?: () => unknown;
+        rebuild?: (input: unknown) => unknown;
+        insert?: (input: unknown) => unknown;
+    };
+    index?: {
+        list?: () => unknown;
+        rebuild?: (input: unknown) => unknown;
+    };
+}
+interface SessionShortcutRouteResult {
+    handled: boolean;
+    reason?: string;
+}
+type RouteReturn = SessionShortcutRouteResult | boolean;
+interface SessionShortcutRoutes {
+    focusToolbar?: () => RouteReturn;
+    focusHeaderFooter?: (region: 'header' | 'footer') => RouteReturn;
+    exitSession?: () => RouteReturn;
+    updateFields?: () => RouteReturn;
+    insertPageField?: (kind: 'page' | 'numpages') => RouteReturn;
+}
+export interface CreateV2SessionShortcutRoutesDeps {
+    /** Resolve the live toolbar container element for this SuperDoc instance. */
+    resolveToolbarElement: () => HTMLElement | null | undefined;
+    /** Resolve the live public Document API facade, or null when unavailable. */
+    getDocumentApi: () => ReferenceDocumentApi | null | undefined;
+}
+/**
+ * Build the durable session/reference shortcut routes. Returned routes match the
+ * `SessionShortcutRoutes` shape consumed by `bindV2SessionShortcuts`.
+ */
+export declare function createV2SessionShortcutRoutes(deps: CreateV2SessionShortcutRoutesDeps): SessionShortcutRoutes;
+export {};

package/dist/superdoc/src/core/extensions/define.d.ts

@@ -0,0 +1,56 @@
+import { SuperDocExtension } from './types.js';
+/**
+ * Define a v2 SuperDoc extension.
+ *
+ * A narrow identity + validation helper: it asserts the two load-bearing
+ * fields exist and returns the extension object unchanged (so the authored
+ * object literal keeps its inferred storage type). Pass the result to
+ * `new SuperDoc({ selector, document, extensions: [AcmeHighlights] })`.
+ *
+ * `superdoc@2` IS the v2 editor — there is no `editorVersion` /
+ * `editorIntegration` selection. V2 extensions are not v1 ProseMirror
+ * extensions; the legacy `editorExtensions` config key is a v1/ProseMirror
+ * concept and is ignored in `superdoc@2`.
+ *
+ * @example
+ * ```ts
+ * import { SuperDoc, defineSuperDocExtension } from 'superdoc';
+ *
+ * const AcmeHighlights = defineSuperDocExtension({
+ *   id: 'acme.highlights',
+ *   storage: () => ({ searchText: 'ACME' }),
+ *   activate(ctx) {
+ *     const highlights = ctx.anchors.collection('acme.highlights');
+ *     ctx.commands.register({
+ *       id: 'acme.refreshHighlights',
+ *       label: 'Refresh highlights',
+ *       execute: async () => {
+ *         const result = await ctx.doc.query.match({
+ *           select: { type: 'text', pattern: ctx.storage.searchText },
+ *         });
+ *         highlights.replace(result.items.map((item) => ctx.anchors.from(item.target)));
+ *         ctx.decorations.invalidate('acme.highlights');
+ *       },
+ *     });
+ *     ctx.onMutation({ affects: ['text'] }, () => ctx.decorations.invalidate('acme.highlights'));
+ *     ctx.decorations.register({
+ *       id: 'acme.highlights',
+ *       provide: ({ visible }) =>
+ *         highlights.visibleIn(visible).map((anchor) => ({
+ *           type: 'text',
+ *           anchor,
+ *           className: 'acme-highlight',
+ *           data: { source: 'acme' },
+ *         })),
+ *     });
+ *   },
+ * });
+ *
+ * new SuperDoc({
+ *   selector: '#editor',
+ *   document,
+ *   extensions: [AcmeHighlights],
+ * });
+ * ```
+ */
+export declare function defineSuperDocExtension<TStorage extends Record<string, unknown> = Record<string, unknown>>(extension: SuperDocExtension<TStorage>): SuperDocExtension<TStorage>;