@zeke-02/docx-editor 0.5.2 → 0.5.3

package/dist/index.d.mts

@@ -1,23 +1,19 @@
-import { R as ReactEditorPlugin } from './react-D0Pn1nww.mjs';
-export { D as DEFAULT_SELECTION_STYLE, a as DocxEditor, b as DocxEditorHandle, c as DocxEditorProps, d as DocxEditorRef, E as EditorMode, e as EditorPlugin, f as ErrorBoundary, g as ErrorBoundaryProps, h as ErrorContextValue, i as ErrorProvider, H as HIGH_CONTRAST_SELECTION_STYLE, j as HighlightRect, P as PLUGIN_HOST_STYLES, k as ParseErrorDisplay, l as ParseErrorDisplayProps, m as PluginContext, n as PluginHost, o as PluginHostProps, p as PluginHostRef, q as ReactSidebarItem, r as RenderAsyncOptions, S as SELECTION_CSS_VARS, s as SelectionHighlightConfig, t as SelectionOverlayProps, u as SelectionRange, v as SidebarItemRenderProps, T as TableSelectionState, U as UnsupportedFeatureWarning, w as UnsupportedFeatureWarningProps, x as UseAutoSaveOptions, y as UseAutoSaveReturn, z as UseClipboardOptions, A as UseClipboardReturn, B as UseSelectionHighlightOptions, C as UseSelectionHighlightReturn, F as UseTableSelectionOptions, G as UseTableSelectionReturn, I as UseWheelZoomOptions, J as UseWheelZoomReturn, Z as ZOOM_PRESETS, K as areSelectionStylesInjected, L as clampZoom, M as clearSelection, N as createSelectionChangeHandler, O as findNearestZoomPreset, Q as formatZoom, V as generateOverlayElements, W as generateSelectionCSS, X as getHighlightRectStyle, Y as getMergedSelectionRects, _ as getNextZoomPreset, $ as getPreviousZoomPreset, a0 as getSelectedText, a1 as getSelectionBoundingRect, a2 as getSelectionRects, a3 as getUserFriendlyMessage, a4 as getZoomPresets, a5 as hasActiveSelection, a6 as highlightTextRange, a7 as injectSelectionStyles, a8 as isParseError, a9 as isSelectionBackwards, aa as isSelectionWithin, ab as isZoomPreset, ac as mergeAdjacentRects, ad as normalizeSelectionDirection, ae as parseZoom, af as removeSelectionStyles, ag as renderAsync, ah as selectRange, ai as useAutoSave, aj as useClipboard, ak as useErrorNotifications, al as useSelectionHighlight, am as useTableSelection, an as useWheelZoom } from './react-D0Pn1nww.mjs';
-export { A as AgentContextOptions, C as CreateEmptyDocumentOptions, E as ExtendedSelectionContext, P as ProcessTemplateOptions, a as ProcessTemplateResult, b as SelectionContextOptions, c as blendColors, d as buildExtendedSelectionContext, e as buildSelectionContext, g as colorsEqual, h as createDocumentWithText, i as createEmptyDocument, j as createRgbColor, l as createThemeColor, m as darkenColor, n as emuToPixels, o as emuToTwips, p as executeCommand, q as executeCommands, r as formatPx, s as getAgentContext, t as getContrastingColor, u as getDocumentSummary, x as getTemplateTags, y as halfPointsToPixels, z as isBlack, B as isWhite, D as lightenColor, G as parseColorString, H as parseDocx, I as pixelsToEmu, J as pixelsToTwips, K as pointsToPixels, M as processTemplate, O as processTemplateAsBlob, Q as processTemplateDetailed, R as resolveColor, U as resolveHighlightColor, V as resolveShadingColor, W as serializeDocumentBody, X as serializeDocx, Y as serializeSectionProperties, Z as twipsToEmu, _ as twipsToPixels, $ as validateTemplate } from './documentSerializer-DtS_-oGA.mjs';
-import { T as Translations, a as TranslationKey } from './TableToolbar-YL74HNS1.mjs';
-export { C as CLIPBOARD_TYPES, b as ClipboardContent, c as ClipboardOptions, F as FontOption, d as FontPicker, e as FontPickerProps, I as INTERNAL_CLIPBOARD_TYPE, L as LocaleStrings, P as ParsedClipboardContent, f as PartialLocaleStrings, g as PrintButton, h as PrintButtonProps, i as PrintOptions, j as PrintStyles, k as TableAction, l as TableContext, m as TableSelection, n as TableSplitConfig, o as TableToolbar, p as TableToolbarProps, q as addColumn, r as addRow, s as cleanWordHtml, t as copyParagraphs, u as copyRuns, v as createClipboardHandlers, w as createTableContext, x as deleteColumn, y as deleteRow, z as formatPrintPageRange, A as getCellAt, B as getColumnCount, D as getDefaultPrintOptions, E as getTableSplitCellDialogConfig, G as handlePasteEvent, H as htmlToRuns, J as isEditorHtml, K as isPrintSupported, M as isWordHtml, N as mergeCells, O as openPrintWindow, Q as paragraphsToClipboardContent, R as parseClipboardHtml, S as parsePageRange, U as readFromClipboard, V as runsToClipboardContent, W as splitCell, X as splitTableCell, Y as triggerPrint, Z as writeToClipboard } from './TableToolbar-YL74HNS1.mjs';
-export { D as DocumentAgent, g as DocxInput, t as toArrayBuffer } from './DocumentAgent-BWflKHpH.mjs';
-export { I as InsertPosition, c as canRenderFont, a as countPageBreaks, b as createColumnBreak, d as createHorizontalRule, e as createLineBreak, f as createPageBreak, g as createPageBreakParagraph, h as createPageBreakRun, i as findPageBreaks, j as getLoadedFonts, k as hasPageBreakBefore, l as insertHorizontalRule, m as insertPageBreak, n as isBreakContent, o as isColumnBreak, p as isFontLoaded, q as isFontsLoading, r as isLineBreak, s as isPageBreak, t as loadFont, u as loadFontFromBuffer, v as loadFonts, w as onFontsLoaded, x as preloadCommonFonts, y as removePageBreak } from './insertOperations-BTH1Asas.mjs';
-export { f as AIAction, g as AIActionRequest, A as AgentCommand, h as AgentContext, i as AgentResponse, j as ApplyStyleCommand, l as BlockContent, ad as BookmarkEnd, ae as BookmarkStart, aq as BorderSpec, C as Comment, p as DeleteTextCommand, D as Document, d as DocumentBody, r as DocxPackage, E as Endnote, af as Field, ag as FooterReference, F as Footnote, t as FormatTextCommand, ah as HeaderFooter, ai as HeaderReference, H as Hyperlink, I as Image, u as InsertHyperlinkCommand, v as InsertImageCommand, w as InsertTableCommand, x as InsertTextCommand, ar as LineSpacingRule, L as ListLevel, as as NumberFormat, N as NumberingDefinitions, a as Paragraph, at as ParagraphAlignment, G as ParagraphContent, J as ParagraphContext, K as ParagraphFormatting, P as Position, R as Range, Q as Relationship, S as ReplaceTextCommand, b as Run, c as RunContent, au as Section, V as SectionProperties, W as SelectionContext, X as SetVariableCommand, aj as Shape, Y as Style, Z as StyleDefinitions, $ as SuggestedAction, e as Table, av as TableBorders, a0 as TableCell, aw as TableCellFormatting, a1 as TableRow, ak as TextBox, a2 as TextContent, T as TextFormatting, a3 as Theme, al as ThemeColorScheme, am as ThemeFont, an as ThemeFontScheme } from './agentApi-DLt94vXk.mjs';
-import * as react_jsx_runtime from 'react/jsx-runtime';
+import * as React from 'react';
 import { ReactNode, CSSProperties } from 'react';
