@stll/folio-react 0.12.1 → 0.12.3

package/dist/{renderAsync-D2OJupOm.d.ts → renderAsync-CH8S7yqU.d.ts}

@@ -17,15 +17,19 @@ import { ColorValue, Document, ParagraphAlignment, SdtProperties, SectionPropert
 import { Comment } from "@stll/folio-core/types/content";
 import { DocxInput } from "@stll/folio-core/utils/docxInput";
 import { ScrollToParaIdOptions } from "@stll/folio-core/paged-layout/paragraphFlash";
+import "@stll/folio-core/controller/noteEditorManager";
 import { Layout } from "@stll/folio-core/layout-engine/types";
+import "@stll/folio-core/prosemirror/extensions/ExtensionManager";
+import "@stll/folio-core/controller/hiddenEditorManager";
 import { Checkbox } from "@base-ui/react/checkbox";
 import { Dialog } from "@base-ui/react/dialog";
 import { Menu } from "@base-ui/react/menu";
 import { Popover } from "@base-ui/react/popover";
 import { Select } from "@base-ui/react/select";
+import "@stll/folio-core/managers/DocumentLoaderManager";
+import "@stll/folio-core/managers/HistoryManager";
 import { EditorMode } from "@stll/folio-core/managers/EditorModeManager";
 import { TableAction } from "@stll/folio-core/utils/tableOperations";
-
 //#region src/paged-editor/hostFonts.d.ts
 /**
  * Host-app custom fonts — the `fonts` prop on `DocxEditor`.
@@ -44,19 +48,29 @@ import { TableAction } from "@stll/folio-core/utils/tableOperations";
  * editor. Multiple entries can share `family` to register distinct weights.
  */
 type FontDefinition = {
-  /** CSS `font-family` name to expose; match the family your documents reference. */family: string; /** URL to the font file (woff2, woff, ttf, or otf). */
-  src: string; /** CSS `font-weight` for this face (a number like `700`, or a keyword). Defaults to `normal`. */
-  weight?: number | string; /** CSS `font-style` for this face (for example `italic`). Defaults to `normal`. */
+  /** CSS `font-family` name to expose; match the family your documents reference. */
+  family: string;
+  /** URL to the font file (woff2, woff, ttf, or otf). */
+  src: string;
+  /** CSS `font-weight` for this face (a number like `700`, or a keyword). Defaults to `normal`. */
+  weight?: number | string;
+  /** CSS `font-style` for this face (for example `italic`). Defaults to `normal`. */
   style?: string;
 };
 //#endregion
 //#region src/paged-editor/PagedEditor.d.ts
 type PagedEditorRef = {
-  /** The headless editor controller (imperative API + events; Seam 6). */getEditor: () => FolioEditor; /** Get the current document. */
-  getDocument: () => Document | null; /** Get the ProseMirror EditorState. */
-  getState: () => EditorState | null; /** Get the ProseMirror EditorView. */
-  getView: () => EditorView | null; /** Get the active body, header/footer, or note-story view. */
-  getActiveView: () => EditorView | null; /** Close the visible note story, if one is active. */
+  /** The headless editor controller (imperative API + events; Seam 6). */
+  getEditor: () => FolioEditor;
+  /** Get the current document. */
+  getDocument: () => Document | null;
+  /** Get the ProseMirror EditorState. */
+  getState: () => EditorState | null;
+  /** Get the ProseMirror EditorView. */
+  getView: () => EditorView | null;
+  /** Get the active body, header/footer, or note-story view. */
+  getActiveView: () => EditorView | null;
+  /** Close the visible note story, if one is active. */
   closeNoteStory: () => void;
   /**
    * Look up the persistent hidden HF EditorView by `rId`. Returns null when
@@ -71,19 +85,32 @@ type PagedEditorRef = {
    */
   ensureView: (options?: {
     focus?: boolean;
-  }) => void; /** 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; /** Check whether undo is available. */
-  canUndo: () => boolean; /** Check whether redo is available. */
-  canRedo: () => 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 the visible pages to bring a page into view. */
+  }) => void;
+  /** 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;
+  /** Check whether undo is available. */
+  canUndo: () => boolean;
+  /** Check whether redo is available. */
+  canRedo: () => 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 the visible pages to bring a page into view. */
   scrollToPage: (pageNumber: number) => void;
   /**
    * Scroll the paginated view to the paragraph with the given Word `w14:paraId`.
@@ -316,9 +343,12 @@ type FolioDatePickerPopoverProps = {
  */
 type OutlineItem = {
   id: string;
-  label: string; /** Nesting depth; drives indent + tick taper. */
-  level: number; /** Optional trailing annotation in the panel (e.g. a page number). */
-  meta?: string; /** Optional CSS custom-property name colouring this entry. */
+  label: string;
+  /** Nesting depth; drives indent + tick taper. */
+  level: number;
+  /** Optional trailing annotation in the panel (e.g. a page number). */
+  meta?: string;
+  /** Optional CSS custom-property name colouring this entry. */
   color?: string;
 };
 /**
@@ -350,10 +380,7 @@ type FolioUIComponents = {
   DatePickerPopover: ComponentType<FolioDatePickerPopoverProps>;
   OutlineRail: ComponentType<FolioOutlineRailProps>;
 };
-declare function FolioUIProvider({
-  components,
-  children
-}: {
+declare function FolioUIProvider({ components, children }: {
   components?: Partial<FolioUIComponents> | undefined;
   children: ReactNode;
 }): import("react").JSX.Element;
@@ -386,21 +413,37 @@ type ListState = {
  * Current formatting state of the selection
  */
 type SelectionFormatting = {
-  /** Whether selected text is bold */bold?: boolean | undefined; /** Whether selected text is italic */
-  italic?: boolean | undefined; /** Whether selected text is underlined */
-  underline?: boolean | undefined; /** Whether selected text has strikethrough */
-  strike?: boolean | undefined; /** Whether selected text is superscript */
-  superscript?: boolean | undefined; /** Whether selected text is subscript */
-  subscript?: boolean | undefined; /** Font family of selected text */
-  fontFamily?: string | undefined; /** Font size of selected text (in half-points) */
-  fontSize?: number | undefined; /** Text color */
-  color?: string | undefined; /** Highlight color */
-  highlight?: string | undefined; /** Paragraph alignment */
-  alignment?: ParagraphAlignment | undefined; /** List state of the current paragraph */
-  listState?: ListState | undefined; /** Line spacing in twips (OOXML value, 240 = single spacing) */
-  lineSpacing?: number | undefined; /** Paragraph style ID */
-  styleId?: string | undefined; /** Paragraph left indentation in twips */
-  indentLeft?: number | undefined; /** Whether the paragraph is RTL (bidi) */
+  /** Whether selected text is bold */
+  bold?: boolean | undefined;
+  /** Whether selected text is italic */
+  italic?: boolean | undefined;
+  /** Whether selected text is underlined */
+  underline?: boolean | undefined;
+  /** Whether selected text has strikethrough */
+  strike?: boolean | undefined;
+  /** Whether selected text is superscript */
+  superscript?: boolean | undefined;
+  /** Whether selected text is subscript */
+  subscript?: boolean | undefined;
+  /** Font family of selected text */
+  fontFamily?: string | undefined;
+  /** Font size of selected text (in half-points) */
+  fontSize?: number | undefined;
+  /** Text color */
+  color?: string | undefined;
+  /** Highlight color */
+  highlight?: string | undefined;
+  /** Paragraph alignment */
+  alignment?: ParagraphAlignment | undefined;
+  /** List state of the current paragraph */
+  listState?: ListState | undefined;
+  /** Line spacing in twips (OOXML value, 240 = single spacing) */
+  lineSpacing?: number | undefined;
+  /** Paragraph style ID */
+  styleId?: string | undefined;
+  /** Paragraph left indentation in twips */
+  indentLeft?: number | undefined;
+  /** Whether the paragraph is RTL (bidi) */
   bidi?: boolean | undefined;
 };
 /**
@@ -434,56 +477,95 @@ type FormattingAction = "bold" | "italic" | "underline" | "strikethrough" | "sup
  * Props for the Toolbar component
  */
 type ToolbarProps = {
-  /** Current formatting of the selection */currentFormatting?: SelectionFormatting | undefined; /** Callback when a formatting action is triggered */
-  onFormat?: ((action: FormattingAction) => void) | undefined; /** Callback for undo action */
-  onUndo?: (() => void) | undefined; /** Callback for redo action */
-  onRedo?: (() => void) | undefined; /** Whether undo is available */
-  canUndo?: boolean | undefined; /** Whether redo is available */
-  canRedo?: boolean | undefined; /** Whether the toolbar is disabled */
-  disabled?: boolean | undefined; /** Additional CSS class name */
-  className?: string | undefined; /** Additional inline styles */
-  style?: CSSProperties | undefined; /** Whether to enable keyboard shortcuts (default: true) */
-  enableShortcuts?: boolean | undefined; /** Ref to the editor container for keyboard events */
-  editorRef?: React$1.RefObject<HTMLElement | null> | undefined; /** Custom toolbar items to render */
-  children?: ReactNode | undefined; /** Whether to show font family picker (default: true) */
+  /** Current formatting of the selection */
+  currentFormatting?: SelectionFormatting | undefined;
+  /** Callback when a formatting action is triggered */
+  onFormat?: ((action: FormattingAction) => void) | undefined;
+  /** Callback for undo action */
+  onUndo?: (() => void) | undefined;
+  /** Callback for redo action */
+  onRedo?: (() => void) | undefined;
+  /** Whether undo is available */
+  canUndo?: boolean | undefined;
+  /** Whether redo is available */
+  canRedo?: boolean | undefined;
+  /** Whether the toolbar is disabled */
+  disabled?: boolean | undefined;
+  /** Additional CSS class name */
+  className?: string | undefined;
+  /** Additional inline styles */
+  style?: CSSProperties | undefined;
+  /** Whether to enable keyboard shortcuts (default: true) */
+  enableShortcuts?: boolean | undefined;
+  /** Ref to the editor container for keyboard events */
+  editorRef?: React$1.RefObject<HTMLElement | null> | undefined;
+  /** Custom toolbar items to render */
+  children?: ReactNode | undefined;
+  /** Whether to show font family picker (default: true) */
   showFontPicker?: boolean | undefined;
   /**
    * Custom families for the font-family dropdown (strings and/or `FontOption`
    * objects). Omit to use the built-in defaults; an empty array renders an
    * empty dropdown. Normalized to `FontOption[]` before reaching the picker.
    */
-  fontFamilies?: ReadonlyArray<string | FontOption> | undefined; /** Whether to show font size picker (default: true) */
-  showFontSizePicker?: boolean | undefined; /** Whether to show text color picker (default: true) */
-  showTextColorPicker?: boolean | undefined; /** Whether to show highlight color picker (default: true) */
-  showHighlightColorPicker?: boolean | undefined; /** Whether to show alignment buttons (default: true) */
-  showAlignmentButtons?: boolean | undefined; /** Whether to show list buttons (default: true) */
-  showListButtons?: boolean | undefined; /** Whether to show line spacing picker (default: true) */
-  showLineSpacingPicker?: boolean | undefined; /** Whether to show style picker (default: true) */
-  showStylePicker?: boolean | undefined; /** Whether to show the format painter button (default: true) */
-  showFormatPainter?: boolean | undefined; /** Whether the format painter is armed (drives the button's active state) */
+  fontFamilies?: ReadonlyArray<string | FontOption> | undefined;
+  /** Whether to show font size picker (default: true) */
+  showFontSizePicker?: boolean | undefined;
+  /** Whether to show text color picker (default: true) */
+  showTextColorPicker?: boolean | undefined;
+  /** Whether to show highlight color picker (default: true) */
+  showHighlightColorPicker?: boolean | undefined;
+  /** Whether to show alignment buttons (default: true) */
+  showAlignmentButtons?: boolean | undefined;
+  /** Whether to show list buttons (default: true) */
+  showListButtons?: boolean | undefined;
+  /** Whether to show line spacing picker (default: true) */
+  showLineSpacingPicker?: boolean | undefined;
+  /** Whether to show style picker (default: true) */
+  showStylePicker?: boolean | undefined;
+  /** Whether to show the format painter button (default: true) */
+  showFormatPainter?: boolean | undefined;
+  /** Whether the format painter is armed (drives the button's active state) */
   formatPainterActive?: boolean | undefined;
   /**
    * Arm the format painter: capture the current selection's formatting so the
    * next selection is painted. `sticky` (double-click) keeps it armed until Esc
    * or a toggle off; a single click disarms after one paint.
    */
-  onFormatPainter?: ((sticky: boolean) => void) | undefined; /** Document styles for the style picker */
-  documentStyles?: Style[] | undefined; /** Theme for the style picker */
-  theme?: Theme | null | undefined; /** Callback for print action */
-  onPrint?: (() => void) | undefined; /** Whether to show print button (default: true) */
-  showPrintButton?: boolean | undefined; /** Whether to show zoom control (default: true) */
-  showZoomControl?: boolean | undefined; /** Current zoom level (1.0 = 100%) */
-  zoom?: number | undefined; /** Callback when zoom changes */
-  onZoomChange?: ((zoom: number) => void) | undefined; /** Whether the rulers are currently visible (drives the toggle's active state) */
-  rulerVisible?: boolean | undefined; /** Toggle the rulers on/off. The ruler control renders only when this is provided. */
-  onToggleRuler?: (() => void) | undefined; /** Callback to refocus the editor after toolbar interactions */
-  onRefocusEditor?: (() => void) | undefined; /** Callback when a table should be inserted */
-  onInsertTable?: ((rows: number, columns: number) => void) | undefined; /** Whether to show table insert button (default: true) */
-  showTableInsert?: boolean | undefined; /** Callback when user wants to insert an image */
-  onInsertImage?: (() => void) | undefined; /** Callback when user wants to insert a page break */
-  onInsertPageBreak?: (() => void) | undefined; /** Callback when user wants to insert a table of contents */
-  onInsertTOC?: (() => void) | undefined; /** Callback when user wants to insert a symbol/special character */
-  onInsertSymbol?: (() => void) | undefined; /** Callback when user wants to insert a shape */
+  onFormatPainter?: ((sticky: boolean) => void) | undefined;
+  /** Document styles for the style picker */
+  documentStyles?: Style[] | undefined;
+  /** Theme for the style picker */
+  theme?: Theme | null | undefined;
+  /** Callback for print action */
+  onPrint?: (() => void) | undefined;
+  /** Whether to show print button (default: true) */
+  showPrintButton?: boolean | undefined;
+  /** Whether to show zoom control (default: true) */
+  showZoomControl?: boolean | undefined;
+  /** Current zoom level (1.0 = 100%) */
+  zoom?: number | undefined;
+  /** Callback when zoom changes */
+  onZoomChange?: ((zoom: number) => void) | undefined;
+  /** Whether the rulers are currently visible (drives the toggle's active state) */
+  rulerVisible?: boolean | undefined;
+  /** Toggle the rulers on/off. The ruler control renders only when this is provided. */
+  onToggleRuler?: (() => void) | undefined;
+  /** Callback to refocus the editor after toolbar interactions */
+  onRefocusEditor?: (() => void) | undefined;
+  /** Callback when a table should be inserted */
+  onInsertTable?: ((rows: number, columns: number) => void) | undefined;
+  /** Whether to show table insert button (default: true) */
+  showTableInsert?: boolean | undefined;
+  /** Callback when user wants to insert an image */
+  onInsertImage?: (() => void) | undefined;
+  /** Callback when user wants to insert a page break */
+  onInsertPageBreak?: (() => void) | undefined;
+  /** Callback when user wants to insert a table of contents */
+  onInsertTOC?: (() => void) | undefined;
+  /** Callback when user wants to insert a symbol/special character */
+  onInsertSymbol?: (() => void) | undefined;
+  /** Callback when user wants to insert a shape */
   onInsertShape?: (data: {
     shapeType: string;
     width: number;
@@ -492,16 +574,22 @@ type ToolbarProps = {
     fillType?: string | undefined;
     outlineWidth?: number | undefined;
     outlineColor?: string | undefined;
-  }) => void; /** Image context when an image is selected */
+  }) => void;
+  /** Image context when an image is selected */
   imageContext?: {
     wrapType: string;
     displayMode: string;
     cssFloat: string | null;
-  } | null; /** Callback when image wrap type changes */
-  onImageWrapType?: ((wrapType: string) => void) | undefined; /** Callback for image transform (rotate/flip) */
-  onImageTransform?: (action: "rotateCW" | "rotateCCW" | "flipH" | "flipV") => void; /** Callback to open image properties dialog (alt text + border) */
-  onOpenImageProperties?: (() => void) | undefined; /** Callback to open page setup dialog */
-  onPageSetup?: (() => void) | undefined; /** Table context when cursor is in a table */
+  } | null;
+  /** Callback when image wrap type changes */
+  onImageWrapType?: ((wrapType: string) => void) | undefined;
+  /** Callback for image transform (rotate/flip) */
+  onImageTransform?: (action: "rotateCW" | "rotateCCW" | "flipH" | "flipV") => void;
+  /** Callback to open image properties dialog (alt text + border) */
+  onOpenImageProperties?: (() => void) | undefined;
+  /** Callback to open page setup dialog */
+  onPageSetup?: (() => void) | undefined;
+  /** Table context when cursor is in a table */
   tableContext?: {
     isInTable: boolean;
     rowCount?: number | undefined;
@@ -510,14 +598,18 @@ type ToolbarProps = {
     hasMultiCellSelection?: boolean | undefined;
     cellBorderColor?: ColorValue | undefined;
     cellBackgroundColor?: string | undefined;
-  } | null; /** Callback when a table action is triggered */
+  } | null;
+  /** Callback when a table action is triggered */
   onTableAction?: ((action: TableAction) => void) | undefined;
 };
 //#endregion
 //#region src/components/DocxEditor.props.d.ts
 type DocxEditorProps = {
-  /** Document data — ArrayBuffer, Uint8Array, Blob, or File */documentBuffer?: DocxInput | null; /** Password for Agile-encrypted .docx files (Office 2010+). */
-  password?: string | undefined; /** Pre-parsed document (alternative to documentBuffer) */
+  /** Document data — ArrayBuffer, Uint8Array, Blob, or File */
+  documentBuffer?: DocxInput | null;
+  /** Password for Agile-encrypted .docx files (Office 2010+). */
+  password?: string | undefined;
+  /** Pre-parsed document (alternative to documentBuffer) */
   document?: Document | null;
   /**
    * Stable identity of the loaded document (same across internal edits, distinct
@@ -525,10 +617,14 @@ type DocxEditorProps = {
    * external load from an edited document round-tripped back through state.
    * Falls back to a document-metadata signature when omitted.
    */
-  documentKey?: string; /** 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 */
+  documentKey?: string;
+  /** 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 fired with the resolved PM positions and the
@@ -544,8 +640,10 @@ type DocxEditorProps = {
     from: number;
     to: number;
     text: string;
-  }) => void; /** Callback on error */
-  onError?: (error: Error) => void; /** Callback when fonts are loaded */
+  }) => void;
+  /** Callback on error */
+  onError?: (error: Error) => void;
+  /** Callback when fonts are loaded */
   onFontsLoaded?: () => void;
   /**
    * Custom families shown in the toolbar's font-family dropdown. Strings render
@@ -563,9 +661,12 @@ type DocxEditorProps = {
    * Match `family` to the `fontFamilies` name a user applies. Pass a stable
    * reference — a new array identity re-registers on every render.
    */
