@docx-editor.dev/core 2.32.0 → 2.34.0

package/dist/{headless-document-view-Bcz9_Qva.d.ts → drawing-graphic-kind-CK0cMc7H.d.ts}

@@ -1,19 +1,6 @@
-import { aC as OoxmlNodeId, ax as OoxmlGenericElementNode, a4 as OoxmlNode, a5 as OoxmlPackage, O as OoxmlPart, av as OoxmlElement, aB as OoxmlPackageRejection } from './tree-op-types-C_S2niXW.js';
-import { H as HeaderFooterParts, b as HeaderFooterSectionResolution, T as TreePackageStore } from './tree-package-store-CRHvMyNj.js';
+import { aG as OoxmlNodeId, ax as OoxmlGenericElementNode, a4 as OoxmlNode, a5 as OoxmlPackage, O as OoxmlPart, av as OoxmlElement, aA as OoxmlPackageRejection } from './tree-op-types-DKvJSH8T.js';
+import { e as HeaderFooterParts, f as HeaderFooterSectionResolution, T as TreePackageStore } from './tree-package-store-Cl3BkWXF.js';
 
-/** Office Math Markup Language namespace. */
-declare const OFFICE_MATH_NAMESPACE_URI = "http://schemas.openxmlformats.org/officeDocument/2006/math";
-declare const DEFAULT_OMML_LIMITS: Readonly<{
-    maxDepth: 24;
-    maxNodes: 256;
-    maxTextLength: 512;
-}>;
-/** Shared work limits for untrusted OMML and linear-math input. */
-interface OmmlLimits {
-    readonly maxDepth?: number;
-    readonly maxNodes?: number;
-    readonly maxTextLength?: number;
-}
 /**
  * Marks a structure whose property element carries `m:ctrlPr` operator run formatting that
  * compact replacement cannot reproduce.
@@ -26,6 +13,17 @@ interface OmmlLimits {
 interface EquationControlSource {
     /** The structure carries non-default `m:ctrlPr` properties, so compact replacement refuses it. */
     readonly controlProperties?: true;
