@docx-editor.dev/core 2.31.0 → 2.33.0

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

@@ -1,139 +1,14 @@
-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 { d as ResolvedRevisionMarkup, a as ReviewDisplayMode } from './revision-projection-OVusTS77.js';
+import { ResolvedReviewPane } from './contracts/types.js';
+import { V as ViewScope, b as HistoryDiagnostic, c as HistoryGroup, a as EditorExecOptions, E as EditorScope, d as HistoryGroupOptions } from './editor-scope-CA6egMaK.js';
+import { E as EditorFontErrorCode, a as FontFaceRequest } from './editor-fonts-D_-vjuJi.js';
+import { T as RevisionBatchSkipDetail, t as DocAnchor, g as ReviewRevisionKind, c as ReviewCommentItem, b as ReviewRevisionItem, d as ReviewCustomItem, aT as SourceCrop, a8 as DrawingKind, ag as ImageWrapTarget, aa as DrawingPositionInput, a9 as DrawingLocks, af as ImageResourceState, r as ColorValue, x as ExecErrorCode, ah as ParagraphFormatCommand, an as SupportedImageMime, ar as Watermark, E as ExecResult, at as WatermarkState, n as ContentControlFilter, o as DocRange, k as RunFormatting, p as Revision, ak as Rect, am as SelectionPin, ao as Unsubscribe } from './tree-op-types-Df4oY2u4.js';
+import { C as CollaborationDiagnosticCode, b as CustomNodeDiagnosticCode, c as DiagnosticErrorName, F as FailureStage, B as ByteSizeBucket, a as CountBucket, e as DocumentOpenDiagnosticCode, f as DocumentPartKind, g as DocumentSaveDiagnosticCode, E as EditDiagnosticCode, R as ReviewDiagnosticCode, k as ReviewOperation, j as ReviewChangeKind, i as FormattingChangeKind, h as FontDiagnosticCode, H as HistoryDiagnosticCode, P as PerformanceDiagnosticCode } from './diagnostic-hints-BtCaCqQC.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-dApRIYpt.js';
-import { a as DocumentProtectionState } from './document-protection-C8x3P2J6.js';
-import { C as CollaborationStatus } from './failure-NS2lsya4.js';
-
-/**
- * When the review pane opens by itself.
- *
- * - `'auto'`: the pane opens when a document with review items loads, and when a tracked
- *   change is made while it is closed, in both cases when the pane has items to list. With
- *   `revisionsIn: 'balloons'` the pane lists no tracked change and no reply to one, so
- *   tracked changes and their replies alone do not open it.
- * - `'manual'`: the pane stays closed until the host or the user opens it. Use it when the
- *   host shows review items its own way, such as in balloons or margin markers.
- *
- * @public
- */
-type ReviewPaneOpening = 'auto' | 'manual';
-/**
- * What the open review pane does when its full card column does not fit beside the page at
- * the page's zoom.
- *
- * - `'float'`: the pane shrinks to a strip of markers, and the open card floats over the
- *   page.
- * - `'shrinkPage'`: under a fit zoom mode, the page may shrink down to the mode's
- *   `minZoom` (or 10%) so that the full column fits. The pane changes to the marker strip
- *   only when the column does not fit at that floor either. A fixed zoom behaves as
- *   `'float'`.
- * - `'scroll'`: the page keeps the size it has beside the closed pane's marker strip, and
- *   the full column stands beside it. The document and the column scroll together: the
- *   viewport scrolls sideways to reach the cards.
- *
- * The setting applies to the review pane only. The navigation pane stays docked at its side
- * in every mode: it never scrolls with the document, and it takes its room beside the page
- * exactly as it does with no review pane.
- *
- * @public
- */
-type ReviewPaneOverflow = 'float' | 'shrinkPage' | 'scroll';
-/**
- * Where tracked changes open.
- *
- * - `'pane'`: the review pane lists tracked changes as cards beside the comments.
- * - `'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. A replacement is one balloon.
- *   In both settings, Next Change and Previous Change stop on a replacement once.
- *
- * @public
- */
-type RevisionDisplay = 'pane' | 'balloons';
-/**
- * How a collapsed comment marker looks.
- *
- * - `'initials'`: a badge with the thread author's initials in the author's color, a reply
- *   count, and a check mark when the thread is resolved.
- * - `'icon'`: the comment icon.
- *
- * @public
- */
-type CommentMarkerStyle = 'initials' | 'icon';
-/**
- * Review pane settings to change. Every field is optional, and an omitted field keeps its
- * current value.
- *
- * @public
- */
-interface ReviewPaneOptions {
-    /** Default `'auto'`. */
-    readonly opening?: ReviewPaneOpening;
-    /** Default `'float'`. */
-    readonly overflow?: ReviewPaneOverflow;
-    /** Default `'pane'`. */
-    readonly revisionsIn?: RevisionDisplay;
-    /** Default `'icon'`. */
-    readonly commentMarkers?: CommentMarkerStyle;
-}
-/**
- * The review pane settings in force, with every field resolved.
- *
- * @public
- */
-interface ResolvedReviewPane {
-    /** When the pane opens by itself. */
-    readonly opening: ReviewPaneOpening;
-    /** What the open pane does when its card column does not fit beside the page. */
-    readonly overflow: ReviewPaneOverflow;
-    /** Where tracked changes open. */
-    readonly revisionsIn: RevisionDisplay;
-    /** How a collapsed comment marker looks. */
-    readonly commentMarkers: CommentMarkerStyle;
-}
-/** The settings an editor starts with when nothing sets them. @public */
-declare const DEFAULT_REVIEW_PANE: ResolvedReviewPane;
-/**
- * Merge `options` over `base`. Throws a `TypeError` for an unknown field or value, so a
- * misspelled setting fails loudly instead of being ignored. Returns `base` itself when
- * nothing changes, so the snapshot keeps its reference.
- *
- * @public
- */
-declare function resolveReviewPane(options: ReviewPaneOptions | undefined, base?: ResolvedReviewPane): ResolvedReviewPane;
-/**
- * The fields of a review item that decide whether the review pane lists it. A
- * `ReviewItem` and a review item placement both have them.
- *
- * @public
- */
-interface ReviewPaneItemFields {
-    /** The item kind, as `ReviewItem.kind` gives it. */
-    readonly kind: 'revision' | 'comment' | 'custom';
-    /** For a comment, the tracked change it replies to. */
-    readonly parentRevisionId?: string;
-}
-/**
- * Whether the review pane lists a card for `item` under `revisionsIn`.
- *
- * With `'balloons'`, a balloon at the text shows every tracked change and every comment
- * that replies to a tracked change, so the pane lists neither. Give the item as an
- * unfiltered `getReviewItems()` read returns it: a query that excludes revision kinds
- * removes `parentRevisionId` from replies to the changes it drops.
- *
- * The engine applies this rule to every review item when it decides whether the pane opens
- * by itself or closes after a settings change. A review pane must apply the same rule before
- * its own filters, such as a hidden kind or a host filter. Those filters can hide every card,
- * and then the pane that the engine opens is empty.
- *
- * @public
- */
-declare function reviewPaneListsItem(revisionsIn: RevisionDisplay, item: ReviewPaneItemFields): boolean;
+import { a as SemanticSelection, S as SemanticPosition } from './semantic-interaction-BbA4dgEo.js';
+import { a as DocumentProtectionState } from './document-protection-BvbpSXbQ.js';
+import { a as CollaborationStatus } from './failure-6KGFrDO9.js';
 
 /**
  * What a fit mode fits the page to.
@@ -167,6 +42,52 @@ type ZoomMode = {
     readonly maxZoom?: number;
 };
 
+/**
+ * One occurrence of a search query in the document.
+ *
+ * Carries TWO addresses on purpose. `blockId` + `start` is the engine's own: stable
+ * across edits and independent of ordering. `paragraphIndex` + `runIndex` + `runOffset`
+ * is the positional one a find/replace UI needs to show and navigate results, and it is
+ * derived from the same walk rather than left to the caller to reconstruct — a caller
+ * guessing at run boundaries would send the selection to the wrong place.
+ *
+ * A match can span runs when formatting changes mid-word; the run address is where it
+ * STARTS. `scope` identifies a non-body story so navigation opens the correct surface.
+ * A frame scope selects its anchoring drawing and never places a caret inside its story.
+ * A match inside a field result reports the field atom's model range. Its `length` is one,
+ * while `text` carries the visible match and can be longer. Select with `start` and `length`.
+ * Never derive the selected length from `text.length`.
+ */
+interface TextMatch {
+    readonly blockId: string;
+    /** Character offset within the paragraph's concatenated run text. */
+    readonly start: number;
+    readonly length: number;
+    /**
+     * Paragraph ordinal within this match's story. Table and nested-table paragraphs count.
+     * Non-paragraph blocks add no ordinal.
+     */
+    readonly paragraphIndex: number;
+    /** Index of the run the match starts in, and the offset within that run. */
+    readonly runIndex: number;
+    readonly runOffset: number;
+    /** Story containing the match. Absence means the body. */
+    readonly scope?: ViewScope;
+    /** The matched text as it appears in the document. */
+    readonly text: string;
+    /**
+     * Paragraph text immediately before and after the match, bounded at the derivation
+     * boundary. A results list shows the match in its sentence — "…as described in this
+     * **Exhi**bit A" — and nothing else in the contract can reach paragraph text, so a
+     * caller would otherwise have to re-read the document to render one row.
+     *
+     * Optional and additive: an implementation that has not derived them omits them, and a
+     * consumer treats absent as empty.
+     */
+    readonly contextBefore?: string;
+    readonly contextAfter?: string;
+}
+
 /**
  * Anonymous diagnostics: why something failed, as stable codes and bucketed numbers.
  *
@@ -352,8 +273,11 @@ interface ReviewSkippedDiagnostic extends DiagnosticBase {
     /** The role of the part the changes are in, such as `'footnotes'`. Never its name. */
     readonly part?: DocumentPartKind;
     /**
-     * For `review.revision-unsupported`, the engine condition that refused the change, such as
-     * `unaddressed` (no `w:id` or author) or `unrecorded-properties`. See `diagnosticCauses()`.
+     * The structure behind the skip. For `review.revision-unsupported`, the engine condition that
+     * refused the change, such as `unaddressed` (no `w:id` or author). For
+     * `review.incomplete-group`, the change the decision would also decide, such as
+     * `paired-change` (the other half of a move or merge) or `removed-content`. For
+     * `review.retained-structure`, `nested-table`. See `diagnosticCauses()`.
      */
     readonly cause?: string;
 }
