superdoc 2.2.0 → 2.3.0

package/dist/superdoc/src/core/SuperDoc.d.ts

@@ -0,0 +1,775 @@
+import { EventEmitter } from 'eventemitter3';
+import { HocuspocusProviderWebsocket } from '@hocuspocus/provider';
+import { createSuperdocVueApp } from './create-app.js';
+import { Whiteboard } from './whiteboard/Whiteboard.js';
+import { normalizeUiConfig } from './config/normalize-ui-config.js';
+import { normalizeInteractionConfig } from './config/normalize-interaction-config.js';
+import { normalizeSurfacesConfig } from './config/normalize-surfaces-config.js';
+import { EditorRuntimeFocusOptions } from './editor-runtime/types.js';
+import { BorrowedSuperDocUI } from '../public/ui/types.js';
+import { AwarenessUser, CanPerformPermissionParams, CollaborationProvider, Config, ContentControlActiveChangePayload, ContentControlClickPayload, DocumentMode, Editor, EditorUpdateEvent, ExportParams, FontsChangedPayload, FontsResolvedPayload, InternalConfig, ListDefinitionsPayload, NavigableAddress, DocumentRendererRuntime, SearchMatch, SuperDocAwarenessUpdatePayload, SuperDocCommentsUpdatePayload, SuperDocDocumentReplacedPayload, SuperDocEditorPayload, SuperDocExceptionPayload, SuperDocFontsApi, SuperDocLockedPayload, SuperDocMeasurementUnit, SuperDocMeasurementUnitChangePayload, SuperDocReadyPayload, SuperDocState, SuperDocViewportChangePayload, SuperDocViewportMetrics, SuperDocZoomMode, SuperDocZoomPayload, SuperDocZoomState, SurfaceHandle, SurfaceRequest, UpgradeToCollaborationOptions, User } from './types/index.js';
+import { WhiteboardData } from './whiteboard/Whiteboard.js';
+type ToolbarLike = {
+    activeEditor?: unknown;
+    setActiveEditor?: (editor: unknown) => void;
+    getToolbarItemByName?: (name: string) => unknown;
+    getToolbarItemByGroup?: (group: string) => unknown;
+    updateToolbarState?: () => void;
+    on?: (event: string, handler: (payload?: unknown) => void) => void;
+    off?: (event: string, handler: (payload?: unknown) => void) => void;
+    destroy: () => void;
+};
+import type * as Y from 'yjs';
+interface SuperDocWhiteboardPayload {
+    whiteboard: Whiteboard;
+}
+interface SuperDocFormattingMarksPayload {
+    showFormattingMarks: boolean;
+    superdoc: SuperDoc;
+}
+interface SuperDocDocumentModeChangePayload {
+    documentMode: DocumentMode;
+}
+interface SuperDocPaginationPayload {
+    totalPages: number;
+    superdoc: SuperDoc;
+}
+interface SuperDocContentErrorPayload {
+    error: unknown;
+    editor: Editor;
+}
+/**
+ * SuperDoc lifecycle event registry. Keys are event names emitted via
+ * `this.emit(...)`; each value is the tuple of arguments. Used as the
+ * generic parameter of `EventEmitter<SuperDocEventMap>` so `superdoc.on`
+ * / `superdoc.emit` reject unknown event names at compile time.
+ */
+interface SuperDocEventMap {
+    ready: [SuperDocReadyPayload];
+    editorBeforeCreate: [SuperDocEditorPayload];
+    editorCreate: [SuperDocEditorPayload];
+    editorDestroy: [];
+    'pdf:document-ready': [];
+    'sidebar-toggle': [boolean];
+    /** Requests the shell open its find/replace surface (e.g. the toolbar search button). */
+    'search:open': [];
+    zoomChange: [SuperDocZoomPayload];
+    'measurement-unit-change': [SuperDocMeasurementUnitChangePayload];
+    'formatting-marks-change': [SuperDocFormattingMarksPayload];
+    'document-mode-change': [SuperDocDocumentModeChangePayload];
+    /**
+     * The active editor was assigned or cleared. Internal: the UI controller
+     * listens so its snapshot follows the live editor. `editorCreate` only
+     * covers assignment, and it is emitted after `broadcastReady()`, so
+     * neither a pre-ready read nor a clear would refresh without this.
+     */
+    'active-editor-change': [];
+    /**
+     * `replaceFile()` swapped the content under a stable editor identity.
+     *
+     * Deliberately distinct from `active-editor-change`: the editor object and its
+     * host both survive a replace, so anything bound to the HOST — geometry
+     * observers, for one — is still attached to the thing now rendering the
+     * replacement and must not be torn down. Only state describing the previous
+     * document's content is stale.
+     *
+     * Emitted only after the replacement is confirmed, and carrying the editor
+     * whose replacement completed: a replace is asynchronous, so the active editor
+     * can move while it is in flight, and a consumer must ignore an event naming an
+     * editor it is not bound to.
+     */
+    'document-replaced': [SuperDocDocumentReplacedPayload];
+    'editor-update': [EditorUpdateEvent];
+    'content-error': [SuperDocContentErrorPayload];
+    'fonts-resolved': [FontsResolvedPayload];
+    'fonts-changed': [FontsChangedPayload];
+    'pagination-update': [SuperDocPaginationPayload];
+    'list-definitions-change': [ListDefinitionsPayload];
+    'comments-update': [SuperDocCommentsUpdatePayload];
+    'content-control:active-change': [ContentControlActiveChangePayload];
+    'content-control:click': [ContentControlClickPayload];
+    'collaboration-ready': [SuperDocEditorPayload];
+    'awareness-update': [SuperDocAwarenessUpdatePayload];
+    locked: [SuperDocLockedPayload];
+    'whiteboard:init': [SuperDocWhiteboardPayload];
+    'whiteboard:ready': [SuperDocWhiteboardPayload];
+    'whiteboard:change': [WhiteboardData];
+    'whiteboard:enabled': [boolean];
+    'whiteboard:tool': [string];
+    exception: [SuperDocExceptionPayload];
+    'viewport-change': [SuperDocViewportChangePayload];
+    'source:complete': [];
+    'source:signals-complete': [];
+}
+/**
+ * SuperDoc class
+ * Expects a config object
+ *
+ * @class
+ */
+export declare class SuperDoc extends EventEmitter<SuperDocEventMap> {
+    #private;
+    static allowedTypes: ("application/vnd.openxmlformats-officedocument.wordprocessingml.document" | "application/pdf" | "text/html")[];
+    /**
+     * Which built-in surfaces this instance renders.
+     *
+     * Resolved from {@link Config.ui}, falling back to the historical defaults
+     * when it is omitted. Read-only: changing what SuperDoc renders after mount
+     * is a per-surface concern, not a config swap.
+     */
+    get uiConfig(): ReturnType<typeof normalizeUiConfig>;
+    /**
+     * What the user is permitted to do, as distinct from what SuperDoc draws.
+     *
+     * Resolved from {@link Config.interaction}. Stays meaningful when the
+     * application renders its own UI: `ui: false` removes the built-in comment
+     * dialog but not the policy that rejects a mutation.
+     */
+    get interactionConfig(): ReturnType<typeof normalizeInteractionConfig>;
+    /**
+     * Shared plumbing for dialogs and floating overlays, including ones the
+     * application opens itself through `openSurface()`.
+     *
+     * Resolved from {@link Config.surfaces}. Unaffected by `ui: false`, which
+     * turns off SuperDoc's own surfaces without disabling the mechanism.
+     */
+    get surfacesConfig(): ReturnType<typeof normalizeSurfacesConfig>;
+    /**
+     * Build-time SuperDoc version string. Initialized to `'0.0.0'` so the
+     * field is structurally assigned before the constructor runs, then
+     * overwritten with the injected `__APP_VERSION__` constant inside
+     * `#init` (the existing `@ts-expect-error` keeps the injected global
+     * out of the JSDoc type graph). Consumers reading `superdoc.version`
+     * immediately after `new SuperDoc(...)` see the real version because
+     * `#init` runs synchronously through the overwrite before returning.
+     */
+    version: string;
+    /**
+     * Local copy of the shared users list. Initialized to `[]` so direct
+     * reads (`superdoc.users`) are stable before the async `#init`
+     * re-seeds from `config.users`. Pre-ready `addSharedUser` /
+     * `removeSharedUser` mutations would be silently overwritten by the
+     * re-seed, so those methods guard with `#requireReady('addSharedUser')`
+     * and throw a clear lifecycle error instead.
+     */
+    users: User[];
+    /** Yjs document for collaboration; set in `#init` when collaboration is enabled, otherwise undefined. */
+    ydoc: Y.Doc | undefined;
+    /**
+     * Provider for the SuperDoc-level collaboration room (separate from
+     * per-document providers). Widened to `CollaborationProvider` to match
+     * the runtime, which stores whatever provider the consumer passed via
+     * `Config.modules.collaboration.provider`. Consumers needing Hocuspocus-
+     * specific members must narrow before use.
+     *
+     */
+    provider: CollaborationProvider | undefined;
+    /**
+     * Whiteboard instance, created by `#initWhiteboard()` after the
+     * collaboration await. Initialized to `null` so consumers reading
+     * `superdoc.whiteboard` before the `whiteboard:init` event fires get
+     * a stable null, not `undefined`.
+     */
+    whiteboard: Whiteboard | null;
+    /**
+     * Awareness palette assigned to local users when no explicit color is set.
+     * Defaults to an empty array so `#assignUserColor` falls back to the
+     * built-in `DEFAULT_AWARENESS_PALETTE`.
+     */
+    colors: string[];
+    /**
+     * Pinia stores and Vue runtime references. Populated by `#initVueApp`
+     * inside the async `#init`, which runs *after* `await #initCollaboration`,
+     * so these fields are `undefined` between `new SuperDoc(config)`
+     * returning and the `ready` event firing. Typed as `T | undefined` so
+     * @ts-check forces every access path to either narrow or use the
+     * `#requireSuperdocStore` / `#requireCommentsStore` helpers below
+     * (which throw a clear "wait for ready" error). SD-2916 PR-B closed
+     * the delayed-init soundness gap.
+     *
+     * `@private` is a TypeScript-surface hide, not runtime privacy: the
+     * fields still exist on the runtime instance and internal callers
+     * across the package keep working. Consumers can no longer reach into
+     * them via `.d.ts`, which collapses the Pinia type graph from the
+     * public surface (SD-3213f). The headless-toolbar host contract was
+     * refactored in the same PR to replace raw store reach with narrow
+     * host methods, so SuperDoc instances satisfy
+     * `HeadlessToolbarSuperdocHost` directly without exposing
+     * `superdocStore` publicly.
+     *
+     * @private
+     */
+    private superdocStore;
+    /**
+     * @private
+     */
+    private commentsStore;
+    /**
+     * @private
+     */
+    private highContrastModeStore;
+    /**
+     * Internal mount handle for the `SuperComments` Vue component, created
+     * lazily by `addCommentsList()` and torn down by `removeCommentsList()`.
+     * Not consumer API: `SuperComments` is not publicly exported, no docs
+     * or examples reference `superdoc.commentsList`, and the inner fields
+     * (`element`, `superdoc` backref, `container` Vue ComponentPublicInstance)
+     * are internal mount state.
+     *
+     * Typed as `SuperComments | null | undefined` so the runtime states
+     * stay type-clean: `undefined` before `addCommentsList()` runs (e.g.
+     * when the viewer role skips initialization; see SuperDoc.test.js
+     * for the assertion), `SuperComments` after `addCommentsList()`, and
+     * `null` after `removeCommentsList()` tears down. No initializer, to
+     * match the convention used by the adjacent `@private` store fields.
+     *
+     * @private
+     */
+    private commentsList;
+    /**
+     * Internal Vue app handle created in `#initVueApp()` and used for
+     * mount/unmount, `provide()`, and `config.globalProperties` setup.
+     * Not consumer API: no docs or examples reference `superdoc.app`,
+     * and the only cross-file reader (`SuperComments.createVueApp()`
+     * at `super-comments-list.js:35`) is a `.js` file under
+     * `checkJs: false`, so the `@private` boundary does not break
+     * internal source compilation.
+     *
+     * Same SD-3213f-style TS surface hide as
+     * `superdocStore` / `commentsStore` / `highContrastModeStore` /
+     * `commentsList`; not runtime privacy.
+     *
+     * @private
+     */
+    private app;
+    /** Pinia store root for the SuperDoc Vue app. Set in `#initVueApp`. */
+    pinia: ReturnType<typeof createSuperdocVueApp>['pinia'] | undefined;
+    /** Count of editors that have signaled `editorCreate`. */
+    readyEditors: number;
+    /** Outstanding async saves waiting for collaboration ack. */
+    pendingCollaborationSaves: number;
+    activeEditor: Editor | null;
+    editorVersion: 2;
+    toolbar: ToolbarLike | null;
+    toolbarElement: string | HTMLElement | undefined;
+    userColorMap: Map<string, string>;
+    colorIndex: number;
+    isCollaborative: boolean;
+    isLocked: boolean;
+    lockedBy: User | null;
+    isDev: boolean;
+    superdocId: string;
+    comments: unknown[];
+    socket: HocuspocusProviderWebsocket | null;
+    user: AwarenessUser;
+    _cleanupAwareness: (() => void) | null;
+    _commentsCollabInitialized: boolean;
+    /**
+     * The active configuration. Typed as `InternalConfig` because `#init` runs
+     * synchronously in the constructor and normalizes the consumer-provided
+     * `Config` into the wider shape (`documents` filled, `modules` defaulted,
+     * `user` spread with `DEFAULT_USER`, etc.). Any callsite reading
+     * `this.config` runs after `#init`, so it sees the normalized shape.
+     *
+     * Public consumer input shape: `Config` (re-exported from `superdoc`).
+     * Internal post-normalize shape: `InternalConfig`.
+     */
+    config: InternalConfig;
+    constructor(config: Config);
+    /**
+     * Get the number of editors that are required for this superdoc
+     * @returns The number of required editors
+     */
+    get requiredNumberOfEditors(): number;
+    /**
+     * The UI controller for this instance: the single place to read command
+     * state and drive comments, track changes, selection, zoom, and the other
+     * UI surfaces from application code.
+     *
+     * SuperDoc owns exactly one controller per instance. Every internal
+     * consumer — the built-in toolbar, the link popover, keyboard command
+     * routing, and the React bindings — reads this same object, so command
+     * state never diverges between built-in and custom UI. The controller is
+     * created by the first read and its identity never changes afterwards:
+     * replacing the document, remounting an editor, or switching the active
+     * editor in a multi-document instance all keep the same controller.
+     *
+     * Reading it is safe before the document is ready. Slices report a `pending`
+     * status and commands report themselves disabled instead of throwing, so a
+     * custom UI can subscribe in the same tick as the constructor and will start
+     * receiving real values once an editor mounts.
+     *
+     * `SuperDoc.destroy()` destroys the controller. The returned type is
+     * {@link BorrowedSuperDocUI}, which omits `destroy()`, so a consumer tearing
+     * down state that other readers of this instance still observe is a compile
+     * error rather than a rule in a comment. The instance keeps the owning
+     * reference privately.
+     *
+     * This is an observation and command surface, not a permission boundary.
+     * Anything it exposes is reachable by the page that hosts SuperDoc.
+     *
+     * @example
+     * const superdoc = new SuperDoc({ selector: '#editor', document: file });
+     * const stop = superdoc.ui.comments.observe((comments) => render(comments));
+     * superdoc.ui.commands.get('bold').getState(); // { enabled, active, ... }
+     */
+    get ui(): BorrowedSuperDocUI;
+    /**
+     * Snapshot of the current SuperDoc state. Always reflects the most
+     * recent values from the Pinia store; consumers must re-read on
+     * change rather than caching.
+     *
+     * @see {@link SuperDocState} for the public return shape. The runtime
+     * still walks `RuntimeDocument[]` internally, but `state.documents`
+     * is exposed as the public `Document[]` view - consumers should not
+     * rely on the richer runtime fields (`getEditor`, etc.).
+     */
+    get state(): SuperDocState;
+    /**
+     * Look up the DocumentRendererRuntime associated with a given documentId.
+     * Returns null if no document matches or the document has no
+     * renderer runtime. Replaces raw store reach for `custom UI` host routing
+     * (SD-3213f).
+     *
+     */
+    getDocumentRuntimeForDocument(documentId: string): DocumentRendererRuntime | null;
+    /**
+     * Look up a comment by id. Returns null if not found. Replaces the
+     * legacy `superdoc.commentsStore.getComment(id)` reach for
+     * `custom UI` helpers (SD-3213f). The return type is
+     * intentionally wide (`Record<string, unknown> | null`) so the public
+     * surface does not pull the Pinia comment model type graph.
+     *
+     */
+    getComment(commentId: string): Record<string, unknown> | null;
+    /**
+     * Get the SuperDoc container element
+     */
+    get element(): Element | null;
+    /**
+     * Upgrade a local SuperDoc instance into collaboration by overwriting
+     * the supplied room with the current local document and comment state,
+     * then attaching collaboration to the live editor instance in place.
+     *
+     * This is a **destructive promotion**: the target room is authoritatively
+     * overwritten with the caller's current local state. It is NOT the API
+     * for joining an existing room without changing its content.
+     *
+     * Currently limited to:
+     * - A single DOCX document
+     * - A supported v2 single-doc `v2Collaboration` target
+     * - Overwrite-and-upgrade only (no merge semantics)
+     *
+     * @returns Resolves once the collaborative runtime is ready
+     */
+    upgradeToCollaboration(options: UpgradeToCollaborationOptions): Promise<void>;
+    /**
+     * Add a user to the shared users list. Requires the instance to be
+     * ready; pre-ready mutations would be silently overwritten by the
+     * `this.users = this.config.users || []` re-seed inside `#init`.
+     *
+     * @param user The user to add
+     */
+    addSharedUser(user: User): void;
+    /**
+     * Remove a user from the shared users list. Requires the instance
+     * to be ready for the same reason as `addSharedUser`. Accepts
+     * either a user-like object or a legacy email string.
+     *
+     * @param userOrEmail The user or email of the user to remove
+     */
+    removeSharedUser(userOrEmail: User | string): void;
+    /**
+     * Forward the editor's raw content-error to the consumer callback,
+     * enriching with documentId and the source file. `error` is widened
+     * to `unknown` because editor emitters do not normalize to
+     * `Error` consistently (e.g. `insertContentAt` forwards the original
+     * caught value).
+     *
+     */
+    onContentError({ error, editor }: {
+        error: unknown;
+        editor: Editor;
+    }): void;
+    /**
+     * Triggered when the PDF document is ready
+     */
+    broadcastPdfDocumentReady(): void;
+    /**
+     * Triggered when the superdoc is ready
+     */
+    broadcastReady(): void;
+    /**
+     * Triggered before an editor is created
+     * @param editor The editor that is about to be created
+     */
+    broadcastEditorBeforeCreate(editor: Editor): void;
+    /**
+     * Triggered when an editor is created
+     * @param editor The editor that was created
+     */
+    broadcastEditorCreate(editor: Editor): void;
+    broadcastSourceComplete(): void;
+    broadcastSourceSignalsComplete(): void;
+    /**
+     * Triggered when an editor is destroyed
+     */
+    broadcastEditorDestroy(): void;
+    /**
+     * Triggered when the comments sidebar is toggled
+     */
+    broadcastSidebarToggle(isOpened: boolean): void;
+    /**
+     * Read-only font surface: the substitution- and load-aware report for the active
+     * editor's document. Pulls on demand (the same report streams via `fonts-changed`).
+     * Stable identity; the closures always read the current `activeEditor`. Returns empty
+     * arrays when no editor is active or layout mode is off.
+     */
+    get fonts(): SuperDocFontsApi;
+    /**
+     * Set the active editor compatibility projection. Registered runtimes route
+     * through the registry so the active runtime and `activeEditor` cannot drift.
+     *
+     * @param editor The editor to set as active
+     */
+    setActiveEditor(editor: Editor | null): void;
+    getV2FeatureMatrix(): {
+        feature: string;
+        status: string;
+        reason: string;
+    }[];
+    get v2(): {
+        version: number;
+        featureMatrix: {
+            feature: string;
+            status: string;
+            reason: string;
+        }[];
+    } | null;
+    /**
+     * Register a mounted editor runtime with the shell-owned registry.
+     *
+     * @param runtime
+     * @internal
+     */
+    private registerEditorRuntime;
+    /**
+     * Unregister a mounted editor runtime by id. If it was active, active state
+     * clears and the registry does not auto-promote a different runtime.
+     *
+     * @param runtimeId
+     * @returns Whether a runtime was removed.
+     * @internal
+     */
+    private unregisterEditorRuntime;
+    /**
+     * Return the active editor runtime, or null.
+     *
+     * @internal
+     */
+    private getActiveRuntime;
+    /**
+     * Select the active editor runtime, or clear it with null.
+     *
+     * @param runtimeId
+     * @param reason
+     * @internal
+     */
+    private setActiveRuntime;
+    /**
+     * Resolve which mounted runtime owns a DOM event target.
+     *
+     * @param target
+     * @internal
+     */
+    private resolveRuntimeFromEventTarget;
+    /**
+     * Resolve and activate the runtime that owns a DOM event target.
+     *
+     * @param target
+     * @param reason
+     * @returns Whether a runtime was resolved and activated.
+     * @internal
+     */
+    private activateRuntimeFromEventTarget;
+    /**
+     * Toggle the ruler visibility for document editors.
+     *
+     */
+    toggleRuler(): void;
+    /**
+     * Determine whether the current configuration allows a given permission.
+     * Used by downstream consumers (toolbar, context menu, commands) to keep
+     * tracked-change affordances consistent with customer overrides.
+     *
+     * The `comment` and `trackedChange` fields on the input carry open
+     * index signatures because the function forwards the full payload to
+     * `isAllowed()`; tracked-change payloads from the editor include
+     * `type`, `attrs`, `from`, `to`, `segments`, and consumer comment
+     * shapes vary. The fields read directly here are documented on the
+     * input type itself.
+     *
+     * @see {@link CanPerformPermissionParams} for the input shape.
+     */
+    canPerformPermission({ permission, role, isInternal, comment, trackedChange, }?: CanPerformPermissionParams): boolean;
+    /**
+     * Add a comments list to the superdoc
+     * Requires the comments module to be enabled
+     * @param element The DOM element to render the comments list in
+     */
+    addCommentsList(element: HTMLElement): void;
+    /**
+     * Remove the comments list from the superdoc
+     */
+    removeCommentsList(): void;
+    /**
+     * Scroll the document to a given comment by id.
+     *
+     * @param commentId The comment id
+     * @param [options]
+     * @returns Whether a matching element was found
+     */
+    scrollToComment(commentId: string, options?: {
+        behavior?: ScrollBehavior;
+        block?: ScrollLogicalPosition;
+    }): boolean;
+    /**
+     * Navigate to a block, bookmark, comment, or tracked change target.
+     *
+     * Story-aware navigation is currently supported for bookmark and tracked
+     * change targets. Block and comment targets are body-only.
+     *
+     * @returns Whether the target was found and navigated to.
+     */
+    navigateTo(target: NavigableAddress): Promise<boolean>;
+    /**
+     * Scroll to any document element by its ID.
+     *
+     * Pass any element ID — paragraph nodeId, comment entityId, or tracked
+     * change entityId. The method resolves the element type automatically
+     * and scrolls to it.
+     *
+     * @param elementId - The element's stable ID.
+     * @returns Whether the element was found and scrolled to.
+     *
+     * @example
+     * // Navigate to a paragraph by its nodeId
+     * await superdoc.scrollToElement('5AF80E61');
+     *
+     * // Navigate to a comment by its entityId
+     * await superdoc.scrollToElement('imported-25def254');
+     */
+    scrollToElement(elementId: string): Promise<boolean>;
+    /**
+     * Toggle the custom context menu globally.
+     * Updates both flow editors and DocumentRendererRuntime instances so downstream listeners can short-circuit early.
+     */
+    setDisableContextMenu(disabled?: boolean): void;
+    /**
+     * SD-2454: Toggle bookmark bracket indicators (opt-in, off by default).
+     * Matches Word's "Show bookmarks" option. Triggers a re-layout on change
+     * because the brackets are visible characters participating in text flow.
+     */
+    setShowBookmarks(show?: boolean): void;
+    /**
+     * Toggle nonprinting formatting marks (spaces, tabs, paragraph marks) in the
+     * rendered layout. This is a view-only setting and is not exported to DOCX.
+     */
+    setShowFormattingMarks(show?: boolean): void;
+    /**
+     * Toggle nonprinting formatting marks from their current state.
+     */
+    toggleFormattingMarks(): void;
+    /**
+     * Set the document mode.
+     */
+    setDocumentMode(type: DocumentMode): void;
+    /**
+     * Force DocumentRendererRuntime instances to render a specific tracked-changes mode
+     * or disable tracked-change metadata entirely.
+     *
+     * @param [preferences]
+     */
+    setTrackedChangesPreferences(preferences?: {
+        mode?: 'review' | 'original' | 'final' | 'off';
+        enabled?: boolean;
+    }): void;
+    /**
+     * Search for text or regex in the active editor.
+     *
+     * Returns `undefined` when there is no active editor; otherwise
+     * returns the array of matches the underlying search command produced
+     * (possibly empty).
+     *
+     * @param text The text or regex to search for
+     * @returns The search results, or `undefined` when there is no active editor
+     *   or the active legacy projection exposes no `search` command (e.g. a
+     *   v2-shaped runtime with `commands: null`).
+     */
+    search(text: string | RegExp): SearchMatch[] | undefined;
+    /**
+     * Go to the next search result.
+     *
+     * Pass back a match returned by `superdoc.search()` unchanged; the
+     * runtime resolves its current document position via the embedded
+     * tracker ids.
+     *
+     * @param match The match object returned by `superdoc.search()`.
+     * @returns Whether the command dispatched, or `undefined` when there is no
+     *   active editor or the active legacy projection exposes no
+     *   `goToSearchResult` command (e.g. a v2-shaped runtime with `commands:
+     *   null`).
+     */
+    goToSearchResult(match: SearchMatch): boolean | undefined;
+    /**
+     * Get the current zoom level as a percentage (e.g., 100 for 100%)
+     * @returns The current zoom level as a percentage
+     * @example
+     * const zoom = superdoc.getZoom(); // Returns 100, 150, 200, etc.
+     */
+    getZoom(): number;
+    /**
+     * Set the zoom level for all documents and switch the zoom mode to
+     * `manual` (an explicit numeric zoom expresses intent to leave
+     * `fit-width`; use `setZoomMode('fit-width')` to re-enter fitting).
+     * Updates the centralized activeZoom state, which propagates to all
+     * presentation editors, PDF viewers, and whiteboard layers via the Vue watcher.
+     * @param percent - The zoom level as a percentage (e.g., 100, 150, 200)
+     * @example
+     * superdoc.setZoom(150); // Set zoom to 150%, mode becomes 'manual'
+     * superdoc.setZoom(50);  // Set zoom to 50%
+     */
+    setZoom(percent: number): void;
+    /**
+     * Switch the zoom mode. `fit-width` continuously re-fits the
+     * document to the available container width (clamped by
+     * `config.zoom.fitWidth`); `manual` holds the current value.
+     * Switching to `fit-width` applies the fit immediately when
+     * viewport metrics are available. Emits `zoomChange` (with the
+     * current value) so zoom UIs observe mode-only transitions; a
+     * same-mode call is a no-op.
+     * @param mode - The zoom mode: `'manual'` or `'fit-width'`
+     * @example
+     * superdoc.setZoomMode('fit-width'); // start fitting to the container
+     * superdoc.setZoomMode('manual');    // hold the current zoom value
+     */
+    setZoomMode(mode: SuperDocZoomMode): void;
+    /**
+     * Get a snapshot of the current zoom state: mode, value, the latest
+     * computed fit zoom (null before the first viewport measurement),
+     * and the effective fit bounds.
+     * @returns The current zoom state snapshot
+     * @example
+     * const { mode, value, fitZoom } = superdoc.getZoomState();
+     */
+    getZoomState(): SuperDocZoomState;
+    /**
+     * Get the latest viewport measurements: the width available to the
+     * document, the document's base page width at 100% zoom, and the
+     * unclamped fit zoom. Returns `null` until the first measurement
+     * (editors still mounting). Subscribe to `viewport-change` (or pass
+     * `Config.onViewportChange`) for updates.
+     * @returns The latest viewport metrics, or `null` before the first measurement
+     * @example
+     * const metrics = superdoc.getViewportMetrics();
+     * if (metrics) superdoc.setZoom(Math.min(100, metrics.fitZoom));
+     */
+    getViewportMetrics(): SuperDocViewportMetrics | null;
+    /**
+     * Get the current measurement unit for rulers and measurement fields
+     * (`'in'` or `'cm'`). Defaults to `'in'` before initialization.
+     * @returns The current measurement unit
+     * @example
+     * const unit = superdoc.getMeasurementUnit(); // 'in' | 'cm'
+     */
+    getMeasurementUnit(): SuperDocMeasurementUnit;
+    /**
+     * Set the document-wide measurement unit for rulers and measurement fields
+     * (Word's "measurement units" preference). Updates the centralized state,
+     * which propagates to the ruler and header/footer measurement fields via the
+     * Vue watcher in `SuperDoc.vue`.
+     * @param unit - `'in'` for inches or `'cm'` for centimetres
+     * @example
+     * superdoc.setMeasurementUnit('cm'); // ruler + measurement fields switch to cm
+     */
+    setMeasurementUnit(unit: SuperDocMeasurementUnit): void;
+    /**
+     * Set the document to locked or unlocked
+     */
+    setLocked(lock?: boolean): void;
+    /**
+     * Get the HTML content of all editors
+     * @returns The HTML content of all editors
+     */
+    getHTML(options?: Parameters<Editor['getHTML']>[0]): unknown[];
+    /**
+     * Lock the current superdoc and emit the `locked` event.
+     *
+     * @param [isLocked] Whether the superdoc is locked. Defaults to `false`.
+     * @param [lockedBy] The user who locked the superdoc, or `null`
+     *   when unlocking (or when no user is known). Defaults to `null`.
+     */
+    lockSuperdoc(isLocked?: boolean, lockedBy?: User | null): void;
+    /**
+     * Export the superdoc to a file
+     * @param params - Export configuration
+     */
+    export({ exportType, commentsType, exportedName, additionalFiles, additionalFileNames, isFinalDoc, triggerDownload, fieldsHighlightColor, }?: ExportParams): Promise<Blob>;
+    /**
+     * Replace the active document with a new file while preserving the mounted
+     * editor instance when the active runtime supports it.
+     *
+     * V2 collaboration routes this through the host-owned replace-file command so
+     * the room can be atomically cleared and reseeded instead of tearing down the
+     * SuperDoc instance and racing an empty Y.Doc against imported DOCX bytes.
+     */
+    replaceFile(source: File | Blob | ArrayBuffer | Uint8Array): Promise<unknown>;
+    /**
+     * Export editors to DOCX format.
+     * @param [options]
+     */
+    exportEditorsToDOCX({ commentsType, isFinalDoc, fieldsHighlightColor, }?: {
+        commentsType?: string;
+        isFinalDoc?: boolean;
+        fieldsHighlightColor?: string | null;
+    }): Promise<Blob[]>;
+    /**
+     * Save the superdoc if in collaboration mode. Resolves when all
+     * collaboration documents have flushed their pending writes.
+     */
+    save(): Promise<void>;
+    /**
+     * Open a surface (dialog or floating) above the document content.
+     *
+     */
+    openSurface<TResult = unknown>(request: SurfaceRequest): SurfaceHandle<TResult>;
+    /**
+     * Close a surface by id, or the topmost surface if no id is given.
+     */
+    closeSurface(id?: string): void;
+    /**
+     * Remove one mounted document from the shell by document id.
+     *
+     * Clears any registered runtimes for that document without silently
+     * promoting another runtime, prunes shell-owned comment state for the
+     * document, and resolves after Vue flushes the unmount so DOM-based callers
+     * can observe the root disappearing.
+     *
+     * @param documentId The document id to remove.
+     * @returns `true` when a document was removed, `false` when none matched.
+     */
+    removeDocument(documentId: string): Promise<boolean>;
+    /**
+     * Destroy the superdoc instance
+     */
+    destroy(): void;
+    /**
+     * Focus the active editor or the first editor in the superdoc
+     */
+    focus(options?: EditorRuntimeFocusOptions): void;
+    /**
+     * Set the high contrast mode
+     */
+    setHighContrastMode(isHighContrast: boolean): void;
+}
+export {};