@docx-editor.dev/core 2.29.0 → 2.31.0

package/dist/{editor-CZQZmTIU.d.ts → editor-B2ShlO23.d.ts}

@@ -1,13 +1,12 @@
-import { q as ResolvedRevisionMarkup, a as ReviewDisplayMode } from './semantic-records-DQmumPgL.js';
-import { t as DocAnchor, g as ReviewRevisionKind, c as ReviewCommentItem, b as ReviewRevisionItem, d as ReviewCustomItem, aI as SourceCrop, Y as DrawingKind, a1 as ImageWrapTarget, _ as DrawingPositionInput, Z as DrawingLocks, r as ColorValue, x as ExecErrorCode, a5 as ParagraphFormatCommand, af as Watermark, E as ExecResult, n as ContentControlFilter, o as DocRange, k as RunFormatting, p as Revision, a7 as Rect, ab as SelectionPin, ae as Unsubscribe } from './types-barrel-DuC5QBNC.js';
-import { H as HistoryDiagnostic, V as ViewScope, b as HistoryGroup, a as EditorExecOptions, E as EditorScope } from './editor-scope-7o9xweiJ.js';
+import { q as ResolvedRevisionMarkup, a as ReviewDisplayMode } from './semantic-records-B-akgRch.js';
+import { t as DocAnchor, g as ReviewRevisionKind, c as ReviewCommentItem, b as ReviewRevisionItem, d as ReviewCustomItem, aT as SourceCrop, Y as DrawingKind, a2 as ImageWrapTarget, _ as DrawingPositionInput, Z as DrawingLocks, a1 as ImageResourceState, r as ColorValue, x as ExecErrorCode, a6 as ParagraphFormatCommand, af as SupportedImageMime, al as Watermark, E as ExecResult, an as WatermarkState, n as ContentControlFilter, o as DocRange, k as RunFormatting, p as Revision, a9 as Rect, ae as SelectionPin, ai as Unsubscribe } from './types-barrel-CkF2JbU4.js';
+import { H as HistoryDiagnostic, V as ViewScope, b as HistoryGroup, a as EditorExecOptions, E as EditorScope, c as HistoryGroupOptions } from './editor-scope-C7ke1KJG.js';
+import { C as CollaborationDiagnosticCode, c as CustomNodeDiagnosticCode, D as DiagnosticErrorName, F as FailureStage, B as ByteSizeBucket, b as CountBucket, f as DocumentOpenDiagnosticCode, a as DocumentPartKind, g as DocumentSaveDiagnosticCode, E as EditDiagnosticCode, j as ReviewDiagnosticCode, k as ReviewOperation, R as ReviewChangeKind, i as FormattingChangeKind, h as FontDiagnosticCode, H as HistoryDiagnosticCode, P as PerformanceDiagnosticCode } from './diagnostic-hints-C9JlLz1L.js';
 import { DocEdits, DocQueries, DocQueryResults, ContentControlSummary } from './contracts/document.js';
 import { InteractionOutcome } from './contracts/interaction.js';
-import { a as SemanticSelection, S as SemanticPosition } from './semantic-interaction-kR_QB845.js';
-import { I as ImageResourceState, S as SupportedImageMime } from './image-resources-tXLQShoC.js';
-import { a as DocumentProtectionState } from './document-protection-CUb55pl_.js';
+import { a as SemanticSelection, S as SemanticPosition } from './semantic-interaction-dApRIYpt.js';
+import { a as DocumentProtectionState } from './document-protection-C8x3P2J6.js';
 import { C as CollaborationStatus } from './failure-NS2lsya4.js';
-import { C as CollaborationDiagnosticCode, c as CustomNodeDiagnosticCode, D as DiagnosticErrorName, F as FailureStage, B as ByteSizeBucket, b as CountBucket, f as DocumentOpenDiagnosticCode, a as DocumentPartKind, E as EditDiagnosticCode, i as ReviewDiagnosticCode, j as ReviewOperation, R as ReviewChangeKind, h as FormattingChangeKind, g as FontDiagnosticCode, H as HistoryDiagnosticCode, P as PerformanceDiagnosticCode } from './diagnostic-hints-BeVjfNOv.js';
 
 /**
  * When the review pane opens by itself.
@@ -50,7 +49,8 @@ type ReviewPaneOverflow = 'float' | 'shrinkPage' | 'scroll';
  * - `'balloons'`: the pane lists comments only, except comments that reply to a tracked
  *   change: the change's balloon shows those. A tracked change opens in a balloon at its
  *   text when the reader clicks it, or when Next Change, Previous Change, or
- *   `setActiveReviewItem(key, { announce: true })` reaches it.
+ *   `setActiveReviewItem(key, { announce: true })` reaches it. A replacement is one balloon.
+ *   In both settings, Next Change and Previous Change stop on a replacement once.
  *
  * @public
  */
@@ -246,6 +246,76 @@ type DocumentOpenDiagnostic = DiagnosticBase & {
     /** The role of the part that failed, such as `'header'`. Never its name. */
     readonly part?: DocumentPartKind;
 }));
