@docx-editor.dev/react 2.1.3 → 2.2.0

package/README.md

@@ -18,9 +18,9 @@ WYSIWYG `.docx` editor for React. Opens a Word file in the browser, paints the r
 layout, edits it in place, and writes a `.docx` back out. No upload service, no conversion
 backend: parsing and serialization both happen client-side.
 
-Saving is lossless. Everything you do not edit comes back byte for byte, including the parts
-the editor does not understand: custom XML, embedded fonts, macros, unknown extensions. Two
-oracles gate that in CI, so opening a document here cannot quietly destroy it.
+Saving has a lossless semantic round-trip. Untouched content, unsupported OOXML, and package
+payloads survive editing and save. Two oracles gate that in CI, so opening a document here
+cannot quietly destroy it.
 
 ```bash
 npm install @docx-editor.dev/react

package/dist/index.d.mts

@@ -1,6 +1,6 @@
 import * as react from 'react';
 import react__default, { CSSProperties, ReactNode, ReactElement, ForwardRefExoticComponent, RefAttributes, HTMLAttributes, Ref } from 'react';
-import { DocumentSource, FontConfiguration, Editor, DocumentChange, EditorFontError, TextMatch, ViewScope, DocumentHandle, EditorCommand, EditorScope, ExecResult, EditorSnapshot, EditorEvents, PageSetup, IndentFormatting, ColorValue, Theme } from '@docx-editor.dev/core/contracts/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';
@@ -139,7 +139,20 @@ interface DocxEditorRootProps {
     modules?: readonly EditorModule[];
     /** `'edit'` (default) or `'view'` (read-only). Sampled at mount only. */
     mode?: 'edit' | 'view';
+    /**
+     * 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.
+     */
     zoom?: number;
+    /**
+     * Where the scale comes from. Defaults to `'auto'`: fit the page width, between 50% and
+     * 100%, so a window with room for the sheet renders at 100% and a narrower one shrinks
+     * rather than growing a horizontal scrollbar — down to the floor, past which it scrolls.
+     *
+     * A fit tracks the room beside the page, so opening the comments rail or docking the
+     * navigation pane shrinks the document by what it took. Pass `{ type: 'fixed' }` to opt out.
+     */
+    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). */
     onReady?: (editor: Editor) => void;
@@ -1370,6 +1383,23 @@ interface NavigationShiftInput {
     readonly reservation: number;
     /** Padding already reserved at the inline end, for example by the review rail. */
     readonly inlineEndReservation?: number;
+    /**
+     * Whether the page's WIDTH follows the padding right now.
+     *
+     * This turns the answer binary, and it has to. The proportional branch below assumes a page
+     * of fixed width sitting in a shrinking box, so padding P moves it by P/2. Where the page is
+     * re-scaled to the padded box instead, a partial shift makes the page narrower, which widens
+     * the gutter, which asks for a smaller shift, which makes the page wider — the pane and the
+     * document chase each other every frame and never settle. Docked or not is a fixed point;
+     * anything in between is not.
+     *
+     * NOT "a fit mode is selected". The default fit is capped at 100%, and on any container with
+     * room for the sheet it sits AT that cap with the page a fixed width — exactly the case the
+     * proportional branch was written for. Reading the mode alone docked those containers too
+     * and pushed the page up to 128px further right than the pane needed. The question is
+     * whether the fit is BINDING, which is `zoom < maxZoom`.
+     */
+    readonly docked?: boolean;
 }
 /**
  * The viewport's left padding, in px, that puts the page's left edge exactly at
@@ -1379,7 +1409,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, }: NavigationShiftInput): number;
+declare function navigationShift({ viewportWidth, pageWidthPx, reservation, inlineEndReservation, docked, }: NavigationShiftInput): number;
 
 /**
  * The px the chrome is currently displaced by an open navigation pane. `0` when no pane
@@ -1854,6 +1884,27 @@ interface DocxEditorProps {
      * them renders the raw placeholders for those labels.
      */
     t?: (key: string, params?: Record<string, string | number>) => string;
+    /**
+     * The chrome's language: a locale from `@docx-editor.dev/i18n` (or your own partial
+     * over English). Keys the locale leaves out fall back to English rather than showing
+     * the key.
+     *
+     * ```tsx
+     * import { de } from '@docx-editor.dev/i18n';
+     * <DocxEditor i18n={de} />
+     * ```
+     *
+     * Equivalent to wrapping this editor in `<LocaleProvider i18n={de}>`, which is still
+     * the way to set one language for several editors at once — this prop overrides such a
+     * provider for this editor only. Unlike `locale`, which tells the ENGINE what language
+     * the document is in, this decides what the buttons say.
+     *
+     * Hold it at a stable identity: a catalogue written inline (`i18n={{ toolbar: … }}`) is
+     * a new object every render, and the merged catalogue behind it is what the chrome
+     * memoizes its labels on — so an inline one re-renders every toolbar control on each
+     * render of the host. Put your overrides in a module constant, or memoize them.
+     */
+    i18n?: Translations;
     /**
      * Renders the packaged chrome — title bar and toolbar — around the document.
      * Default `true`. Set `false` for the painted surface alone when the host supplies
@@ -1938,7 +1989,15 @@ interface DocxEditorProps {
     document?: DocumentSource;
     /** 'edit' (default) or 'view' (read-only). Applied at mount only — not reactive; remount to change. */
     mode?: EditorMode;
+    /** A fixed scale. Supplying one also makes the mode fixed unless `zoomMode` says otherwise. */
     zoom?: number;
+    /**
+     * Where the scale comes from. Defaults to `'auto'`: fit the page width, between 50% and
+     * 100%. A fit tracks the room beside the page, so opening comments shrinks the document
+     * instead of pushing it off screen; past the floor it scrolls sideways instead.
+     * `{ type: 'fixed' }` opts out.
+     */
+    zoomMode?: ZoomMode | 'auto';
     locale?: string;
     author?: string;
     /**
@@ -2119,7 +2178,7 @@ type ChromeTranslate = (key: string, params?: Record<string, string | number>) =
  * English by default), with `overrides` consulted first for key-level renames.
  *
  * ```tsx
