@docx-editor.dev/core 2.30.0 → 2.31.0

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

@@ -1,13 +1,12 @@
-import { q as ResolvedRevisionMarkup, a as ReviewDisplayMode } from './semantic-records-CjcF26ZL.js';
-import { t as DocAnchor, g as ReviewRevisionKind, c as ReviewCommentItem, b as ReviewRevisionItem, d as ReviewCustomItem, aJ 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-CA0xB8kH.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-Dc3pf3hr.js';
-import { I as ImageResourceState, S as SupportedImageMime } from './image-resources-Bipz8toD.js';
-import { a as DocumentProtectionState } from './document-protection-8eyMWIJ0.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, 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-2Bke6H_w.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
  */
@@ -488,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;
@@ -527,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.
  *
@@ -535,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;
     /**
@@ -897,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 {
     /**
@@ -910,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
@@ -931,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.
@@ -1046,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;
@@ -1319,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>;
     /**
@@ -1450,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;
@@ -1682,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;
@@ -1835,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. */
@@ -1932,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.
@@ -1969,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);
      * });
      * ```
@@ -2005,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.
      *
@@ -2029,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.
      *
@@ -2042,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: {
@@ -2167,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;
@@ -2186,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';
     };
@@ -2394,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;
@@ -2505,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;
     };
@@ -2614,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}.
@@ -2640,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.
@@ -2744,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;
@@ -2819,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. */
@@ -2889,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, resolveReviewPane as a$, DEFAULT_REVIEW_PANE as aQ, cropPercentFromCropPermille as aW, cropPercentFromPermille as aX, cropPercentFromSourceCrop as aY, cropPermilleFromCropPercent as aZ, cropPermilleFromPercent as a_, reviewPaneListsItem as b0, sourceCropFromCropPercent as b1, validateImageCropPercent as b2, EditorFontError as z };
-export type { HeaderFooterState as $, AnchorHighlightAnimation as A, EditorFontErrorCode as B, CanResult as C, EditorDiagnostic as E, EditorFormatPainterCommands as F, EditorHeaderFooterCommands as G, EditorHighlights as H, EditorNoteCommands as I, EditorPosition as J, EditorQueries as K, EditorQuery as L, EditorQueryResults as M, EditorReviewHits as N, EditorSelection as O, EditorSnapshot as P, FontConfiguration as Q, ReviewPaneOptions as R, FontFaceRequest as S, FontFailedDiagnostic as T, FontSource as U, FontSourceSubstitution as V, FormatPainterLevel as W, FormatPainterMode as X, FormatPainterSurfaceState as Y, FurnitureVariant as Z, HeaderFooterSlotArgs as _, EditorDiagnosticKind as a, HighlightHit as a0, HighlightOptions as a1, HighlightRange as a2, HighlightRect as a3, HighlightResult as a4, HistoryDiagnosticEvent as a5, HyperlinkInfo as a6, ImageContext as a7, ImageCropPercent as a8, NoteKind as a9, TableBorderStyle as aA, TableBorderTarget as aB, TableCellVerticalAlignment as aC, TableColumnDividerResizeTarget as aD, TableColumnOccurrenceTarget as aE, TableContext as aF, TableRightEdgeResizeTarget as aG, TableRowOccurrenceTarget as aH, TextMatch as aI, TimingSummary as aJ, TrackedChangeFilterMode as aK, TrackedChangePredicate as aL, ZoomFitTarget as aM, ZoomMode as aN, ReviewPaneOverflow as aO, CommentMarkerStyle as aP, ImageCropPermille as aR, ResolvedReviewPane as aS, ReviewPaneItemFields as aT, ReviewPaneOpening as aU, RevisionDisplay as aV, NotePropertiesSide as aa, NotePropertiesState as ab, PageSetup as ac, PerformanceDiagnostic as ad, ResolveReviewChangesOptions as ae, ResolvedNoteNumbering as af, ReviewActivationOptions as ag, ReviewChangesAttribution as ah, ReviewCommentPlacement as ai, ReviewCustomPlacement as aj, ReviewItemHit as ak, ReviewItemPlacement as al, ReviewItemPlacementBase as am, ReviewItemQuery as an, ReviewItemRevealEvent as ao, ReviewItemRevealSource as ap, ReviewRevisionPlacement as aq, ReviewSkippedDiagnostic as ar, ScrollPlacement as as, ScrollToAnchorOptions as at, SelectedImageState as au, SessionActivity as av, SessionDiagnostic as aw, SetReviewChangesAuthorOptions as ax, TableBorderEdgeTarget as ay, TableBorderSpec 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, DocumentSaveDiagnostic as o, DocumentShape as p, DocumentSource as q, EditRejectedDiagnostic as r, EditRejectionOrigin as s, Editor as t, EditorAnchorNavigation as u, EditorCommandShape as v, EditorCommands as w, EditorError as x, EditorEvents as y };
+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 };

package/dist/{editor-scope-7o9xweiJ.d.ts → editor-scope-C7ke1KJG.d.ts}

@@ -4,13 +4,33 @@ interface HistoryGroup {
     readonly [historyGroupBrand]: true;
     /** Closed after `end()`, document replacement, detach, or destruction. */
     readonly state: 'open' | 'closed';
+    /**
+     * The outcome of the latest write that named this handle, or `null` before the first one.
+     *
+     * Every grouped write reports here. A browser runtime `run({ historyGroup }, callback)` is
+     * ONE write, whatever number of syncs it makes: it has no `ExecResult`, and it settles here
+     * once, after the callback finishes. A split anywhere in the run makes its outcome `split`. Read it
+     * after a write to learn whether the write started, extended, or split the group.
+     *
+     * @example
+     * ```ts
+     * await runtime.run({ historyGroup: decision }, async (context) => {
+     *   context.document.body.insertParagraph('Revised terms follow.', 'End');
+     *   await context.sync();
+     * });
+     * if (decision.lastOutcome?.kind === 'split') console.warn(decision.lastOutcome.reason);
+     * ```
+     */
+    readonly lastOutcome: HistoryGroupOutcome | null;
     /** End this gesture without reverting any edits. Safe to call more than once. */
     end(): void;
 }
 /** The history authority's result for this frame. @public */
 interface HistoryGroupOutcome {
     readonly kind: 'started' | 'extended' | 'split' | 'none';
-    readonly reason?: 'history-boundary' | 'undo-redo' | 'no-history' | 'package-unit' | 'composition';
+    readonly reason?: 'history-boundary' | 'undo-redo' | 'no-history'
+    /** @deprecated No longer reported: writes that span document parts now extend the group. */
+     | 'package-unit' | 'composition';
 }
 /**
  * The editor is N+1 editing views: one body plus one per header/footer relationship, plus
@@ -63,12 +83,45 @@ type EditorScope = {
 type ViewScope = Exclude<EditorScope, {
     kind: 'all';
 }>;
+/**
+ * Options for a review write that can join an explicit history group.
+ *
+ * Every write that names one open handle becomes part of one undo step, across commands,
+ * review methods, and browser automation runs. A closed handle, or a handle from another
+ * editor, refuses the write with `code: 'unsupported'` and changes nothing.
+ *
+ * @example
+ * ```ts
+ * const decision = editor.beginHistoryGroup();
+ * // Reply first: the card's key no longer exists after the change is accepted.
+ * const reply = editor.replyToReviewItem(key, 'Accepted with one change.', {
+ *   historyGroup: decision,
+ * });
+ * const accepted = editor.acceptReviewItem(key, { historyGroup: decision });
+ * decision.end();
+ * if (!reply.ok || !accepted.ok) throw new Error('the review card was refused');
+ * editor.exec({ type: 'undo' }); // reverts both writes
+ * ```
+ * @public
+ */
+interface HistoryGroupOptions {
+    /**
+     * An open handle from {@link Editor.beginHistoryGroup} on this editor.
+     *
+     * Undo, redo, and an ungrouped write close the group, so a later frame starts a new undo
+     * step. Inspect `ExecResult.history` to see whether a write started, extended, or split it.
+     */
+    readonly historyGroup?: HistoryGroup;
+}
 /** Options for a command's editing view and explicit gesture. @public */
-interface EditorExecOptions {
+interface EditorExecOptions extends HistoryGroupOptions {
     /** Omitted, the command addresses the current selection. */
     readonly scope?: EditorScope;
     /**
-     * An open handle from this editor. Supported for synchronous formatting commands.
+     * An open handle from this editor. Supported for synchronous formatting commands, tracked
+     * proposals (`proposeInsertion`, `proposeDeletion`, `proposeReplacement`),
+     * `resolveAllReviewChanges`, and `setReviewChangesAuthor`. Other commands refuse a handle
+     * with `code: 'unsupported'`.
      * Intervening writes and undo/redo can split a gesture; inspect `ExecResult.history`.
      * Read-only commands do not close a gesture. Ungrouped collaboration uses timed capture.
      * See the core history grouping guide for gesture bindings and boundary rules.
@@ -81,4 +134,4 @@ interface HistoryDiagnostic {
     readonly reason: string;
 }
 
-export type { EditorScope as E, HistoryDiagnostic as H, ViewScope as V, EditorExecOptions as a, HistoryGroup as b, HistoryGroupOutcome as c };
+export type { EditorScope as E, HistoryDiagnostic as H, ViewScope as V, EditorExecOptions as a, HistoryGroup as b, HistoryGroupOptions as c, HistoryGroupOutcome as d };