+/**
+ * A `save()` call returned the document, or failed. Reported for each call, by the editor that
+ * saved. A save the host does afterwards, such as an upload, is the host's to measure.
+ *
+ * @public
+ */
+type DocumentSaveDiagnostic = DiagnosticBase & {
+    readonly kind: 'document.save';
+} & ({
+    readonly outcome: 'saved';
+    /** Size of the saved bytes. */
+    readonly sizeBucket: ByteSizeBucket;
+    /** Milliseconds from the `save()` call to the bytes, pending edits included. */
+    readonly durationMs: number;
+} | (DiagnosticFailureDetail & {
+    readonly outcome: 'rejected';
+    readonly code: DocumentSaveDiagnosticCode;
+    /** Milliseconds from the `save()` call to the failure. */
+    readonly durationMs: number;
+}));
+/**
+ * What an editor did over a window of use or over its whole session. Counts and milliseconds
+ * only: no key, position, command argument or text.
+ *
+ * @public
+ */
+interface SessionActivity {
+    /**
+     * For `active`, milliseconds from the window's first activity to the summary. For `end`,
+     * milliseconds from the editor's creation to its end, idle time included.
+     */
+    readonly durationMs: number;
+    /**
+     * Milliseconds of use: the time between key presses, pointer presses and edits that are at
+     * most 30 seconds apart. A longer pause counts as idle.
+     */
+    readonly activeMs: number;
+    /**
+     * Edits from typing, the clipboard, drag and drop, keyboard undo, and other input that changed
+     * the document. Each committed change counts once: typing commits about one change per
+     * character, and characters typed faster than the editor paints commit together.
+     */
+    readonly inputEdits: number;
+    /** Editor commands, from `exec(...)` or the toolbar, that changed the document. */
+    readonly commandEdits: number;
+    /** Editing API batches that changed the document. */
+    readonly automationEdits: number;
+}
+/**
+ * The lifecycle and activity of one editor instance, without any content.
+ *
+ * - `start`: the editor was created.
+ * - `active`: a summary of one window of use. Sent after a minute of activity, when the page is
+ *   hidden, and before `end`, if anything happened since the last summary. An idle editor sends
+ *   none, so `active` is not a heartbeat.
+ * - `end`: the editor was destroyed, or the page closed. Carries totals for the whole session.
+ *
+ * Edits count changes this editor committed. Refused edits are in `edit.rejected`, and edits
+ * that collaborators made are not counted. Sum `active` summaries or read `end` totals, not
+ * both: the totals include every summary.
+ *
+ * @public
+ */
+type SessionDiagnostic = DiagnosticBase & {
+    readonly kind: 'session';
+} & ({
+    readonly phase: 'start';
+} | (SessionActivity & {
+    readonly phase: 'active' | 'end';
+}));
 /** Where a refused edit came from. @public */
 type EditRejectionOrigin = 'command' | 'input' | 'automation';
 /** An edit, a command or a tracked change was refused. @public */