-import { ToolbarProps } from './ui.mjs';
-export { AlignmentButtons, AlignmentButtonsProps, ColorPicker, ColorPickerMode, ColorPickerProps, ContextMenu, ContextMenuProps, DialogKeyboardShortcut, FindMatch, FindOptions, FindReplaceDialog, FindReplaceDialogProps, FindReplaceOptions, FindReplaceState, FindResult, FontSizePicker, FontSizePickerProps, HighlightOptions, HorizontalRuler, HorizontalRulerProps, HyperlinkData, HyperlinkDialog, HyperlinkDialogProps, ImageData, IndicatorPosition, IndicatorVariant, InsertImageDialog, InsertImageDialogProps, InsertSymbolDialog, InsertSymbolDialogProps, InsertTableDialog, InsertTableDialogProps, KeyboardShortcutsDialog, KeyboardShortcutsDialogProps, LineSpacingOption, LineSpacingPicker, LineSpacingPickerProps, ListButtons, ListButtonsProps, ListState, LoadingIndicator, LoadingIndicatorProps, LoadingOperation, LoadingSize, LoadingVariant, PasteOption, PasteSpecialDialog, PasteSpecialDialogProps, ResponsePreview, ResponsePreviewProps, ResponsePreviewState, ResponsiveToolbar, ResponsiveToolbarGroup, ResponsiveToolbarGroupProps, ResponsiveToolbarProps, SYMBOL_CATEGORIES, ShortcutCategory, StyleOption, StylePicker, StylePickerProps, SymbolCategory, TableBorderColorPicker, TableBorderColorPickerProps, TableBorderPicker, TableBorderPickerProps, TableBorderWidthPicker, TableBorderWidthPickerProps, TableCellFillPicker, TableCellFillPickerProps, TableConfig, TableInsertButtons, TableInsertButtonsProps, TableMergeButton, TableMergeButtonProps, TableMoreDropdown, TableMoreDropdownProps, TextContextAction, TextContextMenu, TextContextMenuItem, TextContextMenuProps, Toolbar, ToolbarButton, ToolbarGroup, ToolbarItem, ToolbarItemPriority, ToolbarSeparator, UnsavedIndicator, UnsavedIndicatorProps, UseFindReplaceReturn, UseKeyboardShortcutsDialogOptions, UseKeyboardShortcutsDialogReturn, UseLoadingOptions, UseLoadingReturn, UsePasteSpecialOptions, UsePasteSpecialReturn, UseResponsiveToolbarOptions, UseResponsiveToolbarReturn, UseTextContextMenuOptions, UseTextContextMenuReturn, UseUnsavedChangesOptions, UseUnsavedChangesReturn, ZoomControl, ZoomControlProps, calculateFitDimensions, clampTableConfig, createChangeTracker, createDefaultFindOptions, createDefaultListState, createDefaultTableConfig, createErrorResponse, createMockResponse, createSearchPattern, createToolbarItem, createToolbarItems, dataUrlToBlob, delay, escapeRegexString, findAllMatches, findInDocument, findInParagraph, formatFileSize, formatShortcutKeys, formatTableDimensions, getActionShortcut, getAllActions, getAllCategories, getAllIndicatorPositions, getAllIndicatorVariants, getAllLoadingSizes, getAllLoadingVariants, getAllPasteOptions, getCategoryLabel, getCommonShortcuts, getDefaultActions, getDefaultHighlightOptions, getDefaultPasteOption, getDefaultShortcuts, getDefaultTextContextMenuItems, getImageAcceptString, getImageDimensions, getLoadingVariantLabel, getMarginInUnits, getMatchCountText, getPasteOption, getRecommendedPriority, getRulerDimensions, getShortcutsByCategory, getSupportedImageExtensions, getSymbolCategories, getSymbolUnicodeInfo, getSymbolsByCategory, getTablePresets, getTextActionLabel, getTextActionShortcut, getVariantLabel, isActionAvailable, isEmptySearch, isPasteSpecialShortcut, isTextActionAvailable, isValidImageFile, isValidTableConfig, parseMarginFromUnits, positionToMargin, replaceAllInContent, replaceFirstInContent, scrollToMatch, searchSymbols, symbolFromCodePoint, useContextMenu, useFindReplace, useHyperlinkDialog, useInsertImageDialog, useInsertSymbolDialog, useInsertTableDialog, useKeyboardShortcutsDialog, useLoading, useLoadingOperations, usePasteSpecial, useResponsePreview, useResponsiveToolbar, useTextContextMenu, useUnsavedChanges } from './ui.mjs';
+import * as prosemirror_view from 'prosemirror-view';
+import { EditorView } from 'prosemirror-view';
 import * as prosemirror_state from 'prosemirror-state';
