@docx-editor.dev/core 2.30.0 → 2.32.0

package/dist/{chrome-print-BM3Js-6X.d.ts → chrome-print-CznJ0ucN.d.ts}

@@ -1,20 +1,22 @@
-import { c as FontConfigurationFragment, g as FontResolver, M as MarkedFontResolver, f as FontResolutionRequest } from './font-resolver-CL9BVKZo.js';
-import { q as DocumentSource, Q as FontConfiguration, aN as ZoomMode, z as EditorFontError, t as Editor, R as ReviewPaneOptions, b as EditorCommand, C as CanResult, au as SelectedImageState, Y as FormatPainterSurfaceState, as as ScrollPlacement, aL as TrackedChangePredicate, aK as TrackedChangeFilterMode, S as FontFaceRequest, U as FontSource, a7 as ImageContext, ay as TableBorderEdgeTarget, az as TableBorderSpec, aA as TableBorderStyle, aF as TableContext } from './editor-DaEJd2so.js';
-import { V as ViewScope, a as EditorExecOptions } from './editor-scope-7o9xweiJ.js';
-import { ag as TreeDocOp, aN as TextFormFieldRange, aO as TextFormFieldOptions, ae as Unsubscribe, E as ExecResult, _ as DrawingPositionInput, aP as DrawingTransform, A as ParagraphTabStop, y as IndentFormatting, z as ParagraphFlags, a4 as ParagraphDisagreements, az as DrawingTreeDocOp, ab as SelectionPin, Q as OoxmlPackage, g as ReviewRevisionKind, a1 as ImageWrapTarget } from './types-barrel-CA0xB8kH.js';
-import { c as ImageDecodePort, S as SupportedImageMime } from './image-resources-Bipz8toD.js';
-import { T as TextMeasurer, a as ReviewDisplayMode, q as ResolvedRevisionMarkup, t as RevisionMarkupOptions, z as RevisionMarkupChromeHandlers, S as SemanticLayout, C as ContentControlBoundaryRecord, O as SectionProperties } from './semantic-records-CjcF26ZL.js';
-import { F as FieldResultsMode, C as ContentLockPolicy, I as InsertImageInput, S as StoryScope, A as ApplyImagePropertiesInput, i as ImageIntentResult } from './tree-package-store-DKhdEVym.js';
+import { c as FontConfigurationFragment, g as FontResolver, M as MarkedFontResolver, f as FontResolutionRequest } from './font-resolver-BlQNGdvR.js';
+import { F as FontConfiguration, a as FontFaceRequest, b as FontSource } from './editor-fonts-D_-vjuJi.js';
+import { V as ViewScope, a as EditorExecOptions } from './editor-scope-B3L-1ALc.js';
+import { au as TreeDocOp, b0 as TextFormFieldRange, b1 as TextFormFieldOptions, ad as ImageDecodePort, ao as Unsubscribe, E as ExecResult, aa as DrawingPositionInput, b2 as DrawingTransform, G as ParagraphTabStop, y as IndentFormatting, F as ParagraphFlags, A as ParagraphDisagreements, aJ as DrawingTreeDocOp, an as SupportedImageMime, am as SelectionPin, a5 as OoxmlPackage, g as ReviewRevisionKind, aH as PackageWatermarkWrite, ag as ImageWrapTarget } from './tree-op-types-C_S2niXW.js';
+import { e as BookmarkStory, u as DocumentSource, aP as ZoomMode, J as EditorFontError, x as Editor, b as EditorCommand, C as CanResult, aw as SelectedImageState, _ as FormatPainterSurfaceState, f as BookmarkSummary, au as ScrollPlacement, aN as TrackedChangePredicate, aM as TrackedChangeFilterMode, a9 as ImageContext, aA as TableBorderEdgeTarget, aB as TableBorderSpec, aC as TableBorderStyle, aH as TableContext } from './editor-DZwOTmlR.js';
+import { T as TextMeasurer, f as UnsupportedElementRule, S as SemanticLayout, C as ContentControlBoundaryRecord, t as SectionProperties } from './semantic-records-BvN-WWst.js';
+import { a as ReviewDisplayMode, d as ResolvedRevisionMarkup, k as RevisionMarkupOptions, g as RevisionMarkupChromeHandlers } from './revision-projection-Cn6rZJ7H.js';
+import { F as FieldResultsMode, C as ContentLockPolicy, I as InsertImageInput, S as StoryScope, A as ApplyImagePropertiesInput, i as ImageIntentResult } from './tree-package-store-CRHvMyNj.js';
+import { ReviewPaneOptions } from './contracts/types.js';
 import { F as FontShapingOptions } from './font-shaping-policy-BvpkrfxM.js';
-import { F as FieldShadingMode, d as RevisionStyles, f as DrawingPaintStrings, R as ReviewAuthorInfo, c as RevisionAuthorStyle } from './semantic-paint-Bz3FBAoH.js';
+import { F as FieldShadingMode, c as RevisionStyles, f as DrawingPaintStrings, R as ReviewAuthorInfo, b as RevisionAuthorStyle } from './semantic-paint-BPw_n0li.js';
 import { ReviewModuleContribution, EditorModule } from './contracts/modules.js';
-import { S as SemanticPosition, a as SemanticSelection, N as NavigationCommand } from './semantic-interaction-Dc3pf3hr.js';
+import { S as SemanticPosition, a as SemanticSelection, N as NavigationCommand } from './semantic-interaction-CJoHLoOl.js';
 import { CollaborationModuleContribution, EditorCollaborationSession, CollaborationRemoteSelection } from './collaboration.js';
