@docx-editor.dev/react 2.4.1 → 2.6.0

package/dist/index.d.mts

@@ -1,17 +1,35 @@
 import * as react from 'react';
-import react__default, { CSSProperties, ReactNode, ReactElement, ForwardRefExoticComponent, RefAttributes, HTMLAttributes, Ref } from 'react';
+import react__default, { ReactNode, CSSProperties, ReactElement, ForwardRefExoticComponent, RefAttributes, HTMLAttributes, Ref } from 'react';
+import { RevisionAuthorStyle, DocxEditorInstance, FontConfigurationFragment, FontResolver, EditorModule, ImageDecodePort, ChromeSlotId, SupportedImageMime, TableChromeSlotId, ChromeMenuId, ChromeMenuEntry, SurfaceHyperlink, ReviewAuthorInfo, ImageWrapTarget, TextMeasurer, PaginatedSurfaceState, NavigationCommand, SurfaceFormatting, SectionProperties, RulerIndent } from '@docx-editor.dev/core/editor';
+export { CHROME_GROUPS, CHROME_MENUS, ChromeMenu, ChromeMenuEntry, ChromeMenuId, ChromeMenuItemEntry, ChromeMenuSeparatorEntry, ChromeMenuSubmenuEntry, ChromeSlotId, FontConfigurationBase, FontConfigurationFragment, FontLoadFailure, FontLoadFailureReason, FontResolutionRequest, FontResolver, FontUrlSource, ImageWrapTarget, LOADING_SNAPSHOT, LoadFontsRequest, LoadFontsResult, MAX_RESOLVER_FAMILIES, PX_PER_CM, PX_PER_INCH, ReviewAuthorInfo, RevisionAuthorAssignments, RevisionAuthorStyle, RevisionStyles, RulerTick, RulerUnit, ToolbarCommandState, WORD_DEFAULT_FONT, chromeMenuSlots, commandForSlot, composeFontConfiguration, createFontSource, generateRulerTicks, loadFonts, rulerPageBox, runToolbarCommand, toolbarCommandState } from '@docx-editor.dev/core/editor';
 import { DocumentSource, FontConfiguration, ZoomMode, Editor, DocumentChange, EditorFontError, TextMatch, ViewScope, DocumentHandle, EditorCommand, EditorScope, ExecResult, EditorSnapshot, EditorEvents, PageSetup, IndentFormatting, ColorValue, Theme } from '@docx-editor.dev/core/contracts/editor';
 export { Editor, EditorCommand, EditorFontError, EditorFontErrorCode, EditorQuery, EditorScope, EditorSnapshot, FontConfiguration, FontFaceRequest, FontSource, FontSourceSubstitution, PageSetup } from '@docx-editor.dev/core/contracts/editor';
-import { FontConfigurationFragment, FontResolver, EditorModule, ImageDecodePort, ChromeSlotId, SupportedImageMime, TableChromeSlotId, ChromeMenuId, ChromeMenuEntry, DocxEditorInstance, SurfaceHyperlink, ImageWrapTarget, TextMeasurer, PaginatedSurfaceState, NavigationCommand, SurfaceFormatting, SectionProperties, RulerIndent } from '@docx-editor.dev/core/editor';
-export { CHROME_GROUPS, CHROME_MENUS, ChromeMenu, ChromeMenuEntry, ChromeMenuId, ChromeMenuItemEntry, ChromeMenuSeparatorEntry, ChromeMenuSubmenuEntry, ChromeSlotId, FontConfigurationBase, FontConfigurationFragment, FontLoadFailure, FontLoadFailureReason, FontResolutionRequest, FontResolver, FontUrlSource, ImageWrapTarget, LoadFontsRequest, LoadFontsResult, MAX_RESOLVER_FAMILIES, PX_PER_CM, PX_PER_INCH, RulerTick, RulerUnit, ToolbarCommandState, WORD_DEFAULT_FONT, chromeMenuSlots, commandForSlot, composeFontConfiguration, createFontSource, generateRulerTicks, loadFonts, rulerPageBox, runToolbarCommand, toolbarCommandState } from '@docx-editor.dev/core/editor';
-import { TFunction, Translations } from '@docx-editor.dev/i18n';
+import { TFunction, Translations, LocaleStrings } from '@docx-editor.dev/i18n';
+export { TranslationKey } from '@docx-editor.dev/i18n';
 import { ContentControlType, ContentControlSummary } from '@docx-editor.dev/core';
 export { DocxDocument } from '@docx-editor.dev/core/contracts/types';
 
+/** @public */
+declare const VERSION: string;
+
+/** React composables take plain values; parity name matches the Vue surface. @public */
+type MaybeRefOrGetter<T> = T;
+
+/**
+ * Slot and icon content in public component props.
+ *
+ * React hosts pass {@link ReactNode}. Vue hosts pass {@link https://vuejs.org/api/utility-types.html#vnode | VNode}
+ * through the paired {@link DocxEditorChildren} alias in `@docx-editor.dev/vue`.
+ *
+ * @public
+ */
+type DocxEditorChildren = ReactNode;
+
 /** Props for `DocxEditor.Content`. @public */
 interface DocxEditorContentProps {
     /** Appended after the load-bearing `docx-paginated-surface` class. */
     className?: string;
+    children?: DocxEditorChildren;
 }
 /**
  * The element the engine paints pages into. Must render inside a
@@ -38,6 +56,16 @@ interface DocxEditorLoadingProps {
      * provider only after those resolve.
      */
     when?: boolean;
+    /**
+     * Render as an opaque overlay pinned over the nearest positioned ancestor, covering
+     * the previous document while the next one opens. This is the shape for the big-file
+     * case: a large document mounts behind one painted frame, and the overlay is what
+     * that frame shows. It carries a short appearance delay, so an open that finishes
+     * quickly never flashes it. Compose it INSIDE a positioned box (the packaged frame
+     * puts it in the workspace row); without `overlay` the part is an in-flow box that
+     * fills whatever the host gives it.
+     */
+    overlay?: boolean;
     /** Appended after the load-bearing `docx-editor docx-editor__loading` classes. */
     className?: string;
     /** Inline styles for the loading container, as on `DocxEditor.Viewport`. */