-import { Plugin, PluginKey } from 'prosemirror-state';
-import { DecorationSet, EditorView } from 'prosemirror-view';
-export { b as CommandHandler, d as CommandResult, C as CorePlugin, e as McpSession, M as McpToolDefinition, i as McpToolHandler, j as McpToolResult, k as PluginCommand, b as PluginCommandHandler } from './types-UDsUq8D3.mjs';
-export { P as PluginRegistry, p as pluginRegistry, r as registerPlugins } from './registry-CWBKYlNW.mjs';
-export { docxtemplaterPlugin } from './core-plugins-reexport.mjs';
-export { d as AutoSaveStatus, e as ClipboardSelection, h as ErrorNotification, i as ErrorSeverity, j as PanelConfig, k as PluginPanelProps, l as PositionCoordinates, R as RenderedDomContext, m as SavedDocumentData, F as SidebarItem, G as SidebarItemContext, T as TABLE_DATA_ATTRIBUTES, p as createSelectionFromDOM, t as formatLastSaveTime, u as formatStorageSize, v as getAutoSaveStatusLabel, w as getAutoSaveStorageSize, x as getSelectionRuns, z as isAutoSaveSupported } from './ClipboardManager-V3aaMnWE.mjs';
+import { EditorState, Transaction } from 'prosemirror-state';
+import { D as Document, T as Theme } from './document-Di1qGqLS.mjs';
+import { S as StyleInfo, A as AgentContext, P as Position, R as Range, a as AgentCommand, F as FontOption, b as PrintOptions } from './agentApi-C41hiW-n.mjs';
+import { R as RenderedDomContext, a as ReactSidebarItem } from './types-Bd_YzkhG.mjs';
+import { T as TextFormatting, P as ParagraphFormatting, C as Comment } from './content-B2MzIMwA.mjs';
+import { T as Translations, a as TranslationKey } from './types-DZUhB7Ao.mjs';
+export { L as LocaleStrings, P as PartialLocaleStrings } from './types-DZUhB7Ao.mjs';
+import { E as EditorHandle } from './types-CkfDgB0O.mjs';
+import * as react_jsx_runtime from 'react/jsx-runtime';
 import 'prosemirror-model';
