@docx-editor.dev/core 2.4.1 → 2.6.0

package/dist/editor.d.cts

@@ -1,31 +1,32 @@
-import { F as FontConfiguration, E as EditorFontError, a as EditorCommand, C as CanResult, Z as ZoomMode } from './editor-DYvC9CZs.cjs';
-export { I as ImageContext, b as ImageCropPercent, c as ImageCropPermille, S as SelectedImageState, d as cropPercentFromCropPermille, e as cropPercentFromPermille, f as cropPercentFromSourceCrop, g as cropPermilleFromCropPercent, h as cropPermilleFromPercent, s as sourceCropFromCropPercent, v as validateImageCropPercent } from './editor-DYvC9CZs.cjs';
-import { L as LayoutShapingOptions } from './shaped-measurer-CBOTJTV_.cjs';
-import { P as PaginatedSurfaceOptions, O as OpenPaginatedResult, a as PaginatedSurface, T as TableCommandPlan, D as DocxEditorInstance } from './index-Bb-QAg_f.cjs';
-export { A as AnchorFrameOrigin, C as CHROME_GROUPS, b as CHROME_MENUS, c as CHROME_UNAVAILABLE_KEY, d as ChromeControl, e as ChromeControlId, f as ChromeControlState, g as ChromeGroup, h as ChromeGroupId, i as ChromeMenu, j as ChromeMenuEntry, k as ChromeMenuId, l as ChromeMenuItemEntry, m as ChromeMenuSeparatorEntry, n as ChromeMenuSubmenuEntry, o as ChromeSlotId, p as DEFAULT_TABLE_CHROME_DRAFT, q as DocxEditorConfig, E as EMU_PER_POINT, F as FinalizedImageOverlayInteraction, r as FontConfigurationBase, s as FontConfigurationFragment, t as FontLoadFailure, u as FontLoadFailureReason, v as FontMeasurementState, w as FontResolutionRequest, x as FontResolver, y as FontUrlSource, H as HyperlinkActivation, z as HyperlinkChromeHandlers, B as HyperlinkOps, I as IMAGE_OVERLAY_NUDGE_PT, G as IMAGE_OVERLAY_NUDGE_SHIFT_PT, J as ImageInteractionSession, K as ImageOverlayScrollPort, L as ImageResizeHandle, M as ImageResizeResult, N as LoadFontsRequest, Q as LoadFontsResult, R as MAX_RESOLVER_FAMILIES, S as OverlayFrameRect, U as PaginatedSurfaceState, V as RunTableChromeCommandResult, W as SelectedDrawingOverlayTarget, X as SurfaceFormatting, Y as SurfaceHyperlink, Z as SurfaceNavigation, _ as SurfaceOverlayCoordinates, $ as TABLE_BORDER_STYLE_OPTIONS, a0 as TABLE_BORDER_TARGET_OPTIONS, a1 as TABLE_BORDER_WIDTH_OPTIONS, a2 as TABLE_CHROME_SLOT_IDS, a3 as TableBorderStyleOption, a4 as TableBorderTargetOption, a5 as TableBorderTargetValue, a6 as TableBorderWidthOption, a7 as TableChromeDraft, a8 as TableChromePick, a9 as TableChromeSlotId, aa as TableInteractionLabelKey, ab as ToolbarCommandState, ac as WORD_DEFAULT_FONT, ad as applyTableChromePick, ae as blankDocumentBytes, af as canExecuteImageCommand, ag as captureImageMutationPreconditions, ah as chromeControlCount, ai as chromeMenuSlots, aj as chromeProbeForSlot, ak as chromeSlotId, al as commandForSlot, am as commandForSlotValue, an as commandForTableChromeSlotValue, ao as composeFontConfiguration, ap as computeImageResizeResult, aq as computeMovedImagePosition, ar as computeResizedImageExtentEmu, as as createDocxEditor, at as createFontSource, au as createImageOverlayScrollPort, av as cssPixelsToLayoutPoints, aw as defaultChromeGroups, ax as defaultTableLabel, ay as emuToOverlayPoints, az as executeImageCommand, aA as finalizeImageOverlayInteraction, aB as formattingBarChromeGroups, aC as isStaleImageInteractionCommit, aD as isTableChromeSlot, aE as layoutPointsToCssPixels, aF as loadFonts, aG as overlayFrameToSheetCssPixels, aH as pointsToEmu, aI as probeTableChromeCommand, aJ as resizePreservesAspect, aK as runSave, aL as runTableChromeCommand, aM as runTableCommand, aN as runToolbarCommand, aO as selectedDrawingOverlayTargetOf, aP as selectedImageStateOf, aQ as surfacePaintScale, aR as tableChromeIconPaths, aS as tableChromeLabelKeyForTarget, aT as tableChromeToolbarState, aU as tableChromeVisible, aV as tableCommandToolbarState, aW as toolbarCommandState, aX as toolbarCommandStates } from './index-Bb-QAg_f.cjs';
+export { D as DEFAULT_IMAGE_RESOURCE_LIMITS, b as ImageDecodePort, c as ImageResourceLimits, R as RenderableImageMime, S as SupportedImageMime, a as VectorImageMime, r as resolveImageResourceLimits, d as resolveSvgIntrinsicSize, s as sniffImageMime, v as validateRasterHeader } from './image-resources-BaHz4QAd.cjs';
+import { i as TreeDocColorValue, d as DrawingPositionInput } from './tree-op-types-CUCwPWjT.cjs';
+export { j as IMAGE_WRAP_TARGETS, b as ImageWrapTarget } from './tree-op-types-CUCwPWjT.cjs';
+import { g as DocumentThemeColorEntry } from './tree-session-b7bggR-S.cjs';
+export { a as TreeApplyResult, c as TreeDocxSessionView } from './tree-session-b7bggR-S.cjs';
+import { F as FontConfiguration, E as EditorFontError, a as EditorSnapshot, b as EditorCommand, C as CanResult, Z as ZoomMode } from './editor-BZEJL3vv.cjs';
+export { I as ImageContext, c as ImageCropPercent, d as ImageCropPermille, S as SelectedImageState, e as cropPercentFromCropPermille, f as cropPercentFromPermille, g as cropPercentFromSourceCrop, h as cropPermilleFromCropPercent, i as cropPermilleFromPercent, s as sourceCropFromCropPercent, v as validateImageCropPercent } from './editor-BZEJL3vv.cjs';
+import { L as LayoutShapingOptions } from './shaped-measurer-C2SJAjV0.cjs';
+import { P as PaginatedSurfaceOptions, O as OpenPaginatedResult, a as PaginatedSurface, T as TableCommandPlan, D as DocxEditorInstance } from './index-_xF7n_z0.cjs';
+export { A as AnchorFrameOrigin, C as CHROME_GROUPS, b as CHROME_MENUS, c as CHROME_UNAVAILABLE_KEY, d as ChromeControl, e as ChromeControlId, f as ChromeControlState, g as ChromeGroup, h as ChromeGroupId, i as ChromeMenu, j as ChromeMenuEntry, k as ChromeMenuId, l as ChromeMenuItemEntry, m as ChromeMenuSeparatorEntry, n as ChromeMenuSubmenuEntry, o as ChromeSlotId, p as DEFAULT_TABLE_CHROME_DRAFT, q as DocxEditorConfig, E as EMU_PER_POINT, F as FinalizedImageOverlayInteraction, r as FontConfigurationBase, s as FontConfigurationFragment, t as FontLoadFailure, u as FontLoadFailureReason, v as FontMeasurementState, w as FontResolutionRequest, x as FontResolver, y as FontUrlSource, H as HyperlinkActivation, z as HyperlinkChromeHandlers, B as HyperlinkOps, I as IMAGE_OVERLAY_NUDGE_PT, G as IMAGE_OVERLAY_NUDGE_SHIFT_PT, J as ImageInteractionSession, K as ImageOverlayScrollPort, L as ImageResizeHandle, M as ImageResizeResult, N as LoadFontsRequest, Q as LoadFontsResult, R as MAX_RESOLVER_FAMILIES, S as OverlayFrameRect, U as PaginatedSurfaceState, V as RunTableChromeCommandResult, W as SelectedDrawingOverlayTarget, X as SurfaceFormatting, Y as SurfaceHyperlink, Z as SurfaceNavigation, _ as SurfaceOverlayCoordinates, $ as TABLE_BORDER_STYLE_OPTIONS, a0 as TABLE_BORDER_TARGET_OPTIONS, a1 as TABLE_BORDER_WIDTH_OPTIONS, a2 as TABLE_CHROME_SLOT_IDS, a3 as TableBorderStyleOption, a4 as TableBorderTargetOption, a5 as TableBorderTargetValue, a6 as TableBorderWidthOption, a7 as TableChromeDraft, a8 as TableChromePick, a9 as TableChromeSlotId, aa as TableInteractionLabelKey, ab as ToolbarCommandState, ac as WORD_DEFAULT_FONT, ad as applyTableChromePick, ae as blankDocumentBytes, af as canExecuteImageCommand, ag as captureImageMutationPreconditions, ah as chromeControlCount, ai as chromeMenuSlots, aj as chromeProbeForSlot, ak as chromeSlotId, al as commandForSlot, am as commandForSlotValue, an as commandForTableChromeSlotValue, ao as composeFontConfiguration, ap as computeImageResizeResult, aq as computeMovedImagePosition, ar as computeResizedImageExtentEmu, as as createDocxEditor, at as createFontSource, au as createImageOverlayScrollPort, av as cssPixelsToLayoutPoints, aw as defaultChromeGroups, ax as defaultTableLabel, ay as emuToOverlayPoints, az as executeImageCommand, aA as finalizeImageOverlayInteraction, aB as formattingBarChromeGroups, aC as isStaleImageInteractionCommit, aD as isTableChromeSlot, aE as layoutPointsToCssPixels, aF as loadFonts, aG as overlayFrameToSheetCssPixels, aH as pointsToEmu, aI as probeTableChromeCommand, aJ as resizePreservesAspect, aK as runSave, aL as runTableChromeCommand, aM as runTableCommand, aN as runToolbarCommand, aO as selectedDrawingOverlayTargetOf, aP as selectedImageStateOf, aQ as surfacePaintScale, aR as tableChromeIconPaths, aS as tableChromeLabelKeyForTarget, aT as tableChromeToolbarState, aU as tableChromeVisible, aV as tableCommandToolbarState, aW as toolbarCommandState, aX as toolbarCommandStates } from './index-_xF7n_z0.cjs';
 import { A as AutomationCapabilities, a as AutomationHost } from './protocol-CD7slqvl.cjs';
 export { CollectReviewItems, EditorModule, EditorModuleRegistry, ReviewModuleContribution, resolveEditorModules } from './contracts/modules.cjs';
 import { ColorValue } from './contracts/types.cjs';