-  fonts?: ReadonlyArray<FontDefinition>; /** Theme for styling */
-  theme?: Theme | null; /** Whether to show toolbar (default: true) */
-  showToolbar?: boolean; /** Whether to show zoom control (default: true) */
+  fonts?: ReadonlyArray<FontDefinition>;
+  /** 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 the review controls — the track-changes toggle and the
@@ -580,36 +681,54 @@ type DocxEditorProps = {
    * (default: true). Turn off for plain-markdown editing, which has no running
    * header/footer.
    */
-  showHeaderFooterEditing?: boolean; /** Whether to show page margin guides/boundaries (default: false) */
-  showMarginGuides?: boolean; /** Color for margin guides (default: '#c0c0c0') */
+  showHeaderFooterEditing?: boolean;
+  /** Whether to show page margin guides/boundaries (default: false) */
+  showMarginGuides?: boolean;
+  /** Color for margin guides (default: '#c0c0c0') */
   marginGuideColor?: string;
   /**
    * Whether the horizontal and vertical rulers start visible (default: false).
    * Seeds the initial state of the toolbar's ruler toggle; users show/hide the
    * rulers at runtime from there (like Word's View > Ruler).
    */
-  showRuler?: boolean; /** Measurement unit shown on the rulers (default: 'inch'). */
-  rulerUnit?: "inch" | "cm"; /** Initial zoom level (default: 1.0) */
-  initialZoom?: number; /** Whether Ctrl/Cmd+wheel and trackpad-pinch zoom are enabled (default: true) */
-  enableWheelZoom?: boolean; /** Whether the editor is read-only. When true, hides toolbar and rulers */
-  readOnly?: boolean; /** Whether comments/tracked changes should auto-open the review sidebar (default: true) */
+  showRuler?: boolean;
+  /** Measurement unit shown on the rulers (default: 'inch'). */
+  rulerUnit?: "inch" | "cm";
+  /** Initial zoom level (default: 1.0) */
+  initialZoom?: number;
+  /** Whether Ctrl/Cmd+wheel and trackpad-pinch zoom are enabled (default: true) */
+  enableWheelZoom?: boolean;
+  /** Whether the editor is read-only. When true, hides toolbar and rulers */
+  readOnly?: boolean;
+  /** Whether comments/tracked changes should auto-open the review sidebar (default: true) */
   autoOpenReviewSidebar?: boolean;
   /**
    * Override folio's built-in chrome UI primitives (Button, …) with a
    * consumer's design-system components. Omitted entries fall back to folio's
    * built-in defaults, so standalone folio works without any injection.
    */