- * const MY_LABELS = new Map([['toolbar.bold', 'Heavy']]); // module-level: stable identity
+ * const MY_LABELS = new Map([['formattingBar.bold', 'Heavy']]); // module-level: stable identity
  *
  * const t = useChromeTranslate(MY_LABELS);
  * <DocxEditor.Toolbar t={t} />
@@ -2423,6 +2482,46 @@ interface UseEditorStateOptions {
  */
 declare function useEditorState<T>(selector: (snapshot: EditorSnapshot) => T, isEqual?: (a: T, b: T) => boolean, options?: UseEditorStateOptions): T;
 
+/** What {@link useZoom} answers. @public */
+interface UseZoomResult {
+    /** The scale in force, resolved. 1 is 100%. */
+    readonly zoom: number;
+    /** Where {@link UseZoomResult.zoom} came from. Fixed until an implementation says otherwise. */
+    readonly mode: ZoomMode;
+    /** Whether the editor is tracking the viewport rather than holding a number. */
+    readonly isFit: boolean;
+    /** Set a fixed scale. Leaves any fit mode, the same as picking a level in the toolbar. */
+    readonly setZoom: (zoom: number) => void;
+    readonly setMode: (mode: ZoomMode | 'auto') => void;
+    /** Fit the page width and keep fitting: shrink AND grow with the viewport. */
+    readonly fitToWidth: () => void;
+    /** The default: fit the page width, never past 100%. */
+    readonly auto: () => void;
+    /** Back to a plain, untracked 100%. */
+    readonly reset: () => void;
+    readonly zoomIn: () => void;
+    readonly zoomOut: () => void;
+    readonly canZoomIn: boolean;
+    readonly canZoomOut: boolean;
+    /** The ladder the steppers walk, so a custom control shows the same levels. */
+    readonly levels: readonly number[];
+}
+/**
+ * Read and drive the document's zoom.
+ *
+ * ```tsx
+ * const { zoom, isFit, auto, zoomIn } = useZoom();
+ * <button onClick={auto} aria-pressed={isFit}>Fit</button>
+ * <span>{Math.round(zoom * 100)}%</span>
+ * ```
+ *
+ * Outside a `DocxEditor.Root` — and before the editor is created — this reports 100% fixed
+ * and every action is a no-op, so a control can render unconditionally.
+ *
+ * @public
+ */
+declare function useZoom(): UseZoomResult;
+
 /**
  * A caret position: a paragraph and a UTF-16 offset inside it — the shape the write APIs take
  * as their `at`.
@@ -3323,4 +3422,4 @@ declare function useEditorSnapshot(editor: Editor | null): number;
  */
 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, 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 };