-import { h as TreeDocColorValue, d as DrawingPositionInput } from './tree-op-types-EZXbR8bW.cjs';
-export { i as IMAGE_WRAP_TARGETS, b as ImageWrapTarget } from './tree-op-types-EZXbR8bW.cjs';
-import { f as DocumentThemeColorEntry } from './tree-session-DrMm8Cj2.cjs';
-import { S as SemanticLayout } from './semantic-records-DSD8WENa.cjs';
-export { T as TextMeasurer } from './semantic-records-DSD8WENa.cjs';
-export { D as DEFAULT_IMAGE_RESOURCE_LIMITS, b as ImageDecodePort, c as ImageResourceLimits, R as RenderableImageMime, S as SupportedImageMime, a as VectorImageMime, r as resolveImageResourceLimits, d as resolveSvgIntrinsicSize, s as sniffImageMime, v as validateRasterHeader } from './image-resources-DXvPZvXD.cjs';
-export { S as SectionProperties } from './semantic-cell-selection--ezfezTe.cjs';
-export { R as ReviewModelInput } from './review-support-BJ-YjGmD.cjs';
-export { N as NavigationCommand, S as SemanticPosition, a as SemanticSelection } from './semantic-interaction-2yxdv7q0.cjs';
-export { F as FieldShadingMode } from './semantic-paint-BYjE0Xbl.cjs';
-import './contracts/document.cjs';
-import './revision-projection-72ZApe-g.cjs';
-import './ooxml-tree-BU0e3DVi.cjs';
-import './review-reads-CxgN62yp.cjs';
+import { S as SemanticLayout } from './semantic-records-DEOs3_tE.cjs';
+export { T as TextMeasurer } from './semantic-records-DEOs3_tE.cjs';
+export { S as SectionProperties } from './semantic-cell-selection-BTQFpN0S.cjs';
+export { R as ReviewModelInput } from './review-support-T-riLz4Y.cjs';
+export { N as NavigationCommand, S as SemanticPosition, a as SemanticSelection } from './semantic-interaction-CDNEU_Tx.cjs';
+export { F as FieldShadingMode, R as ReviewAuthorInfo, a as RevisionAuthorAssignments, b as RevisionAuthorStyle, c as RevisionStyles } from './semantic-paint-IjbL-4CT.cjs';
 import './ooxml-package-CR5us6ad.cjs';
-import './custom-node-writes-C5YRoPcc.cjs';
+import './ooxml-tree-BU0e3DVi.cjs';
+import './custom-node-writes-D9G3GKQ7.cjs';
 import './hf-references-CgEOSw3i.cjs';
 import './note-nodes-C6DLxlvj.cjs';
-import './tree-store-UYrGKF_Q.cjs';
+import './tree-store-BqgeCa1Q.cjs';
 import 'prosemirror-model';
