@zeke-02/docx-editor 0.5.3 → 0.5.4

package/dist/index-B5A-J9GC.d.ts

@@ -0,0 +1,1119 @@
+import * as React from 'react';
+import { ReactNode, CSSProperties } from 'react';
+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 { D as Document, T as Theme } from './document-CxOagoLQ.js';
+import { S as StyleInfo, A as AgentContext, P as Position, R as Range, a as AgentCommand, F as FontOption, b as PrintOptions } from './agentApi-B2Y7kexW.js';
+import { R as RenderedDomContext, a as ReactSidebarItem } from './types-BnIs4sE7.js';
+import { T as TextFormatting, P as ParagraphFormatting, C as Comment } from './content-REFGFfEH.js';
+import { a as Translations, T as TranslationKey } from './types-BF48VxkC.js';
+import { E as EditorHandle } from './types-CW6HFAX6.js';
+import * as react_jsx_runtime from 'react/jsx-runtime';
+
+interface LocaleProviderProps {
+    i18n?: Translations;
+    children: ReactNode;
+}
+declare function LocaleProvider({ i18n, children }: LocaleProviderProps): react_jsx_runtime.JSX.Element;
+declare function useTranslation(): {
+    t: (key: TranslationKey, vars?: Record<string, string | number>) => string;
+};
+
+/**
+ * Selective Save Module
+ *
+ * Orchestrates selective XML patching for the save flow.
+ * Serializes full document.xml, validates patch safety, builds patched XML,
+ * and calls applyUpdatesToZip() to produce the final DOCX.
+ *
+ * Returns null on any failure, signaling the caller to fall back to full repack.
+ */
+
+interface SelectiveSaveOptions {
+    /** Changed paragraph IDs to selectively patch */
+    changedParaIds: Set<string>;
+    /** Whether structural changes occurred (paragraph add/delete) */
+    structuralChange: boolean;
+    /** Whether any changes affected paragraphs without paraId */
+    hasUntrackedChanges: boolean;
+}
+
+/**
+ * Flexible input types for DOCX documents.
+ *
+ * Accepts any common binary format so consumers don't need to manually
+ * convert before passing data to the editor or parser.
+ */
+/**
+ * Any binary representation of a DOCX file that the editor can consume.
+ *
+ * - `ArrayBuffer` — from `FileReader.readAsArrayBuffer()` or `fetch().arrayBuffer()`
+ * - `Uint8Array` — from Node.js `fs.readFile()` or streaming APIs
+ * - `Blob` — from drag-and-drop or `<input type="file">`
+ * - `File` — subclass of Blob, from `<input type="file">`
+ */
+type DocxInput = ArrayBuffer | Uint8Array | Blob | File;
+
+/**
+ * DocumentAgent - High-level fluent API for programmatic document manipulation
+ *
+ * Provides a convenient interface for:
+ * - Reading document content and metadata
+ * - Editing text with formatting
+ * - Inserting tables, images, and hyperlinks
+ * - Managing template variables
+ * - Exporting to DOCX buffer
+ *
+ * All operations are immutable - they return a new DocumentAgent instance
+ * or don't modify the underlying document.
+ */
+
+/**
+ * Options for inserting text
+ */
+interface InsertTextOptions {
+    /** Text formatting */
+    formatting?: TextFormatting;
+}
+/**
+ * Options for inserting table
+ */
+interface InsertTableOptions {
+    /** Table data (2D array of strings) */
+    data?: string[][];
+    /** Whether first row is a header */
+    hasHeader?: boolean;
+}
+/**
+ * Options for inserting image
+ */
+interface InsertImageOptions {
+    /** Image width in pixels */
+    width?: number;
+    /** Image height in pixels */
+    height?: number;
+    /** Alt text for accessibility */
+    alt?: string;
+}
+/**
+ * Options for inserting hyperlink
+ */
+interface InsertHyperlinkOptions {
+    /** Display text (overrides selected text) */
+    displayText?: string;
+    /** Tooltip on hover */
+    tooltip?: string;
+}
+/**
+ * Formatted text segment
+ */
+interface FormattedTextSegment {
+    /** Text content */
+    text: string;
+    /** Applied formatting */
+    formatting?: TextFormatting;
+    /** Is part of a hyperlink */
+    isHyperlink?: boolean;
+    /** Hyperlink URL if applicable */
+    hyperlinkUrl?: string;
+}
+/**
+ * DocumentAgent provides a fluent API for document manipulation
+ *
+ * @example
+ * ```ts
+ * const agent = new DocumentAgent(buffer);
+ *
+ * // Read operations
+ * const text = agent.getText();
+ * const wordCount = agent.getWordCount();
+ * const variables = agent.getVariables();
+ *
+ * // Write operations (returns new agent)
+ * const newAgent = agent
+ *   .insertText({ paragraphIndex: 0, offset: 0 }, 'Hello ', { formatting: { bold: true } })
+ *   .applyStyle({ paragraphIndex: 0, offset: 0 }, { paragraphIndex: 0, offset: 5 }, 'Heading1');
+ *
+ * // Export
+ * const newBuffer = await newAgent.toBuffer();
+ * ```
+ */
+declare class DocumentAgent {
+    private _document;
+    private _pendingVariables;
+    /**
+     * Create a new DocumentAgent
+     *
+     * @param source - Document object or ArrayBuffer to parse
+     */
+    constructor(source: Document | ArrayBuffer);
+    /**
+     * Create a DocumentAgent from a DOCX buffer (async)
+     *
+     * @param buffer - DOCX file as ArrayBuffer, Uint8Array, Blob, or File
+     * @returns Promise resolving to DocumentAgent
+     */
+    static fromBuffer(buffer: DocxInput): Promise<DocumentAgent>;
+    /**
+     * Create a DocumentAgent from a Document object
+     *
+     * @param document - Parsed Document
+     * @returns DocumentAgent
+     */
+    static fromDocument(document: Document): DocumentAgent;
+    /**
+     * Get the underlying document
+     */
+    getDocument(): Document;
+    /**
+     * Get plain text content of the document
+     *
+     * @returns All document text concatenated
+     */
+    getText(): string;
+    /**
+     * Get formatted text segments
+     *
+     * @returns Array of text segments with formatting info
+     */
+    getFormattedText(): FormattedTextSegment[];
+    /**
+     * Get detected template variables
+     *
+     * @returns Array of variable names (without braces)
+     */
+    getVariables(): string[];
+    /**
+     * Get available styles from the document
+     *
+     * @returns Array of style info
+     */
+    getStyles(): StyleInfo[];
+    /**
+     * Get approximate page count
+     *
+     * Note: This is an estimate based on content length.
+     * Actual page count requires full layout computation.
+     *
+     * @returns Estimated page count
+     */
+    getPageCount(): number;
+    /**
+     * Get word count
+     *
+     * @returns Number of words in the document
+     */
+    getWordCount(): number;
+    /**
+     * Get character count
+     *
+     * @param includeSpaces - Whether to include whitespace
+     * @returns Number of characters
+     */
+    getCharacterCount(includeSpaces?: boolean): number;
+    /**
+     * Get paragraph count
+     *
+     * @returns Number of paragraphs
+     */
+    getParagraphCount(): number;
+    /**
+     * Get table count
+     *
+     * @returns Number of tables
+     */
+    getTableCount(): number;
+    /**
+     * Get document context for AI agents
+     *
+     * @param outlineMaxChars - Max characters per paragraph in outline
+     * @returns Agent context
+     */
+    getAgentContext(outlineMaxChars?: number): AgentContext;
+    /**
+     * Insert text at a position
+     *
+     * @param position - Where to insert
+     * @param text - Text to insert
+     * @param options - Insert options
+     * @returns New DocumentAgent with text inserted
+     */
+    insertText(position: Position, text: string, options?: InsertTextOptions): DocumentAgent;
+    /**
+     * Replace text in a range
+     *
+     * @param range - Range to replace
+     * @param text - Replacement text
+     * @param options - Replace options
+     * @returns New DocumentAgent with text replaced
+     */
+    replaceRange(range: Range, text: string, options?: InsertTextOptions): DocumentAgent;
+    /**
+     * Delete text in a range
+     *
+     * @param range - Range to delete
+     * @returns New DocumentAgent with text deleted
+     */
+    deleteRange(range: Range): DocumentAgent;
+    /**
+     * Apply text formatting to a range
+     *
+     * @param range - Range to format
+     * @param formatting - Formatting to apply
+     * @returns New DocumentAgent with formatting applied
+     */
+    applyFormatting(range: Range, formatting: Partial<TextFormatting>): DocumentAgent;
+    /**
+     * Apply a named style to a paragraph
+     *
+     * @param paragraphIndex - Index of the paragraph
+     * @param styleId - Style ID to apply
+     * @returns New DocumentAgent with style applied
+     */
+    applyStyle(paragraphIndex: number, styleId: string): DocumentAgent;
+    /**
+     * Apply paragraph formatting
+     *
+     * @param paragraphIndex - Index of the paragraph
+     * @param formatting - Formatting to apply
+     * @returns New DocumentAgent with formatting applied
+     */
+    applyParagraphFormatting(paragraphIndex: number, formatting: Partial<ParagraphFormatting>): DocumentAgent;
+    /**
+     * Insert a table at a position
+     *
+     * @param position - Where to insert the table
+     * @param rows - Number of rows
+     * @param cols - Number of columns
+     * @param options - Table options
+     * @returns New DocumentAgent with table inserted
+     */
+    insertTable(position: Position, rows: number, cols: number, options?: InsertTableOptions): DocumentAgent;
+    /**
+     * Insert an image at a position
+     *
+     * @param position - Where to insert the image
+     * @param src - Image source (base64 data URL or URL)
+     * @param options - Image options
+     * @returns New DocumentAgent with image inserted
+     */
+    insertImage(position: Position, src: string, options?: InsertImageOptions): DocumentAgent;
+    /**
+     * Insert a hyperlink
+     *
+     * @param range - Range to make into a hyperlink
+     * @param url - URL of the hyperlink
+     * @param options - Hyperlink options
+     * @returns New DocumentAgent with hyperlink inserted
+     */
+    insertHyperlink(range: Range, url: string, options?: InsertHyperlinkOptions): DocumentAgent;
+    /**
+     * Remove a hyperlink but keep the text
+     *
+     * @param range - Range containing the hyperlink
+     * @returns New DocumentAgent with hyperlink removed
+     */
+    removeHyperlink(range: Range): DocumentAgent;
+    /**
+     * Insert a paragraph break
+     *
+     * @param position - Where to break the paragraph
+     * @returns New DocumentAgent with paragraph broken
+     */
+    insertParagraphBreak(position: Position): DocumentAgent;
+    /**
+     * Merge consecutive paragraphs
+     *
+     * @param startParagraphIndex - First paragraph index
+     * @param count - Number of paragraphs to merge with the first
+     * @returns New DocumentAgent with paragraphs merged
+     */
+    mergeParagraphs(startParagraphIndex: number, count: number): DocumentAgent;
+    /**
+     * Set a template variable value
+     *
+     * Note: Variables are not applied until `applyVariables()` is called
+     *
+     * @param name - Variable name (without braces)
+     * @param value - Variable value
+     * @returns This DocumentAgent (for chaining)
+     */
+    setVariable(name: string, value: string): DocumentAgent;
+    /**
+     * Set multiple template variables
+     *
+     * @param variables - Map of variable names to values
+     * @returns This DocumentAgent (for chaining)
+     */
+    setVariables(variables: Record<string, string>): DocumentAgent;
+    /**
+     * Get pending variable values
+     *
+     * @returns Map of pending variable values
+     */
+    getPendingVariables(): Record<string, string>;
+    /**
+     * Clear pending variables
+     *
+     * @returns This DocumentAgent (for chaining)
+     */
+    clearPendingVariables(): DocumentAgent;
+    /**
+     * Apply all pending template variables
+     *
+     * Uses docxtemplater to substitute variables while preserving formatting.
+     *
+     * @param variables - Optional additional variables (merged with pending)
+     * @returns New DocumentAgent with variables applied
+     */
+    applyVariables(variables?: Record<string, string>): Promise<DocumentAgent>;
+    /**
+     * Export document to DOCX ArrayBuffer
+     *
+     * @returns Promise resolving to DOCX file as ArrayBuffer
+     */
+    toBuffer(options?: {
+        selective?: SelectiveSaveOptions;
+    }): Promise<ArrayBuffer>;
+    /**
+     * Export document to Blob
+     *
+     * @param mimeType - MIME type for the blob
+     * @returns Promise resolving to DOCX file as Blob
+     */
+    toBlob(mimeType?: string): Promise<Blob>;
+    /**
+     * Execute multiple commands in sequence
+     *
+     * @param commands - Commands to execute
+     * @returns New DocumentAgent with all commands applied
+     */
+    executeCommands(commands: AgentCommand[]): DocumentAgent;
+    /**
+     * Execute a single command and return new agent
+     */
+    private _executeCommand;
+    /**
+     * Get plain text from document body
+     */
+    private _getBodyText;
+    /**
+     * Get plain text from a paragraph
+     */
+    private _getParagraphText;
+    /**
+     * Get plain text from a run
+     */
+    private _getRunText;
+    /**
+     * Get plain text from a hyperlink
+     */
+    private _getHyperlinkText;
+    /**
+     * Get plain text from a table
+     */
+    private _getTableText;
+    /**
+     * Extract formatted text segments from a paragraph
+     */
+    private _extractParagraphSegments;
+    /**
+     * Parse heading level from style ID
+     */
+    private _parseHeadingLevel;
+    /**
+     * Check if document has images
+     */
+    private _hasImages;
+    /**
+     * Check if document has hyperlinks
+     */
+    private _hasHyperlinks;
+}
+
+/**
+ * Selection State Utilities
+ *
+ * Extracts selection state from ProseMirror for toolbar integration.
+ */
+
+/**
+ * Selection state for toolbar integration
+ */
+interface SelectionState {
+    /** Whether there's an active selection (not just cursor) */
+    hasSelection: boolean;
+    /** Whether selection spans multiple paragraphs */
+    isMultiParagraph: boolean;
+    /** Current text formatting at selection/cursor */
+    textFormatting: TextFormatting;
+    /** Current paragraph formatting */
+    paragraphFormatting: ParagraphFormatting;
+    /** Current paragraph style ID (e.g., 'Heading1', 'Normal') */
+    styleId: string | null;
+    /** Start paragraph index */
+    startParagraphIndex: number;
+    /** End paragraph index */
+    endParagraphIndex: number;
+}
+
+/**
+ * Layout Engine Types
+ *
+ * Core types for the paginated layout engine.
+ * Converts document blocks + measurements into positioned fragments on pages.
+ */
+/**
+ * Unique identifier for a block in the document.
+ * Format: typically `${index}-${type}` or just the block index.
+ */
+type BlockId = string | number;
+/**
+ * Base fragment properties common to all fragment types.
+ */
+type FragmentBase = {
+    /** Block ID this fragment belongs to. */
+    blockId: BlockId;
+    /** X position on page (relative to page left). */
+    x: number;
+    /** Y position on page (relative to page top). */
+    y: number;
+    /** Width of the fragment. */
+    width: number;
+    /** ProseMirror start position (for click mapping). */
+    pmStart?: number;
+    /** ProseMirror end position (for click mapping). */
+    pmEnd?: number;
+};
+/**
+ * A paragraph fragment positioned on a page.
+ * May span only part of the paragraph's lines if split across pages.
+ */
+type ParagraphFragment = FragmentBase & {
+    kind: 'paragraph';
+    /** First line index (inclusive) from the measure. */
+    fromLine: number;
+    /** Last line index (exclusive) from the measure. */
+    toLine: number;
+    /** Height of this fragment. */
+    height: number;
+    /** True if this continues from a previous page. */
+    continuesFromPrev?: boolean;
+    /** True if this continues onto the next page. */
+    continuesOnNext?: boolean;
+};
+/**
+ * A table fragment positioned on a page.
+ * May span only part of the table's rows if split across pages.
+ */
+type TableFragment = FragmentBase & {
+    kind: 'table';
+    /** First row index (inclusive). */
+    fromRow: number;
+    /** Last row index (exclusive). */
+    toRow: number;
+    /** Height of this fragment. */
+    height: number;
+    /** True if this is a floating table. */
+    isFloating?: boolean;
+    /** True if this continues from a previous page. */
+    continuesFromPrev?: boolean;
+    /** True if this continues onto the next page. */
+    continuesOnNext?: boolean;
+    /** Number of header rows prepended to this continuation fragment (0 or undefined for first fragment). */
+    headerRowCount?: number;
+};
+/**
+ * An image fragment positioned on a page.
+ */
+type ImageFragment = FragmentBase & {
+    kind: 'image';
+    /** Height of the image. */
+    height: number;
+    /** True if this is an anchored/floating image. */
+    isAnchored?: boolean;
+    /** Z-index for layering. */
+    zIndex?: number;
+};
+/**
+ * A text box fragment positioned on a page.
+ */
+type TextBoxFragment = FragmentBase & {
+    kind: 'textBox';
+    /** Height of the text box. */
+    height: number;
+    /** True when positioned outside normal document flow. */
+    isFloating?: boolean;
+    /** Stack order hint for anchored text boxes. */
+    zIndex?: number;
+};
+/**
+ * Union of all fragment types.
+ */
+type Fragment = ParagraphFragment | TableFragment | ImageFragment | TextBoxFragment;
+/**
+ * Page margin configuration.
+ */
+type PageMargins = {
+    top: number;
+    right: number;
+    bottom: number;
+    left: number;
+    /** Distance from page top to header content. */
+    header?: number;
+    /** Distance from page bottom to footer content. */
+    footer?: number;
+};
+/**
+ * A rendered page containing positioned fragments.
+ */
+type Page = {
+    /** Page number (1-indexed). */
+    number: number;
+    /** Fragments positioned on this page. */
+    fragments: Fragment[];
+    /** Page margins. */
+    margins: PageMargins;
+    /** Page size (width, height). */
+    size: {
+        w: number;
+        h: number;
+    };
+    /** Page orientation. */
+    orientation?: 'portrait' | 'landscape';
+    /** Section index this page belongs to. */
+    sectionIndex?: number;
+    /** Header/footer references for this page. */
+    headerFooterRefs?: {
+        headerDefault?: string;
+        headerFirst?: string;
+        headerEven?: string;
+        footerDefault?: string;
+        footerFirst?: string;
+        footerEven?: string;
+    };
+    /** Footnote IDs that appear on this page (for rendering). */
+    footnoteIds?: number[];
+    /** Height reserved for the footnote area at page bottom (pixels). */
+    footnoteReservedHeight?: number;
+    /** Column layout for this page (if multi-column). */
+    columns?: ColumnLayout;
+};
+/**
+ * Column layout configuration.
+ */
+type ColumnLayout = {
+    count: number;
+    gap: number;
+    equalWidth?: boolean;
+    /** Draw vertical separator line between columns (w:sep). */
+    separator?: boolean;
+};
+/**
+ * Header/footer layout for a specific type.
+ */
+type HeaderFooterLayout = {
+    height: number;
+    fragments: Fragment[];
+};
+/**
+ * Final layout output ready for rendering/painting.
+ */
+type Layout = {
+    /** Default page size for the document. */
+    pageSize: {
+        w: number;
+        h: number;
+    };
+    /** All rendered pages with positioned fragments. */
+    pages: Page[];
+    /** Column configuration (if multi-column). */
+    columns?: ColumnLayout;
+    /** Header layouts by type (default, first, even). */
+    headers?: Record<string, HeaderFooterLayout>;
+    /** Footer layouts by type (default, first, even). */
+    footers?: Record<string, HeaderFooterLayout>;
+    /** Gap between pages in pixels (for rendering). */
+    pageGap?: number;
+};
+
+interface PagedEditorRef {
+    /** Get the current document. */
+    getDocument(): Document | null;
+    /** Get the ProseMirror EditorState. */
+    getState(): EditorState | null;
+    /** Get the ProseMirror EditorView. */
+    getView(): EditorView | null;
+    /** Focus the editor. */
+    focus(): void;
+    /** Blur the editor. */
+    blur(): void;
+    /** Check if focused. */
+    isFocused(): boolean;
+    /** Dispatch a transaction. */
+    dispatch(tr: Transaction): void;
+    /** Undo. */
+    undo(): boolean;
+    /** Redo. */
+    redo(): boolean;
+    /** Set selection by PM position. */
+    setSelection(anchor: number, head?: number): void;
+    /** Get current layout. */
+    getLayout(): Layout | null;
+    /** Force re-layout. */
+    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;
+}
+
+/**
+ * DocxEditor props
+ */
+interface DocxEditorProps {
+    /** Document data — ArrayBuffer, Uint8Array, Blob, or File */
+    documentBuffer?: DocxInput | null;
+    /** Pre-parsed document (alternative to documentBuffer) */
+    document?: Document | null;
+    /** Callback when document is saved */
+    onSave?: (buffer: ArrayBuffer) => void;
+    /** Author name used for comments and track changes */
+    author?: string;
+    /** Callback when document changes */
+    onChange?: (document: Document) => void;
+    /** Callback when selection changes */
+    onSelectionChange?: (state: SelectionState | null) => void;
+    /** Callback on error */
+    onError?: (error: Error) => void;
+    /** Callback when fonts are loaded */
+    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 */
+    theme?: Theme | null;
+    /** Whether to show toolbar (default: true) */
+    showToolbar?: boolean;
+    /** Whether to show zoom control (default: true) */
+    showZoomControl?: boolean;
+    /** Whether to show page margin guides/boundaries (default: false) */
+    showMarginGuides?: boolean;
+    /** Color for margin guides (default: '#c0c0c0') */
+    marginGuideColor?: string;
+    /** Whether to show horizontal ruler (default: false) */
+    showRuler?: boolean;
+    /** Unit for ruler display (default: 'inch') */
+    rulerUnit?: 'inch' | 'cm';
+    /** Initial zoom level (default: 1.0) */
+    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 */
+    className?: string;
+    /** Additional inline styles */
+    style?: CSSProperties;
+    /** Placeholder when no document */
+    placeholder?: ReactNode;
+    /** Loading indicator */
+    loadingIndicator?: ReactNode;
+    /** Whether to show the document outline sidebar (default: false) */
+    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) */
+    showModeSwitcher?: boolean;
+    /** Whether to show the comments sidebar toggle button in toolbar (default: true) */
+    showCommentsSidebarToggle?: boolean;
+    /** Print options for print preview */
+    printOptions?: PrintOptions;
+    /**
+     * Callback when print is triggered. Pass it to enable the `File > Print`
+     * menu entry; omit to hide. The imperative `ref.current.print()` also
+     * invokes this callback.
+     */
+    onPrint?: () => void;
+    /** Callback when content is copied */
+    onCopy?: () => void;
+    /** Callback when content is cut */
+    onCut?: () => void;
+    /** Callback when content is pasted */
+    onPaste?: () => void;
+    /** Editor mode: 'editing' (direct edits), 'suggesting' (track changes), or 'viewing' (read-only). Default: 'editing' */
+    mode?: EditorMode;
+    /** Callback when the editing mode changes */
+    onModeChange?: (mode: EditorMode) => void;
+    /** Callback when a comment is added via the UI */
+    onCommentAdd?: (comment: Comment) => void;
+    /** Callback when a comment is resolved via the UI */
+    onCommentResolve?: (comment: Comment) => void;
+    /** Callback when a comment is deleted via the UI */
+    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.
+     */
+    onRenderedDomContextReady?: (context: RenderedDomContext) => void;
+    /**
+     * Plugin overlays to render inside the editor viewport.
+     * Passed from PluginHost to render plugin-specific overlays.
+     */
+    pluginOverlays?: ReactNode;
+    /** Sidebar items from plugins (passed from PluginHost). */
+    pluginSidebarItems?: ReactSidebarItem[];
+    /** Rendered DOM context from PluginHost (for sidebar position resolution). */
+    pluginRenderedDomContext?: RenderedDomContext | null;
+    /** Custom logo/icon for the title bar */
+    renderLogo?: () => ReactNode;
+    /** Document name shown in the title bar */
+    documentName?: string;
+    /** Callback when document name changes */
+    onDocumentNameChange?: (name: string) => void;
+    /** Whether the document name is editable (default: true) */
+    documentNameEditable?: boolean;
+    /** Custom right-side actions for the title bar */
+    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
+ */
+interface DocxEditorRef {
+    /** Get the DocumentAgent for programmatic access */
+    getAgent: () => DocumentAgent | null;
+    /** Get the current document */
+    getDocument: () => Document | null;
+    /** Get the editor ref */
+    getEditorRef: () => PagedEditorRef | null;
+    /** Save the document to buffer. Pass { selective: false } to force full repack. */
+    save: (options?: {
+        selective?: boolean;
+    }) => Promise<ArrayBuffer | null>;
+    /** Set zoom level */
+    setZoom: (zoom: number) => void;
+    /** Get current zoom level */
+    getZoom: () => number;
+    /** Focus the editor */
+    focus: () => void;
+    /** Get current page number */
+    getCurrentPage: () => number;
+    /** Get total page count */
+    getTotalPages: () => number;
+    /**
+     * 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 */
+    print: () => void;
+    /** Load a pre-parsed document programmatically */
+    loadDocument: (doc: Document) => void;
+    /** Load a DOCX buffer programmatically (ArrayBuffer, Uint8Array, Blob, or File) */
+    loadDocumentBuffer: (buffer: DocxInput) => Promise<void>;
+    /**
+     * Apply document changes from a DocumentAgent while preserving undo history.
+     * This dispatches a PM transaction that replaces the document content,
+     * allowing undo/redo to work with agent-made changes.
+     *
+     * @param doc - The modified Document from an agent
+     * @returns true if the changes were applied, false if the editor is not ready
+     *
+     * @example
+     * ```ts
+     * const agent = EnhancedDocumentAgent.fromDocument(editorRef.current.getDocument());
+     * const updated = agent.toggleBulletList([0, 1, 2]).getDocument();
+     * editorRef.current.applyDocumentChanges(updated);
+     * // Ctrl+Z will undo the bullet list changes
+     * ```
+     */
+    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';
+/**
+ * DocxEditor - Complete DOCX editor component
+ */
+declare const DocxEditor: React.ForwardRefExoticComponent<DocxEditorProps & React.RefAttributes<DocxEditorRef>>;
+
+/**
+ * Simple imperative API for rendering a DOCX editor into a DOM element.
+ *
+ * Returns an `EditorHandle` (from @eigenpal/docx-editor-core) that works with
+ * any framework implementation.
+ *
+ * Usage:
+ * ```ts
+ * import { renderAsync } from '@eigenpal/docx-editor-react';
+ *
+ * const editor = await renderAsync(docxBlob, document.getElementById('container'), {
+ *   readOnly: false,
+ *   showToolbar: true,
+ * });
+ *
+ * // Save the edited document
+ * const blob = await editor.save();
+ *
+ * // Clean up
+ * editor.destroy();
+ * ```
+ */
+
+/**
+ * Options for {@link renderAsync}. A subset of DocxEditorProps minus
+ * `documentBuffer` / `document` (passed as the first argument instead).
+ */
+type RenderAsyncOptions = Omit<DocxEditorProps, 'documentBuffer' | 'document'>;
+/**
+ * React-specific handle that extends the framework-agnostic EditorHandle
+ * with zoom control.
+ */
+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.
+ *
+ * @param input - DOCX data as ArrayBuffer, Uint8Array, Blob, or File
+ * @param container - DOM element to render into
+ * @param options - Editor configuration (toolbar, readOnly, callbacks, etc.)
+ * @returns A handle with save / destroy / getDocument methods
+ */
+declare function renderAsync(input: DocxInput, container: HTMLElement, options?: RenderAsyncOptions): Promise<DocxEditorHandle>;
+
+/**
+ * @eigenpal/docx-editor-react
+ *
+ * Curated root entry for the documented React editor API. Advanced surfaces
+ * stay public through explicit subpaths:
+ * - `@eigenpal/docx-editor-react/ui`
+ * - `@eigenpal/docx-editor-react/dialogs`
+ * - `@eigenpal/docx-editor-react/hooks`
+ * - `@eigenpal/docx-editor-react/plugin-api`
+ *
+ * Framework-agnostic document utilities live in `@eigenpal/docx-editor-core`.
+ * Agent/MCP surfaces live in `@eigenpal/docx-editor-agents`.
+ */
+declare const VERSION = "0.0.2";
+
+export { type DocxInput as D, type EditorMode as E, LocaleProvider as L, type RenderAsyncOptions as R, VERSION as V, DocumentAgent as a, DocxEditor as b, type DocxEditorHandle as c, type DocxEditorProps as d, type DocxEditorRef as e, type LocaleProviderProps as f, renderAsync as r, useTranslation as u };