+import '@eigenpal/docx-editor-i18n/en.json';
 
 interface LocaleProviderProps {
     i18n?: Translations;
@@ -29,564 +25,1098 @@ declare function useTranslation(): {
 };
 
 /**
- * Keyboard Navigation Utilities
+ * Selective Save Module
  *
- * Provides enhanced keyboard navigation for the editor:
- * - Ctrl+Left/Right: Move by word
- * - Home/End: Move to start/end of line
- * - Ctrl+Home/End: Move to start/end of document
- * - Ctrl+Shift+Left/Right: Select by word
- * - Shift+Home/End: Select to start/end of line
- */
-/**
- * Navigation direction
- */
-type NavigationDirection = 'left' | 'right' | 'up' | 'down';
-/**
- * Navigation unit
- */
-type NavigationUnit = 'character' | 'word' | 'line' | 'paragraph' | 'document';
-/**
- * Keyboard navigation action
- */
-interface NavigationAction {
-    /** Direction to navigate */
-    direction: NavigationDirection;
-    /** Unit of movement */
-    unit: NavigationUnit;
-    /** Whether to extend selection */
-    extend: boolean;
-}
-/**
- * Keyboard shortcut definition
+ * 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 KeyboardShortcut {
-    key: string;
-    ctrlKey?: boolean;
-    metaKey?: boolean;
-    shiftKey?: boolean;
-    altKey?: boolean;
+
+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;
 }
+
 /**
- * Check if a character is a word character (letter, digit, or underscore)
- */
-declare function isWordCharacter(char: string): boolean;
-/**
- * Check if a character is whitespace
- */
-declare function isWhitespace(char: string): boolean;
-/**
- * Check if a character is a punctuation character
+ * 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.
  */
-declare function isPunctuation(char: string): boolean;
 /**
- * Find the start of the current or previous word
+ * 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">`
  */
-declare function findWordStart(text: string, position: number): number;
+type DocxInput = ArrayBuffer | Uint8Array | Blob | File;
+
 /**
- * Find the end of the current or next word
+ * 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.
  */
-declare function findWordEnd(text: string, position: number): number;
+
 /**
- * Find the next word start (for Ctrl+Right navigation)
+ * Options for inserting text
  */
-declare function findNextWordStart(text: string, position: number): number;
+interface InsertTextOptions {
+    /** Text formatting */
+    formatting?: TextFormatting;
+}
 /**
- * Find the previous word start (for Ctrl+Left navigation)
+ * Options for inserting table
  */
-declare function findPreviousWordStart(text: string, position: number): number;
+interface InsertTableOptions {
+    /** Table data (2D array of strings) */
+    data?: string[][];
+    /** Whether first row is a header */
+    hasHeader?: boolean;
+}
 /**
- * Find the start of the current line in a text node
- * Uses visual line detection based on bounding rectangles
+ * Options for inserting image
  */
-declare function findVisualLineStart(container: Node, offset: number): {
-    node: Node;
-    offset: number;
-} | null;
+interface InsertImageOptions {
+    /** Image width in pixels */
+    width?: number;
+    /** Image height in pixels */
+    height?: number;
+    /** Alt text for accessibility */
+    alt?: string;
+}
 /**
- * Find the end of the current line in a text node
- * Uses visual line detection based on bounding rectangles
+ * Options for inserting hyperlink
  */
-declare function findVisualLineEnd(container: Node, offset: number): {
-    node: Node;
-    offset: number;
-} | null;
+interface InsertHyperlinkOptions {
+    /** Display text (overrides selected text) */
+    displayText?: string;
+    /** Tooltip on hover */
+    tooltip?: string;
+}
 /**
- * Get the current selection info
+ * Formatted text segment
  */
-declare function getSelectionInfo(): {
-    node: Node;
-    offset: number;
-    anchorNode: Node | null;
-    anchorOffset: number;
-    focusNode: Node | null;
-    focusOffset: number;
-    isCollapsed: boolean;
+interface FormattedTextSegment {
+    /** Text content */
     text: string;
-} | null;
-/**
- * Set the selection to a specific position
- */
-declare function setSelectionPosition(node: Node, offset: number): void;
-/**
- * Extend selection to a specific position
- */
-declare function extendSelectionTo(node: Node, offset: number): void;
-/**
- * Move selection by word in a text node
- */
-declare function moveByWord(direction: 'left' | 'right', extend?: boolean): boolean;
-/**
- * Move to start/end of line
- */
-declare function moveToLineEdge(edge: 'start' | 'end', extend?: boolean): boolean;
-/**
- * Parse a keyboard event into a navigation action
- */
-declare function parseNavigationAction(event: KeyboardEvent): NavigationAction | null;
+    /** Applied formatting */
+    formatting?: TextFormatting;
+    /** Is part of a hyperlink */
+    isHyperlink?: boolean;
+    /** Hyperlink URL if applicable */
+    hyperlinkUrl?: string;
+}
 /**
- * Handle a keyboard navigation event
- * Returns true if the event was handled
+ * 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 function handleNavigationKey(event: KeyboardEvent, options?: {
-    onDocumentStart?: () => void;
-    onDocumentEnd?: () => void;
-}): boolean;
+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;
+}
+
 /**
- * Check if an event is a navigation key event
+ * Selection State Utilities
+ *
+ * Extracts selection state from ProseMirror for toolbar integration.
  */
-declare function isNavigationKey(event: KeyboardEvent): boolean;
+
 /**
- * Expand selection to word boundaries
- * Used for double-click word selection
+ * Selection state for toolbar integration
  */
-declare function expandSelectionToWord(): boolean;
+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;
+}
+
 /**
- * Get the word at the current cursor position
+ * Layout Engine Types
+ *
+ * Core types for the paginated layout engine.
+ * Converts document blocks + measurements into positioned fragments on pages.
  */
-declare function getWordAtCursor(): string | null;
 /**
- * Check if a keyboard event matches a shortcut definition
+ * Unique identifier for a block in the document.
+ * Format: typically `${index}-${type}` or just the block index.
  */