-  components?: Partial<FolioUIComponents>; /** 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; /** Keep the current parsed document visible while a new buffer is loading. */
-  preserveDocumentWhileLoading?: boolean; /** Initial scroll offset for the editor's document scroll container. */
-  initialScrollTop?: number; /** Callback when the editor's document scroll container scrolls. */
-  onScrollTopChange?: (scrollTop: number) => void; /** Whether to show the document outline sidebar (default: false) */
-  showOutline?: boolean; /** Whether to show print button in toolbar (default: true) */
-  showPrintButton?: boolean; /** Callback when print is triggered */
+  components?: Partial<FolioUIComponents>;
+  /** 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;
+  /** Keep the current parsed document visible while a new buffer is loading. */
+  preserveDocumentWhileLoading?: boolean;
+  /** Initial scroll offset for the editor's document scroll container. */
+  initialScrollTop?: number;
+  /** Callback when the editor's document scroll container scrolls. */
+  onScrollTopChange?: (scrollTop: number) => void;
+  /** Whether to show the document outline sidebar (default: false) */
+  showOutline?: boolean;
+  /** Whether to show print button in toolbar (default: true) */
+  showPrintButton?: boolean;
+  /** Callback when print is triggered */
   onPrint?: () => void;
   /**
    * Insert controls are opt-in: each toolbar control renders only when its
@@ -618,16 +737,26 @@ type DocxEditorProps = {
    * view-level helpers exported from the package (`insertTableInView`,
    * `insertPageBreakInView`, `insertTableOfContentsInView`, `insertImageFromFile`).
    */