-import { R as ResolvedFootnoteProperties, a as ResolvedEndnoteProperties, A as AuthoredNoteProperties } from './note-properties-9FH8zAeG.js';
-import { B as BookmarkIndex } from './custom-node-writes-0v0Kgw1T.js';
-import { C as CellSelection } from './semantic-cell-selection-Dr9yxFZt.js';
-import { T as TreeDocxSessionView, a as TreeApplyResult } from './tree-session-contract-CwnTEVLF.js';
-import { C as CollaborationStatus } from './failure-NS2lsya4.js';
+import { R as ResolvedFootnoteProperties, a as ResolvedEndnoteProperties, A as AuthoredNoteProperties } from './note-properties-Ds5R2_3F.js';
+import { B as BookmarkIndex } from './custom-node-writes-CLJKGD9t.js';
+import { C as CellSelection } from './semantic-cell-selection-BaUR0iJ4.js';
+import { T as TreeDocxSessionView, a as TreeApplyResult } from './tree-session-contract-D1awo_dA.js';
+import { a as CollaborationStatus } from './failure-6KGFrDO9.js';
 
 /**
  * A blank document, freshly zipped per call (the caller may hand the
@@ -259,10 +261,18 @@ interface HyperlinkActivation {
  */
 interface SurfaceNavigation {
     /** Snap to a semantic position using layout geometry, then place the caret there. */
+    /**
+     * With `orShow`, a story that cannot be opened is scrolled to without moving the caret into
+     * it, and the answer is `'shown'`. With `center`, the target is centered in the viewport
+     * unless it is already well inside it, so it never lands under chrome at the top edge.
+     */
     goToPosition(position: {
         paragraphId: string;
         offset: number;
-    }): boolean;
+    }, options?: {
+        readonly orShow?: boolean;
+        readonly center?: boolean;
+    }): boolean | 'shown';
     /**
      * Scroll a bookmark into view and place the caret at it. Answers false for a name no
      * bookmark declares — an inert click, which is what Word does with a dangling anchor.
@@ -276,6 +286,19 @@ interface SurfaceNavigation {
     destroy(): void;
 }
 
+/**
+ * The surface's view of the mark options.
+ *
+ * @public
+ */
+interface BookmarkMarkOptionsSource {
+    readonly current: () => BookmarkMarkOptions;
+    /** Name the repaint to run when the options change. One slot: a remount replaces it. */
+    readonly onChange: (repaint: (() => void) | null) => void;
+    /** Report an error a host callback threw while marks were painted. */
+    readonly reportError: (error: unknown) => void;
+}
+
 /**
  * How the caret moves through an inline content control whose effective lock is
  * `contentLocked` or `sdtContentLocked`.
@@ -324,6 +347,14 @@ interface PaginatedSurfaceOptions {
     readonly author?: string;
     /** Opening mode; changeable at runtime with `setEditingMode`. */
     readonly editingMode?: SurfaceEditingMode;
+    /**
+     * True while the active band covers both halves of a replacement: when the review UI lists
+     * a replacement as one card, or while an activation of the whole replacement holds. Read
+     * on each band paint. Set by the editor; a host changes `revisionsIn` instead.
+     *
+     * @internal
+     */
+    readonly pairsReplacements?: () => boolean;
     /**
      * Identifies the measurer for cache invalidation.
      *
@@ -363,6 +394,8 @@ interface PaginatedSurfaceOptions {
     /** Show paragraph-end furniture without changing document content. */
     readonly showParagraphMarks?: boolean;
     readonly onToggleParagraphMarks?: () => void;
+    /** Show bracket marks at bookmarks. Paint-level; the document does not change. */
+    readonly showBookmarks?: boolean;
     /**
      * 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
@@ -370,6 +403,7 @@ interface PaginatedSurfaceOptions {
      * revision markup paints, whatever the {@link revisionDisplayMode} leaves visible.
      */
     readonly revisionStyles?: RevisionStyles;
+    readonly unsupportedElementRules?: readonly UnsupportedElementRule[];
     readonly revisionMarkup?: ResolvedRevisionMarkup;
     /**
      * The review module's derivation hooks for this surface's session. Absent,
@@ -407,6 +441,12 @@ interface PaginatedSurfaceOptions {
      * maps it to a public code before it reports anything.
      */
     readonly onRejection?: (reason: string) => void;
+    /**
+     * The pages turned up in another document without a `moveTo`: a host moved the mount
+     * element itself (a Vue `Teleport` retargeted, or a plain `appendChild`). The surface has
+     * already re-bound its own listeners; the owner re-registers what is per document.
+     */
+    readonly onHostMoved?: (document: Document) => void;
     /**
      * Told the milliseconds of each layout pass and each paint. For `'input'`, told the browser
      * timestamp of each key press or pointer press on the pages, so a listener can time it to
@@ -433,6 +473,18 @@ interface PaginatedSurfaceOptions {
      * rather than doing something surprising with it.
      */
     readonly onRequestHyperlink?: () => void;
+    /**
+     * Ctrl/Cmd+Shift+F5: open the host's bookmark dialog. Answers whether chrome took the
+     * request; when none did, or when this is absent, the key is left to the browser.
+     */
+    readonly onRequestBookmark?: () => boolean;
+    /** Ctrl+G (Cmd+Option+G on macOS): open the host's Go To UI; answers whether chrome took it. */
+    readonly onRequestGoTo?: () => boolean;
+    /**
+     * The host's Show bookmarks options, read on every paint. `onChange` names the repaint to
+     * run when the host changes them.
+     */
+    readonly bookmarkMarks?: BookmarkMarkOptionsSource;
     /** Return true when host chrome handles this session. */
     readonly onRequestTextFormField?: (session: TextFormFieldDialogSession) => boolean;
     readonly onRequestContentControlWidget?: (session: ContentControlWidgetSession) => boolean;
@@ -458,8 +510,8 @@ interface PaginatedSurfaceOptions {
 }
 
 /**
- * Receives the element that shows the loading indicator on the first page, while a large
- * document lays out its remaining pages.
+ * Receives the element that shows the loading indicator below the laid-out pages, while a
+ * large document lays out its remaining pages.
  *
  * @example
  * ```ts
@@ -476,8 +528,8 @@ interface OpeningIndicatorHost {
     /**
      * Called with the indicator element when the first pages show, and with `null` when the
      * remaining pages are laid out or the open is abandoned. The element is empty while a host
-     * is set: render the host's content into it. It is centered on the first page, at most 30%
-     * of the window height below the page top, and scrolls with the document.
+     * is set: render the host's content into it. It is centered in a band below the last
+     * laid-out page, as wide as the page, and scrolls with the document.
      */
     publish(element: HTMLElement | null): void;
 }