+import './contracts/document.cjs';
+import './revision-projection-WzlQGBJx.cjs';
+import './review-reads-Dr0CpW6u.cjs';
 
 interface LayoutShapingInstrumentation {
     readonly onFontByteCopy?: () => void;
@@ -50,6 +51,14 @@ declare function createLayoutShaping(configuration: FontConfiguration, instrumen
  */
 declare function disposeLayoutShaping(shaping: LayoutShapingOptions): void;
 
+/**
+ * What `snapshot()` reports before an editor exists: loading, not editable, nothing
+ * selected, nothing undoable — never invented state.
+ *
+ * @public
+ */
+declare const LOADING_SNAPSHOT: EditorSnapshot;
+
 /** The engine paints at 96 px per inch (twips / 15, 1440 twips per inch). */
 declare const PX_PER_INCH = 96;
 /** Painted pixels per centimetre, derived from {@link PX_PER_INCH}. */
@@ -149,6 +158,13 @@ declare function dragIndent(handle: RulerIndentHandle, positionTwips: number, in
  */
 declare function mountPaginatedSurface(container: HTMLElement, bytes: Uint8Array, options?: PaginatedSurfaceOptions): OpenPaginatedResult;
 
+/**
+ * Stable value identity for a command, including nested payloads.
+ *
+ * @internal
+ */
+declare function editorCommandKey(command: EditorCommand): string;
+
 /** Planner-backed can/plan pair — production gate for table commands. Task 9 maps chrome slots. */
 declare function tableCommandState(command: EditorCommand, surface: PaginatedSurface): {
     readonly can: CanResult;
@@ -308,4 +324,4 @@ declare function validateSetImagePositionCommand(command: {
     readonly relativeToV?: string;
 }, mode: 'frame' | 'simple'): boolean;
 
-export { AUTO_ZOOM_MODE, BROWSER_AUTOMATION_CAPABILITIES, type ColorLowerResult, DRAWING_REL_FROM_H, DRAWING_REL_FROM_V, DocxEditorInstance, DrawingPositionInput, FIT_WIDTH_ZOOM_MODE, OpenPaginatedResult, PX_PER_CM, PX_PER_INCH, PaginatedSurface, PaginatedSurfaceOptions, type RulerDragOptions, type RulerIndent, type RulerIndentHandle, type RulerPageMetrics, type RulerTick, type RulerUnit, SNAP_TWIPS_CM, SNAP_TWIPS_INCH, type SurfaceExtent, TWIPS_PER_CM, TWIPS_PER_INCH, ZOOM_MAX, ZOOM_MIN, applyThemeShade, applyThemeTint, createBrowserAutomationHost, createLayoutShaping, disposeLayoutShaping, dragIndent, generateRulerTicks, handlePosition, lowerColorValueForBorder, lowerColorValueForFill, mountPaginatedSurface, positionInputFromPropertiesCommand, propertiesCommandHasPositionFields, resolveColorValueToCss, resolveThemeColorHex, resolveZoomMode, rulerPageBox, sameZoomMode, snapTwips, surfaceExtent, tableCommandState, toEditorFontError, validateDrawingPositionInput, validateSetImagePositionCommand, validateThemeModifier };
+export { AUTO_ZOOM_MODE, BROWSER_AUTOMATION_CAPABILITIES, type ColorLowerResult, DRAWING_REL_FROM_H, DRAWING_REL_FROM_V, DocxEditorInstance, DrawingPositionInput, FIT_WIDTH_ZOOM_MODE, LOADING_SNAPSHOT, OpenPaginatedResult, PX_PER_CM, PX_PER_INCH, PaginatedSurface, PaginatedSurfaceOptions, type RulerDragOptions, type RulerIndent, type RulerIndentHandle, type RulerPageMetrics, type RulerTick, type RulerUnit, SNAP_TWIPS_CM, SNAP_TWIPS_INCH, type SurfaceExtent, TWIPS_PER_CM, TWIPS_PER_INCH, ZOOM_MAX, ZOOM_MIN, applyThemeShade, applyThemeTint, createBrowserAutomationHost, createLayoutShaping, disposeLayoutShaping, dragIndent, editorCommandKey, generateRulerTicks, handlePosition, lowerColorValueForBorder, lowerColorValueForFill, mountPaginatedSurface, positionInputFromPropertiesCommand, propertiesCommandHasPositionFields, resolveColorValueToCss, resolveThemeColorHex, resolveZoomMode, rulerPageBox, sameZoomMode, snapTwips, surfaceExtent, tableCommandState, toEditorFontError, validateDrawingPositionInput, validateSetImagePositionCommand, validateThemeModifier };

package/dist/editor.d.ts

@@ -1,31 +1,32 @@
-import { F as FontConfiguration, E as EditorFontError, a as EditorCommand, C as CanResult, Z as ZoomMode } from './editor-D1qHfzOt.js';
-export { I as ImageContext, b as ImageCropPercent, c as ImageCropPermille, S as SelectedImageState, d as cropPercentFromCropPermille, e as cropPercentFromPermille, f as cropPercentFromSourceCrop, g as cropPermilleFromCropPercent, h as cropPermilleFromPercent, s as sourceCropFromCropPercent, v as validateImageCropPercent } from './editor-D1qHfzOt.js';
-import { L as LayoutShapingOptions } from './shaped-measurer-BL8g4AcW.js';
-import { P as PaginatedSurfaceOptions, O as OpenPaginatedResult, a as PaginatedSurface, T as TableCommandPlan, D as DocxEditorInstance } from './index-DpY3WZuP.js';
-export { A as AnchorFrameOrigin, C as CHROME_GROUPS, b as CHROME_MENUS, c as CHROME_UNAVAILABLE_KEY, d as ChromeControl, e as ChromeControlId, f as ChromeControlState, g as ChromeGroup, h as ChromeGroupId, i as ChromeMenu, j as ChromeMenuEntry, k as ChromeMenuId, l as ChromeMenuItemEntry, m as ChromeMenuSeparatorEntry, n as ChromeMenuSubmenuEntry, o as ChromeSlotId, p as DEFAULT_TABLE_CHROME_DRAFT, q as DocxEditorConfig, E as EMU_PER_POINT, F as FinalizedImageOverlayInteraction, r as FontConfigurationBase, s as FontConfigurationFragment, t as FontLoadFailure, u as FontLoadFailureReason, v as FontMeasurementState, w as FontResolutionRequest, x as FontResolver, y as FontUrlSource, H as HyperlinkActivation, z as HyperlinkChromeHandlers, B as HyperlinkOps, I as IMAGE_OVERLAY_NUDGE_PT, G as IMAGE_OVERLAY_NUDGE_SHIFT_PT, J as ImageInteractionSession, K as ImageOverlayScrollPort, L as ImageResizeHandle, M as ImageResizeResult, N as LoadFontsRequest, Q as LoadFontsResult, R as MAX_RESOLVER_FAMILIES, S as OverlayFrameRect, U as PaginatedSurfaceState, V as RunTableChromeCommandResult, W as SelectedDrawingOverlayTarget, X as SurfaceFormatting, Y as SurfaceHyperlink, Z as SurfaceNavigation, _ as SurfaceOverlayCoordinates, $ as TABLE_BORDER_STYLE_OPTIONS, a0 as TABLE_BORDER_TARGET_OPTIONS, a1 as TABLE_BORDER_WIDTH_OPTIONS, a2 as TABLE_CHROME_SLOT_IDS, a3 as TableBorderStyleOption, a4 as TableBorderTargetOption, a5 as TableBorderTargetValue, a6 as TableBorderWidthOption, a7 as TableChromeDraft, a8 as TableChromePick, a9 as TableChromeSlotId, aa as TableInteractionLabelKey, ab as ToolbarCommandState, ac as WORD_DEFAULT_FONT, ad as applyTableChromePick, ae as blankDocumentBytes, af as canExecuteImageCommand, ag as captureImageMutationPreconditions, ah as chromeControlCount, ai as chromeMenuSlots, aj as chromeProbeForSlot, ak as chromeSlotId, al as commandForSlot, am as commandForSlotValue, an as commandForTableChromeSlotValue, ao as composeFontConfiguration, ap as computeImageResizeResult, aq as computeMovedImagePosition, ar as computeResizedImageExtentEmu, as as createDocxEditor, at as createFontSource, au as createImageOverlayScrollPort, av as cssPixelsToLayoutPoints, aw as defaultChromeGroups, ax as defaultTableLabel, ay as emuToOverlayPoints, az as executeImageCommand, aA as finalizeImageOverlayInteraction, aB as formattingBarChromeGroups, aC as isStaleImageInteractionCommit, aD as isTableChromeSlot, aE as layoutPointsToCssPixels, aF as loadFonts, aG as overlayFrameToSheetCssPixels, aH as pointsToEmu, aI as probeTableChromeCommand, aJ as resizePreservesAspect, aK as runSave, aL as runTableChromeCommand, aM as runTableCommand, aN as runToolbarCommand, aO as selectedDrawingOverlayTargetOf, aP as selectedImageStateOf, aQ as surfacePaintScale, aR as tableChromeIconPaths, aS as tableChromeLabelKeyForTarget, aT as tableChromeToolbarState, aU as tableChromeVisible, aV as tableCommandToolbarState, aW as toolbarCommandState, aX as toolbarCommandStates } from './index-DpY3WZuP.js';
+export { D as DEFAULT_IMAGE_RESOURCE_LIMITS, b as ImageDecodePort, c as ImageResourceLimits, R as RenderableImageMime, S as SupportedImageMime, a as VectorImageMime, r as resolveImageResourceLimits, d as resolveSvgIntrinsicSize, s as sniffImageMime, v as validateRasterHeader } from './image-resources-Cl5_cNi9.js';
+import { i as TreeDocColorValue, d as DrawingPositionInput } from './tree-op-types-D0fTNBVW.js';
+export { j as IMAGE_WRAP_TARGETS, b as ImageWrapTarget } from './tree-op-types-D0fTNBVW.js';
+import { g as DocumentThemeColorEntry } from './tree-session-CH1oA75f.js';
+export { a as TreeApplyResult, c as TreeDocxSessionView } from './tree-session-CH1oA75f.js';
+import { F as FontConfiguration, E as EditorFontError, a as EditorSnapshot, b as EditorCommand, C as CanResult, Z as ZoomMode } from './editor-D2zOJztO.js';
+export { I as ImageContext, c as ImageCropPercent, d as ImageCropPermille, S as SelectedImageState, e as cropPercentFromCropPermille, f as cropPercentFromPermille, g as cropPercentFromSourceCrop, h as cropPermilleFromCropPercent, i as cropPermilleFromPercent, s as sourceCropFromCropPercent, v as validateImageCropPercent } from './editor-D2zOJztO.js';
+import { L as LayoutShapingOptions } from './shaped-measurer-l4o5ITJ0.js';
+import { P as PaginatedSurfaceOptions, O as OpenPaginatedResult, a as PaginatedSurface, T as TableCommandPlan, D as DocxEditorInstance } from './index-D8L8WrNF.js';
+export { A as AnchorFrameOrigin, C as CHROME_GROUPS, b as CHROME_MENUS, c as CHROME_UNAVAILABLE_KEY, d as ChromeControl, e as ChromeControlId, f as ChromeControlState, g as ChromeGroup, h as ChromeGroupId, i as ChromeMenu, j as ChromeMenuEntry, k as ChromeMenuId, l as ChromeMenuItemEntry, m as ChromeMenuSeparatorEntry, n as ChromeMenuSubmenuEntry, o as ChromeSlotId, p as DEFAULT_TABLE_CHROME_DRAFT, q as DocxEditorConfig, E as EMU_PER_POINT, F as FinalizedImageOverlayInteraction, r as FontConfigurationBase, s as FontConfigurationFragment, t as FontLoadFailure, u as FontLoadFailureReason, v as FontMeasurementState, w as FontResolutionRequest, x as FontResolver, y as FontUrlSource, H as HyperlinkActivation, z as HyperlinkChromeHandlers, B as HyperlinkOps, I as IMAGE_OVERLAY_NUDGE_PT, G as IMAGE_OVERLAY_NUDGE_SHIFT_PT, J as ImageInteractionSession, K as ImageOverlayScrollPort, L as ImageResizeHandle, M as ImageResizeResult, N as LoadFontsRequest, Q as LoadFontsResult, R as MAX_RESOLVER_FAMILIES, S as OverlayFrameRect, U as PaginatedSurfaceState, V as RunTableChromeCommandResult, W as SelectedDrawingOverlayTarget, X as SurfaceFormatting, Y as SurfaceHyperlink, Z as SurfaceNavigation, _ as SurfaceOverlayCoordinates, $ as TABLE_BORDER_STYLE_OPTIONS, a0 as TABLE_BORDER_TARGET_OPTIONS, a1 as TABLE_BORDER_WIDTH_OPTIONS, a2 as TABLE_CHROME_SLOT_IDS, a3 as TableBorderStyleOption, a4 as TableBorderTargetOption, a5 as TableBorderTargetValue, a6 as TableBorderWidthOption, a7 as TableChromeDraft, a8 as TableChromePick, a9 as TableChromeSlotId, aa as TableInteractionLabelKey, ab as ToolbarCommandState, ac as WORD_DEFAULT_FONT, ad as applyTableChromePick, ae as blankDocumentBytes, af as canExecuteImageCommand, ag as captureImageMutationPreconditions, ah as chromeControlCount, ai as chromeMenuSlots, aj as chromeProbeForSlot, ak as chromeSlotId, al as commandForSlot, am as commandForSlotValue, an as commandForTableChromeSlotValue, ao as composeFontConfiguration, ap as computeImageResizeResult, aq as computeMovedImagePosition, ar as computeResizedImageExtentEmu, as as createDocxEditor, at as createFontSource, au as createImageOverlayScrollPort, av as cssPixelsToLayoutPoints, aw as defaultChromeGroups, ax as defaultTableLabel, ay as emuToOverlayPoints, az as executeImageCommand, aA as finalizeImageOverlayInteraction, aB as formattingBarChromeGroups, aC as isStaleImageInteractionCommit, aD as isTableChromeSlot, aE as layoutPointsToCssPixels, aF as loadFonts, aG as overlayFrameToSheetCssPixels, aH as pointsToEmu, aI as probeTableChromeCommand, aJ as resizePreservesAspect, aK as runSave, aL as runTableChromeCommand, aM as runTableCommand, aN as runToolbarCommand, aO as selectedDrawingOverlayTargetOf, aP as selectedImageStateOf, aQ as surfacePaintScale, aR as tableChromeIconPaths, aS as tableChromeLabelKeyForTarget, aT as tableChromeToolbarState, aU as tableChromeVisible, aV as tableCommandToolbarState, aW as toolbarCommandState, aX as toolbarCommandStates } from './index-D8L8WrNF.js';
 import { A as AutomationCapabilities, a as AutomationHost } from './protocol-DsbfgBwA.js';
 export { CollectReviewItems, EditorModule, EditorModuleRegistry, ReviewModuleContribution, resolveEditorModules } from './contracts/modules.js';
 import { ColorValue } from './contracts/types.js';
-import { h as TreeDocColorValue, d as DrawingPositionInput } from './tree-op-types-8a6xyRCN.js';
-export { i as IMAGE_WRAP_TARGETS, b as ImageWrapTarget } from './tree-op-types-8a6xyRCN.js';
-import { f as DocumentThemeColorEntry } from './tree-session-SucW0znF.js';
-import { S as SemanticLayout } from './semantic-records-CR5hTqMK.js';
-export { T as TextMeasurer } from './semantic-records-CR5hTqMK.js';
-export { D as DEFAULT_IMAGE_RESOURCE_LIMITS, b as ImageDecodePort, c as ImageResourceLimits, R as RenderableImageMime, S as SupportedImageMime, a as VectorImageMime, r as resolveImageResourceLimits, d as resolveSvgIntrinsicSize, s as sniffImageMime, v as validateRasterHeader } from './image-resources-BG9DLyW7.js';
-export { S as SectionProperties } from './semantic-cell-selection-DZtyMXkH.js';
-export { R as ReviewModelInput } from './review-support-DgXTIYBW.js';
-export { N as NavigationCommand, S as SemanticPosition, a as SemanticSelection } from './semantic-interaction-DrgbgKg6.js';
-export { F as FieldShadingMode } from './semantic-paint-BedBxkyY.js';
-import './contracts/document.js';
-import './revision-projection-DHAkcD_L.js';
-import './ooxml-tree-BU0e3DVi.js';
-import './review-reads-CQmU9Lcl.js';
+import { S as SemanticLayout } from './semantic-records-CdQvpUj1.js';
+export { T as TextMeasurer } from './semantic-records-CdQvpUj1.js';
+export { S as SectionProperties } from './semantic-cell-selection-B5vfPz4Q.js';
+export { R as ReviewModelInput } from './review-support-D4ZBdUXa.js';
+export { N as NavigationCommand, S as SemanticPosition, a as SemanticSelection } from './semantic-interaction-lvpzZRpA.js';
+export { F as FieldShadingMode, R as ReviewAuthorInfo, a as RevisionAuthorAssignments, b as RevisionAuthorStyle, c as RevisionStyles } from './semantic-paint-BBPL3u5w.js';
 import './ooxml-package-D_CtywTW.js';
-import './custom-node-writes-BkMgMXxs.js';
+import './ooxml-tree-BU0e3DVi.js';
+import './custom-node-writes-tJw8U9MO.js';
 import './hf-references-BdjsQNE_.js';
 import './note-nodes-BPSTVDMr.js';
-import './tree-store-BoM6eXaL.js';
+import './tree-store-CIKASRHk.js';
 import 'prosemirror-model';
+import './contracts/document.js';
+import './revision-projection-UKqvPa4-.js';
+import './review-reads-HDvoQXK2.js';
 
 interface LayoutShapingInstrumentation {
     readonly onFontByteCopy?: () => void;
@@ -50,6 +51,14 @@ declare function createLayoutShaping(configuration: FontConfiguration, instrumen
  */
 declare function disposeLayoutShaping(shaping: LayoutShapingOptions): void;
 
+/**
+ * What `snapshot()` reports before an editor exists: loading, not editable, nothing
+ * selected, nothing undoable — never invented state.
+ *
+ * @public
+ */
+declare const LOADING_SNAPSHOT: EditorSnapshot;
+
 /** The engine paints at 96 px per inch (twips / 15, 1440 twips per inch). */
 declare const PX_PER_INCH = 96;
 /** Painted pixels per centimetre, derived from {@link PX_PER_INCH}. */
@@ -149,6 +158,13 @@ declare function dragIndent(handle: RulerIndentHandle, positionTwips: number, in
  */
 declare function mountPaginatedSurface(container: HTMLElement, bytes: Uint8Array, options?: PaginatedSurfaceOptions): OpenPaginatedResult;
 
+/**
+ * Stable value identity for a command, including nested payloads.
+ *
+ * @internal
+ */
+declare function editorCommandKey(command: EditorCommand): string;
+
 /** Planner-backed can/plan pair — production gate for table commands. Task 9 maps chrome slots. */
 declare function tableCommandState(command: EditorCommand, surface: PaginatedSurface): {
     readonly can: CanResult;
@@ -308,4 +324,4 @@ declare function validateSetImagePositionCommand(command: {
     readonly relativeToV?: string;
 }, mode: 'frame' | 'simple'): boolean;
 
-export { AUTO_ZOOM_MODE, BROWSER_AUTOMATION_CAPABILITIES, type ColorLowerResult, DRAWING_REL_FROM_H, DRAWING_REL_FROM_V, DocxEditorInstance, DrawingPositionInput, FIT_WIDTH_ZOOM_MODE, OpenPaginatedResult, PX_PER_CM, PX_PER_INCH, PaginatedSurface, PaginatedSurfaceOptions, type RulerDragOptions, type RulerIndent, type RulerIndentHandle, type RulerPageMetrics, type RulerTick, type RulerUnit, SNAP_TWIPS_CM, SNAP_TWIPS_INCH, type SurfaceExtent, TWIPS_PER_CM, TWIPS_PER_INCH, ZOOM_MAX, ZOOM_MIN, applyThemeShade, applyThemeTint, createBrowserAutomationHost, createLayoutShaping, disposeLayoutShaping, dragIndent, generateRulerTicks, handlePosition, lowerColorValueForBorder, lowerColorValueForFill, mountPaginatedSurface, positionInputFromPropertiesCommand, propertiesCommandHasPositionFields, resolveColorValueToCss, resolveThemeColorHex, resolveZoomMode, rulerPageBox, sameZoomMode, snapTwips, surfaceExtent, tableCommandState, toEditorFontError, validateDrawingPositionInput, validateSetImagePositionCommand, validateThemeModifier };
+export { AUTO_ZOOM_MODE, BROWSER_AUTOMATION_CAPABILITIES, type ColorLowerResult, DRAWING_REL_FROM_H, DRAWING_REL_FROM_V, DocxEditorInstance, DrawingPositionInput, FIT_WIDTH_ZOOM_MODE, LOADING_SNAPSHOT, OpenPaginatedResult, PX_PER_CM, PX_PER_INCH, PaginatedSurface, PaginatedSurfaceOptions, type RulerDragOptions, type RulerIndent, type RulerIndentHandle, type RulerPageMetrics, type RulerTick, type RulerUnit, SNAP_TWIPS_CM, SNAP_TWIPS_INCH, type SurfaceExtent, TWIPS_PER_CM, TWIPS_PER_INCH, ZOOM_MAX, ZOOM_MIN, applyThemeShade, applyThemeTint, createBrowserAutomationHost, createLayoutShaping, disposeLayoutShaping, dragIndent, editorCommandKey, generateRulerTicks, handlePosition, lowerColorValueForBorder, lowerColorValueForFill, mountPaginatedSurface, positionInputFromPropertiesCommand, propertiesCommandHasPositionFields, resolveColorValueToCss, resolveThemeColorHex, resolveZoomMode, rulerPageBox, sameZoomMode, snapTwips, surfaceExtent, tableCommandState, toEditorFontError, validateDrawingPositionInput, validateSetImagePositionCommand, validateThemeModifier };

package/dist/editor.js

@@ -1 +1 @@
-export{Ea as AUTO_ZOOM_MODE,Ja as BROWSER_AUTOMATION_CAPABILITIES,sa as CHROME_GROUPS,wa as CHROME_MENUS,za as CHROME_UNAVAILABLE_KEY,W as DEFAULT_TABLE_CHROME_DRAFT,O as EMU_PER_POINT,Fa as FIT_WIDTH_ZOOM_MODE,M as IMAGE_OVERLAY_NUDGE_PT,N as IMAGE_OVERLAY_NUDGE_SHIFT_PT,d as MAX_RESOLVER_FAMILIES,k as PX_PER_CM,j as PX_PER_INCH,q as SNAP_TWIPS_CM,p as SNAP_TWIPS_INCH,aa as TABLE_BORDER_STYLE_OPTIONS,$ as TABLE_BORDER_TARGET_OPTIONS,ba as TABLE_BORDER_WIDTH_OPTIONS,X as TABLE_CHROME_SLOT_IDS,o as TWIPS_PER_CM,n as TWIPS_PER_INCH,e as WORD_DEFAULT_FONT,Da as ZOOM_MAX,Ca as ZOOM_MIN,ca as applyTableChromePick,w as applyThemeShade,v as applyThemeTint,g as blankDocumentBytes,K as canExecuteImageCommand,J as captureImageMutationPreconditions,ya as chromeControlCount,xa as chromeMenuSlots,ga as chromeProbeForSlot,ta as chromeSlotId,ha as commandForSlot,ja as commandForSlotValue,ia as commandForTableChromeSlotValue,f as composeFontConfiguration,Qa as computeImageResizeResult,T as computeMovedImagePosition,S as computeResizedImageExtentEmu,Ka as createBrowserAutomationHost,Ia as createDocxEditor,i as createFontSource,Ra as createImageOverlayScrollPort,b as createLayoutShaping,G as cropPercentFromCropPermille,E as cropPercentFromPermille,B as cropPercentFromSourceCrop,F as cropPermilleFromCropPercent,D as cropPermilleFromPercent,Na as cssPixelsToLayoutPoints,ua as defaultChromeGroups,Y as defaultTableLabel,c as disposeLayoutShaping,t as dragIndent,R as emuToOverlayPoints,L as executeImageCommand,Sa as finalizeImageOverlayInteraction,va as formattingBarChromeGroups,l as generateRulerTicks,r as handlePosition,U as isStaleImageInteractionCommit,Z as isTableChromeSlot,Ma as layoutPointsToCssPixels,h as loadFonts,y as lowerColorValueForBorder,z as lowerColorValueForFill,Ba as mountPaginatedSurface,Oa as overlayFrameToSheetCssPixels,Q as pointsToEmu,da as probeTableChromeCommand,Pa as resizePreservesAspect,A as resolveColorValueToCss,x as resolveThemeColorHex,Ga as resolveZoomMode,m as rulerPageBox,pa as runSave,na as runTableChromeCommand,ra as runTableCommand,oa as runToolbarCommand,Ha as sameZoomMode,P as selectedDrawingOverlayTargetOf,I as selectedImageStateOf,s as snapTwips,C as sourceCropFromCropPercent,Aa as surfaceExtent,La as surfacePaintScale,fa as tableChromeIconPaths,ea as tableChromeLabelKeyForTarget,ka as tableChromeToolbarState,_ as tableChromeVisible,V as tableCommandState,qa as tableCommandToolbarState,a as toEditorFontError,la as toolbarCommandState,ma as toolbarCommandStates,H as validateImageCropPercent,u as validateThemeModifier}from'./chunk-FL4GWK76.js';import'./chunk-F6WNPYOM.js';import'./chunk-SG7OH2EK.js';import'./chunk-ZACHY6OS.js';import'./chunk-LIJPSHRA.js';import'./chunk-4WWEDTTE.js';import'./chunk-33F6TRXO.js';export{D as DEFAULT_IMAGE_RESOURCE_LIMITS,qf as DRAWING_REL_FROM_H,rf as DRAWING_REL_FROM_V,Wa as IMAGE_WRAP_TARGETS,tf as positionInputFromPropertiesCommand,sf as propertiesCommandHasPositionFields,E as resolveImageResourceLimits,nb as resolveSvgIntrinsicSize,jb as sniffImageMime,pf as validateDrawingPositionInput,ob as validateRasterHeader,uf as validateSetImagePositionCommand}from'./chunk-TCX3PVWR.js';import'./chunk-GOEBQ26R.js';export{a as resolveEditorModules}from'./chunk-GQQOL4PV.js';
+export{Ga as AUTO_ZOOM_MODE,La as BROWSER_AUTOMATION_CAPABILITIES,ua as CHROME_GROUPS,ya as CHROME_MENUS,Ba as CHROME_UNAVAILABLE_KEY,X as DEFAULT_TABLE_CHROME_DRAFT,P as EMU_PER_POINT,Ha as FIT_WIDTH_ZOOM_MODE,N as IMAGE_OVERLAY_NUDGE_PT,O as IMAGE_OVERLAY_NUDGE_SHIFT_PT,d as LOADING_SNAPSHOT,e as MAX_RESOLVER_FAMILIES,l as PX_PER_CM,k as PX_PER_INCH,r as SNAP_TWIPS_CM,q as SNAP_TWIPS_INCH,ba as TABLE_BORDER_STYLE_OPTIONS,aa as TABLE_BORDER_TARGET_OPTIONS,ca as TABLE_BORDER_WIDTH_OPTIONS,Y as TABLE_CHROME_SLOT_IDS,p as TWIPS_PER_CM,o as TWIPS_PER_INCH,f as WORD_DEFAULT_FONT,Fa as ZOOM_MAX,Ea as ZOOM_MIN,da as applyTableChromePick,x as applyThemeShade,w as applyThemeTint,h as blankDocumentBytes,L as canExecuteImageCommand,K as captureImageMutationPreconditions,Aa as chromeControlCount,za as chromeMenuSlots,ha as chromeProbeForSlot,va as chromeSlotId,ia as commandForSlot,ka as commandForSlotValue,ja as commandForTableChromeSlotValue,g as composeFontConfiguration,Sa as computeImageResizeResult,U as computeMovedImagePosition,T as computeResizedImageExtentEmu,Ma as createBrowserAutomationHost,Ka as createDocxEditor,j as createFontSource,Ta as createImageOverlayScrollPort,b as createLayoutShaping,H as cropPercentFromCropPermille,F as cropPercentFromPermille,C as cropPercentFromSourceCrop,G as cropPermilleFromCropPercent,E as cropPermilleFromPercent,Pa as cssPixelsToLayoutPoints,wa as defaultChromeGroups,Z as defaultTableLabel,c as disposeLayoutShaping,u as dragIndent,ta as editorCommandKey,S as emuToOverlayPoints,M as executeImageCommand,Ua as finalizeImageOverlayInteraction,xa as formattingBarChromeGroups,m as generateRulerTicks,s as handlePosition,V as isStaleImageInteractionCommit,_ as isTableChromeSlot,Oa as layoutPointsToCssPixels,i as loadFonts,z as lowerColorValueForBorder,A as lowerColorValueForFill,Da as mountPaginatedSurface,Qa as overlayFrameToSheetCssPixels,R as pointsToEmu,ea as probeTableChromeCommand,Ra as resizePreservesAspect,B as resolveColorValueToCss,y as resolveThemeColorHex,Ia as resolveZoomMode,n as rulerPageBox,qa as runSave,oa as runTableChromeCommand,sa as runTableCommand,pa as runToolbarCommand,Ja as sameZoomMode,Q as selectedDrawingOverlayTargetOf,J as selectedImageStateOf,t as snapTwips,D as sourceCropFromCropPercent,Ca as surfaceExtent,Na as surfacePaintScale,ga as tableChromeIconPaths,fa as tableChromeLabelKeyForTarget,la as tableChromeToolbarState,$ as tableChromeVisible,W as tableCommandState,ra as tableCommandToolbarState,a as toEditorFontError,ma as toolbarCommandState,na as toolbarCommandStates,I as validateImageCropPercent,v as validateThemeModifier}from'./chunk-NIGGABAA.js';import'./chunk-WAVN7MAT.js';import'./chunk-OPKOTVQQ.js';import'./chunk-WU7PUTVA.js';import'./chunk-E7BXJ4BF.js';import'./chunk-4GQXAXTZ.js';import'./chunk-UVIUNAQ6.js';import'./chunk-SMRD66T5.js';export{E as DEFAULT_IMAGE_RESOURCE_LIMITS,vf as DRAWING_REL_FROM_H,wf as DRAWING_REL_FROM_V,Xa as IMAGE_WRAP_TARGETS,yf as positionInputFromPropertiesCommand,xf as propertiesCommandHasPositionFields,F as resolveImageResourceLimits,ob as resolveSvgIntrinsicSize,kb as sniffImageMime,uf as validateDrawingPositionInput,pb as validateRasterHeader,zf as validateSetImagePositionCommand}from'./chunk-R75OLPL6.js';import'./chunk-PSZH2VXP.js';export{a as resolveEditorModules}from'./chunk-GQQOL4PV.js';

package/dist/{image-resources-DXvPZvXD.d.cts → image-resources-BaHz4QAd.d.cts}

@@ -1,4 +1,4 @@
-import { D as DrawingProjection } from './tree-op-types-EZXbR8bW.cjs';
+import { D as DrawingProjection } from './tree-op-types-CUCwPWjT.cjs';
 import { O as OoxmlPackage } from './ooxml-package-CR5us6ad.cjs';
 
 /**

package/dist/{image-resources-BG9DLyW7.d.ts → image-resources-Cl5_cNi9.d.ts}

@@ -1,4 +1,4 @@
-import { D as DrawingProjection } from './tree-op-types-8a6xyRCN.js';
+import { D as DrawingProjection } from './tree-op-types-D0fTNBVW.js';
 import { O as OoxmlPackage } from './ooxml-package-D_CtywTW.js';
 
 /**

package/dist/{index-DpY3WZuP.d.ts → index-D8L8WrNF.d.ts}

@@ -1,17 +1,17 @@
-import { i as FontSource, j as FontSourceSubstitution, F as FontConfiguration, k as FontFaceRequest, I as ImageContext, D as DocumentSource, Z as ZoomMode, E as EditorFontError, l as Editor, a as EditorCommand, C as CanResult, S as SelectedImageState, V as ViewScope, T as TableBorderEdgeTarget, m as TableBorderSpec, n as TableBorderStyle, o as TableContext } from './editor-D1qHfzOt.js';
-import { T as TreeDocOp, d as DrawingPositionInput, k as DrawingTransform, m as DrawingTreeDocOp } from './tree-op-types-8a6xyRCN.js';
-import { b as ImageDecodePort, S as SupportedImageMime } from './image-resources-BG9DLyW7.js';
-import { R as RevisionDisplayMode } from './revision-projection-DHAkcD_L.js';
-import './review-support-DgXTIYBW.js';
-import { a as SemanticSelection, S as SemanticPosition, N as NavigationCommand } from './semantic-interaction-DrgbgKg6.js';
-import { R as ResolvedFootnoteProperties, a as ResolvedEndnoteProperties, A as AuthoredNoteProperties, l as ReviewRevisionKind } from './review-reads-CQmU9Lcl.js';
-import { S as SemanticLayout, C as ContentControlBoundaryRecord, T as TextMeasurer } from './semantic-records-CR5hTqMK.js';
-import { S as StoryScope, A as ApplyImagePropertiesInput, d as ImageIntentResult, c as InsertImageInput, B as BookmarkIndex } from './custom-node-writes-BkMgMXxs.js';
-import { C as CellSelection, S as SectionProperties } from './semantic-cell-selection-DZtyMXkH.js';
+import { T as TreeDocOp, d as DrawingPositionInput, l as DrawingTransform, h as DrawingTreeDocOp } from './tree-op-types-D0fTNBVW.js';
+import { b as ImageDecodePort, S as SupportedImageMime } from './image-resources-Cl5_cNi9.js';
+import './review-support-D4ZBdUXa.js';
 import { EditorModule, ReviewModuleContribution } from './contracts/modules.js';
-import { Unsubscribe, ExecResult, IndentFormatting } from './contracts/types.js';
-import { F as FieldShadingMode, a as DrawingPaintStrings } from './semantic-paint-BedBxkyY.js';
-import { T as TreeDocxSession, a as TreeApplyResult } from './tree-session-SucW0znF.js';
+import { j as FontSource, k as FontSourceSubstitution, F as FontConfiguration, l as FontFaceRequest, I as ImageContext, D as DocumentSource, Z as ZoomMode, E as EditorFontError, m as Editor, b as EditorCommand, C as CanResult, S as SelectedImageState, V as ViewScope, T as TableBorderEdgeTarget, n as TableBorderSpec, o as TableBorderStyle, p as TableContext } from './editor-D2zOJztO.js';
+import { R as RevisionDisplayMode } from './revision-projection-UKqvPa4-.js';
+import { a as SemanticSelection, S as SemanticPosition, N as NavigationCommand } from './semantic-interaction-lvpzZRpA.js';
+import { R as ResolvedFootnoteProperties, a as ResolvedEndnoteProperties, A as AuthoredNoteProperties, l as ReviewRevisionKind } from './review-reads-HDvoQXK2.js';
+import { S as SemanticLayout, C as ContentControlBoundaryRecord, T as TextMeasurer } from './semantic-records-CdQvpUj1.js';
+import { S as StoryScope, A as ApplyImagePropertiesInput, d as ImageIntentResult, c as InsertImageInput, B as BookmarkIndex } from './custom-node-writes-tJw8U9MO.js';
+import { C as CellSelection, S as SectionProperties } from './semantic-cell-selection-B5vfPz4Q.js';
+import { c as RevisionStyles, R as ReviewAuthorInfo, b as RevisionAuthorStyle, F as FieldShadingMode, d as DrawingPaintStrings } from './semantic-paint-BBPL3u5w.js';
+import { Unsubscribe, ExecResult, IndentFormatting, SelectionPin } from './contracts/types.js';
+import { c as TreeDocxSessionView, a as TreeApplyResult } from './tree-session-CH1oA75f.js';
 import './contracts/document.js';
 
 /**
@@ -1004,6 +1004,14 @@ interface HyperlinkOps {
     linksInCaretParagraph(): SurfaceHyperlink[];
     /** The link the caret sits in, or null. */
     linkAtCaret(): SurfaceHyperlink | null;
+    /**
+     * The FIELD link whose painted atom the caret sits on, or null.
+     *
+     * Separate from {@link linkAtCaret} on purpose: a `HYPERLINK` field is not a tree node, so
+     * the typed lane never returns one, and link-create must not mistake a field atom for an
+     * editable link. Resolved from the layout projection, boundary-inclusive.
+     */
+    fieldLinkAtCaret(): SurfaceHyperlink | null;
     /** The link with this node id, or null. */
     linkById(linkId: string): SurfaceHyperlink | null;
     /**
@@ -1079,9 +1087,10 @@ interface DocxEditorConfig {
      */
     container?: HTMLElement;
     /**
-     * A document to load at construction. Bytes only in practice: a `DocumentHandle` cannot
-     * be re-opened (the handle is identity, not content), so passing one emits a typed
-     * `error` event rather than silently loading nothing.
+     * A document to load at construction: DOCX bytes, or `'blank'` for Word's blank
+     * template. A `DocumentHandle` cannot be re-opened (the handle is identity, not
+     * content), so passing one emits a typed `error` event rather than silently loading
+     * nothing. Omitting this mounts NO document, which is not the same as an empty one.
      */
     document?: DocumentSource;
     /**
@@ -1111,8 +1120,39 @@ interface DocxEditorConfig {
      * reason. See {@link EditorModule}.
      */
     modules?: readonly EditorModule[];
-    /** `'view'` refuses every mutating command through the facade; default `'edit'`. */
-    mode?: 'edit' | 'view';
+    /**
+     * The mode the editor opens in — one prop, matching the toolbar's three-state pill.
+     *
+     * - `'edit'` — opens in editing, even when the document's `w:trackRevisions` asks for
+     *   tracked changes; the reader still moves between modes from the toolbar.
+     * - `'suggesting'` — opens in suggesting. It needs what suggesting always needs — a
+     *   review module and an {@link DocxEditorConfig.author} — and falls back to editing
+     *   with the reason published when either is missing.
+     * - `'view'` — read-only: every mutating command through the facade is refused, and
+     *   the toolbar cannot leave viewing.
+     * - Omitted — the DOCUMENT decides: a package carrying `w:trackRevisions` opens in
+     *   suggesting, everything else in editing.
+     */
+    mode?: 'edit' | 'view' | 'suggesting';
+    /**
+     * How painted tracked changes are coloured. Presentation only — nothing is serialised.
+     *
+     * - `'author'` (the DEFAULT) — every change takes its author's colour from the
+     *   `--doc-review-author-N` ramp, by order of first appearance, as Word does. Restyle a
+     *   slot under `.docx-editor` to change the ramp.
+     * - `'kind'` — insertions green, deletions red, so "added" and "removed" are what a
+     *   glance tells apart, whoever proposed them.
+     * - {@link RevisionAuthorAssignments} — style the named authors; `others` decides
+     *   whether the rest take the ramp (the default) or the kind colours.
+     *
+     * The opening value. In React this is authored declaratively — `DocxEditor.ColorByChangeType`
+     * and `DocxEditor.AuthorStyle` compose and apply it, seeding this config for the first
+     * paint — so React hosts never pass it by hand; it is the entry for headless hosts. Read
+     * the document's resolved roster with `getReviewAuthors`. Applies wherever revision
+     * markup paints: the full all-markup view needs a review module registered; without one
+     * the proposed view still marks surviving insertions.
+     */
+    revisionStyles?: RevisionStyles;
     /** Override raster decode for insert/replace image commands; defaults to browser/headless. */
     imageDecodePort?: ImageDecodePort;
     /**
@@ -1202,6 +1242,58 @@ interface DocxEditorInstance extends Editor {
      * `stateVersion()`.
      */
     fontMeasurement(): FontMeasurementState;
+    /**
+     * Every author the review surface DRAWS, in Word's slot order, with the colour the review
+     * chrome draws them in. The discovery surface a legend or colour picker builds on —
+     * authors depend on the loaded file, so they cannot be known at configuration time.
+     *
+     * The colour is the author's, not the document's: under `'kind'` the painted text goes to
+     * the insertion/deletion colours while the cards keep these accents, so a legend built
+     * from this describes the rail rather than the page.
+     *
+     * BOTH HALVES OF REVIEW. Authors of tracked changes come first, numbered by where their
+     * first change appears; authors who only commented follow. One person therefore draws in
+     * one colour across their comments and their edits, which is what a reader assumes the
+     * moment they learn the pairing on either. The order puts commenters last so that adding
+     * a comment can never renumber a tracked change the painter has already drawn.
+     *
+     * 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. Empty while detached. Reference-stable between
+     * changes, so it is safe as a dependency; changes bump `stateVersion()`.
+     */
+    getReviewAuthors(): readonly ReviewAuthorInfo[];
+    /**
+     * The configured author used when a comment or reply omits an explicit author.
+     *
+     * @internal Review compose chrome uses this to draw an unfinished comment in the same
+     * author colour it will receive after commit.
+     */
+    getConfiguredAuthor(): string | null;
+    /**
+     * The style declared for one author, whether or not the SURFACE has published them yet —
+     * so review chrome can draw a card the rail is holding before the roster catches up.
+     *
+     * {@link DocxEditorInstance.getReviewAuthors} answers for every author of a tracked
+     * change or a comment, so this is a narrow fallback rather than the way to reach a
+     * commenter.
+     *
+     * @internal The seam `@docx-editor.dev/pro`'s review rail resolves those authors
+     * through. A consumer reads `useReviewAuthor` (pro) or `useReviewAuthors` (react)
+     * instead; nothing here answers a question those two do not.
+     */
+    getReviewAuthorStyle(author: string): RevisionAuthorStyle | undefined;
+    /**
+     * Replace how tracked changes are coloured, live. Paint-level: pages repaint without a
+     * layout pass, and the caret, selection and undo history stay where they are. Pass
+     * `'author'` to restore the default, or `'kind'` to opt out to the green/red
+     * rendering. Survives a document reload.
+     *
+     * The imperative PRIMITIVE beneath React's declarative lane: `DocxEditor.ColorByChangeType`
+     * and `DocxEditor.AuthorStyle` drive this seam, and React hosts declare those instead
+     * of calling it. Call it directly from headless and non-React hosts.
+     */
+    setRevisionStyles(styles: RevisionStyles): void;
     /**
      * Mount into `el`. If the instance holds pending document bytes (created without a
      * container, or previously detached), they mount now — under the shaped measurer when
@@ -1594,6 +1686,13 @@ interface PaginatedSurfaceOptions {
      * without remeasuring a single line.
      */
     readonly fieldShading?: FieldShadingMode;
+    /**
+     * How tracked changes are coloured: by AUTHOR (the default), by kind, or by author with
+     * host-pinned colours. A paint-level option like {@link fieldShading}: it changes no
+     * geometry, so switching it repaints without remeasuring a line. Applies wherever
+     * revision markup paints, whatever the {@link revisionDisplayMode} leaves visible.
+     */
+    readonly revisionStyles?: RevisionStyles;
     /**
      * The review module's derivation hooks for this surface's session. Absent,
      * `session.reviewItems()` is the typed empty queue and every review affordance
@@ -1811,10 +1910,10 @@ interface ContentControlSurfaceState {
  * `session` to apply ops directly bypasses the layout invalidation and the caret bookkeeping.
  */
 interface PaginatedSurface {
-    readonly session: TreeDocxSession;
+    readonly session: TreeDocxSessionView;
     storyScope(): StoryScope;
     imageDecodePort(): ImageDecodePort;
-    applyDrawingOps(ops: readonly DrawingTreeDocOp[]): ReturnType<TreeDocxSession['applyTreeOps']>;
+    applyDrawingOps(ops: readonly DrawingTreeDocOp[]): TreeApplyResult;
     applyImageProperties(input: ApplyImagePropertiesInput): ImageIntentResult;
     deleteImage(drawingNodeId: string): ImageIntentResult;
     insertImage(input: Omit<InsertImageInput, 'decodePort'>): Promise<ImageIntentResult>;
@@ -1827,6 +1926,21 @@ interface PaginatedSurface {
     /** One-based page at the caret, or at the centre of the mounted viewport. */
     currentPage(mode?: 'viewport' | 'caret'): number;
     type(text: string): void;
+    /**
+     * Queue plain typed text for a batched commit at the caret.
+     *
+     * The DOM input lane's entry: keystrokes arriving in a burst append here and land
+     * through ONE `type()` call — one transaction, one undo step, one layout flush —
+     * when the input queue drains. Every surface-level mutation, selection or scope
+     * move, geometry read, composition start and teardown flushes the buffer first.
+     * Code reading `session` directly (its text or its bytes) sits BELOW the buffer
+     * and must call {@link flushPendingInput} first, as the facade's save/detach
+     * paths do. `type()` itself stays synchronous; automation and commands should
+     * keep calling it directly.
+     */
+    enqueueType(text: string): void;
+    /** Land any queued typed text now, as its own transaction. No-op when empty. */
+    flushPendingInput(): void;
     /**
      * Insert text whose newlines are PARAGRAPH BOUNDARIES, in one commit.
      *
@@ -2096,9 +2210,9 @@ interface PaginatedSurface {
      * which is what lets a host close its panel on "the user clicked somewhere else" without
      * every adapter reimplementing that comparison.
      */
-    retainSelection(): void;
-    /** Drop the pin and stop drawing it, whether or not the caret ever left. */
-    releaseSelection(): void;
+    retainSelection(): SelectionPin;
+    /** Drop one owned pin. Another owner's pin remains visible. */
+    releaseSelection(pin: SelectionPin): void;
     /** The pinned range, or null once it was released or escaped. */
     retainedSelection(): SemanticSelection | null;
     /**
@@ -2110,6 +2224,17 @@ interface PaginatedSurface {
      */
     editingMode(): SurfaceEditingMode;
     setEditingMode(mode: SurfaceEditingMode): void;
+    /**
+     * Every author with a revision in the CURRENT layout, mapped to Word's colour slot by
+     * order of first appearance. One map instance per layout, so a caller can key caches on
+     * its identity.
+     */
+    revisionAuthors(): ReadonlyMap<string, number>;
+    /**
+     * Replace how tracked changes are coloured, live. Paint-level: the pages repaint without
+     * remeasuring a line, and the caret, selection and undo history stay where they are.
+     */
+    setRevisionStyles(colors: RevisionStyles | undefined): void;
     /**
      * Commit ops that came from automation, through the gate a keystroke goes through.
      *
@@ -2168,6 +2293,36 @@ interface PaginatedSurface {
      * while the text stayed highlighted.
      */
     activeReviewKey(): string | null;
+    /**
+     * Open THIS item, named by key, for as long as `selection` stays the live one.
+     *
+     * Without it the caret is the only evidence of which card is open, and a caret cannot name a
+     * card when two cards cover exactly the same characters: `w:ins` wrapping `w:del` — content
+     * one reviewer added and another struck — gives the insertion and the deletion one identical
+     * range, and every click on either card classified back to whichever the queue happened to
+     * list first. The reader clicked "Deleted" and watched "Added" light up.
+     *
+     * A key, not a position, because the position is precisely what is ambiguous. It holds only
+     * while the selection matches; a pointer or keyboard move hands the answer back to the caret,
+     * which is what lets the reader step out of a card by clicking away from it.
+     *
+     * `selection` is what activation wants installed, and it is installed HERE rather than by a
+     * `setSelection` of the caller's own so that the pin is up before anything is published. The
+     * other order repainted the bands and reported state while the caret was still the only
+     * evidence, so a host saw the wrong twin active for one frame and then a correction. Omit it
+     * to pin against the live selection, which is what a header or note scope has already set.
+     */
+    activateReview(key: string, selection?: SemanticSelection): void;
+    /**
+     * The key {@link activateReview} pinned, or null once its selection is no longer live.
+     *
+     * Exists so nothing outside the surface keeps its own copy of "the selection came from
+     * opening a card". `selectionPlacement` needs that fact to stay quiet about offering a
+     * comment on text the reader only selected by opening a card over it, and the copy it used to
+     * keep was set on one of activation's three branches, so a header card offered to comment on
+     * itself.
+     */
+    activatedReviewKey(): string | null;
     /**
      * Close the open item until the caret next moves.
      *