@docx-editor.dev/core 2.26.0 → 2.28.0

package/dist/{editor-DYUlyKmb.d.ts → editor-Ci7IZGmG.d.ts}

@@ -1,12 +1,13 @@
-import { t as DocAnchor, a8 as SourceCrop, a9 as DrawingKind, aa as ImageWrapTarget, ab as DrawingPositionInput, ac as DrawingLocks, r as ColorValue, x as ExecErrorCode, ad as ParagraphFormatCommand, ae as Watermark, E as ExecResult, g as ReviewRevisionKind, c as ReviewCommentItem, b as ReviewRevisionItem, d as ReviewCustomItem, n as ContentControlFilter, o as DocRange, k as RunFormatting, p as Revision, af as Rect, ag as SelectionPin, ah as Unsubscribe } from './types-barrel-BO73JqHG.js';
+import { d as ResolvedRevisionMarkup, a as ReviewDisplayMode } from './revision-projection-DZ4kKVev.js';
+import { a as ResolvedReviewPane } from './review-pane-D9jm8DcY.js';
+import { t as DocAnchor, g as ReviewRevisionKind, c as ReviewCommentItem, b as ReviewRevisionItem, d as ReviewCustomItem, al as SourceCrop, am as DrawingKind, an as ImageWrapTarget, ao as DrawingPositionInput, ap as DrawingLocks, r as ColorValue, x as ExecErrorCode, aq as ParagraphFormatCommand, ar as Watermark, E as ExecResult, n as ContentControlFilter, o as DocRange, k as RunFormatting, p as Revision, as as Rect, at as SelectionPin, au as Unsubscribe } from './types-barrel-D3xCgQX6.js';
 import { H as HistoryDiagnostic, V as ViewScope, a as HistoryGroup, b as EditorExecOptions, E as EditorScope } from './editor-scope-OHPwVQ5l.js';
-import { R as ReviewDisplayMode } from './revision-projection-DfWxdBqA.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-CvFAj0GR.js';
-import { b as ImageResourceState, S as SupportedImageMime } from './image-resources-DfagDguq.js';
-import { D as DocumentProtectionState } from './document-protection-Bp19Ad4I.js';
-import { C as CollaborationStatus } from './failure-BIPVQbRm.js';
+import { a as SemanticSelection, S as SemanticPosition } from './semantic-interaction-CIC-PooQ.js';
+import { b as ImageResourceState, S as SupportedImageMime } from './image-resources-BN-hUgCn.js';
+import { D as DocumentProtectionState } from './document-protection-BAGVGqaP.js';
+import { C as CollaborationStatus } from './failure-NS2lsya4.js';
 
 /**
  * What a fit mode fits the page to.
@@ -48,13 +49,63 @@ type ZoomMode = {
  * against these rather than against the snapshot.
  */
 interface EditorEvents {
+    /** Local viewer preferences changed through the API or review dialog. */
+    revisionMarkupChange: (settings: ResolvedRevisionMarkup) => void;
     /** A document mutation committed, with the ids it touched. */
     change: (change: DocumentChange) => void;
     /** The selection or its derived formatting moved. */
     selectionChange: (snapshot: EditorSnapshot) => void;
     error: (error: EditorError) => void;
     historyDiagnostic: (diagnostic: HistoryDiagnostic) => void;
+    /**
+     * An explicit request landed on a review item, and its card or balloon should open.
+     *
+     * Fires each time Next Change or Previous Change lands (`source: 'navigate'`), and each time
+     * `setActiveReviewItem(key, { announce: true })` succeeds (`source: 'host'`). It fires again
+     * when the item was already active, so a card the reader closed can open again.
+     *
+     * It does not fire for a caret move, a click in the page, a dismissal (`key` of `null`), a
+     * refused activation, or `setActiveReviewItem(key)` without `announce: true`. A remote edit in a
+     * collaboration session never fires it: it is a local view event.
+     *
+     * @example
+     * ```ts
+     * editor.on('reviewItemReveal', ({ key, source }) => {
+     *   openMyBalloon(key); // `source` is 'navigate' or 'host'
+     * });
+     * ```
+     */
+    reviewItemReveal: (event: ReviewItemRevealEvent) => void;
 }