-declare function matchesShortcut(event: KeyboardEvent, shortcut: KeyboardShortcut): boolean;
+type BlockId = string | number;
 /**
- * Common navigation shortcuts
+ * Base fragment properties common to all fragment types.
  */
-declare const NAVIGATION_SHORTCUTS: {
-    readonly wordLeft: KeyboardShortcut;
-    readonly wordRight: KeyboardShortcut;
-    readonly selectWordLeft: KeyboardShortcut;
-    readonly selectWordRight: KeyboardShortcut;
-    readonly lineStart: KeyboardShortcut;
-    readonly lineEnd: KeyboardShortcut;
-    readonly selectToLineStart: KeyboardShortcut;
-    readonly selectToLineEnd: KeyboardShortcut;
-    readonly documentStart: KeyboardShortcut;
-    readonly documentEnd: KeyboardShortcut;
-    readonly selectToDocumentStart: KeyboardShortcut;
-    readonly selectToDocumentEnd: KeyboardShortcut;
+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;
 };
 /**
- * Get a human-readable description of a shortcut
- */
-declare function describeShortcut(shortcut: KeyboardShortcut): string;
-/**
- * Get all navigation shortcuts with descriptions
- */
-declare function getNavigationShortcutDescriptions(): Array<{
-    action: string;
-    shortcut: string;
-}>;
-
-/**
- * Find word boundaries around a position in text
- * Returns [startIndex, endIndex] inclusive start, exclusive end
- */
-declare function findWordBoundaries(text: string, position: number): [number, number];
-/**
- * Get the word at a position in text
+ * A paragraph fragment positioned on a page.
+ * May span only part of the paragraph's lines if split across pages.
  */
-declare function getWordAt(text: string, position: number): string;
+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;
+};
 /**
- * Word selection result
+ * A table fragment positioned on a page.
+ * May span only part of the table's rows if split across pages.
  */
-interface WordSelectionResult {
-    /** The selected word */
-    word: string;
-    /** Start index in the text (inclusive) */
-    startIndex: number;
-    /** End index in the text (exclusive) */
-    endIndex: number;
-}
+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;
+};
 /**
- * Find the word at a position and return detailed info
+ * An image fragment positioned on a page.
  */
-declare function findWordAt(text: string, position: number): WordSelectionResult;
+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;
+};
 /**
- * Select a word at the current cursor position using the browser's native APIs.
- * This works reliably across different browsers and handles contentEditable well.
+ * A text box fragment positioned on a page.
  */
-declare function selectWordAtCursor(): boolean;
+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;
+};
 /**
- * Select a word in a specific text node at the given offset
+ * Union of all fragment types.
  */
-declare function selectWordInTextNode(textNode: Text, offset: number): boolean;
+type Fragment = ParagraphFragment | TableFragment | ImageFragment | TextBoxFragment;
 /**
- * Expand the current selection to word boundaries.
- * If there's a collapsed selection (cursor), selects the word at cursor.
- * If there's an existing selection, expands to include complete words.
+ * Page margin configuration.
  */
-declare function expandSelectionToWordBoundaries(): boolean;
+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;
+};
 /**
- * Select the entire paragraph containing the current selection.
- * Looks for the nearest element with [data-paragraph-index] attribute.
+ * A rendered page containing positioned fragments.
  */
-declare function selectParagraphAtCursor(): boolean;
+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;
+};
 /**
- * Handle click event for multi-click detection.
- * Call this in your click handler.
- * Returns the click count (1 = single, 2 = double, 3 = triple).
+ * Column layout configuration.
  */
-declare function handleClickForMultiClick(event: MouseEvent): number;
+type ColumnLayout = {
+    count: number;
+    gap: number;
+    equalWidth?: boolean;
+    /** Draw vertical separator line between columns (w:sep). */
+    separator?: boolean;
+};
 /**
- * Create a double-click handler that selects words.
- * Returns a function that should be called on dblclick events.
+ * Header/footer layout for a specific type.
  */
-declare function createDoubleClickWordSelector(): (event: MouseEvent) => void;
+type HeaderFooterLayout = {
+    height: number;
+    fragments: Fragment[];
+};
 /**
- * Create a triple-click handler that selects paragraphs.
- * This uses our custom click counting since browsers have inconsistent triple-click.
+ * Final layout output ready for rendering/painting.
  */
-declare function createTripleClickParagraphSelector(): (event: MouseEvent) => void;
+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 AgentPanelProps {
-    /** Header title. Defaults to `t('agentPanel.defaultTitle')`. */
-    title?: string;
-    /** Header icon node. Defaults to a sparkle SVG. */
-    icon?: ReactNode;
-    /** Controlled width in pixels. Omit for uncontrolled (internal state + localStorage). */
-    width?: number;
-    /** Default width when uncontrolled. */
-    defaultWidth?: number;
-    /** Min drag width. */
-    minWidth?: number;
-    /** Max drag width. */
-    maxWidth?: number;
-    /** Width change callback (drag end and intermediate). */
-    onWidthChange?: (w: number) => void;
-    /** Header close button click. Omit to hide the close button. */
-    onClose?: () => void;
-    /** Panel content. Render whatever you want — a chat, tabs, settings, anything. */
-    children: ReactNode;
-    /** Optional class on the outer wrapper. */
-    className?: string;
+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;
     /**
-     * When `true`, the panel collapses to zero width with an ease-out
-     * transition (the children are still mounted so chat state survives
-     * close/reopen). The DocxEditor wrapper passes this when the user
-     * toggles the panel — kept off by default for standalone usage.
+     * 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.
      */
-    closed?: boolean;
+    scrollToPage(pageNumber: number): void;
 }
