wordinweb 0.2.5 → 0.3.0

package/dist/{index-CGp6gVjn.d.ts → index-C_oyKJu0.d.ts}

@@ -123,10 +123,21 @@ interface RunProps {
     raise?: number;
     /** w:outline — hollow stroked glyphs. */
     outline?: boolean;
+    /** w14:textOutline — glyph outline stroke (WordArt gallery styles). */
+    textOutline?: {
+        color: string;
+        width: number;
+    };
+    /** w:shadow / w14:shadow — offset glyph shadow. */
+    textShadow?: boolean;
     /** w:emboss / w:imprint — Word triple-draws offset copies. */
     emboss?: boolean;
     imprint?: boolean;
     vanish?: boolean;
+    /** w:rPr w:snapToGrid: whether this run participates in the section's
+     * docGrid. A line whose runs ALL declare 0 lays off the grid (see
+     * finishLine); ParaProps.snapToGrid covers the whole paragraph. */
+    snapToGrid?: boolean;
     /** Character style id (w:rStyle). */
     styleId?: string;
     lang?: string;
@@ -308,7 +319,7 @@ interface EmbeddedObjectReference {
     progId: string;
 }
 /** OMML equation node (subset: runs, scripts, fractions, radicals). */
-type MathNode = {
+type MathNode = ({
     t: "run";
     text: string;
     normal?: boolean;
@@ -377,6 +388,15 @@ type MathNode = {
     pos: "low" | "upp";
     e: MathNode[];
     lim: MathNode[];
+}) & {
+    /**
+     * The OMML element this node was read from. Only the math EDITOR's reader
+     * (edit/math.ts) sets it; the renderer's parser leaves it undefined. Editing
+     * re-emits through it, so the properties the linear syntax does not spell
+     * out — run fonts, m:ctrlPr, a matrix's column specs, an n-ary's limit
+     * placement — survive a text edit instead of being dropped.
+     */
+    src?: XmlElement;
 };
 interface MathContent {
     kind: "math";
@@ -405,6 +425,11 @@ interface FieldContent {
      * (in the fldChar begin's w:ffData). Its presence makes the rendered ballot
      * box a click-to-toggle target; the glyph derives from its w:checked child. */
     checkbox?: XmlElement;
+    /** The field's own XML: the `w:fldSimple`, or the `w:fldChar` begin of a
+     * complex field. The update pass (edit/update-fields.ts) writes a recomputed
+     * result back through it — layout resolves fields from this model, so
+     * without the link the computed value has nowhere to land in the file. */
+    src?: XmlElement;
 }
 /** What an anchored shape's coordinates are measured from. "char" (relH=
  * "character") measures from the anchor run's pen position; "line" (relV=
@@ -420,8 +445,11 @@ interface ShapeLine {
     color: string;
     /** Stroke weight px. */
     weight: number;
+    style?: "single" | "dotted" | "dashed";
     hRel: AnchorRel;
     vRel: AnchorRel;
+    /** Source VML v:line for selection and save-back editing. */
+    src?: XmlElement;
 }
 interface ShapeTextbox {
     type: "textbox";
@@ -477,12 +505,18 @@ interface ShapeTextbox {
         r: number;
         b: number;
     };
-    /** Non-rect preset geometry: paint this outline (in a viewW x viewH space
-     * scaled to the shape box) instead of a rectangle. */
+    /** Non-rect preset geometry: paint these outline paths (in a viewW x viewH
+     * space scaled to the shape box) instead of a rectangle. Each path carries
+     * its resolved fill colour (undefined = unfilled) and whether the shape's
+     * stroke applies to it. */
     geom?: {
-        d: string;
         viewW: number;
         viewH: number;
+        paths: {
+            d: string;
+            fill?: string;
+            stroke: boolean;
+        }[];
     };
     /** bodyPr a:noAutofit: the box does NOT grow with its text — Word hides
      * whole lines that stick out past the shape bottom (phase23 p12 ovals:
@@ -492,6 +526,13 @@ interface ShapeTextbox {
      * plus the top/bottom insets (the stored cy is only Word's last cached
      * value). Width is fixed. */
     autofitHeight?: boolean;
+    /** bodyPr a:normAutofit — "shrink text on overflow". The mode is recorded
+     * because the fit report names it, NOT because it changes the layout:
+     * probe-shapefit measured fourteen normAutofit shapes through desktop Word
+     * and every one paints at its authored size and clips at the box bottom,
+     * exactly like a:noAutofit. `clipText` is set alongside this and is what the
+     * layout reads. */
+    shrinkText?: boolean;
     /** Linked text-box chain id (wps:txbx/@id or wps:linkedTxbx/@id): boxes with
      * the same id form one story. The seq-0 box (wps:txbx) holds the content;
      * later boxes (wps:linkedTxbx, chainSeq>0) are empty sinks that continue the
@@ -507,6 +548,10 @@ interface ShapeTextbox {
     textboxStory?: boolean;
     /** DrawingML WordArt, including the identity textNoShape preset. */
     wordArt?: boolean;
+    /** WordArt glyph fill from w14:textFill or the fallback run color. */
+    wordArtFill?: string;
+    /** WordArt glyph alpha, 0..1. */
+    wordArtOpacity?: number;
     /** bodyPr a:prstTxWarp preset name (textArchUp, textWave1, textChevron,
      * textCirclePour, …): the shape's text is bent onto the preset's envelope
      * rather than flowed as ordinary lines. "textNoShape" (no warp) is dropped. */
@@ -564,6 +609,16 @@ interface ShapeArt {
     behind?: boolean;
     /** a:xfrm rotation, degrees clockwise. */
     rotation?: number;
+    /** wp:wrapSquare/.../wrapTopAndBottom on the anchor. Only FRAME stories
+     * (header/footer/cell) act on it - body flow ignores art wrap, as before. */
+    wrap?: WrapMode;
+    /** wp:anchor dist* in px, used with `wrap`. */
+    dist?: {
+        t: number;
+        b: number;
+        l: number;
+        r: number;
+    };
     lines: DrawingLine[];
     images: DrawingImage[];
     paths: DrawingPath[];
@@ -697,16 +752,91 @@ interface DrawingContent {
      * SmartArt cached-drawing shapes). Painted above lines/paths. */
     texts?: DrawingTextShape[];
 }
-type ChartType = "column" | "bar" | "line" | "pie";
+/** The c:chartSpace plot kinds the renderer paints. Anything else (3-D, radar,
+ * surface, stock, bubble) parses with `unsupported` set instead. */
+type ChartType = "column" | "bar" | "line" | "pie" | "doughnut" | "area" | "scatter";
 interface ChartSeries {
     name: string;
     values: number[];
+    /** c:xVal of a scatter series. Every other type shares one category axis,
+     * so only scatter carries per-series x values. */
+    xValues?: number[];
+    /** Explicit series fill/line from c:spPr, overriding the palette slot. */
+    color?: string;
+    /** Explicit c:dPt fills, keyed by point index (pie slices, single bars). */
+    pointColors?: Record<number, string>;
+    /** c:smooth — draw the line series through a spline instead of segments. */
+    smooth?: boolean;
+    /** c:spPr/a:ln/@w, in px. A line or scatter series says here how heavy its
+     * stroke is; a scatter series, whose stroke is optional, says it has one. */
+    lineWidth?: number;
+    /** c:marker/c:symbol, an ST_MarkerStyle name. "none" draws no marker, and a
+     * name with no shape behind it takes the series' slot in Word's sequence. */
+    markerSymbol?: string;
+    /** c:marker/c:size, the width across the marker in px. */
+    markerSize?: number;
+}
+type ChartTickMark = "none" | "in" | "out" | "cross";
+/** One axis of a 2-D chart (c:catAx/c:valAx/c:dateAx). */
+interface ChartAxis {
+    /** c:delete val="1": Word draws no line, ticks or labels for the axis. */
+    hidden?: boolean;
+    /** A c:majorGridlines child is present. */
+    gridlines?: boolean;
+    /** c:numFmt formatCode applied to the tick labels, e.g. "0.0%". */
+    format?: string;
+    title?: string;
+    /** c:scaling overrides of the automatic scale. */
+    min?: number;
+    max?: number;
+    majorUnit?: number;
+    /** c:scaling/c:orientation val="maxMin". */
+    reversed?: boolean;
+    /** c:majorTickMark / c:minorTickMark. The schema default is "out" for major
+     * and "none" for minor; Word writes both explicitly. */
+    majorTick?: ChartTickMark;
+    minorTick?: ChartTickMark;
+    /** c:tickLblPos val="none" keeps the axis but drops its labels. */
+    labels?: boolean;
+    /** c:crossBetween on a value axis, which decides where the category axis puts
+     * its points: "between" insets them by half a category (Word's choice for
+     * bar and column), "midCat" seats the first and last on the plot's edges
+     * (Word's choice for line and area). */
+    crossBetween?: "between" | "midCat";
 }
 interface ChartData {
     type: ChartType;
+    /** Local name of a plot the renderer does not paint (bar3DChart, radarChart,
+     * …). When set, `type` is a placeholder and the renderer draws a labeled box
+     * rather than pretending the data is a column chart. */
+    unsupported?: string;
     title?: string;
     categories: string[];
     series: ChartSeries[];
+    /** c:grouping — how bar/column/area series stack. */
+    grouping?: "clustered" | "stacked" | "percentStacked";
+    /** Legend edge. Absent when the chart has no c:legend. */
+    legend?: "l" | "r" | "t" | "b" | "tr";
+    /** c:dLbls showVal on the plot or on every series. */
+    dataLabels?: boolean;
+    /** c:varyColors — give each point of a single series its own palette slot. */
+    varyColors?: boolean;
+    categoryAxis?: ChartAxis;
+    valueAxis?: ChartAxis;
+    /** c:holeSize percent of a doughnut (Word's default is 75). */
+    holeSize?: number;
+    /** c:gapWidth percent between bar/column categories (Word's default is 150). */
+    gapWidth?: number;
+    /** c:overlap percent between bars of one category (Word: -27 clustered,
+     * 100 stacked). */
+    overlap?: number;
+    /** c:marker val="1" on a line chart: draw a point marker at each value. */
+    markers?: boolean;
+    /** Font size in px from c:title//a:defRPr@sz. Word's default title is 14pt. */
+    titleSize?: number;
+    /** Font size in px from c:txPr//a:defRPr@sz, the chart-wide text size. Word's
+     * default for axis labels, legend entries and data labels is 9pt. */
+    textSize?: number;
 }
 type SmartArtLayout = "process" | "cycle" | "hierarchy" | "list";
 interface SmartArtData {
@@ -992,7 +1122,10 @@ interface SectionProps {
         right?: Border;
         offsetFrom: "text" | "page";
     };
-    /** w:lnNumType: margin line numbering. distance px from the text edge. */
+    /** w:lnNumType: margin line numbering. distance px from the text edge.
+     * start is the raw w:start OFFSET (0 when the attribute is absent, its
+     * literal value otherwise) added to the running per-line count — see
+     * parse/section.ts for why an absent attribute isn't just "start 1". */
     lineNumbering?: {
         countBy: number;
         start: number;
@@ -1004,6 +1137,16 @@ interface SectionProps {
     footnoteNumStart?: number;
     endnoteNumFmt?: string;
     endnoteNumStart?: number;
+    /** w:numRestart: when the mark counter resets. Absent means "continuous"
+     * (the whole document shares one counter — this engine's only honored
+     * value; eachSect/eachPage are round-trip preserved but not laid out). */
+    footnoteNumRestart?: "continuous" | "eachSect" | "eachPage";
+    endnoteNumRestart?: "continuous" | "eachSect" | "eachPage";
+    /** w:pos: where the note text is placed. Round-trip preserved only — the
+     * layout always places footnotes at the page bottom and endnotes at the
+     * document end, regardless of this value. */
+    footnotePos?: "pageBottom" | "beneathText";
+    endnotePos?: "sectEnd" | "docEnd";
     /** w:textDirection tbRl: the whole section flows as East-Asian vertical
      * writing — lines run top-to-bottom, progressing right-to-left. */
     textDirection?: "tbRl";
@@ -1025,6 +1168,10 @@ interface DocComment {
     paraId?: string;
     /** Parent comment id when this comment is a reply (commentsExtended). */
     parentId?: string;
+    /** Thread resolved (w15:commentEx w15:done="1" — the [MS-DOCX] CT_CommentEx
+     * extension; ECMA-376 itself has no resolved state). Meaningful on the
+     * thread parent; Word grays the whole thread from the parent's flag. */
+    resolved?: boolean;
 }
 interface HeaderFooter {
     blocks: Block[];
@@ -1146,10 +1293,10 @@ declare class Package {
  * the table is keyed by element identity and in-place XML mutation preserves
  * identity across `refresh()`.
  */
-type StableId$1 = number;
+type StableId$2 = number;
 interface EncodedCaret {
-    blockId: StableId$1;
-    runId: StableId$1;
+    blockId: StableId$2;
+    runId: StableId$2;
     /** Offset in the run's WIRE space: cumulative through the run's inline
      * content in document order, where each w:t contributes its text length
      * and each inline separator (w:tab / w:br / w:cr) contributes ONE unit.
@@ -1193,14 +1340,21 @@ declare class StableIds {
     /** Explicitly assign an id to a newly created node. Local edits allocate
      * (`assign(el)`); applying a replicated edit installs the carried value
      * (`assign(el, carriedId)`). Carried ids must not collide. */
-    assign(el: XmlElement, id?: StableId$1): StableId$1;
+    assign(el: XmlElement, id?: StableId$2): StableId$2;
     /** Force `el` to carry `id`, replacing any id it already has (e.g. one
      * auto-assigned by a refresh() before a carried id could be installed).
      * The previous id is retired. Throws if `id` is held by a different element. */
-    reassign(el: XmlElement, id: StableId$1): void;
+    reassign(el: XmlElement, id: StableId$2): void;
+    /** Drop an element's mapping entirely; its id retires (never reused —
+     * `next` stays monotonic). Used before carried-id assignment: a refresh
+     * inside a mutation auto-assigns sequential ids to the nodes it created,
+     * and one of those autos can equal a LATER id of the same carried batch,
+     * which would make reassign throw on a perfectly good intent. No-op for an
+     * unmapped element. */
+    unassign(el: XmlElement): void;
     private install;
-    idOf(el: XmlElement): StableId$1 | undefined;
-    elOf(id: StableId$1): XmlElement | undefined;
+    idOf(el: XmlElement): StableId$2 | undefined;
+    elOf(id: StableId$2): XmlElement | undefined;
     /** Drop mappings for elements no longer reachable from the given roots
      * (deleted content). Keeps the table from growing across long sessions.
      * Ids of dropped elements are retired, never reused. */
@@ -1210,10 +1364,10 @@ declare class StableIds {
      * the tree: `pairs` maps originals→clones (as produced by walking original
      * and cloned roots in step). Used by the reconciliation snapshot (plan
      * doc 03) so a restore re-keys the table to the restored elements. */
-    captureForClone(originalToClone: Map<XmlElement, XmlElement>): Map<StableId$1, XmlElement>;
+    captureForClone(originalToClone: Map<XmlElement, XmlElement>): Map<StableId$2, XmlElement>;
     /** Replace the table wholesale from a captured mapping (restore path). */
-    restore(fromCapture: Map<StableId$1, XmlElement>, nextId: StableId$1): void;
-    nextId(): StableId$1;
+    restore(fromCapture: Map<StableId$2, XmlElement>, nextId: StableId$2): void;
+    nextId(): StableId$2;
     /**
      * Export the table as `(id, path)` pairs, where a path is the structural
      * location of the id'd element within the given roots: `[rootIndex,
@@ -1224,14 +1378,14 @@ declare class StableIds {
      * consistently.
      */
     exportSidecar(roots: XmlElement[]): {
-        next: StableId$1;
-        entries: [StableId$1, number[]][];
+        next: StableId$2;
+        entries: [StableId$2, number[]][];
     };
     /** Rebuild the table from a sidecar against freshly parsed roots (the
      * snapshot the sidecar was exported from). Replaces any current mappings. */
     importSidecar(roots: XmlElement[], sidecar: {
-        next: StableId$1;
-        entries: [StableId$1, number[]][];
+        next: StableId$2;
+        entries: [StableId$2, number[]][];
     }): void;
     /** Encode a caret as wire-stable addresses. `t` is the w:t (or other text
      * holder) the caret sits in; the run is its nearest tracked ancestor run,
@@ -1259,6 +1413,8 @@ interface Relationship {
 }
 type Relationships = Map<string, Relationship>;
 
+/** The two note parts a document can carry — see notePartsHolding. */
+type NotePart = "footnotes" | "endnotes";
 /**
  * A fully parsed .docx: sections of blocks, styles, numbering, theme, and
  * header/footer parts, with helpers to resolve effective formatting.
@@ -1279,7 +1435,7 @@ declare class DocxDocument {
     /** Header/footer parts keyed by relationship id from document.xml.rels. */
     readonly headers: Map<string, HeaderFooter>;
     readonly footers: Map<string, HeaderFooter>;
-    /** Note content by note id (render-only; sources stripped). */
+    /** Note content by note id. */
     readonly footnotes: Map<number, Block[]>;
     readonly endnotes: Map<number, Block[]>;
     /** The separator paragraph controls the gap between its rule and the first
@@ -1292,11 +1448,23 @@ declare class DocxDocument {
     readonly documentRels: Relationships;
     /** settings.xml w:evenAndOddHeaders — enables the "even" header/footer variants. */
     readonly evenAndOddHeaders: boolean;
+    /** settings.xml w:autoHyphenation (§17.15.1.10). This engine's layout does
+     * not hyphenate automatically — the setting is round-trip state that
+     * governs Word's own rendering of the document. */
+    readonly autoHyphenation: boolean;
+    /** settings.xml w:hyphenationZone/@w:val in twips (§17.15.1.53); null when
+     * the document does not declare one (Word defaults to 360 = 0.25"). */
+    readonly hyphenationZoneTwips: number | null;
+    /** settings.xml w:doNotHyphenateCaps (§17.15.1.41). */
+    readonly doNotHyphenateCaps: boolean;
     /** settings.xml w:mirrorMargins — facing-page (book fold) margins: even
      * (verso) pages swap the left/right margins and place the gutter on the
      * inside (right) edge so the binding margin stays on the inner side of
      * each spread. */
     readonly mirrorMargins: boolean;
+    /** settings.xml w:compat w:suppressTopSpacing: the first line of a page
+     * takes its character height, not its authored (exact) line spacing. */
+    readonly suppressTopSpacing: boolean;
     /** settings.xml w:defaultTabStop in px (Word default 0.5"). */
     readonly defaultTabStop: number;
     /** settings.xml w:compat compatibilityMode (12=Word2007, 14=Word2010,
@@ -1305,6 +1473,12 @@ declare class DocxDocument {
      * it (nccih: a Heading1/2 after a page break sits at margin + its before).
      * Absent → treated as current (15). */
     readonly compatibilityMode: number;
+    /** The compatibilityMode settings.xml actually declares, or undefined when
+     * the setting (or settings.xml itself) is missing. `compatibilityMode`
+     * defaults an omitted value to 15, but a table's percentage width needs the
+     * distinction: Word fits the horizontal cell margins inside the table box at
+     * an EXPLICIT 15 and adds them around it when the setting is absent. */
+    readonly declaredCompatibilityMode: number | undefined;
     /** settings.xml m:mathPr/m:defJc — default justification for display
      * equations whose m:oMathParaPr carries no explicit m:jc (Word default:
      * centerGroup — the rows of a broken equation left-align to each other and
@@ -1340,6 +1514,31 @@ declare class DocxDocument {
     private footnotesRoot;
     private footnotesDirty;
     private footnotesRels;
+    /** Retained endnotes.xml tree (endnote insertion + save round-trip). */
+    private endnotesPart;
+    private endnotesRoot;
+    private endnotesDirty;
+    private endnotesRels;
+    /** Retained bibliography sources part (the customXml b:Sources data of
+     * ECMA-376 §22.6), when present. Source-management editing mutates this
+     * tree in place; a document with none gets the part on first create. */
+    private sourcesPart;
+    private sourcesRoot;
+    private sourcesDirty;
+    /** Companion parts written when THIS session created the sources part
+     * (itemProps + its .rels); an arriving part keeps its own companions. */
+    private sourcesAux;
+    /** Retained glossary document part (word/glossary/document.xml, ECMA-376
+     * §17.12: glossaryDocument/docParts/docPart — Word's Quick Parts / Building
+     * Blocks store), when present. Building-block editing mutates this tree in
+     * place; a document with none gets the part on first create. Unlike
+     * headers/footers, a docPart's body is never caret-editable — it is only
+     * ever cloned INTO the main document body (insertBuildingBlock) or captured
+     * OUT of a selection (createBuildingBlock) — so this part carries no
+     * editableRoots()/stable-id integration of its own. */
+    private glossaryPart;
+    private glossaryRoot;
+    private glossaryDirty;
     /** Serialize retained optional parts only once actually mutated, keeping
      * untouched parts byte-identical through save(). */
     private stylesDirty;
@@ -1462,12 +1661,80 @@ declare class DocxDocument {
      */
     numberingTree(create?: boolean): XmlElement | null;
     markNumberingChanged(): void;
+    /** Retained styles.xml tree, or null when the package has no styles part.
+     * Style-definition editing mutates this tree in place. */
+    stylesTree(): XmlElement | null;
+    /**
+     * Re-resolve the style cascade after a definition changed in place.
+     *
+     * A style definition is not addressed by any paragraph's XML, so mutating one
+     * changes how EVERY paragraph resolves without changing a single w:p. Two
+     * things therefore have to be reset by hand: the parsed Styles map every
+     * effective-props call reads, and layoutGlobalSig, which is what makes the
+     * line-break cache treat cached breaks for unchanged paragraph XML as stale.
+     */
+    markStylesChanged(): void;
+    /**
+     * Retained bibliography sources tree (b:Sources), or null when the package
+     * has no sources part. With create=true, a missing part is created and
+     * registered the way Word lays one out (ECMA-376 §22.6 + Part 2 custom XML
+     * data storage): the data itself as customXml/itemN.xml, a datastore-item
+     * properties part (itemPropsN.xml) declaring the Bibliography schema URI as
+     * its schemaRef, a .rels from the item to its properties, a customXml
+     * relationship from the main document part, and the content-type overrides.
+     *
+     * DETERMINISM. Everything written is a pure function of the package —
+     * the item number is the first free one, and the datastore itemID GUID is a
+     * fixed constant rather than Word's random draw — so two replicas creating
+     * the part through the same sequenced operation write identical bytes.
+     */
+    sourcesTree(create?: boolean): XmlElement | null;
+    /**
+     * Invalidate what a sources-part edit changes downstream. Like
+     * markStylesChanged, the part is addressed by no paragraph's XML: a
+     * CITATION field's painted text resolves from the part at layout, so the
+     * layout signature has to drop for unchanged paragraph XML to repaint.
+     */
+    markSourcesChanged(): void;
+    /**
+     * Retained glossary document tree (w:glossaryDocument), or null when the
+     * package has no glossary part. With create=true, a missing part is
+     * created and registered — package part, document relationship,
+     * content-type override — the createNotesPart discipline.
+     *
+     * The glossary part gets none of the sources part's companion machinery
+     * (no datastore item, no random itemID): it is an ordinary WordprocessingML
+     * part named by relationship TYPE, so creation just mints an empty
+     * `<w:glossaryDocument><w:docParts/></w:glossaryDocument>` and wires it up
+     * — closer to createNotesPart than to sourcesTree. A real Word-authored
+     * glossary part additionally carries its own styles.xml / settings.xml /
+     * fontTable.xml; this engine writes none of them, because a docPart's
+     * content is read once — to clone its blocks into the main document, where
+     * they resolve styles against the MAIN document's own styles.xml — and is
+     * never laid out or rendered as its own story the way a header/footer is.
+     *
+     * DETERMINISM: nothing here depends on Word's random draws (no GUID is
+     * written at all — w:docPartPr/w:guid is optional and this engine never
+     * reads it back), so two replicas creating the part through the same
+     * sequenced operation write identical bytes.
+     */
+    glossaryTree(create?: boolean): XmlElement | null;
+    /** Invalidate what a glossary-part edit changes: nothing downstream, since
+     * createBuildingBlock/deleteBuildingBlock touch only the glossary tree, not
+     * any paragraph the layout reads. Exists for the same "explicit intent to
+     * persist" reason markSourcesChanged does. */
+    markGlossaryChanged(): void;
     /**
      * Retained footnotes tree. With create=true, a missing footnotes.xml part
      * is created and registered (with Word's required separator footnotes) so
      * inserted footnotes serialize and round-trip.
      */
     footnotesTree(create?: boolean): XmlElement | null;
+    /** Retained endnotes tree; the endnote mirror of footnotesTree. */
+    endnotesTree(create?: boolean): XmlElement | null;
+    /** Register a new notes part in document.xml.rels and [Content_Types].xml,
+     * and return the part path. The tree itself is the caller's. */
+    private createNotesPart;
     /**
      * Create an empty header/footer part (with a default-type reference in
      * every sectPr) when the document has none - Word does this implicitly the
@@ -1482,7 +1749,29 @@ declare class DocxDocument {
      * whether an ensureHeaderFooter intent has anything to do). */
     hasHfPart(kind: "header" | "footer"): boolean;
     ensureHfPart(kind: "header" | "footer"): XmlElement;
+    /** A w:headerReference / w:footerReference element. */
+    private hfReference;
+    /** Materialize the default body-level sectPr when the document declares no
+     * section properties at all (schema: the body's sectPr is its LAST child). */
+    private ensureBodySectPr;
+    /**
+     * Give every section a header and footer reference of the given variant
+     * type, creating one empty part per band the way Word does the first time
+     * "different first page" (type "first") or "different odd & even pages"
+     * (type "even") is enabled. Sections that already carry a reference of the
+     * type keep it — and its part's content. True when anything was added.
+     */
+    ensureHfVariantParts(type: "first" | "even"): boolean;
+    /** Create and register a new empty header/footer part — package part,
+     * document relationship, content-type override, hfParts entry — with no
+     * section references of its own; the caller decides which sectPrs point at
+     * it and with which w:type. */
+    private createHfPart;
     markFootnotesChanged(): void;
+    markEndnotesChanged(): void;
+    /** Re-derive both id -> blocks maps from the retained trees, so layout sees
+     * an inserted or edited note. */
+    private rederiveNotes;
     /** Called by comment edit commands after mutating the comments tree. */
     markCommentsChanged(): void;
     /**
@@ -1498,23 +1787,78 @@ declare class DocxDocument {
      * nearest preceding w:t.
      */
     commentAnchors(): Map<string, XmlElement[]>;
-    /** Flag the footnotes part dirty when `t` lives inside it, so save()
-     * re-serializes footnotes.xml. Called by the editor after a text edit; a
-     * no-op for body/header/footer targets. */
+    /** Flag a notes part dirty when `t` lives inside it, so save()
+     * re-serializes footnotes.xml / endnotes.xml. Called by the editor after a
+     * text edit; a no-op for body/header/footer targets. */
     markDirtyIfFootnote(t: XmlElement): void;
+    /**
+     * Which note parts hold `el` right now. An operation that DETACHES `el` —
+     * accepting or rejecting a revision, for one — has to ask BEFORE it mutates
+     * and mark the answer afterwards: a detached element belongs to no part, so
+     * a containment test run after the fact reports nothing and save() then
+     * leaves the stale footnotes.xml / endnotes.xml in the package.
+     */
+    notePartsHolding(el: XmlElement): NotePart[];
+    /** Flag the given note parts dirty, so save() re-serializes exactly those. */
+    markNotePartsChanged(parts: readonly NotePart[]): void;
     /** The mutable XML roots (document body, related modeled parts, settings).
      * settingsRoot is always second and always present so its history snapshot
      * index stays stable even when optional related roots are created later. */
     editableRoots(): XmlElement[];
+    /** CT_Settings children that precede w:mirrorMargins in the schema sequence
+     * (§17.15.1.78). Insertions go before the first child that is not a
+     * predecessor, so Word never has to repair settings.xml. */
+    private static readonly SETTINGS_BEFORE_MIRROR;
+    /** The schema predecessors of w:evenAndOddHeaders (§17.10.1): everything up
+     * to mirrorMargins, then the sequence through defaultTableStyle. */
+    private static readonly SETTINGS_BEFORE_EVEN_AND_ODD;
+    /** Set or remove one settings.xml element at its schema position. Null
+     * removes; otherwise the element is (re)inserted before the first child
+     * that is not a schema predecessor. */
+    private setSettingsElement;
+    /** Set or remove one on/off settings.xml toggle at its schema position. */
+    private setSettingsToggle;
+    /** The schema predecessors of w:autoHyphenation: everything through
+     * w:defaultTabStop (§17.15.1.78). Its cluster mates append in order. */
+    private static readonly SETTINGS_BEFORE_AUTO_HYPHENATION;
+    /**
+     * Patch the hyphenation settings (w:autoHyphenation §17.15.1.10,
+     * w:hyphenationZone §17.15.1.53, w:doNotHyphenateCaps §17.15.1.41). Each
+     * present key is written; `zoneTwips: null` removes the zone element. True
+     * when anything changed — the honest no-op a replicated document-scoped
+     * operation needs. This engine's layout does not hyphenate automatically;
+     * the settings govern Word's own rendering of the file.
+     */
+    setHyphenation(patch: {
+        auto?: boolean;
+        zoneTwips?: number | null;
+        noCaps?: boolean;
+    }): boolean;
     /** Toggle the document-global facing-page margin mode in settings.xml. */
     setMirrorMargins(enabled: boolean): void;
+    /** Toggle w:evenAndOddHeaders (§17.10.1) — the document-global switch that
+     * makes even pages use the "even" header/footer variants. */
+    setEvenAndOddHeaders(enabled: boolean): void;
+    /** Register settings.xml in document.xml.rels and [Content_Types].xml when
+     * the package was born without it (a minimal document). */
+    private registerSettingsPart;
     /**
      * Find the parent element of `target` in any modeled XML tree (document
      * body, headers, footers). Linear scan — documents are small and this only
      * runs on structural edits (Enter, paragraph merge).
      */
-    /** XML roots that can carry tracked changes: body, headers/footers, footnotes. */
+    /** The header part roots, in package order. A watermark is authored into
+     * every one of them: Word paints it on every page, and a document with a
+     * first-page or even-page header has more than one header part. */
+    headerRoots(): XmlElement[];
+    /** The footer part roots, in package order — headerRoots' counterpart, for
+     * operations that walk both bands (the page-number gallery's removal
+     * sweep). */
+    footerRoots(): XmlElement[];
+    /** XML roots that can carry tracked changes: body, headers/footers, notes. */
     revisionRoots(): XmlElement[];
+    /** Body, header/footer and note roots — every tree the caret can reach. */
+    private contentRoots;
     /**
      * Memoized child→parent links. Nothing invalidates this map — the tree is
      * spliced constantly — so every answer is RE-DERIVED before it is returned:
@@ -1561,6 +1905,27 @@ declare class DocxDocument {
     saveAsync(): Promise<Uint8Array>;
     private buildPackage;
     private buildPackageFiles;
+    /**
+     * Leave out the chart parts the document no longer references.
+     *
+     * Deleting a chart splices its w:drawing out of the story, but the chart
+     * part, its rels part, its embedded workbook, the document relationship, and
+     * the two [Content_Types].xml overrides all stay. An agent that inserts a
+     * chart, deletes it, and inserts a replacement therefore saves TWO chart
+     * parts for the one chart the document shows.
+     *
+     * The release happens here, at save time, rather than when the drawing goes,
+     * because undo restores the drawing XML — r:id and all — from a snapshot
+     * that models package parts but no relationship state. Dropping the
+     * relationship early would make undo produce a chart pointing at nothing.
+     * The live tree keeps everything; only the written bytes lose the orphans,
+     * and the saveJournal puts back the two trees this touches.
+     *
+     * Relationship ids are scoped to the part that owns the rels file, so the
+     * document body is the only place that can reference these ids, and reading
+     * it is a complete check. Headers, footers, and notes carry their own rels.
+     */
+    private dropOrphanChartParts;
     /** Fresh unique docPr id for inserted drawings. Seeded once past the
      * highest id already present in any editable root (floor 1000, matching
      * the historical seed for documents with no drawings) so a document that
@@ -1580,6 +1945,23 @@ declare class DocxDocument {
     addHyperlinkRel(url: string): string;
     /** Retarget an existing external relationship (hyperlink href edit). */
     setRelTarget(relId: string, url: string): boolean;
+    /** The relationships of the part that holds `source`: a header or footer
+     * part when the element is inside one, else the document part. */
+    private imageRelsOwner;
+    /** Add an image relationship pointing at `part`, in the relationships of
+     * whichever part holds `source`. */
+    private addImageRel;
+    /**
+     * Point a SECOND part at an image part this document already has.
+     *
+     * Word's picture watermark is ONE media part that every header part
+     * references. Registering the image again per header would put a full copy
+     * of the bytes in the package for each one — three headers, three copies of
+     * the same logo — and give the media-install path three pending parts to
+     * fill from one upload.
+     */
+    linkImageResource(part: string, source: XmlElement): string;
+    private addImageResourceAt;
     addImageResource(bytes: Uint8Array, ext: string): string;
     /** Add a GLB model part and its Office 2019 model3d relationship. */
     addModel3DResource(bytes: Uint8Array): {
@@ -1652,7 +2034,16 @@ declare class DocxDocument {
     registerPendingImage(sha: string, ext: string, meta?: {
         iv?: string;
         genesisId?: string;
-    }): string;
+    }, source?: XmlElement): string;
+    /** As registerPendingImage, and also names the part it made — what a second
+     * part needs to reach the same image through linkImageResource. */
+    registerPendingImagePart(sha: string, ext: string, meta?: {
+        iv?: string;
+        genesisId?: string;
+    }, source?: XmlElement): {
+        relId: string;
+        part: string;
+    };
     /** Install fetched bytes into a pending part (doc 05). The caller has
      * ALREADY verified the sha against the intent's declaration (the
      * reservation is the hash commitment — doc 16 §1.1); this installs and
@@ -1773,6 +2164,11 @@ interface TextItem {
     href?: string;
     /** Present for editable text (absent on numbering labels etc.). */
     src?: TextSource;
+    /** This line is one a fixed-size text box hides past its bottom edge (see
+     * LaidOutPage.hiddenText). It mounts unpainted so a caret can bind to it, so
+     * anything that draws from item geometry — selection, comment highlights —
+     * must skip it or it paints a block where there is no text. */
+    hidden?: true;
     /** Source drawing when this text belongs to an independently editable
      * text-box story. */
     textboxStory?: XmlElement;
@@ -1788,6 +2184,8 @@ interface TextItem {
      * layers in-front shapes above the text layer). */
     front?: boolean;
     z?: number;
+    /** Paint-only alpha for decorative text such as DrawingML WordArt. */
+    opacity?: number;
     /** Right-to-left run: renderer sets direction:rtl so the browser shapes and
      * orders the (Arabic/Hebrew) glyphs within the span box. */
     rtl?: boolean;
@@ -1898,6 +2296,28 @@ interface ChartItem {
     height: number;
     data: ChartData;
 }
+/** bodyPr autofit mode: how a shape reconciles its text with its box.
+ * "resizeShape" is a:spAutoFit (grow the box), "shrinkText" is a:normAutofit
+ * (scale the text down), "none" is a:noAutofit or no bodyPr autofit at all. */
+type ShapeAutofit = "none" | "resizeShape" | "shrinkText";
+/** What a text-bearing shape's laid-out text measured, beside the frame that
+ * holds it. The layout already measures the text to place it; recording the
+ * measurement here is what lets an agent see whether the text fits without
+ * re-measuring anything. */
+interface DrawingTextFit {
+    /** Widest laid line, px (the text extent, not the box). It can exceed the
+     * box's inset width by a trailing space or an unbreakable token. */
+    textW: number;
+    /** Full laid text height, px. */
+    textH: number;
+    /** The text is taller than the box's insets leave room for. Overflow is a
+     * vertical question: the text is wrapped to the box width by construction,
+     * and a token too wide to wrap spends its excess on extra LINES. */
+    overflow: boolean;
+    /** Lines the box hides because they fall past its bottom. */
+    clippedLines: number;
+    autofit: ShapeAutofit;
+}
 /** Interactive resize zone over a table boundary (column or row). */
 interface DrawingHitItem {
     kind: "drawingHit";
@@ -1931,6 +2351,9 @@ interface DrawingHitItem {
     behind?: boolean;
     /** The drawing owns an independently editable text-box story. */
     textboxStory?: boolean;
+    /** Measured text extent for a text-bearing shape (agent fit inspection).
+     * Absent on drawings that flow no text: pictures, lines, charts, WordArt. */
+    textFit?: DrawingTextFit;
     rotate?: {
         deg: number;
         ox: number;
@@ -2000,6 +2423,15 @@ interface WarpTextItem {
     italic?: boolean;
     /** CSS text color. */
     fill: string;
+    /** WordArt glyph alpha, 0..1. */
+    opacity?: number;
+    /** w14:textOutline glyph stroke. */
+    outline?: {
+        color: string;
+        width: number;
+    };
+    /** w14:shadow / w:shadow offset glyph shadow. */
+    shadow?: boolean;
     /** Preset name (textArchUp, textWave1, textChevron, textCirclePour, …). */
     warp: string;
     rotate?: {
@@ -2032,6 +2464,24 @@ interface LaidOutPage {
         colXs: number[];
         colWidths: number[];
     }>;
+    /** Lines a fixed-size text box (a:noAutofit) hides past its bottom edge.
+     * Held apart from `items` so nothing that paints, measures, or reads the
+     * page picks them up: they exist only so a caret that lands in the hidden
+     * part of a text-box story still has a place to be. */
+    hiddenText?: TextItem[];
+}
+/** Internal page-model window used by the DOM virtualizer. */
+interface LayoutWindow {
+    /** Ensure that each requested page has a complete positioned item model. */
+    materialize(pageIndexes: Iterable<number>): void;
+    /** Release positioned items outside the requested page window. */
+    releaseExcept(pageIndexes: Iterable<number>): void;
+    /** Return the pages whose positioned items are retained. */
+    retainedPages(): Set<number>;
+}
+interface LayoutFontSample {
+    font: FontSpec;
+    text: string;
 }
 interface LayoutResult {
     pages: LaidOutPage[];
@@ -2050,6 +2500,12 @@ interface LayoutResult {
     /** Opaque page state used to refresh headers/footers without repaginating
      * the body when their measured geometry is unchanged. */
     _hf?: unknown;
+    /** Internal positioned-model window. */
+    _window?: LayoutWindow;
+    /** Font samples collected before offscreen page items were released. */
+    _fontSamples?: LayoutFontSample[];
+    /** True when any page contains a 3D model item. */
+    _hasModel3D?: boolean;
 }
 
 interface FontMetrics {
@@ -2085,8 +2541,18 @@ interface TextMeasurer {
     } | undefined;
 }
 
+/** One mail-merge data record: column name → this record's value. The host
+ * parses the data file and hands over plain strings; the engine never learns a
+ * path, a connection string or a query. */
+type MergeRecord = Readonly<Record<string, string>>;
 interface LayoutOptions {
     measurer?: TextMeasurer;
+    /** Retain positioned items only for a viewport-sized page window. */
+    windowModel?: boolean;
+    /** Mail-merge PREVIEW: the active record's column values, substituted into
+     * MERGEFIELD fields as they are painted. Nothing is written to the document —
+     * see FieldContext.mergeField. Absent renders the «Name» placeholders. */
+    mergeRecord?: MergeRecord;
     /** Previous layout result (from an earlier layoutDocument call on the same
      * document). Enables incremental relayout: pages whose input blocks and
      * lead-in state are unchanged are reused instead of re-laid. The engine falls
@@ -2129,6 +2595,15 @@ interface RenderOptions {
     /** Called when the user submits a reply from a balloon's reply box. The
      * reply box only renders when this is provided. */
     onReplyComment?: (id: string, text: string) => void;
+    /** Called when the user resolves (true) or reopens (false) a thread from
+     * its balloon. The button only renders when this is provided. */
+    onResolveComment?: (id: string, resolved: boolean) => void;
+    /** Called when the user commits an in-balloon edit of a comment's text.
+     * Offered only on comments whose author matches `commentAuthor`. */
+    onEditComment?: (id: string, text: string) => void;
+    /** The local user's comment author name — gates the edit affordance to
+     * their own comments (Word's edit-my-comment rule). */
+    commentAuthor?: string;
 }
 interface TextBinding {
     el: HTMLElement;
@@ -2210,6 +2685,48 @@ declare function renderToDom(doc: DocxDocument, layout: LayoutResult, container:
  */
 declare function printPages(root: HTMLElement, pageWidthPx: number, pageHeightPx: number): void;
 
+/** The legacy named presets, or any DrawingML ST_ShapeType name the preset
+ * geometry table knows (isValidShapePreset). */
+type ShapePreset = "line" | "verticalLine" | "rectangle" | "roundedRectangle" | "ellipse" | "diamond" | "textBox" | (string & {});
+type WordArtPreset = "plain" | "archUp" | "archDown" | "wave" | "chevron" | "circle" | "button" | "chevronDown";
+/** A WordArt gallery style: glyph fill plus optional outline and shadow
+ * (w14:textFill / w14:textOutline / w14:shadow run effects). */
+interface WordArtStyle {
+    /** 6-hex-digit RGB, with or without "#". */
+    fill: string;
+    outline?: {
+        color: string;
+        widthPt: number;
+    };
+    shadow?: boolean;
+}
+type DrawingLineDash = "solid" | "dashed" | "dotted";
+type DrawingTool = {
+    kind?: "pen";
+    color: string;
+    width: number;
+} | {
+    kind: "highlighter";
+    color: string;
+    width: number;
+} | {
+    kind: "eraser";
+    size: number;
+} | {
+    kind: "lasso";
+};
+/** Outline/shadow for an ordinary run — Word's Home-tab "Text Effects and
+ * Typography" gallery, distinct from inserting a WordArt object. */
+interface RunTextEffectPatch {
+    outline?: {
+        color: string;
+        widthPt: number;
+    } | null;
+    shadow?: boolean;
+}
+/** bodyPr's autofit choice: grow the shape, shrink the text, or neither. */
+type DrawingTextFitMode = "none" | "resizeShape" | "shrinkText";
+
 interface RunFormatPatch {
     bold?: boolean;
     italic?: boolean;
@@ -2224,6 +2741,24 @@ interface RunFormatPatch {
     fontFamily?: string;
     /** Superscript/subscript; null returns the run to the baseline. */
     verticalAlign?: "superscript" | "subscript" | null;
+    /**
+     * Character style (w:rStyle); null removes the reference.
+     *
+     * This rides the run patch rather than taking an operation of its own
+     * because applying a character style to PART of a run splits the run — which
+     * breaks the registry's position-stable precondition, and which formatRange
+     * already handles with its carried before/middle/after piece ids.
+     */
+    characterStyleId?: string | null;
+    /**
+     * w14 outline/shadow run effects (Word's Home-tab "Text Effects and
+     * Typography" gallery) — the same vocabulary a WordArt object's text
+     * carries, applied directly to ordinary runs. null removes every w14
+     * effect, reverting to plain text. Rides the run patch rather than an
+     * operation of its own for the same reason characterStyleId does: applying
+     * it to PART of a run splits the run, which formatRange already handles.
+     */
+    textEffect?: RunTextEffectPatch | null;
     /** Remove all direct character formatting (and character style). */
     clear?: boolean;
 }
@@ -2238,175 +2773,1121 @@ interface SelectionFormat {
     highlight?: string;
     fontFamily?: string;
     verticalAlign?: "superscript" | "subscript";
+    /** The character style every selected run carries, if they agree. Null when
+     * they agree on carrying none; undefined when the selection is mixed. */
+    characterStyleId?: string | null;
 }
 
-type ShapePreset = "line" | "verticalLine" | "rectangle" | "roundedRectangle" | "ellipse" | "diamond" | "textBox";
-type WordArtPreset = "plain" | "archUp" | "archDown" | "wave" | "chevron";
-type DrawingLineDash = "solid" | "dashed" | "dotted";
-type DrawingTool = {
-    kind?: "pen";
-    color: string;
-    width: number;
-} | {
-    kind: "highlighter";
-    color: string;
-    width: number;
-} | {
-    kind: "eraser";
-    size: number;
-} | {
-    kind: "lasso";
-};
+/**
+ * Shortcuts owned by the embedding application rather than the editor — a
+ * desktop app's menu accelerators, say. A menu accelerator is consumed by the
+ * menu before the editor's keydown handler ever sees it, so the editor cannot
+ * discover these; the host injects them (HelpGuide's `hostShortcuts` prop) and
+ * the sheet becomes a reference for the whole keyboard instead of half of it.
+ */
+interface HostShortcutSection {
+    title: string;
+    items: {
+        label: string;
+        keys: string;
+        detail?: string;
+    }[];
+}
 
-interface SmartArtTextFormat {
-    fontFamily: string;
-    fontSizePt: number;
-    color: string;
-    bold: boolean;
-    italic: boolean;
-    alignment: "left" | "center" | "right";
+/**
+ * CITATION resolution: the document's bibliography sources and the simple
+ * parenthetical and bibliography-entry formats Word paints for the built-in
+ * styles.
+ *
+ * WHERE THE SOURCES LIVE. Word stores the bibliography source list as a
+ * Custom XML Data part (customXml/item1.xml in Word's own files), targeted
+ * from the main document part by a customXml relationship. The markup is the
+ * Bibliography namespace of ECMA-376 §22.6: a b:Sources root whose
+ * StyleName attribute names the selected citation style ("APA", "MLA", …)
+ * and whose b:Source children each carry a b:Tag the CITATION instruction
+ * references. The part is retained by DocxDocument (sourcesTree) so the
+ * source-management operations in edit/sources.ts can mutate it; a part
+ * those operations never touch keeps its original bytes through save().
+ *
+ * WHAT IS FORMATTED. The author-date parenthetical of the simple built-in
+ * styles: "(Author, Year)" for the APA-shaped family and "(Author)" /
+ * "(Author page)" for MLA — plus the matching bibliography ENTRY per source
+ * (bibliographyEntryText below). Full style-sheet fidelity (Word ships an
+ * XSL per style) is out of scope; a CITATION whose display this module
+ * cannot build keeps its cached result, which is Word's own rendering.
+ *
+ * It lives here, above both consumers, for the style-ref.ts reason: layout
+ * paints what the reader sees and the update pass writes what the saved file
+ * carries, and the two must not disagree about the same field.
+ */
+/** A person author, in b:NameList order. */
+interface BibliographyPerson {
+    last: string;
+    first?: string;
 }
+interface BibliographySource {
+    tag: string;
+    /** b:SourceType text ("Book", "JournalArticle", "InternetSite", "Report", …). */
+    sourceType?: string;
+    /** Person authors, in b:NameList order. */
+    authors: BibliographyPerson[];
+    /** b:Author/b:Corporate, used when there is no person author. */
+    corporate?: string;
+    title?: string;
+    year?: string;
+    /** b:JournalName (journal articles). */
+    journal?: string;
+    /** b:Publisher (books, reports). */
+    publisher?: string;
+    /** b:URL (internet sites). */
+    url?: string;
+}
+/** The citation styles the style selector offers: the two whose parenthetical
+ * and bibliography-entry rules this module models. One list, so the operation
+ * validator, the agent schema, and the toolbar cannot disagree. */
+declare const CITATION_STYLES: readonly ["APA", "MLA"];
+type CitationStyle = (typeof CITATION_STYLES)[number];
 
-type ObjectArrangeAction = "alignLeft" | "alignCenter" | "alignRight" | "alignTop" | "alignMiddle" | "alignBottom" | "rotateLeft" | "rotateRight" | "bringToFront" | "sendToBack";
-type SelectedObjectKind = "shape" | "line" | "smartArt" | "chart" | "image" | "model3d";
-type SelectedObjectCommand = "altText" | "editText" | "fill" | "outline" | "lineStyle" | "rotate" | "size" | "position" | "wrapInline" | "wrapSquare" | "wrapTopAndBottom" | "wrapFront" | "wrapBehind" | "bringForward" | "sendBackward" | "reset3d" | "delete";
-/** A local edit expressed as a replicable intent, emitted by the editor for
- * the collab layer. Positions are stable ids; the connection adds wire
- * bookkeeping (clientId/clientSeq/base). Mirrors the @wordinweb/collab intent
- * shapes without a dependency on that package. */
-type EditorIntent = {
-    kind: "insertText";
-    at: {
-        blockId: number;
-        runId: number;
-        offset: number;
-    };
-    text: string;
-    suggest?: {
-        author: string;
-        date: string;
-    };
+/** An a:srcRect crop as fractions of the source bitmap trimmed off each edge.
+ * The four together must leave a visible strip on both axes. */
+interface ImageCrop {
+    l: number;
+    t: number;
+    r: number;
+    b: number;
+}
+
+/**
+ * Numbering DEFINITION editing: the levels of an abstract numbering
+ * definition, and the per-instance overrides that restart or continue a
+ * sequence. Applying numbering to a paragraph lives in lists.ts.
+ *
+ * Two things are edited here, and the difference matters:
+ *
+ *  - A LEVEL of an abstract definition (w:abstractNum/w:lvl). Every list
+ *    instance sharing that abstract definition changes with it.
+ *  - An OVERRIDE on one instance (w:num/w:lvlOverride). Only the paragraphs
+ *    carrying that numId change, which is how one list restarts at 1 while
+ *    another sharing the same look keeps counting.
+ */
+/** The numbering formats Word offers for a level. */
+declare const NUMBER_FORMATS: readonly ["decimal", "decimalZero", "upperRoman", "lowerRoman", "upperLetter", "lowerLetter", "ordinal", "bullet", "none"];
+type NumberFormat = (typeof NUMBER_FORMATS)[number];
+/** What one level of a multilevel definition can be changed to. Undefined
+ * leaves a property alone. */
+interface LevelPatch {
+    format?: NumberFormat;
+    /** The label template: "%1." or "%1.%2." for a multilevel definition, or the
+     * bullet glyph when format is "bullet". */
+    text?: string;
+    /** The counter this level starts at. */
+    start?: number;
+    alignment?: "left" | "center" | "right";
+    /** Text indent, in points. */
+    indentLeftPt?: number;
+    /** Hanging indent of the label, in points. */
+    hangingPt?: number;
+}
+/**
+ * Word's multilevel-list gallery, expressed as per-level patches over the
+ * deep numbering ops (setNumberingLevel). One entry per preset; index = ilvl.
+ */
+declare const NUMBERING_PRESETS: Record<string, {
+    name: string;
+    levels: LevelPatch[];
+}>;
+type NumberingPresetId = keyof typeof NUMBERING_PRESETS;
+
+/**
+ * Table manipulation: add/remove rows and columns relative to the cell
+ * containing the caret. Mutates source XML; callers checkpoint + relayout.
+ *
+ * v1 scope: column operations refuse tables using gridSpan (merged cells)
+ * rather than corrupt them.
+ *
+ * SUGGESTING MODE. Every formatting operation below takes an optional
+ * RevisionMeta. With one, it records the properties it is about to replace as
+ * a tracked change — w:tblPrChange on the table, w:trPrChange on a row,
+ * w:tcPrChange on a cell — before mutating them, so a reviewer can accept or
+ * reject the change (edit/suggest.ts). Without one it mutates outright, which
+ * is what a direct edit does. STRUCTURAL operations (row and column insert and
+ * delete, merge, split) take no meta: they are not tracked, and the surfaces
+ * that enforce suggesting mode refuse them rather than apply them untracked.
+ */
+type TableOp = "rowAbove" | "rowBelow" | "deleteRow" | "colLeft" | "colRight" | "deleteCol" | "deleteTable" | "mergeRight" | "mergeDown" | "splitCell" | {
+    kind: "cellShading";
+    fill: string | null;
 } | {
-    kind: "deleteText";
-    blockId: number;
-    runId: number;
-    start: number;
-    end: number;
+    kind: "cellVAlign";
+    v: "top" | "center" | "bottom";
 } | {
-    kind: "splitParagraph";
-    at: {
-        blockId: number;
-        runId: number;
-        offset: number;
+    kind: "textWrapping";
+    wrapping: "none" | "around";
+    xPx: number;
+    yPx: number;
+};
+/** The w:val values w:tblBorders / w:tcBorders edges accept. "none" writes
+ * w:val="nil", Word's spelling for an explicitly suppressed rule. */
+type TableBorderStyle = "single" | "thick" | "double" | "dotted" | "dashed" | "dotDash" | "dotDotDash" | "thinThickSmallGap" | "triple" | "wave" | "none";
+/** One border edge. Table scope carries the four sides plus the two inside
+ * rules; cell scope carries the four sides plus the two diagonals. Neither
+ * carries the other's — the parser reads only these, so writing the rest
+ * would emit XML that renders nothing. */
+type TableBorderEdge = "top" | "bottom" | "left" | "right" | "insideH" | "insideV" | "tl2br" | "tr2bl";
+interface TableBorderSpec {
+    style: TableBorderStyle;
+    /** Stroke width in eighths of a point (w:sz). Word's UI offers 2..48. */
+    sz?: number;
+    /** "#RRGGBB", "RRGGBB", or "auto". */
+    color?: string;
+    /** Gap between rule and content, in points (w:space). */
+    space?: number;
+}
+/** Word's six "Table Style Options" checkboxes. Banding is expressed
+ * positively here and inverted into w:noHBand / w:noVBand on write — the
+ * negative spelling is a wire detail, and every caller that had to remember
+ * the inversion got it wrong at least once. */
+interface TableLookToggles {
+    firstRow: boolean;
+    lastRow: boolean;
+    firstColumn: boolean;
+    lastColumn: boolean;
+    bandedRows: boolean;
+    bandedCols: boolean;
+}
+/** Cell padding in points. An omitted side is left as it was; pass null to
+ * setTableCellMargins to drop the whole override. */
+interface CellMarginsPt {
+    top?: number;
+    left?: number;
+    bottom?: number;
+    right?: number;
+}
+/**
+ * What a Table Properties dialog needs to show the table around the caret,
+ * in points throughout so no caller handles twips.
+ *
+ * Read-only, and separate from the setters because Word's dialog PREFILLS:
+ * a width box that opens empty asks the user to retype a number the document
+ * already carries, and one that opens on a guess is worse than empty.
+ */
+interface TablePropertiesPt {
+    /** Columns in the table's grid. */
+    columnCount: number;
+    /** Grid column the caret sits in, counting gridSpans to its left. */
+    columnIdx: number;
+    /** w:tblW. An absent element IS "auto" — that is what the schema's default
+     * says — so the unit is always answered. */
+    width: {
+        unit: "pt" | "pct" | "auto";
+        value: number;
     };
-    newBlockId: number;
-    newRunId: number;
-    suggest?: {
-        author: string;
-        date: string;
+    /** Each grid column's width. */
+    columnWidthsPt: number[];
+    /** The table's default cell margins (w:tblCellMar). A side the table does
+     * not declare is ABSENT rather than zero, so a caller can tell an inherited
+     * margin from a suppressed one. */
+    cellMargins: CellMarginsPt;
+    /** Rows in the repeating header band (see setTableHeaderRows). */
+    headerRows: number;
+}
+
+/**
+ * Style DEFINITION editing: the entries in styles.xml, as opposed to applying
+ * an existing style to content (setParagraphStyle in blocks.ts, w:rStyle via
+ * the run format patch).
+ *
+ * Everything here mutates the retained styles.xml tree and then calls
+ * doc.markStylesChanged(), which re-parses the tree and drops the layout
+ * signature. That is the whole of the cascade re-resolution: a definition is
+ * not addressed by any paragraph's XML, so no w:p changes and the model
+ * re-derives effective props from the new Styles map on the next layout.
+ */
+/** The paragraph properties a style definition can carry, in points.
+ * Null clears the property; undefined leaves it alone. */
+interface StyleParaPatch {
+    alignment?: "left" | "center" | "right" | "both" | null;
+    spacingBeforePt?: number | null;
+    spacingAfterPt?: number | null;
+    /** Line spacing as a multiple of single (1.5 → w:line="360" auto). */
+    lineMultiple?: number | null;
+    indentLeftPt?: number | null;
+    indentFirstLinePt?: number | null;
+    keepNext?: boolean | null;
+    /** w:outlineLvl 0-8 — what makes a paragraph style a TOC heading level. */
+    outlineLevel?: number | null;
+}
+/** The run properties a style definition can carry. Same names as direct
+ * character formatting; `clear` has no meaning for a definition. */
+type StyleRunPatch = Omit<RunFormatPatch, "clear">;
+/** The four style kinds a w:style can declare. One list, so a validator and
+ * a schema cannot disagree about which types exist. */
+declare const STYLE_TYPES: readonly ["paragraph", "character", "table", "numbering"];
+type StyleType = (typeof STYLE_TYPES)[number];
+interface StyleSpec {
+    styleId: string;
+    type: StyleType;
+    /** The display name (w:name) — what a gallery shows. */
+    name: string;
+    /** Parent in the cascade. Defaults per type to what Word writes: Normal for
+     * a paragraph style, DefaultParagraphFont for a character style,
+     * TableNormal for a table style, and nothing for a numbering style. */
+    basedOn?: string | null;
+    /** Style applied to the NEXT paragraph after this one (paragraph only). */
+    next?: string | null;
+    /** w:qFormat — show the style in the quick-style gallery. */
+    quickStyle?: boolean;
+    /** w:uiPriority — gallery sort order. */
+    uiPriority?: number;
+    paragraph?: StyleParaPatch;
+    run?: StyleRunPatch;
+    /**
+     * PARAGRAPH styles only: also write the linked character companion Word
+     * pairs with one, so the same look can be applied to a span of text as well
+     * as to a whole paragraph. The companion takes the id `<styleId>Char` and
+     * the name `<name> Char`, copies the paragraph style's run properties, and
+     * the two point at each other through w:link.
+     *
+     * Refused when `<styleId>Char` is already taken, rather than picking
+     * another id: the companion's id has to be derivable from the paragraph
+     * style's, or two replicas applying the same operation would disagree
+     * about what to call it.
+     */
+    linked?: boolean;
+    /** TABLE styles only: the grid the style draws. Conditional formats
+     * (w:tblStylePr — banded rows, header row) are not expressible yet. */
+    table?: {
+        borders?: Partial<Record<TableBorderEdge, TableBorderSpec>>;
     };
-} | {
-    kind: "formatRun";
-    blockId: number;
-    runId: number;
-    patch: Record<string, unknown>;
-} | {
-    kind: "formatRange";
-    blockId: number;
-    runId: number;
-    start: number;
-    end: number;
-    patch: Record<string, unknown>;
-    beforeId?: number;
-    middleId: number;
-    afterId?: number;
-} | {
-    kind: "formatParagraph";
-    blockId: number;
-    align?: "left" | "center" | "right" | "justify";
-    styleId?: string | null;
-} | {
-    kind: "setListType";
-    blockId: number;
-    listKind: "bullet" | "number" | null;
-} | {
-    kind: "mergeParagraph";
-    blockId: number;
-} | {
-    kind: "suggestRevision";
-    ranges?: {
-        blockId: number;
-        runId: number;
-        start: number;
-        end: number;
-    }[];
-    marks?: {
-        blockId: number;
-        glyph: "ins" | "del";
-    }[];
-    suggest: {
-        author: string;
-        date: string;
+    /** NUMBERING styles only, and required for them: the w:numId of the
+     * numbering definition the style names. A numbering style is a NAME for a
+     * list definition, so it carries nothing else of its own. */
+    numbering?: {
+        numId: number;
     };
-} | {
-    kind: "acceptRevision";
-    index: number;
-} | {
-    kind: "rejectRevision";
-    index: number;
-} | {
-    kind: "acceptAllRevisions";
-} | {
+}
+interface StylePatch {
+    name?: string;
+    basedOn?: string | null;
+    next?: string | null;
+    quickStyle?: boolean;
+    uiPriority?: number;
+    paragraph?: StyleParaPatch;
+    run?: StyleRunPatch;
+}
+/** A gallery row: what a style chooser needs to draw one entry. */
+interface StyleGalleryEntry {
+    id: string;
+    name: string;
+    type: "paragraph" | "character" | "table" | "numbering";
+    basedOn?: string;
+    /** w:qFormat: Word shows these in the ribbon's quick-style gallery. */
+    quickStyle: boolean;
+    uiPriority?: number;
+    /** True for a style this document declares, false for a built-in offered
+     * without a definition (applying one injects the definition). */
+    defined: boolean;
+    /** Number of paragraphs or runs that reference the style. */
+    usageCount: number;
+    /** Effective run props through the style's basedOn chain — enough to paint a
+     * live preview of the entry. */
+    preview: RunProps;
+}
+
+interface Model3DRotation {
+    x: number;
+    y: number;
+    z: number;
+}
+
+/**
+ * Bibliography SOURCE editing: the b:Source entries of the customXml sources
+ * part (ECMA-376 §22.6), as opposed to citing one (insertCitationField in
+ * fields.ts) or rendering one (src/citations.ts).
+ *
+ * Everything here mutates the retained sources tree and then calls
+ * doc.markSourcesChanged() — the styles.ts discipline. The part is created on
+ * the first source (doc.sourcesTree(true)); only the sources part is written,
+ * so a package whose sources this engine never touches keeps its original
+ * bytes through save().
+ */
+/** The source kinds the manager offers, mapped to the b:SourceType values
+ * Word's own Source Manager writes. The four cover the common cases; an
+ * arriving source of any other type still renders and can be cited. */
+declare const CITATION_SOURCE_TYPES: readonly ["book", "article", "website", "report"];
+type CitationSourceType = (typeof CITATION_SOURCE_TYPES)[number];
+interface CitationSourceSpec {
+    /** Word's Source-Manager tag shape (isValidCitationTag): what a CITATION
+     * instruction references. */
+    tag: string;
+    type: CitationSourceType;
+    /** Person authors. Mutually exclusive with `corporate`. */
+    authors?: BibliographyPerson[];
+    /** Corporate author (b:Corporate). */
+    corporate?: string;
+    title?: string;
+    year?: string;
+    /** Books and reports. */
+    publisher?: string;
+    /** Journal articles (b:JournalName). */
+    journal?: string;
+    /** Internet sites. */
+    url?: string;
+}
+/** Everything but the tag, each field optional; an empty string clears the
+ * field. `authors`/`corporate` replace the whole author element. */
+type CitationSourcePatch = Partial<Omit<CitationSourceSpec, "tag">>;
+
+type ParagraphDividerStyle = "single" | "double" | "dotted" | "dashed" | "thinThickSmallGap";
+interface ParagraphDivider {
+    style: ParagraphDividerStyle;
+    color: string;
+    widthPt: number;
+    spacePt: number;
+}
+declare const PARAGRAPH_BORDER_EDGES: readonly ["top", "left", "bottom", "right", "between", "bar"];
+type ParagraphBorderEdge = (typeof PARAGRAPH_BORDER_EDGES)[number];
+interface ParagraphBordersPatch {
+    /** Edges to change: a spec writes the rule, null removes the direct edge.
+     * Absent edges are left alone. The spec vocabulary is the table border
+     * picker's (style / sz in eighths / color / space in points). */
+    borders?: Partial<Record<ParagraphBorderEdge, TableBorderSpec | null>>;
+    /** Paragraph shading fill "RRGGBB"; null removes the direct w:shd.
+     * Undefined leaves shading alone. */
+    shading?: string | null;
+}
+declare const TAB_STOP_ALIGNMENTS: readonly ["left", "center", "right", "decimal", "bar"];
+declare const TAB_STOP_LEADERS: readonly ["none", "dot", "hyphen", "underscore", "middleDot"];
+interface TabStopSpec {
+    /** Position in points from the left text edge. */
+    posPt: number;
+    align: (typeof TAB_STOP_ALIGNMENTS)[number];
+    leader: (typeof TAB_STOP_LEADERS)[number];
+}
+
+/** The cover-page design gallery. "title" is Word's plain centered title
+ * block (this engine's original single form). "banner" shades the title
+ * paragraph into a colored band — Word's "Sideline"/"Facet" family look —
+ * reusing setParagraphBorders' shading rather than inventing a second way to
+ * paint a fill. "sidebar" left-aligns the block lower on the page with a
+ * colored accent rule on the title, the same reuse for the rule itself. */
+declare const COVER_PAGE_LAYOUTS: readonly ["title", "banner", "sidebar"];
+type CoverPageLayout = (typeof COVER_PAGE_LAYOUTS)[number];
+interface CoverPageContent {
+    title: string;
+    subtitle?: string;
+    author?: string;
+    /** Defaults to "title" — the original single layout, unchanged. */
+    layout?: CoverPageLayout;
+}
+/** The w:pgNumType number formats the layout engine paints (its PAGE_FMT
+ * table); the editable subset of ST_NumberFormat (ECMA-376 §17.18.59). */
+declare const PAGE_NUMBER_FORMATS: readonly ["decimal", "lowerRoman", "upperRoman", "lowerLetter", "upperLetter"];
+type PageNumberFormat = (typeof PAGE_NUMBER_FORMATS)[number];
+interface PageNumberFormatPatch {
+    /** w:pgNumType@fmt. null removes the attribute (back to decimal). */
+    fmt?: PageNumberFormat | null;
+    /** w:pgNumType@start. null removes it (numbering continues from the
+     * previous section, the OOXML default). */
+    start?: number | null;
+}
+/** Note-mark numbering formats the layout engine paints (formatNoteMark's
+ * table): the page-number format subset plus "chicago", Word's symbol style
+ * (*, †, ‡, §) — footnotes' traditional default in some templates. */
+declare const NOTE_NUMBER_FORMATS: readonly ["decimal", "lowerRoman", "upperRoman", "lowerLetter", "upperLetter", "chicago"];
+type NoteNumberFormat = (typeof NOTE_NUMBER_FORMATS)[number];
+/** ST_RestartNumber (ECMA-376 §17.18.81): when the mark counter resets.
+ * Only "eachSect" is honored by layout (assignNoteNumbers); "continuous" is
+ * the OOXML default; "eachPage" round-trips but is not laid out — see
+ * assignNoteNumbers' comment for why. */
+declare const NOTE_RESTART_VALUES: readonly ["continuous", "eachSect", "eachPage"];
+type NoteRestart = (typeof NOTE_RESTART_VALUES)[number];
+interface FootnoteOptionsPatch {
+    /** w:footnotePr/w:numFmt@val. null removes it (back to decimal). */
+    fmt?: NoteNumberFormat | null;
+    /** w:footnotePr/w:numStart@val. null removes it (back to 1). */
+    start?: number | null;
+    /** w:footnotePr/w:numRestart@val. null removes it (back to continuous). */
+    restart?: NoteRestart | null;
+    /** w:footnotePr/w:pos@val (§17.11.21). null removes it (back to pageBottom). */
+    pos?: "pageBottom" | "beneathText" | null;
+}
+interface EndnoteOptionsPatch {
+    fmt?: NoteNumberFormat | null;
+    start?: number | null;
+    restart?: NoteRestart | null;
+    /** w:endnotePr/w:pos@val. null removes it (back to docEnd). */
+    pos?: "sectEnd" | "docEnd" | null;
+}
+/** Current w:footnotePr settings for the section governing `t`. */
+declare function footnoteOptionsAt(doc: DocxDocument, t: XmlElement): {
+    fmt: NoteNumberFormat;
+    start: number | null;
+    restart: NoteRestart;
+    pos: "pageBottom" | "beneathText";
+};
+/** Current w:endnotePr settings for the section governing `t`. */
+declare function endnoteOptionsAt(doc: DocxDocument, t: XmlElement): {
+    fmt: NoteNumberFormat;
+    start: number | null;
+    restart: NoteRestart;
+    pos: "sectEnd" | "docEnd";
+};
+interface LineNumberingPatch {
+    /** Turn margin line numbering on/off for the target section(s). */
+    enabled: boolean;
+    /** Number every Nth line (1/5/10). Default 1 when first enabled. */
+    countBy?: number;
+    /** When the count resets. Default newPage when first enabled. */
+    restart?: "continuous" | "newPage" | "newSection";
+    /** First line number. Default 1. */
+    start?: number;
+}
+
+declare const PAGE_NUMBER_POSITIONS: readonly ["top", "bottom"];
+type PageNumberGalleryPosition = (typeof PAGE_NUMBER_POSITIONS)[number];
+declare const PAGE_NUMBER_ALIGNMENTS: readonly ["left", "center", "right"];
+type PageNumberGalleryAlign = (typeof PAGE_NUMBER_ALIGNMENTS)[number];
+declare const HEADER_FOOTER_PRESETS: readonly ["blank", "centeredTitle", "titleAndDate", "threeColumn"];
+type HeaderFooterPreset = (typeof HEADER_FOOTER_PRESETS)[number];
+
+/**
+ * A native Word table of contents: a TOC field whose cached result is the
+ * entry list.
+ *
+ * WHY A FIELD AND NOT PLAIN PARAGRAPHS. Word recognises a TOC only by its
+ * field structure, and everything a user expects from one — "Update Table",
+ * the grey field shading, Ctrl-click navigation — follows from it. A pile of
+ * paragraphs that merely looks like a TOC is a document Word cannot maintain.
+ *
+ * THE STRUCTURE, as Word writes it (verified against the parity corpus's
+ * Word-authored TOCs, e.g. wild2-med-nccih-protocol.docx):
+ *
+ *   <w:p>                       first entry paragraph, pStyle TOC1
+ *     fldChar begin
+ *     instrText ` TOC \o "1-3" \h \z \u `
+ *     fldChar separate
+ *     <w:hyperlink w:anchor="_Toc…" w:history="1"> … </w:hyperlink>
+ *   </w:p>
+ *   <w:p> … </w:p>              one paragraph per further entry
+ *   <w:p> fldChar end </w:p>    closes the field
+ *
+ * The field's begin/separate live in the FIRST entry paragraph rather than in
+ * a paragraph of their own, and everything between separate and end is the
+ * cached result. Each entry is a hyperlink to the heading's `_Toc` bookmark,
+ * holding the title, a tab to a right-aligned dot-leader stop, and a PAGEREF
+ * field for the page number.
+ *
+ * HOW IT STAYS CURRENT. The entries' PAGEREF fields are ordinary complex
+ * fields, so the update pass (edit/update-fields.ts) repages the whole table
+ * with no TOC-specific code: it harvests each PAGEREF's page from a layout
+ * like any other. Only a change to the HEADING SET needs rebuildToc, which
+ * replaces the entry paragraphs outright.
+ */
+/** Levels a `\o` switch includes, e.g. [1, 3] for `\o "1-3"`. */
+type TocLevels = [number, number];
+/** The tab leaders a TOC entry can draw. One list, so a validator and a
+ * schema cannot disagree about which exist. */
+declare const TOC_LEADERS: readonly ["dot", "hyphen", "underscore", "none"];
+type TocLeader = (typeof TOC_LEADERS)[number];
+interface TocOptions {
+    /** Outline levels to include. Default [1, 3], Word's own default. */
+    levels?: TocLevels;
+    /** Tab leader between an entry's title and its page number. */
+    leader?: TocLeader;
+    /** Build a TABLE OF FIGURES instead: entries are the caption paragraphs
+     * whose SEQ field carries this label ("Figure", "Table", …), and the field
+     * instruction takes Word's `\c "Label"` switch (§17.16.5.68). */
+    captionLabel?: string;
+}
+
+/**
+ * The operation registry: ONE declaration per edit operation, read by every
+ * surface that used to carry its own hand-written copy.
+ *
+ * Adding an operation used to cost four to six coordinated edits — a core
+ * mutation, an editor dispatch, a wire intent variant in TWO packages, a
+ * transform/validate case, an agent capability row, an agent id-budget case.
+ * Each of those is guarded by a compile-time exhaustiveness gate, so nothing
+ * could silently go missing; the cost was the coordination, not the risk. A
+ * registered operation is declared once here, and the gates then consume the
+ * registry instead of a second hand-maintained list. The gates are NOT
+ * relaxed: an operation that is not registered still has to satisfy every one
+ * of them by hand.
+ *
+ * WHAT MAY BE REGISTERED. The declaration shape below is deliberately narrow.
+ * A registered operation must be:
+ *
+ *  1. ADDRESSED BY STABLE ID — a run, a paragraph, or a table cell paragraph.
+ *     The address is the whole of its collaborative "honest no-op" predicate:
+ *     when the id does not resolve in the room, the operation applies as a
+ *     clean rejection everywhere rather than mutating anything locally.
+ *  2. POSITION-STABLE — it moves no run's text, so a concurrent intent's
+ *     offsets need no remapping and its transform is identity. The
+ *     text-shaped intents (insertText, deleteText, splitParagraph,
+ *     formatRange) each carry bespoke transform logic and stay hand-written.
+ *  3. WITHOUT A WIRE INVERSE — collaborative undo skips it, which is the
+ *     status quo for every intent except the four in @wordinweb/collab's
+ *     invert.ts. The local path still takes a history checkpoint.
+ *
+ * Those three preconditions ARE the operation's undo and transform
+ * classification. They are stated once, here, instead of repeated per
+ * operation, because every operation the registry admits shares them; an
+ * operation that breaks one of them does not belong in the registry yet.
+ */
+/** A stable id from the core side table (the wire's addressing unit). */
+type StableId$1 = number;
+/**
+ * How a registered operation names its target on the wire.
+ *
+ * "document" scopes an operation to the whole document, which means it has no
+ * stable id and therefore none of the honest-no-op protection an id gives: a
+ * document address ALWAYS resolves. Such an operation has to supply its own
+ * rejection predicate from the payload — see updateFields below, whose result
+ * count must match the document's field count — and it must carry every value
+ * a replica cannot re-derive identically.
+ *
+ * "object" names a DRAWING: the stable id of the run that CARRIES it, plus an
+ * `objectIndex` into that run's content picking out which drawing it is (a run
+ * can hold several). This is the addressing every hand-written drawing intent
+ * already uses — setImageWrap, resizeDrawing — so a migrated one keeps its
+ * wire shape. The index is NOT in the table below: it is a position inside the
+ * run rather than an id of its own, which is also why it stays out of the
+ * agent-facing field list, where a raw index is forbidden. BOTH halves reject:
+ * an id nobody has and an index that no longer names a drawing are each the
+ * same clean no-op, so the honest-no-op predicate is exactly the one every
+ * addressed operation has. The index's WELL-FORMEDNESS is checked centrally
+ * (see validateRegisteredOperation) rather than by each operation, for the
+ * same reason the three preconditions above are stated once.
+ */
+type OperationAddress = "run" | "block" | "cell" | "object" | "document";
+/**
+ * Agent capability category. Mirrors @wordinweb/agent's
+ * AgentEditCapability["category"]; the agent's typed capability map is what
+ * checks the two stay equal.
+ */
+type OperationCategory = "text" | "paragraph" | "review" | "table" | "insert" | "drawing" | "math" | "document";
+/** An agent-facing payload field beyond the address reference. Order is the
+ * order the agent's JSON schema lists them in. */
+interface OperationField {
+    name: string;
+    /** Absent means required. */
+    optional?: true;
+}
+/** What an address resolved to in the document. */
+interface OperationTarget {
+    /** The addressed element: the w:r, the w:p, or the w:tbl owning the cell. */
+    el: XmlElement;
+    /** The first w:t under a run, or the first text descendant of a paragraph.
+     * Null when the target carries no text (and for cell addressing). */
+    t: XmlElement | null;
+    /** The parsed run for a run address, null for the other two. Needed by
+     * operations whose state is reachable only through the model — the checkbox
+     * marker parsing hangs on a run's content — rather than from the XML. */
+    run: Run | null;
+    /**
+     * For cell addressing: the addressed w:p itself. `el` deliberately widens a
+     * cell address to the owning w:tbl, which is what a table-scoped operation
+     * wants; a CELL-scoped one (per-edge borders, a margin override) needs the
+     * one cell the caret is in, and the paragraph is how it gets there. Null
+     * for run and block addressing, whose addressed element IS `el`.
+     */
+    cellParagraph: XmlElement | null;
+    /** For object addressing: the w:drawing (or VML shape) the address named.
+     * Null for every other address. */
+    drawing: XmlElement | null;
+}
+interface OperationContext<Payload> {
+    doc: DocxDocument;
+    target: OperationTarget;
+    payload: Payload;
+}
+/**
+ * The caller-supplied part of a wire payload: everything except the address
+ * field the dispatcher fills in and the carried ids it allocates.
+ */
+type OperationArgs<Payload> = Omit<Payload, "runId" | "blockId" | "cellParagraphId" | "nodeIds">;
+interface OperationDefinition<Kind extends string, Payload> {
+    kind: Kind;
+    address: OperationAddress;
+    /** Agent capability row: how the operation is grouped and described. */
+    category: OperationCategory;
+    description: string;
+    /** Agent-facing fields beyond the address reference, in schema order. */
+    fields: readonly OperationField[];
+    /**
+     * How many fresh stable ids the mutation needs for the id-tracked nodes it
+     * creates. Omit when it creates none. Every producer (the editor, the React
+     * host, the agent compiler) reads this instead of repeating the arithmetic.
+     */
+    nodeIds?: (args: OperationArgs<Payload>) => number;
+    /** The mutation removes id-tracked nodes, so the caller must retire their
+     * stable ids afterwards. Deletion and pruning are paired everywhere else in
+     * the apply path (mergeParagraph, removeDrawing); declaring it here keeps
+     * the pairing in the operation's single declaration. */
+    prunesIds?: true;
+    /**
+     * Reject a malformed payload before it is sequenced. Runs on both sides of
+     * the wire, so it must be a pure function of the payload.
+     */
+    validate?: (payload: Payload) => string | null;
+    /**
+     * The XML mutation, headless and from a resolved target. False means a
+     * clean no-op: the operation applied nothing and every replica agrees.
+     */
+    apply: (ctx: OperationContext<Payload>) => boolean;
+}
+/**
+ * The optional suggest payload a TRACKABLE operation carries, and the
+ * validation they share.
+ *
+ * With it the operation records what it replaced — w:pPrChange for a list
+ * marker, w:tblPrChange / w:trPrChange / w:tcPrChange for table formatting —
+ * instead of mutating outright, so a reviewer can accept or reject it. The
+ * author and date travel in the payload so every replica writes byte-identical
+ * XML; the w:id is scan-derived from identical tree state and needs no
+ * carrying. Omitting it is a direct, untracked edit.
+ */
+interface SuggestablePayload {
+    suggest?: {
+        author: string;
+        date: string;
+    };
+}
+/** A payload with no fields of its own. Not `Record<string, never>`: that
+ * carries an index signature, which would forbid the clientId/clientSeq/base
+ * bookkeeping @wordinweb/collab intersects onto every wire body. */
+type NoPayload = Record<never, never>;
+declare const OPERATIONS: readonly [OperationDefinition<"setListType", {
+    blockId: StableId$1;
+    listKind: "bullet" | "number" | null;
+    /** Additional target paragraphs beyond the addressed one, sharing its
+     * minted numbering definition. Absent = the old single-paragraph form. */
+    moreBlockIds?: StableId$1[];
+} & SuggestablePayload>, OperationDefinition<"insertTable", {
+    runId: StableId$1;
+    rows: number;
+    cols: number;
+    cells?: string[][];
+    headerRow?: boolean;
+    nodeIds: StableId$1[];
+}>, OperationDefinition<"resizeTableRow", {
+    cellParagraphId: StableId$1;
+    rowIdx: number;
+    heightPx: number;
+}>, OperationDefinition<"toggleCheckbox", {
+    runId: StableId$1;
+}>, OperationDefinition<"updateFields", {
+    results: string[];
+}>, OperationDefinition<"insertToc", {
+    runId: StableId$1;
+    levels?: TocLevels;
+    leader?: TocLeader;
+    /** With a label the field is a TABLE OF FIGURES (`TOC \c "Label"`): the
+     * entries come from the label's caption paragraphs instead of headings. */
+    captionLabel?: string;
+    entryCount: number;
+    nodeIds: StableId$1[];
+}>, OperationDefinition<"insertCaption", {
+    blockId: StableId$1;
+    label: string;
+    text?: string;
+    position?: "below" | "above";
+    nodeIds: StableId$1[];
+}>, OperationDefinition<"ensureRefBookmark", {
+    blockId: StableId$1;
+    name: string;
+}>, OperationDefinition<"insertIndexEntry", {
+    runId: StableId$1;
+    entry: string;
+    nodeIds: StableId$1[];
+}>, OperationDefinition<"insertIndex", {
+    runId: StableId$1;
+    entryCount: number;
+    nodeIds: StableId$1[];
+}>, OperationDefinition<"refreshIndex", {
+    entryCount: number;
+    nodeIds: StableId$1[];
+}>, OperationDefinition<"createStyle", {
+    style: StyleSpec;
+}>, OperationDefinition<"modifyStyle", {
+    styleId: string;
+    patch: StylePatch;
+}>, OperationDefinition<"deleteStyle", {
+    styleId: string;
+}>, OperationDefinition<"setNumberingLevel", {
+    blockId: StableId$1;
+    ilvl: number | null;
+    patch: LevelPatch;
+}>, OperationDefinition<"setNumberingRestart", {
+    blockId: StableId$1;
+    start: number | null;
+}>, OperationDefinition<"setParagraphBorders", {
+    blockId: StableId$1;
+    patch: ParagraphBordersPatch;
+} & SuggestablePayload>, OperationDefinition<"setTabStops", {
+    blockId: StableId$1;
+    stops: TabStopSpec[];
+} & SuggestablePayload>, OperationDefinition<"setTableBorders", {
+    cellParagraphId: StableId$1;
+    scope: "cell" | "table";
+    edges: TableBorderEdge[];
+    border: TableBorderSpec | null;
+} & SuggestablePayload>, OperationDefinition<"setTableStyle", {
+    cellParagraphId: StableId$1;
+    styleId: string | null;
+} & SuggestablePayload>, OperationDefinition<"setTableLook", {
+    cellParagraphId: StableId$1;
+    look: Partial<TableLookToggles>;
+} & SuggestablePayload>, OperationDefinition<"setTableWidth", {
+    cellParagraphId: StableId$1;
+    unit: "pt" | "pct" | "auto";
+    value?: number;
+} & SuggestablePayload>, OperationDefinition<"setTableColumnWidth", {
+    cellParagraphId: StableId$1;
+    colIdx: number;
+    widthPt: number;
+} & SuggestablePayload>, OperationDefinition<"setTableLayout", {
+    cellParagraphId: StableId$1;
+    layout: "fixed" | "autofit";
+    renderedWidths?: number[];
+} & SuggestablePayload>, OperationDefinition<"setTableCellMargins", {
+    cellParagraphId: StableId$1;
+    scope: "cell" | "table";
+    margins: CellMarginsPt | null;
+} & SuggestablePayload>, OperationDefinition<"setTableHeaderRows", {
+    cellParagraphId: StableId$1;
+    count: number;
+} & SuggestablePayload>, OperationDefinition<"insertTableFormula", {
+    cellParagraphId: StableId$1;
+    formula: string;
+    numFmt?: string;
+    nodeIds: StableId$1[];
+}>, OperationDefinition<"sortTableRows", {
+    cellParagraphId: StableId$1;
+    colIdx: number;
+    order: "asc" | "desc";
+    /** "kind" would collide with the intent discriminant, hence "compare". */
+    compare: "text" | "number";
+    hasHeader?: boolean;
+}>, OperationDefinition<"convertTextToTable", {
+    blockId: StableId$1;
+    moreBlockIds?: StableId$1[];
+    separator: "tab" | "comma";
+    cellCount: number;
+    nodeIds: StableId$1[];
+}>, OperationDefinition<"convertTableToText", {
+    cellParagraphId: StableId$1;
+    separator: "tab" | "comma";
+    rowCount: number;
+    nodeIds: StableId$1[];
+}>, OperationDefinition<"insertEndnote", {
+    runId: StableId$1;
+    text: string;
+    nodeIds: StableId$1[];
+}>, OperationDefinition<"setCrop", {
+    runId: StableId$1;
+    objectIndex?: number;
+    crop: ImageCrop;
+}>, OperationDefinition<"setModel3DRotation", {
+    runId: StableId$1;
+    objectIndex?: number;
+    rotation: Model3DRotation;
+}>, OperationDefinition<"setDrawingTextFit", {
+    runId: StableId$1;
+    objectIndex?: number;
+    mode: DrawingTextFitMode;
+    fontScalePct?: number;
+}>, OperationDefinition<"insertMergeField", {
+    runId: StableId$1;
+    name: string;
+    nodeIds: StableId$1[];
+}>, OperationDefinition<"insertCitation", {
+    runId: StableId$1;
+    tag: string;
+    nodeIds: StableId$1[];
+}>, OperationDefinition<"insertBibliography", {
+    runId: StableId$1;
+    entryCount: number;
+    nodeIds: StableId$1[];
+}>, OperationDefinition<"refreshBibliography", {
+    entryCount: number;
+    nodeIds: StableId$1[];
+}>, OperationDefinition<"createCitationSource", {
+    source: CitationSourceSpec;
+}>, OperationDefinition<"editCitationSource", {
+    tag: string;
+    patch: CitationSourcePatch;
+}>, OperationDefinition<"deleteCitationSource", {
+    tag: string;
+}>, OperationDefinition<"setCitationStyle", {
+    style: CitationStyle;
+}>, OperationDefinition<"createBuildingBlock", {
+    name: string;
+    category?: string;
+    blocksXml: string;
+}>, OperationDefinition<"insertBuildingBlock", {
+    name: string;
+    /** The carried-id budget, computed by the caller from the SAME already-
+     * synced glossary state the apply side reads (buildingBlockNodeCount) —
+     * the insertBibliography entryCount pattern. */
+    blockCount: number;
+}>, OperationDefinition<"deleteBuildingBlock", {
+    name: string;
+}>, OperationDefinition<"insertWatermark", {
+    text: string;
+    headerCount: number;
+    diagonal?: boolean;
+    color?: string;
+    opacity?: number;
+    nodeIds: StableId$1[];
+}>, OperationDefinition<"insertPictureWatermark", {
+    blobSha: string;
+    bytesLen: number;
+    ext: string;
+    iv?: string;
+    naturalWidthPx: number;
+    naturalHeightPx: number;
+    headerCount: number;
+    washout?: boolean;
+    nodeIds: StableId$1[];
+}>, OperationDefinition<"removeWatermark", NoPayload>, OperationDefinition<"setTitlePage", {
+    enabled: boolean;
+    nodeIds: StableId$1[];
+}>, OperationDefinition<"setEvenOddHeaders", {
+    enabled: boolean;
+    nodeIds: StableId$1[];
+}>, OperationDefinition<"setPageNumberFormat", {
+    fmt?: PageNumberFormat | null;
+    start?: number | null;
+}>, OperationDefinition<"setHyphenation", {
+    auto?: boolean;
+    zonePt?: number | null;
+    noCaps?: boolean;
+}>, OperationDefinition<"insertPageNumberPosition", {
+    position: PageNumberGalleryPosition;
+    align: PageNumberGalleryAlign;
+    nodeIds: StableId$1[];
+}>, OperationDefinition<"removePageNumbers", Record<never, never>>, OperationDefinition<"insertHeaderFooterPreset", {
+    hfKind: "header" | "footer";
+    preset: HeaderFooterPreset;
+    nodeIds: StableId$1[];
+}>, OperationDefinition<"setFootnoteOptions", {
+    fmt?: NoteNumberFormat | null;
+    start?: number | null;
+    restart?: NoteRestart | null;
+    pos?: "pageBottom" | "beneathText" | null;
+}>, OperationDefinition<"setEndnoteOptions", {
+    fmt?: NoteNumberFormat | null;
+    start?: number | null;
+    restart?: NoteRestart | null;
+    pos?: "sectEnd" | "docEnd" | null;
+}>];
+type AnyOperationDefinition = (typeof OPERATIONS)[number];
+/** Distributes: one body type per registered operation. */
+type BodyOf<D> = D extends OperationDefinition<infer Kind, infer Payload> ? {
+    kind: Kind;
+} & Payload : never;
+type RegisteredOperationKind = AnyOperationDefinition["kind"];
+/**
+ * The wire body of every registered operation. @wordinweb/collab intersects
+ * this with its IntentBase bookkeeping to form the Intent variants, so the
+ * payload is declared once and the wire shape follows.
+ */
+type RegisteredOperationBody = BodyOf<AnyOperationDefinition>;
+
+interface SmartArtTextFormat {
+    fontFamily: string;
+    fontSizePt: number;
+    color: string;
+    bold: boolean;
+    italic: boolean;
+    alignment: "left" | "center" | "right";
+}
+
+type ObjectArrangeAction = "alignLeft" | "alignCenter" | "alignRight" | "alignTop" | "alignMiddle" | "alignBottom" | "rotateLeft" | "rotateRight" | "bringToFront" | "sendToBack";
+type SelectedObjectKind = "shape" | "line" | "smartArt" | "chart" | "image" | "model3d";
+type SelectedObjectCommand = "altText" | "editText" | "fill" | "outline" | "lineStyle" | "rotate" | "size" | "position" | "crop" | "wrapInline" | "wrapSquare" | "wrapTopAndBottom" | "wrapFront" | "wrapBehind" | "autofitNone" | "autofitResizeShape" | "autofitShrinkText" | "bringForward" | "sendBackward" | "reset3d" | "delete";
+/** A local edit expressed as a replicable intent, emitted by the editor for
+ * the collab layer. Positions are stable ids; the connection adds wire
+ * bookkeeping (clientId/clientSeq/base). Mirrors the @wordinweb/collab intent
+ * shapes without a dependency on that package — except for the registered
+ * operations, whose single declaration in registry.ts feeds BOTH this type
+ * and the collab intent union, so there is nothing left to mirror. */
+type EditorIntent = RegisteredOperationBody | {
+    kind: "insertText";
+    at: {
+        blockId: number;
+        runId: number;
+        offset: number;
+    };
+    text: string;
+    suggest?: {
+        author: string;
+        date: string;
+    };
+} | {
+    kind: "insertSeparator";
+    at: {
+        blockId: number;
+        runId: number;
+        offset: number;
+    };
+    separator: "br" | "tab";
+    suggest?: {
+        author: string;
+        date: string;
+    };
+} | {
+    kind: "deleteSeparator";
+    at: {
+        blockId: number;
+        runId: number;
+        offset: number;
+    };
+    suggest?: {
+        author: string;
+        date: string;
+    };
+} | {
+    kind: "deleteText";
+    blockId: number;
+    runId: number;
+    start: number;
+    end: number;
+} | {
+    kind: "splitParagraph";
+    at: {
+        blockId: number;
+        runId: number;
+        offset: number;
+    };
+    newBlockId: number;
+    newRunId: number;
+    suggest?: {
+        author: string;
+        date: string;
+    };
+} | {
+    kind: "formatRun";
+    blockId: number;
+    runId: number;
+    patch: Record<string, unknown>;
+} | {
+    kind: "formatRange";
+    blockId: number;
+    runId: number;
+    start: number;
+    end: number;
+    patch: Record<string, unknown>;
+    beforeId?: number;
+    middleId: number;
+    afterId?: number;
+} | {
+    kind: "formatParagraph";
+    blockId: number;
+    align?: "left" | "center" | "right" | "justify";
+    styleId?: string | null;
+} | {
+    kind: "mergeParagraph";
+    blockId: number;
+} | {
+    kind: "setListLevel";
+    blockId: number;
+    delta: 1 | -1;
+} | {
+    kind: "pasteBlocks";
+    afterBlockId: number;
+    blocksXml: string;
+    nodeIds: number[];
+} | {
+    kind: "suggestRevision";
+    ranges?: {
+        blockId: number;
+        runId: number;
+        start: number;
+        end: number;
+    }[];
+    marks?: {
+        blockId: number;
+        glyph: "ins" | "del";
+    }[];
+    suggest: {
+        author: string;
+        date: string;
+    };
+} | {
+    kind: "acceptRevision";
+    index: number;
+} | {
+    kind: "rejectRevision";
+    index: number;
+} | {
+    kind: "acceptAllRevisions";
+    author?: string;
+} | {
     kind: "rejectAllRevisions";
+    author?: string;
 } | {
     kind: "setImageWrap";
     runId: number;
+    objectIndex?: number;
     mode: "inline" | "square" | "topAndBottom" | "none" | "behind";
 } | {
     kind: "setFloatingPagePosition";
     runId: number;
+    objectIndex?: number;
     xPx: number;
     yPx: number;
 } | {
     kind: "resizeDrawing";
     runId: number;
+    objectIndex?: number;
     widthPx: number;
     heightPx: number;
 } | {
     kind: "setDrawingRotation";
     runId: number;
+    objectIndex?: number;
     degrees: number;
 } | {
     kind: "setDrawingOrder";
     runId: number;
+    objectIndex?: number;
     order: "front" | "back";
 } | {
     kind: "setDrawingLineStyle";
     runId: number;
+    objectIndex?: number;
     color: string;
     widthPx: number;
     dash: "solid" | "dashed" | "dotted";
 } | {
     kind: "setImageAltText";
     runId: number;
+    objectIndex?: number;
     alt: string;
 } | {
     kind: "setDrawingFill";
     runId: number;
+    objectIndex?: number;
     color: string | null;
 } | {
     kind: "setSmartArtFill";
     runId: number;
+    objectIndex?: number;
     color: string | null;
     nodeIndex?: number;
 } | {
     kind: "setSmartArtNodeText";
     runId: number;
+    objectIndex?: number;
     index: number;
     text: string;
 } | {
     kind: "setDrawingWordArtText";
     runId: number;
+    objectIndex?: number;
     text: string;
 } | {
     kind: "insertBreak";
@@ -2419,11 +3900,6 @@ type EditorIntent = {
     boundary: number;
     deltaPx: number;
     renderedWidths?: number[];
-} | {
-    kind: "resizeTableRow";
-    cellParagraphId: number;
-    rowIdx: number;
-    heightPx: number;
 } | {
     kind: "moveTable";
     cellParagraphId: number;
@@ -2434,7 +3910,7 @@ type EditorIntent = {
 } | {
     kind: "tableOp";
     cellParagraphId: number;
-    op: {
+    op: "deleteTable" | {
         kind: "textWrapping";
         wrapping: "none" | "around";
         xPx: number;
@@ -2443,16 +3919,20 @@ type EditorIntent = {
 } | {
     kind: "removeDrawing";
     runId: number;
+    objectIndex?: number;
 } | {
     kind: "setMathLinear";
     blockId: number;
+    mathIndex: number;
     mathText: string;
 } | {
     kind: "deleteMath";
     blockId: number;
+    mathIndex: number;
 } | {
     kind: "moveMath";
     blockId: number;
+    mathIndex: number;
     at: {
         blockId: number;
         runId: number;
@@ -2465,6 +3945,76 @@ type EditorIntent = {
     nodeIds: number[];
 };
 
+/**
+ * Compare Documents — Word's "legal blackline".
+ *
+ * Produces a THIRD document: `revised`, with every difference from `original`
+ * expressed as an ordinary tracked change attributed to one reviewer. Nothing
+ * here invents a revision format; it drives the same w:ins / w:del / *PrChange
+ * vocabulary the suggesting editor writes, so the result is reviewable with
+ * the accept/reject surface that already exists, and round-trips through it:
+ *
+ *   accept every revision in the result  →  `revised`
+ *   reject every revision in the result  →  `original`
+ *
+ * (Equal modulo run coalescing — accepting a revision unwraps it without
+ * re-merging the runs it split, which is true of Word too. The gate test in
+ * test/compare-roundtrip.test.ts states the canonical form exactly.)
+ *
+ * ## Tiers, stated plainly
+ *
+ * **Text — full.** Paragraphs align by histogram diff over a text/style/
+ * numbering fingerprint, then by Dice similarity inside the gaps; matched
+ * paragraphs are diffed word by word. Insertions, deletions, paragraph splits
+ * and merges, paragraph-property and run-property changes are all expressed
+ * faithfully.
+ *
+ * **Tables — rows and cells.** A matched table pair aligns its ROWS by the
+ * same histogram pass, so a mid-table insert does not cascade. Matched rows
+ * with the same cell count recurse into each cell's paragraphs. A row that
+ * matches nothing becomes a row insertion or deletion (w:trPr/w:ins, w:trPr/
+ * w:del). A row pair whose cell COUNTS differ is coarse: the whole row is
+ * struck and the whole new row inserted.
+ *
+ * **Drawings, fields, footnote references and other non-text run content —
+ * atomic.** They match themselves byte for byte or they are a change. A
+ * changed image is a struck image plus an inserted one, never a patched one.
+ *
+ * **Paragraphs holding a hyperlink, content control, smart tag or inline
+ * math — coarse.** Word-level diffing rebuilds a paragraph's runs, and a
+ * revision wrapper may not sit around a `w:hyperlink` (the schema puts w:ins
+ * INSIDE it). Such a paragraph is never word-diffed: if it changed at all it
+ * is struck whole and the new one inserted whole, and `onNote` says so.
+ *
+ * **Headers, footers, footnotes, endnotes, comments, styles and numbering —
+ * NOT compared.** The result carries `revised`'s. `onNote` reports when
+ * `original`'s differ, so a reviewer is never told "no change" about something
+ * that was never looked at.
+ *
+ * **Moves — not detected, by architecture.** `RevisionKind` has no moveFrom /
+ * moveTo member and nothing in suggest.ts writes those elements, so a move is
+ * a new output primitive, not a smarter aligner. A moved paragraph comes out
+ * as a deletion plus an insertion, which is what Word usually produces too.
+ */
+interface CompareNote {
+    code: 
+    /** A paragraph pair too structured to word-diff; struck and reinserted whole. */
+    "coarse-paragraph"
+    /** A table row pair whose cell counts differ; struck and reinserted whole. */
+     | "coarse-row"
+    /** A block that is neither a paragraph nor a table, added or removed. */
+     | "untracked-block"
+    /** A paragraph mark whose run properties differ across the swap; see below. */
+     | "paragraph-mark-props"
+    /** A part outside the body differs and was not compared. */
+     | "part-not-compared"
+    /** The documents share no paragraph at all; one paragraph mark goes untracked. */
+     | "no-common-paragraph"
+    /** Original-only content referencing a relationship the result does not have. */
+     | "unresolved-relationship";
+    detail: string;
+}
+
 type ParagraphAlignment = "left" | "center" | "right" | "justify";
 interface PageLayoutPatch {
     /** Margins in inches. */
@@ -2495,47 +4045,58 @@ interface PageLayoutPatch {
 }
 
 /**
- * Table manipulation: add/remove rows and columns relative to the cell
- * containing the caret. Mutates source XML; callers checkpoint + relayout.
+ * Find & replace and selection text transforms. Matching runs over the
+ * parsed model — every story: the body (incl. tables), each header and
+ * footer part, and each footnote and endnote. Positions map back to source
+ * w:t elements so hits can be selected, replaced, or case-transformed.
  *
- * v1 scope: column operations refuse tables using gridSpan (merged cells)
- * rather than corrupt them.
+ * Within one story, paragraphs concatenate with "\n" standing for the
+ * paragraph mark (Word's ^p), so a query containing "\n" matches across
+ * paragraph boundaries. A match never crosses a story boundary.
  */
-type TableOp = "rowAbove" | "rowBelow" | "deleteRow" | "colLeft" | "colRight" | "deleteCol" | "deleteTable" | "mergeRight" | "mergeDown" | "splitCell" | {
-    kind: "cellShading";
-    fill: string | null;
-} | {
-    kind: "cellVAlign";
-    v: "top" | "center" | "bottom";
-} | {
-    kind: "textWrapping";
-    wrapping: "none" | "around";
-    xPx: number;
-    yPx: number;
-};
-
-type ParagraphDividerStyle = "single" | "double" | "dotted" | "dashed" | "thinThickSmallGap";
-interface ParagraphDivider {
-    style: ParagraphDividerStyle;
-    color: string;
-    widthPt: number;
-    spacePt: number;
+/** Which story a match sits in. Every header part is "header" (and every
+ * footer part "footer") regardless of which section references it. */
+type FindStory = "body" | "header" | "footer" | "footnote" | "endnote";
+interface FindOptions {
+    /** Case-sensitive matching. Default: case-insensitive. */
+    matchCase?: boolean;
+    /** Match whole words only: the characters adjacent to the hit must not be
+     * letters, digits, or underscores (Word's "Find whole words only"). */
+    wholeWord?: boolean;
+    /** Word's wildcard pattern language (the subset below). Like Word, wildcard
+     * matching is always case-sensitive and ignores wholeWord — the pattern's
+     * own `<` and `>` express word boundaries. */
+    wildcards?: boolean;
+}
+interface ReplaceAllResult {
+    total: number;
+    byStory: Partial<Record<FindStory, number>>;
+}
+/** A wire range inside one run: the shape suggestRevision and presence use. */
+interface WireRange {
+    blockId: number;
+    runId: number;
+    start: number;
+    end: number;
 }
 
-interface CoverPageContent {
-    title: string;
-    subtitle?: string;
-    author?: string;
+/** Every building block the glossary part holds, name and category, in
+ * document order — the gallery listing the toolbar groups by category. Empty
+ * when the package has no glossary part. */
+interface BuildingBlockInfo {
+    name: string;
+    category: string;
 }
-interface LineNumberingPatch {
-    /** Turn margin line numbering on/off for the target section(s). */
-    enabled: boolean;
-    /** Number every Nth line (1/5/10). Default 1 when first enabled. */
-    countBy?: number;
-    /** When the count resets. Default newPage when first enabled. */
-    restart?: "continuous" | "newPage" | "newSection";
-    /** First line number. Default 1. */
-    start?: number;
+
+interface WatermarkSpec {
+    text: string;
+    /** Word's default 45° stamp. False lays the text flat across the page. */
+    diagonal?: boolean;
+    /** Glyph colour as RRGGBB, the form every other operation uses. Defaults to
+     * Word's silver. */
+    color?: string;
+    /** v:fill opacity, 0..1. Defaults to Word's washed-out 0.5. */
+    opacity?: number;
 }
 
 interface MissingFont {
@@ -2559,6 +4120,7 @@ interface MissingFont {
  * against everything sequenced in `(base, seq)` before applying and
  * broadcasting the canonical form (doc 03).
  */
+
 type StableId = number;
 /** A caret/endpoint position within a run. */
 interface Position {
@@ -2599,10 +4161,13 @@ interface SuggestRevisionIntent extends IntentBase {
         blockId: StableId;
         glyph: "ins" | "del";
     }[];
-    suggest: {
-        author: string;
-        date: string;
-    };
+    suggest: SuggestMeta;
+}
+/** Author + date of a tracked change, generated once by the originating
+ * client so every replica writes the same w:author/w:date (rule a above). */
+interface SuggestMeta {
+    author: string;
+    date: string;
 }
 /** Insert `text` at a position. With `suggest`, the insertion is recorded as
  * a tracked change (w:ins) carrying the author + date (revision tracking /
@@ -2617,6 +4182,37 @@ interface InsertTextIntent extends IntentBase {
         date: string;
     };
 }
+/**
+ * Insert an inline separator — a soft line break (w:br, Shift+Enter) or a
+ * tab character (w:tab, Tab in a body paragraph) — at a position. The
+ * mutation splits the addressed run's w:t IN PLACE (no new run, every stable
+ * id preserved), and a separator counts ONE unit in the run's wire-offset
+ * basis (core runWireLength), so the transform is exactly an insertText of
+ * length one. With `suggest` the separator is recorded as a w:ins sibling
+ * (insertSuggestedSeparator) like a typed suggestion.
+ */
+interface InsertSeparatorIntent extends IntentBase {
+    kind: "insertSeparator";
+    at: Position;
+    separator: "br" | "tab";
+    suggest?: SuggestMeta;
+}
+/**
+ * Delete the inline separator (w:br / w:tab / w:cr) occupying wire unit
+ * [at.offset, at.offset+1) of the addressed run — insertSeparator's inverse
+ * (a separator-aware Backspace/Delete). The plain mutation removes the
+ * separator element and joins the two w:t halves its insert split, so the
+ * transform is exactly a deleteText of length one in the separator-counting
+ * wire basis. With `suggest` the separator is recorded as a tracked deletion
+ * instead (deleteSuggestedSeparator: a w:del around the separator's own run
+ * slice, the host run splitting like a text strike). A unit that no longer
+ * holds a separator (concurrent edit) is a clean no-op on every replica.
+ */
+interface DeleteSeparatorIntent extends IntentBase {
+    kind: "deleteSeparator";
+    at: Position;
+    suggest?: SuggestMeta;
+}
 /** Delete `[start, end)` characters within a single run. */
 interface DeleteTextIntent extends IntentBase {
     kind: "deleteText";
@@ -2658,6 +4254,9 @@ interface FormatRunIntent extends IntentBase {
     /** RunFormatPatch (bold/italic/underline/strike/color/…). Structural shape
      * mirrors @wordinweb/core's RunFormatPatch; carried verbatim. */
     patch: Record<string, unknown>;
+    /** Tracked-change (suggesting) metadata: the run records the properties it
+     * had in a w:rPrChange instead of losing them. Omit for a direct format. */
+    suggest?: SuggestMeta;
 }
 /**
  * Paragraph-level formatting: alignment and/or paragraph style. Block-level —
@@ -2670,17 +4269,26 @@ interface FormatParagraphIntent extends IntentBase {
     align?: "left" | "center" | "right" | "justify";
     /** Paragraph style id; null clears to Normal. Omit to leave unchanged. */
     styleId?: string | null;
+    /** Tracked-change (suggesting) metadata: the paragraph records the
+     * properties it had in a w:pPrChange. Omit for a direct format. */
+    suggest?: SuggestMeta;
 }
 /**
  * Turn a paragraph into a bullet/numbered list item, or clear its list
  * formatting (kind null). Block-level: mutates w:pPr/numbering, preserves the
  * block id, moves no text — transform identity.
+ *
+ * A multi-paragraph selection rides in ONE intent (optional `moreBlockIds`
+ * beyond the addressed paragraph): the single apply mints ONE numbering
+ * definition shared by every target, which is both Word's semantics (one
+ * continuous list) and the only convergent shape — per-paragraph intents
+ * each minted a fresh definition at apply, diverging from the originator's
+ * single shared-definition local mutation.
+ *
+ * REGISTERED: shape and wiring come from the core operation registry (see
+ * RegisteredIntent below). The alias keeps the published type name.
  */
-interface SetListTypeIntent extends IntentBase {
-    kind: "setListType";
-    blockId: StableId;
-    listKind: "bullet" | "number" | null;
-}
+type SetListTypeIntent = RegisteredIntentOf<"setListType">;
 /**
  * Format a character sub-range of a single run (plan doc 03 F3). The run is
  * split into up to three pieces — before [0,start), middle [start,end)
@@ -2701,19 +4309,23 @@ interface FormatRangeIntent extends IntentBase {
     beforeId?: StableId;
     middleId: StableId;
     afterId?: StableId;
+    /** Tracked-change (suggesting) metadata: the middle piece records the
+     * properties it had in a w:rPrChange. Omit for a direct format. */
+    suggest?: SuggestMeta;
 }
 /**
- * A table operation that does NOT create new tracked nodes (so no carried ids
- * are needed and the transform is identity): delete row/column/table, cell
- * shading, cell vertical align. The target cell is addressed by the stable id
- * of a paragraph inside it. Row/column INSERTION (which creates cells with new
- * paragraphs and runs needing carried ids) is a documented harder extension.
+ * A table operation addressed by the stable id of a paragraph inside the
+ * target cell. Every op is position-stable (no surviving run's offsets move),
+ * so the transform is identity; concurrent edits into removed cells fail
+ * cleanly at apply (retired ids). Ops that create tracked nodes (the inserts,
+ * mergeDown's fresh continuation paragraph, splitCell's new cells) take their
+ * ids from `nodeIds`; ops that remove content prune the retired ids at apply.
  */
 interface TableOpIntent extends IntentBase {
     /** Stable id of a paragraph inside the target cell. */
     cellParagraphId: StableId;
     kind: "tableOp";
-    op: "deleteRow" | "deleteCol" | "deleteTable" | "rowAbove" | "rowBelow" | "colLeft" | "colRight" | {
+    op: "deleteRow" | "deleteCol" | "deleteTable" | "rowAbove" | "rowBelow" | "colLeft" | "colRight" | "mergeRight" | "mergeDown" | "splitCell" | {
         kind: "cellShading";
         fill: string | null;
     } | {
@@ -2725,10 +4337,18 @@ interface TableOpIntent extends IntentBase {
         xPx: number;
         yPx: number;
     };
-    /** For INSERT ops (rowAbove/rowBelow/colLeft/colRight): carried ids for the
-     * new tracked nodes (p / r) in document order, so replicas address them
-     * alike. */
+    /** For ops that create tracked nodes (rowAbove/rowBelow/colLeft/colRight,
+     * mergeDown, splitCell): carried ids for the new nodes (p / r) in document
+     * order, so replicas address them alike. */
     nodeIds?: StableId[];
+    /**
+     * Tracked-change (suggesting) metadata; see FormatParagraphIntent. Only the
+     * three FORMATTING ops honour it — cellShading and cellVAlign record a
+     * w:tcPrChange, textWrapping a w:tblPrChange. The structural ops have no
+     * tracked form and ignore it, so the surfaces that enforce suggesting mode
+     * refuse those outright rather than send one.
+     */
+    suggest?: SuggestMeta;
 }
 /**
  * Merge a paragraph into its predecessor (Backspace at paragraph start). The
@@ -2740,6 +4360,14 @@ interface MergeParagraphIntent extends IntentBase {
     kind: "mergeParagraph";
     /** The paragraph to merge into the one before it. */
     blockId: StableId;
+    /**
+     * Tracked-change (suggesting) metadata. Word tracks a merge as a DELETED
+     * PARAGRAPH MARK: the pilcrow that separates the two paragraphs — the
+     * PREVIOUS paragraph's mark — gets a w:del in its pPr/rPr, and both
+     * paragraphs stay in place until the reviewer accepts. Omit for a direct
+     * merge.
+     */
+    suggest?: SuggestMeta;
 }
 /**
  * Add a review comment anchored to an entire run. Comment markers
@@ -2835,11 +4463,14 @@ interface InsertMathIntent extends IntentBase {
     mathText: string;
     nodeIds: StableId[];
 }
-/** Insert a shape/textbox drawing at the end of a run (sibling — identity). */
+/** Insert a shape/textbox drawing at the end of a run (sibling — identity).
+ * `preset` is a legacy named preset (line/verticalLine/rectangle/
+ * roundedRectangle/ellipse/diamond/textBox) or any ST_ShapeType name core's
+ * preset-geometry table knows; validated with isValidShapePreset. */
 interface InsertShapeIntent extends IntentBase {
     kind: "insertShape";
     runId: StableId;
-    preset: "line" | "verticalLine" | "rectangle" | "roundedRectangle" | "ellipse" | "diamond" | "textBox";
+    preset: string;
     text?: string;
     nodeIds: StableId[];
 }
@@ -2865,6 +4496,8 @@ interface AdjustIndentIntent extends IntentBase {
     kind: "adjustIndent";
     blockId: StableId;
     direction: 1 | -1;
+    /** Tracked-change (suggesting) metadata; see FormatParagraphIntent. */
+    suggest?: SuggestMeta;
 }
 /** Set paragraph line/before/after spacing. Block-level, identity. */
 interface SetSpacingIntent extends IntentBase {
@@ -2872,6 +4505,8 @@ interface SetSpacingIntent extends IntentBase {
     blockId: StableId;
     /** ParagraphSpacingPatch (before/after/line/lineRule) — carried verbatim. */
     patch: Record<string, unknown>;
+    /** Tracked-change (suggesting) metadata; see FormatParagraphIntent. */
+    suggest?: SuggestMeta;
 }
 /** Insert a page-number field at the end of a run (sibling insertion,
  * identity). Page fields are deterministic (no clock). */
@@ -2915,7 +4550,22 @@ interface InsertBookmarkIntent extends IntentBase {
     runId: StableId;
     name: string;
 }
-type Intent = InsertTextIntent | DeleteTextIntent | SplitParagraphIntent | FormatRunIntent | FormatParagraphIntent | SetListTypeIntent | FormatRangeIntent | TableOpIntent | MergeParagraphIntent | CommentRunIntent | PasteBlocksIntent | InsertImageIntent | SuggestRevisionIntent | InsertBreakIntent | InsertMathIntent | InsertShapeIntent | ReplyCommentIntent | AdjustIndentIntent | SetSpacingIntent | InsertPageFieldIntent | SetLinkIntent | InsertFootnoteIntent | SetDropCapIntent | SetDividerIntent | InsertBookmarkIntent | InsertBlankPageIntent | InsertSectionBreakIntent | InsertCrossRefIntent | InsertCoverPageIntent | SetPageLayoutIntent | SetListLevelIntent | InsertWordArtIntent | InsertChartIntent | InsertSmartArtIntent | SetLineNumberingIntent | InsertDateTimeFieldIntent | InsertFieldIntent | SetDrawingRotationIntent | SetDrawingFillIntent | SetChartDataIntent | SetSmartArtNodeTextIntent | SetDrawingWordArtTextIntent | SetDrawingLineStyleIntent | SetImageAltTextIntent | RemoveLinkIntent | SetImageWrapIntent | SetDrawingOrderIntent | SetSmartArtDataIntent | SetSmartArtFillIntent | SetSmartArtTextFormatIntent | SetFloatingPagePositionIntent | ResizeDrawingIntent | ResizeTableColumnIntent | ResizeTableRowIntent | MoveTableIntent | RemoveDrawingIntent | SetMathLinearIntent | DeleteMathIntent | MoveMathIntent | EnsureHeaderFooterIntent | DeleteCommentIntent | InsertBookmarkRangeIntent | ToggleCheckboxIntent | AcceptRevisionIntent | RejectRevisionIntent | AcceptAllRevisionsIntent | RejectAllRevisionsIntent | InsertTableIntent;
+/**
+ * Intents whose wire shape comes from the core operation registry. One
+ * declaration in @wordinweb/core's edit/registry.ts produces the payload, the
+ * apply, the validation, the carried-id budget, and the agent capability row;
+ * here it just picks up the wire bookkeeping every intent carries.
+ *
+ * The registry admits only id-addressed, position-stable operations with no
+ * wire inverse, so every registered intent's transform is identity and
+ * collaborative undo skips it — see the registry's module comment.
+ */
+type RegisteredIntent = RegisteredOperationBody & IntentBase;
+/** One registered intent, by kind. */
+type RegisteredIntentOf<Kind extends RegisteredOperationKind> = Extract<RegisteredIntent, {
+    kind: Kind;
+}>;
+type Intent = InsertTextIntent | InsertSeparatorIntent | DeleteSeparatorIntent | DeleteTextIntent | SplitParagraphIntent | FormatRunIntent | FormatParagraphIntent | SetListTypeIntent | FormatRangeIntent | TableOpIntent | MergeParagraphIntent | CommentRunIntent | PasteBlocksIntent | InsertImageIntent | SuggestRevisionIntent | InsertBreakIntent | InsertMathIntent | InsertShapeIntent | ReplyCommentIntent | AdjustIndentIntent | SetSpacingIntent | InsertPageFieldIntent | SetLinkIntent | InsertFootnoteIntent | SetDropCapIntent | SetDividerIntent | InsertBookmarkIntent | InsertBlankPageIntent | InsertSectionBreakIntent | InsertCrossRefIntent | InsertCoverPageIntent | SetPageLayoutIntent | SetListLevelIntent | InsertWordArtIntent | InsertChartIntent | InsertSmartArtIntent | SetLineNumberingIntent | InsertDateTimeFieldIntent | InsertFieldIntent | SetDrawingRotationIntent | SetDrawingFillIntent | SetChartDataIntent | SetSmartArtNodeTextIntent | SetDrawingWordArtTextIntent | SetDrawingWordArtStyleIntent | SetDrawingLineStyleIntent | SetImageAltTextIntent | RemoveLinkIntent | SetImageWrapIntent | SetDrawingOrderIntent | SetSmartArtDataIntent | SetSmartArtFillIntent | SetSmartArtTextFormatIntent | SetFloatingPagePositionIntent | ResizeDrawingIntent | ResizeTableColumnIntent | MoveTableIntent | RemoveDrawingIntent | SetMathLinearIntent | DeleteMathIntent | MoveMathIntent | EnsureHeaderFooterIntent | DeleteCommentIntent | ResolveCommentIntent | EditCommentIntent | InsertBookmarkRangeIntent | AcceptRevisionIntent | RejectRevisionIntent | AcceptAllRevisionsIntent | RejectAllRevisionsIntent | RegisteredIntent;
 /** Insert a blank page at the end of a run. */
 interface InsertBlankPageIntent extends IntentBase {
     kind: "insertBlankPage";
@@ -2963,22 +4613,33 @@ interface InsertWordArtIntent extends IntentBase {
     kind: "insertWordArt";
     runId: StableId;
     text: string;
-    preset: "plain" | "archUp" | "archDown" | "wave" | "chevron";
+    preset: "plain" | "archUp" | "archDown" | "wave" | "chevron" | "circle" | "button" | "chevronDown";
+    /** Gallery style: glyph fill plus optional outline and shadow. */
+    style?: {
+        fill: string;
+        outline?: {
+            color: string;
+            widthPt: number;
+        };
+        shadow?: boolean;
+    };
     nodeIds: StableId[];
 }
-/** Insert a data chart (column/bar/line/pie) at the end of a run. The chart
- * data is carried verbatim; the workbook part is generated deterministically. */
+/** Insert a data chart at the end of a run. The chart data is carried
+ * verbatim; the workbook part is generated deterministically. */
 interface InsertChartIntent extends IntentBase {
     kind: "insertChart";
     runId: StableId;
     chart: {
-        type: "column" | "bar" | "line" | "pie";
+        type: "column" | "bar" | "line" | "pie" | "doughnut" | "area" | "scatter";
         title?: string;
         categories: string[];
         series: {
             name: string;
             values: number[];
         }[];
+        /** How bar/column/area series group; absent = clustered. */
+        grouping?: "clustered" | "stacked" | "percentStacked";
     };
     nodeIds: StableId[];
 }
@@ -3021,58 +4682,67 @@ interface InsertFieldIntent extends IntentBase {
     cachedResult?: string;
     nodeIds: StableId[];
 }
+interface DrawingTarget {
+    runId: StableId;
+    /** Parsed run-content index. It disambiguates several drawings carried by one run. */
+    objectIndex?: number;
+}
 /** Rotate the drawing carried by a run. Identity transform (run-addressed). */
-interface SetDrawingRotationIntent extends IntentBase {
+interface SetDrawingRotationIntent extends IntentBase, DrawingTarget {
     kind: "setDrawingRotation";
     runId: StableId;
     degrees: number;
 }
 /** Set/clear the solid fill of the drawing carried by a run. `color` is a
  * 6-hex-digit RGB (no #) or null to clear. */
-interface SetDrawingFillIntent extends IntentBase {
+interface SetDrawingFillIntent extends IntentBase, DrawingTarget {
     kind: "setDrawingFill";
     runId: StableId;
     color: string | null;
 }
 /** Replace the data of the chart carried by a run (same shape as insertChart's
  * chart). Edits an existing chart in place. */
-interface SetChartDataIntent extends IntentBase {
+interface SetChartDataIntent extends IntentBase, DrawingTarget {
     kind: "setChartData";
     runId: StableId;
-    chart: {
-        type: "column" | "bar" | "line" | "pie";
-        title?: string;
-        categories: string[];
-        series: {
-            name: string;
-            values: number[];
-        }[];
-    };
+    chart: InsertChartIntent["chart"];
 }
 /** Set the text of one node of the SmartArt diagram carried by a run. */
-interface SetSmartArtNodeTextIntent extends IntentBase {
+interface SetSmartArtNodeTextIntent extends IntentBase, DrawingTarget {
     kind: "setSmartArtNodeText";
     runId: StableId;
     index: number;
     text: string;
 }
 /** Replace the text of the WordArt drawing carried by a run. */
-interface SetDrawingWordArtTextIntent extends IntentBase {
+interface SetDrawingWordArtTextIntent extends IntentBase, DrawingTarget {
     kind: "setDrawingWordArtText";
     runId: StableId;
     text: string;
 }
-/** Set the outline (line) style of the drawing carried by a run. */
-interface SetDrawingLineStyleIntent extends IntentBase {
+/** Set the glyph fill and alpha of the WordArt drawing carried by a run. */
+interface SetDrawingWordArtStyleIntent extends IntentBase, DrawingTarget {
+    kind: "setDrawingWordArtStyle";
+    runId: StableId;
+    color: string;
+    opacity: number;
+}
+/** Set or clear the outline of the drawing carried by a run. */
+type SetDrawingLineStyleIntent = IntentBase & DrawingTarget & {
     kind: "setDrawingLineStyle";
     runId: StableId;
+} & ({
+    color: null;
+    widthPx?: number;
+    dash?: "solid" | "dashed" | "dotted";
+} | {
     color: string;
     widthPx: number;
     dash: "solid" | "dashed" | "dotted";
-}
+});
 /** Set/clear the alt text (accessibility description) of the image/drawing
  * carried by a run. Empty string clears it. */
-interface SetImageAltTextIntent extends IntentBase {
+interface SetImageAltTextIntent extends IntentBase, DrawingTarget {
     kind: "setImageAltText";
     runId: StableId;
     alt: string;
@@ -3084,19 +4754,19 @@ interface RemoveLinkIntent extends IntentBase {
 }
 /** Set the text-wrap mode of the drawing carried by a run. A floating mode
  * converts an inline drawing to an anchor. */
-interface SetImageWrapIntent extends IntentBase {
+interface SetImageWrapIntent extends IntentBase, DrawingTarget {
     kind: "setImageWrap";
     runId: StableId;
     mode: "inline" | "square" | "topAndBottom" | "none" | "behind";
 }
 /** Bring the (floating) drawing carried by a run to front/back. */
-interface SetDrawingOrderIntent extends IntentBase {
+interface SetDrawingOrderIntent extends IntentBase, DrawingTarget {
     kind: "setDrawingOrder";
     runId: StableId;
     order: "front" | "back";
 }
 /** Replace the whole SmartArt diagram (layout + items) carried by a run. */
-interface SetSmartArtDataIntent extends IntentBase {
+interface SetSmartArtDataIntent extends IntentBase, DrawingTarget {
     kind: "setSmartArtData";
     runId: StableId;
     smartArt: {
@@ -3106,14 +4776,14 @@ interface SetSmartArtDataIntent extends IntentBase {
 }
 /** Set/clear the fill of a SmartArt node (or all nodes when nodeIndex omitted).
  * `color` is 6-hex RGB (no #) or null to clear. */
-interface SetSmartArtFillIntent extends IntentBase {
+interface SetSmartArtFillIntent extends IntentBase, DrawingTarget {
     kind: "setSmartArtFill";
     runId: StableId;
     color: string | null;
     nodeIndex?: number;
 }
 /** Set the text format of a SmartArt node (or all nodes). */
-interface SetSmartArtTextFormatIntent extends IntentBase {
+interface SetSmartArtTextFormatIntent extends IntentBase, DrawingTarget {
     kind: "setSmartArtTextFormat";
     runId: StableId;
     format: {
@@ -3127,7 +4797,7 @@ interface SetSmartArtTextFormatIntent extends IntentBase {
     nodeIndex?: number;
 }
 /** Position the (floating) drawing carried by a run relative to the page. */
-interface SetFloatingPagePositionIntent extends IntentBase {
+interface SetFloatingPagePositionIntent extends IntentBase, DrawingTarget {
     kind: "setFloatingPagePosition";
     runId: StableId;
     xPx: number;
@@ -3135,7 +4805,7 @@ interface SetFloatingPagePositionIntent extends IntentBase {
 }
 /** Resize the drawing carried by a run (extent in px; the mutation clamps to
  * a 1px-EMU floor and keeps line geometry degenerate on its minor axis). */
-interface ResizeDrawingIntent extends IntentBase {
+interface ResizeDrawingIntent extends IntentBase, DrawingTarget {
     kind: "resizeDrawing";
     runId: StableId;
     widthPx: number;
@@ -3151,13 +4821,6 @@ interface ResizeTableColumnIntent extends IntentBase {
     deltaPx: number;
     renderedWidths?: number[];
 }
-/** Drag-resize a table row's height (trHeight atLeast). */
-interface ResizeTableRowIntent extends IntentBase {
-    kind: "resizeTableRow";
-    cellParagraphId: StableId;
-    rowIdx: number;
-    heightPx: number;
-}
 /** Position a table at page coordinates (converts inline to float). */
 interface MoveTableIntent extends IntentBase {
     kind: "moveTable";
@@ -3167,30 +4830,37 @@ interface MoveTableIntent extends IntentBase {
     preservePageStart: boolean;
     pageDelta: number;
 }
-/** Delete the drawing carried by a run (removes the carrier run). */
-interface RemoveDrawingIntent extends IntentBase {
+/** Delete the drawing at the supplied run-content target. */
+interface RemoveDrawingIntent extends IntentBase, DrawingTarget {
     kind: "removeDrawing";
     runId: StableId;
 }
-/** Replace the equation of the math object in a paragraph (linear syntax).
+/**
+ * Which equation inside a block a math intent means: its position among the
+ * block's m:oMath elements in document order. Absent means the first one, so
+ * an intent recorded before a block could hold more than one addressable
+ * equation still names what it always named.
+ */
+interface MathTarget {
+    blockId: StableId;
+    mathIndex?: number;
+}
+/** Replace the equation of a math object in a paragraph (linear syntax).
  * Math (m:oMath) lives at paragraph level, so this is block-addressed. */
-interface SetMathLinearIntent extends IntentBase {
+interface SetMathLinearIntent extends IntentBase, MathTarget {
     kind: "setMathLinear";
-    blockId: StableId;
     mathText: string;
 }
-/** Delete the math object in a paragraph. */
-interface DeleteMathIntent extends IntentBase {
+/** Delete a math object in a paragraph. */
+interface DeleteMathIntent extends IntentBase, MathTarget {
     kind: "deleteMath";
-    blockId: StableId;
 }
 /** Drag-move the equation out of `blockId` to the text position `at`. The
- * equation is addressed like the other math intents (block + firstMathIn); the
+ * equation is addressed like the other math intents (block + mathIndex); the
  * destination is an ordinary wire caret. Dropping mid-text splits the
  * destination run, so the split-off tail run takes a carried id. */
-interface MoveMathIntent extends IntentBase {
+interface MoveMathIntent extends IntentBase, MathTarget {
     kind: "moveMath";
-    blockId: StableId;
     at: Position;
     nodeIds: StableId[];
 }
@@ -3206,11 +4876,36 @@ interface EnsureHeaderFooterIntent extends IntentBase {
     hfKind: "header" | "footer";
     nodeIds: StableId[];
 }
-/** Delete a comment (and its reply thread) by id. */
+/** Delete a comment (and its reply thread) by id. Addressed with a reply's
+ * id it deletes just that reply — the thread/reply distinction is the id. */
 interface DeleteCommentIntent extends IntentBase {
     kind: "deleteComment";
     commentId: string;
 }
+/**
+ * Resolve (true) or reopen (false) a comment thread. Addressed like
+ * deleteComment, by the comment's deterministic string id (a reply id
+ * resolves its thread's parent). The mutation writes w15:done on the thread
+ * parent's commentsExtended entry; when the parent's body paragraph carries
+ * no w14:paraId yet, the carried `paraId` candidate is consumed to mint one
+ * (provenance rule a — generated once by the originator, identical XML on
+ * every replica). No document run's text moves — identity transform.
+ */
+interface ResolveCommentIntent extends IntentBase {
+    kind: "resolveComment";
+    commentId: string;
+    resolved: boolean;
+    /** paraId candidate, consumed only when the thread parent lacks one. */
+    paraId: string;
+}
+/** Replace a comment's body text (Word's edit-my-comment). Author, date, id,
+ * anchors and threading stay; deterministic given the carried text — identity
+ * transform, clean no-op for an unknown id or unchanged text. */
+interface EditCommentIntent extends IntentBase {
+    kind: "editComment";
+    commentId: string;
+    text: string;
+}
 /** Wrap a sub-range of a run's text in a named bookmark. */
 interface InsertBookmarkRangeIntent extends IntentBase {
     kind: "insertBookmarkRange";
@@ -3219,11 +4914,6 @@ interface InsertBookmarkRangeIntent extends IntentBase {
     start: number;
     end: number;
 }
-/** Toggle the checkbox content control carried by a run. */
-interface ToggleCheckboxIntent extends IntentBase {
-    kind: "toggleCheckbox";
-    runId: StableId;
-}
 /** Accept one tracked change, addressed by its position in document order
  * (collectRevisions order — deterministic across replicas). */
 interface AcceptRevisionIntent extends IntentBase {
@@ -3235,21 +4925,17 @@ interface RejectRevisionIntent extends IntentBase {
     kind: "rejectRevision";
     index: number;
 }
-/** Accept every tracked change in the document. */
+/** Accept every tracked change in the document, or only one author's when
+ * `author` is given — a surface that owns some of the revisions must not
+ * resolve the rest. Absent means all, which is what older clients send. */
 interface AcceptAllRevisionsIntent extends IntentBase {
     kind: "acceptAllRevisions";
+    author?: string;
 }
-/** Reject every tracked change in the document. */
+/** Reject every tracked change, or only one author's. See AcceptAll. */
 interface RejectAllRevisionsIntent extends IntentBase {
     kind: "rejectAllRevisions";
-}
-/** Insert a rows×cols table after the paragraph containing the anchor run. */
-interface InsertTableIntent extends IntentBase {
-    kind: "insertTable";
-    runId: StableId;
-    rows: number;
-    cols: number;
-    nodeIds: StableId[];
+    author?: string;
 }
 /** A sequenced log entry: an applied intent with its assigned seq, or a
  * rejection no-op (doc 03) that still occupies a position in the total order
@@ -3287,8 +4973,13 @@ type IdSidecar = ReturnType<StableIds["exportSidecar"]>;
  *  nothing-to-undo  the stack is empty
  *  unavailable    this connection has no collaborative undo (plaintext rooms,
  *                 whose authority is the server)
+ *  queued         the press is HELD because this client's own edits are still
+ *                 in flight and the undo stack cannot see them yet. It runs
+ *                 when they confirm, or is dropped at the deadline — either
+ *                 way onUndoQueue reports it (see
+ *                 EncryptedCollabConnection.undoLast)
  */
-type UndoOutcome = "undone" | "cannot-undo" | "changed-since" | "nothing-to-undo" | "unavailable";
+type UndoOutcome = "undone" | "cannot-undo" | "changed-since" | "nothing-to-undo" | "unavailable" | "queued";
 
 /**
  * E2EE primitives for the blind-sequencer mode (plan doc 13). Pure WebCrypto
@@ -3503,6 +5194,8 @@ interface RosterEntry {
     clientId: string;
     profile: ParticipantProfile;
     connected: boolean;
+    /** Set by the server after a valid one-time AI invitation is redeemed. */
+    participantType?: "human" | "agent";
     /**
      * Whether this participant may write, re-fanned on every transition.
      *
@@ -3570,12 +5263,37 @@ type ClientMessage = {
      * accounts: lose the bundle, lose the crown; re-seed to reclaim.
      */
     ownerToken?: string;
+    /** One-time room invitation created by an already joined participant. */
+    agentInvite?: {
+        inviteId: string;
+        token: string;
+    };
 }
 /** Update this connection's profile mid-session (rename / recolor). */
  | {
     t: "profile";
     profile: ParticipantProfile;
 }
+/** Register or revoke an AI invitation. The server binds it to this
+ * connection's room identity and never broadcasts the token. */
+ | {
+    t: "agent-invite";
+    inviteId: string;
+    token: string;
+    expiresAt: number;
+} | {
+    t: "agent-invite-revoke";
+    inviteId: string;
+}
+/** End-to-end encrypted private chat. The server only routes the envelope
+ * between the invited agent and the participant who created its invite. */
+ | {
+    t: "agent-chat";
+    agentClientId: string;
+    messageId: string;
+    iv: string;
+    ciphertext: string;
+}
 /**
  * Owner admin channel (doc 14 §2.5) — only honored from a connection
  * whose hello proved the owner token. All enforceable by a BLIND server
@@ -3813,6 +5531,26 @@ type ServerMessage = {
  | {
     t: "roster";
     roster: RosterEntry[];
+} | {
+    t: "agent-invite-registered";
+    inviteId: string;
+    expiresAt: number;
+} | {
+    t: "agent-invite-refused";
+    inviteId: string;
+    reason: string;
+} | {
+    t: "agent-connected";
+    inviteId: string;
+    agentClientId: string;
+    profile: ParticipantProfile;
+} | {
+    t: "agent-chat";
+    agentClientId: string;
+    messageId: string;
+    sender: "inviter" | "agent";
+    iv: string;
+    ciphertext: string;
 }
 /**
  * The session is going to END, and this is the grace period before it does
@@ -3886,13 +5624,28 @@ interface ToolbarMenuSelectProps {
     menuWidth?: number;
     className?: string;
     style?: React.CSSProperties;
+    /** Greys the control and refuses to open it. Distinct from an option's own
+     * `disabled`, which only rules out that one choice. */
+    disabled?: boolean;
+    /**
+     * `"bar"` (default) sits in the ribbon: no border, no background, 26px.
+     * `"field"` sits in a popover or dialog beside a label, where the control
+     * has to read as an input — visible box, full width, popover background.
+     *
+     * A preset rather than a style object at each call site: the 23 selects
+     * this replaced carried four different near-identical style sources between
+     * them, which is how they drifted apart in the first place.
+     */
+    variant?: "bar" | "field";
+    /** Fold priority for the bar's layout engine; see RibbonItem.fold. */
+    fold?: number;
 }
 /** CSS-overridable replacement for visible native selects. An inert,
  * transparent select is kept as an event bridge for existing integrations;
  * every user-facing part is a button/listbox rendered by us. */
-declare function ToolbarMenuSelect({ value, options, onChange, placeholder, title, ariaLabel, triggerAriaLabel, width, menuWidth, className, style, }: ToolbarMenuSelectProps): react.JSX.Element;
+declare function ToolbarMenuSelect({ value, options, onChange, placeholder, title, ariaLabel, triggerAriaLabel, width, menuWidth, className, style, disabled, variant, fold, }: ToolbarMenuSelectProps): react.JSX.Element;
 /** Toolbar control groups a host can disable via the `features` prop. */
-type ToolbarFeature = "history" | "styles" | "font" | "size" | "format" | "color" | "highlight" | "alignment" | "indent" | "spacing" | "link" | "lists" | "table" | "image" | "icon" | "screenshot" | "model3D" | "media" | "object" | "chart" | "smartArt" | "comment" | "footnote" | "bookmark" | "crossReference" | "dateTime" | "field" | "equation" | "symbol" | "shape" | "divider" | "textBox" | "wordArt" | "drawing" | "arrange" | "dropCap" | "headerFooter" | "coverPage" | "pageNumber" | "break" | "layout" | "help" | "download";
+type ToolbarFeature = "history" | "styles" | "charStyles" | "formatPainter" | "font" | "size" | "format" | "color" | "highlight" | "alignment" | "indent" | "spacing" | "link" | "lists" | "borders" | "table" | "image" | "icon" | "screenshot" | "model3D" | "media" | "object" | "chart" | "smartArt" | "comment" | "footnote" | "bookmark" | "crossReference" | "dateTime" | "field" | "citations" | "quickParts" | "equation" | "symbol" | "shape" | "divider" | "textBox" | "wordArt" | "drawing" | "arrange" | "dropCap" | "headerFooter" | "watermark" | "coverPage" | "pageNumber" | "break" | "layout" | "review" | "help" | "download";
 /**
  * Every `DocxViewApi` command that INSERTS content at the caret, paired with
  * the toolbar feature group that gates its control.
@@ -3922,7 +5675,7 @@ type ToolbarMode = "simple" | "advanced";
 interface DocxToolbarProps {
     api: DocxViewApi | null;
     onSave?: (bytes: Uint8Array) => void;
-    /** Simple shows basic Home editing; advanced adds the Insert, Draw, and Layout ribbons. */
+    /** Simple shows basic Home editing; advanced adds the Insert, Draw, Layout, and Review ribbons. */
     mode?: ToolbarMode;
     /** Per-group overrides; every group defaults to enabled. */
     features?: Partial<Record<ToolbarFeature, boolean>>;
@@ -3930,8 +5683,80 @@ interface DocxToolbarProps {
     className?: string;
     /** Inline overrides merged onto the toolbar root; wins over the defaults. */
     style?: React.CSSProperties;
+    /** Connected collaborator names offered as @mention shortcuts in comments. */
+    commentMentions?: string[];
+    /** Start with the toolbar expanded (all groups inline, wrapping onto extra
+     * rows). A choice the user makes via the chevron toggle is persisted in
+     * localStorage and wins over this default. */
+    defaultExpanded?: boolean;
+    /**
+     * Shortcuts the embedding application owns, listed in the help guide
+     * alongside the editor's own. A desktop menu accelerator is consumed by the
+     * menu before the editor sees the key, so the engine cannot discover it;
+     * the app declares it once and passes it here, and the reference stays
+     * complete. Electron hosts can read the live menu rather than repeat it:
+     * walk Menu.getApplicationMenu() for {label, accelerator} pairs.
+     */
+    hostShortcuts?: HostShortcutSection[];
 }
-declare function DocxToolbar({ api, onSave, mode, features, className, style, }: DocxToolbarProps): react.JSX.Element;
+declare function DocxToolbar({ api, onSave, mode, features, className, style, commentMentions, defaultExpanded, hostShortcuts, }: DocxToolbarProps): react.JSX.Element;
+
+/**
+ * The host affordance for Compare Documents — Word's "legal blackline".
+ *
+ * The engine call (`compareDocuments` in @wordinweb/core) is pure: two
+ * documents in, a third out. Everything a browser has to do around it lives
+ * here — pick a file, read it, hand the result somewhere — so the toolbar
+ * entry is one button and the engine stays free of the DOM.
+ *
+ * The document on screen is the ORIGINAL and the picked file is the REVISED
+ * one, which is the direction Word's dialog defaults to. The result is a new
+ * document whose differences are tracked changes attributed to `author`;
+ * accepting them all gives the picked file back, rejecting them all gives what
+ * is on screen back.
+ */
+interface CompareResult {
+    /** The compared document, as .docx bytes. */
+    bytes: Uint8Array;
+    /** What the comparison could not express as a tracked change. */
+    notes: CompareNote[];
+    /** The picked file's name, for whatever the host calls the result. */
+    revisedName: string;
+}
+interface CompareWithFileOptions {
+    /** Who the tracked changes are attributed to. */
+    author?: string;
+    /** Timestamp for every revision. Defaults to now. */
+    date?: string;
+    /** Compare formatting as well as text. Default true, as in Word. */
+    formatting?: boolean;
+    /** Report whitespace-only differences. Default true, as in Word. */
+    whitespace?: boolean;
+}
+/**
+ * Compare `originalBytes` with a .docx `file`. Returns the result and the list
+ * of differences that could not be tracked, which a caller should show rather
+ * than swallow — a comparison that quietly skipped something is worse than one
+ * that says what it skipped.
+ */
+declare function compareWithFile(originalBytes: Uint8Array, file: File, options?: CompareWithFileOptions): Promise<CompareResult>;
+/** Ask for one .docx. Resolves to null when the picker is dismissed. */
+declare function pickDocx(): Promise<File | null>;
+/** Save bytes to the user's downloads under `name`. */
+declare function downloadDocx(bytes: Uint8Array, name: string): void;
+/**
+ * The whole affordance behind one click: pick a file, compare, hand the result
+ * to `onResult` (or download it), and report anything untrackable.
+ *
+ * Returns false when no file was picked, so a caller can tell "cancelled" from
+ * "compared with nothing to say".
+ */
+declare function pickAndCompare(originalBytes: Uint8Array, options?: CompareWithFileOptions & {
+    onResult?: (result: CompareResult) => void;
+    onNotes?: (notes: CompareNote[]) => void;
+}): Promise<boolean>;
+/** "report.docx" → "report (compared).docx". */
+declare function comparedName(revisedName: string): string;
 
 interface DocxViewApi {
     /** Apply character formatting to the current browser selection. */
@@ -3940,6 +5765,8 @@ interface DocxViewApi {
     addComment(text: string): boolean;
     /** Insert a footnote at the caret. False without a caret. */
     addFootnote(text: string): boolean;
+    /** Insert an endnote at the caret. False without a caret. */
+    addEndnote(text: string): boolean;
     /** Insert a dynamic page-number field at the caret (body, header or footer). */
     insertPageNumber(kind?: "page" | "pageOfTotal"): boolean;
     /** Insert any Word field instruction supported by the renderer. */
@@ -3948,10 +5775,137 @@ interface DocxViewApi {
     insertDateTime(kind: "date" | "time", picture?: string): boolean;
     /** Named bookmarks in document order. */
     listBookmarks(): string[];
+    /**
+     * How many entries a table of contents would find right now, and how many
+     * index entries have been marked.
+     *
+     * A TOC and an INDEX are both built from something the user has to do first —
+     * apply heading styles, or mark entries — and inserting one before that puts
+     * Word's own "No table of contents entries found." into the document, which
+     * is accurate and explains nothing. A surface that can ask beforehand can say
+     * what is missing instead.
+     */
+    contentsAvailability(): {
+        headings: number;
+        indexEntries: number;
+    };
     /** Add a bookmark around the selection, or a zero-length bookmark at the caret. */
     addBookmark(name: string): boolean;
     /** Insert a live text or page reference to a bookmark. */
     insertCrossReference(bookmark: string, kind: "text" | "page"): boolean;
+    /**
+     * Cross-reference targets beyond plain bookmarks, in document order:
+     * headings, captions (SEQ paragraphs), and numbered list items — what
+     * Word's Cross-reference dialog lists per reference type. The keys stay
+     * valid until the next call (or a document change).
+     */
+    listCrossRefTargets(): {
+        key: string;
+        kind: "heading" | "caption" | "numberedItem";
+        text: string;
+    }[];
+    /**
+     * Insert a live text or page reference to a listed target. A target with
+     * no hidden `_Ref` bookmark gets one first (Word's own mechanism), so the
+     * REF/PAGEREF has something durable to point at.
+     */
+    insertCrossRefToTarget(key: string, kind: "text" | "page"): boolean;
+    /**
+     * Insert a Word caption — "<label> <n>" in the Caption style, the number a
+     * live SEQ field — below or above the selected object (or the caret's
+     * block; a caret inside a table captions the table). updateFields
+     * renumbers the whole label sequence.
+     */
+    insertCaption(label: string, text?: string, position?: "below" | "above"): boolean;
+    /**
+     * Recompute every supported field's cached result — Word's F9, and what a
+     * host calls before printing or exporting so the file it hands on carries
+     * current page numbers, dates and cross-references. False when nothing
+     * changed.
+     *
+     * `fileName` and `author` are the host's to supply: the engine has no
+     * filesystem of its own, so FILENAME and AUTHOR fields keep their cached
+     * results without them.
+     */
+    updateFields(values?: {
+        fileName?: string;
+        author?: string;
+    }): boolean;
+    /**
+     * Insert a native Word table of contents at the caret.
+     *
+     * Outside a room the page numbers are filled in immediately, from a layout
+     * this call runs. IN a room the entries land with placeholders: page numbers
+     * come from a layout, a layout depends on the host's font metrics, and that
+     * is precisely the value `updateFields` carries as data instead of letting
+     * each replica recompute it. Run the update pass to fill them.
+     */
+    insertToc(options?: TocOptions): boolean;
+    /**
+     * Rebuild every table of contents from the document's current headings, then
+     * repage it. Use after headings are added, removed or retitled; repaging an
+     * unchanged heading set needs only updateFields. False in a shared document,
+     * for the reason insertToc gives.
+     */
+    refreshTocs(): boolean;
+    /**
+     * Every data column this document's MERGEFIELD fields name, in document
+     * order, once each — headers and footers included.
+     *
+     * A mail-merge UI compares this against its data source's headers to report
+     * which fields the data does not supply. Those keep their «Name» placeholder
+     * while previewing, so the user sees an unbound field instead of a blank.
+     *
+     * Read-only, like the whole preview path: no operation, no undo entry, no
+     * collab traffic. Set the values through the `mergeRecord` prop.
+     */
+    listMergeFieldNames(): string[];
+    /** The bibliography sources the document's sources part declares, in part
+     * order — what a citation picker and the source manager list. */
+    listCitationSources(): BibliographySource[];
+    /** The selected citation style (b:Sources/@StyleName — "APA", "MLA", or
+     * whatever an arriving document declares), or null with no sources part. */
+    getCitationStyle(): string | null;
+    /** Select the citation style (APA or MLA) for citations and the
+     * bibliography, creating the sources part when the document has none.
+     * Refreshes citation displays and bibliographies in the same call. */
+    setCitationStyle(style: CitationStyle): boolean;
+    /** Add a bibliography source (book, article, website, or report), creating
+     * the sources part on first use. False when the tag is already taken. */
+    createCitationSource(spec: CitationSourceSpec): boolean;
+    /** Change a source's fields, by tag. Refreshes citation displays and
+     * bibliographies in the same call. */
+    editCitationSource(tag: string, patch: CitationSourcePatch): boolean;
+    /** Delete a source. False while a CITATION field still cites it — remove
+     * the citations first. */
+    deleteCitationSource(tag: string): boolean;
+    /** Insert a citation to an existing source at the caret, displayed in the
+     * document's citation style. False for a tag the sources part lacks. */
+    insertCitation(tag: string): boolean;
+    /** Insert a bibliography at the caret: a BIBLIOGRAPHY field whose entries
+     * are generated from the document's sources (regenerated by updateFields). */
+    insertBibliography(): boolean;
+    /** The Quick Parts (building blocks) the document's glossary part declares,
+     * name and category, in part order — what the gallery lists. */
+    listBuildingBlocks(): BuildingBlockInfo[];
+    /** Save the current selection as a named Quick Part, creating the glossary
+     * part on first use. False with nothing selected, a name already taken, or
+     * a selection the paste-fragment gate refuses (the pasteBlocks gate). */
+    createBuildingBlock(name: string, category?: string): boolean;
+    /** Insert a named Quick Part at the caret, cloning its stored content.
+     * False for a name the glossary part lacks. */
+    insertBuildingBlock(name: string): boolean;
+    /** Delete a Quick Part from the glossary part, by name. False when the name
+     * names none. */
+    deleteBuildingBlock(name: string): boolean;
+    /** Mark an index entry: an invisible XE field after the selection (or the
+     * caret). With no `entry` the selected text is the entry; a colon makes a
+     * subentry ("Widgets:assembly"). False with nothing to mark. */
+    addIndexEntry(entry?: string): boolean;
+    /** Insert an index at the caret, built from the document's XE entry marks
+     * (alphabetized; page numbers filled by the update pass). Rebuilt from the
+     * current marks by updateFields. */
+    insertIndex(): boolean;
     /** Insert an editable inline equation from WordInWeb's linear math syntax. */
     insertEquation(linear: string): boolean;
     /** Insert a Unicode symbol through the normal undo/suggestion-aware typing path. */
@@ -3963,7 +5917,7 @@ interface DocxViewApi {
         dash: DrawingLineDash;
     }): boolean;
     /** Insert editable DrawingML WordArt at the caret. */
-    insertWordArt(text: string, preset?: WordArtPreset): boolean;
+    insertWordArt(text: string, preset?: WordArtPreset, style?: WordArtStyle): boolean;
     /** Insert a native editable ChartML chart at the caret. */
     insertChart(data: ChartData): boolean;
     /** Replace the selected native chart's type and data. */
@@ -4007,12 +5961,82 @@ interface DocxViewApi {
     redo(): void;
     canUndo(): boolean;
     canRedo(): boolean;
+    /**
+     * Record the document's current state as an undo boundary.
+     *
+     * For a host that mutates the document THROUGH SOMETHING OTHER THAN THIS API
+     * — an agent session applying intents to the same DocxDocument — and still
+     * wants Cmd+Z to reach those changes. Every editing method here checkpoints
+     * on its own; nothing outside can, so without this an external edit is
+     * invisible to undo and leaves the history's shadow describing a document
+     * that no longer exists.
+     */
+    checkpoint(): void;
+    /**
+     * MAIL MERGE OUTPUT: this document with one record's values baked into its
+     * MERGEFIELD results, as bytes. The open document is NOT modified — the
+     * merge runs against a fresh parse of its serialized form, so a hundred
+     * records produce a hundred files and leave the template on screen alone.
+     */
+    mergeRecordToBytes(record: MergeRecord): Uint8Array;
     /** Insert a rows×cols table at the caret's paragraph. */
     insertTable(rows: number, cols: number): void;
     /** Row/column/table operations on the table containing the caret. */
     tableOp(op: TableOp): void;
     /** Current table-cell fill, undefined when the caret is outside a table. */
     getTableCellFill(): string | null | undefined;
+    /** What a Table Properties dialog prefills from — the table's width, its
+     * grid columns, the caret's column, the default cell margins and the header
+     * band, in points. Undefined when the caret is outside a table. */
+    getTableProperties(): TablePropertiesPt | undefined;
+    /** Set or clear border edges on the caret's cell or its whole table. A null
+     * `border` removes the edges so they inherit again; `{ style: "none" }`
+     * instead suppresses them, which is Word's No Border. */
+    setTableBorders(scope: "cell" | "table", edges: TableBorderEdge[], border: TableBorderSpec | null): void;
+    /** The table styles this document's styles.xml defines — the whole valid
+     * domain for setTableStyle, since an undefined id renders nothing. */
+    listTableStyles(): {
+        id: string;
+        name: string;
+    }[];
+    /** Style id of the table containing the caret: null when it has none,
+     * undefined when the caret is outside a table. */
+    getTableStyleId(): string | null | undefined;
+    /** Apply a table style, or with null remove the reference. */
+    setTableStyle(styleId: string | null): void;
+    /** Word's six table style options for the caret's table, undefined outside
+     * a table. */
+    getTableLook(): TableLookToggles | undefined;
+    /** Set some of the six table style options. */
+    setTableLook(patch: Partial<TableLookToggles>): void;
+    /** Set the table's preferred width. `value` is points for "pt", 0-100 for
+     * "pct", and ignored for "auto". */
+    setTableWidth(unit: "pt" | "pct" | "auto", value?: number): void;
+    /** Set one column to an exact width in points. */
+    setTableColumnWidth(colIdx: number, widthPt: number): void;
+    /** Switch the table between fixed column widths and autofit. Switching to
+     * fixed freezes the columns as currently RENDERED, which is what the user
+     * is looking at; switching to autofit measures them from content again. */
+    setTableLayout(layout: "fixed" | "autofit"): void;
+    /** Set the table's default cell margins, or the caret cell's override, in
+     * points. A null patch drops the override. */
+    setTableCellMargins(scope: "cell" | "table", margins: CellMarginsPt | null): void;
+    /** Repeat the first `count` rows as a header band on every page. */
+    setTableHeaderRows(count: number): void;
+    /** Sort the caret table's body rows by one grid column, as text or as
+     * numbers. The repeating header band always stays in place; `hasHeader`
+     * additionally pins the first row. Refuses tables with merged cells. */
+    sortTableRows(colIdx: number, order: "asc" | "desc", compare: "text" | "number", hasHeader?: boolean): void;
+    /** Convert the selected paragraphs (or the caret paragraph) into a table,
+     * one row per paragraph, cells split on the separator. */
+    convertTextToTable(separator: "tab" | "comma"): boolean;
+    /** Convert the caret's table into paragraphs, one per row, cell texts
+     * joined by the separator. */
+    convertTableToText(separator: "tab" | "comma"): boolean;
+    /** Insert a table formula field ("=SUM(ABOVE)", "=A1+B2", …) at the caret's
+     * cell paragraph, with an optional \# number format like "#,##0.00". The
+     * result is evaluated immediately; updateFields recomputes it. */
+    insertTableFormula(formula: string, numFmt?: string): boolean;
     /** Insert an image file at the caret (inline, natural size clamped to column).
      * The result is REPORTED rather than swallowed: a picker that accepts a file
      * and then does nothing is indistinguishable from a broken button. */
@@ -4053,22 +6077,51 @@ interface DocxViewApi {
     setParagraphDivider(divider: ParagraphDivider | null): boolean;
     /** Direct bottom-border divider on the caret paragraph. */
     getParagraphDivider(): ParagraphDivider | null;
+    /** Replace the selected paragraphs' direct tab stops (w:tabs). An empty
+     * list removes them, so style stops and the default grid apply again. */
+    setTabStops(stops: TabStopSpec[]): boolean;
+    /** Direct tab stops on the caret paragraph, sorted by position. */
+    getTabStops(): TabStopSpec[];
+    /** Patch the selected paragraphs' border edges (w:pBdr) and/or shading
+     * fill (w:shd). Each named edge is set (spec) or cleared (null); absent
+     * edges stay. `shading: null` removes the fill. */
+    setParagraphBorders(patch: ParagraphBordersPatch): boolean;
+    /** Direct borders and shading on the caret paragraph. */
+    getParagraphBorders(): {
+        borders: Partial<Record<ParagraphBorderEdge, TableBorderSpec>>;
+        shading: string | null;
+    };
     /** Apply or remove a native Word drop cap on the caret paragraph. */
     setDropCap(mode: "drop" | "margin" | null, lines?: number): boolean;
     /** Remove direct character formatting from the selection. */
     clearFormatting(): void;
     /** Change the selection's case. */
     changeCase(mode: "upper" | "lower" | "title"): void;
-    /** Find matches for a query; selects the first and returns the count. */
-    find(query: string, opts?: {
-        matchCase?: boolean;
-    }): number;
+    /** Find matches for a query across every story (body, headers, footers,
+     * footnotes, endnotes); selects the first and returns the count. */
+    find(query: string, opts?: FindOptions): number;
     /** Select the next/previous match; returns 1-based index or 0. */
     findStep(delta: 1 | -1): number;
     /** Replace the current match; returns remaining match count. */
     replaceCurrent(replacement: string): number;
-    /** Replace every match; returns how many were replaced. */
-    replaceAll(query: string, replacement: string): number;
+    /** Replace every match; reports how many were replaced, per story. */
+    replaceAll(query: string, replacement: string, opts?: FindOptions): ReplaceAllResult;
+    /** Go To: scroll the given 1-based page into view. */
+    goToPage(page: number): boolean;
+    /** Go To: move the caret to a named bookmark and scroll it into view. */
+    goToBookmark(name: string): boolean;
+    /**
+     * Select an exact text range by stable address — the `{blockId, runId,
+     * start, end}` shape the wire, presence, and suggestRevision already use
+     * (offsets in the run's wire basis; see getEncodedCaret for the caret
+     * half). Several ranges select together, for a word split across runs.
+     * Selection and scroll ride find-navigation's machinery; the view only
+     * scrolls when the range is off screen. In a local document the first call
+     * populates the stable-id table (enableStableIds), so hosts — the desktop
+     * spellcheck's select-and-replace — can address text without a collab
+     * mount. False when no range resolves to text.
+     */
+    selectRange(range: WireRange | WireRange[]): boolean;
     /** Paragraph styles for the style menu (declared + Word built-ins). */
     listParagraphStyles(): {
         id: string;
@@ -4076,6 +6129,55 @@ interface DocxViewApi {
     }[];
     /** pStyle id of the caret paragraph (null = Normal). */
     getParagraphStyleId(): string | null;
+    /**
+     * Every declared style with the data a gallery entry needs: identity,
+     * cascade parent, quick-style flag, usage count, and resolved preview props.
+     * Richer than listParagraphStyles, which is the flat menu the toolbar's
+     * existing style dropdown reads.
+     */
+    listStyles(filter?: {
+        type?: StyleGalleryEntry["type"];
+        quickStyleOnly?: boolean;
+    }): StyleGalleryEntry[];
+    /** Add a paragraph or character style definition. */
+    createStyle(spec: StyleSpec): boolean;
+    /** Patch an existing style definition; the cascade re-resolves live. */
+    modifyStyle(styleId: string, patch: StylePatch): boolean;
+    /** Delete a style definition; its users fall back to its basedOn. */
+    deleteStyle(styleId: string): boolean;
+    /**
+     * Stamp a text watermark across every page. Word keeps a watermark in the
+     * header parts, so a document with none gets one first.
+     */
+    insertWatermark(spec: WatermarkSpec): boolean;
+    /**
+     * Stamp a PICTURE across every page — Word's Watermark > Picture. Replaces
+     * whichever watermark is already there, text or picture.
+     *
+     * The picture is washed out (Word's own recolor) and fitted to the page.
+     * Takes the same formats a shared document can carry, so SVG is refused;
+     * `imageAccept()` is the list to hand a file picker.
+     */
+    insertPictureWatermark(file: Blob): Promise<ImageInsertResult>;
+    /** Take the watermark back off every page. False when there was none. */
+    removeWatermark(): boolean;
+    /** Apply (or with null remove) a character style over the selection. */
+    setCharacterStyle(styleId: string | null): void;
+    /** Change a list level's number format, label text, or indent. */
+    setNumberingLevel(ilvl: number | null, patch: LevelPatch): boolean;
+    /**
+     * Apply a preset multilevel definition (Word's multilevel gallery) to the
+     * caret's list — the paragraphs join a numbered list first when they are
+     * not in one. Compiles onto the existing per-level patch operation, so it
+     * rides the same wire ops and converges like any level edit.
+     */
+    applyNumberingPreset(preset: NumberingPresetId): boolean;
+    /** Restart list numbering at the caret, or (null) continue the preceding list. */
+    setNumberingRestart(start: number | null): boolean;
+    /** Format painter, half one: the selection's formatting, or null. */
+    copyFormatting(): SelectionFormat | null;
+    /** Format painter, half two: paint a copied format over the selection. */
+    applyCopiedFormatting(format: SelectionFormat): void;
     /** Change margins / page size / orientation (inches). */
     setPageLayout(patch: PageLayoutPatch, scope?: "document" | "section"): void;
     /** One-based logical section containing the caret or selection. */
@@ -4102,10 +6204,90 @@ interface DocxViewApi {
     closeHeaderFooter(): void;
     /** Enter and, if needed, create the header or footer on the caret's page. */
     openHeaderFooter(kind: "header" | "footer"): boolean;
+    /** Word's "Different First Page" (w:titlePg). Enabling creates the empty
+     * first-page header/footer parts; disabling keeps them for re-enable. */
+    setDifferentFirstPage(on: boolean): boolean;
+    /** Whether any section requests a different first page. */
+    getDifferentFirstPage(): boolean;
+    /** Word's "Different Odd & Even Pages" (settings.xml w:evenAndOddHeaders).
+     * Enabling creates the empty even-page header/footer parts. */
+    setOddEvenHeaders(on: boolean): boolean;
+    getOddEvenHeaders(): boolean;
+    /** Page-number format and start-at (w:pgNumType): decimal / roman / letter
+     * numbering, restart value. scope "section" targets the caret's section;
+     * "document" (and any shared document) every section. */
+    setPageNumberFormat(patch: PageNumberFormatPatch, scope?: "document" | "section"): boolean;
+    /** Current page-number settings for the caret's section. */
+    getPageNumberFormat(): {
+        fmt: PageNumberFormat;
+        start: number | null;
+    };
+    /** Patch the automatic-hyphenation settings (w:autoHyphenation,
+     * w:hyphenationZone in points, w:doNotHyphenateCaps). Round-trip state:
+     * this engine's layout does not hyphenate automatically — the settings
+     * govern Word's own rendering of the document. */
+    setHyphenation(patch: {
+        auto?: boolean;
+        zonePt?: number | null;
+        noCaps?: boolean;
+    }): boolean;
+    /** Current hyphenation settings (zonePt null = Word's default 18pt). */
+    getHyphenation(): {
+        auto: boolean;
+        zonePt: number | null;
+        noCaps: boolean;
+    };
+    /** Word's page-number position gallery: a single live PAGE field in the
+     * header (top) or footer (bottom), aligned left/center/right. Creates the
+     * part on demand and replaces its content — a gallery pick, not a merge. */
+    insertPageNumberPosition(position: PageNumberGalleryPosition, align: PageNumberGalleryAlign): boolean;
+    /** Word's "Remove Page Numbers": strips PAGE/NUMPAGES fields from every
+     * header and footer part. */
+    removePageNumbers(): boolean;
+    /** The Header & Footer preset gallery: replace a header or footer's
+     * content with a preset layout (blank / centered title / title + date /
+     * three-column). */
+    insertHeaderFooterPreset(kind: "header" | "footer", preset: HeaderFooterPreset): boolean;
+    /** Footnote options (w:footnotePr): number format, restart rule, start-at,
+     * and position (§17.11.17/19/21). scope "section" targets the caret's
+     * section; "document" (and any shared document) every section. Format and
+     * start drive the painted marks; restart honors "eachSect" only; position
+     * round-trips without changing where footnotes lay out (always page
+     * bottom in this engine). */
+    setFootnoteOptions(patch: FootnoteOptionsPatch, scope?: "document" | "section"): boolean;
+    /** Current footnote options for the caret's section. */
+    getFootnoteOptions(): ReturnType<typeof footnoteOptionsAt>;
+    /** Same as setFootnoteOptions, for endnotes — position vocabulary differs
+     * (sectEnd / docEnd). */
+    setEndnoteOptions(patch: EndnoteOptionsPatch, scope?: "document" | "section"): boolean;
+    getEndnoteOptions(): ReturnType<typeof endnoteOptionsAt>;
+    /** Resolve (true) or reopen (false) a comment thread. */
+    resolveComment(id: string, resolved: boolean): boolean;
+    /** Replace a comment's body text (Word's edit-my-comment). */
+    editComment(id: string, text: string): boolean;
+    /** Select and scroll to the next/previous commented range (Review-tab
+     * navigation). Returns the focused thread's comment id, or null when the
+     * document has no anchored comments. */
+    stepComment(delta: 1 | -1): string | null;
+    /** Word Count: body text statistics from the model plus the page count
+     * from the latest layout. */
+    wordCount(): {
+        words: number;
+        characters: number;
+        charactersWithSpaces: number;
+        paragraphs: number;
+        pages: number;
+    };
     /** Effective formatting of the current selection (toolbar state), or null. */
     getSelectionFormat(): SelectionFormat | null;
     /** Print the rendered pages (browser print dialog / save as PDF). */
     print(): void;
+    /**
+     * The standalone print document (all pages plus styles) as an HTML string,
+     * for hosts that produce the PDF themselves (e.g. a desktop shell).
+     * Null before the first render.
+     */
+    exportPrintHtml(): string | null;
     /** Serialize the (edited) document back to .docx bytes. */
     save(): Uint8Array;
     /** Page count after the latest layout. */
@@ -4123,14 +6305,21 @@ interface DocxViewApi {
     /** Reject the tracked change at the caret (drop insertion / restore deletion). */
     rejectRevisionAtCaret(): boolean;
     /** How many tracked changes (suggestions) the document currently holds. */
-    revisionCount(): number;
+    /** Tracked changes in the document, or only `author`'s when given. */
+    revisionCount(author?: string): number;
     /** Accept every tracked change (one undo step). Returns how many applied. */
-    acceptAllRevisions(): number;
+    /** Accept every tracked change, or only `author`'s. A surface that owns some
+     * of the document's revisions must pass its own author, or it resolves work
+     * it never made. */
+    acceptAllRevisions(author?: string): number;
     /** Reject every tracked change (one undo step). Returns how many applied. */
-    rejectAllRevisions(): number;
-    /** Current caret as stable-id addresses (collab), or null. The encoding
-     * survives a reconciliation reload, so it can be captured from a view
-     * about to remount and restored into its replacement. */
+    /** Reject every tracked change, or only `author`'s. See acceptAllRevisions. */
+    rejectAllRevisions(author?: string): number;
+    /** Current caret as stable-id addresses, or null. The encoding survives a
+     * reconciliation reload, so it can be captured from a view about to
+     * remount and restored into its replacement. In a local document the first
+     * call populates the stable-id table (like selectRange), so hosts can
+     * capture addresses outside a collab mount too. */
     getEncodedCaret(): EncodedCaret | null;
     /** Restore a caret captured by getEncodedCaret. False when the position no
      * longer resolves (or outside collab mode). */
@@ -4154,6 +6343,7 @@ interface DocxViewApi {
     document: DocxDocument;
 }
 type ScreenshotInsertResult = "inserted" | "unsupported" | "cancelled" | "error" | "no-caret";
+
 /**
  * Image formats a SHARED document accepts, and the single source of truth for
  * both halves of that promise: the guard that declines an intent and the
@@ -4169,6 +6359,10 @@ type ScreenshotInsertResult = "inserted" | "unsupported" | "cancelled" | "error"
  * it is an intent-shape change with an ENGINE_VERSION bump, not a UI edit.
  */
 declare const COLLAB_IMAGE_EXTS: readonly ["png", "jpg", "jpeg", "gif", "bmp", "webp"];
+/** File-picker accept list for the raster formats. Also the picture
+ * watermark's whole list: a VML `v:imagedata` cannot carry an SVG, in a
+ * shared document or a local one. */
+declare const RASTER_IMAGE_ACCEPT = "image/png,image/jpeg,image/gif,image/bmp,image/webp";
 /**
  * Why an image insert did not happen, so the caller can SAY so. Every one of
  * these was a bare `return` until a user hit the `unsupported-format` path and
@@ -4307,9 +6501,17 @@ interface DocxViewProps {
          * stack would edit this replica with nothing on the wire. Absent ⇒ undo
          * declines rather than mutating. */
         undoLast?: () => void;
+        /** Single-process session marker (useAgentDocumentSession over a
+         * LocalDocumentSession). Its presence tells the editor there are NO peers,
+         * so undo/redo replay the local history stack; it fires after each applied
+         * undo/redo so the session can bump its revision. A REAL room must leave
+         * this unset, or Cmd+Z would fork it. */
+        noteLocalHistory?: () => void;
     };
     /** Author name stamped on comment replies (default "You"). */
     commentAuthor?: string;
+    /** Connected collaborator names offered as @mention shortcuts in comments. */
+    commentMentions?: string[];
     /** Render review comments (range highlights + margin balloons). Default true. */
     showComments?: boolean;
     /** Tracked-changes display: "final" (default) or "markup". */
@@ -4318,7 +6520,53 @@ interface DocxViewProps {
      * render (unavailable, or lacking the document's script) — the page is
      * silently substituting and may differ from Word. Empty array = all good. */
     onMissingFonts?: (missing: MissingFont[]) => void;
+    /**
+     * Mail-merge PREVIEW: the active record's column values, painted into the
+     * document's MERGEFIELD fields. Absent (or undefined) shows the «Name»
+     * placeholders — that is preview "off".
+     *
+     * Nothing is written to the document. The values are resolved as the pages
+     * are laid out, so they cannot reach a saved file, an undo entry or the
+     * collab wire; preview is per-viewer state by construction. Changing this
+     * prop relays the pages without re-parsing the .docx.
+     *
+     * A column the record does NOT carry keeps its «Name» placeholder, so the
+     * user can see which fields the data leaves unbound. Word renders such a
+     * field blank; this is a deliberate divergence. A column that IS present but
+     * empty renders empty and suppresses the field's \b and \f switch texts.
+     */
+    mergeRecord?: MergeRecord;
+}
+interface AgentDocumentViewBinding {
+    subscribe(listener: () => void): () => void;
+    getSnapshot(): number;
+    doc: DocxDocument;
+    submit(intent: EditorIntent): void;
+    submitOp(intent: {
+        kind: string;
+    } & Record<string, unknown>): void;
+    allocIds(count: number): number[];
+    uploadMedia?(bytes: Uint8Array): Promise<{
+        blobSha: string;
+        bytesLen: number;
+        iv?: string;
+    } | null>;
+    /** Bump the session revision after a local history undo/redo mutated the
+     * document outside the intent path. See collab.noteLocalHistory. */
+    noteHistory?(): void;
+    takeRenderScope(): {
+        kind: "doc";
+    } | {
+        kind: "block";
+        blocks: XmlElement[];
+    } | {
+        kind: "split";
+        before: XmlElement;
+        after: XmlElement;
+    } | null;
 }
+/** Connect a framework-neutral local document session to DocxView. */
+declare function useAgentDocumentSession(binding: AgentDocumentViewBinding): Pick<DocxViewProps, "source" | "collab">;
 /**
  * High-fidelity paginated DOCX viewer (and, with `editable`, editor).
  *
@@ -4327,6 +6575,6 @@ interface DocxViewProps {
  * <DocxView source="/report.docx" editable onReady={setApi} /> // editing
  * ```
  */
-declare function DocxView({ source, zoom, fitWidth, narrowWidth, editable, className, style, onLoad, onPageCountChange, onReady, onError, commentAuthor, showComments, revisions, onMissingFonts, collab, }: DocxViewProps): react.JSX.Element;
+declare function DocxView({ source, zoom, fitWidth, narrowWidth, editable, className, style, onLoad, onPageCountChange, onReady, onError, commentAuthor, commentMentions, showComments, revisions, onMissingFonts, mergeRecord, collab, }: DocxViewProps): react.JSX.Element;
 
-export { type ShapePreset as A, ToolbarMenuSelect as B, type ClientMessage as C, DocxDocument as D, type ToolbarMenuSelectOption as E, type ToolbarMenuSelectProps as F, layoutDocument as G, printPages as H, type Intent as I, renderToDom as J, type LineageHead as L, type PresencePosition as P, type RosterEntry as R, type ServerMessage as S, type ToolbarFeature as T, type UndoOutcome as U, type WriteStatus as W, type XmlElement as X, type ParticipantProfile as a, type IdSidecar as b, type ToolbarMode as c, type DocxViewApi as d, bytesToB64 as e, deriveEpochKeys as f, docKeyFromFragment as g, stretchShareCode as h, COLLAB_IMAGE_EXTS as i, type CoverPageContent as j, DocxToolbar as k, type DocxToolbarProps as l, mintDocKey as m, DocxView as n, type DocxViewProps as o, type DrawingTool as p, INSERT_COMMANDS as q, type ImageInsertResult as r, sealCheckpoint as s, type InsertCommandSpec as t, type LineNumberingPatch as u, type PageLayoutPatch as v, type ParagraphAlignment as w, type RunFormatPatch as x, type ScreenshotInsertResult as y, type SelectionFormat as z };
+export { downloadDocx as $, type AgentDocumentViewBinding as A, RASTER_IMAGE_ACCEPT as B, type ClientMessage as C, DocxDocument as D, type EncodedCaret as E, type RunFormatPatch as F, type ScreenshotInsertResult as G, type HostShortcutSection as H, type Intent as I, type SelectionFormat as J, type ShapePreset as K, type LineageHead as L, type MergeRecord as M, NUMBERING_PRESETS as N, ToolbarMenuSelect as O, type PresencePosition as P, type ToolbarMenuSelectOption as Q, type RosterEntry as R, type ServerMessage as S, type ToolbarFeature as T, type UndoOutcome as U, type ToolbarMenuSelectProps as V, type WriteStatus as W, type XmlElement as X, type WireRange as Y, compareWithFile as Z, comparedName as _, type ParticipantProfile as a, layoutDocument as a0, pickAndCompare as a1, pickDocx as a2, printPages as a3, renderToDom as a4, useAgentDocumentSession as a5, type IdSidecar as b, type ToolbarMode as c, type DocxViewApi as d, bytesToB64 as e, deriveEpochKeys as f, docKeyFromFragment as g, stretchShareCode as h, COLLAB_IMAGE_EXTS as i, type CompareResult as j, type CompareWithFileOptions as k, type CoverPageContent as l, mintDocKey as m, DocxToolbar as n, type DocxToolbarProps as o, DocxView as p, type DocxViewProps as q, type DrawingTool as r, sealCheckpoint as s, INSERT_COMMANDS as t, type ImageInsertResult as u, type InsertCommandSpec as v, type LineNumberingPatch as w, type NumberingPresetId as x, type PageLayoutPatch as y, type ParagraphAlignment as z };