@docx-editor.dev/core 2.30.0 → 2.31.0

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

@@ -1,19 +1,18 @@
-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-CWh40DYp.js';
+import { e as BookmarkStory, u as DocumentSource, Z as FontConfiguration, aV as ZoomMode, J as EditorFontError, x as Editor, R as ReviewPaneOptions, b as EditorCommand, C as CanResult, aC as SelectedImageState, a4 as FormatPainterSurfaceState, f as BookmarkSummary, aA as ScrollPlacement, aT as TrackedChangePredicate, aS as TrackedChangeFilterMode, _ as FontFaceRequest, a0 as FontSource, af as ImageContext, aG as TableBorderEdgeTarget, aH as TableBorderSpec, aI as TableBorderStyle, aN as TableContext } from './editor-B2ShlO23.js';
+import { V as ViewScope, a as EditorExecOptions } from './editor-scope-C7ke1KJG.js';
+import { ao as TreeDocOp, b0 as TextFormFieldRange, b1 as TextFormFieldOptions, aE as ImageDecodePort, ai as Unsubscribe, E as ExecResult, _ as DrawingPositionInput, b2 as DrawingTransform, A as ParagraphTabStop, y as IndentFormatting, z as ParagraphFlags, a5 as ParagraphDisagreements, aJ as DrawingTreeDocOp, af as SupportedImageMime, ae as SelectionPin, Q as OoxmlPackage, g as ReviewRevisionKind, aH as PackageWatermarkWrite, a2 as ImageWrapTarget } from './types-barrel-CkF2JbU4.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-B-akgRch.js';
+import { F as FieldResultsMode, C as ContentLockPolicy, I as InsertImageInput, S as StoryScope, A as ApplyImagePropertiesInput, i as ImageIntentResult } from './tree-package-store-B8l8DX3Z.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, d as RevisionStyles, f as DrawingPaintStrings, R as ReviewAuthorInfo, c as RevisionAuthorStyle } from './semantic-paint-DLzA8sjP.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-dApRIYpt.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 { R as ResolvedFootnoteProperties, a as ResolvedEndnoteProperties, A as AuthoredNoteProperties } from './note-properties-QsKh24sM.js';
+import { B as BookmarkIndex } from './custom-node-writes-TeUvMP13.js';
+import { C as CellSelection } from './semantic-cell-selection-Cub9FDa8.js';
+import { T as TreeDocxSessionView, a as TreeApplyResult } from './tree-session-contract-DeLRqohz.js';
 import { C as CollaborationStatus } from './failure-NS2lsya4.js';
 
 /**
@@ -259,10 +258,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 +283,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 +344,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 +391,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
@@ -407,6 +437,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 +469,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;
@@ -656,10 +704,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.
  *
@@ -684,6 +828,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
@@ -892,20 +1058,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.
      *
-     * 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.
+     * 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.
+     *
+     * 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 +1676,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 +1725,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 +1898,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.
      *
@@ -2055,6 +2271,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 +2283,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.
      *
@@ -2198,11 +2421,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 +2489,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 +2571,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 +2639,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 +3384,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';
@@ -3439,6 +3702,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 +3739,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' | '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 +4071,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 +4209,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 { CHROME_GROUPS as C, bindHistoryGroup as J, blankDocumentBytes as K, chromeMenuSlots as M, commandForSlot as N, commandForSlotValue as O, createDocxEditor as P, createFontSource as Q, customFonts as R, isChromePrintShortcut as U, loadFonts as V, runChromeExport as W, runChromePrint as X, runToolbarCommand as Y, toolbarCommandState as Z, CHROME_UNAVAILABLE_KEY as a7, TABLE_BORDER_STYLE_OPTIONS as aO, TABLE_BORDER_TARGET_OPTIONS as aP, TABLE_BORDER_WIDTH_OPTIONS as aQ, TABLE_CHROME_SLOT_IDS as aR, DEFAULT_TABLE_CHROME_DRAFT as ag, EMU_PER_POINT as ai, IMAGE_OVERLAY_NUDGE_PT as ap, IMAGE_OVERLAY_NUDGE_SHIFT_PT as aq, CHROME_MENUS as b, 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, ChromeExportError as c, ChromePrintError as m };
+export type { OpenPaginatedResult as $, HyperlinkChromeHandlers as A, BookmarkMarkInfo as B, DocxEditorConfig as D, LoadFontsResult as E, FontLoadFailure as F, GoToChromeHandlers as G, HistoryGroupBinding as H, LockedControlNavigation as I, LoadFontsRequest as L, SurfaceHyperlink as S, ToolbarCommandState as T, PaginatedSurfaceOptions as _, BookmarkMarkOptions as a, TextFormFieldDialogSession as a$, PaginatedSurface as a0, TableCommandPlan as a1, SurfaceFormatting as a2, AnchorFrameOrigin as a3, AttachOptions as a4, BookmarkChromeHandlers as a5, BookmarkMarkOptionsSource as a6, ChromeControl as a8, ChromeControlId as a9, ParagraphPropertyEdit as aA, PopupChromeRegistrationOptions as aB, RemoteCaretLabelAnchor as aC, RemoteCaretLabelHost as aD, ReviewWriteIntent as aE, RunTableChromeCommandResult as aF, SectionAnchor as aG, SectionBreakInsertType as aH, SelectedDrawingOverlayTarget as aI, SurfaceEquation as aJ, SurfaceInsertImageInput as aK, SurfaceNavigation as aL, SurfaceOverlayCoordinates as aM, SurfaceParagraphFormat as aN, TableBorderStyleOption as aS, TableBorderTargetOption as aT, TableBorderTargetValue as aU, TableBorderWidthOption as aV, TableChromeDraft as aW, TableChromePick as aX, TableChromeSlotId as aY, TableInteractionLabelKey as aZ, TextFormFieldChromeHandlers as a_, ChromeControlState as aa, ChromeExportView as ab, ChromeGroup as ac, ChromeGroupId as ad, ContentControlWidgetChromeHandlers as ae, ContentControlWidgetSession as af, DrawingSelectionIntent as ah, EditorCommandExecute as aj, EquationActivation as ak, EquationChromeHandlers as al, EquationOps as am, FinalizedImageOverlayInteraction as an, HyperlinkOps as ao, ImageInteractionSession as ar, ImageOverlayScrollPort as as, ImageResizeHandle as at, ImageResizeResult as au, InvalidTextFormFieldChromeHandlers as av, InvalidTextFormFieldSession as aw, OpeningIndicatorHost as ax, OverlayFrameRect as ay, PaginatedSurfaceState as az, ToolbarSlotValue as b0, ToolbarValueMap as b1, ToolbarValueSlot as b2, ChromeExportFormat as d, ChromeExportHandlers as e, ChromeExportResult as f, ChromeMenu as g, ChromeMenuEntry as h, ChromeMenuId as i, ChromeMenuItemEntry as j, ChromeMenuSeparatorEntry as k, ChromeMenuSubmenuEntry as l, ChromePrintErrorCode as n, ChromePrintJob as o, ChromePrintOptions as p, ChromeSlotId as q, CommentDraftChromeHandlers as r, CustomFontsOptions as s, CustomFontsResolver as t, DocxEditorInstance as u, FontLoadFailureReason as v, FontMeasurementState as w, FontUrlSource as x, HistoryGroupBindingOptions as y, HyperlinkActivation as z };