-declare function AgentPanel({ title, icon, width: controlledWidth, defaultWidth, minWidth, maxWidth, onWidthChange, onClose, children, className, closed, }: AgentPanelProps): react_jsx_runtime.JSX.Element;
 
-/** A single tool call the agent made — shown in the collapsible timeline. */
-interface AgentToolCall {
-    /** Stable id for keying. */
-    id: string;
-    /** Tool name (e.g. `read_document`, `add_comment`). */
-    name: string;
-    /** JSON-able input the agent passed. Rendered in the expanded view. */
-    input?: unknown;
-    /** Result text or summary. Set after the call completes. */
-    result?: string;
-    /** Set when the call errored — surfaces in the timeline as failed. */
-    error?: string;
-    /** `running` while in flight, `done` on success, `error` on failure. */
-    status: 'running' | 'done' | 'error';
-}
-interface AgentMessage {
-    id: string;
-    role: 'user' | 'assistant';
-    text: string;
+/**
+ * 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[];
     /**
-     * Tool calls the assistant made for this turn, in order. The timeline
-     * stays expanded while `status === 'streaming'` and auto-collapses to
-     * an "N steps" summary when the message hits `status === 'done'`.
+     * 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.
      */
-    toolCalls?: AgentToolCall[];
-    /** `streaming` while the model is still calling tools / writing text; `done` once the turn is final. */
-    status?: 'streaming' | 'done';
-}
-interface AgentChatLogProps {
-    messages: AgentMessage[];
-    /** Render thinking dots at the bottom of the list. */
-    loading?: boolean;
-    /** Render an error bubble after the last message. */
-    error?: string | null;
-    /** Shown when there are no messages and not loading. */
-    emptyState?: ReactNode;
-    /** Auto-scroll to bottom on new messages / loading toggles. Default: true. */
-    autoScroll?: boolean;
-    /**
-     * Map a tool name to a friendly label for the per-message timeline.
-     * Pass `getToolDisplayName` from `@eigenpal/docx-editor-agents/react` to
-     * use the toolkit's registry-aware labels (e.g. "Adding comment").
-     */
-    humanizeToolName?: (name: string) => string;
-    /** Cap the tool-call timeline to this many recent rows. Default 3. */
-    maxVisibleCalls?: number;
+    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;
-}
-interface AgentTimelineProps {
-    /** Tool calls in chronological order. */
-    toolCalls: AgentToolCall[];
+    /** 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;
     /**
-     * Whether the parent assistant turn is still streaming. While true, the
-     * timeline is forced expanded and shows a spinner; on false it
-     * auto-collapses to an "N steps" summary unless the user expanded it.
+     * 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' }]}
      */
-    streaming?: boolean;
+    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;
     /**
-     * Cap the number of rendered call rows — older entries collapse into a
-     * "+N earlier steps" header. Default 3.
+     * 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.
      */
-    maxVisibleCalls?: number;
+    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;
     /**
-     * Map a tool name to a friendly label. Defaults to a sentence-case
-     * conversion of the snake_case name. Pass `getToolDisplayName` from
-     * `@eigenpal/docx-editor-agents/react` to use the toolkit's registry.
+     * 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.
      */
-    humanizeName?: (name: string) => string;
-}
-/**
- * Collapsible timeline of an assistant turn's tool calls. Lives above the
- * assistant text bubble. Auto-collapses when the turn finishes; click the
- * summary row to re-expand.
- */
-declare function AgentTimeline({ toolCalls, streaming, maxVisibleCalls, humanizeName, }: AgentTimelineProps): react_jsx_runtime.JSX.Element | null;
-declare function AgentChatLog({ messages, loading, error, emptyState, autoScroll, humanizeToolName, maxVisibleCalls, className, style, }: AgentChatLogProps): react_jsx_runtime.JSX.Element;
-interface AgentComposerProps {
-    value: string;
-    onChange: (next: string) => void;
-    onSubmit: () => void;
-    disabled?: boolean;
-    placeholder?: string;
-    /** Small text under the input — typically a scope reminder. */
-    footnote?: ReactNode;
-    className?: string;
-}
-declare function AgentComposer({ value, onChange, onSubmit, disabled, placeholder, footnote, className, }: AgentComposerProps): react_jsx_runtime.JSX.Element;
-interface AgentSuggestionChipProps {
-    label: string;
-    onClick: () => void;
-    disabled?: boolean;
-}
-declare function AgentSuggestionChip({ label, onClick, disabled }: AgentSuggestionChipProps): react_jsx_runtime.JSX.Element;
-
-/**
- * Props for the EditorToolbar compound component.
- * Extends ToolbarProps with title bar-specific fields.
- */
-interface EditorToolbarProps extends ToolbarProps {
-}
-
-interface LogoProps {
-    children: ReactNode;
-}
-declare function Logo({ children }: LogoProps): react_jsx_runtime.JSX.Element;
-interface DocumentNameProps {
-    value: string;
-    onChange?: (value: string) => void;
-    placeholder?: string;
-    editable?: boolean;
-}
-declare function DocumentName({ value, onChange, placeholder, editable }: DocumentNameProps): react_jsx_runtime.JSX.Element;
-interface TitleBarRightProps {
-    children: ReactNode;
-}
-declare function TitleBarRight({ children }: TitleBarRightProps): react_jsx_runtime.JSX.Element;
-declare function MenuBar(): react_jsx_runtime.JSX.Element;
-interface TitleBarProps {
-    children: ReactNode;
+    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;
+    };
 }
 /**
- * TitleBar layout (Google Docs style):
- *
- *   ┌──────────┬────────────────────────────┬──────────────────┐
- *   │          │ Document Name              │                  │
- *   │  Logo    │                            │  Right Actions   │
- *   │          │ File  Format  Insert       │                  │
- *   └──────────┴────────────────────────────┴──────────────────┘
- *
- * Logo and TitleBarRight span full height. DocumentName + MenuBar
- * stack vertically in the center column.
+ * DocxEditor ref interface
  */
