@arbidocs/blocks 0.4.101 → 0.4.102

package/node_modules/@docx-editor.dev/core/dist/editor-Ci7IZGmG.d.ts

@@ -0,0 +1,2448 @@
+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 { DocEdits, DocQueries, DocQueryResults, ContentControlSummary } from './contracts/document.js';
+import { InteractionOutcome } from './contracts/interaction.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.
+ *
+ * One member today. It is a union rather than a boolean because Word's other two — the whole
+ * sheet including its height, and the text column inside the margins — are the same
+ * computation with a different numerator, and a later change adds one without breaking the
+ * shape a host already stores.
+ */
+type ZoomFitTarget = 'pageWidth';
+/**
+ * Where the display scale comes from.
+ *
+ * `fixed` is a number the engine holds until someone changes it. `fit` is a number the engine
+ * recomputes whenever the room beside the page changes — a resized window, an opened comments
+ * rail, a docked navigation pane — bounded by `minZoom`/`maxZoom`.
+ *
+ * The bounds are what make one mode serve both cases. The default, `'auto'`, is this fit
+ * bounded at both ends: it leaves a page that fits at 100%, shrinks one that does not, and
+ * stops at 50% — past which it would be trading a scrollbar nobody minds for a page nobody
+ * can read.
+ */
+type ZoomMode = {
+    readonly type: 'fixed';
+} | {
+    readonly type: 'fit';
+    readonly fit: ZoomFitTarget;
+    /** Never shrink past this. Defaults to the contract floor, 0.1. */
+    readonly minZoom?: number;
+    /** Never grow past this. `1` is the "shrink only" rule. Defaults to the ceiling, 5. */
+    readonly maxZoom?: number;
+};
+
+/**
+ * What `editor.on(...)` can be subscribed to, and what each handler receives.
+ *
+ * These are PUSH notifications and are not interchangeable with reading `snapshot()`: a snapshot
+ * read cannot observe an event that was never emitted, which is why adapter behaviour is asserted
+ * 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
+ * be prohibitive for large documents. Call `save()` to get bytes on demand.
+ */
+interface DocumentChange {
+    /** Replacement events must not start another external processing request. Absent for edits. */
+    readonly source?: 'load' | 'refresh' | 'recovery';
+    /** Package revision after this change — `getDocumentHandle()`'s number, monotonic. */
+    readonly revision: number;
+    /** Block ids created/deleted/edited by this change, when the engine reports them. */
+    readonly created?: readonly string[];
+    readonly deleted?: readonly string[];
+    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 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. */
+    readonly offsetPx?: number;
+}
+/** Opacity fade settings. Reduced motion limits fades to 125 milliseconds. @public */
+interface AnchorHighlightAnimation {
+    /** Fade duration in milliseconds. Default: 180. Must be finite and between 0 and 10000. */
+    readonly durationMs?: number;
+    /** Automatic and explicit exit fade duration. Defaults to durationMs. Range: 0 through 10000. */
+    readonly exitDurationMs?: number;
+    /** CSS timing function for both fades. Defaults to --doc-motion-ease-out. This option does not accept CSS variables. */
+    readonly easing?: string;
+}
+/**
+ * Presentation for temporary paragraph highlights. Each call starts from these defaults.
+ * Document refresh `RefreshHighlightOptions` extends this type, so one style object serves both. @public
+ */
+interface AnchorHighlightOptions {
+    /**
+     * CSS color, including var(). Default: a light blue theme token,
+     * var(--doc-anchor-highlight-color) for anchors and var(--doc-refresh-highlight-color) for refresh.
+     */
+    readonly color?: string;
+    /** Fill opacity, from 0 to 1. Default: 0.14. Does not change document text opacity. */
+    readonly opacity?: number;
+    /** Extra space on each edge, in CSS pixels at 100% zoom. Default: 4. Must be finite and nonnegative. */
+    readonly padding?: number;
+    /** Corner radius in CSS pixels at 100% zoom. Default: 6. Must be finite and nonnegative. */
+    readonly borderRadius?: number;
+    /** Border width in CSS pixels at 100% zoom. Default: 0. Finite and nonnegative. */
+    readonly borderWidth?: number;
+    /** CSS border color. Defaults to color. Use an alpha color for a translucent border; opacity controls only the fill. */
+    readonly borderColor?: string;
+    /** Border pattern. Default: solid. */
+    readonly borderStyle?: 'solid' | 'dashed' | 'dotted';
+    /** Optional CSS classes for shadows or patterns. The editor controls highlight placement and size. */
+    readonly className?: string;
+    /** Milliseconds before dismissal starts. Default: 3000. Set `null` to keep highlights until you dismiss them. Maximum: 2147483647. */
+    readonly timeoutMs?: number | null;
+    /** Default: true, a 180-millisecond fade. False disables motion. Repeated calls for the same paragraph do not restart the fade. */
+    readonly animation?: boolean | AnchorHighlightAnimation;
+}
+/** Explicit highlight dismissal. @public */
+interface ClearAnchorHighlightOptions {
+    /** Defaults to the last highlight call's exit animation. False removes highlights immediately. */
+    readonly animation?: boolean | AnchorHighlightAnimation;
+}
+/** Navigation and temporary highlights for external paragraph references. @public */
+interface EditorAnchorNavigation {
+    /**
+     * Reveal a paragraph by its `w14:paraId` without changing selection, focus, or editing scope.
+     * With `search`, reveal the start of the matched text. Matching follows {@link DocAnchor}.
+     * By default, an offscreen target is centered and an already visible target does not move the viewport.
+     *
+     * Supports laid-out body, table, header, footer, footnote, and endnote paragraphs.
+     * Repeated headers and footers use their first laid-out occurrence. Text boxes are unsupported.
+     * Returns true when the target is visible or scrolling succeeds. Returns false for invalid,
+     * missing, or ambiguous targets, or targets without layout positions.
+     * Also returns false without a mounted, measurable scroll container.
+     * Invalid options throw `TypeError` or `RangeError`. Works in viewing mode.
+     * Does not change document content or undo history.
+     *
+     * @example
+     * ```ts
+     * const revealed = editor.scrollToAnchor({ paraId: '1B4C77A2' });
+     * ```
+     * @public
+     */
+    scrollToAnchor(anchor: DocAnchor, options?: ScrollToAnchorOptions): boolean;
+    /**
+     * Highlight the paragraph that a {@link DocAnchor} resolves to, without scrolling.
+     * Matching follows `scrollToAnchor`; `search` must resolve, and the whole paragraph is marked.
+     * A new call replaces the previous anchor highlight. Repeating a call resets its timeout.
+     *
+     * Supports body, table, and block content control paragraphs with layout positions.
+     * Returns false for invalid, missing, or ambiguous targets, or targets without layout positions.
+     * Also returns false for headers, footers, notes, and text boxes, or without a mounted document.
+     * A false result leaves the current highlight unchanged.
+     * The method validates options first. Invalid numbers throw `RangeError`.
+     * Invalid colors, border styles, or animation settings throw `TypeError`.
+     *
+     * The highlight never changes selection, focus, document content, or undo history. Loading or
+     * replacing the document removes it.
+     *
+     * @example
+     * ```ts
+     * if (editor.scrollToAnchor(anchor)) editor.highlightAnchor(anchor, { timeoutMs: 1500 });
+     * ```
+     * @public
+     */
+    highlightAnchor(anchor: DocAnchor, options?: AnchorHighlightOptions): boolean;
+    /**
+     * Dismiss the anchor highlight with a fade, or immediately with `animation: false`.
+     * Validates options even when nothing is highlighted. @public
+     */
+    clearAnchorHighlight(options?: ClearAnchorHighlightOptions): void;
+}
+
+/**
+ * One text range to mark. A `TextMatch` from `findMatches()` is a valid range, so search
+ * results pass straight through. @public
+ */
+interface HighlightRange {
+    /** Paragraph that holds the range: `TextMatch.blockId`. IDs belong to the open document. */
+    readonly blockId: string;
+    /** UTF-16 offset in the paragraph's model text, as `TextMatch.start` counts it. */
+    readonly start: number;
+    /** Range length in the same units. A zero length marks nothing. */
+    readonly length: number;
+    /** Story that holds the paragraph. Informational; `blockId` already names the paragraph. */
+    readonly scope?: ViewScope;
+    /**
+     * Model text the range must cover to paint. Set it for ranges computed outside the editor,
+     * such as on a server, so a range that no longer matches the document never paints. When it
+     * is omitted, a range must keep covering the text it covered when it was first set.
+     */
+    readonly expectedText?: string;
+}
+/** Presentation for one named highlight set. Every field is optional. @public */
+interface HighlightOptions {
+    /**
+     * Fill for every range: a CSS color or `var()` expression.
+     * Default: `var(--doc-text-highlight-color)`, a translucent yellow.
+     */
+    readonly color?: string;
+    /**
+     * Index of the active range, or `-1` for none. An index past the last range also means
+     * none. The active range takes `activeColor` and the `docx-text-highlight--active` class.
+     * Default: `-1`.
+     */
+    readonly activeIndex?: number;
+    /** Fill for the active range. Default: `var(--doc-text-highlight-active-color)`, orange. */
+    readonly activeColor?: string;
+    /** Space-separated CSS classes added to every mark of this set. */
+    readonly className?: string;
+    /**
+     * Stacking order between sets, as an integer from -1000 to 1000. A higher value paints
+     * on top. Sets with equal priority stack in the order they were first set. Default: `0`.
+     * The built-in Find pane uses the set name `search` with priority `10`.
+     */
+    readonly priority?: number;
+}
+/** What `setHighlights()` resolved against the open document. @public */
+interface HighlightResult {
+    /** Ranges that resolve to their text in the open document and can paint. */
+    readonly applied: number;
+    /**
+     * Ranges that do not resolve or cannot paint: an unknown paragraph, offsets past the
+     * paragraph end, a zero length, text that differs from `expectedText`, or a story without
+     * a layout position.
+     */
+    readonly unavailable: number;
+}
+/** A client-space rectangle, compatible with `DOMRect` readers such as positioning libraries. @public */
+interface HighlightRect {
+    readonly x: number;
+    readonly y: number;
+    readonly width: number;
+    readonly height: number;
+    readonly top: number;
+    readonly right: number;
+    readonly bottom: number;
+    readonly left: number;
+}
+/**
+ * One painted mark under a point. `R` is your range type: pass ranges with extra fields,
+ * such as a glossary definition, and read them back from `range`. @public
+ */
+interface HighlightHit<R extends HighlightRange = HighlightRange> {
+    /** Set name passed to `setHighlights()`. */
+    readonly name: string;
+    /** Index of the range in the array passed to `setHighlights()`. */
+    readonly index: number;
+    /**
+     * The range object exactly as it was passed, including your own fields. Its offsets are
+     * the ones you passed; `start` and `length` are where the text is now.
+     */
+    readonly range: R;
+    /** Current start of the highlighted text in its paragraph, after edits moved it. */
+    readonly start: number;
+    /** Current length of the highlighted text. */
+    readonly length: number;
+    /** Whether this range is the set's active range. */
+    readonly active: boolean;
+    /** The marked line box under the point, in client coordinates. Anchor popovers to it. */
+    readonly rect: HighlightRect;
+}
+/**
+ * Paint-only text highlights: search results, glossary terms, review findings.
+ *
+ * Highlights are view state. They never change the document, selection, focus, or undo
+ * history, they are never saved, and they are not shared with collaborators. @public
+ */
+interface EditorHighlights {
+    /**
+     * Mark text ranges as one named set, replacing the set's previous ranges and options.
+     *
+     * Names are 1 to 64 letters, digits, `-`, or `_`, and start with a letter. Each set paints
+     * in its own layer, so sets never replace each other. An empty `ranges` array clears the
+     * set. At most 32 sets exist at once. A set paints its first 10000 ranges and counts the
+     * rest as unavailable. The name `search` belongs to the shared document search.
+     *
+     * Ranges cover the body, tables, headers, footers, footnotes, endnotes, and anchored text
+     * boxes in the body. A range moves with its text when an edit before it shifts the
+     * paragraph. When an edit changes the text inside a range, the range stops painting, so a
+     * mark never covers the wrong text. Search again after edits to mark new occurrences.
+     *
+     * Loading, refreshing, or recovering the document removes every set. Invalid names,
+     * ranges, or options throw
+     * `TypeError` or `RangeError` and leave the current highlights unchanged.
+     *
+     * @example
+     * ```ts
+     * const matches = editor.findMatches('Supplier', { wholeWord: true });
+     * editor.setHighlights('search', matches, { activeIndex: 0 });
+     * ```
+     * @public
+     */
+    setHighlights(name: string, ranges: readonly HighlightRange[], options?: HighlightOptions): HighlightResult;
+    /** Remove one highlight set, or every set when `name` is omitted. @public */
+    clearHighlights(name?: string): void;
+    /**
+     * The marks under a client point, topmost first. Use it from `pointermove` or `click`
+     * handlers on the editor to show definitions or details for a marked term.
+     * Only marks on painted pages are reported. @public
+     */
+    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';
+    /** Defaults to revisions included by author visibility and the tracked-changes predicate. */
+    scope?: 'visible' | 'document';
+    /** Exact keys from getReviewItems(); overrides scope. Duplicate keys resolve once. */
+    keys?: readonly string[];
+    /** 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.
+ *
+ * Separated from `editor.ts` so the facade file stays under the max-lines gate while
+ * furniture/notes APIs remain one cohesive vocabulary. Re-exported from `editor.ts`
+ * so consumers keep importing `@docx-editor.dev/core/contracts/editor`.
+ */
+/** Furniture variant selected by section title-page / even-and-odd flags. */
+type FurnitureVariant = 'default' | 'first' | 'even';
+/** Header/footer editing state: which region is being edited, if any. */
+interface HeaderFooterState {
+    readonly editing: 'header' | 'footer' | null;
+    readonly sectionIndex: number;
+    /** Furniture variant in effect on the page used to enter the scope. */
+    readonly variant?: FurnitureVariant;
+    /** Relationship id of the open story (`EditorScope.rId`). */
+    readonly rId?: string;
+    /** Package part name of the open story. */
+    readonly partName?: string;
+    /**
+     * Whether the resolved part is inherited from a preceding section ("Same as Previous")
+     * rather than declared on this section.
+     */
+    readonly inherited?: boolean;
+    /** Section `w:titlePg` — first-page furniture is distinct when true. */
+    readonly titlePage?: boolean;
+    /** Document `w:evenAndOddHeaders` — even-page furniture is distinct when true. */
+    readonly evenAndOddHeaders?: boolean;
+    /** Section header distance from sheet edge, twips (`w:pgMar w:header`). */
+    readonly headerDistanceTwips?: number;
+    /** Section footer distance from sheet edge, twips (`w:pgMar w:footer`). */
+    readonly footerDistanceTwips?: number;
+}
+/** Footnote vs endnote — the public Editor vocabulary. */
+type NoteKind = 'footnote' | 'endnote';
+/** Authored note-numbering fields as Word's properties dialog writes them. */
+interface AuthoredNoteNumbering {
+    readonly pos?: string;
+    readonly numFmt?: string;
+    readonly numStart?: number;
+    readonly numRestart?: string;
+}
+/** Resolved note-numbering fields after document/section cascade. */
+interface ResolvedNoteNumbering {
+    readonly pos: string;
+    readonly numFmt: string;
+    readonly numStart: number;
+    readonly numRestart: string;
+}
+/** One note kind's resolved + authored properties for the caret section. */
+interface NotePropertiesSide {
+    readonly resolved: ResolvedNoteNumbering;
+    readonly documentAuthored?: AuthoredNoteNumbering;
+    readonly sectionAuthored?: AuthoredNoteNumbering;
+}
+/** Resolved and authored note properties for the caret section — properties dialog read-model. */
+interface NotePropertiesState {
+    readonly sectionIndex: number;
+    readonly footnote: NotePropertiesSide;
+    readonly endnote: NotePropertiesSide;
+}
+/** Optional slot targeting shared by remove / link / unlink furniture commands. */
+interface HeaderFooterSlotArgs {
+    position?: 'header' | 'footer';
+    /** Prefer over `firstPage` / `evenPage` when selecting a furniture variant. */
+    variant?: FurnitureVariant;
+    firstPage?: boolean;
+    evenPage?: boolean;
+    sectionIndex?: number;
+}
+/**
+ * Header/footer lifecycle and page-field commands on {@link EditorCommands}.
+ *
+ * Kept as a mixin so `editor.ts` can extend it without inlining the furniture vocabulary.
+ */
+interface EditorHeaderFooterCommands {
+    /**
+     * Open a header or footer for editing, materialising an empty one if the section has
+     * none — which is what a double-click on the header band means in Word.
+     *
+     * Prefer `variant` when selecting first/even/default furniture. `firstPage` /
+     * `evenPage` remain supported for existing callers (`firstPage: true` ≡ `variant:
+     * 'first'`; `evenPage: true` ≡ `variant: 'even'`). Creating a missing `first` part
+     * also enables section `w:titlePg` in the same undo unit; creating a missing `even`
+     * part also enables document `w:evenAndOddHeaders` in the same undo unit.
+     */
+    editHeaderFooter: {
+        position: 'header' | 'footer';
+        variant?: FurnitureVariant;
+        firstPage?: boolean;
+        evenPage?: boolean;
+        sectionIndex?: number;
+    };
+    /** Leave header/footer editing and return to the body. */
+    exitHeaderFooter: Record<never, never>;
+    /**
+     * Delete a declared header/footer reference (and GC the part when orphaned). When the
+     * editor is already in furniture scope, omitted fields default to the active story.
+     */
+    removeHeaderFooter: HeaderFooterSlotArgs;
+    /**
+     * Turn on "Same as Previous" for a section's furniture slot (drop its declared ref).
+     * Refused on the first section. Omitted fields default to the active story when scoped.
+     */
+    linkHeaderFooterToPrevious: HeaderFooterSlotArgs;
+    /**
+     * Turn off "Same as Previous": clone the inherited part into a declared reference.
+     * When the active scope was the inherited rId, the editor rebinds to the clone.
+     */
+    unlinkHeaderFooterFromPrevious: HeaderFooterSlotArgs;
+    /**
+     * Section/document furniture options: `titlePg` and header/footer distances on a
+     * section; `evenAndOddHeaders` document-wide in settings.
+     */
+    setHeaderFooterOptions: {
+        sectionIndex?: number;
+        titlePage?: boolean;
+        evenAndOddHeaders?: boolean;
+        headerDistanceTwips?: number;
+        footerDistanceTwips?: number;
+    };
+    /**
+     * Insert an allowlisted page-number field at the caret. Only valid while a header or
+     * footer scope is open. `PAGE_X_OF_Y` writes PAGE + " of " + NUMPAGES as one undo unit.
+     */
+    insertPageField: {
+        field: 'PAGE' | 'NUMPAGES' | 'SECTIONPAGES' | 'PAGE_X_OF_Y';
+    };
+}
+/**
+ * Footnote/endnote lifecycle and properties commands on {@link EditorCommands}.
+ */
+interface EditorNoteCommands {
+    /** Insert a footnote or endnote reference at the caret (body only). */
+    insertNote: {
+        noteKind: NoteKind;
+    };
+    /** Delete a note and its body reference together. */
+    deleteNote: {
+        noteKind: NoteKind;
+        noteId: number;
+    };
+    /** Convert one note to the other kind. */
+    convertNote: {
+        fromKind: NoteKind;
+        noteId: number;
+    };
+    /** Convert every note of one kind to the other in document order (one undo step). */
+    convertAllNotes: {
+        fromKind: NoteKind;
+    };
+    /**
+     * Footnote and endnote properties for the section — numbering format, restart rule
+     * and position, as Word's dialog offers them.
+     */
+    setNoteProperties: {
+        scope?: 'document' | 'section';
+        sectionIndex?: number;
+        footnote?: {
+            numFmt?: string;
+            numRestart?: string;
+            position?: string;
+            numStart?: number;
+        };
+        endnote?: {
+            numFmt?: string;
+            numRestart?: string;
+            position?: string;
+            numStart?: number;
+        };
+    };
+}
+
+/**
+ * Format painter commands for the Editor facade.
+ *
+ * Separated from `editor.ts` so the facade file stays under the max-lines gate while the
+ * painter keeps one cohesive vocabulary. Re-exported from `editor.ts`, so consumers keep
+ * importing `@docx-editor.dev/core/contracts/editor`.
+ */
+/**
+ * Word's Format Painter, as the two halves a keyboard user drives separately.
+ *
+ * The pair is deliberately NOT one command with a direction flag: `copyFormatting` reads
+ * and `pasteFormatting` writes, so they answer `can` differently — copying is allowed on a
+ * document open for viewing, and applying is not.
+ */
+interface EditorFormatPainterCommands {
+    /**
+     * Capture the formatting at the selection (Word's Ctrl+Shift+C).
+     *
+     * Reads the RESOLVED cascade rather than the direct run properties, so painting from a
+     * styled paragraph carries what the reader sees rather than the little the paragraph
+     * happens to state itself.
+     *
+     * The LEVEL follows the selection, as Word's does. A range inside one paragraph captures
+     * character formatting alone; a range that covers a paragraph mark — a whole paragraph, a
+     * multi-paragraph selection, or a collapsed caret — captures the paragraph style and its
+     * 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.
+     */
+    copyFormatting: Record<never, never>;
+    /**
+     * Apply the captured formatting to the current selection (Word's Ctrl+Shift+V).
+     *
+     * Refused with `no formatting has been copied` until `copyFormatting` has run. Paragraph
+     * formatting is applied only when the capture carries it; the text itself never moves.
+     *
+     * Three things stay on the TARGET rather than being painted over, because they are outside
+     * the property vocabulary an op may name — the same limit `clearFormatting` states:
+     * paragraph borders (`w:pBdr`), the run's character style (`w:rStyle`), and character
+     * shading (`w:rPr/w:shd`), which is resolved and painted but cannot be authored.
+     */
+    pasteFormatting: Record<never, never>;
+}
+/**
+ * How long the painter stays armed.
+ *
+ * Word's two gestures, named: a single press arms it for ONE application, a double press
+ * locks it on until the user presses `Esc`. `'off'` is the resting state.
+ */
+type FormatPainterMode = 'off' | 'once' | 'locked';
+/**
+ * What a capture carries.
+ *
+ * `'run'` is character formatting alone — the level a range INSIDE one paragraph copies.
+ * `'paragraph'` adds the paragraph style and its direct paragraph properties, which is what
+ * a selection covering a paragraph mark copies. `'none'` means nothing has been captured.
+ */
+type FormatPainterLevel = 'none' | 'run' | 'paragraph';
+/**
+ * Painter state, as the editor publishes it.
+ *
+ * Chrome state rather than document state, so it moves through the same report every other
+ * observable surface state uses — a toolbar's pressed state has one source. It lives in the
+ * CONTRACTS lane rather than beside the surface implementation because `EditorSnapshot`
+ * names it, and the contracts lane may not reach into the editor lane.
+ */
+interface FormatPainterSurfaceState {
+    readonly mode: FormatPainterMode;
+    readonly level: FormatPainterLevel;
+}
+
+/** Crop edge in UI percent (0–100). @public */
+interface ImageCropPercent {
+    readonly left: number;
+    readonly top: number;
+    readonly right: number;
+    readonly bottom: number;
+}
+/** Crop edge in OOXML permille (0–100000). */
+interface ImageCropPermille {
+    readonly left: number;
+    readonly top: number;
+    readonly right: number;
+    readonly bottom: number;
+}
+/** Projection fraction (0–1) → UI percent (0–100). */
+declare function cropPercentFromSourceCrop(crop: SourceCrop): ImageCropPercent;
+/** UI percent (0–100) → projection fraction (0–1). */
+declare function sourceCropFromCropPercent(crop: ImageCropPercent): SourceCrop;
+/** UI percent → OOXML permille. */
+declare function cropPermilleFromPercent(percent: number): number;
+/** OOXML permille → UI percent. */
+declare function cropPercentFromPermille(permille: number): number;
+/** UI percent crop → permille for tree ops / a:srcRect. */
+declare function cropPermilleFromCropPercent(crop: ImageCropPercent): ImageCropPermille;
+/** Permille crop → UI percent. */
+declare function cropPercentFromCropPermille(crop: ImageCropPermille): ImageCropPercent;
+/**
+ * Whether a crop is expressible: every edge finite and in range, and opposite edges not
+ * overlapping.
+ *
+ * Opposite edges matter — a left plus right crop summing past 100% describes a negative width,
+ * which DrawingML has no way to store.
+ */
+declare function validateImageCropPercent(crop: ImageCropPercent): boolean;
+
+/**
+ * The selected-image read model, split out of `editor.ts`.
+ *
+ * Separated so the facade file stays under the max-lines gate while the image vocabulary
+ * stays one cohesive shape. Re-exported from `editor.ts`, so consumers keep importing
+ * `@docx-editor.dev/core/contracts/editor`.
+ */
+
+/**
+ * Canonical selected-image read model shared by {@link EditorSnapshot.image} and
+ * {@link Editor.getSelectedImage}.
+ *
+ * @public
+ */
+interface SelectedImageState {
+    readonly id: string;
+    readonly kind: DrawingKind;
+    readonly widthEmu: number;
+    readonly heightEmu: number;
+    /** Crop inset per edge in UI percent (0–100); OOXML stores permille (×1000). */
+    readonly crop: ImageCropPercent;
+    readonly rotationDegrees: number;
+    readonly wrap: ImageWrapTarget;
+    readonly position: DrawingPositionInput | null;
+    readonly name: string;
+    readonly title: string;
+    readonly description: string;
+    readonly hyperlink: string | null;
+    readonly locks: DrawingLocks;
+    readonly hidden: boolean;
+    readonly resourceStatus: ImageResourceState['kind'];
+    readonly intrinsic: Readonly<{
+        readonly pixelWidth: number;
+        readonly pixelHeight: number;
+        readonly dpiX: number;
+        readonly dpiY: number;
+    }> | null;
+    readonly canResize: boolean;
+    readonly canMove: boolean;
+    readonly canChangeWrap: boolean;
+    readonly canCrop: boolean;
+}
+/**
+ * The selected image and what may be done to it — the `imageContext` query's answer.
+ *
+ * An alias of `SelectedImageState`, kept as its own name because it is the query's result type
+ * and chrome is written against it.
+ *
+ * @public
+ */
+type ImageContext = SelectedImageState;
+
+/** Where the caret sits inside a table: its shape and current cell. */
+interface TableContext {
+    readonly rows: number;
+    readonly columns: number;
+    /** Zero-based, within the table. */
+    readonly rowIndex: number;
+    /** Zero-based, within the row. */
+    readonly columnIndex: number;
+}
+/** Which cell edges a table border command targets. */
+type TableBorderTarget = 'all' | 'outside' | 'inside' | 'none' | 'top' | 'bottom' | 'left' | 'right';
+/** Concrete scopes that apply a complete border spec. */
+type TableBorderEdgeTarget = Exclude<TableBorderTarget, 'none'>;
+/**
+ * Allowlisted OOXML table border line styles.
+ *
+ * Kept identical to `store/table-border-style.ts`; `table-border-style-parity.test-d.ts`
+ * fails if the contract and store vocabularies drift.
+ */
+type TableBorderStyle = 'single' | 'dashed' | 'dotted' | 'double' | 'triple' | 'thick';
+/** Complete border spec for {@link EditorCommands.setTableBorders}. Size is in eighths of a point. */
+interface TableBorderSpec {
+    readonly style: TableBorderStyle;
+    readonly size: number;
+    readonly color: ColorValue;
+}
+/** Vertical placement of content inside selected table cells. @public */
+type TableCellVerticalAlignment = 'top' | 'center' | 'bottom';
+/**
+ * Adjacent grid columns addressed by an internal divider resize gesture.
+ *
+ * `sourceRevision` is the PACKAGE revision of the layout the target was read from — the number
+ * `getDocumentHandle()` reports, never one story's own. Commit MUST refuse when it no longer
+ * equals the current one, even if an older layout remains published for geometry.
+ */
+interface TableColumnDividerResizeTarget {
+    readonly sourceRevision: number;
+    readonly tableId: string;
+    readonly leftGridColumnId: string;
+    readonly rightGridColumnId: string;
+    readonly isHeaderRepeat: boolean;
+}
+/**
+ * Last grid column and table width addressed by an outer-right-edge resize gesture.
+ *
+ * `sourceRevision` follows the same rule as {@link TableColumnDividerResizeTarget}: the package
+ * revision of the layout the target was read from, and commit refuses once it no longer equals
+ * the current one.
+ */
+interface TableRightEdgeResizeTarget {
+    readonly sourceRevision: number;
+    readonly tableId: string;
+    readonly gridColumnId: string;
+    readonly isHeaderRepeat: boolean;
+}
+/** Explicit row occurrence. `sourceRevision` per {@link TableColumnDividerResizeTarget}. */
+interface TableRowOccurrenceTarget {
+    readonly sourceRevision: number;
+    readonly tableId: string;
+    readonly rowId: string;
+    readonly isHeaderRepeat: boolean;
+}
+/** Explicit column occurrence. `sourceRevision` per {@link TableColumnDividerResizeTarget}. */
+interface TableColumnOccurrenceTarget {
+    readonly sourceRevision: number;
+    readonly tableId: string;
+    readonly gridColumnId: string;
+    readonly isHeaderRepeat: boolean;
+}
+
+/**
+ * An opaque handle to a loaded document — its stable identity and current
+ * revision. The canonical authored state is the engine's `PackageModel`, NOT a
+ * simplified tree; advanced automation (`DocxEditor.run(handle, …)`) addresses a
+ * document through this handle rather than a serialized structure. Kept
+ * deliberately minimal and open so it can carry more identity later without a
+ * breaking change.
+ */
+interface DocumentHandle {
+    /** Package revision: rises for every edit, wherever it landed. Safe to compare. */
+    readonly revision: number;
+}
+/**
+ * What `createDocxEditor`/`load` accept as a document: raw DOCX bytes, an existing
+ * in-memory `DocumentHandle` (shared/handed off), or `'blank'`. The engine is byte-native
+ * (`PackageModel` is canonical); there is intentionally no structured-tree input,
+ * which would be lossy against the canonical package.
+ *
+ * `'blank'` is Word's blank template, the same bytes `blankDocumentBytes()` returns from
+ * `@docx-editor.dev/core/editor`. OMITTING the document is not a way to ask for an empty
+ * one: with no document there is no editing surface, so every command refuses with "no
+ * document is loaded" behind a loading screen waiting for bytes that are not coming.
+ *
+ * The two spellings serve different gestures. `'blank'` is a CONSTANT, so an adapter that
+ * remounts on document identity holds one document — right for MOUNTING.
+ * `blankDocumentBytes()` allocates, so it starts a fresh document every call — right for
+ * File › New. Call the function into `load()` or host state, never inline in a prop,
+ * 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;
+    readonly code: EditorFontErrorCode;
+    readonly request?: FontFaceRequest;
+    readonly diagnostic?: string;
+    constructor(code: EditorFontErrorCode, message: string, details?: {
+        readonly request?: FontFaceRequest;
+        readonly diagnostic?: string;
+        readonly cause?: unknown;
+    });
+}
+/**
+ * A selection endpoint, in either vocabulary the engine resolves.
+ *
+ * {@link DocAnchor} addresses a paragraph by its `w14:paraId`, which is what an LLM or an
+ * automation script can name in a payload. {@link SemanticPosition} addresses it by the
+ * paragraph id the painted surface and the ops already use, with a UTF-16 offset inside it.
+ *
+ * Neither subsumes the other. A paraId survives being written to a file and read back, so it
+ * is the one an out-of-process caller can hold; but it is OPTIONAL in the document, and
+ * `ParagraphSummary.paraId` says so — a paragraph the file gave no `w14:paraId` cannot be
+ * reached by a `DocAnchor` at all. The paragraph id reaches every paragraph.
+ */
+type EditorPosition = DocAnchor | SemanticPosition;
+/**
+ * A selection, in one endpoint vocabulary or the other.
+ *
+ * The two do NOT mix: a range is a pair of paraId anchors, or a semantic anchor/head pair,
+ * and `can()` refuses anything else with the engine's own reason. Spelled as two arms rather
+ * than `{ from: EditorPosition; to: EditorPosition }` for exactly that reason — the looser
+ * shape would type a mixed pair the engine rejects at runtime.
+ */
+type EditorSelection = SemanticSelection | {
+    from: DocAnchor;
+    to: DocAnchor;
+};
+/**
+ * Whether a command would be accepted, and why not when it would not.
+ *
+ * The `reason` is the ENGINE's own words, which is what lets disabled chrome explain itself
+ * instead of guessing — see `toolbarCommandState`.
+ */
+type CanResult = {
+    ok: true;
+} | {
+    ok: false;
+    code: ExecErrorCode;
+    reason: string;
+};
+/**
+ * The engine's whole public surface: load and save, execute and query, observe and subscribe.
+ *
+ * Commands go through `can` before `exec` — the same check chrome uses to decide whether a
+ * control is enabled, so a button and the engine never disagree about what is possible.
+ *
+ * `snapshot()` is version-cached: the same reference until state actually moves, with
+ * reference-stable sub-objects, which is what makes it safe as a `useSyncExternalStore` source.
+ *
+ * @example
+ * ```ts
+ * const editor = createDocxEditor({ container });
+ * editor.load(bytes);
+ * if (editor.can({ type: 'toggleBold' }).ok) editor.exec({ type: 'toggleBold' });
+ * const bytesOut = await editor.save();
+ * ```
+ */
+interface Editor extends EditorAnchorNavigation, EditorHighlights, EditorReviewHits {
+    /**
+     * Load a new document (DOCX bytes, `'blank'`, or a handle), replacing the current one.
+     *
+     * A large document mounts behind one painted frame, so a loading screen keyed on
+     * `snapshot().isOpening` can show instead of a frozen page; a small one mounts before
+     * this returns. Callers that need the document synchronously do not have to care:
+     * `save`, `exec` and `selectMatch` complete a scheduled open before they run.
+     */
+    load(document: DocumentSource): void;
+    /**
+     * 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.
+     */
+    save(): Promise<ArrayBuffer>;
+    getDocumentHandle(): DocumentHandle;
+    /** Create an explicit gesture handle; creates no undo entry. */
+    beginHistoryGroup(): HistoryGroup;
+    exec(command: EditorCommand, options?: EditorExecOptions): ExecResult;
+    /** Dry run: reports whether `exec` would apply. Never reports `changed`. */
+    can(command: EditorCommand, options?: EditorExecOptions): CanResult;
+    /**
+     * Dry run for byte commands that require {@link Editor.executeImageCommand}.
+     * Generic {@link Editor.can} on `insertImage` / `replaceImage` refuses with an async-path
+     * reason; this method answers whether async execution can proceed right now.
+     */
+    canExecuteImageCommand(command: Extract<EditorCommand, {
+        type: 'insertImage' | 'replaceImage';
+    }>, options?: {
+        scope?: EditorScope;
+    }): CanResult;
+    /** Insert or replace picture bytes as one package undo unit. */
+    executeImageCommand(command: Extract<EditorCommand, {
+        type: 'insertImage' | 'replaceImage';
+    }>): Promise<ExecResult>;
+    /**
+     * Whether a formatting command is currently APPLIED at the selection — distinct from
+     * `can`, which answers whether it may run.
+     *
+     * A toolbar must show that bold is on, and the repo's own guidance is that controls
+     * reflect live editor state rather than being static. `can` cannot answer this, and the
+     * legacy adapter answered it by reading a ProseMirror `EditorState` directly, which the
+     * greenfield architecture forbids in adapters.
+     *
+     * The derivation EXISTS for marks and alignment: `toggleMark` bold/italic/underline/
+     * strike answers from the snapshot's selection formatting (Word's agreement rule — true
+     * only when the WHOLE selection carries the mark), and `setAlignment` compares the
+     * command's `align` (with justify↔`both` mapped the way `exec` writes it) to the
+     * selection's paragraph alignment. Every other command still returns `false`: it must
+     * never return a value it has not actually derived from canonical state, and `false` is
+     * the honest answer while a derivation does not exist.
+     */
+    isActive(command: EditorCommand, options?: {
+        scope?: EditorScope;
+    }): boolean;
+    /** Paragraph/character styles defined by the document, for the style picker. */
+    getDocumentStyles(): readonly {
+        readonly styleId: string;
+        readonly name: string;
+        readonly type: string;
+        /**
+         * How the style looks, so a picker can show each entry in its own face rather than a
+         * list of identical rows. Presentation only, and already bounded for a CSS sink.
+         */
+        readonly preview: {
+            readonly fontFamily: string | null;
+            readonly fontSizePt: number | null;
+            readonly bold: boolean;
+            readonly italic: boolean;
+            readonly color: string | null;
+        };
+    }[];
+    /** Font families the document actually uses, for the font picker. */
+    getDocumentFonts(): readonly string[];
+    /**
+     * Selectable standard and provider-supported families plus the configured catalog (the default face,
+     * the Word-name families the substitution map stands in for, and host-registered
+     * source families) merged with {@link getDocumentFonts}. Never empty — a brand-new
+     * document offers the same standard choices. This does not report installed or loaded fonts.
+     */
+    getAvailableFonts(): readonly string[];
+    /**
+     * The document theme's ten picker colours (`a:clrScheme`) in Word's column order
+     * (Background 1, Text 1, Background 2, Text 2, Accent 1-6), each a six-digit hex
+     * without '#'. Empty when the document has no complete scheme — the picker then
+     * falls back to a default palette.
+     */
+    getDocumentThemeColors(): readonly {
+        readonly slot: string;
+        readonly hex: string;
+    }[];
+    /** Heading outline for the navigation panel, in document order. */
+    getOutline(): readonly {
+        readonly text: string;
+        readonly level: number;
+        readonly blockId: string;
+    }[];
+    /** Comment threads anchored in the document. */
+    getComments(): readonly {
+        readonly id: string;
+        readonly text: string;
+        readonly resolved: boolean;
+    }[];
+    /** Formatting at the current selection, for toolbar value display (font, size, colour,
+     *  alignment, list state). `null` when nothing is selected or nothing is derivable. */
+    getSelectionFormatting(): {
+        readonly fontFamily?: string;
+        readonly fontSizeHalfPoints?: number;
+        readonly styleId?: string;
+        readonly alignment?: string;
+        readonly bold?: boolean;
+        readonly italic?: boolean;
+        readonly underline?: boolean;
+    } | null;
+    /**
+     * Find across body, headers, footers, footnotes, endnotes, and selectable text boxes.
+     *
+     * 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.
+     */
+    findMatches(query: string, options?: {
+        readonly matchCase?: boolean;
+        readonly wholeWord?: boolean;
+    }): readonly TextMatch[];
+    /** Find many terms in one pass, such as a glossary: one result list per term, in order. */
+    findMatches(queries: readonly string[], options?: {
+        readonly matchCase?: boolean;
+        readonly wholeWord?: boolean;
+    }): readonly (readonly TextMatch[])[];
+    /**
+     * Move the selection to a found match — what a find dialog's next/previous do.
+     *
+     * Separate from `findMatches` because finding is a read and selecting is a write, and
+     * a caller may want the count without moving the caret.
+     */
+    selectMatch(match: TextMatch): ExecResult;
+    /** The image at the selection, for the image toolbar and transform controls. */
+    getSelectedImage(): SelectedImageState | null;
+    /** The table containing the selection, for the table toolbar. `null` outside a table. */
+    getSelectedTable(): {
+        readonly blockId: string;
+        readonly rowCount: number;
+        readonly columnCount: number;
+        readonly cell: {
+            readonly row: number;
+            readonly column: number;
+        } | null;
+    } | null;
+    /** Live rectangular cell selection, if any. `null` when the caret is not in a cell rectangle. */
+    getTableCellSelection(): {
+        readonly tableId: string;
+        readonly rows: {
+            readonly from: number;
+            readonly to: number;
+        };
+        readonly columns: {
+            readonly from: number;
+            readonly to: number;
+        };
+        readonly cellIds: readonly string[];
+    } | null;
+    /** Update table furniture aria labels without remounting the editor. */
+    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;
+    /** 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. */
+    getNotePropertiesState(): NotePropertiesState | null;
+    /** Plain-text note preview for hover chrome. */
+    getNotePreviewText(scopeId: string): string | null;
+    /** Tracked changes in the document — body AND header/footer stories. */
+    getTrackedChanges(): readonly {
+        readonly id: string;
+        readonly kind: string;
+        readonly author?: string;
+        /** Which story holds the change, so a consumer can group or filter by region. */
+        readonly story?: 'body' | 'header' | 'footer' | 'footnote' | 'endnote';
+    }[];
+    /**
+     * Every pending decision in the document, with where its card belongs.
+     *
+     * Derived from the document TREE, not from what is painted: a queue derived from laid-out
+     * spans empties by half the moment the reader switches to a resolved display mode, and the
+     * changes that vanished become unreachable from the surface meant to resolve them.
+     *
+     * `anchorY` comes from layout records. A surface must not measure painted DOM for it — that
+     * is a repaint behind the document and fails outright during pagination.
+     */
+    getReviewItems(query?: ReviewItemQuery): readonly ReviewItemPlacement[];
+    /**
+     * Set the view-time tracked-change filter, or clear it with `null`.
+     *
+     * The predicate receives each full revision item. A false result renders that revision as
+     * accepted by default. With `reject`, excluded content, moves, paragraph marks, and table-row
+     * insertions/deletions use their rejected projection; formatting and other property-change
+     * records keep their current values with revision markup hidden. Both modes are view-only: they
+     * change no OOXML and do not change saved bytes. Calling this method again re-evaluates every
+     * revision, even when the function reference is unchanged.
+     */
+    setTrackedChangesFilter(predicate: TrackedChangePredicate | null, mode?: TrackedChangeFilterMode): void;
+    /**
+     * Custom-node definitions registered through `createDocxEditor({ modules })`, in
+     * registration order.
+     *
+     * OPAQUE to the engine — the capability package that defined them narrows them back.
+     * Published so chrome components can default to the registered definitions instead of
+     * every surface taking the same `nodes` array and drifting.
+     */
+    getCustomNodeDefinitions(): readonly unknown[];
+    /**
+     * Report a custom-node diagnostic to the modules registered on THIS editor.
+     *
+     * The capability package raises these from its own read paths as well as from the review
+     * derivation, and both have to reach the same listeners — the ones belonging to this instance.
+     * Keeping the channel here rather than in the package is what stops two editors on one page
+     * hearing about each other's documents.
+     *
+     * Opaque, like `getCustomNodeDefinitions`: what a diagnostic means belongs to whoever raised it.
+     */
+    reportCustomNodeDiagnostic(diagnostic: unknown): void;
+    /**
+     * How edits are written: directly, as suggestions, or not at all.
+     *
+     * Runtime state, unlike the construction-time `DocxEditorConfig.mode` — a reader who switches
+     * to Viewing and back expects the same document, not a remount.
+     */
+    getEditingMode(): DocumentEditingMode;
+    setEditingMode(mode: DocumentEditingMode): ExecResult;
+    /**
+     * Whether the review pane is showing its cards.
+     *
+     * Engine-owned, like zoom: the toolbar toggles it, the rail renders from it, and the
+     * document shifts to make room for it. Three consumers, one answer.
+     */
+    isReviewPaneOpen(): boolean;
+    /**
+     * Layout points to CSS pixels, zoom included.
+     *
+     * Published because {@link ReviewItemPlacement.anchorY} is in the engine's own unit, and a
+     * host that re-derived the factor would own a second copy of the points-to-pixels rule.
+     * The first copy drifted the moment it was written: a rail that used zoom alone put every
+     * card at three quarters of its true height.
+     */
+    getRenderScale(): number;
+    /**
+     * A counter that changes exactly when {@link getReviewItems} would return something new.
+     *
+     * Lets a subscriber re-derive on a real change rather than on every event.
+     */
+    getReviewRevision(): number;
+    /**
+     * Comment on the current selection.
+     *
+     * 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.
+     */
+    addComment(text: string, author?: string): ExecResult;
+    /**
+     * Where a comment on the current selection would sit, in the same space as
+     * {@link ReviewItemPlacement.anchorY}, or null when nothing is selected.
+     *
+     * Published so a host can place an "add a comment" affordance beside the selected text
+     * without deriving document geometry, which is the one thing an adapter must not do.
+     */
+    getSelectionPlacement(): {
+        readonly anchorY: number;
+        readonly pageIndex: number;
+    } | null;
+    /**
+     * Card to document: a COLLAPSED caret at the range start, and a scroll to it. `null` clears it.
+     *
+     * 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}), 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.
+     *
+     * A host rail that hides some kinds (structural and format cards, typically) tells the
+     * engine here, so a click on tracked text cannot activate a card the rail does not
+     * render — the band would light and nothing on screen would answer it.
+     * `formattingKinds` limits a format exclusion to those OOXML property-change names,
+     * allowing other formatting decisions to retain sidebar activation.
+     */
+    setReviewActivationExclusions(kinds: readonly ReviewRevisionKind[] | null, options?: {
+        readonly formattingKinds?: readonly string[];
+    }): void;
+    /**
+     * Accept or reject the revision behind a card.
+     *
+     * Every site carrying the revision's `(id, author, date)` triple resolves in ONE transaction
+     * and one undo step: a tracked row insertion is `w:trPr/w:ins` on the row plus `w:cellIns`
+     * on each cell, and resolving them separately would leave the row half-tracked.
+     *
+     * 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.
+     */
+    acceptReviewItem(key: string): ExecResult;
+    rejectReviewItem(key: string): 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.
+     */
+    setCommentResolved(key: string, resolved: boolean): ExecResult;
+    /**
+     * Discard the item behind a card: the destructive half of the review verbs.
+     *
+     * On a COMMENT it deletes the thread — the `w:comment` body, the `w15:commentEx` record and
+     * the story's range markers, in one transaction and therefore one undo step. Word deletes a
+     * conversation rather than one remark, and a reply whose parent is gone has nothing left to
+     * answer.
+     *
+     * On a REVISION it rejects the change, which is what discarding a suggestion means: the
+     * proposal goes away and the document reads as it did before. Deliberately the same verb, so
+     * 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.
+     */
+    deleteReviewItem(key: string): ExecResult;
+    /**
+     * Reply to a review item.
+     *
+     * Against a comment this is a threaded reply. Against a REVISION it is a comment anchored
+     * over that revision's range: OOXML gives `w:ins` and `w:del` no body and no thread, so
+     * there is nowhere else for the text to live.
+     *
+     * 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.
+     */
+    replyToReviewItem(key: string, text: string, author?: string): ExecResult;
+    setActiveScope(scope: ViewScope): void;
+    getActiveScope(): ViewScope;
+    query<K extends keyof EditorQueries>(query: {
+        type: K;
+    } & EditorQueries[K], options?: {
+        scope?: EditorScope;
+    }): EditorQueryResults[K];
+    snapshot(options?: {
+        scope?: EditorScope;
+    }): EditorSnapshot;
+    getTotalPages(): number;
+    /**
+     * One-based page at the caret (default), or at the centre of the mounted scroll viewport.
+     * Viewport mode falls back to the caret when no measurable viewport is attached.
+     */
+    getCurrentPage(mode?: 'viewport' | 'caret'): number;
+    /**
+     * Display scale of the painted pages. 1 is 100%.
+     *
+     * Zoom is ENGINE-OWNED rather than a host prop, so the toolbar's zoom control, the
+     * scale a host paints at, and the factor hit testing divides by cannot disagree —
+     * a host that scaled its own transform without telling the engine would land every
+     * click at the wrong content point.
+     */
+    /**
+     * 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".
+     */
+    scrollToPage(pageNumber: number): 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
+     * clamped silently, so a caller learns its input was refused.
+     *
+     * Also LEAVES any fit mode: a reader who picks 150% has said what they want, and a
+     * viewport resize must not take it back off them. Call `setZoomMode` to go back.
+     */
+    setZoom(zoom: number): ExecResult;
+    /** Whether the scale is a number the engine holds, or one it recomputes from the viewport. */
+    getZoomMode(): ZoomMode;
+    /**
+     * Choose between holding a scale and tracking the viewport.
+     *
+     * `'auto'` is the shorthand for {@link ZoomMode}'s bounded page-width fit and the default
+     * for a new editor: a window wide enough for the sheet stays at 100%, and a narrower one
+     * shrinks rather than growing a horizontal scrollbar — down to 50%, past which the page
+     * keeps a legible size and the scrollbar is the better trade. Refused (`invalidArgs`) for a
+     * value that is not a mode, in the same spirit as `setZoom`.
+     *
+     * A fit tracks the scroller's CONTENT box, so anything that reserves width beside the page
+     * — an open comments rail, a docked navigation pane — shrinks the document by exactly what
+     * it took. Nothing else has to be told.
+     */
+    setZoomMode(mode: ZoomMode | 'auto'): ExecResult;
+    /** Page boxes in stack coordinates, each with the text area the engine laid out.
+     * `contentBox` is the page inset by the section margin. Rulers use it for margin zones.
+     * The engine's margin is uniform, so do not present this as per-side fidelity.
+     * Empty before the first layout, which is the honest answer rather than a guessed page. */
+    getPageGeometry(): readonly {
+        index: number;
+        box: Rect;
+        contentBox: Rect;
+    }[];
+    /** Replaces the module-scope cache-invalidation calls adapters make today. */
+    relayout(options?: {
+        sync?: boolean;
+    }): void;
+    focus(scope?: EditorScope): InteractionOutcome<void>;
+    /** Pin the selection while chrome has focus. Returns null while detached. */
+    retainSelection(): SelectionPin | null;
+    /** Release only the pin installed by the matching {@link retainSelection} call. */
+    releaseSelection(pin: SelectionPin): void;
+    destroy(): void;
+    on<E extends keyof EditorEvents>(event: E, handler: EditorEvents[E]): Unsubscribe;
+}
+/**
+ * Open by declaration merging: extensions contribute keys from `core/plugin`.
+ * `exec` resolves `{ type, ... }` through the extension registry, which is
+ * already the production dispatch path.
+ */
+/**
+ * In the editor a command targets the current selection unless told otherwise,
+ * and authoring is ambient — the author comes from `DocxEditorConfig`/the session,
+ * the way the Office JS API sources it from context — so the document layer's
+ * required `target` and `author` both become optional here.
+ */
+type EditorCommandShape<T> = {
+    [K in keyof T]: Omit<T[K], 'target' | 'author'> & (T[K] extends {
+        target: infer G;
+    } ? {
+        target?: G;
+    } : unknown) & (T[K] extends {
+        author: infer A;
+    } ? {
+        author?: A;
+    } : unknown);
+};
+
+/**
+ * Decides whether one tracked change renders as markup.
+ *
+ * Return `true` to keep the revision visible as tracked markup. Return `false` to render it with
+ * the selected {@link TrackedChangeFilterMode} without changing the document. The callback
+ * receives the complete revision item, including its author, date, kind, text, ranges, nesting,
+ * and resolution metadata.
+ */
+type TrackedChangePredicate = (revision: ReviewRevisionItem) => boolean;
+/** How revisions excluded by a tracked-changes predicate project into the view. */
+type TrackedChangeFilterMode = 'accept' | 'reject';
+
+/**
+ * Every command the editor accepts, keyed by name with its payload as the value.
+ *
+ * Extends the document-level {@link DocEdits} vocabulary with the things only a LIVE editor has:
+ * 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 {
+    /** Switch how edits are written. A view command: it changes no document state. */
+    setEditingMode: {
+        mode: DocumentEditingMode;
+    };
+    /**
+     * Show or hide the review pane.
+     *
+     * A view command rather than a document edit, and a COMMAND rather than a host flag so the
+     * toolbar button gets its pressed state from the same place every other button does. Both
+     * 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. */
+    toggleDocumentProtection: Record<never, never>;
+    /** Navigate tracked changes, including hidden formatting balloons, and wrap at the end. */
+    navigateReviewChange: {
+        direction: 'next' | 'previous';
+    };
+    /** 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;
+    };
+    toggleMark: {
+        mark: string;
+    };
+    setMarkAttr: {
+        mark: string;
+        attr: string;
+        value: unknown;
+    };
+    /**
+     * Word's Clear All Formatting (Home > Font > the eraser).
+     *
+     * Takes direct CHARACTER formatting off the selected text, and resets every paragraph the
+     * selection touches to the document's default paragraph style with its direct paragraph
+     * properties dropped — alignment, indents, spacing, list membership. Character formatting
+     * is a range and paragraph formatting is not, so a partial selection clears the text it
+     * covers and still resets the paragraph it sits in, which is Word's split.
+     *
+     * Formatting inherited from a style is not touched: this removes what the document states
+     * DIRECTLY, so the text falls back to what its style gives it rather than to nothing.
+     *
+     * A CHARACTER STYLE survives, and so do paragraph borders and hidden text. Those live
+     * outside the property vocabulary an edit can name — a run's `w:rStyle`, `w:vanish` and
+     * `w:bdr`, a paragraph's `w:pBdr` and `w:outlineLvl` — and are preserved rather than
+     * dropped, which is where this stops short of Word: clearing a run that carries a
+     * character style leaves that style's face on it.
+     */
+    clearFormatting: Record<never, never>;
+    /**
+     * Physical alignment on every paragraph the selection touches. A right-to-left paragraph
+     * reaches its right margin with `w:jc="left"`, so the written value follows each
+     * paragraph's direction.
+     */
+    setAlignment: {
+        align: 'left' | 'center' | 'right' | 'justify';
+    };
+    /**
+     * Word's Left-to-Right and Right-to-Left Text Direction: the base direction (`w:bidi`) of
+     * every paragraph the selection touches, table cells included. `rtl` writes `w:bidi`.
+     * `ltr` removes a direct `w:bidi`, and writes `w:bidi w:val="0"` only where a style would
+     * otherwise make the paragraph right-to-left. Run text, run direction (`w:rtl`)
+     * and `w:jc` are untouched: alignment and indents are leading and trailing sides, so a
+     * start-aligned paragraph moves to the other margin with its direction.
+     * A paragraph already in the requested direction is left as it is.
+     */
+    setParagraphDirection: {
+        direction: 'ltr' | 'rtl';
+    };
+    /**
+     * Word's Line Spacing, on every paragraph the selection touches.
+     *
+     * `value` is in the unit the RULE implies, which is the unit Word's own dialog uses:
+     * LINES for `multiple` (1, 1.15, 1.5, 2), points for `exact` and `atLeast`. The
+     * OOXML attribute is one number meaning two different quantities depending on
+     * `w:lineRule`, and a caller should not have to know which.
+     */
+    setLineSpacing: {
+        rule: 'multiple' | 'exact' | 'atLeast';
+        value: number;
+    };
+    /**
+     * Space above and below a paragraph, in points, on every paragraph the selection
+     * touches. Omitting a field leaves it as authored; `null` clears it, which is how
+     * Word's "Remove space before/after paragraph" differs from setting it to zero.
+     */
+    setParagraphSpacing: {
+        beforePt?: number | null;
+        afterPt?: number | null;
+    };
+    /**
+     * Exact paragraph indent, in twips, on every paragraph the selection touches.
+     *
+     * Omitting a field leaves it as authored; `null` clears it so the paragraph falls back to
+     * its style, the same distinction `setParagraphSpacing` draws — a zero blocks the cascade,
+     * a missing attribute does not.
+     *
+     * `firstLine` is ONE SIGNED offset from the left indent: negative IS the hanging indent.
+     * OOXML spells it as two mutually exclusive attributes (`w:firstLine`/`w:hanging`, where
+     * hanging wins per §17.3.1.12); collapsing them here means a caller cannot state a
+     * contradiction, and matches the single signed value Word's own model keeps.
+     */
+    setIndent: {
+        left?: number | null;
+        right?: number | null;
+        firstLine?: number | null;
+    };
+    /**
+     * The Paragraph dialog as one command: alignment, indents, spacing, line spacing and
+     * the five paragraph flags, applied to every paragraph the selection touches.
+     *
+     * ONE undo step, because a dialog is one gesture. The single-purpose commands beside it
+     * (`setAlignment`, `setIndent`, `setLineSpacing`, `setParagraphSpacing`) stay the right
+     * choice for a toolbar button; this is for chrome that changes several at once.
+     */
+    setParagraphFormat: ParagraphFormatCommand;
+    toggleList: {
+        kind: 'bullet' | 'ordered';
+    };
+    insertRow: {
+        where: 'above' | 'below';
+        target?: TableRowOccurrenceTarget;
+    };
+    insertColumn: {
+        where: 'left' | 'right';
+        target?: TableColumnOccurrenceTarget;
+    };
+    deleteRow: {
+        target?: TableRowOccurrenceTarget;
+    };
+    deleteColumn: {
+        target?: TableColumnOccurrenceTarget;
+    };
+    deleteTable: Record<never, never>;
+    mergeCells: Record<never, never>;
+    splitCell: {
+        rows: number;
+        cols: number;
+    };
+    /** Selected-cell fill. `null` clears direct fill so the table-style cascade applies again. */
+    setCellFill: {
+        color: ColorValue | null;
+    };
+    /** Vertically align content inside the selected table cells. */
+    setTableCellVerticalAlignment: {
+        alignment: TableCellVerticalAlignment;
+    };
+    toggleHeaderRow: Record<never, never>;
+    /**
+     * Selected-cell borders. Concrete edge scopes require a complete spec;
+     * `{ scope: 'none', target }` clears only that active edge target and MUST NOT carry `spec`.
+     */
+    setTableBorders: {
+        scope: 'none';
+        target: TableBorderEdgeTarget;
+    } | {
+        scope: TableBorderEdgeTarget;
+        spec: TableBorderSpec;
+    };
+    /**
+     * Commit an internal column-divider resize from an explicit pointer target.
+     * Widths are twips for the adjacent pair; their sum must match the pre-drag total.
+     */
+    commitTableColumnDividerResize: {
+        target: TableColumnDividerResizeTarget;
+        leftWidthTwips: number;
+        rightWidthTwips: number;
+    };
+    /**
+     * Commit an outer-right table-edge resize from an explicit pointer target.
+     * Updates the last grid column and overall table width together.
+     */
+    commitTableRightEdgeResize: {
+        target: TableRightEdgeResizeTarget;
+        columnWidthTwips: number;
+        tableWidthTwips: number;
+    };
+    /**
+     * Select a table region — the whole table, the current row, or the current column.
+     * Legacy's table toolbar offers all three.
+     */
+    selectTableRegion: {
+        region: 'table' | 'row' | 'column';
+    };
+    /**
+     * Table-level properties from the table properties dialog: preferred width and
+     * its unit (`dxa`, `pct`, `auto`), and horizontal justification. `null` clears a
+     * property; omitting it leaves the current value alone.
+     */
+    setTableProperties: {
+        width?: number | null;
+        widthType?: string | null;
+        justification?: 'left' | 'center' | 'right' | null;
+    };
+    /**
+     * Section-level page setup: the fields Word's Page Setup dialog and the rulers'
+     * margin drags change. Twips throughout, matching OOXML. Every field is optional —
+     * a margin drag sends one, the dialog sends several — and an omitted field is left
+     * as it is rather than reset. `scope` is Word's "Apply to": `'document'` (the
+     * default) writes every section; `'section'` writes only the section the selection
+     * is in. An orientation change without explicit dimensions swaps each written
+     * section's own dimensions, preserving distinct paper sizes.
+     */
+    setPageSetup: {
+        pageWidth?: number;
+        pageHeight?: number;
+        marginTop?: number;
+        marginRight?: number;
+        marginBottom?: number;
+        marginLeft?: number;
+        orientation?: 'portrait' | 'landscape';
+        scope?: 'document' | 'section';
+    };
+    /** Remove the tab stop at this position (twips) from the current paragraph. */
+    removeTabMark: {
+        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.
+     */
+    replaceMatch: {
+        match: TextMatch;
+        text: string;
+    };
+    /**
+     * Replace EVERY match of `query` in one undoable step. Separate from looping
+     * `replaceMatch` because each replacement shifts the offsets of the ones after it —
+     * legacy applied its edits back-to-front for exactly this reason, and that ordering
+     * belongs with whoever owns the offsets.
+     */
+    replaceAllMatches: {
+        query: string;
+        text: string;
+        matchCase?: boolean;
+        wholeWord?: boolean;
+    };
+    /**
+     * How the selected image sits relative to text. `inline` flows in the line; the rest
+     * are `wp:anchor` variants, with `squareLeft`/`squareRight` distinguishing which side
+     * text wraps on. Legacy's vocabulary, unchanged.
+     */
+    setImageWrapType: {
+        drawingNodeId?: string;
+        expectedPackageRevision?: number;
+        target: 'inline' | 'square' | 'squareLeft' | 'squareRight' | 'tight' | 'through' | 'topAndBottom' | 'behind' | 'inFront';
+        /** Where an inline image sat, so promoting it to an anchor keeps its place. */
+        initialPositionEmu?: {
+            horizontalEmu: number;
+            verticalEmu: number;
+        };
+    };
+    /** Rotate or flip the selected image. Legacy composed these into a CSS transform. */
+    transformImage: {
+        drawingNodeId?: string;
+        expectedPackageRevision?: number;
+        action: 'rotateCW' | 'rotateCCW' | 'flipH' | 'flipV';
+    };
+    /** Anchor position of the selected floating image, from the position dialog. */
+    setImagePosition: {
+        drawingNodeId?: string;
+        expectedPackageRevision?: number;
+        horizontalEmu?: number;
+        verticalEmu?: number;
+        relativeToH?: string;
+        relativeToV?: string;
+    };
+    /** Size, alt text, crop, position, and border of the selected image, from the properties dialog. */
+    setImageProperties: {
+        /** Expected drawing node id captured when the dialog opened. */
+        drawingNodeId?: string;
+        /** Package revision captured when the dialog opened. */
+        expectedPackageRevision?: number;
+        /** Selection anchor captured when the dialog opened. */
+        selectionParagraphId?: string;
+        /** Selection offset captured when the dialog opened. */
+        selectionOffset?: number;
+        widthEmu?: number;
+        heightEmu?: number;
+        alt?: string;
+        title?: string;
+        description?: string;
+        hyperlink?: string | null;
+        crop?: ImageCropPercent;
+        resetToNaturalSize?: boolean;
+        wrap?: ImageWrapTarget;
+        horizontalEmu?: number;
+        verticalEmu?: number;
+        relativeToH?: string;
+        relativeToV?: string;
+        borderWidthEmu?: number;
+        borderColor?: ColorValue;
+    };
+    /**
+     * Insert a raster image at the caret as one package undo unit.
+     *
+     * `widthPoints`/`heightPoints` are the extent to insert AT MOST: Word's insert rule, an
+     * extent that does not fit where the caret flows (its cell, column, or page content box)
+     * is scaled down proportionally to fit. Read the committed extent back from
+     * `snapshot().image` or `getSelectedImage()`; use `setImageProperties` to enlarge past
+     * the fit afterwards.
+     */
+    /** Insert a rectangular body textbox and enter its text. */
+    insertTextBox: Record<never, never>;
+    insertImage: {
+        data: Uint8Array;
+        mime: SupportedImageMime;
+        widthPoints: number;
+        heightPoints: number;
+        expectedPackageRevision?: number;
+        title?: string;
+        description?: string;
+        hyperlink?: string;
+    };
+    /** Replace the selected picture's bytes as one package undo unit. */
+    replaceImage: {
+        data: Uint8Array;
+        mime?: SupportedImageMime;
+        drawingNodeId?: string;
+        expectedPackageRevision?: number;
+    };
+    /** Delete the selected picture drawing as one package undo unit. */
+    deleteImage: {
+        drawingNodeId?: string;
+        expectedPackageRevision?: number;
+    };
+    setWatermark: {
+        watermark: Watermark | null;
+    };
+    /** Insert a generated, hyperlink-enabled TOC for heading levels 1–3 at the selection. */
+    insertToc: Record<never, never>;
+    /** Open options for the selected or context-clicked legacy text form. */
+    editTextFormField: Record<never, never>;
+    refreshToc: {
+        tocId?: string;
+        mode?: 'entire' | 'pageNumbers';
+    };
+    undo: Record<never, never>;
+    redo: Record<never, never>;
+    /**
+     * Move the selection. Three accepted forms, and `can()` names all three when it refuses:
+     * a collapsed paraId anchor, a range of two paraId anchors, or a semantic anchor/head pair.
+     *
+     * `{ anchor }` takes a {@link DocAnchor} rather than an {@link EditorPosition} because a
+     * collapsed SEMANTIC position is spelled as a range whose anchor and head are equal, which
+     * is what a caret already is.
+     */
+    setSelection: {
+        anchor: DocAnchor;
+    } | {
+        range: EditorSelection;
+    };
+    /** Select the whole body. Word's Ctrl+A, as a command rather than only a keystroke. */
+    selectAll: Record<never, never>;
+    /**
+     * Put the selected text on the clipboard. Reports `changed: false` — the document is
+     * untouched.
+     *
+     * Refused at a collapsed selection: there is nothing to copy, and a live Copy row over an
+     * empty selection silently no-ops.
+     */
+    copy: Record<never, never>;
+    /**
+     * Put the selected text on the clipboard and delete it. Refused at a collapsed selection,
+     * and — unlike `copy` — in a read-only document.
+     *
+     * The clipboard write is dispatched but NOT awaited, and its failure does not fail the
+     * command: the deletion has already happened by then, and reporting an edit as failed
+     * because a clipboard write lost a race would be a lie about the document.
+     */
+    cut: Record<never, never>;
+    /**
+     * Insert the clipboard payload at the selection, replacing it.
+     *
+     * PAYLOAD COMES IN. `exec` is synchronous and reading the clipboard is not — it prompts
+     * in Chrome and is refused outright by Firefox and Safari — so an engine-owned read
+     * would have to either turn every command's result into a promise or lie about this
+     * one's. The caller reads the clipboard inside the click or keystroke that asked for
+     * the paste, which is where the permission gesture belongs, and hands the engine what
+     * it read.
+     *
+     * `html`, when present, routes through the same fidelity order as the paste event:
+     * an embedded fragment first, then the bounded external-HTML projection, then `text` —
+     * degrading on any refusal. Without `html`, the plain lane inserts `text` with
+     * newlines becoming real paragraph boundaries, as this command always has.
+     */
+    paste: {
+        text: string;
+        html?: string;
+    };
+    /**
+     * Insert `text` as if typed, whatever richer flavours the clipboard held.
+     *
+     * The plain twin `paste` deliberately lacked while there was no rich lane; with one,
+     * "paste" and "paste without formatting" are two different user intentions
+     * (Cmd+V / Cmd+Shift+V) and each needs a name a menu row can call.
+     */
+    pasteWithoutFormatting: {
+        text: string;
+    };
+}
+/**
+ * One command, as a discriminated union derived from {@link EditorCommands}.
+ *
+ * This is what `can` and `exec` take. Widening `EditorCommands` widens it automatically.
+ */
+type EditorCommand = {
+    [K in keyof EditorCommands]: {
+        type: K;
+    } & EditorCommands[K];
+}[keyof EditorCommands];
+/**
+ * Every query the editor answers, keyed by name with its arguments as the value.
+ *
+ * Extends {@link DocQueries} with the reads that only mean something against a live, laid-out
+ * document: the selection, its formatting, the table or hyperlink under the caret.
+ */
+interface EditorQueries extends DocQueries {
+    selection: Record<never, never>;
+    selectionFormatting: Record<never, never>;
+    tableContext: Record<never, never>;
+    hyperlinkAt: {
+        pos?: number;
+        fallbackHref?: string;
+    };
+    selectedText: Record<never, never>;
+    watermark: Record<never, never>;
+    splitCellConfig: Record<never, never>;
+    contentControlAt: {
+        filter?: ContentControlFilter;
+    };
+    isInsideToc: {
+        pos: number;
+    };
+    trackedChanges: Record<never, never>;
+}
+/**
+ * One query, as a discriminated union derived from {@link EditorQueries}.
+ *
+ * This is what `query` takes; {@link EditorQueryResults} says what each answers.
+ */
+type EditorQuery = {
+    [K in keyof EditorQueries]: {
+        type: K;
+    } & EditorQueries[K];
+}[keyof EditorQueries];
+/** What each editor query returns. Keyed identically to `EditorQueries`. */
+interface EditorQueryResults extends DocQueryResults {
+    selection: DocRange | null;
+    selectionFormatting: RunFormatting | null;
+    tableContext: TableContext | null;
+    hyperlinkAt: HyperlinkInfo | null;
+    selectedText: string;
+    watermark: Watermark | null;
+    splitCellConfig: {
+        maxRows: number;
+        maxCols: number;
+    } | null;
+    contentControlAt: ContentControlSummary | null;
+    isInsideToc: boolean;
+    trackedChanges: readonly Revision[];
+}
+/**
+ * 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.
+ *
+ * `href` has already been through `sanitizeHref` — it comes from a file, so a `javascript:` or
+ * `data:` target is dropped at the parse boundary rather than here.
+ */
+interface HyperlinkInfo {
+    readonly href: string;
+    readonly range: DocRange;
+    /**
+     * `w:tooltip` on the `w:hyperlink` — the text Word shows on hover, and what the
+     * hyperlink dialog seeds its tooltip field with when editing an existing link.
+     */
+    readonly tooltip?: string;
+}
+/**
+ * Section page setup — size, orientation and margins, in twips — as `getPageSetup()`
+ * and `snapshot().pageSetup` report it and the `setPageSetup` command writes it. In a
+ * multi-section document this is the setup of the section the SELECTION is in, which
+ * is what a ruler or a dialog reflects — Word's behaviour.
+ */
+interface PageSetup {
+    readonly pageWidthTwips: number;
+    readonly pageHeightTwips: number;
+    readonly orientation: 'portrait' | 'landscape';
+    readonly marginsTwips: {
+        readonly top: number;
+        readonly right: number;
+        readonly bottom: number;
+        readonly left: number;
+    };
+    /** Binding gutter (`w:gutter`), folded into the left margin by layout. */
+    readonly gutterTwips?: number;
+}
+/**
+ * A read model of the current editor state, safe to hand to framework
+ * rendering. Named `EditorSnapshot` rather than `EditorState` so it never
+ * collides with an editing engine's own state type.
+ */
+interface EditorSnapshot {
+    readonly scope: EditorScope;
+    /** Whether the editor is still waiting for a document: no bytes handed over yet, and no
+     *  parse failure. Bytes count from the moment they are supplied, not from the moment
+     *  pages paint, so this stays false across a detach and remount. Safe to gate a mount
+     *  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
+     * additive: absent means the implementation has not derived it, read as `false`.
+     */
+    readonly isOpening?: boolean;
+    readonly parseError: string | 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;
+    readonly zoom: number;
+    /**
+     * Where {@link EditorSnapshot.zoom} came from.
+     *
+     * Both are needed, and neither implies the other: `zoom` is the resolved scale a ruler
+     * multiplies by, `zoomMode` is what a zoom control has to show as selected. A menu that
+     * ticked the entry matching the percentage would tick "75%" while the editor was tracking
+     * the viewport and about to move off it.
+     *
+     * Optional and additive like `pageSetup`; absent means the implementation has not derived
+     * it, and a consumer reads absent as a plain fixed scale.
+     */
+    readonly zoomMode?: ZoomMode;
+    readonly selection: DocRange | null;
+    /**
+     * Whether the selection is a CARET rather than a range. `true` when nothing is loaded.
+     *
+     * Separate from `selection` because `DocRange` addresses paragraphs by paraId and carries
+     * no offsets, so a caret and a range inside one paragraph are the same value there.
+     * Answering this from `query({ type: 'selectedText' })` builds the whole selected string
+     * to produce one bit, on every tick a host's selector runs.
+     */
+    readonly selectionCollapsed: boolean;
+    readonly formatting: RunFormatting | null;
+    readonly table: TableContext | null;
+    /**
+     * The table of contents the last right-click landed on, or null.
+     *
+     * NOT caret context, unlike `table`: a right-click leaves the selection where it was, and
+     * a generated TOC refuses the caret outright, so a host's context menu could otherwise
+     * never tell which table of contents it was opened over. Cleared by a right-click
+     * anywhere else.
+     */
+    readonly tocContext: {
+        readonly id: string;
+    } | null;
+    readonly image: ImageContext | null;
+    readonly page: {
+        readonly current: number;
+        readonly total: number;
+    };
+    /**
+     * Whether undo/redo have anything to apply, derived from the session's history.
+     * Optional and additive: an implementation that has not derived them omits them,
+     * and a consumer treats absent as `false` — the honest empty answer.
+     */
+    readonly canUndo?: boolean;
+    readonly canRedo?: boolean;
+    /**
+     * The section's page setup, reference-stable across ticks that did not change it.
+     * Optional and additive like `canUndo`: absent means the implementation has not
+     * derived it, `null` means no document is loaded.
+     */
+    readonly pageSetup?: PageSetup | null;
+    /**
+     * Whether the review pane is showing its cards.
+     *
+     * In the SNAPSHOT because chrome reflects it: the toolbar's comments button is pressed
+     * while it is open, and a button reads its pressed state from the snapshot like every
+     * other button. Kept off the snapshot it stayed pressed after the pane closed, because a
+     * 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.
+     *
+     * The free tier's honest signal: revisions render in their final-state
+     * projection there, so without this a host cannot tell its user "this
+     * document has tracked changes" — the one fact the upsell hint needs.
+     * Optional and additive like `canUndo`; derived cheaply from store
+     * vocabulary and memoized per revision.
+     */
+    readonly hasReviewContent?: boolean;
+    /** Authors whose revisions currently render as accepted and whose comments stay hidden. */
+    readonly hiddenReviewAuthors?: readonly string[];
+    /**
+     * Lifecycle of the attached collaboration replica, or `'inactive'` when no
+     * collaboration module is registered.
+     *
+     * The free tier's honest upsell signal: a host can render from this value
+     * without importing `@docx-editor.dev/pro`. When a module is registered the
+     * field follows the session's `status()`.
+     */
+    readonly collaborationStatus: CollaborationStatus | 'inactive';
+    /**
+     * How edits are written right now.
+     *
+     * In the snapshot for the same reason `reviewPaneOpen` is: the editing-mode control shows
+     * it, and a control reads what it shows from the snapshot like every other control.
+     */
+    readonly editingMode?: DocumentEditingMode;
+    /**
+     * Why the last edit was refused, or null.
+     *
+     * The engine knew — `lastRejection` has been on the surface all along — and nothing
+     * published it, so a keystroke refused because the document is open for viewing, or
+     * because suggesting has no author to attribute a proposal to, looked to the user like
+     * the editor had simply stopped responding.
+     */
+    readonly lastRejection?: string | null;
+    /**
+     * Document font families that are NOT AVAILABLE: declared by the document, but with no byte
+     * source admitted, no redirect to an admitted face, nothing embedded, and nothing the platform
+     * could resolve. Chrome shows a compatibility notice from this the way Word does.
+     *
+     * A family the app answers with a metric-compatible stand-in — Word's Times New Roman
+     * with Liberation Serif — is AVAILABLE and stays out: the outlines differ, the advance
+     * widths do not, so wrap and pagination land where Word puts them. The face a `w:sym`
+     * names (MS Gothic for a checkbox, Wingdings for a bullet) stays out too, because it
+     * paints one code point rather than text, and has no metric twin an app could supply.
+     *
+     * Optional and additive like `canUndo`: absent means the implementation has not derived
+     * it; empty means every family resolved (or no document is loaded).
+     */
+    readonly fontSubstitutions?: readonly string[];
+    /**
+     * Format painter arming, and the level of what it holds. Here for the same reason
+     * `lastRejection` is: it moves no revision and no caret, so a mode the snapshot does not
+     * carry is a mode no toolbar can reflect. Optional and additive.
+     */
+    readonly formatPainter?: FormatPainterSurfaceState;
+}
+/**
+ * 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.
+ */
+interface EditorError extends Error {
+    readonly code?: string;
+}
+
+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 };