-  onInsertImage?: (() => void) | undefined; /** Insert a `rows × columns` table at the current selection. */
-  onInsertTable?: ((rows: number, columns: number) => void) | undefined; /** Whether the Insert Table control is shown when `onInsertTable` is set (default: true). */
-  showTableInsert?: boolean | undefined; /** Insert a page break at the current selection. */
-  onInsertPageBreak?: (() => void) | undefined; /** Insert a table of contents generated from the document's headings. */
-  onInsertTOC?: (() => void) | undefined; /** 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 readonly user action would mutate the document. */
+  onInsertImage?: (() => void) | undefined;
+  /** Insert a `rows × columns` table at the current selection. */
+  onInsertTable?: ((rows: number, columns: number) => void) | undefined;
+  /** Whether the Insert Table control is shown when `onInsertTable` is set (default: true). */
+  showTableInsert?: boolean | undefined;
+  /** Insert a page break at the current selection. */
+  onInsertPageBreak?: (() => void) | undefined;
+  /** Insert a table of contents generated from the document's headings. */
+  onInsertTOC?: (() => void) | undefined;
+  /** 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 readonly user action would mutate the document. */
   onReadonlyEditAttempt?: () => void;
   /**
    * Controlled comments array. When provided, the editor reads comment thread
@@ -635,15 +764,18 @@ type DocxEditorProps = {
    * Use with collaboration backends (Yjs, etc.) so comment threads sync across
    * peers; PM carries range markers, thread metadata lives outside the doc.
    */