@@ -490,8 +414,8 @@ interface EditorEvents {
     change: (change: DocumentChange) => void;
     /**
      * 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.
+     * formatting, the armed typing format, the open header or footer, the collaboration
+     * session's status, or the page count when pages finish laying out in the background.
      */
     selectionChange: (snapshot: EditorSnapshot) => void;
     error: (error: EditorError) => void;
@@ -531,6 +455,20 @@ interface EditorEvents {
      * ```
      */
     reviewItemReveal: (event: ReviewItemRevealEvent) => void;
+    /**
+     * An accept-all or reject-all decision committed: from the toolbar, the menu, or
+     * `exec({ type: 'resolveAllReviewChanges' })`. `skipped` names the changes it left pending,
+     * so a host can say why they stay. A remote decision in a collaboration session never fires
+     * it: it is a local event.
+     *
+     * @example
+     * ```ts
+     * editor.on('reviewChangesResolved', ({ skipped }) => {
+     *   if (skipped.length) showNotice(`${skipped.length} changes stay pending`);
+     * });
+     * ```
+     */
+    reviewChangesResolved: (event: ReviewChangesResolvedEvent) => 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
@@ -595,6 +533,33 @@ interface ReviewItemRevealEvent {
      */
     readonly source: ReviewItemRevealSource;
 }
+/**
+ * The payload of the `reviewChangesResolved` event.
+ *
+ * @public
+ */
+interface ReviewChangesResolvedEvent {
+    /** Whether the decision accepted or rejected the changes. */
+    readonly action: 'accept' | 'reject';
+    /** How many listed changes it resolved. The `exec` result lists them in `revisions.resolved`. */
+    readonly resolvedCount: number;
+    /**
+     * The listed changes it left pending, with why: `'retained-structure'` for a row that stays
+     * to keep a nested table, `'incomplete-group'` for a change that would also resolve one the
+     * selection leaves out, `'unsupported-revision'` for a structure the engine cannot resolve,
+     * and `'unknown-revision'` for a key that no longer names a change. `reviewCodeOfSkip(skip)`
+     * gives each entry's review code, with its `detail`.
+     */
+    readonly skipped: readonly {
+        /** The skipped change's key, as `getReviewItems({ pairReplacements: false })` lists it. */
+        readonly key: string;
+        /** The key of the replacement it is one half of, as the default `getReviewItems()` lists it. */
+        readonly pairKey?: string;
+        readonly reason: 'unsupported-revision' | 'incomplete-group' | 'retained-structure' | 'unknown-revision';
+        /** Which condition kept it, such as `'locked-content'` (a content lock) or `'bound-content'` (a data binding). */
+        readonly detail?: RevisionBatchSkipDetail;
+    }[];
+}
 /** What asked to reveal a review item. See {@link ReviewItemRevealEvent.source}. @public */
 type ReviewItemRevealSource = 'navigate' | 'host';
 /**
@@ -1517,9 +1482,21 @@ interface SelectedImageState {
         readonly dpiX: number;
         readonly dpiY: number;
     }> | null;
+    /**
+     * Whether `setImageProperties` can change the size. False for a hidden drawing, a drawing
+     * whose size is locked, a rotated legacy VML text box or one sized as a percentage of a
+     * frame, and in viewing mode. An inline text box resizes.
+     */
     readonly canResize: boolean;
+    /**
+     * Whether `setImagePosition` can move the drawing. False for an inline drawing, which flows
+     * with its line, for a locked or hidden drawing, a rotated legacy VML text box, and in
+     * viewing mode.
+     */
     readonly canMove: boolean;
+    /** Whether `setImageWrapType` applies: pictures only, never text boxes. */
     readonly canChangeWrap: boolean;
+    /** Whether `setImageProperties` can crop: pictures only, never text boxes. */
     readonly canCrop: boolean;
 }
 /**
@@ -1736,57 +1713,6 @@ interface DocumentHandle {
  * where a new array per render rebuilds the editor per render.
  */
 type DocumentSource = ArrayBuffer | Uint8Array | DocumentHandle | 'blank';
-/** A concrete font face requested by authored document content. */
-interface FontFaceRequest {
-    readonly family: string;
-    readonly weight: number;
-    readonly style: 'normal' | 'italic';
-}
-/** Immutable, byte-backed font face supplied to layout and browser paint. */
-interface FontSource {
-    readonly request: FontFaceRequest;
-    readonly id: string;
-    readonly bytes: Uint8Array;
-    readonly hash: string;
-    readonly faceIndex: number;
-    readonly availability?: 'available' | 'forbidden';
-}
-/** An explicit authored-font substitution. No implicit platform fallback is performed. */
-interface FontSourceSubstitution {
-    readonly from: FontFaceRequest;
-    readonly to: FontFaceRequest;
-    /** Word line-box metrics for the requested face, expressed as em ratios. */
-    readonly lineMetrics?: {
-        readonly heightEm: number;
-        readonly baselineEm: number;
-    };
-}
-/**
- * Public font source configuration sampled when an adapter mounts. It must be immutable for that
- * editor lifetime; remount the adapter to replace bytes or substitutions atomically.
- */
-interface FontConfiguration {
-    /** Selectable provider families, independent of loaded bytes. Listing them performs no fetch. */
-    readonly supportedFamilies?: readonly string[];
-    readonly epoch: number;
-    readonly maxFontBytes: number;
-    readonly sources: readonly FontSource[];
-    readonly substitutions?: readonly FontSourceSubstitution[];
-    readonly defaultFont: {
-        readonly family: string;
-        readonly sizeHalfPoints: number;
-    };
-    readonly language?: string;
-}
-/**
- * Why a font was not admitted.
- *
- * Distinguished rather than collapsed because the responses differ: `overLimit` and `malformed`
- * are the caller's own bytes, while `forbidden` and `hashMismatch` mean the source was not what
- * it claimed and the load should not be retried. `wasmUnavailable` alone is a HOST fault — the
- * shaper's WASM never loaded, `diagnostic` carries the remedy — surface it as a setup error.
- */
-type EditorFontErrorCode = 'initializationFailed' | 'wasmUnavailable' | 'missing' | 'forbidden' | 'overLimit' | 'malformed' | 'hashMismatch' | 'metadataMismatch' | 'fontFaceLoadFailed' | 'unsupportedFaceIndex' | 'missingFont' | 'hashInvalid' | 'fontMismatch' | 'unsupportedFace' | 'loadFailed';
 /** Typed adapter error reported both through `onFontError` and accessible alert UI. */
 declare class EditorFontError extends Error {
     readonly name: string;
@@ -1980,6 +1906,13 @@ interface Editor extends EditorAnchorNavigation, EditorHighlights, EditorReviewH
      * The search narrows to the body and its selectable text boxes when other stories cannot open.
      * This includes viewing mode and surfaces without header, footer, or note entry methods.
      * Text boxes in footnotes and endnotes remain excluded until their drawings are selectable.
+     *
+     * Pass a match to `exec({ type: 'replaceMatch', match, text })` to replace it, which records a
+     * tracked replacement in suggesting mode, or to {@link selectMatch} and then
+     * {@link addComment} to comment on it. For headless or server use, see `body.search` in
+     * `@docx-editor.dev/editor-api`.
+     *
+     * @see {@link https://www.docx-editor.dev/docs/2.x/recipes/tracked-replacement | Replace as a tracked change}
      */
     findMatches(query: string, options?: {
         readonly matchCase?: boolean;
@@ -2138,6 +2071,13 @@ interface Editor extends EditorAnchorNavigation, EditorHighlights, EditorReviewH
      * editor.addComment('Counter-proposal: 45 days.', { historyGroup: decision });
      * editor.addComment('Approved.', 'Legal team', { historyGroup: decision });
      * ```
+     *
+     * To comment on found text, select it first with {@link findMatches} and
+     * {@link selectMatch}. In a React or Vue host with the review module, `useReview().comment`
+     * calls this. For headless or server use, see `Range.insertComment` in
+     * `@docx-editor.dev/editor-api`.
+     *
+     * @see {@link https://www.docx-editor.dev/docs/2.x/recipes/comment-on-found-text | Comment on found text}
      */
     addComment(text: string, options?: HistoryGroupOptions): ExecResult;
     /** {@link addComment} with an author for this call, overriding the configured author. */
@@ -2165,6 +2105,11 @@ interface Editor extends EditorAnchorNavigation, EditorHighlights, EditorReviewH
      * With `options.announce: true`, a call that lands fires `reviewItemReveal` with
      * `source: 'host'`, also when the item was already active, so the packaged review UI opens
      * the item's balloon or card. By default it fires nothing. A `null` key fires nothing.
+     *
+     * Pass `{ reveal: false }` to open the item without scrolling, for a host whose own list
+     * drives the scroll. `useReview().setActive` calls this.
+     *
+     * @see {@link https://www.docx-editor.dev/docs/2.x/recipes/accept-reject-without-scrolling | Accept or reject without scrolling}
      */
     setActiveReviewItem(key: string | null, options?: ReviewActivationOptions): ExecResult;
     /**
@@ -2212,7 +2157,19 @@ 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.
+     * Other refusals name their cause, as {@link addComment} describes. A change that resolves
+     * only together with another change refuses with a reason led by `incomplete-group:`, and a
+     * row that stays to keep a nested table with one led by `retained-structure:`. A change a
+     * content control lock keeps refuses with `code: 'locked'` and a reason led by
+     * `locked-content:`; one in a data-bound control with `code: 'bound'` and `bound-content:`.
+     * `reviewCodeOfRefusal(result.reason)` names the review code of each. In a React or
+     * Vue host, `useReviewRefusalMessage()` turns `useReview().lastRefusal` into a sentence.
+     *
+     * Neither call scrolls. In a React or Vue host with the review module, `useReview().accept`
+     * and `useReview().reject` call these. For headless or server use, see `Revision.accept()`
+     * and `Revision.reject()` in `@docx-editor.dev/editor-api`.
+     *
+     * @see {@link https://www.docx-editor.dev/docs/2.x/recipes/accept-reject-without-scrolling | Accept or reject without scrolling}
      */
     acceptReviewItem(key: string, options?: HistoryGroupOptions): ExecResult;
     /** The rejecting half of {@link acceptReviewItem}, with the same rules and options. */
@@ -2254,11 +2211,24 @@ interface Editor extends EditorAnchorNavigation, EditorHighlights, EditorReviewH
      * 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.
+     *
+     * In a React or Vue host with the review module, `useReview().reply` calls this. For
+     * headless or server use, see `Comment.reply` in `@docx-editor.dev/editor-api`.
      */
     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;
+    /**
+     * Move editing into `scope`: the body, a header or footer, a note, or a text box (`frame`).
+     *
+     * A frame whose `owner` is a header or footer opens that story first and edits the box
+     * inside it. The box is edited on the page of the open story when that story is already
+     * open, otherwise on the page in view, otherwise on the first page that shows it. A frame
+     * owned by a note, a box with rotated or vertical text, and a box holding a table are refused:
+     * the scope stays where it was. Read {@link getActiveScope} to confirm the entry.
+     */
     setActiveScope(scope: ViewScope): void;
+    /** The scope editing is in, as {@link setActiveScope} last set it or a press moved it. */
     getActiveScope(): ViewScope;
     query<K extends keyof EditorQueries>(query: {
         type: K;
@@ -2284,7 +2254,8 @@ interface Editor extends EditorAnchorNavigation, EditorHighlights, EditorReviewH
      */
     /**
      * Scroll a page or a block into view. Returns false when the target does not exist or
-     * the host has no scroll container — a caller can tell "not found" from "scrolled".
+     * the host has no scroll container. During a large open, a target not laid out yet answers
+     * true and scrolls once it is; input cancels that, and a page past the end never scrolls.
      */
     scrollToPage(pageNumber: number): boolean;
     /**
@@ -2622,6 +2593,17 @@ interface EditorCommands extends EditorCommandShape<DocEdits>, EditorHeaderFoote
      * 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.
+     *
+     * For headless or server use, see `range.insertText(text, 'Replace')` with
+     * `document.changeTrackingMode` set to `'TrackMineOnly'` in `@docx-editor.dev/editor-api`.
+     *
+     * @example
+     * ```ts
+     * const [match] = editor.findMatches('30 days', { matchCase: true });
+     * if (match) editor.exec({ type: 'replaceMatch', match, text: '45 days' });
+     * ```
+     *
+     * @see {@link https://www.docx-editor.dev/docs/2.x/recipes/tracked-replacement | Replace as a tracked change}
      */
     replaceMatch: {
         match: TextMatch;
@@ -2872,51 +2854,6 @@ interface EditorQueryResults extends DocQueryResults {
     trackedChanges: readonly Revision[];
     bookmarks: readonly BookmarkSummary[];
 }
-/**
- * One occurrence of a search query in the document.
- *
- * Carries TWO addresses on purpose. `blockId` + `start` is the engine's own: stable
- * across edits and independent of ordering. `paragraphIndex` + `runIndex` + `runOffset`
- * is the positional one a find/replace UI needs to show and navigate results, and it is
- * derived from the same walk rather than left to the caller to reconstruct — a caller
- * guessing at run boundaries would send the selection to the wrong place.
- *
- * A match can span runs when formatting changes mid-word; the run address is where it
- * STARTS. `scope` identifies a non-body story so navigation opens the correct surface.
- * A frame scope selects its anchoring drawing and never places a caret inside its story.
- * A match inside a field result reports the field atom's model range. Its `length` is one,
- * while `text` carries the visible match and can be longer. Select with `start` and `length`.
- * Never derive the selected length from `text.length`.
- */
-interface TextMatch {
-    readonly blockId: string;
-    /** Character offset within the paragraph's concatenated run text. */
-    readonly start: number;
-    readonly length: number;
-    /**
-     * Paragraph ordinal within this match's story. Table and nested-table paragraphs count.
-     * Non-paragraph blocks add no ordinal.
-     */
-    readonly paragraphIndex: number;
-    /** Index of the run the match starts in, and the offset within that run. */
-    readonly runIndex: number;
-    readonly runOffset: number;
-    /** Story containing the match. Absence means the body. */
-    readonly scope?: ViewScope;
-    /** The matched text as it appears in the document. */
-    readonly text: string;
-    /**
-     * Paragraph text immediately before and after the match, bounded at the derivation
-     * boundary. A results list shows the match in its sentence — "…as described in this
-     * **Exhi**bit A" — and nothing else in the contract can reach paragraph text, so a
-     * caller would otherwise have to re-read the document to render one row.
-     *
-     * Optional and additive: an implementation that has not derived them omits them, and a
-     * consumer treats absent as empty.
-     */
-    readonly contextBefore?: string;
-    readonly contextAfter?: string;
-}
 /**
  * The hyperlink under a position: where it points, how far it reaches, and what Word shows on
  * hover.
@@ -2965,12 +2902,12 @@ interface EditorSnapshot {
      *  point on — it never depends on one existing. */
     readonly isLoading: boolean;
     /**
-     * Whether a supplied document is still on its way to painted pages. Opening a large
-     * document mounts behind one painted frame so a loading screen can show instead of a
-     * frozen page; this is true for exactly that window, and across it the previous
-     * document (if any) stays on screen. Show a loading overlay while it holds — but gate
-     * only chrome on it, never the mount point, which must stay mounted for the open to
-     * complete ({@link EditorSnapshot.isLoading} is the gate-safe flag). Optional and
+     * Whether a supplied document is still on its way to painted pages. A large document
+     * mounts behind one painted frame so a loading screen can show instead of a frozen page,
+     * with the previous document (if any) still on screen. Show an overlay while it holds,
+     * but gate only chrome on it, never the mount point, which must stay mounted for the open
+     * to complete ({@link EditorSnapshot.isLoading} is the gate-safe flag). It turns false
+     * when the first pages paint; they take input while the rest lay out. Optional and
      * additive: absent means the implementation has not derived it, read as `false`.
      */
     readonly isOpening?: boolean;
@@ -3137,5 +3074,5 @@ interface EditorError extends Error {
     readonly code?: string;
 }
 
-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 };
+export { DIAGNOSTIC_SCHEMA_VERSION as D, EditorFontError as J, cropPercentFromCropPermille as aS, cropPercentFromPermille as aT, cropPercentFromSourceCrop as aU, cropPermilleFromCropPercent as aV, cropPermilleFromPercent as aW, sourceCropFromCropPercent as aX, validateImageCropPercent as aY };
+export type { FurnitureVariant 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, EditorFormatPainterCommands as K, EditorHeaderFooterCommands as L, EditorHighlights as M, EditorHostChange as N, EditorHostDocument as O, EditorNoteCommands as P, EditorPosition as Q, EditorQueries as R, EditorQuery as S, EditorQueryResults as T, EditorReviewHits as U, EditorSelection as V, EditorSnapshot as W, FontFailedDiagnostic as X, FormatPainterLevel as Y, FormatPainterMode as Z, FormatPainterSurfaceState as _, EditorDiagnosticKind as a, HeaderFooterSlotArgs as a0, HeaderFooterState as a1, HighlightHit as a2, HighlightOptions as a3, HighlightRange as a4, HighlightRect as a5, HighlightResult as a6, HistoryDiagnosticEvent as a7, HyperlinkInfo as a8, ImageContext as a9, SetReviewChangesAuthorOptions as aA, TableBorderEdgeTarget as aB, TableBorderSpec as aC, TableBorderStyle as aD, TableBorderTarget as aE, TableCellVerticalAlignment as aF, TableColumnDividerResizeTarget as aG, TableColumnOccurrenceTarget as aH, TableContext as aI, TableRightEdgeResizeTarget as aJ, TableRowOccurrenceTarget as aK, TextMatch as aL, TimingSummary as aM, TrackedChangeFilterMode as aN, TrackedChangePredicate as aO, ZoomFitTarget as aP, ZoomMode as aQ, ImageCropPermille as aR, ImageCropPercent as aa, NoteKind as ab, NotePropertiesSide as ac, NotePropertiesState as ad, PageSetup as ae, PerformanceDiagnostic as af, ResolveReviewChangesOptions as ag, ResolvedNoteNumbering as ah, ReviewActivationOptions as ai, ReviewChangesAttribution as aj, ReviewChangesResolvedEvent as ak, ReviewCommentPlacement as al, ReviewCustomPlacement as am, ReviewItemHit as an, ReviewItemPlacement as ao, ReviewItemPlacementBase as ap, ReviewItemQuery as aq, ReviewItemRevealEvent as ar, ReviewItemRevealSource as as, ReviewRevisionPlacement as at, ReviewSkippedDiagnostic as au, ScrollPlacement as av, ScrollToAnchorOptions as aw, SelectedImageState as ax, SessionActivity as ay, SessionDiagnostic as az, EditorCommand as b, 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-fonts-D_-vjuJi.d.ts

@@ -0,0 +1,53 @@
+/** A concrete font face requested by authored document content. */
+interface FontFaceRequest {
+    readonly family: string;
+    readonly weight: number;
+    readonly style: 'normal' | 'italic';
+}
+/** Immutable, byte-backed font face supplied to layout and browser paint. */
+interface FontSource {
+    readonly request: FontFaceRequest;
+    readonly id: string;
+    readonly bytes: Uint8Array;
+    readonly hash: string;
+    readonly faceIndex: number;
+    readonly availability?: 'available' | 'forbidden';
+}
+/** An explicit authored-font substitution. No implicit platform fallback is performed. */
+interface FontSourceSubstitution {
+    readonly from: FontFaceRequest;
+    readonly to: FontFaceRequest;
+    /** Word line-box metrics for the requested face, expressed as em ratios. */
+    readonly lineMetrics?: {
+        readonly heightEm: number;
+        readonly baselineEm: number;
+    };
+}
+/**
+ * Public font source configuration sampled when an adapter mounts. It must be immutable for that
+ * editor lifetime; remount the adapter to replace bytes or substitutions atomically.
+ */
+interface FontConfiguration {
+    /** Selectable provider families, independent of loaded bytes. Listing them performs no fetch. */
+    readonly supportedFamilies?: readonly string[];
+    readonly epoch: number;
+    readonly maxFontBytes: number;
+    readonly sources: readonly FontSource[];
+    readonly substitutions?: readonly FontSourceSubstitution[];
+    readonly defaultFont: {
+        readonly family: string;
+        readonly sizeHalfPoints: number;
+    };
+    readonly language?: string;
+}
+/**
+ * Why a font was not admitted.
+ *
+ * Distinguished rather than collapsed because the responses differ: `overLimit` and `malformed`
+ * are the caller's own bytes, while `forbidden` and `hashMismatch` mean the source was not what
+ * it claimed and the load should not be retried. `wasmUnavailable` alone is a HOST fault — the
+ * shaper's WASM never loaded, `diagnostic` carries the remedy — surface it as a setup error.
+ */
+type EditorFontErrorCode = 'initializationFailed' | 'wasmUnavailable' | 'missing' | 'forbidden' | 'overLimit' | 'malformed' | 'hashMismatch' | 'metadataMismatch' | 'fontFaceLoadFailed' | 'unsupportedFaceIndex' | 'missingFont' | 'hashInvalid' | 'fontMismatch' | 'unsupportedFace' | 'loadFailed';
+
+export type { EditorFontErrorCode as E, FontConfiguration as F, FontFaceRequest as a, FontSource as b, FontSourceSubstitution as c };

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

@@ -66,7 +66,11 @@ type EditorScope = {
     drawingNodeId: string;
     /** The paragraph that anchors that drawing. */
     hostParagraphId: string;
-    /** Furniture or note story that owns this frame. Absence means the body story. */
+    /**
+     * Furniture or note story that owns this frame. Absence means the body story. Entering a
+     * frame owned by a header or footer opens that story around it; a note-owned frame cannot
+     * be entered.
+     */
     owner?: {
         kind: 'headerFooter';
         rId: string;
@@ -134,4 +138,4 @@ interface HistoryDiagnostic {
     readonly reason: string;
 }
 
-export type { EditorScope as E, HistoryDiagnostic as H, ViewScope as V, EditorExecOptions as a, HistoryGroup as b, HistoryGroupOptions as c, HistoryGroupOutcome as d };
+export type { EditorScope as E, HistoryGroupOutcome as H, ViewScope as V, EditorExecOptions as a, HistoryDiagnostic as b, HistoryGroup as c, HistoryGroupOptions as d };