+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 };

package/dist/index.d.ts

@@ -1,6 +1,6 @@
 import * as react from 'react';
 import react__default, { CSSProperties, ReactNode, ReactElement, ForwardRefExoticComponent, RefAttributes, HTMLAttributes, Ref } from 'react';
-import { DocumentSource, FontConfiguration, Editor, DocumentChange, EditorFontError, TextMatch, ViewScope, DocumentHandle, EditorCommand, EditorScope, ExecResult, EditorSnapshot, EditorEvents, PageSetup, IndentFormatting, ColorValue, Theme } from '@docx-editor.dev/core/contracts/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';
@@ -139,7 +139,20 @@ interface DocxEditorRootProps {
     modules?: readonly EditorModule[];
     /** `'edit'` (default) or `'view'` (read-only). Sampled at mount only. */
     mode?: 'edit' | 'view';
+    /**
+     * 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.
+     */
     zoom?: number;
+    /**
+     * Where the scale comes from. Defaults to `'auto'`: fit the page width, between 50% and
+     * 100%, so a window with room for the sheet renders at 100% and a narrower one shrinks
+     * rather than growing a horizontal scrollbar — down to the floor, past which it scrolls.
+     *
+     * A fit tracks the room beside the page, so opening the comments rail or docking the
+     * navigation pane shrinks the document by what it took. Pass `{ type: 'fixed' }` to opt out.
+     */
+    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). */
     onReady?: (editor: Editor) => void;
@@ -1370,6 +1383,23 @@ interface NavigationShiftInput {
     readonly reservation: number;
     /** Padding already reserved at the inline end, for example by the review rail. */
     readonly inlineEndReservation?: number;
+    /**
+     * Whether the page's WIDTH follows the padding right now.
+     *
+     * This turns the answer binary, and it has to. The proportional branch below assumes a page
+     * of fixed width sitting in a shrinking box, so padding P moves it by P/2. Where the page is
+     * re-scaled to the padded box instead, a partial shift makes the page narrower, which widens
+     * the gutter, which asks for a smaller shift, which makes the page wider — the pane and the
+     * document chase each other every frame and never settle. Docked or not is a fixed point;
+     * anything in between is not.
+     *
+     * NOT "a fit mode is selected". The default fit is capped at 100%, and on any container with
+     * room for the sheet it sits AT that cap with the page a fixed width — exactly the case the
+     * proportional branch was written for. Reading the mode alone docked those containers too
+     * and pushed the page up to 128px further right than the pane needed. The question is
+     * whether the fit is BINDING, which is `zoom < maxZoom`.
+     */
+    readonly docked?: boolean;
 }
 /**
  * The viewport's left padding, in px, that puts the page's left edge exactly at
@@ -1379,7 +1409,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, }: NavigationShiftInput): number;
+declare function navigationShift({ viewportWidth, pageWidthPx, reservation, inlineEndReservation, docked, }: NavigationShiftInput): number;
 
 /**
  * The px the chrome is currently displaced by an open navigation pane. `0` when no pane
@@ -1854,6 +1884,27 @@ interface DocxEditorProps {
      * them renders the raw placeholders for those labels.
      */
     t?: (key: string, params?: Record<string, string | number>) => string;