-  comments?: Comment[]; /** Fires whenever the comments array changes (controlled and uncontrolled). */
-  onCommentsChange?: (comments: Comment[]) => void; /** Callback with the parsed document's editing compatibility report. */
+  comments?: Comment[];
+  /** Fires whenever the comments array changes (controlled and uncontrolled). */
+  onCommentsChange?: (comments: Comment[]) => void;
+  /** Callback with the parsed document's editing compatibility report. */
   onCompatibilityChange?: (compatibility: DocxCompatibility) => void;
   /**
    * Fires when the live ProseMirror view is captured (or torn down).
    * The host wires this so it can drive the AI suggestion overlay
    * (decoration meta, apply, scroll-to) from outside the editor.
    */
-  onEditorViewReady?: (view: EditorView | null) => void; /** Yjs-backed collaboration owner. Experimental and opt-in. */
+  onEditorViewReady?: (view: EditorView | null) => void;
+  /** Yjs-backed collaboration owner. Experimental and opt-in. */
   collaboration?: DocxEditorCollaboration | undefined;
   /**
    * Fires with the current anonymization match list every time
@@ -666,7 +798,8 @@ type DocxEditorProps = {
    * `anonymizationSelectionSeq` increments (so repeated
    * sidebar clicks of the same term re-trigger the scroll).
    */
