@zeke-02/docx-editor 0.0.35 → 0.5.1

package/dist/{react-1OO-DXvx.d.ts → react-B0W16SV6.d.ts}

@@ -4,10 +4,10 @@ import * as prosemirror_view from 'prosemirror-view';
 import { EditorView } from 'prosemirror-view';
 import * as prosemirror_state from 'prosemirror-state';
 import { EditorState, Transaction } from 'prosemirror-state';
-import { T as TextFormatting, K as ParagraphFormatting, D as Document, a3 as Theme, C as Comment, e as Table } from './agentApi-mv532p8I.js';
-import { F as SidebarItem, g as EditorPluginCore, k as PluginPanelProps, R as RenderedDomContext, G as SidebarItemContext, f as EditorHandle, h as ErrorNotification, m as SavedDocumentData, d as AutoSaveStatus, e as ClipboardSelection } from './ClipboardManager-C1l58nzE.js';
-import { g as PrintOptions, T as Translations, j as TableContext, i as TableAction, P as ParsedClipboardContent } from './clipboard-BvkuNZub.js';
-import { g as DocxInput, D as DocumentAgent } from './DocumentAgent-iedmc_8s.js';
+import { T as TextFormatting, K as ParagraphFormatting, D as Document, a3 as Theme, C as Comment, e as Table } from './agentApi-DLt94vXk.js';
+import { F as FontOption, i as PrintOptions, T as Translations, l as TableContext, k as TableAction, n as TableSplitConfig, P as ParsedClipboardContent } from './TableToolbar-DUgmob2I.js';
+import { F as SidebarItem, g as EditorPluginCore, k as PluginPanelProps, R as RenderedDomContext, G as SidebarItemContext, f as EditorHandle, h as ErrorNotification, m as SavedDocumentData, d as AutoSaveStatus, e as ClipboardSelection } from './ClipboardManager-CVKX0v9q.js';
+import { g as DocxInput, D as DocumentAgent } from './DocumentAgent-DsdXtetF.js';
 import * as react_jsx_runtime from 'react/jsx-runtime';
 
 /**
@@ -111,6 +111,167 @@ interface PluginHostRef {
     refreshPluginStates: () => void;
 }
 
+/**
+ * Selection Highlight Utilities
+ *
+ * Provides visual highlighting for text selection across multiple runs.
+ * Browsers handle ::selection pseudo-element differently, especially when
+ * selection spans multiple elements with different backgrounds or styling.
+ *
+ * This module provides:
+ * - Custom selection highlight rendering
+ * - Programmatic selection range marking
+ * - Visual feedback for selection across runs
+ */
+/** Framework-agnostic CSS properties type (compatible with React.CSSProperties) */
+type CSSProperties = Record<string, any>;
+/**
+ * Highlight rectangle representing a selected region
+ */
+interface HighlightRect {
+    /** Left position in pixels */
+    left: number;
+    /** Top position in pixels */
+    top: number;
+    /** Width in pixels */
+    width: number;
+    /** Height in pixels */
+    height: number;
+}
+/**
+ * Selection highlight configuration
+ */
+interface SelectionHighlightConfig {
+    /** Background color for selection */
+    backgroundColor: string;
+    /** Optional border color for selection */
+    borderColor?: string;
+    /** Optional border radius */
+    borderRadius?: number;
+    /** Z-index for overlay */
+    zIndex?: number;
+    /** Opacity for highlight */
+    opacity?: number;
+    /** Mix blend mode */
+    mixBlendMode?: CSSProperties['mixBlendMode'];
+}
+/**
+ * Selection range in document coordinates
+ */
+interface SelectionRange {
+    /** Start position */
+    start: {
+        paragraphIndex: number;
+        contentIndex: number;
+        offset: number;
+    };
+    /** End position */
+    end: {
+        paragraphIndex: number;
+        contentIndex: number;
+        offset: number;
+    };
+}
+/**
+ * Default selection highlight style (matches Word/Google Docs)
+ */
+declare const DEFAULT_SELECTION_STYLE: SelectionHighlightConfig;
+/**
+ * High contrast selection style
+ */
+declare const HIGH_CONTRAST_SELECTION_STYLE: SelectionHighlightConfig;
+/**
+ * Selection highlight CSS custom properties
+ */
+declare const SELECTION_CSS_VARS: {
+    readonly backgroundColor: "--docx-selection-bg";
+    readonly borderColor: "--docx-selection-border";
+    readonly textColor: "--docx-selection-text";
+};
+/**
+ * Get all selection rectangles from the current DOM selection
+ *
+ * Uses getClientRects() to get accurate rectangles even when
+ * selection spans multiple inline elements.
+ */
+declare function getSelectionRects(containerElement?: HTMLElement | null): HighlightRect[];
+/**
+ * Merge adjacent or overlapping rectangles
+ *
+ * This reduces the number of highlight elements needed and creates
+ * a cleaner visual appearance.
+ */
+declare function mergeAdjacentRects(rects: HighlightRect[], tolerance?: number): HighlightRect[];
+/**
+ * Get selection rectangles with merging applied
+ */
+declare function getMergedSelectionRects(containerElement?: HTMLElement | null): HighlightRect[];
+/**
+ * Generate CSS styles for a highlight rectangle
+ */
+declare function getHighlightRectStyle(rect: HighlightRect, config?: SelectionHighlightConfig): CSSProperties;
+/**
+ * Generate inline CSS for selection pseudo-elements
+ *
+ * This is used to inject consistent selection styling
+ * across all editable elements.
+ */
+declare function generateSelectionCSS(selector: string, config?: SelectionHighlightConfig): string;
+/**
+ * Check if there is an active text selection (not collapsed)
+ */
+declare function hasActiveSelection(): boolean;
+/**
+ * Get the selected text
+ */
+declare function getSelectedText(): string;
+/**
+ * Check if selection is within a specific element
+ */
+declare function isSelectionWithin(element: HTMLElement): boolean;
+/**
+ * Get the bounding rect of the current selection
+ */
+declare function getSelectionBoundingRect(): DOMRect | null;
+/**
+ * Create a selection highlight for a specific text range
+ *
+ * This is useful for find/replace highlighting, AI action previews, etc.
+ */
+declare function highlightTextRange(_containerElement: HTMLElement, startNode: Node, startOffset: number, endNode: Node, endOffset: number): Range | null;
+/**
+ * Select a text range programmatically
+ */
+declare function selectRange(range: Range): void;
+/**
+ * Clear the current selection
+ */
+declare function clearSelection(): void;
+/**
+ * Check if selection is backwards (focus before anchor)
+ */
+declare function isSelectionBackwards(): boolean;
+/**
+ * Normalize selection to always be forward (start before end)
+ */
+declare function normalizeSelectionDirection(): void;
+/**
+ * Inject selection highlight CSS into document
+ */
+declare function injectSelectionStyles(config?: SelectionHighlightConfig): void;
+/**
+ * Remove injected selection styles
+ */
+declare function removeSelectionStyles(): void;
+/**
+ * Check if selection styles are injected
+ */
+declare function areSelectionStylesInjected(): boolean;
+/**
+ * Create a selection change handler that updates highlight rects
+ */
+declare function createSelectionChangeHandler(containerElement: HTMLElement | null, onRectsChange: (rects: HighlightRect[]) => void, merge?: boolean): () => void;
+
 /**
  * Selection State Utilities
  *
@@ -340,6 +501,16 @@ interface PagedEditorRef {
     relayout(): void;
     /** Scroll the visible pages to bring a PM position into view. */
     scrollToPosition(pmPos: number): void;