+/**
+ * The payload of the `reviewItemReveal` event.
+ *
+ * @public
+ */
+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`
+     * 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`.
+     */
+    readonly pairKey?: string;
+    /**
+     * What asked for the item. `'navigate'` is Next Change or Previous Change, from the menu,
+     * the toolbar, a shortcut, or `exec({ type: 'navigateReviewChange' })`. `'host'` is a call
+     * to `setActiveReviewItem` (and so `useReview().setActive`) with `announce: true`.
+     */
+    readonly source: ReviewItemRevealSource;
+}
+/** What asked to reveal a review item. See {@link ReviewItemRevealEvent.source}. @public */
+type ReviewItemRevealSource = 'navigate' | 'host';
 /**
  * The payload of the `change` event / `onChange`. It carries revision + identity
  * deltas, NOT serialized bytes: serializing a whole DOCX on every keystroke would
@@ -71,13 +122,30 @@ interface DocumentChange {
     readonly dirty?: readonly string[];
 }
 
+/**
+ * Where a scroll places its target in the viewport.
+ *
+ * - `'start'`: near the top, like a jump to a heading.
+ * - `'center'`: centred.
+ * - `'centerIfNeeded'`: still while the target is on screen, centred when it has to move.
+ * - `'nearest'`: the minimum scroll, which leaves the target at the edge it came in from.
+ *
+ * Each method that takes a placement states its own default.
+ *
+ * @public
+ */
+type ScrollPlacement = 'start' | 'center' | 'centerIfNeeded' | 'nearest';
 /**
  * Scroll settings for {@link EditorAnchorNavigation.scrollToAnchor}. Every field is optional.
  * The fields match document refresh `NavigateToChangeOptions`. @public
  */
 interface ScrollToAnchorOptions {
-    /** Target alignment. Default: centerIfNeeded, which keeps the viewport still for a visible target. */
-    readonly block?: 'start' | 'center' | 'centerIfNeeded' | 'nearest';
+    /**
+     * Target placement. The default depends on the method: `scrollToAnchor` uses
+     * `'centerIfNeeded'`, which keeps the viewport still for a visible target, and
+     * `scrollToBlock` uses `'start'`.
+     */
+    readonly block?: ScrollPlacement;
     /** Default: instant. Reduced motion uses instant even when smooth is requested. */
     readonly behavior?: 'instant' | 'smooth';
     /** Edge padding for start/nearest placement, in CSS pixels. Default: 24. Finite and nonnegative. */
@@ -308,6 +376,243 @@ interface EditorHighlights {
     getHighlightsAt<R extends HighlightRange = HighlightRange>(clientX: number, clientY: number): readonly HighlightHit<R>[];
 }
 
+/** One review item under a client point. @public */
+interface ReviewItemHit {
+    /** The item, as `getReviewItems()` with the same query returns it. */
+    readonly placement: ReviewItemPlacement;
+    /**
+     * The item's painted band on the line under the point, in client coordinates. It covers the
+     * part of the item's range on that line, not the whole range. Anchor popovers to it.
+     */
+    readonly rect: HighlightRect;
+}
+/** Hit testing for hosts that draw their own review chrome. @public */
+interface EditorReviewHits {
+    /**
+     * The review items whose text is under a client point, innermost first.
+     *
+     * An item hits when the CHARACTER under the point is inside one of its ranges, so the
+     * right half of a range's last character still hits, and the left half of the next
+     * character does not. Ranges that cover no characters, such as a tracked paragraph mark or
+     * a comment on an empty range, never hit. Items without a range never hit.
+     *
+     * The test covers every story the review queue lists and the pages paint: the body,
+     * tables, headers, footers, footnotes, and endnotes. Only painted pages are tested, so a
+     * point over a page that is not built returns no items.
+     *
+     * The result reports every item whose range covers the character, including replies,
+     * which share their thread's range, and resolved comments. Filter on
+     * `placement.parentId`, `placement.parentRevisionId`, or `placement.resolved` to find the
+     * card that owns the hit. Order follows the review queue's own rule for the caret: the
+     * narrowest range first, then comments before custom nodes before revisions, then the
+     * most deeply nested revision.
+     *
+     * A point hits the glyph band of a line, the same band a text highlight marks. A point in
+     * the spacing between lines hits nothing. `query` filters the items the same way it
+     * filters `getReviewItems()`. Coordinates that are not finite numbers return an empty
+     * array. Each call reads the whole review queue, so call it from a click, not on every
+     * pointer move.
+     *
+     * @example
+     * ```ts
+     * pages.addEventListener('click', (event) => {
+     *   const [hit] = editor.getReviewItemsAt(event.clientX, event.clientY);
+     *   if (hit) showBalloon(hit.placement.key, hit.rect);
+     * });
+     * ```
+     * @public
+     */
+    getReviewItemsAt(clientX: number, clientY: number, query?: ReviewItemQuery): readonly ReviewItemHit[];
+    /**
+     * The bands one review item paints, one per line part, in client coordinates.
+     *
+     * `key` is a `ReviewItemPlacement.key`. Bands follow page order, and within a page the
+     * body comes before headers, footers, and notes. Only painted pages contribute. An unknown
+     * key, an item without a range, or an item with no text on a painted page returns an
+     * empty array. Anchor a balloon to the first band, or join the bands for an outline.
+     *
+     * @example
+     * ```ts
+     * const [first] = editor.getReviewItemRects(placement.key);
+     * if (first) positionBalloon(first);
+     * ```
+     * @public
+     */
+    getReviewItemRects(key: string): readonly HighlightRect[];
+}
+
+/**
+ * Narrows what `getReviewItems` returns.
+ *
+ * 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.
+ */
+interface ReviewItemQuery {
+    /**
+     * Revision kinds to leave out of the returned items, for example structural kinds that the
+     * host has no card for. Default: none. Comments and custom items are never removed. This
+     * filters only the returned data; to stop the caret from activating the same kinds, call
+     * `setReviewActivationExclusions`.
+     */
+    readonly excludeRevisionKinds?: readonly ReviewRevisionKind[];
+    /** 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.
+     *
+     * 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
+     * the deletion's last range ends at the same paragraph and offset where the insertion's
+     * first range starts. The pair's `text` is the inserted words and `replacedText` the
+     * deleted words. The two halves are not listed separately.
+     *
+     * Kinds in {@link excludeRevisionKinds} are removed before pairing, so an excluded deletion
+     * or insertion never pairs. Excluding `'replace'` removes the pairs too.
+     *
+     * The pair's `key` is stable while both halves are pending, and every key-addressed verb
+     * accepts it whatever query you read it with. Accepting or rejecting it resolves both
+     * halves in one transaction and one undo step. Activating it opens the deletion; the pair
+     * reports `isActive` while either half is active. A reply anchors over the inserted words,
+     * and replies to either half are listed under the pair.
+     */
+    readonly pairReplacements?: boolean;
+}
+
+/**
+ * How activating a review item places it in the viewport, and whether it announces the
+ * reveal.
+ *
+ * @public
+ */
+interface ReviewActivationOptions {
+    /**
+     * Where the item lands, or `false` to open it without scrolling at all.
+     *
+     * Default `'centerIfNeeded'`: silent while the item is already on screen, centred when it
+     * has to travel. `'nearest'` scrolls the minimum instead, which parks the item flush
+     * against the edge it came in from; `'start'` puts it near the top, the way a jump to a
+     * heading reads. `false` is for a host whose own list already drives the scroll and does
+     * not want the engine competing with it.
+     *
+     * It governs the reveal of the ITEM. An item in a header, a footer or a note also opens
+     * that story, and opening one always brings its band into view — a story the reader cannot
+     * see is one they cannot read the change in, which is the whole point of activating it.
+     */
+    readonly reveal?: ScrollPlacement | false;
+    /**
+     * Whether a successful activation fires the `reviewItemReveal` event. Default `false`.
+     *
+     * Pass `true` to open the item the way Next Change does: the packaged review UI opens its
+     * balloon, or opens a closed review pane at its card when the pane's `opening` setting is
+     * `'auto'`. The item becomes active either way.
+     *
+     * @example
+     * ```ts
+     * editor.setActiveReviewItem(key, { announce: true });
+     * ```
+     */
+    readonly announce?: boolean;
+}
+
+/**
+ * What every review card carries, whatever kind of decision it represents.
+ *
+ * Presentation-ready by design: author, initials, date and text are derived by the ENGINE,
+ * because deriving them means walking runs and reading `w15:commentsEx`. An adapter doing that
+ * walk would put document derivation in the host and would have to be written once per
+ * framework.
+ */
+interface ReviewItemPlacementBase {
+    /** Stable and unique per decision within this editor instance. */
+    readonly key: string;
+    /** The engine's own id for the comment, the revision, or the custom node. */
+    readonly id: string;
+    readonly author: string;
+    /** Initials for an avatar: `@w:initials` when the file carries one, else from the name. */
+    readonly initials: string;
+    /** `@w:date`, absent when the file omits it — Word does when date stamping is off. */
+    readonly date?: string;
+    /**
+     * The comment's body, the words the revision covers, or the custom card's detail.
+     *
+     * PLAIN TEXT, and it must be rendered as text: a `.docx` is a zip of XML an attacker
+     * controls end to end, so this string is untrusted and never markup.
+     */
+    readonly text: string;
+    /**
+     * Replies to this item, in document order.
+     *
+     * Comments AND revisions carry them: OOXML gives `w:ins` and `w:del` no body, so replying
+     * to a tracked change writes a comment over the change's own range, and the reply belongs
+     * inside the card for the change rather than beside it.
+     */
+    readonly replyIds: readonly string[];
+    /**
+     * True when the engine cannot resolve this kind structurally, so accept and reject must
+     * not be offered. A card offering a button the engine will refuse is worse than one that
+     * explains why it cannot.
+     */
+    readonly readOnly: boolean;
+    /**
+     * Whether {@link Editor.setActiveReviewItem} would take this key.
+     *
+     * False for an item with no resolvable range, for a custom node without `reviewCard`
+     * (`carded: false`), and for a revision kind the host's rail excluded through
+     * {@link Editor.setReviewActivationExclusions} — the queue still LISTS
+     * those, because `getReviewItems` answers "what does this document hold" rather than "what
+     * may be clicked", and a host filtering the two apart needs to be told which is which. A
+     * card drawn for an item that cannot be activated is a card that does nothing when clicked.
+     */
+    readonly activatable: boolean;
+    /** Document-space Y of the anchor, or null when the item has no resolvable range. */
+    readonly anchorY: number | null;
+    readonly pageIndex: number | null;
+    readonly isActive: boolean;
+}
+/** A comment thread's card. @public */
+interface ReviewCommentPlacement extends ReviewItemPlacementBase {
+    readonly kind: 'comment';
+    /** Whether `w15:commentsEx` marks the thread done. */
+    readonly resolved: boolean;
+    /** The comment this replies to, absent at the top of a thread. */
+    readonly parentId?: string;
+    /**
+     * The REVISION this comment answers, absent unless it does.
+     *
+     * A surface listing top-level cards must skip these as well as the ones with a
+     * {@link parentId}: the card is rendered inside the change it answers, and a rail that
+     * only checked `parentId` drew the reply twice.
+     */
+    readonly parentRevisionId?: string;
+    readonly item: ReviewCommentItem;
+}
+/** A tracked change's card. @public */
+interface ReviewRevisionPlacement extends ReviewItemPlacementBase {
+    readonly kind: 'revision';
+    /** Which decision this is. */
+    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}.
+     */
+    readonly replacedText?: string;
+    readonly item: ReviewRevisionItem;
+}
+/** A custom node's card (`defineCustomNode` with a `reviewCard` hook). @public */
+interface ReviewCustomPlacement extends ReviewItemPlacementBase {
+    readonly kind: 'custom';
+    readonly item: ReviewCustomItem;
+}
+/**
+ * A DISCRIMINATED union on {@link ReviewItemPlacementBase.kind}: narrowing the kind
+ * narrows `item` and the kind-specific fields with it, so a consumer never writes the
+ * `placement.kind === 'custom' && placement.item.kind === 'custom'` double check.
+ */
+type ReviewItemPlacement = ReviewCommentPlacement | ReviewRevisionPlacement | ReviewCustomPlacement;
+
 /** Selection and unsupported-change policy for a bulk review decision. @public */
 interface ResolveReviewChangesOptions {
     action: 'accept' | 'reject';
@@ -318,6 +623,49 @@ interface ResolveReviewChangesOptions {
     /** Defaults to skip. Strict refuses the entire selection if any target cannot resolve. */
     unsupported?: 'skip' | 'fail';
 }
+/**
+ * Who and when a change of tracked-change author records. Shared by both selections.
+ * @public
+ */
+interface ReviewChangesAttribution {
+    /**
+     * The author to record. Defaults to the editor's `author`, so a reviewer adopts changes as
+     * their own. A command with neither refuses, because `w:author` is required.
+     */
+    author?: string;
+    /** An ISO 8601 `xsd:dateTime` to record. Omit it to keep each change's own date. */
+    date?: string;
+    /** Defaults to skip. Strict refuses the entire selection if any target cannot change. */
+    unsupported?: 'skip' | 'fail';
+}
+/**
+ * Selection and attribution for a change of tracked-change author. The changes stay pending.
+ *
+ * Select exact `keys` from `getReviewItems()`, or a `scope` narrowed by `authors`. The two
+ * selections exclude each other.
+ * @public
+ */
+type SetReviewChangesAuthorOptions = ReviewChangesAttribution & ({
+    /** Exact keys from getReviewItems(). Duplicate keys change once. */
+    keys: readonly string[];
+    scope?: never;
+    authors?: never;
+} | {
+    keys?: never;
+    /** Defaults to revisions shown by author visibility and the tracked-changes filter. */
+    scope?: 'visible' | 'document';
+    /** Only the changes these authors made, within `scope`. Matches `w:author` exactly. */
+    authors?: readonly string[];
+});
+
+/**
+ * How a keystroke reaches the document.
+ *
+ * `'suggesting'` changes what an edit MEANS rather than whether it is allowed: typing writes
+ * `w:ins` and deleting writes `w:del` over the words it would have removed, so every change
+ * arrives as a proposal somebody else accepts or rejects.
+ */
+type DocumentEditingMode = 'editing' | 'suggesting' | 'viewing';
 
 /**
  * Header/footer and footnote/endnote public contract types for the Editor facade.
@@ -721,16 +1069,6 @@ interface TableColumnOccurrenceTarget {
     readonly isHeaderRepeat: boolean;
 }
 
-/**
- * `@docx-editor.dev/core/contracts/editor` — the `Editor` contract adapters are written against.
- *
- * Commands go through `can` before `exec`; queries answer against the live, laid-out document.
- * Type-only declarations let adapters name the surface without importing the engine.
- *
- * @packageDocumentation
- * @public
- */
-
 /**
  * An opaque handle to a loaded document — its stable identity and current
  * revision. The canonical authored state is the engine's `PackageModel`, NOT a
@@ -879,7 +1217,7 @@ type CanResult = {
  * const bytesOut = await editor.save();
  * ```
  */
-interface Editor extends EditorAnchorNavigation, EditorHighlights {
+interface Editor extends EditorAnchorNavigation, EditorHighlights, EditorReviewHits {
     /**
      * Load a new document (DOCX bytes, `'blank'`, or a handle), replacing the current one.
      *
@@ -1161,11 +1499,40 @@ interface Editor extends EditorAnchorNavigation, EditorHighlights {
      *
      * REPORTS, like {@link acceptReviewItem} and for the same reason. Activation is refused for
      * an item with no resolvable range, for a kind the host's rail excluded (see
-     * {@link setReviewActivationExclusions}), and when the story it lives in will not open —
-     * and a host walking a queue with next/previous controls has no other way to learn that a
-     * step did nothing. Consult {@link ReviewItemPlacement.activatable} to avoid asking.
+     * {@link setReviewActivationExclusions}), for a custom node without `reviewCard`, and when
+     * the story it lives in will not open — and a host walking a queue with next/previous
+     * controls has no other way to learn that a step did nothing. Consult {@link ReviewItemPlacement.activatable} to avoid asking.
+     *
+     * 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.
      */
     setActiveReviewItem(key: string | null, options?: ReviewActivationOptions): ExecResult;
+    /**
+     * The key of the ACTIVATED review item: the one {@link setActiveReviewItem}, Next Change, or
+     * Previous Change made active, while the caret stays in it.
+     *
+     * Two ideas of "active" exist. The caret-active item is the one the caret is in, however it
+     * got there: `isActive` on the placements {@link getReviewItems} returns, and `activeKey` in
+     * `useReview()`. The activated item is narrower: only an explicit activation sets it, so a
+     * 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`.
+     *
+     * @example
+     * ```ts
+     * const query = { pairReplacements: true };
+     * editor.on('selectionChange', () => {
+     *   const activated = editor.getActivatedReviewItemKey(query);
+     *   if (activated !== null) showMyCard(activated);
+     * });
+     * ```
+     */
+    getActivatedReviewItemKey(query?: ReviewItemQuery): string | null;
     /**
      * Revision kinds the caret must never activate, or null for none.
      *
@@ -1255,7 +1622,12 @@ interface Editor extends EditorAnchorNavigation, EditorHighlights {
      * the host has no scroll container — a caller can tell "not found" from "scrolled".
      */
     scrollToPage(pageNumber: number): boolean;
-    scrollToBlock(blockId: string): boolean;
+    /**
+     * `options` takes the {@link ScrollToAnchorOptions} fields. `block` defaults to `'start'`
+     * here (`scrollToAnchor` defaults to `'centerIfNeeded'`), `behavior` to `'instant'`, and
+     * `offsetPx` to 24. An invalid option also returns false, and nothing scrolls.
+     */
+    scrollToBlock(blockId: string, options?: ScrollToAnchorOptions): boolean;
     getZoom(): number;
     /**
      * Set the display scale. Values outside a sane range are rejected rather than
@@ -1336,144 +1708,6 @@ type EditorCommandShape<T> = {
 type TrackedChangePredicate = (revision: ReviewRevisionItem) => boolean;
 /** How revisions excluded by a tracked-changes predicate project into the view. */
 type TrackedChangeFilterMode = 'accept' | 'reject';
-/**
- * Narrows what `getReviewItems` returns.
- *
- * Both fields exist to keep the review rail cheap: filtering revision kinds is how a host hides
- * structural cards it has no UI for, and `placement: false` skips the layout pass entirely when
- * only metadata is wanted.
- */
-interface ReviewItemQuery {
-    readonly excludeRevisionKinds?: readonly ReviewRevisionKind[];
-    /** When false, skip layout geometry; metadata is unchanged and anchors are null. Default true. */
-    readonly placement?: boolean;
-}
-/**
- * What every review card carries, whatever kind of decision it represents.
- *
- * Presentation-ready by design: author, initials, date and text are derived by the ENGINE,
- * because deriving them means walking runs and reading `w15:commentsEx`. An adapter doing that
- * walk would put document derivation in the host and would have to be written once per
- * framework.
- */
-interface ReviewItemPlacementBase {
-    /** Stable and unique per DECISION — a revision with three ranges is one entry. */
-    readonly key: string;
-    /** The engine's own id for the comment, the revision, or the custom node. */
-    readonly id: string;
-    readonly author: string;
-    /** Initials for an avatar: `@w:initials` when the file carries one, else from the name. */
-    readonly initials: string;
-    /** `@w:date`, absent when the file omits it — Word does when date stamping is off. */
-    readonly date?: string;
-    /**
-     * The comment's body, the words the revision covers, or the custom card's detail.
-     *
-     * PLAIN TEXT, and it must be rendered as text: a `.docx` is a zip of XML an attacker
-     * controls end to end, so this string is untrusted and never markup.
-     */
-    readonly text: string;
-    /**
-     * Replies to this item, in document order.
-     *
-     * Comments AND revisions carry them: OOXML gives `w:ins` and `w:del` no body, so replying
-     * to a tracked change writes a comment over the change's own range, and the reply belongs
-     * inside the card for the change rather than beside it.
-     */
-    readonly replyIds: readonly string[];
-    /**
-     * True when the engine cannot resolve this kind structurally, so accept and reject must
-     * not be offered. A card offering a button the engine will refuse is worse than one that
-     * explains why it cannot.
-     */
-    readonly readOnly: boolean;
-    /**
-     * Whether {@link Editor.setActiveReviewItem} would take this key.
-     *
-     * False for an item with no resolvable range, and for a revision kind the host's rail
-     * excluded through {@link Editor.setReviewActivationExclusions} — the queue still LISTS
-     * those, because `getReviewItems` answers "what does this document hold" rather than "what
-     * may be clicked", and a host filtering the two apart needs to be told which is which. A
-     * card drawn for an item that cannot be activated is a card that does nothing when clicked.
-     */
-    readonly activatable: boolean;
-    /** Document-space Y of the anchor, or null when the item has no resolvable range. */
-    readonly anchorY: number | null;
-    readonly pageIndex: number | null;
-    readonly isActive: boolean;
-}
-/**
- * How activating a review item places it in the viewport.
- *
- * @public
- */
-interface ReviewActivationOptions {
-    /**
-     * Where the item lands, or `false` to open it without scrolling at all.
-     *
-     * Default `'centerIfNeeded'`: silent while the item is already on screen, centred when it
-     * has to travel. `'nearest'` scrolls the minimum instead, which parks the item flush
-     * against the edge it came in from; `'start'` puts it near the top, the way a jump to a
-     * heading reads. `false` is for a host whose own list already drives the scroll and does
-     * not want the engine competing with it.
-     *
-     * It governs the reveal of the ITEM. An item in a header, a footer or a note also opens
-     * that story, and opening one always brings its band into view — a story the reader cannot
-     * see is one they cannot read the change in, which is the whole point of activating it.
-     */
-    readonly reveal?: 'start' | 'center' | 'centerIfNeeded' | 'nearest' | false;
-}
-/** A comment thread's card. @public */
-interface ReviewCommentPlacement extends ReviewItemPlacementBase {
-    readonly kind: 'comment';
-    /** Whether `w15:commentsEx` marks the thread done. */
-    readonly resolved: boolean;
-    /** The comment this replies to, absent at the top of a thread. */
-    readonly parentId?: string;
-    /**
-     * The REVISION this comment answers, absent unless it does.
-     *
-     * A surface listing top-level cards must skip these as well as the ones with a
-     * {@link parentId}: the card is rendered inside the change it answers, and a rail that
-     * only checked `parentId` drew the reply twice.
-     */
-    readonly parentRevisionId?: string;
-    readonly item: ReviewCommentItem;
-}
-/** A tracked change's card. @public */
-interface ReviewRevisionPlacement extends ReviewItemPlacementBase {
-    readonly kind: 'revision';
-    /** Which decision this is. */
-    readonly revisionKind: ReviewRevisionKind;
-    /**
-     * The words a REPLACEMENT removes, when {@link revisionKind} is `'replace'`.
-     *
-     * Paired with {@link ReviewItemPlacementBase.text}, which holds the words it puts in
-     * their place, so a card can say `Replaced "x" with "y"` — one decision, the way Word
-     * presents it.
-     */
-    readonly replacedText?: string;
-    readonly item: ReviewRevisionItem;
-}
-/** A custom node's card (`defineCustomNode` with a `reviewCard` hook). @public */
-interface ReviewCustomPlacement extends ReviewItemPlacementBase {
-    readonly kind: 'custom';
-    readonly item: ReviewCustomItem;
-}
-/**
- * A DISCRIMINATED union on {@link ReviewItemPlacementBase.kind}: narrowing the kind
- * narrows `item` and the kind-specific fields with it, so a consumer never writes the
- * `placement.kind === 'custom' && placement.item.kind === 'custom'` double check.
- */
-type ReviewItemPlacement = ReviewCommentPlacement | ReviewRevisionPlacement | ReviewCustomPlacement;
-/**
- * How a keystroke reaches the document.
- *
- * `'suggesting'` changes what an edit MEANS rather than whether it is allowed: typing writes
- * `w:ins` and deleting writes `w:del` over the words it would have removed, so every change
- * arrives as a proposal somebody else accepts or rejects.
- */
-type DocumentEditingMode = 'editing' | 'suggesting' | 'viewing';
 
 /**
  * Every command the editor accepts, keyed by name with its payload as the value.
@@ -1495,6 +1729,8 @@ interface EditorCommands extends EditorCommandShape<DocEdits>, EditorHeaderFoote
      * adapters and any host chrome read one answer.
      */
     toggleReviewPane: Record<never, never>;
+    /** Open the local review settings dialog supplied by the review module. */
+    openRevisionMarkupDialog: Record<never, never>;
     /** Word's Show/Hide paragraph marks; presentation only. */
     toggleParagraphMarks: Record<never, never>;
     /** Word's Protect Document: enforce filling-in-forms protection, or lift the enforced one. */
@@ -1505,6 +1741,8 @@ interface EditorCommands extends EditorCommandShape<DocEdits>, EditorHeaderFoote
     };
     /** Resolve eligible changes shown by the active filters, or an explicit scope, in one undo step. */
     resolveAllReviewChanges: ResolveReviewChangesOptions;
+    /** Attribute eligible changes to another author, keeping them pending, in one undo step. */
+    setReviewChangesAuthor: SetReviewChangesAuthorOptions;
     /** Change the review projection without accepting or rejecting document revisions. */
     setReviewDisplayMode: {
         mode: ReviewDisplayMode;
@@ -2121,12 +2359,21 @@ interface EditorSnapshot {
      * value-equal snapshot correctly refuses to re-render.
      */
     readonly reviewPaneOpen?: boolean;
+    /**
+     * The review pane settings in force: every field of `ReviewPaneOptions`, such as when the
+     * pane opens by itself and what it does when its card column does not fit. Change them with
+     * `setReviewPaneOptions`. Never saved. Always
+     * set: an editor without a review module reports `DEFAULT_REVIEW_PANE`.
+     */
+    readonly reviewPane: ResolvedReviewPane;
     /** Whether Show/Hide paragraph marks is enabled. */
     readonly showParagraphMarks?: 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. */
     readonly reviewDisplayMode?: ReviewDisplayMode;
+    /** Resolved local viewer preferences. Never saved into the document. */
+    readonly revisionMarkup: ResolvedRevisionMarkup;
     /**
      * Whether the document carries review content — tracked changes or comment
      * anchors — independent of any registered review module.
@@ -2197,5 +2444,5 @@ interface EditorError extends Error {
     readonly code?: string;
 }
 
-export { EditorFontError as E, cropPercentFromCropPermille as r, cropPercentFromPermille as s, cropPercentFromSourceCrop as t, cropPermilleFromCropPercent as u, cropPermilleFromPercent as v, sourceCropFromCropPercent as w, validateImageCropPercent as x };
-export type { EditorPosition as $, AnchorHighlightOptions as A, TableBorderSpec as B, CanResult as C, DocumentSource as D, FontFaceRequest as F, TableBorderStyle as G, HighlightRange as H, ImageContext as I, TableContext as J, AuthoredNoteNumbering as K, DocumentChange as L, DocumentEditingMode as M, DocumentHandle as N, EditorAnchorNavigation as O, EditorCommandShape as P, EditorCommands as Q, EditorError as R, ScrollToAnchorOptions as S, TextMatch as T, EditorEvents as U, EditorFontErrorCode as V, EditorFormatPainterCommands as W, EditorHeaderFooterCommands as X, EditorHighlights as Y, ZoomMode as Z, EditorNoteCommands as _, FontConfiguration as a, EditorQueries as a0, EditorQuery as a1, EditorQueryResults as a2, EditorSelection as a3, FormatPainterLevel as a4, FormatPainterMode as a5, FurnitureVariant as a6, HeaderFooterSlotArgs as a7, HeaderFooterState as a8, HyperlinkInfo as a9, NoteKind as aa, NotePropertiesSide as ab, NotePropertiesState as ac, PageSetup as ad, ResolveReviewChangesOptions as ae, ResolvedNoteNumbering as af, ReviewActivationOptions as ag, ReviewCommentPlacement as ah, ReviewCustomPlacement as ai, ReviewItemPlacement as aj, ReviewItemPlacementBase as ak, ReviewItemQuery as al, ReviewRevisionPlacement as am, TableBorderTarget as an, TableCellVerticalAlignment as ao, TableColumnDividerResizeTarget as ap, TableColumnOccurrenceTarget as aq, TableRightEdgeResizeTarget as ar, TableRowOccurrenceTarget as as, ZoomFitTarget as at, FontSource as b, FontSourceSubstitution as c, EditorSnapshot as d, EditorCommand as e, ClearAnchorHighlightOptions as f, AnchorHighlightAnimation as g, Editor as h, HighlightResult as i, HighlightOptions as j, HighlightHit as k, HighlightRect as l, ImageCropPercent as m, ImageCropPermille as n, SelectedImageState as o, TrackedChangeFilterMode as p, TrackedChangePredicate as q, FormatPainterSurfaceState as y, TableBorderEdgeTarget as z };
+export { EditorFontError as E, cropPercentFromCropPermille as s, cropPercentFromPermille as t, cropPercentFromSourceCrop as u, cropPermilleFromCropPercent as v, cropPermilleFromPercent as w, sourceCropFromCropPercent as x, validateImageCropPercent as y };
+export type { EditorHighlights as $, AnchorHighlightOptions as A, TableBorderEdgeTarget as B, CanResult as C, DocumentSource as D, FontFaceRequest as F, TableBorderSpec as G, HighlightRange as H, ImageContext as I, TableBorderStyle as J, TableContext as K, AuthoredNoteNumbering as L, DocumentChange as M, DocumentEditingMode as N, DocumentHandle as O, EditorAnchorNavigation as P, EditorCommandShape as Q, ReviewItemHit as R, ScrollToAnchorOptions as S, TextMatch as T, EditorCommands as U, EditorError as V, EditorEvents as W, EditorFontErrorCode as X, EditorFormatPainterCommands as Y, ZoomMode as Z, EditorHeaderFooterCommands as _, FontConfiguration as a, EditorNoteCommands as a0, EditorPosition as a1, EditorQueries as a2, EditorQuery as a3, EditorQueryResults as a4, EditorReviewHits as a5, EditorSelection as a6, FormatPainterLevel as a7, FormatPainterMode as a8, FurnitureVariant as a9, ZoomFitTarget as aA, HeaderFooterSlotArgs as aa, HeaderFooterState as ab, HyperlinkInfo as ac, NoteKind as ad, NotePropertiesSide as ae, NotePropertiesState as af, PageSetup as ag, ResolveReviewChangesOptions as ah, ResolvedNoteNumbering as ai, ReviewActivationOptions as aj, ReviewChangesAttribution as ak, ReviewCommentPlacement as al, ReviewCustomPlacement as am, ReviewItemPlacement as an, ReviewItemPlacementBase as ao, ReviewItemQuery as ap, ReviewItemRevealEvent as aq, ReviewItemRevealSource as ar, ReviewRevisionPlacement as as, SetReviewChangesAuthorOptions as at, TableBorderTarget as au, TableCellVerticalAlignment as av, TableColumnDividerResizeTarget as aw, TableColumnOccurrenceTarget as ax, TableRightEdgeResizeTarget as ay, TableRowOccurrenceTarget as az, FontSource as b, FontSourceSubstitution as c, EditorSnapshot as d, EditorCommand as e, ClearAnchorHighlightOptions as f, ScrollPlacement as g, AnchorHighlightAnimation as h, Editor as i, HighlightResult as j, HighlightOptions as k, HighlightHit as l, HighlightRect as m, ImageCropPercent as n, ImageCropPermille as o, SelectedImageState as p, TrackedChangeFilterMode as q, TrackedChangePredicate as r, FormatPainterSurfaceState as z };