-  selectedAnonymizationCanonical?: string | null | undefined; /** Monotonic counter from the bridge store; drives the re-scroll. */
+  selectedAnonymizationCanonical?: string | null | undefined;
+  /** Monotonic counter from the bridge store; drives the re-scroll. */
   anonymizationSelectionSeq?: number | undefined;
   /**
    * Render legal-template markers ({{field}}, {{@clause:..}},
@@ -753,27 +886,42 @@ type HighlightPassageOptions = {
  * Imperative handle exposed by the DocxEditor component.
  */
 type DocxEditorRef = {
-  /** Get the current document */getDocument: () => Document | null; /** Whether the live ProseMirror state has edits that have not been serialized. */
-  hasPendingChanges: () => boolean; /** Get the editor ref */
-  getEditorRef: () => PagedEditorRef | null; /** The headless editor controller (Seam 6), or null before the editor mounts. */
-  getEditor: () => FolioEditor | null; /** Save the document to buffer. Pass { selective: false } to force full repack. */
+  /** Get the current document */
+  getDocument: () => Document | null;
+  /** Whether the live ProseMirror state has edits that have not been serialized. */
+  hasPendingChanges: () => boolean;
+  /** Get the editor ref */
+  getEditorRef: () => PagedEditorRef | null;
+  /** The headless editor controller (Seam 6), or null before the editor mounts. */
+  getEditor: () => FolioEditor | 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 to a specific page */
+  }) => 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 to a specific page */
   scrollToPage: (pageNumber: number) => void;
   /**
    * Scroll the paginated view to the paragraph with the given Word `w14:paraId`.
    * Pass `options.highlight` to briefly flash it in a custom color.
    */