-declare function TitleBar({ children }: TitleBarProps): react_jsx_runtime.JSX.Element;
-
-interface FormattingBarProps extends ToolbarProps {
-    /** Custom toolbar items to render at the end */
-    children?: ReactNode;
-    /** When true, renders with display:contents so children flow in parent flex container */
-    inline?: boolean;
+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';
 /**
- * Icon-based formatting toolbar — undo/redo, zoom, styles, fonts,
- * bold/italic/underline, colors, alignment, lists, table/image context, clear formatting.
+ * DocxEditor - Complete DOCX editor component
  */
-declare function FormattingBar(explicitProps: FormattingBarProps): react_jsx_runtime.JSX.Element;
+declare const DocxEditor: React.ForwardRefExoticComponent<DocxEditorProps & React.RefAttributes<DocxEditorRef>>;
 
 /**
- * EditorToolbar — Google Docs-style 2-level compound component.
+ * Simple imperative API for rendering a DOCX editor into a DOM element.
  *
- * Usage:
- *   <EditorToolbar {...toolbarProps}>
- *     <EditorToolbar.TitleBar>
- *       <EditorToolbar.Logo><MyIcon /></EditorToolbar.Logo>
- *       <EditorToolbar.DocumentName value={name} onChange={setName} />
- *       <EditorToolbar.MenuBar />
- *       <EditorToolbar.TitleBarRight>
- *         <button>Save</button>
- *       </EditorToolbar.TitleBarRight>
- *     </EditorToolbar.TitleBar>
- *     <EditorToolbar.FormattingBar />
- *   </EditorToolbar>
- */
-
-interface EditorToolbarComponent {
-    (props: EditorToolbarProps & {
-        children: ReactNode;
-    }): React.JSX.Element;
-    TitleBar: typeof TitleBar;
-    Logo: typeof Logo;
-    DocumentName: typeof DocumentName;
-    MenuBar: typeof MenuBar;
-    TitleBarRight: typeof TitleBarRight;
-    FormattingBar: typeof FormattingBar;
-}
-declare const EditorToolbar: EditorToolbarComponent;
-
-/**
- * Template tag types
- */
-type TagType = 'variable' | 'sectionStart' | 'sectionEnd' | 'invertedStart' | 'raw';
-/**
- * A found template tag
- */
-interface TemplateTag {
-    id: string;
-    type: TagType;
-    name: string;
-    rawTag: string;
-    from: number;
-    to: number;
-    /** For sections: nested variable names */
-    nestedVars?: string[];
-    /** True if this variable is inside a section (shown in section's nested vars) */
-    insideSection?: boolean;
-}
-/**
- * Plugin state
- */
-interface TemplatePluginState$1 {
-    tags: TemplateTag[];
-    decorations: DecorationSet;
-    hoveredId?: string;
-    selectedId?: string;
-}
-/**
- * Plugin key
- */
-declare const templatePluginKey: PluginKey<TemplatePluginState$1>;
-/**
- * Create the template plugin
- */
-declare function createTemplatePlugin(): Plugin<TemplatePluginState$1>;
-/**
- * Get tags from editor state
- */
-declare function getTemplateTags(state: prosemirror_state.EditorState): TemplateTag[];
-/**
- * Set hovered tag
- */
-declare function setHoveredElement(view: EditorView, id: string | undefined): void;
-/**
- * Set selected tag
- */
-declare function setSelectedElement(view: EditorView, id: string | undefined): void;
-/**
- * CSS styles for template decorations
- */
-declare const TEMPLATE_DECORATION_STYLES = "\n.docx-template-tag {\n  cursor: pointer;\n  transition: background-color 0.1s;\n}\n\n.docx-template-tag:hover,\n.docx-template-tag.hovered {\n  filter: brightness(0.95);\n}\n\n.docx-template-tag.selected {\n  box-shadow: 0 0 0 2px rgba(59, 130, 246, 0.5);\n}\n";
-
-/**
- * Template Plugin
+ * Returns an `EditorHandle` (from @eigenpal/docx-editor-core) that works with
+ * any framework implementation.
  *
- * Docxtemplater template support as a plugin for the DOCX Editor.
+ * Usage:
+ * ```ts
+ * import { renderAsync } from '@eigenpal/docx-editor-react';
  *
- * Features:
- * - Full docxtemplater syntax detection (variables, loops, conditionals)
- * - Sidebar annotation chips showing template structure (via getSidebarItems)
- * - Differentiated visual highlighting by element type
+ * const editor = await renderAsync(docxBlob, document.getElementById('container'), {
+ *   readOnly: false,
+ *   showToolbar: true,
+ * });
  *
- * @example
- * ```tsx
- * import { PluginHost } from '@docx-editor/plugin-api';
- * import { templatePlugin } from '@docx-editor/plugins/template';
+ * // Save the edited document
+ * const blob = await editor.save();
  *
- * function MyEditor() {
- *   return (
- *     <PluginHost plugins={[templatePlugin]}>
- *       <DocxEditor document={doc} onChange={handleChange} />
- *     </PluginHost>
- *   );
- * }
+ * // Clean up
+ * editor.destroy();
  * ```
  */
 
-interface TemplatePluginState {
-    tags: TemplateTag[];
-    hoveredId?: string;
-    selectedId?: string;
-}
 /**
- * Create the template plugin instance.
+ * Options for {@link renderAsync}. A subset of DocxEditorProps minus
+ * `documentBuffer` / `document` (passed as the first argument instead).
  */
-declare function createPlugin(_options?: {
-    /** @deprecated — panel is no longer used; template chips render in the unified sidebar */
-    defaultCollapsed?: boolean;
-    /** @deprecated */
-    panelPosition?: 'left' | 'right';
-    /** @deprecated */
-    panelWidth?: number;
-}): ReactEditorPlugin<TemplatePluginState>;
+type RenderAsyncOptions = Omit<DocxEditorProps, 'documentBuffer' | 'document'>;
 /**
- * Default template plugin instance.
+ * React-specific handle that extends the framework-agnostic EditorHandle
+ * with zoom control.
  */
-declare const templatePlugin: ReactEditorPlugin<TemplatePluginState>;
-
+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;
+}
 /**
- * @eigenpal/docx-js-editor
+ * Render a DOCX editor into a container element.
  *
- * A complete WYSIWYG DOCX editor with full Microsoft Word fidelity.
+ * @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
  *
- * Features:
- * - Full text and paragraph formatting
- * - Tables, images, shapes, text boxes
- * - Hyperlinks, bookmarks, fields
- * - Footnotes, lists, headers/footers
- * - Page layout with margins and columns
- * - DocumentAgent API for programmatic editing
- * - Template variable substitution
- * - AI-powered context menu
+ * 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`
  *
- * CSS Styles:
- * For optimal cursor visibility and selection highlighting, import the editor styles:
- * ```
- * import '@eigenpal/docx-js-editor/styles/editor.css';
- * ```
+ * 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 { AgentChatLog, type AgentChatLogProps, AgentComposer, type AgentComposerProps, type AgentMessage, AgentPanel, type AgentPanelProps, AgentSuggestionChip, type AgentSuggestionChipProps, AgentTimeline, type AgentTimelineProps, type AgentToolCall, type DocumentNameProps, EditorToolbar, type EditorToolbarProps, FormattingBar, type FormattingBarProps, type KeyboardShortcut, LocaleProvider, type LocaleProviderProps, type LogoProps, NAVIGATION_SHORTCUTS, type NavigationAction, type NavigationDirection, type NavigationUnit, TEMPLATE_DECORATION_STYLES, type TagType, type TemplateTag, type TitleBarProps, type TitleBarRightProps, ToolbarProps, TranslationKey, Translations, VERSION, type WordSelectionResult, createDoubleClickWordSelector, createPlugin as createTemplatePlugin, createTemplatePlugin as createTemplateProseMirrorPlugin, createTripleClickParagraphSelector, describeShortcut, expandSelectionToWord, expandSelectionToWordBoundaries, extendSelectionTo, findNextWordStart, findPreviousWordStart, findVisualLineEnd, findVisualLineStart, findWordAt, findWordBoundaries, findWordEnd, findWordStart, getNavigationShortcutDescriptions, getSelectionInfo, getTemplateTags as getTemplatePluginTags, getWordAt, getWordAtCursor, handleClickForMultiClick, handleNavigationKey, isNavigationKey, isPunctuation, isWhitespace, isWhitespace as isWhitespaceChar, isWordCharacter as isWordChar, isWordCharacter, matchesShortcut, moveByWord, moveToLineEdge, parseNavigationAction, selectParagraphAtCursor, selectWordAtCursor, selectWordInTextNode, setHoveredElement, setSelectedElement, setSelectionPosition, templatePlugin, templatePluginKey, useTranslation };
+export { DocxEditor, type DocxEditorHandle, type DocxEditorProps, type DocxEditorRef, type EditorMode, LocaleProvider, type LocaleProviderProps, type RenderAsyncOptions, TranslationKey, Translations, VERSION, renderAsync, useTranslation };