+    /**
+     * Font size of the structure, in points. The source is the `w:sz` value of the run
+     * properties in the structure's `m:ctrlPr`, which counts half-points.
+     *
+     * Layout sizes script offsets and bar strokes and gaps from this size, not from the size of
+     * the runs inside the structure. When it is not set, those use the size of the text around
+     * the equation. A script or fraction after the first atom of the equation takes its offsets
+     * from the size of that first atom instead. Set whether or not the control properties are
+     * default. Radicals and n-ary operators with limits below and above do not use it yet.
+     */
+    readonly controlFontSizePt?: number;
 }
 type EquationExpression = {
     readonly kind: 'row';
@@ -33,8 +31,32 @@ type EquationExpression = {
 } | {
     readonly kind: 'text';
     readonly value: string;
+    /**
+     * Authored font size of the run, in points. The source is the `w:sz` value of the
+     * run properties (`w:rPr`), which counts half-points.
+     *
+     * Set only when every run of the equation holds the same default math formatting: the
+     * Cambria Math font, italic, one size, and at most a language. Such runs have no
+     * `format`, so compact replacement stays available and writes the same `w:rPr` back.
+     * Otherwise the size is in `format.fontSizePt`. When neither field is set, the text
+     * takes the size of the surrounding text. To read the size of any text expression,
+     * use `format?.fontSizePt ?? fontSizePt`.
+     */
+    readonly fontSizePt?: number;
+    /**
+     * Source formatting of the run. Set when the run has its own supported formatting and
+     * the equation does not use the uniform default math formatting. Compact replacement
+     * refuses an equation that has a text expression with a `format`, because it cannot
+     * write that formatting back.
+     */
     readonly format?: {
         readonly fontFamily?: string;
+        /**
+         * Authored font size of the run, in points. The source is the `w:sz` value of the
+         * run properties (`w:rPr`), which counts half-points. Set when the run has a
+         * `format` and a `w:sz`. The top-level `fontSizePt` is not set in that case.
+         */
+        readonly fontSizePt?: number;
         readonly bold?: boolean;
         readonly italic?: boolean;
         readonly literal?: boolean;
@@ -60,14 +82,64 @@ type EquationExpression = {
     readonly superscript?: EquationExpression;
 } & EquationControlSource) | ({
     readonly kind: 'nary';
+    /** The operator character from `m:chr`, or `∫` when the source names none. */
     readonly operator: string;
     readonly body: EquationExpression;
     readonly lowerLimit?: EquationExpression;
     readonly upperLimit?: EquationExpression;
+    /**
+     * Where the limits sit, from `m:limLoc`: `undOvr` below and above the operator, `subSup`
+     * to its right as a subscript and superscript. Not set when the source names none.
+     * Inline equations place the limits to the right either way. An `m:oMath` alone in its
+     * paragraph is a display equation, as an `m:oMathPara` is, and follows this location.
+     */
+    readonly limitLocation?: 'undOvr' | 'subSup';
+} & EquationControlSource) | ({
+    /**
+     * `m:borderBox`: the body inside a rectangle. A hidden edge draws no rule and keeps no
+     * gap. Strikes cross the box horizontally, vertically, or along a diagonal.
+     */
+    readonly kind: 'borderBox';
+    readonly body: EquationExpression;
+    readonly hidden: EquationBoxEdges;
+    readonly strikes: EquationBoxStrikes;
 } & EquationControlSource) | {
     readonly kind: 'fallback';
     readonly text: string;
 };
+/** The edges of an `m:borderBox` that its properties hide. */
+interface EquationBoxEdges {
+    readonly top: boolean;
+    readonly bottom: boolean;
+    readonly left: boolean;
+    readonly right: boolean;
+}
+/** The strikes an `m:borderBox` draws across its body. */
+interface EquationBoxStrikes {
+    /** `m:strikeH`: a horizontal line through the centre. */
+    readonly horizontal: boolean;
+    /** `m:strikeV`: a vertical line through the centre. */
+    readonly vertical: boolean;
+    /** `m:strikeBLTR`: from the bottom-left corner to the top-right corner. */
+    readonly bottomLeftToTopRight: boolean;
+    /** `m:strikeTLBR`: from the top-left corner to the bottom-right corner. */
+    readonly topLeftToBottomRight: boolean;
+}
+
+/** Office Math Markup Language namespace. */
+declare const OFFICE_MATH_NAMESPACE_URI = "http://schemas.openxmlformats.org/officeDocument/2006/math";
+declare const DEFAULT_OMML_LIMITS: Readonly<{
+    maxDepth: 24;
+    maxNodes: 256;
+    maxTextLength: 512;
+}>;
+/** Shared work limits for untrusted OMML and linear-math input. */
+interface OmmlLimits {
+    readonly maxDepth?: number;
+    readonly maxNodes?: number;
+    readonly maxTextLength?: number;
+}
+
 interface OmmlEquationProjection {
     readonly sourceNodeId: OoxmlNodeId;
     readonly expression: EquationExpression;
@@ -76,7 +148,8 @@ interface OmmlEquationProjection {
     readonly visitedNodes: number;
     /**
      * The font size, in points, that every run of the equation shares through default run
-     * properties (`w:sz`). Absent, the equation takes the size of the surrounding text.
+     * properties (`w:sz`). Individual run sizes remain on their text expressions. Without a
+     * shared size, structural spacing takes the size of the surrounding text.
      */
     readonly fontSizePt?: number;
 }
@@ -250,5 +323,75 @@ declare function openHeadlessDocument(bytes: Uint8Array): OpenHeadlessDocumentRe
 /** Internal live read view over the canonical store, preserving node identities for field pagination. */
 declare function headlessViewOfStore(store: TreePackageStore): HeadlessDocumentView;
 
-export { DEFAULT_OMML_LIMITS as b, OFFICE_MATH_NAMESPACE_URI as h, authorableHyperlinkTarget as k, ensureHyperlinkRelationship as l, equationExpressionToLinearMath as m, headlessViewOfStore as n, linearMathToOmml as o, openHeadlessDocument as p, parseLinearMath as q, projectOmmlEquation as r, relationshipTargetIn as s };
-export type { DocumentProperties as D, EnsuredHyperlinkRelationship as E, HeadlessDocumentView as H, LinearMathOmmlResult as L, OmmlEquationProjection as O, HeadlessDocumentRejection as a, EquationControlSource as c, EquationExpression as d, HeadlessThemeFonts as e, LinearMathParseResult as f, LinearMathRejection as g, OmmlLimits as i, OpenHeadlessDocumentResult as j };
+/**
+ * A drawing feature that the editor does not show as authored. Each code means:
+ *
+ * - `unsupported-effect`: the editor ignores an explicit effect, such as `a:blur`, `a:duotone`,
+ *   or `a14:imgProps`. The drawing renders without it.
+ * - `renderer-required`: an optional effect, such as `a:glow`, needs the drawing module:
+ *   `drawingModule()` or `installDrawing()` from `@docx-editor.dev/pro/drawing`. It appears
+ *   only while that module is not installed in the current process, for occurrences and
+ *   reports alike.
+ * - `unverified-3d`: the drawing has 3-D properties (`a:scene3d`, `a:sp3d`), which render flat.
+ * - `saved-fallback`: the editor shows the saved `mc:Fallback` content, not the main content.
+ * - `unplaced-drawing`: the drawing has no layout position, so the editor does not show it.
+ * - `inspection-limit`: a scan budget stopped the check, so the result is incomplete.
+ * - `projection-diagnostic`: the source is malformed or partly unusable. `detail` holds the
+ *   diagnostic code, such as `invalid-geometry` or `resource-refused`.
+ *
+ * The check reads the drawing's own XML. It does not read chart or diagram parts, inherited
+ * theme effects, or image bytes, so an empty list does not prove full fidelity.
+ *
+ * @public
+ */
+interface DrawingSupportIssue {
+    /** The kind of limitation. The list in this type's description explains each code. */
+    readonly code: 'unsupported-effect' | 'renderer-required' | 'unverified-3d' | 'saved-fallback' | 'unplaced-drawing' | 'inspection-limit' | 'projection-diagnostic';
+    /**
+     * The source node with the feature: in the inspected package for a report, or in the
+     * editor's current document for an occurrence's `drawingIssues`.
+     */
+    readonly nodeId: string;
+    /** The namespace of the node with the feature. */
+    readonly namespaceUri: string;
+    /** The local name of the node with the feature, such as `blur`. */
+    readonly localName: string;
+    /** The feature, such as `a:blur` or `mc:Fallback`, or the projection diagnostic code. */
+    readonly detail: string;
+}
+/**
+ * How completely the editor shows a drawing:
+ *
+ * - `native`: the editor renders the drawing and found no unsupported feature in its source.
+ * - `partial`: the editor renders the drawing, but without some features, or it shows a saved
+ *   fallback. The issue list names the features.
+ * - `unrendered`: the editor shows a placeholder, or the drawing has no layout position.
+ *
+ * A drawing that the document itself hides is `native` or `partial`: the editor shows it as
+ * authored, which is not at all.
+ *
+ * Charts and SmartArt diagrams that the editor draws report `native`, because the check does
+ * not read their chart or diagram parts. Inherited theme effects and image bytes are not
+ * checked either.
+ *
+ * @public
+ */
+type DrawingSupport = 'native' | 'partial' | 'unrendered';
+
+/**
+ * The kind of graphic a drawing holds. Note: `textbox` names every DrawingML shape, with or
+ * without text, and `shape` names only legacy VML drawings.
+ *
+ * Read from its source: `picture`, `chart` (a chart),
+ * `diagram` (SmartArt), `textbox` (a DrawingML shape, with or without text), `group` (a shape
+ * group), `canvas` (a drawing canvas), `shape` (a legacy VML drawing, such as WordArt), or
+ * `graphic` (any other graphic). It does not say whether the engine renders the graphic.
+ * The names match `placeholderGraphicKind`, which adds no `picture` and is set only for
+ * placeholders.
+ *
+ * @public
+ */
+type DrawingGraphicKind = 'picture' | 'chart' | 'diagram' | 'shape' | 'group' | 'textbox' | 'canvas' | 'graphic';
+
+export { DEFAULT_OMML_LIMITS as e, OFFICE_MATH_NAMESPACE_URI as m, authorableHyperlinkTarget as p, ensureHyperlinkRelationship as q, equationExpressionToLinearMath as r, headlessViewOfStore as s, linearMathToOmml as t, openHeadlessDocument as u, parseLinearMath as v, projectOmmlEquation as w, relationshipTargetIn as x };
+export type { DrawingGraphicKind as D, EnsuredHyperlinkRelationship as E, HeadlessDocumentView as H, LinearMathOmmlResult as L, OmmlEquationProjection as O, DrawingSupport as a, DrawingSupportIssue as b, DocumentProperties as c, HeadlessDocumentRejection as d, EquationBoxEdges as f, EquationBoxStrikes as g, EquationControlSource as h, EquationExpression as i, HeadlessThemeFonts as j, LinearMathParseResult as k, LinearMathRejection as l, OmmlLimits as n, OpenHeadlessDocumentResult as o };

package/dist/drawing-preview-package-fFjXpOMS.d.ts

@@ -0,0 +1,115 @@
+import { a5 as OoxmlPackage } from './tree-op-types-DKvJSH8T.js';
+
+/** The longest name a bookmark is written with. */
+declare const MAX_AUTHORED_BOOKMARK_NAME_LENGTH = 40;
+/**
+ * Why a name cannot be written, or null when it can.
+ *
+ * - `empty`: no characters.
+ * - `tooLong`: more than {@link MAX_AUTHORED_BOOKMARK_NAME_LENGTH} characters.
+ * - `invalidStart`: the first character is not a letter or an underscore.
+ * - `invalidCharacter`: a later character is not a letter, a digit or an underscore.
+ *
+ * @public
+ */
+type BookmarkNameProblem = 'empty' | 'tooLong' | 'invalidStart' | 'invalidCharacter';
+/**
+ * Check a name before it is written. Measured in code points, so a letter outside the Basic
+ * Multilingual Plane counts once.
+ *
+ * @public
+ */
+declare function bookmarkNameProblem(name: string): BookmarkNameProblem | null;
+/**
+ * Whether a bookmark is hidden: its name starts with an underscore. Hidden bookmarks are the
+ * ones applications write for themselves, such as the targets of a table of contents.
+ *
+ * @public
+ */
+declare function isHiddenBookmarkName(name: string): boolean;
+/**
+ * The key two names are compared by. Names are case-insensitive, so `Intro` and `intro`
+ * share a key.
+ *
+ * @public
+ */
+declare function bookmarkNameKey(name: string): string;
+
+/**
+ * Where a drawing is. Pass an `inspectDrawingSupport` entry or an editor occurrence as is.
+ *
+ * @public
+ */
+interface DrawingPreviewTarget {
+    /** The part that holds the drawing, such as `/word/document.xml`. */
+    readonly ownerPartName: string;
+    /**
+     * The drawing, its compatibility wrapper, or any node inside them, in the package you pass.
+     * Every node of one drawing gives the same package.
+     */
+    readonly nodeId: string;
+}
+/** Caps for {@link createDrawingPreviewPackage}. @public */
+interface DrawingPreviewPackageLimits {
+    /** Maximum number of copied parts. Defaults to 64. */
+    readonly maxParts?: number;
+    /** Maximum number of copied bytes. Defaults to 64 MiB. */
+    readonly maxBytes?: number;
+}
+/**
+ * A preview package, or why it could not be built.
+ *
+ * - `drawing-not-found`: the target is not a drawing in the package.
+ * - `too-many-parts` or `too-large`: the drawing needs more than the limits allow.
+ *
+ * @public
+ */
+type DrawingPreviewPackageResult = {
+    readonly ok: true;
+    /**
+     * DOCX bytes with one paragraph that holds the drawing. The same drawing and document
+     * parts always give the same bytes, so a hash of them works as a cache key.
+     */
+    readonly docx: Uint8Array;
+    /**
+     * True when the page has the drawing's size, so the first page is the preview image.
+     * False when the size is unknown, such as a legacy VML drawing without a width and height
+     * in its style. Then the page has the document's page size and no margins, and the
+     * drawing starts at its top left corner. With the occurrence's `element.bounds`, crop
+     * from (0, 0) to `bounds.width * dpi / 72` by `bounds.height * dpi / 72` pixels;
+     * `bounds.x` and `bounds.y` are page positions, not crop offsets. Send this flag and the
+     * `bounds` size to your renderer with the bytes.
+     * Without `bounds`, such as for a report entry, trim the white space instead.
+     */
+    readonly pageFitsDrawing: boolean;
+    /** The package parts copied from the source document, for logging and caching. */
+    readonly copiedParts: readonly string[];
+} | {
+    readonly ok: false;
+    readonly reason: 'drawing-not-found' | 'too-many-parts' | 'too-large';
+};
+/**
+ * Build a small DOCX that holds one drawing for an external renderer.
+ *
+ * Contents: one paragraph with the drawing, plus the chart and diagram parts, images, styles,
+ * theme, settings, and fonts it needs. Relationships to external targets, embedded objects,
+ * macros, and templates are dropped, so the package never points outside itself.
+ *
+ * Page: the first page is the preview. It has the drawing's size, including its effect
+ * extent, so it matches the occurrence's `bounds`, and it has no margins. A floating drawing
+ * is placed on the line, and a legacy VML drawing takes its size from its style. When the
+ * size is unknown, `pageFitsDrawing` is false; see that field for how to crop.
+ *
+ * Renderer: use one other than this library, whose own exporters show the same placeholder.
+ * The bytes come from the document, so run the renderer in a sandbox without network access,
+ * with time and memory limits.
+ *
+ * Pass the package that the target comes from: an `inspectDrawingSupport` entry with the
+ * parsed package it inspected, or an editor occurrence with the editor's current package.
+ *
+ * @public
+ */
+declare function createDrawingPreviewPackage(pkg: OoxmlPackage, target: DrawingPreviewTarget, limits?: DrawingPreviewPackageLimits): DrawingPreviewPackageResult;
+
+export { MAX_AUTHORED_BOOKMARK_NAME_LENGTH as M, bookmarkNameKey as c, bookmarkNameProblem as d, createDrawingPreviewPackage as e, isHiddenBookmarkName as i };
+export type { BookmarkNameProblem as B, DrawingPreviewPackageLimits as D, DrawingPreviewPackageResult as a, DrawingPreviewTarget as b };

package/dist/{editor-DZwOTmlR.d.ts → editor-DDCkWqfD.d.ts}

@@ -1,13 +1,13 @@
-import { d as ResolvedRevisionMarkup, a as ReviewDisplayMode } from './revision-projection-Cn6rZJ7H.js';
+import { d as ResolvedRevisionMarkup, a as ReviewDisplayMode } from './revision-projection-DwFhgIR0.js';
 import { ResolvedReviewPane } from './contracts/types.js';
-import { V as ViewScope, b as HistoryDiagnostic, c as HistoryGroup, a as EditorExecOptions, E as EditorScope, d as HistoryGroupOptions } from './editor-scope-B3L-1ALc.js';
+import { V as ViewScope, b as HistoryDiagnostic, c as HistoryGroup, a as EditorExecOptions, E as EditorScope, d as HistoryGroupOptions } from './editor-scope-CA6egMaK.js';
 import { E as EditorFontErrorCode, a as FontFaceRequest } from './editor-fonts-D_-vjuJi.js';
-import { t as DocAnchor, g as ReviewRevisionKind, c as ReviewCommentItem, b as ReviewRevisionItem, d as ReviewCustomItem, aT as SourceCrop, a8 as DrawingKind, ag as ImageWrapTarget, aa as DrawingPositionInput, a9 as DrawingLocks, af as ImageResourceState, r as ColorValue, x as ExecErrorCode, ah as ParagraphFormatCommand, an as SupportedImageMime, ar as Watermark, E as ExecResult, at as WatermarkState, n as ContentControlFilter, o as DocRange, k as RunFormatting, p as Revision, ak as Rect, am as SelectionPin, ao as Unsubscribe } from './tree-op-types-C_S2niXW.js';
-import { C as CollaborationDiagnosticCode, c as CustomNodeDiagnosticCode, D as DiagnosticErrorName, F as FailureStage, B as ByteSizeBucket, b as CountBucket, f as DocumentOpenDiagnosticCode, a as DocumentPartKind, g as DocumentSaveDiagnosticCode, E as EditDiagnosticCode, j as ReviewDiagnosticCode, k as ReviewOperation, R as ReviewChangeKind, i as FormattingChangeKind, h as FontDiagnosticCode, H as HistoryDiagnosticCode, P as PerformanceDiagnosticCode } from './diagnostic-hints-DK8-V0fk.js';
+import { T as RevisionBatchSkipDetail, t as DocAnchor, g as ReviewRevisionKind, c as ReviewCommentItem, b as ReviewRevisionItem, d as ReviewCustomItem, aT as SourceCrop, a8 as DrawingKind, ag as ImageWrapTarget, aa as DrawingPositionInput, a9 as DrawingLocks, af as ImageResourceState, r as ColorValue, x as ExecErrorCode, ah as ParagraphFormatCommand, an as SupportedImageMime, ar as Watermark, E as ExecResult, at as WatermarkState, n as ContentControlFilter, o as DocRange, k as RunFormatting, p as Revision, ak as Rect, am as SelectionPin, ao as Unsubscribe } from './tree-op-types-DKvJSH8T.js';
+import { C as CollaborationDiagnosticCode, b as CustomNodeDiagnosticCode, c as DiagnosticErrorName, F as FailureStage, B as ByteSizeBucket, a as CountBucket, e as DocumentOpenDiagnosticCode, f as DocumentPartKind, g as DocumentSaveDiagnosticCode, E as EditDiagnosticCode, R as ReviewDiagnosticCode, k as ReviewOperation, j as ReviewChangeKind, i as FormattingChangeKind, h as FontDiagnosticCode, H as HistoryDiagnosticCode, P as PerformanceDiagnosticCode } from './diagnostic-hints-BTyb8yzX.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-CJoHLoOl.js';
-import { a as DocumentProtectionState } from './document-protection-NaniLHWF.js';
+import { a as SemanticSelection, S as SemanticPosition } from './semantic-interaction-QeuzEtAk.js';
+import { a as DocumentProtectionState } from './document-protection-DdWxihIN.js';
 import { a as CollaborationStatus } from './failure-6KGFrDO9.js';
 
 /**
@@ -273,8 +273,11 @@ interface ReviewSkippedDiagnostic extends DiagnosticBase {
     /** The role of the part the changes are in, such as `'footnotes'`. Never its name. */
     readonly part?: DocumentPartKind;
     /**
-     * For `review.revision-unsupported`, the engine condition that refused the change, such as
-     * `unaddressed` (no `w:id` or author) or `unrecorded-properties`. See `diagnosticCauses()`.
+     * The structure behind the skip. For `review.revision-unsupported`, the engine condition that
+     * refused the change, such as `unaddressed` (no `w:id` or author). For
+     * `review.incomplete-group`, the change the decision would also decide, such as
+     * `paired-change` (the other half of a move or merge) or `removed-content`. For
+     * `review.retained-structure`, `nested-table`. See `diagnosticCauses()`.
      */
     readonly cause?: string;
 }
@@ -411,8 +414,8 @@ interface EditorEvents {
     change: (change: DocumentChange) => void;
     /**
      * Observable editor state moved without a document change: the selection or its derived
-     * formatting, the armed typing format, the open header or footer, or the collaboration
-     * session's status.
+     * formatting, the armed typing format, the open header or footer, the collaboration
+     * session's status, or the page count when pages finish laying out in the background.
      */
     selectionChange: (snapshot: EditorSnapshot) => void;
     error: (error: EditorError) => void;
@@ -452,6 +455,20 @@ interface EditorEvents {
      * ```
      */
     reviewItemReveal: (event: ReviewItemRevealEvent) => void;
+    /**
+     * An accept-all or reject-all decision committed: from the toolbar, the menu, or
+     * `exec({ type: 'resolveAllReviewChanges' })`. `skipped` names the changes it left pending,
+     * so a host can say why they stay. A remote decision in a collaboration session never fires
+     * it: it is a local event.
+     *
+     * @example
+     * ```ts
+     * editor.on('reviewChangesResolved', ({ skipped }) => {
+     *   if (skipped.length) showNotice(`${skipped.length} changes stay pending`);
+     * });
+     * ```
+     */
+    reviewChangesResolved: (event: ReviewChangesResolvedEvent) => void;
     /**
      * The editor's pages are now in another document: it was attached for the first time, moved
      * into another element or window, detached (`document` is `null`), or found its element
@@ -516,6 +533,33 @@ interface ReviewItemRevealEvent {
      */
     readonly source: ReviewItemRevealSource;
 }
+/**
+ * The payload of the `reviewChangesResolved` event.
+ *
+ * @public
+ */
+interface ReviewChangesResolvedEvent {
+    /** Whether the decision accepted or rejected the changes. */
+    readonly action: 'accept' | 'reject';
+    /** How many listed changes it resolved. The `exec` result lists them in `revisions.resolved`. */
+    readonly resolvedCount: number;
+    /**
+     * The listed changes it left pending, with why: `'retained-structure'` for a row that stays
+     * to keep a nested table, `'incomplete-group'` for a change that would also resolve one the
+     * selection leaves out, `'unsupported-revision'` for a structure the engine cannot resolve,
+     * and `'unknown-revision'` for a key that no longer names a change. `reviewCodeOfSkip(skip)`
+     * gives each entry's review code, with its `detail`.
+     */
+    readonly skipped: readonly {
+        /** The skipped change's key, as `getReviewItems({ pairReplacements: false })` lists it. */
+        readonly key: string;
+        /** The key of the replacement it is one half of, as the default `getReviewItems()` lists it. */
+        readonly pairKey?: string;
+        readonly reason: 'unsupported-revision' | 'incomplete-group' | 'retained-structure' | 'unknown-revision';
+        /** Which condition kept it, such as `'locked-content'` (a content lock) or `'bound-content'` (a data binding). */
+        readonly detail?: RevisionBatchSkipDetail;
+    }[];
+}
 /** What asked to reveal a review item. See {@link ReviewItemRevealEvent.source}. @public */
 type ReviewItemRevealSource = 'navigate' | 'host';
 /**
@@ -1162,7 +1206,11 @@ interface AuthoredNoteNumbering {
     readonly numStart?: number;
     readonly numRestart?: string;
 }
-/** Resolved note-numbering fields after document/section cascade. */
+/**
+ * Resolved note-numbering fields for one section. Numbering and the footnote position come
+ * from the section's own properties and the defaults; the endnote position comes from the
+ * document settings.
+ */
 interface ResolvedNoteNumbering {
     readonly pos: string;
     readonly numFmt: string;
@@ -1172,7 +1220,12 @@ interface ResolvedNoteNumbering {
 /** One note kind's resolved + authored properties for the caret section. */
 interface NotePropertiesSide {
     readonly resolved: ResolvedNoteNumbering;
+    /**
+     * The document settings (settings.xml) values. Only the endnote `pos` affects `resolved`;
+     * the other fields are kept for files that carry them.
+     */
     readonly documentAuthored?: AuthoredNoteNumbering;
+    /** The caret section's own values, which set numbering and the footnote position. */
     readonly sectionAuthored?: AuthoredNoteNumbering;
 }
 /** Resolved and authored note properties for the caret section — properties dialog read-model. */
@@ -1272,8 +1325,17 @@ interface EditorNoteCommands {
         fromKind: NoteKind;
     };
     /**
-     * Footnote and endnote properties for the section — numbering format, restart rule
-     * and position, as Word's dialog offers them.
+     * Footnote and endnote properties: numbering format, start value, restart rule and
+     * position.
+     *
+     * - `scope: 'document'` (the default) writes every section and the document settings.
+     * - `scope: 'section'` writes the `sectionIndex` section.
+     * - The endnote `position` applies to the whole document, so it always goes to the document
+     *   settings, in either scope, and never to a section.
+     * - Fields you omit keep each section's value. A value equal to the default is not added
+     *   where nothing authors the field, so applying the values a section already shows
+     *   leaves the document unchanged.
+     * - The write is not tracked in suggesting mode, like other section property writes.
      */
     setNoteProperties: {
         scope?: 'document' | 'section';
@@ -1438,9 +1500,21 @@ interface SelectedImageState {
         readonly dpiX: number;
         readonly dpiY: number;
     }> | null;
+    /**
+     * Whether `setImageProperties` can change the size. False for a hidden drawing, a drawing
+     * whose size is locked, a rotated legacy VML text box or one sized as a percentage of a
+     * frame, and in viewing mode. An inline text box resizes.
+     */
     readonly canResize: boolean;
+    /**
+     * Whether `setImagePosition` can move the drawing. False for an inline drawing, which flows
+     * with its line, for a locked or hidden drawing, a rotated legacy VML text box, and in
+     * viewing mode.
+     */
     readonly canMove: boolean;
+    /** Whether `setImageWrapType` applies: pictures only, never text boxes. */
     readonly canChangeWrap: boolean;
+    /** Whether `setImageProperties` can crop: pictures only, never text boxes. */
     readonly canCrop: boolean;
 }
 /**
@@ -1627,6 +1701,9 @@ interface TableColumnOccurrenceTarget {
     readonly isHeaderRepeat: boolean;
 }
 
+/** Keys for the table furniture's accessible names, resolved by `tableInteractionLabel`. */
+type TableInteractionLabelKey = 'table.insertRowBelow' | 'table.insertColumnRight' | 'table.selectTable';
+
 /**
  * An opaque handle to a loaded document — its stable identity and current
  * revision. The canonical authored state is the engine's `PackageModel`, NOT a
@@ -1900,7 +1977,7 @@ interface Editor extends EditorAnchorNavigation, EditorHighlights, EditorReviewH
         readonly cellIds: readonly string[];
     } | null;
     /** Update table furniture aria labels without remounting the editor. */
-    setTableInteractionLabel(resolver: (key: 'table.insertRowBelow' | 'table.insertColumnRight') => string): void;
+    setTableInteractionLabel(resolver: (key: TableInteractionLabelKey) => string): void;
     /** Section page setup — size, orientation and margins — for the page-setup dialog. */
     getPageSetup(): PageSetup | null;
     /**
@@ -2101,7 +2178,13 @@ interface Editor extends EditorAnchorNavigation, EditorHighlights, EditorReviewH
      *
      * Refused for a card whose kind the engine cannot resolve structurally, which is why
      * `readOnly` is on the item — a surface should not offer the button in the first place.
-     * Other refusals name their cause, as {@link addComment} describes.
+     * Other refusals name their cause, as {@link addComment} describes. A change that resolves
+     * only together with another change refuses with a reason led by `incomplete-group:`, and a
+     * row that stays to keep a nested table with one led by `retained-structure:`. A change a
+     * content control lock keeps refuses with `code: 'locked'` and a reason led by
+     * `locked-content:`; one in a data-bound control with `code: 'bound'` and `bound-content:`.
+     * `reviewCodeOfRefusal(result.reason)` names the review code of each. In a React or
+     * Vue host, `useReviewRefusalMessage()` turns `useReview().lastRefusal` into a sentence.
      *
      * Neither call scrolls. In a React or Vue host with the review module, `useReview().accept`
      * and `useReview().reject` call these. For headless or server use, see `Revision.accept()`
@@ -2156,7 +2239,17 @@ interface Editor extends EditorAnchorNavigation, EditorHighlights, EditorReviewH
     replyToReviewItem(key: string, text: string, options?: HistoryGroupOptions): ExecResult;
     /** {@link replyToReviewItem} with an author for this call, overriding the configured author. */
     replyToReviewItem(key: string, text: string, author?: string, options?: HistoryGroupOptions): ExecResult;
+    /**
+     * Move editing into `scope`: the body, a header or footer, a note, or a text box (`frame`).
+     *
+     * A frame whose `owner` is a header or footer opens that story first and edits the box
+     * inside it. The box is edited on the page of the open story when that story is already
+     * open, otherwise on the page in view, otherwise on the first page that shows it. A frame
+     * owned by a note, a box with rotated or vertical text, and a box holding a table are refused:
+     * the scope stays where it was. Read {@link getActiveScope} to confirm the entry.
+     */
     setActiveScope(scope: ViewScope): void;
+    /** The scope editing is in, as {@link setActiveScope} last set it or a press moved it. */
     getActiveScope(): ViewScope;
     query<K extends keyof EditorQueries>(query: {
         type: K;
@@ -2654,6 +2747,15 @@ interface EditorCommands extends EditorCommandShape<DocEdits>, EditorHeaderFoote
         tocId?: string;
         mode?: 'entire' | 'pageNumbers';
     };
+    /**
+     * Remove a table of contents: its field, or the table of contents control around it with
+     * its heading. Text before and after the field stays. Without `tocId`, removes the table of
+     * contents last right-clicked, the one at the selection, or the only one. One undo step.
+     * Refuses with `notFound` when there is none, and while suggesting.
+     */
+    removeToc: {
+        tocId?: string;
+    };
     undo: Record<never, never>;
     redo: Record<never, never>;
     /**
@@ -2878,8 +2980,8 @@ interface EditorSnapshot {
     /**
      * 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
+     * NOT caret context, unlike `table`: a generated TOC refuses the caret outright, so a
+     * right-click on it leaves the selection where it was, and a host's context menu could otherwise
      * never tell which table of contents it was opened over. Cleared by a right-click
      * anywhere else.
      */
@@ -2976,8 +3078,10 @@ interface EditorSnapshot {
      * 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.
+     * names (MS Gothic for a checkbox, Wingdings for a bullet) stays out while each glyph it
+     * draws has a Unicode equivalent, because any face can paint that. A `w:sym` face joins
+     * when one of its glyphs is a private-use code point with no equivalent, because that
+     * glyph shows as a missing-glyph box in every other face.
      *
      * Optional and additive like `canUndo`: absent means the implementation has not derived
      * it; empty means every family resolved (or no document is loaded).
@@ -3002,5 +3106,5 @@ interface EditorError extends Error {
     readonly code?: string;
 }
 
-export { DIAGNOSTIC_SCHEMA_VERSION as D, EditorFontError as J, cropPercentFromCropPermille as aR, cropPercentFromPermille as aS, cropPercentFromSourceCrop as aT, cropPermilleFromCropPercent as aU, cropPermilleFromPercent as aV, sourceCropFromCropPercent as aW, validateImageCropPercent as aX };
-export type { FurnitureVariant as $, AnchorHighlightAnimation as A, BookmarkPlace as B, CanResult as C, EditorDiagnostic as E, EditorCommandShape as F, EditorCommands as G, EditorError as H, EditorEvents as I, EditorFormatPainterCommands as K, EditorHeaderFooterCommands as L, EditorHighlights as M, EditorHostChange as N, EditorHostDocument as O, EditorNoteCommands as P, EditorPosition as Q, EditorQueries as R, EditorQuery as S, EditorQueryResults as T, EditorReviewHits as U, EditorSelection as V, EditorSnapshot as W, FontFailedDiagnostic as X, FormatPainterLevel as Y, FormatPainterMode as Z, FormatPainterSurfaceState as _, EditorDiagnosticKind as a, HeaderFooterSlotArgs as a0, HeaderFooterState as a1, HighlightHit as a2, HighlightOptions as a3, HighlightRange as a4, HighlightRect as a5, HighlightResult as a6, HistoryDiagnosticEvent as a7, HyperlinkInfo as a8, ImageContext as a9, TableBorderEdgeTarget as aA, TableBorderSpec as aB, TableBorderStyle as aC, TableBorderTarget as aD, TableCellVerticalAlignment as aE, TableColumnDividerResizeTarget as aF, TableColumnOccurrenceTarget as aG, TableContext as aH, TableRightEdgeResizeTarget as aI, TableRowOccurrenceTarget as aJ, TextMatch as aK, TimingSummary as aL, TrackedChangeFilterMode as aM, TrackedChangePredicate as aN, ZoomFitTarget as aO, ZoomMode as aP, ImageCropPermille as aQ, ImageCropPercent as aa, NoteKind as ab, NotePropertiesSide as ac, NotePropertiesState as ad, PageSetup as ae, PerformanceDiagnostic as af, ResolveReviewChangesOptions as ag, ResolvedNoteNumbering as ah, ReviewActivationOptions as ai, ReviewChangesAttribution as aj, ReviewCommentPlacement as ak, ReviewCustomPlacement as al, ReviewItemHit as am, ReviewItemPlacement as an, ReviewItemPlacementBase as ao, ReviewItemQuery as ap, ReviewItemRevealEvent as aq, ReviewItemRevealSource as ar, ReviewRevisionPlacement as as, ReviewSkippedDiagnostic as at, ScrollPlacement as au, ScrollToAnchorOptions as av, SelectedImageState as aw, SessionActivity as ax, SessionDiagnostic as ay, SetReviewChangesAuthorOptions as az, EditorCommand as b, AnchorHighlightOptions as c, AuthoredNoteNumbering as d, BookmarkStory as e, BookmarkSummary as f, ClearAnchorHighlightOptions as g, CollaborationParticipantsDiagnostic as h, CollaborationStatusDiagnostic as i, CustomNodeDiagnosticEvent as j, DiagnosticBase as k, DiagnosticFailureDetail as l, DocumentChange as m, DocumentEditingMode as n, DocumentHandle as o, DocumentOpenDiagnostic as p, DocumentOpenFailure as q, DocumentOpenFailureReason as r, DocumentSaveDiagnostic as s, DocumentShape as t, DocumentSource as u, EditRejectedDiagnostic as v, EditRejectionOrigin as w, Editor as x, EditorAnchorNavigation as y, EditorBookmarkCommands as z };
+export { DIAGNOSTIC_SCHEMA_VERSION as D, EditorFontError as J, cropPercentFromCropPermille as aT, cropPercentFromPermille as aU, cropPercentFromSourceCrop as aV, cropPermilleFromCropPercent as aW, cropPermilleFromPercent as aX, sourceCropFromCropPercent as aY, validateImageCropPercent as aZ };
+export type { FurnitureVariant as $, AnchorHighlightAnimation as A, BookmarkPlace as B, CanResult as C, EditorDiagnostic as E, EditorCommandShape as F, EditorCommands as G, EditorError as H, EditorEvents as I, EditorFormatPainterCommands as K, EditorHeaderFooterCommands as L, EditorHighlights as M, EditorHostChange as N, EditorHostDocument as O, EditorNoteCommands as P, EditorPosition as Q, EditorQueries as R, EditorQuery as S, EditorQueryResults as T, EditorReviewHits as U, EditorSelection as V, EditorSnapshot as W, FontFailedDiagnostic as X, FormatPainterLevel as Y, FormatPainterMode as Z, FormatPainterSurfaceState as _, EditorDiagnosticKind as a, HeaderFooterSlotArgs as a0, HeaderFooterState as a1, HighlightHit as a2, HighlightOptions as a3, HighlightRange as a4, HighlightRect as a5, HighlightResult as a6, HistoryDiagnosticEvent as a7, HyperlinkInfo as a8, ImageContext as a9, SetReviewChangesAuthorOptions as aA, TableBorderEdgeTarget as aB, TableBorderSpec as aC, TableBorderStyle as aD, TableBorderTarget as aE, TableCellVerticalAlignment as aF, TableColumnDividerResizeTarget as aG, TableColumnOccurrenceTarget as aH, TableContext as aI, TableInteractionLabelKey as aJ, TableRightEdgeResizeTarget as aK, TableRowOccurrenceTarget as aL, TextMatch as aM, TimingSummary as aN, TrackedChangeFilterMode as aO, TrackedChangePredicate as aP, ZoomFitTarget as aQ, ZoomMode as aR, ImageCropPermille as aS, ImageCropPercent as aa, NoteKind as ab, NotePropertiesSide as ac, NotePropertiesState as ad, PageSetup as ae, PerformanceDiagnostic as af, ResolveReviewChangesOptions as ag, ResolvedNoteNumbering as ah, ReviewActivationOptions as ai, ReviewChangesAttribution as aj, ReviewChangesResolvedEvent as ak, ReviewCommentPlacement as al, ReviewCustomPlacement as am, ReviewItemHit as an, ReviewItemPlacement as ao, ReviewItemPlacementBase as ap, ReviewItemQuery as aq, ReviewItemRevealEvent as ar, ReviewItemRevealSource as as, ReviewRevisionPlacement as at, ReviewSkippedDiagnostic as au, ScrollPlacement as av, ScrollToAnchorOptions as aw, SelectedImageState as ax, SessionActivity as ay, SessionDiagnostic as az, EditorCommand as b, AnchorHighlightOptions as c, AuthoredNoteNumbering as d, BookmarkStory as e, BookmarkSummary as f, ClearAnchorHighlightOptions as g, CollaborationParticipantsDiagnostic as h, CollaborationStatusDiagnostic as i, CustomNodeDiagnosticEvent as j, DiagnosticBase as k, DiagnosticFailureDetail as l, DocumentChange as m, DocumentEditingMode as n, DocumentHandle as o, DocumentOpenDiagnostic as p, DocumentOpenFailure as q, DocumentOpenFailureReason as r, DocumentSaveDiagnostic as s, DocumentShape as t, DocumentSource as u, EditRejectedDiagnostic as v, EditRejectionOrigin as w, Editor as x, EditorAnchorNavigation as y, EditorBookmarkCommands as z };

package/dist/{editor-scope-B3L-1ALc.d.ts → editor-scope-CA6egMaK.d.ts}

@@ -66,7 +66,11 @@ type EditorScope = {
     drawingNodeId: string;
     /** The paragraph that anchors that drawing. */
     hostParagraphId: string;
-    /** Furniture or note story that owns this frame. Absence means the body story. */
+    /**
+     * Furniture or note story that owns this frame. Absence means the body story. Entering a
+     * frame owned by a header or footer opens that story around it; a note-owned frame cannot
+     * be entered.
+     */
     owner?: {
         kind: 'headerFooter';
         rId: string;