@@ -47,7 +75,7 @@ interface DocxEditorLoadingProps {
      * used, so the batteries-included path has something to show. Compose your own around
      * `DocxEditor.Loading.Spinner` to keep the packaged indicator beside your own copy.
      */
-    children?: ReactNode;
+    children?: DocxEditorChildren;
 }
 /** Props for `DocxEditor.Loading.Spinner`. @public */
 interface DocxEditorLoadingSpinnerProps {
@@ -91,11 +119,17 @@ interface DocxEditorLoadingComponent {
  * </DocxEditor.Root>
  * ```
  *
- * It clears as soon as bytes are handed over — NOT when pages finish painting — so it is
- * safe to gate a `DocxEditor.Content` on, and an unmounted viewport does not bring it
- * back. A parse failure clears it too, so a broken document never spins forever; report
- * that from `snapshot().parseError` or the `error` event. Add `when` only for async the
- * editor cannot observe, typically a host that mounts the provider after its own fetch.
+ * It covers TWO windows. Before bytes arrive it is the empty-state screen. And while a
+ * LARGE document opens — the engine mounts it behind one painted frame precisely so this
+ * screen can paint before the blocking parse and layout — it holds until the pages land;
+ * pass `overlay` to pin it over the previous document for that window. A parse failure
+ * clears both, so a broken document never spins forever; report that from
+ * `snapshot().parseError` or the `error` event. Add `when` only for async the editor
+ * cannot observe, typically a host that mounts the provider after its own fetch.
+ *
+ * A host gating its own `DocxEditor.Content` must key that on `snapshot().isLoading`,
+ * which clears as soon as bytes are handed over — never on `isOpening`, whose scheduled
+ * mount needs the mount point to stay in the tree.
  *
  * Rendered OUTSIDE a `DocxEditor.Root` it always shows, because there is no editor to
  * report otherwise — the same rule `useEditorState` documents for a null editor. Place
@@ -107,6 +141,91 @@ interface DocxEditorLoadingComponent {
  */
 declare const DocxEditorLoading: DocxEditorLoadingComponent;
 
+/**
+ * Colour tracked changes by the TYPE of change instead of by author, while mounted.
+ *
+ * The editor colours by author out of the box — Word's own default, so a paragraph three
+ * people edited reads as three people. Mount this to opt out: insertions take
+ * `--doc-revision-insertion` and deletions `--doc-revision-deletion`, whoever proposed
+ * them. Renders nothing; unmounting it returns to by-author colouring.
+ *
+ * Composed with `DocxEditor.AuthorStyle`, it also expresses "highlight these reviewers and
+ * leave everyone else green and red": the authors you declare keep their own colour, and
+ * this puts the rest on the kind colours.
+ *
+ * ```tsx
+ * <DocxEditor.Root document={bytes} modules={MODULES}>
+ *   <DocxEditor.ColorByChangeType />
+ *   …
+ * </DocxEditor.Root>
+ * ```
+ *
+ * @public
+ */
+declare function DocxEditorColorByChangeType(): null;
+/**
+ * Props for `DocxEditor.AuthorStyle`: one author, and the {@link RevisionAuthorStyle}
+ * fields to apply — `color` (document ink and the review chrome's accent), `background`
+ * (the wash), `spanClassName` (classes on the painted spans), and `avatarUrl`.
+ *
+ * @public
+ */
+interface DocxEditorAuthorStyleProps extends RevisionAuthorStyle {
+    /** The author to style. Matches `w:author` exactly. */
+    author: string;
+}
+/**
+ * Declare one author's presentation, while mounted.
+ *
+ * Renders nothing. The editor already colours every author from the
+ * `--doc-review-author-N` ramp; this overrides one of them, and leaves the rest where they
+ * are. Prop changes re-apply live — pages repaint without a remount, so the caret and undo
+ * history stay — and unmounting returns that author to the ramp.
+ *
+ * Read who is in the document with `useReviewAuthors`, and read these declarations back
+ * inside a custom review card with `useReviewAuthor`.
+ *
+ * ```tsx
+ * <DocxEditor.Root document={bytes} modules={MODULES}>
+ *   <DocxEditor.AuthorStyle author="Jess Lin" color="#7c3aed" avatarUrl="/jess.png" />
+ *   …
+ * </DocxEditor.Root>
+ * ```
+ *
+ * @public
+ */
+declare function DocxEditorAuthorStyle(props: DocxEditorAuthorStyleProps): null;
+
+/**
+ * The editor instance from the nearest `DocxEditor.Root`, or `null` before the Root's
+ * mount effect has created it (and outside any Root). Deliberately not a throwing
+ * variant: pre-mount is a normal frame every consumer renders through, and the state
+ * hooks built on this already answer it with a typed loading snapshot.
+ *
+ * @public
+ */
+declare function useDocxEditor(): DocxEditorInstance | null;
+/**
+ * Whether a review rail is mounted under this Root, and how much room it wants.
+ *
+ * The GUTTER is the reason this exists. `DocxEditor.Viewport` reserves space beside the
+ * page for the pane, and the ruler shifts by the same amount — but neither of them can see
+ * whether a rail was actually composed in. Keyed on the pane's open state alone, every
+ * consumer of the tier-2 `<DocxEditor>` sugar (which mounts no rail) had its page pushed
+ * 158px off centre beside an empty column.
+ *
+ * A rail registers on mount and unregisters on unmount, so the reservation follows what is
+ * really on screen. Count rather than boolean: StrictMode mounts twice, and a host may
+ * legitimately compose two rails.
+ */
+interface ReviewRailRegistry {
+    readonly mounted: number;
+    readonly register: () => () => void;
+    readonly registerCommentDraft: (handler: () => void) => () => void;
+    readonly requestCommentDraft: () => boolean;
+}
+declare const ReviewRailContext: react.Context<ReviewRailRegistry | null>;
+
 /**
  * Props for `DocxEditor.Root`. Creation parameters (`document`, `fonts`, `author`,
  * `locale`, and the initial `mode`/`zoom`) are sampled when the instance is created;
@@ -116,7 +235,9 @@ declare const DocxEditorLoading: DocxEditorLoadingComponent;
  * @public
  */
 interface DocxEditorRootProps {
-    /** A document to load: DOCX bytes or an existing handle. Identity change remounts. */
+    /** A document to load: DOCX bytes, `'blank'` for an empty one, or an existing handle.
+     * Identity change remounts; `'blank'` is a constant, so holding it across renders does
+     * not. Omitting this mounts NO document, which is not the same as an empty one. */
     document?: DocumentSource;
     /**
      * Font bytes for Word-accurate (HarfBuzz-shaped) wrap and pagination. Omitted, layout
@@ -137,8 +258,16 @@ interface DocxEditorRootProps {
      * construction-time in the engine.
      */
     modules?: readonly EditorModule[];
-    /** `'edit'` (default) or `'view'` (read-only). Sampled at mount only. */
-    mode?: 'edit' | 'view';
+    /**
+     * The mode the editor opens in, matching the toolbar's three-state pill. Sampled at
+     * mount only.
+     *
+     * `'edit'` opens in editing even when the document's `w:trackRevisions` asks for
+     * tracked changes; `'suggesting'` opens in suggesting (needs a review module and an
+     * `author`); `'view'` is read-only and the toolbar cannot leave it. Omitted, the
+     * DOCUMENT decides: a package carrying `w:trackRevisions` opens in suggesting.
+     */
+    mode?: 'edit' | 'view' | 'suggesting';
     /**
      * A fixed scale. Supplying one also means the mode is fixed, unless `zoomMode` says
      * otherwise: an app that pinned 100% keeps 100% on every window size.
@@ -154,7 +283,9 @@ interface DocxEditorRootProps {
      */
     zoomMode?: ZoomMode | 'auto';
     /** Fired once per instance, after it is published to the tree (and after any
-     *  `DocxEditor.Content` in the same commit has attached its mount point). */
+     *  `DocxEditor.Content` in the same commit has attached its mount point). A large
+     *  document mounts behind one painted frame; `onReady` fires AFTER that mount lands,
+     *  so scrolling or selecting from it works on any document size. */
     onReady?: (editor: Editor) => void;
     /** Fired when the document changes (revision + identity deltas, not bytes). */
     onChange?: (change: DocumentChange) => void;
@@ -167,8 +298,29 @@ interface DocxEditorRootProps {
     tableInteractionLabel?: (key: 'table.insertRowBelow' | 'table.insertColumnRight') => string;
     /** Optional decode port for embedded image insertion and paint in tests or custom hosts. */
     imageDecodePort?: ImageDecodePort;
-    children?: ReactNode;
+    children?: DocxEditorChildren;
+}
+/** @public Vue-only lifecycle listeners; exported for cross-adapter API parity. */
+interface DocxEditorRootListeners {
+    onReady?: (editor: Editor) => void;
+    onChange?: (change: DocumentChange) => void;
+    onFontError?: (error: EditorFontError) => void;
+}
+/** @public Vue-only setup result; exported for cross-adapter API parity. */
+interface ProvideDocxEditorResult {
+    readonly DocxEditorRoot: typeof DocxEditorRoot;
+    readonly rootProps: Omit<DocxEditorRootProps, keyof DocxEditorRootListeners>;
+    readonly rootListeners: DocxEditorRootListeners;
+    readonly editorRef: ReturnType<typeof useDocxEditor>;
 }
+/**
+ * Prepares Root props and listeners while exposing the instance created by that Root.
+ * Call this function during render, like a React hook.
+ *
+ * @public
+ */
+declare function useProvidedDocxEditor(options: DocxEditorRootProps): ProvideDocxEditorResult;
+
 /**
  * Creates and owns a `DocxEditorInstance` and provides it to the subtree. Renders no
  * DOM — compose it with `DocxEditor.Viewport` + `DocxEditor.Content` for the painted
@@ -183,7 +335,7 @@ interface DocxEditorViewportProps {
     /** Appended after the load-bearing viewport classes (e.g. `dark` for chrome theming). */
     className?: string;
     style?: CSSProperties;
-    children?: ReactNode;
+    children?: DocxEditorChildren;
 }
 /**
  * The sole scroll container for the painted document. Put `DocxEditor.Content` inside
@@ -195,17 +347,33 @@ declare function DocxEditorViewport({ className, style, children }: DocxEditorVi
 
 /** Resolves an i18n key to display text. @public */
 type ToolbarTranslate = (key: string) => string;
+interface ToolbarContextValue {
+    readonly t: ToolbarTranslate | undefined;
+    /** Host save handler for the `file.save` part; absent renders the part disabled. */
+    readonly onSave: (() => void) | undefined;
+}
+declare const ToolbarContext: react.Context<ToolbarContextValue>;
+/** The toolbar root's published value. Internal: parts read it, hosts pass props. */
+declare function useToolbarContext(): ToolbarContextValue;
+/**
+ * The label for an i18n key given a host resolver: the host's translation, else the
+ * locale catalogue. The toolbar ROOT needs this before it publishes its context, so the
+ * resolver is separate from the context read below — a raw key must never reach the DOM.
+ */
+declare function useToolbarLabelFor(t: ToolbarTranslate | undefined): (key: string) => string;
+/** The label for an i18n key: the host's translation, else the locale catalogue. */
+declare function useToolbarLabel(): (key: string) => string;
 
 /** Props for `DocxEditorToolbar.Button`. @public */
 interface ToolbarButtonProps$1 {
     /** The chrome slot this button drives (`'text.bold'`, `'history.undo'`, ...). */
     slot: ChromeSlotId;
     /** Icon override; falls back to `children`, then to the registry's icon paths. */
-    icon?: ReactNode;
+    icon?: DocxEditorChildren;
     /** Merge the button's behavior into the single child element instead of a <button>. */
     asChild?: boolean;
     className?: string;
-    children?: ReactNode;
+    children?: DocxEditorChildren;
     /** Render nothing — inside the default arrangement this removes the slot. */
     hidden?: boolean;
 }
@@ -230,7 +398,7 @@ interface ImageInsertTriggerProps {
     className?: string;
     hidden?: boolean;
     asChild?: boolean;
-    children?: ReactNode;
+    children?: DocxEditorChildren;
 }
 /** Toolbar insert-image control — opens the shared file picker. @public */
 declare function ImageInsertTrigger({ className, hidden, asChild, children, }: ImageInsertTriggerProps): react.JSX.Element | null;
@@ -243,7 +411,7 @@ interface ImageWrapProps {
     className?: string;
     hidden?: boolean;
     asChild?: boolean;
-    children?: ReactNode;
+    children?: DocxEditorChildren;
 }
 /**
  * Wrap-text dropdown presenting all nine Word choices.
@@ -265,7 +433,7 @@ interface ImageAltTextProps {
     className?: string;
     hidden?: boolean;
     asChild?: boolean;
-    children?: ReactNode;
+    children?: DocxEditorChildren;
 }
 /**
  * Opens a small panel to edit image description (and optional title).
@@ -282,12 +450,17 @@ interface ImageAltTextPartComponent {
     readonly docxSlot: 'image.altText';
 }
 
+/** @public */
+interface RefObject<T> {
+    readonly current: T | null;
+}
+
 /** Props for `DocxEditor.ImagePropertiesDialog`. @public */
 interface DocxEditorImagePropertiesDialogProps {
     open: boolean;
     onClose: () => void;
     className?: string;
-    triggerRef?: React.RefObject<HTMLElement | null>;
+    triggerRef?: RefObject<HTMLElement | null>;
 }
 /**
  * Properties dialog for the selected picture.
@@ -300,7 +473,7 @@ interface ImagePropertiesTriggerProps {
     className?: string;
     hidden?: boolean;
     asChild?: boolean;
-    children?: react.ReactNode;
+    children?: DocxEditorChildren;
 }
 /**
  * Opens the image properties dialog for the selected drawing.
@@ -311,6 +484,9 @@ declare function ImagePropertiesTrigger({ className, hidden, asChild, children,
 declare namespace ImagePropertiesTrigger {
     var docxSlot: "image.properties";
 }
+declare const ToolbarImageProperties: typeof ImagePropertiesTrigger & {
+    docxSlot: "image.properties";
+};
 
 type NormalizedImagePayload = {
     readonly ok: true;
@@ -367,7 +543,7 @@ interface ToolbarColorSplitProps extends ToolbarSlotPartProps {
      * The BAR is not replaceable and still paints the live value, so a host swapping the glyph
      * keeps the thing that makes this control readable at a glance.
      */
-    icon?: ReactNode;
+    icon?: DocxEditorChildren;
 }
 /** A split colour control pinned to one slot. @public */
 interface ToolbarColorSplitComponent {
@@ -391,7 +567,7 @@ interface ToolbarActionProps {
      */
     label: string;
     /** Icon content. Inline SVG sized ~18px matches the packaged controls. */
-    icon?: ReactNode;
+    icon?: DocxEditorChildren;
     /** Pressed state, for an action that toggles. Sets `aria-pressed` and `data-active`. */
     active?: boolean;
     disabled?: boolean;
@@ -401,7 +577,7 @@ interface ToolbarActionProps {
     /** Merge the behavior onto the single child element instead of rendering a `<button>`. */
     asChild?: boolean;
     className?: string;
-    children?: ReactNode;
+    children?: DocxEditorChildren;
 }
 /**
  * A host-owned toolbar action, styled and behaved like the packaged controls.
@@ -437,7 +613,7 @@ declare function useFontFamily(): UseFontFamilyResult;
 interface FontFamilyPartProps {
     asChild?: boolean;
     className?: string;
-    children?: ReactNode;
+    children?: DocxEditorChildren;
 }
 /** Props for the compound root. @public */
 interface FontFamilyProps extends FontFamilyPartProps {
@@ -507,7 +683,7 @@ declare function useParagraphStyle(): UseParagraphStyleResult;
 interface ParagraphStylePartProps {
     asChild?: boolean;
     className?: string;
-    children?: ReactNode;
+    children?: DocxEditorChildren;
 }
 /** Props for the compound root. @public */
 interface ParagraphStyleProps extends ParagraphStylePartProps {
@@ -544,7 +720,7 @@ interface TableChromePartProps {
     /** Merge props onto the single child element instead of rendering a default host node. */
     asChild?: boolean;
     /** Custom panel body or trigger label; defaults to the packaged control chrome. */
-    children?: ReactNode;
+    children?: DocxEditorChildren;
 }
 /** Props for a value-driven row or swatch inside a table compound menu. @public */
 interface TableChromeItemProps extends TableChromePartProps {
@@ -561,11 +737,11 @@ interface TableChromePartComponent extends ToolbarSlotPartComponent {
     /** The chrome slot this compound drives. */
     readonly docxSlot: TableChromeSlotId;
     /** Opens the picker menu or dialog. */
-    readonly Trigger: (props: TableChromePartProps) => ReactNode;
+    readonly Trigger: (props: TableChromePartProps) => DocxEditorChildren;
     /** The open menu or dialog panel; omit to use the default item list. */
-    readonly Content: (props: TableChromePartProps) => ReactNode;
+    readonly Content: (props: TableChromePartProps) => DocxEditorChildren;
     /** One selectable value row or swatch inside {@link Content}. */
-    readonly Item: (props: TableChromeItemProps) => ReactNode;
+    readonly Item: (props: TableChromeItemProps) => DocxEditorChildren;
 }
 /**
  * Border-target picker compound (`DocxEditor.Toolbar.TableBorderTarget`).
@@ -576,11 +752,11 @@ interface TableBorderTargetNamespace extends TableChromePartComponent {
     /** Chrome slot id: `table.borderTarget`. */
     readonly docxSlot: 'table.borderTarget';
     /** Button that opens the border-edge target menu. */
-    readonly Trigger: (props: TableChromePartProps) => ReactNode;
+    readonly Trigger: (props: TableChromePartProps) => DocxEditorChildren;
     /** Open menu listing edge scopes and clear. */
-    readonly Content: (props: TableChromePartProps) => ReactNode;
+    readonly Content: (props: TableChromePartProps) => DocxEditorChildren;
     /** One edge scope or clear row inside the target menu. */
-    readonly Item: (props: TableChromeItemProps) => ReactNode;
+    readonly Item: (props: TableChromeItemProps) => DocxEditorChildren;
 }
 /**
  * Border-colour split compound with a quick-apply main button and swatch dialog
@@ -592,13 +768,13 @@ interface TableBorderColorNamespace extends TableChromePartComponent {
     /** Chrome slot id: `table.borderColor`. */
     readonly docxSlot: 'table.borderColor';
     /** Applies the last swatch without opening the dialog. */
-    readonly Main: (props: TableChromePartProps) => ReactNode;
+    readonly Main: (props: TableChromePartProps) => DocxEditorChildren;
     /** Button that opens the border-colour swatch dialog. */
-    readonly Trigger: (props: TableChromePartProps) => ReactNode;
+    readonly Trigger: (props: TableChromePartProps) => DocxEditorChildren;
     /** Open swatch dialog for the active border target. */
-    readonly Content: (props: TableChromePartProps) => ReactNode;
+    readonly Content: (props: TableChromePartProps) => DocxEditorChildren;
     /** One colour swatch inside the border-colour dialog. */
-    readonly Item: (props: TableChromeItemProps) => ReactNode;
+    readonly Item: (props: TableChromeItemProps) => DocxEditorChildren;
 }
 /**
  * Cell-fill split compound (`DocxEditor.Toolbar.TableCellFill`).
@@ -609,13 +785,13 @@ interface TableCellFillNamespace extends TableChromePartComponent {
     /** Chrome slot id: `table.cellFill`. */
     readonly docxSlot: 'table.cellFill';
     /** Applies the last swatch without opening the dialog. */
-    readonly Main: (props: TableChromePartProps) => ReactNode;
+    readonly Main: (props: TableChromePartProps) => DocxEditorChildren;
     /** Button that opens the cell-fill swatch dialog. */
-    readonly Trigger: (props: TableChromePartProps) => ReactNode;
+    readonly Trigger: (props: TableChromePartProps) => DocxEditorChildren;
     /** Open swatch dialog for the selected cell(s). */
-    readonly Content: (props: TableChromePartProps) => ReactNode;
+    readonly Content: (props: TableChromePartProps) => DocxEditorChildren;
     /** One fill swatch inside the cell-fill dialog. */
-    readonly Item: (props: TableChromeItemProps) => ReactNode;
+    readonly Item: (props: TableChromeItemProps) => DocxEditorChildren;
 }
 /**
  * Border-style menu compound (`DocxEditor.Toolbar.TableBorderStyle`).
@@ -626,11 +802,11 @@ interface TableBorderStyleNamespace extends TableChromePartComponent {
     /** Chrome slot id: `table.borderStyle`. */
     readonly docxSlot: 'table.borderStyle';
     /** Button that opens the border line-style menu. */
-    readonly Trigger: (props: TableChromePartProps) => ReactNode;
+    readonly Trigger: (props: TableChromePartProps) => DocxEditorChildren;
     /** Open menu listing line styles for the active target. */
-    readonly Content: (props: TableChromePartProps) => ReactNode;
+    readonly Content: (props: TableChromePartProps) => DocxEditorChildren;
     /** One line-style row inside the style menu. */
-    readonly Item: (props: TableChromeItemProps) => ReactNode;
+    readonly Item: (props: TableChromeItemProps) => DocxEditorChildren;
 }
 /**
  * Border-width menu compound (`DocxEditor.Toolbar.TableBorderWidth`).
@@ -641,11 +817,11 @@ interface TableBorderWidthNamespace extends TableChromePartComponent {
     /** Chrome slot id: `table.borderWidth`. */
     readonly docxSlot: 'table.borderWidth';
     /** Button that opens the border width menu. */
-    readonly Trigger: (props: TableChromePartProps) => ReactNode;
+    readonly Trigger: (props: TableChromePartProps) => DocxEditorChildren;
     /** Open menu listing width presets for the active target. */
-    readonly Content: (props: TableChromePartProps) => ReactNode;
+    readonly Content: (props: TableChromePartProps) => DocxEditorChildren;
     /** One width preset row inside the width menu. */
-    readonly Item: (props: TableChromeItemProps) => ReactNode;
+    readonly Item: (props: TableChromeItemProps) => DocxEditorChildren;
 }
 /**
  * Resolved label for the active border target in the shared draft.
@@ -678,7 +854,7 @@ interface DocxEditorToolbarProps {
      * menu when it runs out of width. Default `true`.
      */
     overflow?: boolean;
-    children?: ReactNode;
+    children?: DocxEditorChildren;
 }
 /** The toolbar with its parts attached as statics. @public */
 interface DocxEditorToolbarNamespace {
@@ -759,7 +935,7 @@ type MenuId = ChromeMenuId | (string & {});
 /** Props for `DocxEditor.Menu.Row`: one presentational menu row. @public */
 interface MenuRowProps {
     /** Material Symbols paths, rendered as inline SVG in the row's icon column. */
-    icon?: ReactNode;
+    icon?: DocxEditorChildren;
     /** Right-aligned shortcut text (already resolved). */
     shortcut?: string;
     disabled?: boolean;
@@ -783,9 +959,19 @@ interface MenuRowProps {
     selected?: true;
     /** Stable marker for hosts, tests and e2e. */
     slot?: string;
+    /**
+     * Vue TSX maps row identity through `rowSlot` because `slot` is reserved.
+     * React uses {@link slot} directly.
+     */
+    rowSlot?: string;
     onSelect?: () => void;
+    /**
+     * Vue TSX binds row activation through `selectHandler` because `onSelect`
+     * is treated as a listener. React uses {@link onSelect} directly.
+     */
+    selectHandler?: () => void;
     className?: string;
-    children?: ReactNode;
+    children?: DocxEditorChildren;
 }
 /**
  * One menu row: icon column, label, shortcut column.
@@ -804,7 +990,7 @@ interface MenuGroupProps {
     labelKey?: string;
     className?: string;
     hidden?: boolean;
-    children?: ReactNode;
+    children?: DocxEditorChildren;
 }
 /**
  * A named section inside a panel: a visible heading and the rows under it.
@@ -866,7 +1052,7 @@ interface MenuSubmenuProps {
     /** Material Symbols paths for the parent row's icon. */
     paths?: readonly string[] | null;
     className?: string;
-    children?: ReactNode;
+    children?: DocxEditorChildren;
 }
 /**
  * A row that opens a nested panel to its right (Insert › Break).
@@ -934,7 +1120,7 @@ interface MenuProps {
      *
      * Decorative: the label is the accessible name, so the icon is hidden from assistive tech.
      */
-    icon?: ReactNode;
+    icon?: DocxEditorChildren;
     className?: string;
     /** Render nothing — inside the default bar this removes the menu. */
     hidden?: boolean;
@@ -946,7 +1132,7 @@ interface MenuProps {
      */
     preset?: boolean;
     /** Panel content. */
-    children?: ReactNode;
+    children?: DocxEditorChildren;
 }
 /**
  * One menu of the bar: a trigger and the panel it opens.
@@ -1038,7 +1224,7 @@ interface DocxEditorMenuProps {
      * children override their menu in place, others append.
      */
     preset?: boolean;
-    children?: ReactNode;
+    children?: DocxEditorChildren;
 }
 /** The menu bar with its parts attached as statics. @public */
 interface DocxEditorMenuNamespace {
@@ -1104,7 +1290,11 @@ declare function DocxEditorHorizontalRuler(props: DocxEditorRulerProps): ReactEl
  * when the engine supports page-setup writes, committing one undoable step on release.
  *
  * Renders nothing while the editor holds no document — see
- * {@link selectDocumentAbsent}.
+ * {@link selectDocumentAbsent} — and nothing while the page is wider than the
+ * viewport: the ruler rides the scroller at content x=0, so a horizontal scroll
+ * would carry it out of view, and pinning it instead would paint ticks over page
+ * text. Word's web peers drop it on cramped viewports; so does this part, and it
+ * returns as soon as the page fits again.
  *
  * @public
  */
@@ -1177,7 +1367,7 @@ declare function useNavigationPane(options?: UseNavigationPaneOptions): UseNavig
 interface NavigationPartProps {
     className?: string;
     style?: CSSProperties;
-    children?: ReactNode;
+    children?: DocxEditorChildren;
 }
 /**
  * The pane's title row. With no children it renders the close arrow and the title.
@@ -1250,7 +1440,7 @@ interface DocxEditorNavigationProps extends UseNavigationPaneOptions {
     className?: string;
     style?: CSSProperties;
     /** Replaces the default composition (header, tabs, both panels). */
-    children?: ReactNode;
+    children?: DocxEditorChildren;
 }
 /**
  * The document navigation pane — headings and find — over the left gutter.
@@ -1383,6 +1573,12 @@ interface NavigationShiftInput {
     readonly reservation: number;
     /** Padding already reserved at the inline end, for example by the review rail. */
     readonly inlineEndReservation?: number;
+    /**
+     * Padding already standing at the inline START besides the shift itself — the review
+     * gutter's mirrored strip. It moves the page exactly as the shift does, so a shift
+     * computed without it lands the page that far past the reservation.
+     */
+    readonly inlineStartReservation?: number;
     /**
      * Whether the page's WIDTH follows the padding right now.
      *
@@ -1409,7 +1605,7 @@ interface NavigationShiftInput {
  * document with no page setup) rather than guessing: shifting on a zero measurement would
  * make the pane jump on the first frame and settle on the second.
  */
-declare function navigationShift({ viewportWidth, pageWidthPx, reservation, inlineEndReservation, docked, }: NavigationShiftInput): number;
+declare function navigationShift({ viewportWidth, pageWidthPx, reservation, inlineEndReservation, inlineStartReservation, docked, }: NavigationShiftInput): number;
 
 /**
  * The px the chrome is currently displaced by an open navigation pane. `0` when no pane
@@ -1435,6 +1631,8 @@ interface DocxEditorPageSetupDialogProps {
  */
 declare function DocxEditorPageSetupDialog({ open, onClose, className, }: DocxEditorPageSetupDialogProps): ReactElement | null;
 
+/** Internal bridge from the batteries-included editor's `t` prop to this composition part. */
+declare const PageNumberTranslationContext: react.Context<((key: string) => string) | null>;
 /** Props for `DocxEditor.PageNumber`. @public */
 interface DocxEditorPageNumberProps {
     /** Appended after the default page-number classes. */
@@ -1493,12 +1691,12 @@ interface HyperLinkPartProps {
     asChild?: boolean;
     /** Render nothing — inside the default arrangement this removes the part. */
     hidden?: boolean;
-    children?: ReactNode;
+    children?: DocxEditorChildren;
 }
 /** Props for the action parts, which also take an icon. @public */
 interface HyperLinkActionProps extends HyperLinkPartProps {
     /** Icon override; falls back to `children`, then to the part's default glyph. */
-    icon?: ReactNode;
+    icon?: DocxEditorChildren;
 }
 /** Props for `DocxEditor.HyperLink`. @public */
 interface HyperLinkProps extends HyperLinkPartProps {
@@ -1606,7 +1804,7 @@ declare function DocxEditorNotesChrome({ className, }: DocxEditorNotesChromeProp
 /** Props for a packaged context-menu row. @public */
 interface ContextMenuCommandProps {
     /** Icon override. Defaults to the row's own Material Symbol. */
-    icon?: ReactNode;
+    icon?: DocxEditorChildren;
     /** i18n key for the label, overriding the packaged one. */
     labelKey?: string;
     /** i18n key for the shortcut column, overriding the packaged one. */
@@ -1703,7 +1901,7 @@ interface ContextMenuItemProps {
      * action, so the host's own catalogue resolves it. The packaged rows go the other way.
      */
     label: string;
-    icon?: ReactNode;
+    icon?: DocxEditorChildren;
     /** Right-aligned shortcut text, already resolved. */
     shortcut?: string;
     disabled?: boolean;
@@ -1743,7 +1941,7 @@ interface DocxEditorContextMenuProps {
     disabled?: boolean;
     /** Notified whenever the panel opens or closes. */
     onOpenChange?: (open: boolean) => void;
-    children?: ReactNode;
+    children?: DocxEditorChildren;
 }
 /**
  * The packaged right-click menu over the painted document.
@@ -1795,6 +1993,45 @@ interface ContextMenuAnchor {
     readonly x: number;
     readonly y: number;
 }
+interface ContextMenuContextValue {
+    /**
+     * Close the panel. `restoreFocus` on the paths where the user is FINISHING with the menu
+     * (selecting a row); not on the ones where they are already going elsewhere.
+     */
+    readonly close: (restoreFocus?: boolean) => void;
+    /** Non-null exactly while the panel is open. */
+    readonly anchor: ContextMenuAnchor | null;
+    /**
+     * The table of contents this open was over, captured AT OPEN TIME.
+     *
+     * Read imperatively from the editor in the same event that opens the panel, not
+     * subscribed to. The engine records the right-click target and the panel opens from the
+     * same event, so a subscription is a render behind: the first right-click on a TOC drew
+     * the menu without its rows and only a second one had them. It is also the more honest
+     * shape — an open menu describes the gesture that opened it, whatever happens next.
+     */
+    readonly tocId: string | null;
+    /**
+     * The element the opening right-click landed on, captured AT OPEN TIME like {@link tocId}.
+     *
+     * What lets a contextual row decide it applies — a custom-node chip, a painted marker —
+     * without installing a second `contextmenu` listener that could disagree with the one
+     * that opened the panel. Null while closed, and for keyboard-invoked opens, which have
+     * no pointer target.
+     */
+    readonly target: HTMLElement | null;
+    /**
+     * The browser's reason for refusing a clipboard READ, once one has actually been refused.
+     *
+     * Lives on the ROOT rather than in the Paste row because selecting that row closes the
+     * panel, which unmounts the row — state kept there was written and discarded in the same
+     * batch, so the row it was meant to disable came back enabled on the next right-click and
+     * the documented behaviour never once happened. Firefox and Safari refuse every read, so
+     * "ask once, then stop offering it" has to outlive one open.
+     */
+    readonly clipboardRefusal: string | null;
+    readonly reportClipboardRefusal: (reason: string) => void;
+}
 /**
  * The element the opening right-click landed on, or null while the menu is closed.
  *
@@ -1810,11 +2047,11 @@ interface ContentControlPartProps {
     className?: string;
     asChild?: boolean;
     hidden?: boolean;
-    children?: ReactNode;
+    children?: DocxEditorChildren;
 }
 /** Props for action parts that also take an icon. @public */
 interface ContentControlActionProps extends ContentControlPartProps {
-    icon?: ReactNode;
+    icon?: DocxEditorChildren;
 }
 /** Props for `DocxEditor.ContentControl`. @public */
 interface ContentControlProps extends ContentControlPartProps {
@@ -1841,7 +2078,8 @@ interface DocxEditorContentControlNamespace {
 }
 declare const DocxEditorContentControl: DocxEditorContentControlNamespace;
 
-type EditorMode = 'edit' | 'view';
+type EditorMode = 'edit' | 'view' | 'suggesting';
+
 /**
  * Props for the React `DocxEditor`. The adapter is a thin renderer over the
  * `Editor` contract; it holds no editing-engine state of its own and never
@@ -1864,8 +2102,8 @@ interface DocxEditorProps {
      * toggle, Open/New/Save controls — and passes them in; the editor renders them
      * verbatim on either side of the document title.
      */
-    readonly renderTitleBarLeft?: () => ReactNode;
-    readonly renderTitleBarRight?: () => ReactNode;
+    readonly renderTitleBarLeft?: () => DocxEditorChildren;
+    readonly renderTitleBarRight?: () => DocxEditorChildren;
     /**
      * Chrome colour mode. `'system'` follows the OS and re-resolves when it changes.
      * Only the editor CHROME is themed — the document canvas stays Word-faithful.
@@ -1985,9 +2223,20 @@ interface DocxEditorProps {
      * `DocxEditor.HorizontalRuler` / `DocxEditor.VerticalRuler` yourself.
      */
     rulers?: boolean;
-    /** A document to load: DOCX bytes or an existing handle. */
+    /** A document to load: DOCX bytes, `'blank'` for an empty one, or an existing handle.
+     * Omitting it mounts NO document, which is not the same as an empty one. */
     document?: DocumentSource;
-    /** 'edit' (default) or 'view' (read-only). Applied at mount only — not reactive; remount to change. */
+    /**
+     * The mode the editor opens in, matching the toolbar's three-state pill. Applied at
+     * mount only — not reactive; remount to change.
+     *
+     * Defaults to `'edit'`: the packaged editor opens every document ready to type, even
+     * one whose `w:trackRevisions` asks for tracked changes. Pass `'suggesting'` (needs
+     * `modules` with a review module and an `author`) to open in suggesting, or `'view'`
+     * for read-only. To let the DOCUMENT decide — Word's behavior, where
+     * `w:trackRevisions` opens in suggesting — compose `DocxEditor.Root`, which follows
+     * the file's request when `mode` is omitted.
+     */
     mode?: EditorMode;
     /** A fixed scale. Supplying one also makes the mode fixed unless `zoomMode` says otherwise. */
     zoom?: number;
@@ -2011,7 +2260,7 @@ interface DocxEditorProps {
      * `DocxEditorReview` from `@docx-editor.dev/pro/react`). For more control,
      * compose `DocxEditor.Root`/`Viewport`/`Content` directly.
      */
-    children?: ReactNode;
+    children?: DocxEditorChildren;
     className?: string;
     /** Fired after the underlying `Editor` is created. */
     onReady?: (editor: Editor) => void;
@@ -2032,7 +2281,8 @@ interface DocxEditorProps {
  * mirrors capabilities the `Editor` contract already names.
  */
 interface DocxEditorRef {
-    /** Load a document: DOCX bytes or an existing handle. No-op before mount. */
+    /** Load a document: DOCX bytes, `'blank'` for an empty one, or an existing handle.
+     * No-op before mount. */
     load(document: DocumentSource): void;
     /** Serialize the current document; `null` when no editor is mounted. */
     save(): Promise<ArrayBuffer | null>;
@@ -2071,6 +2321,8 @@ interface DocxEditorNamespace extends ForwardRefExoticComponent<DocxEditorProps
     readonly Menu: typeof DocxEditorMenu;
     /** Conditional loading screen: renders while there is no document to paint. */
     readonly Loading: typeof DocxEditorLoading;
+    readonly ColorByChangeType: typeof DocxEditorColorByChangeType;
+    readonly AuthorStyle: typeof DocxEditorAuthorStyle;
     /** Context-fed horizontal ruler with draggable margins (props-driven export stays). */
     readonly HorizontalRuler: typeof DocxEditorHorizontalRuler;
     /** Context-fed vertical ruler with draggable margins (props-driven export stays). */
@@ -2113,49 +2365,111 @@ interface DocxEditorNamespace extends ForwardRefExoticComponent<DocxEditorProps
 }
 declare const DocxEditor: DocxEditorNamespace;
 
+/** @internal Test seam — count of mounted {@link useEditorState} multiplexed subscriptions. */
+declare function editorStateActiveSubscriptionCount(): number;
+/** Optional lifecycle hooks for test instrumentation. @internal */
+interface UseEditorStateOptions {
+    readonly onSubscribe?: () => void;
+    readonly onUnsubscribe?: () => void;
+}
 /**
- * The editor instance from the nearest `DocxEditor.Root`, or `null` before the Root's
- * mount effect has created it (and outside any Root). Deliberately not a throwing
- * variant: pre-mount is a normal frame every consumer renders through, and the state
- * hooks built on this already answer it with a typed loading snapshot.
+ * Subscribe to a slice of the editor's read model. Re-renders the component ONLY when
+ * `selector`'s result changes (by `isEqual`, default `Object.is`).
+ *
+ * Before the editor exists — outside a `DocxEditor.Root`, pre-mount, and on the
+ * server — the selector receives a frozen loading snapshot (`isLoading: true`,
+ * `page: {current: 0, total: 0}`), never `null`.
  *
  * @public
  */
-declare function useDocxEditor(): DocxEditorInstance | null;
+declare function useEditorState<T>(selector: (snapshot: EditorSnapshot) => T, isEqual?: (a: T, b: T) => boolean, options?: UseEditorStateOptions): T;
+
 /**
- * Whether a review rail is mounted under this Root, and how much room it wants.
+ * The scope class a chrome part should add to its own root element: the class
+ * when nothing above it is scoped, an empty string when something already is.
  *
- * The GUTTER is the reason this exists. `DocxEditor.Viewport` reserves space beside the
- * page for the pane, and the ruler shifts by the same amount — but neither of them can see
- * whether a rail was actually composed in. Keyed on the pane's open state alone, every
- * consumer of the tier-2 `<DocxEditor>` sugar (which mounts no rail) had its page pushed
- * 158px off centre beside an empty column.
+ * ```tsx
+ * const scope = useScopeClassName();
+ * <div className={`${scope}docx-toolbar`} />
+ * ```
  *
- * A rail registers on mount and unregisters on unmount, so the reservation follows what is
- * really on screen. Count rather than boolean: StrictMode mounts twice, and a host may
- * legitimately compose two rails.
+ * Returns a trailing space so it concatenates cleanly, and `''` collapses away.
  */
-interface ReviewRailRegistry {
-    readonly mounted: number;
-    readonly register: () => () => void;
+declare function useScopeClassName(): '' | 'docx-editor ';
+
+/** Full reservation: the 300px card column plus its 16px gutter off the page edge. */
+declare const REVIEW_PANE_GUTTER = 316;
+/** The marker strip: anchors and the add-comment button, no cards. */
+declare const REVIEW_MARKERS_GUTTER = 44;
+/** What the scroll container reserves on each edge, in px. */
+interface ReviewGutter {
+    readonly inlineStart: number;
+    readonly inlineEnd: number;
 }
-declare const ReviewRailContext: react.Context<ReviewRailRegistry | null>;
+interface ReviewGutterInput {
+    /** Whether the pane is showing its cards (`snapshot.reviewPaneOpen`). */
+    readonly open: boolean;
+    /** Client width of the scroll container. */
+    readonly viewportWidth: number;
+    /** The width the page is entitled to paint at — authored width times the entitled zoom. */
+    readonly pageWidthPx: number;
+    /**
+     * Start-edge room OTHER chrome is asking for — an open navigation pane's reservation.
+     * Without it the column judged only page-against-viewport, stood in the two-pane case,
+     * and the pane's displacement then squeezed the fit below the page's entitlement — the
+     * very symptom the measurement exists to remove. The STATIC ask (open pane × width),
+     * never the pane's computed shift: the shift depends on this gutter, and reading it
+     * back would close a cycle the two reservations then chase around.
+     */
+    readonly inlineStartReservation?: number;
+    /**
+     * An uncapped fit is in force: the page fills whatever box it is given, so there is no
+     * entitlement to measure the leftover against. The full column stands.
+     */
+    readonly docked?: boolean;
+}
+/**
+ * The paddings, in px, the scroll container reserves for the review rail.
+ *
+ * Returns the FULL column for a degenerate measurement (a viewport that has not been
+ * laid out yet, a document with no page setup) rather than guessing: that is the value
+ * the stylesheet fell back to before this measurement existed, so an unmeasured first
+ * frame paints exactly as it always did and collapses only once there is a real width
+ * to decide by.
+ */
+declare function reviewGutter({ open, viewportWidth, pageWidthPx, inlineStartReservation, docked, }: ReviewGutterInput): ReviewGutter;
+/**
+ * The gutter the review rail reserves right now: nothing with no rail mounted, and the
+ * measured `reviewGutter` pair otherwise. The one source for the scroll container's
+ * paddings and both rulers.
+ *
+ * The result is reference-stable — the pure function answers with one of three shared
+ * constants — and the hook stores THAT, never the raw width: a resize sweeps through
+ * hundreds of widths that all resolve to the same constant, and holding the width as
+ * state re-rendered every consumer (the review rail among them) once per pixel. Storing
+ * the derived constant lets the state setter bail on identity, so consumers re-render
+ * only when the reservation actually flips.
+ */
+declare function useReviewGutter(): ReviewGutter;
 
 interface SlotProps extends HTMLAttributes<HTMLElement> {
-    children?: ReactNode;
+    children?: DocxEditorChildren;
     /** Fanned out alongside the child's own ref. */
     ref?: Ref<unknown>;
+    className?: string;
+    style?: CSSProperties;
 }
 /** Renders its single child element with the slot's props merged in. */
 declare function Slot({ children, ...slotProps }: SlotProps): ReactElement<unknown, string | react.JSXElementConstructor<any>> | null;
 
 interface LocaleProviderProps {
     i18n?: Translations;
-    children: ReactNode;
+    children: DocxEditorChildren;
 }
 declare function LocaleProvider({ i18n, children }: LocaleProviderProps): react.JSX.Element;
 declare function useTranslation(): {
     t: TFunction;
+    catalogue: LocaleStrings;
 };
 
 /**
@@ -2264,6 +2578,15 @@ interface UseHyperlinkPopupResult {
      */
     openTarget: () => boolean;
 }
+/**
+ * A field-derived link (a `HYPERLINK` field's instruction) rather than a typed
+ * `w:hyperlink`. Structurally signalled: the field registry mints every record with no
+ * addressable range (`paragraphId` stays empty), because no `w:hyperlink` node backs it.
+ * The typed editing lane (edit / unlink) can never resolve its id, so chrome offers neither
+ * action. Caret dismissal DOES apply: the field is a one-unit atom, and `fieldLinkAtCaret`
+ * resolves the caret onto it (boundary-inclusive) so the panel closes when the caret leaves.
+ */
+declare function isFieldLink(link: SurfaceHyperlink): boolean;
 /**
  * The hyperlink popover's behavior.
  *
@@ -2294,7 +2617,16 @@ type DocxFontsInput = FontConfiguration | FontConfigurationFragment;
  * @public
  */
 type DocxFontsSource = DocxFontsInput | Promise<DocxFontsInput> | (() => DocxFontsInput | Promise<DocxFontsInput>);
-/** What the document itself can be: a URL to fetch, or bytes already in hand. @public */
+/**
+ * What the document itself can be: a URL to fetch, or bytes already in hand.
+ *
+ * A string here is ALWAYS a URL — this hook exists to fetch one. That is the opposite of
+ * the `document` prop, whose `DocumentSource` reads the string `'blank'` as Word's blank
+ * template; `useDocxSource('blank')` would request `./blank` and report the 404. There is
+ * nothing to fetch for an empty document, so pass `'blank'` straight to `document`.
+ *
+ * @public
+ */
 type DocxSource = string | URL | Uint8Array | ArrayBuffer;
 /** Options for {@link useDocxSource}. @public */
 interface UseDocxSourceOptions {
@@ -2465,22 +2797,33 @@ declare function useContentControl(): UseContentControlResult;
  */
 declare function useContentControlInstance(): UseContentControlResult;
 
-/** Optional lifecycle hooks for test instrumentation. @internal */
-interface UseEditorStateOptions {
-    readonly onSubscribe?: () => void;
-    readonly onUnsubscribe?: () => void;
-}
 /**
- * Subscribe to a slice of the editor's read model. Re-renders the component ONLY when
- * `selector`'s result changes (by `isEqual`, default `Object.is`).
+ * Every author the review surface DRAWS, in Word's slot order, with the colour and style
+ * each resolves to. `[]` before an editor or document exists.
  *
- * Before the editor exists — outside a `DocxEditor.Root`, pre-mount, and on the
- * server — the selector receives a frozen loading snapshot (`isLoading: true`,
- * `page: {current: 0, total: 0}`), never `null`.
+ * Both halves of review: authors of tracked changes first, numbered by where their first
+ * change appears, then authors who only commented. One person is one colour across the two.
+ *
+ * A read of the rendered projection, not of the package: a resolved view hides the
+ * revisions it has resolved away, so an author whose only change is hidden there is listed
+ * only if they also commented.
+ *
+ * The array is reference-stable between changes (the facade caches per layout and colour
+ * state), so it is safe as a dependency and under `useSyncExternalStore`.
+ *
+ * Pairs with the declarative components: read the roster here, declare the styling as
+ * `<DocxEditor.AuthorStyle>` elements.
+ *
+ * ```tsx
+ * const authors = useReviewAuthors();
+ * authors.map(({ author }) => (
+ *   <DocxEditor.AuthorStyle key={author} author={author} color={myTeam[author]?.color} />
+ * ));
+ * ```
  *
  * @public
  */
-declare function useEditorState<T>(selector: (snapshot: EditorSnapshot) => T, isEqual?: (a: T, b: T) => boolean, options?: UseEditorStateOptions): T;
+declare function useReviewAuthors(): readonly ReviewAuthorInfo[];
 
 /** What {@link useZoom} answers. @public */
 interface UseZoomResult {
@@ -2598,6 +2941,23 @@ declare function useEditorValueCommand(slotId: 'image.wrap'): EditorValueCommand
  */
 declare function useEditorValueCommand(slotId: 'image.altText'): EditorValueCommandState<string>;
 
+/** @public */
+type DocxEditorRefCallback<T> = (node: T | null) => void;
+
+type AnchorPlacement = 'before' | 'after' | 'story-label';
+interface ScopedChromeAnchor {
+    readonly ref: DocxEditorRefCallback<HTMLDivElement>;
+    readonly style: CSSProperties;
+}
+/**
+ * Attach contextual chrome to a painted story instead of the top of the editor viewport.
+ *
+ * The engine owns and may replace everything inside the paginated surface, so React cannot
+ * portal controls into a header, footer, or note node. This hook keeps the controls as a
+ * sibling overlay and derives only their screen placement from the current painted host.
+ */
+declare function useScopedChromeAnchor(findAnchor: (viewport: HTMLElement) => HTMLElement | null, placement: AnchorPlacement): ScopedChromeAnchor;
+
 /**
  * Subscribe to an editor event (`'change'`, `'selectionChange'`, `'error'`, …) for the
  * lifetime of the component. No-op until the nearest `DocxEditor.Root` has created the
@@ -2741,6 +3101,8 @@ interface PaginatedDocxEditorHandle {
     /** Serialize the current document. */
     save(): Uint8Array | null;
 }
+/** Vue name for the same handle contract. @public */
+type PaginatedDocxEditorExpose = PaginatedDocxEditorHandle;
 declare function PaginatedDocxEditor({ source, scale, measurer, onStateChange, onError, className, documentFontFamily, ref, }: PaginatedDocxEditorProps): react.JSX.Element;
 
 interface PaginatedDocxEditorShellProps {
@@ -2760,8 +3122,8 @@ interface PaginatedDocxEditorShellProps {
      * They belong to whoever embeds the editor — a demo's switchers are not editor chrome, and
      * baking them in would ship them to every consumer.
      */
-    readonly renderTitleBarLeft?: () => ReactNode;
-    readonly renderTitleBarRight?: () => ReactNode;
+    readonly renderTitleBarLeft?: () => DocxEditorChildren;
+    readonly renderTitleBarRight?: () => DocxEditorChildren;
     /** Commands, forwarded from the editor the shell hosts. */
     readonly ref?: Ref<PaginatedDocxEditorHandle>;
     /** Applies the editor's own dark palette; the document canvas stays Word-faithful. */
@@ -2772,207 +3134,47 @@ interface PaginatedDocxEditorShellProps {
     readonly documentFontFamily?: string;
     readonly className?: string;
 }
+/** @deprecated Use `<DocxEditor>` from the composition layer instead. */
 declare function PaginatedDocxEditorShell({ source, scale, measurer, documentName, onStateChange, onError, onSave, renderTitleBarLeft, renderTitleBarRight, ref, colorMode, onZoomChange, documentFontFamily, className, }: PaginatedDocxEditorShellProps): react.JSX.Element;
 
 /**
- * The horizontal ruler — page margins plus Word's four indent handles.
- *
- * Margins are the grey zones at either end; dragging the grey/white boundary moves them.
- *
- * The indent handles are Word's, not Google's three:
- *
- *   ▽  first line   at leftMargin + left + firstLine
- *   △  hanging      at leftMargin + left      — drags `left`, PINS the first-line marker
- *   ▭  left box     at leftMargin + left      — drags `left`, TAKES the first line with it
- *   △  right        at pageWidth - rightMargin - right
- *
- * The hanging triangle and the left box are coincident horizontally, as in Word, and are
- * separated vertically instead — the box sits below the strip. They differ only in what a
- * drag takes with them.
+ * Paragraph-style preview + option resolution — shared between the React and
+ * Vue toolbars so the style-picker dropdown looks and behaves identically.
  *
- * All the arithmetic lives in the engine (`ruler-indent.ts`), including the snap grid and
- * the clamps, so this file only converts pixels to twips and paints.
+ * Pure logic only: no i18n and no framework CSS types. The returned preview is
+ * a plain `{ fontSize, lineHeight, fontWeight?, fontStyle?, color? }` object,
+ * which is structurally assignable to both React's `CSSProperties` and Vue's
+ * inline-style record, so neither adapter needs a cast. Name localization stays
+ * in the adapters (they own the i18n `t()` boundary).
+ * @packageDocumentation
+ * @public
  */
 
 /**
- * Section page setup as the engine reports it (`Editor.getPageSetup()`) —
- * page size, orientation, and margins, in twips. Derived from the contract.
+ * One entry of `Editor.getDocumentStyles()` — the engine's document-style
+ * summary the picker consumes. Derived from the contract, not re-declared.
+ * @public
  */
-type RulerPageSetup = NonNullable<ReturnType<Editor['getPageSetup']>>;
+type DocumentStyleSummary = ReturnType<Editor['getDocumentStyles']>[number];
+
 /**
- * A tab stop the ruler paints. `position` is twips from the left margin edge —
- * the same value the `removeTabMark` command takes as `positionTwips`.
+ * The paragraph alignments this control understands, in OOXML `w:jc`
+ * vocabulary (`both` is Word's justify; `distribute` renders as justify).
+ * Presentation-only: the dropdown emits the first four.
  */
-interface RulerTabStop {
-    position: number;
-    alignment: 'left' | 'center' | 'right' | 'decimal' | 'bar';
-}
-interface HorizontalRulerProps$1 {
-    pageSetup?: RulerPageSetup | null;
-    zoom?: number;
-    /** Whether the MARGIN handles drag. */
-    editable?: boolean;
-    onLeftMarginChange?: (marginTwips: number) => void;
-    onRightMarginChange?: (marginTwips: number) => void;
-    /** Fires when a margin drag is released — the moment to commit what the drag previewed. */
-    onMarginDragEnd?: () => void;
-    /**
-     * Paint the four indent handles.
-     *
-     * Off by default so a ruler with no paragraph context does not show handles pinned at
-     * zero. When on they are painted whatever `indentEditable` says: Word shows the markers
-     * on a read-only document and simply refuses the drag, and hiding them would remove the
-     * only place a reader can see a paragraph's indents.
-     */
-    showIndentHandles?: boolean;
-    /** The paragraph's indent in twips; `firstLine` is SIGNED, negative for a hanging. */
-    indent?: RulerIndent | null;
-    /** Whether the INDENT handles drag — a different capability from `editable`. */
-    indentEditable?: boolean;
-    /** Fires continuously through an indent drag, for the host to preview. */
-    onIndentChange?: (indent: RulerIndent) => void;
-    /** Fires when an indent drag is released — the moment to commit one undoable step. */
-    onIndentDragEnd?: () => void;
-    unit?: 'inch' | 'cm';
-    className?: string;
-    style?: CSSProperties;
-    tabMarks?: RulerTabStop[] | null;
-    onTabMarkRemove?: (positionTwips: number) => void;
-}
-declare function HorizontalRuler({ pageSetup, zoom, editable, onLeftMarginChange, onRightMarginChange, onMarginDragEnd, showIndentHandles, indent, indentEditable, onIndentChange, onIndentDragEnd, unit, className, style, tabMarks, onTabMarkRemove, }: HorizontalRulerProps$1): react__default.ReactElement;
-
-/**
- * One heading of the engine's outline (`Editor.getOutline()`): text, level,
- * and the block id `Editor.scrollToBlock` accepts. Derived from the contract.
- */
-type OutlineHeading = ReturnType<Editor['getOutline']>[number];
-
-/** One tracked change as the engine reports it (`Editor.getTrackedChanges()`). */
-type TrackedChangeSummary = ReturnType<Editor['getTrackedChanges']>[number];
-interface ScrollPageInfo {
-    currentPage: number;
-    totalPages: number;
-    visible: boolean;
-}
-interface HorizontalRulerProps {
-    pageSetup: RulerPageSetup | undefined;
-    zoom: number;
-    unit: 'inch' | 'cm';
-    editable: boolean;
-    onLeftMarginChange: (marginTwips: number) => void;
-    onRightMarginChange: (marginTwips: number) => void;
-    tabMarks: RulerTabStop[] | null;
-    onTabMarkRemove: (positionTwips: number) => void;
-}
-interface VerticalRulerProps$1 {
-    pageSetup: RulerPageSetup | undefined;
-    zoom: number;
-    unit: 'inch' | 'cm';
-    editable: boolean;
-    onTopMarginChange: (marginTwips: number) => void;
-    onBottomMarginChange: (marginTwips: number) => void;
-}
-interface OutlineProps {
-    headings: readonly OutlineHeading[];
-    onHeadingClick: (blockId: string) => void;
-    onClose: () => void;
-    topOffset: number;
-    scrollLeft: number;
-}
-/**
- * Outer chrome of the editor: i18n + error provider wrappers, the
- * scroll container with its background-click handler, horizontal and
- * vertical rulers, the floating page indicator, document outline panel
- * + toggle button, plus slots for the toolbar, paged-area body,
- * overlays, dialogs, and hidden file inputs.
- *
- * The expanded-sidebar-item highlight styles are computed here from
- * `expandedSidebarItem` + `trackedChanges` because they need to live
- * inside the editor-content `<div>` for proper scoping.
- */
-declare function DocxEditorShell({ i18n, isDark, onEditorError, containerRef, scrollContainerRef, editorContentRef, className, containerStyle, mainContentStyle, editorContainerStyle, showRuler, readOnlyProp, showOutline, showOutlineButton, sidebarOpen, minLayoutWidth, toolbarHeight, editorScrollLeft, expandedSidebarItem, trackedChanges, onScrollContainerMouseDown, onEditorBgMouseDown, onEditorContextMenu, horizontalRulerProps, verticalRulerProps, outlineProps, onToggleOutline, scrollPageInfo, toolbar, pagedArea, overlays, dialogs, fileInputs, }: {
-    i18n: React.ComponentProps<typeof LocaleProvider>['i18n'];
-    isDark?: boolean;
-    onEditorError: (error: Error) => void;
-    containerRef: React.Ref<HTMLDivElement>;
-    scrollContainerRef: React.Ref<HTMLDivElement>;
-    editorContentRef: React.Ref<HTMLDivElement>;
-    className: string | undefined;
-    containerStyle: CSSProperties;
-    mainContentStyle: CSSProperties;
-    editorContainerStyle: CSSProperties;
-    showRuler: boolean;
-    readOnlyProp: boolean | undefined;
-    showOutline: boolean;
-    showOutlineButton: boolean;
-    sidebarOpen: boolean;
-    minLayoutWidth: number;
-    toolbarHeight: number;
-    editorScrollLeft: number;
-    expandedSidebarItem: string | null;
-    trackedChanges: readonly TrackedChangeSummary[];
-    onScrollContainerMouseDown: (e: React.MouseEvent) => void;
-    onEditorBgMouseDown: (e: React.MouseEvent) => void;
-    onEditorContextMenu: (e: React.MouseEvent) => void;
-    horizontalRulerProps: HorizontalRulerProps;
-    verticalRulerProps: VerticalRulerProps$1;
-    outlineProps: OutlineProps;
-    onToggleOutline: () => void;
-    scrollPageInfo: ScrollPageInfo;
-    toolbar: ReactNode;
-    pagedArea: ReactNode;
-    overlays: ReactNode;
-    dialogs: ReactNode;
-    fileInputs: ReactNode;
-}): react.JSX.Element;
-
-/**
- * Paragraph-style preview + option resolution — shared between the React and
- * Vue toolbars so the style-picker dropdown looks and behaves identically.
- *
- * Pure logic only: no i18n and no framework CSS types. The returned preview is
- * a plain `{ fontSize, lineHeight, fontWeight?, fontStyle?, color? }` object,
- * which is structurally assignable to both React's `CSSProperties` and Vue's
- * inline-style record, so neither adapter needs a cast. Name localization stays
- * in the adapters (they own the i18n `t()` boundary).
- * @packageDocumentation
- * @public
- */
-
-/**
- * One entry of `Editor.getDocumentStyles()` — the engine's document-style
- * summary the picker consumes. Derived from the contract, not re-declared.
- * @public
- */
-type DocumentStyleSummary = ReturnType<Editor['getDocumentStyles']>[number];
-
-/**
- * Alignment Dropdown Component (Google Docs style)
- *
- * A single dropdown button for paragraph alignment controls:
- * - Shows current alignment icon + chevron
- * - Opens a floating panel with Left, Center, Right, Justify options
- * - Active option is highlighted
- */
-
-/**
- * The paragraph alignments this control understands, in OOXML `w:jc`
- * vocabulary (`both` is Word's justify; `distribute` renders as justify).
- * Presentation-only: the dropdown emits the first four.
- */
-type ParagraphAlignment = 'left' | 'center' | 'right' | 'both' | 'distribute';
-
-/**
- * Shared FontOption shape + normaliser used by FontPicker components
- * in both adapters. Lifted from packages/react/src/components/ui/
- * normalizeFontFamilies.ts so the type definition has a single home.
- * @packageDocumentation
- * @public
- */
-interface FontOption {
-    name: string;
-    fontFamily: string;
-    category?: 'sans-serif' | 'serif' | 'monospace' | 'other';
+type ParagraphAlignment = 'left' | 'center' | 'right' | 'both' | 'distribute';
+
+/**
+ * Shared FontOption shape + normaliser used by FontPicker components
+ * in both adapters. Lifted from packages/react/src/components/ui/
+ * normalizeFontFamilies.ts so the type definition has a single home.
+ * @packageDocumentation
+ * @public
+ */
+interface FontOption {
+    name: string;
+    fontFamily: string;
+    category?: 'sans-serif' | 'serif' | 'monospace' | 'other';
 }
 
 /**
@@ -2992,19 +3194,6 @@ interface ListState {
     numId?: number;
 }
 
-/**
- * TableToolbar Component
- *
- * Provides controls for editing tables:
- * - Add row above/below
- * - Add column left/right
- * - Delete row/column
- * - Merge cells
- * - Split cell
- *
- * Shows when cursor is in a table.
- */
-
 /**
  * Table editing action types
  */
@@ -3063,18 +3252,6 @@ type TableAction = 'addRowAbove' | 'addRowBelow' | 'addColumnLeft' | 'addColumnR
     styleId: string;
 };
 
-/**
- * Toolbar Component
- *
- * The customizable formatting rail — undo/redo, zoom, styles, fonts,
- * bold/italic/underline, colors, alignment, lists, table/image context,
- * clear formatting. Used standalone (`<Toolbar ...props>`), inside
- * `<EditorToolbar>` (reads from context via `EditorToolbar.Toolbar`), or
- * embedded inline. Also the home of the `ToolbarButton` / `ToolbarGroup` /
- * `ToolbarSeparator` primitives and the shared `FormattingAction` /
- * `SelectionFormatting` / `ToolbarProps` types.
- */
-
 /**
  * Current formatting state of the selection
  */
@@ -3139,6 +3316,7 @@ type FormattingAction = 'bold' | 'italic' | 'underline' | 'strikethrough' | 'sup
 };
 /**
  * Props for the Toolbar (formatting rail) component
+ * @deprecated Use `DocxEditor.Toolbar` from the composition layer instead.
  */
 interface ToolbarProps {
     /** Current formatting of the selection */
@@ -3162,9 +3340,9 @@ interface ToolbarProps {
     /** Whether to enable keyboard shortcuts (default: true) */
     enableShortcuts?: boolean;
     /** Ref to the editor container for keyboard events */
-    editorRef?: react__default.RefObject<HTMLElement>;
+    editorRef?: RefObject<HTMLElement>;
     /** Custom toolbar items to render at the end */
-    children?: ReactNode;
+    children?: DocxEditorChildren;
     /** When true, renders with display:contents so children flow in the parent flex container */
     inline?: boolean;
     /** Whether to show font family picker (default: true) */
@@ -3302,30 +3480,197 @@ interface ToolbarGroupProps {
 /**
  * Individual toolbar button with shadcn styling
  */
+/** @deprecated Use `DocxEditor.Toolbar` button parts instead. */
 declare function ToolbarButton({ active, disabled, title, onClick, children, className, ariaLabel, }: ToolbarButtonProps): react__default.JSX.Element;
 /**
  * Toolbar button group with modern styling
  */
+/** @deprecated Use `DocxEditor.Toolbar` group parts instead. */
 declare function ToolbarGroup({ label, children, className }: ToolbarGroupProps): react__default.JSX.Element;
 /**
  * Icon-based formatting toolbar — undo/redo, zoom, styles, fonts,
  * bold/italic/underline, colors, alignment, lists, table/image context, clear formatting.
  */
+/** @deprecated Use `DocxEditor.Toolbar` from the composition layer instead. */
 declare function Toolbar(explicitProps: ToolbarProps): react__default.JSX.Element;
 
 /**
- * TitleBar and sub-components for the Google Docs-style 2-level toolbar.
+ * The horizontal ruler — page margins plus Word's four indent handles.
+ *
+ * Margins are the grey zones at either end; dragging the grey/white boundary moves them.
+ *
+ * The indent handles are Word's, not Google's three:
+ *
+ *   ▽  first line   at leftMargin + left + firstLine
+ *   △  hanging      at leftMargin + left      — drags `left`, PINS the first-line marker
+ *   ▭  left box     at leftMargin + left      — drags `left`, TAKES the first line with it
+ *   △  right        at pageWidth - rightMargin - right
+ *
+ * The hanging triangle and the left box are coincident horizontally, as in Word, and are
+ * separated vertically instead — the box sits below the strip. They differ only in what a
+ * drag takes with them.
+ *
+ * All the arithmetic lives in the engine (`ruler-indent.ts`), including the snap grid and
+ * the clamps, so this file only converts pixels to twips and paints.
+ */
+
+/**
+ * Section page setup as the engine reports it (`Editor.getPageSetup()`) —
+ * page size, orientation, and margins, in twips. Derived from the contract.
+ */
+type RulerPageSetup = NonNullable<ReturnType<Editor['getPageSetup']>>;
+/**
+ * A tab stop the ruler paints. `position` is twips from the left margin edge —
+ * the same value the `removeTabMark` command takes as `positionTwips`.
+ */
+interface RulerTabStop {
+    position: number;
+    alignment: 'left' | 'center' | 'right' | 'decimal' | 'bar';
+}
+interface HorizontalRulerProps$1 {
+    pageSetup?: RulerPageSetup | null;
+    zoom?: number;
+    /** Whether the MARGIN handles drag. */
+    editable?: boolean;
+    onLeftMarginChange?: (marginTwips: number) => void;
+    onRightMarginChange?: (marginTwips: number) => void;
+    /** Fires when a margin drag is released — the moment to commit what the drag previewed. */
+    onMarginDragEnd?: () => void;
+    /**
+     * Paint the four indent handles.
+     *
+     * Off by default so a ruler with no paragraph context does not show handles pinned at
+     * zero. When on they are painted whatever `indentEditable` says: Word shows the markers
+     * on a read-only document and simply refuses the drag, and hiding them would remove the
+     * only place a reader can see a paragraph's indents.
+     */
+    showIndentHandles?: boolean;
+    /** The paragraph's indent in twips; `firstLine` is SIGNED, negative for a hanging. */
+    indent?: RulerIndent | null;
+    /** Whether the INDENT handles drag — a different capability from `editable`. */
+    indentEditable?: boolean;
+    /** Fires continuously through an indent drag, for the host to preview. */
+    onIndentChange?: (indent: RulerIndent) => void;
+    /** Fires when an indent drag is released — the moment to commit one undoable step. */
+    onIndentDragEnd?: () => void;
+    unit?: 'inch' | 'cm';
+    className?: string;
+    style?: CSSProperties;
+    tabMarks?: RulerTabStop[] | null;
+    onTabMarkRemove?: (positionTwips: number) => void;
+}
+declare function HorizontalRuler({ pageSetup, zoom, editable, onLeftMarginChange, onRightMarginChange, onMarginDragEnd, showIndentHandles, indent, indentEditable, onIndentChange, onIndentDragEnd, unit, className, style, tabMarks, onTabMarkRemove, }: HorizontalRulerProps$1): react__default.ReactElement;
+
+/**
+ * One heading of the engine's outline (`Editor.getOutline()`): text, level,
+ * and the block id `Editor.scrollToBlock` accepts. Derived from the contract.
+ */
+type OutlineHeading = ReturnType<Editor['getOutline']>[number];
+declare const OUTLINE_LEFT_OFFSET = 12;
+declare const OUTLINE_RESERVED_SPACE: number;
+declare const OUTLINE_BUTTON_LEFT_OFFSET = 12;
+declare const OUTLINE_BUTTON_RESERVED_SPACE: number;
+interface DocumentOutlineProps {
+    headings: readonly OutlineHeading[];
+    /** Called with the heading's block id — feed it to `Editor.scrollToBlock`. */
+    onHeadingClick: (blockId: string) => void;
+    onClose: () => void;
+    topOffset?: number;
+    /** Horizontal scroll offset of the editor — outline slides left with the doc. */
+    scrollLeft?: number;
+    /**
+     * Left anchor (px) from the editor area's left edge. Defaults to
+     * OUTLINE_LEFT_OFFSET; the host bumps it past the vertical ruler when one
+     * is shown so the panel doesn't render on top of it.
+     */
+    leftOffset?: number;
+}
+declare const DocumentOutline: react__default.NamedExoticComponent<DocumentOutlineProps>;
+
+/** One tracked change as the engine reports it (`Editor.getTrackedChanges()`). */
+type TrackedChangeSummary = ReturnType<Editor['getTrackedChanges']>[number];
+interface ScrollPageInfo {
+    currentPage: number;
+    totalPages: number;
+    visible: boolean;
+}
+interface HorizontalRulerProps {
+    pageSetup: RulerPageSetup | undefined;
+    zoom: number;
+    unit: 'inch' | 'cm';
+    editable: boolean;
+    onLeftMarginChange: (marginTwips: number) => void;
+    onRightMarginChange: (marginTwips: number) => void;
+    tabMarks: RulerTabStop[] | null;
+    onTabMarkRemove: (positionTwips: number) => void;
+}
+interface VerticalRulerProps$1 {
+    pageSetup: RulerPageSetup | undefined;
+    zoom: number;
+    unit: 'inch' | 'cm';
+    editable: boolean;
+    onTopMarginChange: (marginTwips: number) => void;
+    onBottomMarginChange: (marginTwips: number) => void;
+}
+interface OutlineProps {
+    headings: readonly OutlineHeading[];
+    onHeadingClick: (blockId: string) => void;
+    onClose: () => void;
+    topOffset: number;
+    scrollLeft: number;
+}
+/**
+ * Outer chrome of the editor: i18n + error provider wrappers, the
+ * scroll container with its background-click handler, horizontal and
+ * vertical rulers, the floating page indicator, document outline panel
+ * + toggle button, plus slots for the toolbar, paged-area body,
+ * overlays, dialogs, and hidden file inputs.
  *
- * - TitleBar: two-row layout (row 1: logo + doc name + right actions, row 2: menu bar)
- * - Logo: renders custom logo content left-aligned
- * - DocumentName: editable document name input
- * - MenuBar: File/Format/Insert menus (auto-wired from EditorToolbarContext)
- * - TitleBarRight: right-aligned actions slot
+ * The expanded-sidebar-item highlight styles are computed here from
+ * `expandedSidebarItem` + `trackedChanges` because they need to live
+ * inside the editor-content `<div>` for proper scoping.
  */
+/** @deprecated Use `<DocxEditor>` from the composition layer instead. */
+declare function DocxEditorShell({ i18n, isDark, onEditorError, containerRef, scrollContainerRef, editorContentRef, className, containerStyle, mainContentStyle, editorContainerStyle, showRuler, readOnlyProp, showOutline, showOutlineButton, sidebarOpen, minLayoutWidth, toolbarHeight, editorScrollLeft, expandedSidebarItem, trackedChanges, onScrollContainerMouseDown, onEditorBgMouseDown, onEditorContextMenu, horizontalRulerProps, verticalRulerProps, outlineProps, onToggleOutline, scrollPageInfo, toolbar, pagedArea, overlays, dialogs, fileInputs, }: {
+    i18n: React.ComponentProps<typeof LocaleProvider>['i18n'];
+    isDark?: boolean;
+    onEditorError: (error: Error) => void;
+    containerRef: React.Ref<HTMLDivElement>;
+    scrollContainerRef: React.Ref<HTMLDivElement>;
+    editorContentRef: React.Ref<HTMLDivElement>;
+    className: string | undefined;
+    containerStyle: CSSProperties;
+    mainContentStyle: CSSProperties;
+    editorContainerStyle: CSSProperties;
+    showRuler: boolean;
+    readOnlyProp: boolean | undefined;
+    showOutline: boolean;
+    showOutlineButton: boolean;
+    sidebarOpen: boolean;
+    minLayoutWidth: number;
+    toolbarHeight: number;
+    editorScrollLeft: number;
+    expandedSidebarItem: string | null;
+    trackedChanges: readonly TrackedChangeSummary[];
+    onScrollContainerMouseDown: (e: React.MouseEvent) => void;
+    onEditorBgMouseDown: (e: React.MouseEvent) => void;
+    onEditorContextMenu: (e: React.MouseEvent) => void;
+    horizontalRulerProps: HorizontalRulerProps;
+    verticalRulerProps: VerticalRulerProps$1;
+    outlineProps: OutlineProps;
+    onToggleOutline: () => void;
+    scrollPageInfo: ScrollPageInfo;
+    toolbar: ReactNode;
+    pagedArea: ReactNode;
+    overlays: ReactNode;
+    dialogs: ReactNode;
+    fileInputs: ReactNode;
+}): react.JSX.Element;
 
 interface LogoProps {
     children: ReactNode;
 }
+/** @deprecated Use `<DocxEditor>` title slots instead. */
 declare function Logo({ children }: LogoProps): react__default.JSX.Element;
 interface DocumentNameProps {
     value: string;
@@ -3333,11 +3678,14 @@ interface DocumentNameProps {
     placeholder?: string;
     editable?: boolean;
 }
+/** @deprecated Use `<DocxEditor>` document name slot instead. */
 declare function DocumentName({ value, onChange, placeholder, editable }: DocumentNameProps): react__default.JSX.Element;
 interface TitleBarRightProps {
     children: ReactNode;
 }
+/** @deprecated Use `<DocxEditor>` title slots instead. */
 declare function TitleBarRight({ children }: TitleBarRightProps): react__default.JSX.Element;
+/** @deprecated Use `DocxEditor.Menu` from the composition layer instead. */
 declare function MenuBar(): react__default.JSX.Element;
 interface TitleBarProps {
     children: ReactNode;
@@ -3354,19 +3702,22 @@ interface TitleBarProps {
  * Logo and TitleBarRight span full height. DocumentName + MenuBar
  * stack vertically in the center column.
  */
+/** @deprecated Use `<DocxEditor>` from the composition layer instead. */
 declare function TitleBar({ children }: TitleBarProps): react__default.JSX.Element;
 
+/** @public */
+interface PageIndicatorProps {
+    currentPage: number;
+    totalPages: number;
+    visible: boolean;
+}
 /**
  * Floating page indicator shown next to the scrollbar while the user
  * scrolls a multi-page document. Wrapped so the `{current} of {total}`
  * template runs through `t()`; `useTranslation()` only works inside
  * `<LocaleProvider>`, which `DocxEditor`'s own body is not.
  */
-declare function PageIndicator({ currentPage, totalPages, visible, }: {
-    currentPage: number;
-    totalPages: number;
-    visible: boolean;
-}): react.JSX.Element;
+declare function PageIndicator({ currentPage, totalPages, visible }: PageIndicatorProps): react.JSX.Element;
 
 /**
  * VerticalRuler Component
@@ -3410,16 +3761,4 @@ declare function VerticalRuler({ pageSetup, zoom, editable, onTopMarginChange, o
  */
 declare function useEditorSnapshot(editor: Editor | null): number;
 
-/**
- * @docx-editor.dev/react
- *
- * React adapter for the DOCX editor. A thin renderer over the `Editor`
- * contract from `@docx-editor.dev/core`: it supplies DOM and paints
- * the engine's positioned display list, and holds no editing-engine state.
- *
- * @packageDocumentation
- * @public
- */
-declare const VERSION = "0.0.2";
-
-export { CONTENT_CONTROL_SLOTS, type ChromeTranslate, type ContentControlActionProps, type ContentControlInspectorState, type ContentControlLock, type ContentControlPartProps, type ContentControlProps, type ContentControlSlotId, type ContextMenuAnchor, ContextMenuCellVerticalAlignment, type ContextMenuCommandProps, ContextMenuCopy, ContextMenuCut, ContextMenuDelete, ContextMenuDeleteTable, ContextMenuDeleteTableColumn, ContextMenuDeleteTableRow, ContextMenuInsertColumnLeft, ContextMenuInsertColumnRight, ContextMenuInsertRowAbove, ContextMenuInsertRowBelow, ContextMenuItem, type ContextMenuItemProps, ContextMenuPaste, ContextMenuSelectAll, type ContextMenuTableRowProps, DocumentName, DocxEditor, DocxEditorContent, DocxEditorContentControl, type DocxEditorContentControlNamespace, type DocxEditorContentProps, DocxEditorContextMenu, type DocxEditorContextMenuNamespace, type DocxEditorContextMenuProps, DocxEditorDocumentOutline, type DocxEditorDocumentOutlineProps, DocxEditorFontNotice, type DocxEditorFontNoticeProps, DocxEditorHeaderFooterChrome, type DocxEditorHeaderFooterChromeProps, DocxEditorHorizontalRuler, DocxEditorHyperLink, type DocxEditorHyperLinkNamespace, DocxEditorImagePropertiesDialog, type DocxEditorImagePropertiesDialogProps, DocxEditorLoading, type DocxEditorLoadingComponent, type DocxEditorLoadingProps, DocxEditorLoadingSpinner, type DocxEditorLoadingSpinnerProps, DocxEditorMenu, type DocxEditorMenuNamespace, type DocxEditorMenuProps, type DocxEditorNamespace, DocxEditorNavigation, type DocxEditorNavigationNamespace, type DocxEditorNavigationProps, DocxEditorNotesChrome, type DocxEditorNotesChromeProps, DocxEditorPageSetupDialog, type DocxEditorPageSetupDialogProps, type DocxEditorProps, type DocxEditorRef, DocxEditorRoot, type DocxEditorRootProps, type DocxEditorRulerProps, DocxEditorShell, DocxEditorToolbar, type DocxEditorToolbarNamespace, type DocxEditorToolbarProps, DocxEditorVerticalRuler, DocxEditorViewport, type DocxEditorViewportProps, type DocxFontsInput, type DocxFontsSource, type DocxSource, type EditorCaret, type EditorCommandState, type EditorMode, type EditorValueCommandState, type FontFamilyItemProps, type FontFamilyNamespace, type FontFamilyPartProps, type FontFamilyProps, type FontsInput, type HeaderFooterState, HorizontalRuler, type HorizontalRulerProps$1 as HorizontalRulerProps, type HyperLinkActionProps, type HyperLinkPartProps, type HyperLinkProps, type HyperlinkPopupAnchor, type HyperlinkPopupMode, type HyperlinkPopupState, ImageAltText, ImageInsertProvider, ImageInsertTrigger, ImagePropertiesTrigger, ImageWrap, type IndentUpdate, LocaleProvider, Logo, type MenuActionProps, MenuBar, type MenuGroupProps, type MenuId, type MenuItemProps, type MenuPartComponent, type MenuProps, type MenuReportIssueProps, type MenuRowProps, type MenuSeparatorProps, type MenuSubmenuProps, type MenuTableGridProps, NAVIGATION_PANE_GAP, NAVIGATION_PANE_INSET, NAVIGATION_PANE_WIDTH, NavigationClose, NavigationFind, NavigationHeader, NavigationHeadings, type NavigationPartProps, type NavigationShiftInput, NavigationTab, type NavigationTabProps, type NavigationTab$1 as NavigationTabValue, NavigationTabs, NavigationTitle, NavigationToggle, type NormalizedImagePayload, type NotePropertiesState, type OutlineHeading$1 as OutlineHeading, type OutlineHeadingItem, PageIndicator, type PageSetupUpdate, PaginatedDocxEditor, type PaginatedDocxEditorHandle as PaginatedDocxEditorExpose, type PaginatedDocxEditorHandle, type PaginatedDocxEditorProps, PaginatedDocxEditorShell, type PaginatedDocxEditorShellProps, type ParagraphStyleItemProps, type ParagraphStyleNamespace, type ParagraphStyleOption, type ParagraphStylePartProps, type ParagraphStyleProps, RULER_WIDTH, ReviewRailContext, type ReviewRailRegistry, SEARCH_DEBOUNCE_MS, SEARCH_MATCH_LIMIT, Slot, type SlotProps, type TableBorderColorNamespace, type TableBorderStyleNamespace, type TableBorderTargetNamespace, type TableBorderWidthNamespace, type TableCellFillNamespace, type TableChromeItemProps, type TableChromePartComponent, type TableChromePartProps, TitleBar, TitleBarRight, Toolbar, type ToolbarActionProps, type ToolbarAlignmentComponent, ToolbarButton, type ToolbarButtonProps$1 as ToolbarButtonProps, ToolbarGroup, type ToolbarPartComponent, type ToolbarPartProps, type ToolbarProps, type ToolbarSeparatorProps, type ToolbarSlotPartComponent, type ToolbarSlotPartProps, type ToolbarTranslate, type UseContentControlResult, type UseDocumentOutlineResult, type UseDocumentSearchResult, type UseDocxSourceOptions, type UseDocxSourceResult, type UseFontFamilyResult, type UseHyperlinkPopupResult, type UseNavigationPaneOptions, type UseNavigationPaneResult, type UsePageSetupReturn, type UseParagraphIndentReturn, type UseParagraphStyleResult, type UseZoomResult, VERSION, VerticalRuler, type VerticalRulerProps, navigationPaneReservation, navigationShift, normalizeImageBytes, useChromeTranslate, useContentControl, useContentControlInstance, useContextMenuTarget, useDocumentOutline, useDocumentSearch, useDocxEditor, useDocxSource, useEditorCaret, useEditorCommand, useEditorEvent, useEditorSnapshot, useEditorState, useEditorValueCommand, useFontFamily, useFonts, useHeaderFooterState, useHyperlinkPopup, useHyperlinkPopupInstance, useNavigationPane, useNavigationShift, useNotePropertiesState, useNoteScopeState, usePageSetup, useParagraphIndent, useParagraphStyle, useTableBorderTargetLabel, useTranslation, useZoom };
+export { CONTENT_CONTROL_SLOTS, type ChromeTranslate, type ContentControlActionProps, type ContentControlInspectorState, type ContentControlLock, type ContentControlPartProps, type ContentControlProps, type ContentControlSlotId, type ContextMenuAnchor, ContextMenuCellVerticalAlignment, type ContextMenuCommandProps, type ContextMenuContextValue, ContextMenuCopy, ContextMenuCut, ContextMenuDelete, ContextMenuDeleteTable, ContextMenuDeleteTableColumn, ContextMenuDeleteTableRow, ContextMenuInsertColumnLeft, ContextMenuInsertColumnRight, ContextMenuInsertRowAbove, ContextMenuInsertRowBelow, ContextMenuItem, type ContextMenuItemProps, ContextMenuPaste, ContextMenuRefreshToc, ContextMenuRefreshTocPageNumbers, ContextMenuSelectAll, type ContextMenuTableRowProps, DocumentName, DocumentOutline, DocxEditor, DocxEditorAuthorStyle, type DocxEditorAuthorStyleProps, type DocxEditorChildren, DocxEditorColorByChangeType, DocxEditorContent, DocxEditorContentControl, type DocxEditorContentControlNamespace, type DocxEditorContentProps, DocxEditorContextMenu, type DocxEditorContextMenuNamespace, type DocxEditorContextMenuProps, DocxEditorDocumentOutline, type DocxEditorDocumentOutlineProps, DocxEditorFontNotice, type DocxEditorFontNoticeProps, DocxEditorHeaderFooterChrome, type DocxEditorHeaderFooterChromeProps, DocxEditorHorizontalRuler, DocxEditorHyperLink, type DocxEditorHyperLinkNamespace, DocxEditorImagePropertiesDialog, type DocxEditorImagePropertiesDialogProps, DocxEditorLoading, type DocxEditorLoadingComponent, type DocxEditorLoadingProps, DocxEditorLoadingSpinner, type DocxEditorLoadingSpinnerProps, DocxEditorMenu, type DocxEditorMenuNamespace, type DocxEditorMenuProps, type DocxEditorNamespace, DocxEditorNavigation, type DocxEditorNavigationNamespace, type DocxEditorNavigationProps, DocxEditorNotesChrome, type DocxEditorNotesChromeProps, DocxEditorPageNumber, type DocxEditorPageNumberProps, DocxEditorPageSetupDialog, type DocxEditorPageSetupDialogProps, type DocxEditorProps, type DocxEditorRef, DocxEditorRoot, type DocxEditorRootListeners, type DocxEditorRootProps, type DocxEditorRulerProps, DocxEditorShell, DocxEditorToolbar, type DocxEditorToolbarNamespace, type DocxEditorToolbarProps, DocxEditorVerticalRuler, DocxEditorViewport, type DocxEditorViewportProps, type DocxFontsInput, type DocxFontsSource, type DocxSource, type EditorCaret, type EditorCommandState, type EditorMode, type EditorValueCommandState, type FontFamilyItemProps, type FontFamilyNamespace, type FontFamilyPartProps, type FontFamilyProps, type FontsInput, type HeaderFooterState, HorizontalRuler, type HorizontalRulerProps$1 as HorizontalRulerProps, type HyperLinkActionProps, type HyperLinkPartProps, type HyperLinkProps, type HyperlinkPopupAnchor, type HyperlinkPopupMode, type HyperlinkPopupState, ImageAltText, ImageInsertProvider, ImageInsertTrigger, ImagePropertiesTrigger, type ImagePropertiesTriggerProps, ImageWrap, type IndentUpdate, LocaleProvider, type LocaleProviderProps, Logo, type MaybeRefOrGetter, type MenuActionProps, MenuBar, type MenuGroupProps, type MenuId, type MenuItemProps, type MenuPartComponent, type MenuProps, type MenuReportIssueProps, type MenuRowProps, type MenuSeparatorProps, type MenuSubmenuProps, type MenuTableGridProps, NAVIGATION_PANE_GAP, NAVIGATION_PANE_INSET, NAVIGATION_PANE_WIDTH, NavigationClose, NavigationFind, NavigationHeader, NavigationHeadings, type NavigationPartProps, type NavigationShiftInput, NavigationTab, type NavigationTabProps, type NavigationTab$1 as NavigationTabValue, NavigationTabs, NavigationTitle, NavigationToggle, type NormalizedImagePayload, type NotePropertiesState, OUTLINE_BUTTON_LEFT_OFFSET, OUTLINE_BUTTON_RESERVED_SPACE, OUTLINE_LEFT_OFFSET, OUTLINE_RESERVED_SPACE, type OutlineHeading$1 as OutlineHeading, type OutlineHeadingItem, PageIndicator, type PageIndicatorProps, PageNumberTranslationContext, type PageSetupUpdate, PaginatedDocxEditor, type PaginatedDocxEditorExpose, type PaginatedDocxEditorHandle, type PaginatedDocxEditorProps, PaginatedDocxEditorShell, type PaginatedDocxEditorShellProps, type ParagraphStyleItemProps, type ParagraphStyleNamespace, type ParagraphStyleOption, type ParagraphStylePartProps, type ParagraphStyleProps, type ProvideDocxEditorResult, REVIEW_MARKERS_GUTTER, REVIEW_PANE_GUTTER, RULER_WIDTH, type ReviewGutter, type ReviewGutterInput, ReviewRailContext, type ReviewRailRegistry, SEARCH_DEBOUNCE_MS, SEARCH_MATCH_LIMIT, type ScopedChromeAnchor, Slot, type SlotProps, type TableBorderColorNamespace, type TableBorderStyleNamespace, type TableBorderTargetNamespace, type TableBorderWidthNamespace, type TableCellFillNamespace, type TableChromeItemProps, type TableChromePartComponent, type TableChromePartProps, TitleBar, TitleBarRight, Toolbar, type ToolbarActionProps, type ToolbarAlignmentComponent, ToolbarButton, type ToolbarButtonProps$1 as ToolbarButtonProps, ToolbarContext, type ToolbarContextValue, ToolbarGroup, ToolbarImageProperties, type ToolbarPartComponent, type ToolbarPartProps, type ToolbarProps, type ToolbarSeparatorProps, type ToolbarSlotPartComponent, type ToolbarSlotPartProps, type ToolbarTranslate, type UseContentControlResult, type UseDocumentOutlineResult, type UseDocumentSearchResult, type UseDocxSourceOptions, type UseDocxSourceResult, type UseFontFamilyResult, type UseHyperlinkPopupResult, type UseNavigationPaneOptions, type UseNavigationPaneResult, type UsePageSetupReturn, type UseParagraphIndentReturn, type UseParagraphStyleResult, type UseZoomResult, VERSION, VerticalRuler, type VerticalRulerProps, editorStateActiveSubscriptionCount, isFieldLink, navigationPaneReservation, navigationShift, normalizeImageBytes, useProvidedDocxEditor as provideDocxEditor, reviewGutter, useChromeTranslate, useContentControl, useContentControlInstance, useContextMenuTarget, useDocumentOutline, useDocumentSearch, useDocxEditor, useDocxSource, useEditorCaret, useEditorCommand, useEditorEvent, useEditorSnapshot, useEditorState, useEditorValueCommand, useFontFamily, useFonts, useHeaderFooterState, useHyperlinkPopup, useHyperlinkPopupInstance, useNavigationPane, useNavigationShift, useNotePropertiesState, useNoteScopeState, usePageSetup, useParagraphIndent, useParagraphStyle, useReviewAuthors, useReviewGutter, useScopeClassName, useScopedChromeAnchor, useTableBorderTargetLabel, useToolbarContext, useToolbarLabel, useToolbarLabelFor, useTranslation, useZoom };