+    /**
+     * Scroll to the paragraph identified by Word `w14:paraId` / PM `paraId`.
+     * @returns whether a matching paragraph was found
+     */
+    scrollToParaId(paraId: string): boolean;
+    /**
+     * Scroll the paginated view so `pageNumber` (1-indexed) is in view.
+     * No-op if the layout isn't ready yet or pageNumber is out of range.
+     */
+    scrollToPage(pageNumber: number): void;
 }
 
 /**
@@ -364,6 +535,16 @@ interface DocxEditorProps {
     onFontsLoaded?: () => void;
     /** External ProseMirror plugins (from PluginHost) */
     externalPlugins?: prosemirror_state.Plugin[];
+    /**
+     * When true, the editor treats the `document` prop as a schema seed only and
+     * does not load it into ProseMirror on mount. Content is expected to come from
+     * external sources — typically `externalPlugins` such as `ySyncPlugin` from
+     * `y-prosemirror`, but also any code that dispatches transactions directly.
+     *
+     * You must still pass a `document` prop (e.g., `createEmptyDocument()`) so the
+     * editor can build its schema and render the shell.
+     */
+    externalContent?: boolean;
     /** Callback when editor view is ready (for PluginHost) */
     onEditorViewReady?: (view: prosemirror_view.EditorView) => void;
     /** Theme for styling */