@@ -581,6 +633,8 @@ interface DocxEditorConfig {
      * the proposed view still marks surviving insertions.
      */
     revisionStyles?: RevisionStyles;
+    /** Ordered unsupported-content registrations; the first matching rule reserves a layout box. */
+    unsupportedElementRules?: readonly UnsupportedElementRule[];
     /** Initial local revision presentation and tracking preferences. */
     revisionMarkup?: RevisionMarkupOptions;
     /** Initial review projection. Markup modes require a review module. */
@@ -656,10 +710,106 @@ interface HyperlinkChromeHandlers {
     /** Ctrl/Cmd+K: open insert-or-edit for the selection. */
     readonly onRequest?: () => void;
 }
+/**
+ * Host chrome for bookmarks.
+ *
+ * @public
+ */
+interface BookmarkChromeHandlers {
+    /**
+     * Open the Bookmark dialog for the selection: the `openBookmarkDialog` command, which the
+     * Insert menu row and Ctrl/Cmd+Shift+F5 send.
+     */
+    readonly onRequest?: () => void;
+}
+/**
+ * Host chrome for comment drafts: the review rail, or the host's own comment UI.
+ *
+ * @public
+ */
+interface CommentDraftChromeHandlers {
+    /**
+     * Open a comment draft on the selection: the `review.addComment` control's press. The
+     * handler takes no arguments. It reads the selection with `getSelectionPlacement`, and can
+     * pin it with `retainSelection` while the draft is open. The most recent registration
+     * receives each request.
+     */
+    readonly onRequest?: () => void;
+}
+/**
+ * Host chrome for Go To: the Go to tab of `DocxEditor.Navigation`, or the host's own.
+ *
+ * @public
+ */
+interface GoToChromeHandlers {
+    /** Open the Go To UI: the `openGoTo` command, which its shortcut also sends. */
+    readonly onRequest?: () => void;
+    /**
+     * Whether Ctrl+G (Cmd+Option+G on macOS) in the document opens this UI. Defaults to `true`.
+     * With `false` the chord is left to the browser; `openGoTo` still opens the UI. The most
+     * recent registration decides. It is read when the chord arrives, so a getter can follow a
+     * setting without registering again.
+     */
+    readonly shortcut?: boolean;
+}
+/**
+ * One painted bookmark mark, as `BookmarkMarkOptions` callbacks see it.
+ *
+ * @public
+ */
+interface BookmarkMarkInfo {
+    /** The bookmark's name as the document writes it. */
+    readonly name: string;
+    /** Whether the name starts with an underscore. */
+    readonly hidden: boolean;
+    /** The story the bookmark is in. */
+    readonly story: BookmarkStory;
+    /** Which mark this is: the start bracket, the end bracket, or a point bookmark's I-beam. */
+    readonly edge: 'start' | 'end' | 'point';
+}
+/**
+ * How Show bookmarks paints its marks. Register with `setBookmarkMarks`.
+ *
+ * @public
+ */
+interface BookmarkMarkOptions {
+    /**
+     * Which bookmarks get marks: `'visible'` (the default) skips hidden bookmarks, `'all'`
+     * includes them, and a function decides per bookmark.
+     */
+    readonly include?: 'visible' | 'all' | ((bookmark: Omit<BookmarkMarkInfo, 'edge'>) => boolean);
+    /**
+     * Adjust each mark before it is placed: add a class, a `title` tooltip, or attributes.
+     * Return another element to replace the mark. The editor positions whatever comes back.
+     * Marks ignore the pointer; set `pointer-events: auto` on a mark that shows a tooltip.
+     */
+    readonly decorate?: (element: HTMLElement, mark: BookmarkMarkInfo) => HTMLElement | void;
+    /** Keep the marks when the browser prints the page. Exports never include them. */
+    readonly print?: boolean;
+}
 /** Host chrome that edits a clicked Office Math equation. */
 interface EquationChromeHandlers {
     readonly onPopover?: (activation: EquationActivation) => void;
 }
+/**
+ * How {@link DocxEditorInstance.attach} moves an open document.
+ *
+ * @example
+ * ```ts
+ * // Bring the editor home from a pop-out and keep typing there.
+ * editor.attach(mainSlot, { focus: true });
+ * ```
+ *
+ * @public
+ */
+interface AttachOptions {
+    /**
+     * Focus the pages after the move, so the caret shows and typing continues. Default: focus
+     * returns only when the pages had it before the move or the `detach()`. A first mount from
+     * bytes does not take focus.
+     */
+    readonly focus?: boolean;
+}
 /**
  * The concrete facade type: the full `Editor` contract plus the instance-only surface.
  *
@@ -668,6 +818,17 @@ interface EquationChromeHandlers {
  * need. Production adapters program against `Editor` for everything else.
  */
 interface DocxEditorInstance extends Editor {
+    /**
+     * Replace host font resources without replacing the document or its edit history.
+     * Old resolution is cancelled. Existing host faces are removed before the new
+     * resolver runs; no answer keeps the bounded fallback. Document-embedded faces
+     * remain independent of host fonts. Failures report through `onFontError`.
+     *
+     * The session, selection, undo, protection, and collaboration state stay intact.
+     * Throws after `destroy()`. This does not grant permission to load native fonts.
+     * @public
+     */
+    setFonts(fonts: DocxEditorConfig['fonts']): Promise<void>;
     /** Bumps on mount, detach, destroy, and document reload — guards async image intents. */
     readonly mountGeneration: number;
     /**
@@ -684,6 +845,28 @@ interface DocxEditorInstance extends Editor {
      * command needs.
      */
     setHyperlinkChrome(handlers: HyperlinkChromeHandlers): Unsubscribe;
+    /**
+     * Wire the host's bookmark dialog to Ctrl/Cmd+Shift+F5. Returns an unsubscribe that
+     * restores whatever was registered before, like {@link DocxEditorInstance.setHyperlinkChrome}.
+     */
+    setBookmarkChrome(handlers: BookmarkChromeHandlers): Unsubscribe;
+    /**
+     * Wire the host's Go To UI to the `openGoTo` command. Returns an unsubscribe that restores
+     * whatever was registered before. `DocxEditor.Navigation` registers its Go to tab.
+     */
+    setGoToChrome(handlers: GoToChromeHandlers): Unsubscribe;
+    /**
+     * Wire the host's comment draft UI to the `review.addComment` control. Returns an
+     * unsubscribe that restores whatever was registered before. While nothing is registered,
+     * the control is disabled, because nothing could open the draft. The review rail registers
+     * when it mounts.
+     */
+    setCommentDraftChrome(handlers: CommentDraftChromeHandlers): Unsubscribe;
+    /**
+     * Choose which bookmarks Show bookmarks marks and customize each mark. Returns an
+     * unsubscribe that restores the previous options.
+     */
+    setBookmarkMarks(options: BookmarkMarkOptions): Unsubscribe;
     /**
      * Register local revision settings chrome. Disposal cancels its active sessions.
      * Manual renderers take priority over fallback renderers. Pass null to use native chrome
@@ -867,6 +1050,8 @@ interface DocxEditorInstance extends Editor {
      * of calling it. Call it directly from headless and non-React hosts.
      */
     setRevisionStyles(styles: RevisionStyles): void;
+    /** Replace registrations while preserving document edits and undo history. */
+    setUnsupportedElementRules(rules: readonly UnsupportedElementRule[]): void;
     /** Merge local preferences and emit revisionMarkupChange after a change.
      * Invalid settings throw TypeError without changing the previous settings.
      */
@@ -892,20 +1077,42 @@ interface DocxEditorInstance extends Editor {
      */
     setReviewPaneOptions(options: ReviewPaneOptions): ExecResult;
     /**
-     * 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
-     * fonts have resolved in the meantime. Attaching while already mounted elsewhere moves
-     * the live content via `session.save()`.
+     * Mount into `el`, which may belong to another document: a pop-out window opened with
+     * `window.open`, or a same-origin iframe.
+     *
+     * A document that is already open MOVES into `el`, from another element or from a
+     * previous `detach()`: the undo history, the selection, other editing state (such as an
+     * armed format painter) and any collaboration session stay as they are. The reading
+     * position is kept, and keyboard focus returns when the pages had it before (see
+     * {@link AttachOptions.focus}). Focus, selection, pointer, scroll and resize listeners,
+     * timers and registered font faces follow `el`'s window. Pending document bytes (an
+     * instance created without a container, or a `load` while detached) mount now instead, as
+     * a fresh session.
      *
-     * HONEST COSTS: a mount from bytes is a fresh session — the undo stack and the caret do
-     * not survive re-attach (the same cost as the async font remount). After `destroy()`
-     * this is a no-op that emits a typed `error` event: a destroyed instance never remounts.
+     * The host copies the editor stylesheet and any web fonts it loads into `el`'s document.
+     * Move the editor back, or `destroy()` it, before that window closes. An element whose
+     * window has closed (or that has no window) is refused with an `invalidTarget` error and
+     * the editor stays where it is. After `destroy()` this is a no-op that emits a typed
+     * `error` event: a destroyed instance never remounts.
+     *
+     * @example
+     * ```ts
+     * // Pop the editor out into its own window and bring it back later.
+     * const popup = window.open('', 'editor', 'width=900,height=1000')!;
+     * copyStyles(document, popup.document); // host-owned: the editor CSS and fonts
+     * const slot = popup.document.createElement('div');
+     * popup.document.body.append(slot);
+     * editor.attach(slot);
+     * popup.addEventListener('pagehide', () => editor.attach(mainSlot), { once: true });
+     * ```
      */
-    attach(el: HTMLElement): void;
+    attach(el: HTMLElement, options?: AttachOptions): void;
     /**
-     * Tear down the painted surface, stashing the CURRENT document bytes
-     * (`session.save()`) so a later `attach` restores the content — but not the undo stack
-     * or the caret. No-op when already detached or destroyed.
+     * Take the editor out of its element and keep it, with its undo history, selection and
+     * collaboration session, for a later `attach`. While detached the instance still saves,
+     * runs commands and receives remote edits; it paints when attached again. A `load` while
+     * detached replaces the kept document. `destroy()` releases everything. No-op when already
+     * detached or destroyed.
      */
     detach(): void;
 }
@@ -1488,6 +1695,29 @@ interface RemoteCaretLabelHost {
     publish(anchors: readonly RemoteCaretLabelAnchor[]): void;
 }
 
+/** The surface's bookmark lane. */
+interface SurfaceBookmarks {
+    /** Every bookmark in the document: body first, then headers, footers and notes. */
+    list(): readonly BookmarkSummary[];
+    /** Why `insert(name)` would be refused now, or null. */
+    insertRefusal(name: string): string | null;
+    /** Bookmark the selection under `name`, moving a bookmark that already has it. */
+    insert(name: string): boolean;
+    /** Remove the bookmark with this name, compared without case, and its copies. */
+    remove(name: string): boolean;
+    /** Keep the first bookmark with this name and remove its copies, in one transaction. */
+    keepFirst(name: string): boolean;
+    /** Why a bookmark write cannot happen now, or null. */
+    writeRefusal(): string | null;
+    /** Select the bookmark's range and scroll it into view. */
+    goTo(name: string): boolean;
+    /** Whether the marks are shown. */
+    shown(): boolean;
+    setShown(shown: boolean): void;
+    /** Paint the marks for one rendered frame. */
+    paint(frame: SurfaceOverlayFrame): void;
+}
+
 /**
  * What the selection is currently formatted as.
  *
@@ -1514,7 +1744,8 @@ interface SurfaceFormatting {
     /**
      * `w:spacing`'s line rule and its value: LINES for `multiple`, points for the other two
      * (`w:line` is 240ths of a line under `auto` and twentieths of a point otherwise).
-     * Null when the selection's paragraphs disagree, or state no line spacing at all.
+     * The effective value: a paragraph whose cascade states none reads as single spacing
+     * (`multiple`, 1). Null when the selection's paragraphs disagree.
      */
     readonly lineSpacing: {
         readonly rule: 'multiple' | 'exact' | 'atLeast';
@@ -1686,12 +1917,16 @@ interface PaginatedSurface {
         readonly commitGuard?: () => boolean;
     }): Promise<ImageIntentResult>;
     layout(): SemanticLayout;
+    /** The measurer layout uses; sizes engine-authored shapes such as a watermark. */
+    textMeasurer?(): TextMeasurer;
     state(): PaginatedSurfaceState;
     /** One-based page at the caret, or at the centre of the mounted viewport. */
     currentPage(mode?: 'viewport' | 'caret'): number;
     type(text: string): void;
     /** Author one explicit tracked text change without changing the editing mode. */
     proposeTextChange(kind: 'insertion' | 'deletion' | 'replacement', text: string, author?: string): boolean;
+    /** Replace a paragraph range of the active story in place; suggesting tracks it. */
+    replaceTextInPlace(paragraphId: string, start: number, end: number, text: string): boolean;
     /**
      * Queue plain typed text for a batched commit at the caret.
      *
@@ -1872,16 +2107,17 @@ interface PaginatedSurface {
      * caret-preserving edits (Backspace, Delete, Enter) and IME composition, and is
      * discarded when the caret moves elsewhere or the document is undone. A property the
      * store cannot author is refused at arm time rather than left to poison the keystroke.
+     * Returns the document's refusal reason, or null when the write landed, armed, or did nothing.
      */
-    toggleRunProperty(localName: string, attributes?: Record<string, string>): void;
+    toggleRunProperty(localName: string, attributes?: Record<string, string>): string | null;
     /**
      * SET a run property over the selection, rather than toggling it.
      *
      * Font family, size and colour are values, not switches: picking Arial twice must leave
      * the text in Arial, which a toggle would not. Arms at a collapsed caret on the same
-     * terms as `toggleRunProperty`.
+     * terms as `toggleRunProperty`, and returns a refusal the same way.
      */
-    setRunProperty(localName: string, attributes?: Record<string, string>): void;
+    setRunProperty(localName: string, attributes?: Record<string, string>): string | null;
     /**
      * Set a property on every paragraph the selection touches — alignment, style, spacing.
      *
@@ -2055,6 +2291,11 @@ interface PaginatedSurface {
      * with code `destroyed`. Does not change focus.
      */
     save(): Uint8Array;
+    /**
+     * {@link save} in steps a caller can pause between. Everything `save` does before it
+     * serializes happens at the call, and the document is captured then.
+     */
+    saveSteps(): Generator<void, Uint8Array>;
     /** Whether a body paragraph belongs to a detected TOC boundary or cached result. */
     isInsideToc(paragraphId: string): boolean;
     /**
@@ -2062,6 +2303,8 @@ interface PaginatedSurface {
      * calls `openExternal`; nothing else in the engine may call `window.open`.
      */
     readonly navigation: SurfaceNavigation;
+    /** List, add, delete and jump to bookmarks, and show their marks. */
+    readonly bookmarkEditing: SurfaceBookmarks;
     /**
      * Pin the current selection so it stays VISIBLY selected while focus is elsewhere.
      *
@@ -2125,6 +2368,7 @@ interface PaginatedSurface {
      */
     setRevisionMarkup(settings: ResolvedRevisionMarkup): void;
     setRevisionStyles(colors: RevisionStyles | undefined): void;
+    setUnsupportedElementRules(rules: readonly UnsupportedElementRule[]): void;
     /** Toggle paragraph-end furniture without layout or document changes. */
     setShowParagraphMarks(show: boolean): void;
     /**
@@ -2198,11 +2442,19 @@ interface PaginatedSurface {
      * pages painting text the tree no longer had, every card anchored where it used to be, and
      * the caret past the end of the paragraph — after which every keystroke was refused with
      * `offset-out-of-range` until the user happened to click somewhere else.
+     *
+     * Returns null when the write went through, and otherwise why it did not: the external
+     * refresh when the write guard skipped the commit, a gate's reason (viewing, collaboration)
+     * when `run` never ran, or the reason `run` reported. A `run` that commits nothing without a
+     * reason counts as refused (`'rejected'`). Gate and `run` reasons also become
+     * `lastRejection`; a skipped refresh changes nothing, `lastRejection` included.
+     *
+     * `run` receives the store history token of this commit, for the store write it performs.
      */
-    commitReviewOps(run: () => {
+    commitReviewOps(run: (historyToken: symbol | undefined) => {
         readonly committed: boolean;
         readonly reason?: unknown;
-    }, intent?: ReviewWriteIntent): void;
+    }, intent?: ReviewWriteIntent): string | null;
     /**
      * The layout as last PUBLISHED, without forcing pending work.
      *
@@ -2258,9 +2510,11 @@ interface PaginatedSurface {
      * 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.
+     * `preventScroll` installs `selection` with no scroll, now or on a later repaint.
      */
     activateReview(key: string, selection?: SemanticSelection, options?: {
         readonly allowExcluded?: boolean;
+        readonly preventScroll?: boolean;
     }): void;
     /**
      * The key {@link activateReview} pinned, or null once its selection is no longer live.
@@ -2338,6 +2592,25 @@ interface PaginatedSurface {
      * @public
      */
     setTableInteractionLabel(resolver: (key: 'table.insertRowBelow' | 'table.insertColumnRight') => string): void;
+    /**
+     * Move the painted pages into `container`, which may belong to another document: a pop-out
+     * window or an iframe. The session, undo history, selection and collaboration replica stay
+     * as they are; only the DOM and the document- and window-level listeners move. Open
+     * content-control menus close.
+     */
+    moveTo(container: HTMLElement, options?: {
+        readonly focus?: boolean;
+    }): void;
+    /**
+     * Take the pages out of their container and keep them, with all editing state, for a later
+     * `moveTo`. A parked surface still accepts commands and remote edits; it paints into a
+     * private, disconnected holder until it moves again.
+     */
+    park(): void;
+    /** Whether the surface is parked: mounted nowhere, state kept. */
+    parked(): boolean;
+    /** The element the pages are in now: the host's, or a private holder while parked. */
+    hostElement(): HTMLElement;
     destroy(): void;
     /**
      * The section a painted page belongs to, and the page that section starts on.
@@ -2387,8 +2660,10 @@ interface PaginatedSurface {
      * Flushes layout so the next enter/rebind sees the new resolution.
      */
     applyHeaderFooterLifecycle(op: {
-        readonly op: 'createHeaderFooter' | 'deleteHeaderFooter' | 'linkToPrevious' | 'unlinkFromPrevious' | 'setSectionFurnitureOptions' | 'setDocumentProtection';
+        readonly op: 'createHeaderFooter' | 'deleteHeaderFooter' | 'linkToPrevious' | 'unlinkFromPrevious' | 'setSectionFurnitureOptions' | 'setDocumentProtection' | 'setWatermark';
         readonly sectionIndex?: number;
+        /** `setWatermark` only: the new watermark, or null to remove it. */
+        readonly watermark?: PackageWatermarkWrite | null;
         /** `setDocumentProtection` only: enforce filling-in-forms protection, or lift it. */
         readonly enforce?: boolean;
         readonly kind?: 'header' | 'footer';
@@ -3130,6 +3405,15 @@ declare const CHROME_GROUPS: readonly [{
         readonly state: {
             readonly kind: 'command';
         };
+    }, {
+        readonly id: 'bookmarks';
+        readonly shape: 'icon';
+        readonly labelKey: 'formattingBar.showBookmarks';
+        readonly defaultToolbar: false;
+        readonly paths: readonly string[];
+        readonly state: {
+            readonly kind: 'command';
+        };
     }, {
         readonly id: 'protectDocument';
         readonly shape: 'icon';
@@ -3298,6 +3582,20 @@ declare const CHROME_GROUPS: readonly [{
         readonly state: {
             readonly kind: 'value';
         };
+    }, {
+        readonly id: 'mergeCells';
+        readonly labelKey: 'table.mergeCells';
+        readonly paths: readonly string[];
+        readonly state: {
+            readonly kind: 'command';
+        };
+    }, {
+        readonly id: 'splitCell';
+        readonly labelKey: 'table.splitCell';
+        readonly paths: readonly string[];
+        readonly state: {
+            readonly kind: 'command';
+        };
     }];
 }, {
     readonly id: 'paragraph';
@@ -3439,6 +3737,27 @@ declare const CHROME_GROUPS: readonly [{
         readonly state: {
             readonly kind: 'command';
         };
+    }, {
+        readonly id: 'bookmark';
+        readonly labelKey: 'toolbar.bookmark';
+        readonly paths: readonly string[];
+        readonly state: {
+            readonly kind: 'command';
+        };
+    }, {
+        readonly id: 'goToBookmark';
+        readonly labelKey: 'toolbar.goToBookmark';
+        readonly paths: readonly string[];
+        readonly state: {
+            readonly kind: 'command';
+        };
+    }, {
+        readonly id: 'watermark';
+        readonly labelKey: 'toolbar.watermark';
+        readonly paths: readonly string[];
+        readonly state: {
+            readonly kind: 'command';
+        };
     }];
 }];
 /**
@@ -3455,7 +3774,7 @@ type ChromeGroupId = 'history' | 'zoom' | 'styles' | 'font' | 'text' | 'script'
  *
  * @public
  */
-type ChromeSlotId = 'history.undo' | 'history.redo' | 'zoom.level' | 'styles.style' | 'font.family' | 'font.size' | 'text.bold' | 'text.italic' | 'text.underline' | 'text.strike' | 'text.color' | 'text.highlight' | 'text.link' | 'script.super' | 'script.sub' | 'alignment.left' | 'alignment.center' | 'alignment.right' | 'alignment.justify' | 'direction.ltr' | 'direction.rtl' | 'list.bullet' | 'list.numbered' | 'list.outdent' | 'list.indent' | 'list.lineSpacing' | 'format.painter' | 'format.clear' | 'review.revisionMarkup' | 'review.comments' | 'review.addComment' | 'review.paragraphMarks' | 'review.protectDocument' | 'review.simpleMarkup' | 'review.allMarkup' | 'review.noMarkup' | 'review.original' | 'review.previousChange' | 'review.nextChange' | 'review.acceptAllChanges' | 'review.rejectAllChanges' | 'review.authors' | 'review.editingMode' | 'contentControl.showAll' | 'contentControl.formFill' | 'contentControl.inspector' | 'contentControl.remove' | 'image.insert' | 'image.properties' | 'image.wrap' | 'image.altText' | 'table.insert' | 'table.borderTarget' | 'table.borderColor' | 'table.borderStyle' | 'table.borderWidth' | 'table.cellFill' | 'file.open' | 'file.save' | 'file.exportMarkdown' | 'file.exportPdf' | 'file.print' | 'paragraph.dialog' | 'file.pageSetup' | 'insert.textBox' | 'insert.footnote' | 'insert.endnote' | 'insert.pageNumber' | 'insert.totalPages' | 'insert.sectionPages' | 'insert.pageXofY' | 'insert.pageBreak' | 'insert.sectionBreakNextPage' | 'insert.sectionBreakContinuous' | 'insert.toc';
+type ChromeSlotId = 'history.undo' | 'history.redo' | 'zoom.level' | 'styles.style' | 'font.family' | 'font.size' | 'text.bold' | 'text.italic' | 'text.underline' | 'text.strike' | 'text.color' | 'text.highlight' | 'text.link' | 'script.super' | 'script.sub' | 'alignment.left' | 'alignment.center' | 'alignment.right' | 'alignment.justify' | 'direction.ltr' | 'direction.rtl' | 'list.bullet' | 'list.numbered' | 'list.outdent' | 'list.indent' | 'list.lineSpacing' | 'format.painter' | 'format.clear' | 'review.revisionMarkup' | 'review.comments' | 'review.addComment' | 'review.paragraphMarks' | 'review.bookmarks' | 'review.protectDocument' | 'review.simpleMarkup' | 'review.allMarkup' | 'review.noMarkup' | 'review.original' | 'review.previousChange' | 'review.nextChange' | 'review.acceptAllChanges' | 'review.rejectAllChanges' | 'review.authors' | 'review.editingMode' | 'contentControl.showAll' | 'contentControl.formFill' | 'contentControl.inspector' | 'contentControl.remove' | 'image.insert' | 'image.properties' | 'image.wrap' | 'image.altText' | 'table.insert' | 'table.borderTarget' | 'table.borderColor' | 'table.borderStyle' | 'table.borderWidth' | 'table.cellFill' | 'table.mergeCells' | 'table.splitCell' | 'file.open' | 'file.save' | 'file.exportMarkdown' | 'file.exportPdf' | 'file.print' | 'paragraph.dialog' | 'file.pageSetup' | 'insert.textBox' | 'insert.footnote' | 'insert.endnote' | 'insert.pageNumber' | 'insert.totalPages' | 'insert.sectionPages' | 'insert.pageXofY' | 'insert.pageBreak' | 'insert.sectionBreakNextPage' | 'insert.sectionBreakContinuous' | 'insert.toc' | 'insert.bookmark' | 'insert.goToBookmark' | 'insert.watermark';
 /**
  * Every control id in the chrome, as a literal union. Unique WITHIN a group, not
  * globally (`image.insert` / `table.insert`) — key consumers on {@link ChromeSlotId}.
@@ -3787,7 +4106,8 @@ declare function runTableCommand(editor: Editor | null, command: EditorCommand,
  *
  * Construction is separate from mounting. Pass a `container` and the document mounts
  * immediately; omit it and nothing touches the DOM until `attach(el)` — the provider-first
- * shape. `detach()` remounts from the saved bytes, which resets undo and the caret.
+ * shape. `detach()` parks the live document and a later `attach(el)` moves it in, with undo,
+ * selection and collaboration intact, even into another window (a pop-out or an iframe).
  *
  * `snapshot()` is version-cached: the same reference until state actually moves, with
  * reference-stable sub-objects, so it is safe as a `useSyncExternalStore` source.
@@ -3924,5 +4244,5 @@ interface ChromePrintJob {
  */
 declare function runChromePrint(editor: Pick<Editor, 'save'> & Partial<Pick<Editor, 'snapshot'>>, handlers?: ChromeExportHandlers, container?: Document | Element): Promise<ChromePrintJob>;
 
-export { CHROME_UNAVAILABLE_KEY as $, bindHistoryGroup as B, CHROME_GROUPS as C, blankDocumentBytes as E, chromeMenuSlots as G, commandForSlot as I, commandForSlotValue as J, createDocxEditor as K, createFontSource as M, customFonts as N, isChromePrintShortcut as O, loadFonts as P, runChromeExport as Q, runChromePrint as R, runToolbarCommand as U, toolbarCommandState as V, CHROME_MENUS as a, chromeControlCount as a$, DEFAULT_TABLE_CHROME_DRAFT as a8, TABLE_BORDER_STYLE_OPTIONS as aH, TABLE_BORDER_TARGET_OPTIONS as aI, TABLE_BORDER_WIDTH_OPTIONS as aJ, TABLE_CHROME_SLOT_IDS as aK, applyTableChromePick as aY, canExecuteImageCommand as aZ, captureImageMutationPreconditions as a_, EMU_PER_POINT as aa, IMAGE_OVERLAY_NUDGE_PT as ah, IMAGE_OVERLAY_NUDGE_SHIFT_PT as ai, ChromeExportError as b, chromeProbeForSlot as b0, chromeSlotId as b1, chromeSlotIsToggle as b2, commandExecOptions as b3, commandForTableChromeSlotValue as b4, computeImageResizeResult as b5, computeMovedImagePosition as b6, computeResizedImageExtentEmu as b7, createImageOverlayScrollPort as b8, cssPixelsToLayoutPoints as b9, toolbarCommandStates as bA, defaultChromeGroups as ba, defaultTableLabel as bb, emuToOverlayPoints as bc, equationAtPosition as bd, executeImageCommand as be, finalizeImageOverlayInteraction as bf, formattingBarChromeGroups as bg, isStaleImageInteractionCommit as bh, isTableChromeSlot as bi, layoutPointsToCssPixels as bj, overlayFrameToSheetCssPixels as bk, overlayHostOrigin as bl, pointsToEmu as bm, probeTableChromeCommand as bn, resizePreservesAspect as bo, runSave as bp, runTableChromeCommand as bq, runTableCommand as br, selectedDrawingOverlayTargetOf as bs, selectedImageStateOf as bt, surfacePaintScale as bu, tableChromeIconPaths as bv, tableChromeLabelKeyForTarget as bw, tableChromeToolbarState as bx, tableChromeVisible as by, tableCommandToolbarState as bz, ChromePrintError as l };
-export type { LockedControlNavigation as A, DocxEditorConfig as D, FontLoadFailure as F, HistoryGroupBinding as H, LoadFontsRequest as L, SurfaceHyperlink as S, ToolbarCommandState as T, PaginatedSurfaceOptions as W, OpenPaginatedResult as X, PaginatedSurface as Y, TableCommandPlan as Z, AnchorFrameOrigin as _, ChromeControl as a0, ChromeControlId as a1, ChromeControlState as a2, ChromeExportView as a3, ChromeGroup as a4, ChromeGroupId as a5, ContentControlWidgetChromeHandlers as a6, ContentControlWidgetSession as a7, DrawingSelectionIntent as a9, SelectedDrawingOverlayTarget as aA, SurfaceEquation as aB, SurfaceFormatting as aC, SurfaceInsertImageInput as aD, SurfaceNavigation as aE, SurfaceOverlayCoordinates as aF, SurfaceParagraphFormat as aG, TableBorderStyleOption as aL, TableBorderTargetOption as aM, TableBorderTargetValue as aN, TableBorderWidthOption as aO, TableChromeDraft as aP, TableChromePick as aQ, TableChromeSlotId as aR, TableInteractionLabelKey as aS, TextFormFieldChromeHandlers as aT, TextFormFieldDialogSession as aU, ToolbarSlotValue as aV, ToolbarValueMap as aW, ToolbarValueSlot as aX, EditorCommandExecute as ab, EquationActivation as ac, EquationChromeHandlers as ad, EquationOps as ae, FinalizedImageOverlayInteraction as af, HyperlinkOps as ag, ImageInteractionSession as aj, ImageOverlayScrollPort as ak, ImageResizeHandle as al, ImageResizeResult as am, InvalidTextFormFieldChromeHandlers as an, InvalidTextFormFieldSession as ao, OpeningIndicatorHost as ap, OverlayFrameRect as aq, PaginatedSurfaceState as ar, ParagraphPropertyEdit as as, PopupChromeRegistrationOptions as at, RemoteCaretLabelAnchor as au, RemoteCaretLabelHost as av, ReviewWriteIntent as aw, RunTableChromeCommandResult as ax, SectionAnchor as ay, SectionBreakInsertType as az, ChromeExportFormat as c, ChromeExportHandlers as d, ChromeExportResult as e, ChromeMenu as f, ChromeMenuEntry as g, ChromeMenuId as h, ChromeMenuItemEntry as i, ChromeMenuSeparatorEntry as j, ChromeMenuSubmenuEntry as k, ChromePrintErrorCode as m, ChromePrintJob as n, ChromePrintOptions as o, ChromeSlotId as p, CustomFontsOptions as q, CustomFontsResolver as r, DocxEditorInstance as s, FontLoadFailureReason as t, FontMeasurementState as u, FontUrlSource as v, HistoryGroupBindingOptions as w, HyperlinkActivation as x, HyperlinkChromeHandlers as y, LoadFontsResult as z };
+export { blankDocumentBytes as $, CHROME_GROUPS as C, bindHistoryGroup as _, chromeMenuSlots as a0, commandForSlot as a1, commandForSlotValue as a2, createDocxEditor as a3, createFontSource as a4, customFonts as a5, isChromePrintShortcut as a6, loadFonts as a7, runChromeExport as a8, runChromePrint as a9, TABLE_BORDER_STYLE_OPTIONS as aR, TABLE_BORDER_TARGET_OPTIONS as aS, TABLE_BORDER_WIDTH_OPTIONS as aT, TABLE_CHROME_SLOT_IDS as aU, runToolbarCommand as aa, toolbarCommandState as ab, CHROME_UNAVAILABLE_KEY as aj, DEFAULT_TABLE_CHROME_DRAFT as ap, EMU_PER_POINT as ar, IMAGE_OVERLAY_NUDGE_PT as aw, IMAGE_OVERLAY_NUDGE_SHIFT_PT as ax, applyTableChromePick as b3, canExecuteImageCommand as b4, captureImageMutationPreconditions as b5, chromeControlCount as b6, chromeProbeForSlot as b7, chromeSlotId as b8, chromeSlotIsToggle as b9, selectedImageStateOf as bA, surfacePaintScale as bB, tableChromeIconPaths as bC, tableChromeLabelKeyForTarget as bD, tableChromeToolbarState as bE, tableChromeVisible as bF, tableCommandToolbarState as bG, toolbarCommandStates as bH, commandExecOptions as ba, commandForTableChromeSlotValue as bb, computeImageResizeResult as bc, computeMovedImagePosition as bd, computeResizedImageExtentEmu as be, createImageOverlayScrollPort as bf, cssPixelsToLayoutPoints as bg, defaultChromeGroups as bh, defaultTableLabel as bi, emuToOverlayPoints as bj, equationAtPosition as bk, executeImageCommand as bl, finalizeImageOverlayInteraction as bm, formattingBarChromeGroups as bn, isStaleImageInteractionCommit as bo, isTableChromeSlot as bp, layoutPointsToCssPixels as bq, overlayFrameToSheetCssPixels as br, overlayHostOrigin as bs, pointsToEmu as bt, probeTableChromeCommand as bu, resizePreservesAspect as bv, runSave as bw, runTableChromeCommand as bx, runTableCommand as by, selectedDrawingOverlayTargetOf as bz, CHROME_MENUS as c, ChromeExportError as d, ChromePrintError as o };
+export type { AttachOptions as A, BookmarkChromeHandlers as B, DocxEditorConfig as D, EquationActivation as E, FontLoadFailure as F, FontLoadFailureReason as G, FontMeasurementState as H, FontUrlSource as I, GoToChromeHandlers as J, HistoryGroupBinding as K, HistoryGroupBindingOptions as L, HyperlinkActivation as M, HyperlinkChromeHandlers as N, InvalidTextFormFieldChromeHandlers as O, InvalidTextFormFieldSession as P, LoadFontsRequest as Q, LoadFontsResult as R, LockedControlNavigation as S, PopupChromeRegistrationOptions as T, SurfaceEquation as U, SurfaceHyperlink as V, TableChromeSlotId as W, ToolbarCommandState as X, ToolbarValueMap as Y, ToolbarValueSlot as Z, BookmarkMarkInfo as a, TableInteractionLabelKey as a$, ImageResizeHandle as aA, ImageResizeResult as aB, OpeningIndicatorHost as aC, OverlayFrameRect as aD, PaginatedSurfaceState as aE, ParagraphPropertyEdit as aF, RemoteCaretLabelAnchor as aG, RemoteCaretLabelHost as aH, ReviewWriteIntent as aI, RunTableChromeCommandResult as aJ, SectionAnchor as aK, SectionBreakInsertType as aL, SelectedDrawingOverlayTarget as aM, SurfaceInsertImageInput as aN, SurfaceNavigation as aO, SurfaceOverlayCoordinates as aP, SurfaceParagraphFormat as aQ, TableBorderStyleOption as aV, TableBorderTargetOption as aW, TableBorderTargetValue as aX, TableBorderWidthOption as aY, TableChromeDraft as aZ, TableChromePick as a_, PaginatedSurfaceOptions as ac, OpenPaginatedResult as ad, PaginatedSurface as ae, TableCommandPlan as af, SurfaceFormatting as ag, AnchorFrameOrigin as ah, BookmarkMarkOptionsSource as ai, ChromeControl as ak, ChromeControlId as al, ChromeControlState as am, ChromeGroup as an, ChromeGroupId as ao, DrawingSelectionIntent as aq, EditorCommandExecute as as, EquationOps as at, FinalizedImageOverlayInteraction as au, HyperlinkOps as av, ImageInteractionSession as ay, ImageOverlayScrollPort as az, BookmarkMarkOptions as b, TextFormFieldChromeHandlers as b0, TextFormFieldDialogSession as b1, ToolbarSlotValue as b2, ChromeExportFormat as e, ChromeExportHandlers as f, ChromeExportResult as g, ChromeExportView as h, ChromeMenu as i, ChromeMenuEntry as j, ChromeMenuId as k, ChromeMenuItemEntry as l, ChromeMenuSeparatorEntry as m, ChromeMenuSubmenuEntry as n, ChromePrintErrorCode as p, ChromePrintJob as q, ChromePrintOptions as r, ChromeSlotId as s, CommentDraftChromeHandlers as t, ContentControlWidgetChromeHandlers as u, ContentControlWidgetSession as v, CustomFontsOptions as w, CustomFontsResolver as x, DocxEditorInstance as y, EquationChromeHandlers as z };