@@ -364,7 +434,11 @@ interface PerformanceDiagnostic extends DiagnosticBase {
      * presses were timed and more than one in 20 took over 200 ms.
      */
     readonly code?: PerformanceDiagnosticCode;
-    /** Milliseconds from the window's first timing to the summary. */
+    /**
+     * Milliseconds from the window's first timing to the summary, one minute or less. Idle time
+     * inside the window counts, so this is not active editing time. Use the `count` of
+     * `interaction` to measure activity.
+     */
     readonly windowMs: number;
     /** Pages in the document at the last paint. */
     readonly pagesBucket?: CountBucket;
@@ -398,7 +472,7 @@ interface PerformanceDiagnostic extends DiagnosticBase {
  *
  * @public
  */
-type EditorDiagnostic = DocumentOpenDiagnostic | EditRejectedDiagnostic | ReviewSkippedDiagnostic | FontFailedDiagnostic | HistoryDiagnosticEvent | CustomNodeDiagnosticEvent | CollaborationStatusDiagnostic | CollaborationParticipantsDiagnostic | PerformanceDiagnostic;
+type EditorDiagnostic = DocumentOpenDiagnostic | EditRejectedDiagnostic | ReviewSkippedDiagnostic | FontFailedDiagnostic | HistoryDiagnosticEvent | CustomNodeDiagnosticEvent | CollaborationStatusDiagnostic | CollaborationParticipantsDiagnostic | PerformanceDiagnostic | DocumentSaveDiagnostic | SessionDiagnostic;
 /** The `kind` of every {@link EditorDiagnostic}. @public */
 type EditorDiagnosticKind = EditorDiagnostic['kind'];
 
@@ -414,7 +488,11 @@ interface EditorEvents {
     revisionMarkupChange: (settings: ResolvedRevisionMarkup) => void;
     /** A document mutation committed, with the ids it touched. */
     change: (change: DocumentChange) => void;
-    /** The selection or its derived formatting moved. */
+    /**
+     * Observable editor state moved without a document change: the selection or its derived
+     * formatting, the armed typing format, the open header or footer, or the collaboration
+     * session's status.
+     */
     selectionChange: (snapshot: EditorSnapshot) => void;
     error: (error: EditorError) => void;
     historyDiagnostic: (diagnostic: HistoryDiagnostic) => void;
@@ -453,7 +531,42 @@ interface EditorEvents {
      * ```
      */
     reviewItemReveal: (event: ReviewItemRevealEvent) => void;
+    /**
+     * The editor's pages are now in another document: it was attached for the first time, moved
+     * into another element or window, detached (`document` is `null`), or found its element
+     * moved to another window by the host. Custom chrome that listens on the editor's document
+     * or measures its window re-binds here.
+     *
+     * @example
+     * ```ts
+     * editor.on('hostChange', ({ document }) => {
+     *   stopShortcuts?.();
+     *   stopShortcuts = document ? listenForShortcuts(document) : undefined;
+     * });
+     * ```
+     */
+    hostChange: (event: EditorHostChange) => void;
+}
+/**
+ * The payload of the `hostChange` event.
+ *
+ * @public
+ */
+interface EditorHostChange {
+    /** The document the pages are mounted in now, or `null` while the editor is detached. */
+    readonly document: EditorHostDocument | null;
 }
+/**
+ * The DOM `Document`, wherever DOM types are loaded (every browser host).
+ *
+ * Read from `globalThis` rather than named, so this contract also compiles in the engine's
+ * DOM-free lanes and on servers, where it falls back to `object`.
+ *
+ * @public
+ */
+type EditorHostDocument = typeof globalThis extends {
+    readonly document: infer D;
+} ? D : object;
 /**
  * The payload of the `reviewItemReveal` event.
  *
@@ -461,17 +574,18 @@ interface EditorEvents {
  */
 interface ReviewItemRevealEvent {
     /**
-     * The key of the review item to open, as `getReviewItems()` without `pairReplacements`
-     * lists it. Next Change and Previous Change step through that unpaired queue, so for a
-     * replacement this is the key of its deletion or its insertion. `setActiveReviewItem`
+     * The key of the review item to open, as `getReviewItems({ pairReplacements: false })`
+     * lists it, so for a replacement this is the key of its deletion or its insertion. Next
+     * Change and Previous Change stop once on a replacement and report its deletion's key,
+     * with the pair's key in {@link ReviewItemRevealEvent.pairKey}. `setActiveReviewItem`
      * reports the key it was given, so a call with a pair's key reports that key here and in
      * {@link ReviewItemRevealEvent.pairKey}.
      */
     readonly key: string;
     /**
-     * The key that `getReviewItems({ pairReplacements: true })` gives the replacement this item
-     * belongs to. Present only when the item is a paired replacement or one half of one. A
-     * host that lists pairs opens `pairKey ?? key`.
+     * The key that `getReviewItems()` gives the replacement this item belongs to, since it
+     * pairs replacements by default. Present only when the item is a paired replacement or one
+     * half of one. A host that reads the default list opens `pairKey ?? key`.
      */
     readonly pairKey?: string;
     /**
@@ -823,7 +937,7 @@ interface EditorReviewHits {
  *
  * Filtering revision kinds is how a host hides structural cards it has no UI for,
  * `placement: false` skips the layout pass entirely when only metadata is wanted, and
- * `pairReplacements` lists a typed-over selection as one decision.
+ * `pairReplacements: false` lists a typed-over selection as its two halves.
  */
 interface ReviewItemQuery {
     /**
@@ -836,8 +950,12 @@ interface ReviewItemQuery {
     /** When false, skip layout geometry; metadata is unchanged and anchors are null. Default true. */
     readonly placement?: boolean;
     /**
-     * When true, list a deletion and the insertion that directly follows it as one
-     * `'replace'` item. Default false.
+     * Whether to list a deletion and the insertion that directly follows it as one
+     * `'replace'` item. Default true. Set it to false to list the deletion and the insertion as
+     * separate items, for example to accept or reject each half on its own.
+     *
+     * A host that steps through the list with `setActiveReviewItem` stops once on
+     * each replacement with the default, as Next Change does.
      *
      * Two revisions pair when they are next to each other among the queue's revisions, the
      * deletion comes first, both have the same author, nesting level and `readOnly` value, and
@@ -857,6 +975,43 @@ interface ReviewItemQuery {
     readonly pairReplacements?: boolean;
 }
 
+/**
+ * The refused-open read model, split out of `editor.ts`.
+ *
+ * Re-exported from `editor.ts`, so consumers keep importing
+ * `@docx-editor.dev/core/contracts/editor`.
+ */
+
+/**
+ * What a person can do about a document that did not open. It groups the open codes so a
+ * host can pick a message without listing every code:
+ *
+ * - `damaged`: the archive or its XML is broken. Saving the file again in a desktop editor
+ *   can repair it.
+ * - `not-docx`: the bytes are not a `.docx` document, or hold no main document.
+ * - `too-large`: the file crosses a size, count or depth limit.
+ * - `blocked`: the file uses XML features that the editor refuses for security.
+ * - `unknown`: any other failure.
+ *
+ * @public
+ */
+type DocumentOpenFailureReason = 'damaged' | 'not-docx' | 'too-large' | 'blocked' | 'unknown';
+/**
+ * A document the editor refused to open. It carries a stable code only, never the file's
+ * content or name, so a host can show it, log it, or send it with a support request.
+ *
+ * Each refusal is a new object, so a host can compare it by reference to tell a second
+ * refusal of the same file from the first.
+ *
+ * @public
+ */
+interface DocumentOpenFailure {
+    /** The stable open code, the same one the `document.open` diagnostic reports. */
+    readonly code: DocumentOpenDiagnosticCode;
+    /** The group of {@link DocumentOpenFailure.code} that picks the message. */
+    readonly reason: DocumentOpenFailureReason;
+}
+
 /**
  * How activating a review item places it in the viewport, and whether it announces the
  * reveal.
@@ -972,8 +1127,8 @@ interface ReviewRevisionPlacement extends ReviewItemPlacementBase {
     readonly revisionKind: ReviewRevisionKind;
     /**
      * The words a replacement decision removes when {@link revisionKind} is `'replace'`.
-     * The built-in reader lists separate deletion and insertion cards unless the query sets
-     * {@link ReviewItemQuery.pairReplacements}.
+     * The built-in reader lists separate deletion and insertion cards when the query sets
+     * {@link ReviewItemQuery.pairReplacements} to false.
      */
     readonly replacedText?: string;
     readonly item: ReviewRevisionItem;
@@ -1245,7 +1400,8 @@ interface EditorFormatPainterCommands {
      * direct paragraph properties as well.
      *
      * Non-mutating: the capture lives on the editor, not in the document, and it survives
-     * until the next capture or until the editor is detached.
+     * until the next capture, a document load, or `destroy()`, including across a `detach()`
+     * and a later `attach()`.
      */
     copyFormatting: Record<never, never>;
     /**
@@ -1376,6 +1532,110 @@ interface SelectedImageState {
  */
 type ImageContext = SelectedImageState;
 
+/**
+ * Which kind of story a bookmark is in: the main text, a header or footer, or a note.
+ *
+ * @public
+ */
+type BookmarkStory = 'body' | 'headerFooter' | 'note';
+/**
+ * Where a bookmark is, finer than {@link BookmarkStory}: the main text, a header, a footer, a
+ * footnote or an endnote.
+ *
+ * @public
+ */
+type BookmarkPlace = 'body' | 'header' | 'footer' | 'footnote' | 'endnote';
+/**
+ * One bookmark, as the `bookmarks` query lists it.
+ *
+ * @public
+ */
+interface BookmarkSummary {
+    /** The name as the document writes it. Names compare without case. */
+    readonly name: string;
+    /** Whether the name starts with an underscore. Hidden bookmarks mark application targets. */
+    readonly hidden: boolean;
+    /** The story the bookmark starts in. */
+    readonly story: BookmarkStory;
+    /** The same story, telling a header from a footer and a footnote from an endnote. */
+    readonly place: BookmarkPlace;
+    /**
+     * Position in document order: the main text first, then headers, footers and notes. Sort by
+     * this value to list bookmarks by location.
+     */
+    readonly order: number;
+    /** Whether the bookmark marks a point rather than a range of text. */
+    readonly empty: boolean;
+    /** Whether the start of the selection is inside the bookmark, edges included. */
+    readonly atSelection: boolean;
+    /**
+     * How many other places carry the same name. Usually 0. Collaborators who add one name while
+     * offline can leave copies; the list, Go To and links use this bookmark, the first in
+     * document order. Adding the name again at this bookmark keeps it and removes the copies.
+     */
+    readonly duplicates: number;
+}
+/**
+ * The bookmark commands an editor accepts.
+ *
+ * @public
+ */
+interface EditorBookmarkCommands {
+    /**
+     * Bookmark the selection under `name`, or the caret position when the selection is
+     * collapsed. A bookmark that already has the name, compared without case, moves here, also
+     * from another story, in one undo step. Two collaborators who add one name offline both keep
+     * their bookmark; every replica reads the first in document order until the next write of the
+     * name, which replaces or removes both.
+     * Refused with `invalidArgs` for a name that does not start with a letter, holds a
+     * character other than a letter, a digit or an underscore, or has more than 40 characters.
+     */
+    insertBookmark: {
+        name: string;
+    };
+    /**
+     * Remove the bookmark with this name, compared without case, and any copies of it in other
+     * places. The text stays.
+     */
+    deleteBookmark: {
+        name: string;
+    };
+    /**
+     * Keep the bookmark this name means, the first in document order, and remove its copies, in
+     * one undo step. The selection does not move. Collaborators who add one name while offline
+     * can leave copies; `BookmarkSummary.duplicates` counts them. Refused with `notFound` when no
+     * bookmark has the name, and with `unsupported` when it has no copies.
+     */
+    keepFirstBookmark: {
+        name: string;
+    };
+    /** Select the bookmark's text, or put the caret at a point bookmark, and scroll to it. */
+    goToBookmark: {
+        name: string;
+    };
+    /** Show or hide bracket marks at bookmarks. A view command: the document does not change. */
+    toggleBookmarks: Record<never, never>;
+    /**
+     * Open the host's Go To UI, the Go to tab of `DocxEditor.Navigation`, the request its
+     * shortcut (Ctrl+G, Cmd+Option+G on macOS) sends. Allowed in a read-only document. Refused
+     * with `unsupported` while no host shows one. To jump without UI, run `goToBookmark`.
+     *
+     * `fromShortcut: true` asks as the shortcut does: also refused with `unsupported` when the
+     * Go To UI turned its shortcut off (`GoToChromeHandlers.shortcut`). Chrome that forwards the
+     * chord sends it, and a menu asks `can` with it before it shows the shortcut.
+     */
+    openGoTo: {
+        readonly fromShortcut?: boolean;
+    };
+    /**
+     * Open the Bookmark dialog the host registered, the same request the Insert menu and
+     * Ctrl/Cmd+Shift+F5 send. Allowed in a read-only document, where Go To still works.
+     * Refused with `unsupported` while no host shows a bookmark dialog, for example when the
+     * `bookmark` popup is `false`.
+     */
+    openBookmarkDialog: Record<never, never>;
+}
+
 /** Where the caret sits inside a table: its shape and current cell. */
 interface TableContext {
     readonly rows: number;
@@ -1608,6 +1868,11 @@ interface Editor extends EditorAnchorNavigation, EditorHighlights, EditorReviewH
      * Serialize the current document, finalizing pending text form values first.
      * Invalid input rejects with `EditorError.code === 'invalidArgs'` and remains editable.
      * Validation does not open a dialog. Other write refusals also reject the save.
+     *
+     * The bytes describe the document as it was when you called `save()`. The file is written
+     * in short tasks, so input stays responsive while a long document saves, and edits made
+     * meanwhile belong to the next save. Paragraphs and table rows unchanged since an earlier
+     * save are not written again, so autosave after a small edit stays cheap.
      */
     save(): Promise<ArrayBuffer>;
     getDocumentHandle(): DocumentHandle;
@@ -1761,11 +2026,11 @@ interface Editor extends EditorAnchorNavigation, EditorHighlights, EditorReviewH
     setTableInteractionLabel(resolver: (key: 'table.insertRowBelow' | 'table.insertColumnRight') => string): void;
     /** Section page setup — size, orientation and margins — for the page-setup dialog. */
     getPageSetup(): PageSetup | null;
-    /** The document watermark, for the watermark dialog. */
-    getWatermark(): {
-        readonly kind: 'text' | 'image';
-        readonly text?: string;
-    } | null;
+    /**
+     * The watermark the document shows, read from the first section's headers; null when it
+     * shows none. For a picture watermark's bytes, use `query({ type: 'watermark' })`.
+     */
+    getWatermark(): WatermarkState | null;
     /** Header/footer editing state: which region is being edited, if any. */
     getHeaderFooterState(): HeaderFooterState | null;
     /** Resolved and authored note properties for the caret section — properties dialog read-model. */
@@ -1858,8 +2123,25 @@ interface Editor extends EditorAnchorNavigation, EditorHighlights, EditorReviewH
      * Anchored to the RETAINED range when there is one, so a compose box that took focus does
      * not lose the words it is about — that is what retention exists for. Refused on a
      * collapsed caret: a comment with no range has nothing to point at, and Word writes none.
+     *
+     * A refused write names its cause, as every review write does: `code: 'locked'` with
+     * `'the document is open for viewing'` in viewing or under read-only protection, and
+     * `code: 'unsupported'` with the external refresh sentence or a collaboration reason token
+     * such as `'collaboration-session-not-ready'` (wait for the session, then retry). Branch on
+     * `diagnosticCodeOfRefusal(result.reason, result.code)`, not on the text.
+     *
+     * Pass `options.historyGroup` to make the comment part of a larger undo step, such as a
+     * review decision that also resolves changes. See {@link HistoryGroupOptions}.
+     *
+     * @example
+     * ```ts
+     * editor.addComment('Counter-proposal: 45 days.', { historyGroup: decision });
+     * editor.addComment('Approved.', 'Legal team', { historyGroup: decision });
+     * ```
      */
-    addComment(text: string, author?: string): ExecResult;
+    addComment(text: string, options?: HistoryGroupOptions): ExecResult;
+    /** {@link addComment} with an author for this call, overriding the configured author. */
+    addComment(text: string, author?: string, options?: HistoryGroupOptions): ExecResult;
     /**
      * Where a comment on the current selection would sit, in the same space as
      * {@link ReviewItemPlacement.anchorY}, or null when nothing is selected.
@@ -1895,16 +2177,15 @@ interface Editor extends EditorAnchorNavigation, EditorHighlights, EditorReviewH
      * caret that merely lands in a change leaves this `null`. Open a balloon or card for the
      * activated item, and highlight the caret-active one.
      *
-     * Pass the query you read items with, so the key matches theirs: with
-     * `pairReplacements: true`, a paired replacement reports the pair's key; without it, the
-     * key of the half the caret is in. The value changes with the selection, so read it again
-     * on `selectionChange`.
+     * Pass the query you read items with, so the key matches theirs. By default a paired
+     * replacement reports the pair's key; with `pairReplacements: false`, the key of the half
+     * the caret is in. The value changes with the selection, so read it again on
+     * `selectionChange`.
      *
      * @example
      * ```ts
-     * const query = { pairReplacements: true };
      * editor.on('selectionChange', () => {
-     *   const activated = editor.getActivatedReviewItemKey(query);
+     *   const activated = editor.getActivatedReviewItemKey();
      *   if (activated !== null) showMyCard(activated);
      * });
      * ```
@@ -1931,17 +2212,20 @@ interface Editor extends EditorAnchorNavigation, EditorHighlights, EditorReviewH
      *
      * Refused for a card whose kind the engine cannot resolve structurally, which is why
      * `readOnly` is on the item — a surface should not offer the button in the first place.
+     * Other refusals name their cause, as {@link addComment} describes.
      */
-    acceptReviewItem(key: string): ExecResult;
-    rejectReviewItem(key: string): ExecResult;
+    acceptReviewItem(key: string, options?: HistoryGroupOptions): ExecResult;
+    /** The rejecting half of {@link acceptReviewItem}, with the same rules and options. */
+    rejectReviewItem(key: string, options?: HistoryGroupOptions): ExecResult;
     /**
      * Resolve or reopen the comment thread behind a review card.
      *
      * The thread state is written through the same package transaction as every other comment
      * mutation, so `commentsExtended.xml`, Undo and save/reopen cannot disagree. Repeating the
-     * state already on the item succeeds without adding an undo entry.
+     * state already on the item succeeds without adding an undo entry. A refusal names its cause,
+     * as {@link addComment} describes.
      */
-    setCommentResolved(key: string, resolved: boolean): ExecResult;
+    setCommentResolved(key: string, resolved: boolean, options?: HistoryGroupOptions): ExecResult;
     /**
      * Discard the item behind a card: the destructive half of the review verbs.
      *
@@ -1955,9 +2239,10 @@ interface Editor extends EditorAnchorNavigation, EditorHighlights, EditorReviewH
      * a surface can put one "remove this" affordance on every card instead of branching.
      *
      * Refused on a custom node's card, which is informational, and on a revision kind the engine
-     * cannot resolve — the same rule {@link rejectReviewItem} follows.
+     * cannot resolve — the same rule {@link rejectReviewItem} follows. Other refusals name their
+     * cause, as {@link addComment} describes, and leave the open card and its draft open.
      */
-    deleteReviewItem(key: string): ExecResult;
+    deleteReviewItem(key: string, options?: HistoryGroupOptions): ExecResult;
     /**
      * Reply to a review item.
      *
@@ -1968,8 +2253,11 @@ interface Editor extends EditorAnchorNavigation, EditorHighlights, EditorReviewH
      * The author is AMBIENT — `DocxEditorConfig.author`, the way the rest of the authored commands
      * source it — and the argument overrides it for one call. `CT_Comment` makes `@w:author`
      * required, so a reply with neither is refused rather than written as an empty attribute.
+     * Other refusals name their cause, as {@link addComment} describes.
      */
-    replyToReviewItem(key: string, text: string, author?: string): ExecResult;
+    replyToReviewItem(key: string, text: string, options?: HistoryGroupOptions): ExecResult;
+    /** {@link replyToReviewItem} with an author for this call, overriding the configured author. */
+    replyToReviewItem(key: string, text: string, author?: string, options?: HistoryGroupOptions): ExecResult;
     setActiveScope(scope: ViewScope): void;
     getActiveScope(): ViewScope;
     query<K extends keyof EditorQueries>(query: {
@@ -2093,7 +2381,7 @@ type TrackedChangeFilterMode = 'accept' | 'reject';
  * selection, view state, chrome modes, header/footer and note editing. An interface rather than a
  * closed union so an extension can widen it by declaration merging.
  */
-interface EditorCommands extends EditorCommandShape<DocEdits>, EditorHeaderFooterCommands, EditorNoteCommands, EditorFormatPainterCommands {
+interface EditorCommands extends EditorCommandShape<DocEdits>, EditorHeaderFooterCommands, EditorNoteCommands, EditorFormatPainterCommands, EditorBookmarkCommands {
     /** Switch how edits are written. A view command: it changes no document state. */
     setEditingMode: {
         mode: DocumentEditingMode;
@@ -2112,7 +2400,17 @@ interface EditorCommands extends EditorCommandShape<DocEdits>, EditorHeaderFoote
     toggleParagraphMarks: Record<never, never>;
     /** Word's Protect Document: enforce filling-in-forms protection, or lift the enforced one. */
     toggleDocumentProtection: Record<never, never>;
-    /** Navigate tracked changes, including hidden formatting balloons, and wrap at the end. */
+    /**
+     * Navigate tracked changes, including hidden formatting balloons, and wrap at the end.
+     *
+     * A replacement is one stop in every review layout. A replacement is a deletion and the
+     * touching insertion from the same author that took its place. Navigation lands on the
+     * deletion, highlights both halves, and `reviewItemReveal` carries the pair's `pairKey`.
+     *
+     * Navigation steps through the changes {@link Editor.getReviewItems} returns, so a
+     * reviewer or `setTrackedChangesFilter` filter applies. When a filter hides one half of a
+     * replacement, the other half is a stop of its own.
+     */
     navigateReviewChange: {
         direction: 'next' | 'previous';
     };
@@ -2320,11 +2618,10 @@ interface EditorCommands extends EditorCommandShape<DocEdits>, EditorHeaderFoote
         positionTwips: number;
     };
     /**
-     * Replace one found match with `text`. Addressed by {@link TextMatch} rather than a
-     * `DocTarget` because that is what `findMatches` hands back, and re-deriving a target
-     * from it in the caller is where an off-by-one would come from. An empty `text`
-     * deletes the match, which is what a find/replace dialog means by replacing with
-     * nothing.
+     * Replace one found match with `text`, addressed by the {@link TextMatch} `findMatches`
+     * returns. An empty `text` deletes it. The selection and scroll position stay put. In
+     * suggesting mode it is a tracked replacement under the editor's author, refused where
+     * `proposeReplacement` would be. The match must be in the open story, not a text box.
      */
     replaceMatch: {
         match: TextMatch;
@@ -2431,6 +2728,11 @@ interface EditorCommands extends EditorCommandShape<DocEdits>, EditorHeaderFoote
         drawingNodeId?: string;
         expectedPackageRevision?: number;
     };
+    /**
+     * Replace the document watermark in every header the document shows; null removes it. One
+     * undo step. Refuses with `invalidArgs` for an invalid option and `locked` in a protected
+     * document; a refusal writes nothing. See {@link Watermark} for the options and defaults.
+     */
     setWatermark: {
         watermark: Watermark | null;
     };
@@ -2540,6 +2842,8 @@ interface EditorQueries extends DocQueries {
         pos: number;
     };
     trackedChanges: Record<never, never>;
+    /** Every bookmark in the document, hidden ones included, in document order. */
+    bookmarks: Record<never, never>;
 }
 /**
  * One query, as a discriminated union derived from {@link EditorQueries}.
@@ -2566,6 +2870,7 @@ interface EditorQueryResults extends DocQueryResults {
     contentControlAt: ContentControlSummary | null;
     isInsideToc: boolean;
     trackedChanges: readonly Revision[];
+    bookmarks: readonly BookmarkSummary[];
 }
 /**
  * One occurrence of a search query in the document.
@@ -2670,6 +2975,13 @@ interface EditorSnapshot {
      */
     readonly isOpening?: boolean;
     readonly parseError: string | null;
+    /**
+     * Why the last supplied document did not open, or `null` while it opens or after it opened.
+     * Unlike {@link EditorSnapshot.parseError}, it holds a stable code and never quotes the
+     * file, so a host can show it to a person. `DocxEditor.OpenFailure` renders it. Optional
+     * and additive: absent means the implementation has not derived it, read as `null`.
+     */
+    readonly openFailure?: DocumentOpenFailure | null;
     /** Whether the loaded document is being edited: a patchable document opened in edit mode. A
      *  read-only document (tables/SDTs/unpreservable) or `mode: 'view'` reports false. */
     readonly editable: boolean;
@@ -2745,6 +3057,8 @@ interface EditorSnapshot {
     readonly reviewPane: ResolvedReviewPane;
     /** Whether Show/Hide paragraph marks is enabled. */
     readonly showParagraphMarks?: boolean;
+    /** Whether bracket marks are shown at bookmarks. */
+    readonly showBookmarks?: boolean;
     /** The document's `w:documentProtection`, as the file states it; null with no document. */
     readonly documentProtection?: DocumentProtectionState | null;
     /** The displayed revision projection. The document and its revision history stay unchanged. */
@@ -2815,11 +3129,13 @@ interface EditorSnapshot {
  * An error the engine raised, carrying a machine-readable `code` alongside the message.
  *
  * `code` is optional because an `Error` from deeper down (a parser, a codec) is surfaced as-is
- * rather than wrapped in a fabricated code.
+ * rather than wrapped in a fabricated code. The editor's own codes: `invalidTarget` (`attach`
+ * cannot mount there), `unsupported` (a source it refuses to open), and `hostCallback` (a host
+ * callback such as a bookmark mark's `decorate` threw; the editor kept its default behavior).
  */
 interface EditorError extends Error {
     readonly code?: string;
 }
 
-export { DIAGNOSTIC_SCHEMA_VERSION as D, validateImageCropPercent as a$, DEFAULT_REVIEW_PANE as aN, cropPercentFromCropPermille as aT, cropPercentFromPermille as aU, cropPercentFromSourceCrop as aV, cropPermilleFromCropPercent as aW, cropPermilleFromPercent as aX, resolveReviewPane as aY, reviewPaneListsItem as aZ, sourceCropFromCropPercent as a_, EditorFontError as y };
-export type { HighlightHit as $, AnchorHighlightAnimation as A, EditorFormatPainterCommands as B, CanResult as C, EditorDiagnostic as E, EditorHeaderFooterCommands as F, EditorHighlights as G, EditorNoteCommands as H, EditorPosition as I, EditorQueries as J, EditorQuery as K, EditorQueryResults as L, EditorReviewHits as M, EditorSelection as N, EditorSnapshot as O, FontConfiguration as P, FontFaceRequest as Q, ReviewPaneOptions as R, FontFailedDiagnostic as S, FontSource as T, FontSourceSubstitution as U, FormatPainterLevel as V, FormatPainterMode as W, FormatPainterSurfaceState as X, FurnitureVariant as Y, HeaderFooterSlotArgs as Z, HeaderFooterState as _, EditorDiagnosticKind as a, HighlightOptions as a0, HighlightRange as a1, HighlightRect as a2, HighlightResult as a3, HistoryDiagnosticEvent as a4, HyperlinkInfo as a5, ImageContext as a6, ImageCropPercent as a7, NoteKind as a8, NotePropertiesSide as a9, TableColumnDividerResizeTarget as aA, TableColumnOccurrenceTarget as aB, TableContext as aC, TableRightEdgeResizeTarget as aD, TableRowOccurrenceTarget as aE, TextMatch as aF, TimingSummary as aG, TrackedChangeFilterMode as aH, TrackedChangePredicate as aI, ZoomFitTarget as aJ, ZoomMode as aK, ReviewPaneOverflow as aL, CommentMarkerStyle as aM, ImageCropPermille as aO, ResolvedReviewPane as aP, ReviewPaneItemFields as aQ, ReviewPaneOpening as aR, RevisionDisplay as aS, NotePropertiesState as aa, PageSetup as ab, PerformanceDiagnostic as ac, ResolveReviewChangesOptions as ad, ResolvedNoteNumbering as ae, ReviewActivationOptions as af, ReviewChangesAttribution as ag, ReviewCommentPlacement as ah, ReviewCustomPlacement as ai, ReviewItemHit as aj, ReviewItemPlacement as ak, ReviewItemPlacementBase as al, ReviewItemQuery as am, ReviewItemRevealEvent as an, ReviewItemRevealSource as ao, ReviewRevisionPlacement as ap, ReviewSkippedDiagnostic as aq, ScrollPlacement as ar, ScrollToAnchorOptions as as, SelectedImageState as at, SetReviewChangesAuthorOptions as au, TableBorderEdgeTarget as av, TableBorderSpec as aw, TableBorderStyle as ax, TableBorderTarget as ay, TableCellVerticalAlignment as az, EditorCommand as b, AnchorHighlightOptions as c, AuthoredNoteNumbering as d, ClearAnchorHighlightOptions as e, CollaborationParticipantsDiagnostic as f, CollaborationStatusDiagnostic as g, CustomNodeDiagnosticEvent as h, DiagnosticBase as i, DiagnosticFailureDetail as j, DocumentChange as k, DocumentEditingMode as l, DocumentHandle as m, DocumentOpenDiagnostic as n, DocumentShape as o, DocumentSource as p, EditRejectedDiagnostic as q, EditRejectionOrigin as r, Editor as s, EditorAnchorNavigation as t, EditorCommandShape as u, EditorCommands as v, EditorError as w, EditorEvents as x, EditorFontErrorCode as z };
+export { DIAGNOSTIC_SCHEMA_VERSION as D, EditorFontError as J, DEFAULT_REVIEW_PANE as aY, cropPercentFromCropPermille as b2, cropPercentFromPermille as b3, cropPercentFromSourceCrop as b4, cropPermilleFromCropPercent as b5, cropPermilleFromPercent as b6, resolveReviewPane as b7, reviewPaneListsItem as b8, sourceCropFromCropPercent as b9, validateImageCropPercent as ba };
+export type { FontFailedDiagnostic as $, AnchorHighlightAnimation as A, BookmarkPlace as B, CanResult as C, EditorDiagnostic as E, EditorCommandShape as F, EditorCommands as G, EditorError as H, EditorEvents as I, EditorFontErrorCode as K, EditorFormatPainterCommands as L, EditorHeaderFooterCommands as M, EditorHighlights as N, EditorHostChange as O, EditorHostDocument as P, EditorNoteCommands as Q, ReviewPaneOptions as R, EditorPosition as S, EditorQueries as T, EditorQuery as U, EditorQueryResults as V, EditorReviewHits as W, EditorSelection as X, EditorSnapshot as Y, FontConfiguration as Z, FontFaceRequest as _, EditorDiagnosticKind as a, ReviewPaneItemFields as a$, FontSource as a0, FontSourceSubstitution as a1, FormatPainterLevel as a2, FormatPainterMode as a3, FormatPainterSurfaceState as a4, FurnitureVariant as a5, HeaderFooterSlotArgs as a6, HeaderFooterState as a7, HighlightHit as a8, HighlightOptions as a9, ScrollPlacement as aA, ScrollToAnchorOptions as aB, SelectedImageState as aC, SessionActivity as aD, SessionDiagnostic as aE, SetReviewChangesAuthorOptions as aF, TableBorderEdgeTarget as aG, TableBorderSpec as aH, TableBorderStyle as aI, TableBorderTarget as aJ, TableCellVerticalAlignment as aK, TableColumnDividerResizeTarget as aL, TableColumnOccurrenceTarget as aM, TableContext as aN, TableRightEdgeResizeTarget as aO, TableRowOccurrenceTarget as aP, TextMatch as aQ, TimingSummary as aR, TrackedChangeFilterMode as aS, TrackedChangePredicate as aT, ZoomFitTarget as aU, ZoomMode as aV, ReviewPaneOverflow as aW, CommentMarkerStyle as aX, ImageCropPermille as aZ, ResolvedReviewPane as a_, HighlightRange as aa, HighlightRect as ab, HighlightResult as ac, HistoryDiagnosticEvent as ad, HyperlinkInfo as ae, ImageContext as af, ImageCropPercent as ag, NoteKind as ah, NotePropertiesSide as ai, NotePropertiesState as aj, PageSetup as ak, PerformanceDiagnostic as al, ResolveReviewChangesOptions as am, ResolvedNoteNumbering as an, ReviewActivationOptions as ao, ReviewChangesAttribution as ap, ReviewCommentPlacement as aq, ReviewCustomPlacement as ar, ReviewItemHit as as, ReviewItemPlacement as at, ReviewItemPlacementBase as au, ReviewItemQuery as av, ReviewItemRevealEvent as aw, ReviewItemRevealSource as ax, ReviewRevisionPlacement as ay, ReviewSkippedDiagnostic as az, EditorCommand as b, ReviewPaneOpening as b0, RevisionDisplay as b1, AnchorHighlightOptions as c, AuthoredNoteNumbering as d, BookmarkStory as e, BookmarkSummary as f, ClearAnchorHighlightOptions as g, CollaborationParticipantsDiagnostic as h, CollaborationStatusDiagnostic as i, CustomNodeDiagnosticEvent as j, DiagnosticBase as k, DiagnosticFailureDetail as l, DocumentChange as m, DocumentEditingMode as n, DocumentHandle as o, DocumentOpenDiagnostic as p, DocumentOpenFailure as q, DocumentOpenFailureReason as r, DocumentSaveDiagnostic as s, DocumentShape as t, DocumentSource as u, EditRejectedDiagnostic as v, EditRejectionOrigin as w, Editor as x, EditorAnchorNavigation as y, EditorBookmarkCommands as z };