@@ -384,6 +565,11 @@ interface DocxEditorProps {
     initialZoom?: number;
     /** Whether the editor is read-only. When true, hides toolbar and rulers */
     readOnly?: boolean;
+    /**
+     * When true, the editor does not intercept Cmd/Ctrl+F or Cmd/Ctrl+H.
+     * This lets the browser or host app handle native find/history shortcuts.
+     */
+    disableFindReplaceShortcuts?: boolean;
     /** Custom toolbar actions */
     toolbarExtra?: ReactNode;
     /** Additional CSS class name */
@@ -398,6 +584,19 @@ interface DocxEditorProps {
     showOutline?: boolean;
     /** Whether to show the floating outline toggle button (default: true) */
     showOutlineButton?: boolean;
+    /**
+     * Custom list of fonts shown in the toolbar's font-family dropdown.
+     * Strings render in the "Other" group; pass `FontOption[]` for category
+     * grouping and CSS fallback chains. Omit to use the built-in 12-font
+     * default. An empty array renders an empty (but enabled) dropdown.
+     *
+     * Pass a stable reference (memoized or module-level) — inline arrays
+     * create a new identity per render and invalidate the picker's memo.
+     *
+     * @example fontFamilies={['Arial', 'Roboto']}
+     * @example fontFamilies={[{ name: 'Roboto', fontFamily: 'Roboto, sans-serif', category: 'sans-serif' }]}
+     */
+    fontFamilies?: ReadonlyArray<string | FontOption>;
     /** Whether to show print button in toolbar (default: true) */
     showPrintButton?: boolean;
     /** Whether to show the editing mode switcher (Editing/Suggesting/Viewing) in toolbar (default: true) */
@@ -426,6 +625,23 @@ interface DocxEditorProps {
     onCommentDelete?: (comment: Comment) => void;
     /** Callback when a reply is added to a comment via the UI */
     onCommentReply?: (reply: Comment, parent: Comment) => void;
+    /**
+     * Controlled comments array. When provided, the editor reads comment thread
+     * metadata (text, author, replies, resolved status) from this prop instead
+     * of internal state, and emits every change through `onCommentsChange`.
+     *
+     * Use this with collaboration backends (Yjs, Liveblocks, Automerge, …) so
+     * comment threads sync across peers — the PM document only carries the
+     * range markers; thread metadata lives outside the doc and needs its own
+     * sync channel.
+     *
+     * If omitted, the editor falls back to internal state (current behavior).
+     * The granular `onCommentAdd`/`onCommentResolve`/`onCommentDelete`/
+     * `onCommentReply` callbacks fire in both modes.
+     */
+    comments?: Comment[];
+    /** Fires whenever the comments array changes (controlled mode). */
+    onCommentsChange?: (comments: Comment[]) => void;
     /**
      * Callback when rendered DOM context is ready (for plugin overlays).
      * Used by PluginHost to get access to the rendered page DOM for positioning.
@@ -452,6 +668,45 @@ interface DocxEditorProps {
     renderTitleBarRight?: () => ReactNode;
     /** Translation overrides. Import a locale JSON file and pass it directly. */
     i18n?: Translations;
+    /**
+     * Mount a controllable agent panel on the right side of the editor. The
+     * panel is the chrome (header, close button, drag-resize); the consumer
+     * supplies whatever content goes inside via `render` — typically a chat
+     * UI from `@ai-sdk/react`'s `useChat`, `assistant-ui`, or any other
+     * framework. We do not ship message bubbles, a composer, or a chat engine.
+     *
+     * Three control patterns:
+     *  - **Uncontrolled**: `agentPanel={{ render }}` — toolbar button + panel
+     *    close button toggle the panel. Width persists to localStorage.
+     *  - **Controlled**: `agentPanel={{ render, open, onOpenChange }}` — the
+     *    consumer owns open state (e.g. tied to a global menu).
+     *  - **Headless**: omit `agentPanel`, use the toolkit directly via
+     *    `useDocxAgentTools` — render the panel anywhere you want.
+     */
+    agentPanel?: {
+        /** Render-prop returning the panel content. Called only when open. */
+        render: (ctx: {
+            close: () => void;
+        }) => ReactNode;
+        /** Controlled open state. Omit for uncontrolled. */
+        open?: boolean;
+        /** Fires when toolbar button or panel close button is clicked. */
+        onOpenChange?: (open: boolean) => void;
+        /** Show the toolbar toggle button. Default: true. */
+        showToolbarButton?: boolean;
+        /** Optional badge / dot on the toolbar button. */
+        toolbarBadge?: ReactNode;
+        /** Optional panel title. Default: t('agentPanel.defaultTitle'). */
+        title?: string;
+        /** Optional panel header icon. Default: sparkle. */
+        icon?: ReactNode;
+        /** Initial panel width in px (uncontrolled). Default: 360. */
+        defaultWidth?: number;
+        /** Min drag width. Default: 280. */
+        minWidth?: number;
+        /** Max drag width. Default: 600. */
+        maxWidth?: number;
+    };
 }
 /**
  * DocxEditor ref interface
@@ -477,8 +732,26 @@ interface DocxEditorRef {
     getCurrentPage: () => number;
     /** Get total page count */
     getTotalPages: () => number;
-    /** Scroll to a specific page */
+    /**
+     * Scroll the paginated view so the given page is in view.
+     * Page numbers are 1-indexed (matches `getCurrentPage` / `getTotalPages`).
+     * No-op for out-of-range or non-integer values.
+     * @example ref.current?.scrollToPage(2)
+     */
     scrollToPage: (pageNumber: number) => void;
+    /**
+     * Scroll the paginated view to the paragraph with the given Word `w14:paraId`.
+     * @returns whether a matching paragraph exists in the ProseMirror document
+     * @example ref.current?.scrollToParaId('1A2B3C4D')
+     */
+    scrollToParaId: (paraId: string) => boolean;
+    /**
+     * Scroll the paginated view to a specific ProseMirror document position.
+     * Use this when you have a raw PM offset; for Word `w14:paraId` use
+     * `scrollToParaId` instead.
+     * @example ref.current?.scrollToPosition(42)
+     */
+    scrollToPosition: (pmPos: number) => void;
     /** Open print preview */
     openPrintPreview: () => void;
     /** Print the document directly */
@@ -504,6 +777,104 @@ interface DocxEditorRef {
      * ```
      */
     applyDocumentChanges: (doc: Document) => boolean;
+    /** Add a comment programmatically. Anchored by Word `w14:paraId` so
+     * it survives unrelated edits. Returns the comment ID, or null if
+     * the paraId is unknown or the search text isn't found / is ambiguous. */
+    addComment: (options: {
+        paraId: string;
+        text: string;
+        author: string;
+        /** Optional: anchor to a specific phrase within the paragraph (must be unique). */
+        search?: string;
+    }) => number | null;
+    /** Reply to an existing comment. Returns the reply comment ID. */
+    replyToComment: (commentId: number, text: string, author: string) => number | null;
+    /** Resolve (mark as done) a comment. */
+    resolveComment: (commentId: number) => void;
+    /** Suggest a tracked change. Pass `replaceWith: ''` to delete the matched text;
+     * pass `search: ''` to insert at paragraph end. Returns false on missing paraId,
+     * missing/ambiguous search, or attempt to layer on an existing tracked change. */
+    proposeChange: (options: {
+        paraId: string;
+        search: string;
+        replaceWith: string;
+        author: string;
+    }) => boolean;
+    /** Locate every paragraph containing `query` (case-insensitive substring).
+     * Returns a stable handle (paraId + the matched phrase) the agent can pass
+     * back to `addComment` / `proposeChange`. */
+    findInDocument: (query: string, options?: {
+        caseSensitive?: boolean;
+        limit?: number;
+    }) => Array<{
+        paraId: string;
+        match: string;
+        before: string;
+        after: string;
+    }>;
+    /**
+     * Apply character formatting (bold / italic / color / size / font / etc.)
+     * to a paragraph or to a unique phrase within it. This is a direct edit,
+     * not a tracked change. Returns false on missing paraId or ambiguous search.
+     */
+    applyFormatting: (options: {
+        paraId: string;
+        search?: string;
+        marks: {
+            bold?: boolean;
+            italic?: boolean;
+            underline?: boolean | {
+                style?: string;
+            };
+            strike?: boolean;
+            color?: {
+                rgb?: string;
+                themeColor?: string;
+            };
+            highlight?: string;
+            fontSize?: number;
+            fontFamily?: {
+                ascii?: string;
+                hAnsi?: string;
+            };
+        };
+    }) => boolean;
+    /**
+     * Apply a paragraph style by styleId (e.g. `'Heading1'`, `'Quote'`).
+     * Direct edit, not a tracked change. Returns false if paraId is unknown.
+     */
+    setParagraphStyle: (options: {
+        paraId: string;
+        styleId: string;
+    }) => boolean;
+    /**
+     * Read the contents of a single page. 1-indexed; returns null if the page
+     * does not exist. Each paragraph is returned with its stable paraId so the
+     * agent can comment on or modify it without an extra round-trip.
+     */
+    getPageContent: (pageNumber: number) => {
+        pageNumber: number;
+        text: string;
+        paragraphs: Array<{
+            paraId: string;
+            text: string;
+            styleId?: string;
+        }>;
+    } | null;
+    /** Read the user's current cursor / selection — what's highlighted right now. */
+    getSelectionInfo: () => {
+        paraId: string | null;
+        selectedText: string;
+        paragraphText: string;
+        before: string;
+        after: string;
+    } | null;
+    /** Get all comments. */
+    getComments: () => Comment[];
+    /** Subscribe to document changes. Fires after every committed edit. Returns unsubscribe. */
+    onContentChange: (listener: (document: Document) => void) => () => void;
+    /** Subscribe to selection changes (cursor moves / selection changes). Returns unsubscribe. */
+    onSelectionChange: (listener: (selection: SelectionState | null) => void) => () => void;
 }
 type EditorMode = 'editing' | 'suggesting' | 'viewing';
 /**
@@ -546,6 +917,10 @@ type RenderAsyncOptions = Omit<DocxEditorProps, 'documentBuffer' | 'document'>;
 interface DocxEditorHandle extends EditorHandle {
     /** Set zoom level (1.0 = 100%). */
     setZoom: (zoom: number) => void;
+    /** Scroll to a body paragraph by Word `w14:paraId`. */
+    scrollToParaId: (paraId: string) => boolean;
+    /** Scroll to a raw ProseMirror document position. */
+    scrollToPosition: (pmPos: number) => void;
 }
 /**
  * Render a DOCX editor into a container element.
@@ -670,6 +1045,8 @@ interface UseTableSelectionReturn {
     state: TableSelectionState;
     handleCellClick: (tableIndex: number, rowIndex: number, columnIndex: number) => void;
     handleAction: (action: TableAction) => void;
+    getSplitCellConfig: () => TableSplitConfig | null;
+    applySplitCell: (rows: number, cols: number) => void;
     clearSelection: () => void;
     isCellSelected: (tableIndex: number, rowIndex: number, columnIndex: number) => boolean;
     tableContext: TableContext | null;
@@ -829,167 +1206,6 @@ declare function isZoomPreset(zoom: number): boolean;
  */
 declare function clampZoom(zoom: number, minZoom?: number, maxZoom?: number): number;
 
-/**
- * Selection Highlight Utilities
- *
- * Provides visual highlighting for text selection across multiple runs.
- * Browsers handle ::selection pseudo-element differently, especially when
- * selection spans multiple elements with different backgrounds or styling.
- *
- * This module provides:
- * - Custom selection highlight rendering
- * - Programmatic selection range marking
- * - Visual feedback for selection across runs
- */
-/** Framework-agnostic CSS properties type (compatible with React.CSSProperties) */
-type CSSProperties = Record<string, any>;
-/**
- * Highlight rectangle representing a selected region
- */
-interface HighlightRect {
-    /** Left position in pixels */
-    left: number;
-    /** Top position in pixels */
-    top: number;
-    /** Width in pixels */
-    width: number;
-    /** Height in pixels */
-    height: number;
-}
-/**
- * Selection highlight configuration
- */
-interface SelectionHighlightConfig {
-    /** Background color for selection */
-    backgroundColor: string;
-    /** Optional border color for selection */
-    borderColor?: string;
-    /** Optional border radius */
-    borderRadius?: number;
-    /** Z-index for overlay */
-    zIndex?: number;
-    /** Opacity for highlight */
-    opacity?: number;
-    /** Mix blend mode */
-    mixBlendMode?: CSSProperties['mixBlendMode'];
-}
-/**
- * Selection range in document coordinates
- */
-interface SelectionRange {
-    /** Start position */
-    start: {
-        paragraphIndex: number;
-        contentIndex: number;
-        offset: number;
-    };
-    /** End position */
-    end: {
-        paragraphIndex: number;
-        contentIndex: number;
-        offset: number;
-    };
-}
-/**
- * Default selection highlight style (matches Word/Google Docs)
- */
-declare const DEFAULT_SELECTION_STYLE: SelectionHighlightConfig;
-/**
- * High contrast selection style
- */
-declare const HIGH_CONTRAST_SELECTION_STYLE: SelectionHighlightConfig;
-/**
- * Selection highlight CSS custom properties
- */
-declare const SELECTION_CSS_VARS: {
-    readonly backgroundColor: "--docx-selection-bg";
-    readonly borderColor: "--docx-selection-border";
-    readonly textColor: "--docx-selection-text";
-};
-/**
- * Get all selection rectangles from the current DOM selection
- *
- * Uses getClientRects() to get accurate rectangles even when
- * selection spans multiple inline elements.
- */
-declare function getSelectionRects(containerElement?: HTMLElement | null): HighlightRect[];
-/**
- * Merge adjacent or overlapping rectangles
- *
- * This reduces the number of highlight elements needed and creates
- * a cleaner visual appearance.
- */
-declare function mergeAdjacentRects(rects: HighlightRect[], tolerance?: number): HighlightRect[];
-/**
- * Get selection rectangles with merging applied
- */
-declare function getMergedSelectionRects(containerElement?: HTMLElement | null): HighlightRect[];
-/**
- * Generate CSS styles for a highlight rectangle
- */
-declare function getHighlightRectStyle(rect: HighlightRect, config?: SelectionHighlightConfig): CSSProperties;
-/**
- * Generate inline CSS for selection pseudo-elements
- *
- * This is used to inject consistent selection styling
- * across all editable elements.
- */
-declare function generateSelectionCSS(selector: string, config?: SelectionHighlightConfig): string;
-/**
- * Check if there is an active text selection (not collapsed)
- */
-declare function hasActiveSelection(): boolean;
-/**
- * Get the selected text
- */
-declare function getSelectedText(): string;
-/**
- * Check if selection is within a specific element
- */
-declare function isSelectionWithin(element: HTMLElement): boolean;
-/**
- * Get the bounding rect of the current selection
- */
-declare function getSelectionBoundingRect(): DOMRect | null;
-/**
- * Create a selection highlight for a specific text range
- *
- * This is useful for find/replace highlighting, AI action previews, etc.
- */
-declare function highlightTextRange(_containerElement: HTMLElement, startNode: Node, startOffset: number, endNode: Node, endOffset: number): Range | null;
-/**
- * Select a text range programmatically
- */
-declare function selectRange(range: Range): void;
-/**
- * Clear the current selection
- */
-declare function clearSelection(): void;
-/**
- * Check if selection is backwards (focus before anchor)
- */
-declare function isSelectionBackwards(): boolean;
-/**
- * Normalize selection to always be forward (start before end)
- */
-declare function normalizeSelectionDirection(): void;
-/**
- * Inject selection highlight CSS into document
- */
-declare function injectSelectionStyles(config?: SelectionHighlightConfig): void;
-/**
- * Remove injected selection styles
- */
-declare function removeSelectionStyles(): void;
-/**
- * Check if selection styles are injected
- */
-declare function areSelectionStylesInjected(): boolean;
-/**
- * Create a selection change handler that updates highlight rects
- */
-declare function createSelectionChangeHandler(containerElement: HTMLElement | null, onRectsChange: (rects: HighlightRect[]) => void, merge?: boolean): () => void;
-
 /**
  * Selection Highlight Hook
  *
@@ -1083,6 +1299,8 @@ interface UseClipboardOptions {
     cleanWordFormatting?: boolean;
     editable?: boolean;
     onError?: (error: Error) => void;
+    /** Document theme — used to resolve themed colors in the HTML clipboard payload. */
+    theme?: Theme | null;
 }
 interface UseClipboardReturn {
     copy: (selection: ClipboardSelection) => Promise<boolean>;