+    /**
+     * The chrome's language: a locale from `@docx-editor.dev/i18n` (or your own partial
+     * over English). Keys the locale leaves out fall back to English rather than showing
+     * the key.
+     *
+     * ```tsx
+     * import { de } from '@docx-editor.dev/i18n';
+     * <DocxEditor i18n={de} />
+     * ```
+     *
+     * Equivalent to wrapping this editor in `<LocaleProvider i18n={de}>`, which is still
+     * the way to set one language for several editors at once — this prop overrides such a
+     * provider for this editor only. Unlike `locale`, which tells the ENGINE what language
+     * the document is in, this decides what the buttons say.
+     *
+     * Hold it at a stable identity: a catalogue written inline (`i18n={{ toolbar: … }}`) is
+     * a new object every render, and the merged catalogue behind it is what the chrome
+     * memoizes its labels on — so an inline one re-renders every toolbar control on each
+     * render of the host. Put your overrides in a module constant, or memoize them.
+     */
+    i18n?: Translations;
     /**
      * Renders the packaged chrome — title bar and toolbar — around the document.
      * Default `true`. Set `false` for the painted surface alone when the host supplies
@@ -1938,7 +1989,15 @@ interface DocxEditorProps {
     document?: DocumentSource;
     /** 'edit' (default) or 'view' (read-only). Applied at mount only — not reactive; remount to change. */
     mode?: EditorMode;
+    /** A fixed scale. Supplying one also makes the mode fixed unless `zoomMode` says otherwise. */
     zoom?: number;
+    /**
+     * Where the scale comes from. Defaults to `'auto'`: fit the page width, between 50% and
+     * 100%. A fit tracks the room beside the page, so opening comments shrinks the document
+     * instead of pushing it off screen; past the floor it scrolls sideways instead.
+     * `{ type: 'fixed' }` opts out.
+     */
+    zoomMode?: ZoomMode | 'auto';
     locale?: string;
     author?: string;
     /**
@@ -2119,7 +2178,7 @@ type ChromeTranslate = (key: string, params?: Record<string, string | number>) =
  * English by default), with `overrides` consulted first for key-level renames.
  *
  * ```tsx
- * const MY_LABELS = new Map([['toolbar.bold', 'Heavy']]); // module-level: stable identity
+ * const MY_LABELS = new Map([['formattingBar.bold', 'Heavy']]); // module-level: stable identity
  *
  * const t = useChromeTranslate(MY_LABELS);
  * <DocxEditor.Toolbar t={t} />
@@ -2423,6 +2482,46 @@ interface UseEditorStateOptions {
  */
 declare function useEditorState<T>(selector: (snapshot: EditorSnapshot) => T, isEqual?: (a: T, b: T) => boolean, options?: UseEditorStateOptions): T;
 
+/** What {@link useZoom} answers. @public */
+interface UseZoomResult {
+    /** The scale in force, resolved. 1 is 100%. */
+    readonly zoom: number;
+    /** Where {@link UseZoomResult.zoom} came from. Fixed until an implementation says otherwise. */
+    readonly mode: ZoomMode;
+    /** Whether the editor is tracking the viewport rather than holding a number. */
+    readonly isFit: boolean;
+    /** Set a fixed scale. Leaves any fit mode, the same as picking a level in the toolbar. */
+    readonly setZoom: (zoom: number) => void;
+    readonly setMode: (mode: ZoomMode | 'auto') => void;
+    /** Fit the page width and keep fitting: shrink AND grow with the viewport. */
+    readonly fitToWidth: () => void;
+    /** The default: fit the page width, never past 100%. */
+    readonly auto: () => void;
+    /** Back to a plain, untracked 100%. */
+    readonly reset: () => void;
+    readonly zoomIn: () => void;
+    readonly zoomOut: () => void;
+    readonly canZoomIn: boolean;
+    readonly canZoomOut: boolean;
+    /** The ladder the steppers walk, so a custom control shows the same levels. */
+    readonly levels: readonly number[];
+}
+/**
+ * Read and drive the document's zoom.
+ *
+ * ```tsx
+ * const { zoom, isFit, auto, zoomIn } = useZoom();
+ * <button onClick={auto} aria-pressed={isFit}>Fit</button>
+ * <span>{Math.round(zoom * 100)}%</span>
+ * ```
+ *
+ * Outside a `DocxEditor.Root` — and before the editor is created — this reports 100% fixed
+ * and every action is a no-op, so a control can render unconditionally.
+ *
+ * @public
+ */
+declare function useZoom(): UseZoomResult;
+
 /**
  * A caret position: a paragraph and a UTF-16 offset inside it — the shape the write APIs take
  * as their `at`.
@@ -3323,4 +3422,4 @@ declare function useEditorSnapshot(editor: Editor | null): number;
  */
 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, 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 };
+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 };