-  scrollToParaId: (paraId: string, options?: ScrollToParaIdOptions) => boolean; /** 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) */
+  scrollToParaId: (paraId: string, options?: ScrollToParaIdOptions) => boolean;
+  /** 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>;
   /**
    * Force-create the underlying editor view if it has been deferred.
@@ -785,10 +933,14 @@ type DocxEditorRef = {
    */
   ensureEditorView: (options?: {
     focus?: boolean;
-  }) => void; /** Create the block snapshot that an external AI editor should reference. */
-  createAIEditSnapshot: () => FolioAIEditSnapshot | null; /** Apply a versioned document-operation batch against a previously created block snapshot. */
-  applyDocumentOperations: (options: DocxEditorApplyDocumentOperationsOptions) => FolioDocumentOperationResult; /** Undo the latest unchanged document-operation batch. */
-  undoDocumentOperations: (undoHandle: FolioDocumentOperationUndoHandle) => FolioDocumentOperationUndoResult; /** Apply AI-authored operations against a previously created block snapshot. */
+  }) => void;
+  /** Create the block snapshot that an external AI editor should reference. */
+  createAIEditSnapshot: () => FolioAIEditSnapshot | null;
+  /** Apply a versioned document-operation batch against a previously created block snapshot. */
+  applyDocumentOperations: (options: DocxEditorApplyDocumentOperationsOptions) => FolioDocumentOperationResult;
+  /** Undo the latest unchanged document-operation batch. */
+  undoDocumentOperations: (undoHandle: FolioDocumentOperationUndoHandle) => FolioDocumentOperationUndoResult;
+  /** Apply AI-authored operations against a previously created block snapshot. */
   applyAIEditOperations: (options: {
     snapshot: FolioAIEditSnapshot;
     operations: FolioAIEditOperation[];
@@ -851,8 +1003,10 @@ type DocxEditorRef = {
    * ephemeral view state: cleared on the next doc-changing transaction and by
    * {@link clearPassageHighlight}.
    */
-  highlightPassage: (options: HighlightPassageOptions) => HighlightPassageResult; /** Clear the passage highlight painted by {@link highlightPassage}, if any. */
-  clearPassageHighlight: () => void; /** Resolve a stable block or text-range target and reveal it in the editor. */
+  highlightPassage: (options: HighlightPassageOptions) => HighlightPassageResult;
+  /** Clear the passage highlight painted by {@link highlightPassage}, if any. */
+  clearPassageHighlight: () => void;
+  /** Resolve a stable block or text-range target and reveal it in the editor. */
   showInDocument: (target: FolioDocumentNavigationTarget, snapshot?: FolioAIEditSnapshot) => boolean;
   /**
    * The pending suggestions in the live document: AI-proposed tracked changes
@@ -907,7 +1061,8 @@ type DocxEditorRef = {
    * layout fragments with a newline. Returns `null` when the page number is
    * out of range or the layout hasn't been computed yet.
    */
-  getPageText: (page: number) => string | null; /** Resolve a stable block or text range to its real 1-based rendered page. */
+  getPageText: (page: number) => string | null;
+  /** Resolve a stable block or text range to its real 1-based rendered page. */
   getTargetPage: (target: FolioDocumentNavigationTarget, snapshot?: FolioAIEditSnapshot) => number | null;
   /**
    * List every block-level content control in the live document, filtered by
@@ -925,7 +1080,8 @@ type DocxEditorRef = {
    * the lookup uses the document's current shape on every call.
    */
   getContentControls: (filter?: ContentControlFilter) => {
-    properties: SdtProperties; /** Index in the PM document tree, outer→inner. */
+    properties: SdtProperties;
+    /** Index in the PM document tree, outer→inner. */
     path: number[];
     /**
      * PM position of the control's open token in the SOURCE document state.
@@ -972,20 +1128,28 @@ type DocxEditorRef = {
 //#region src/renderAsync.d.ts
 /** Framework-agnostic handle for an imperatively mounted editor instance. */
 type EditorHandle = {
-  /** Save the document and return the DOCX as a Blob. */save: () => Promise<Blob | null>; /** Get the current parsed document model. */
-  getDocument: () => Document | null; /** Focus the editor. */
-  focus: () => void; /** Unmount the editor and clean up. */
+  /** Save the document and return the DOCX as a Blob. */
+  save: () => Promise<Blob | null>;
+  /** Get the current parsed document model. */
+  getDocument: () => Document | null;
+  /** Focus the editor. */
+  focus: () => void;
+  /** Unmount the editor and clean up. */
   destroy: () => void;
 };
 /** React-specific handle with zoom and scroll helpers. */
 type DocxEditorHandle = EditorHandle & {
-  /** Set zoom level (1.0 = 100%). */setZoom: (zoom: number) => void; /** Scroll the visible pages to a raw ProseMirror document position. */
-  scrollToPosition: (pmPos: number) => void; /** Scroll the visible pages to a 1-indexed page number. */
+  /** Set zoom level (1.0 = 100%). */
+  setZoom: (zoom: number) => void;
+  /** Scroll the visible pages to a raw ProseMirror document position. */
+  scrollToPosition: (pmPos: number) => void;
+  /** Scroll the visible pages to a 1-indexed page number. */
   scrollToPage: (pageNumber: number) => void;
 };
 /** Options for {@link renderAsync}. */
 type RenderAsyncOptions = Omit<DocxEditorProps, "documentBuffer" | "document"> & {
-  /** BCP-47 locale for bundled folio UI strings (default: `en`). */locale?: string;
+  /** BCP-47 locale for bundled folio UI strings (default: `en`). */
+  locale?: string;
 };
 /**
  * Render a DOCX editor into a container element.