@wordinweb/agent 0.1.0 → 0.2.0

package/dist/index.d.ts

@@ -121,10 +121,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;
@@ -306,7 +317,7 @@ interface EmbeddedObjectReference {
     progId: string;
 }
 /** OMML equation node (subset: runs, scripts, fractions, radicals). */
-type MathNode = {
+type MathNode = ({
     t: "run";
     text: string;
     normal?: boolean;
@@ -375,6 +386,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";
@@ -403,6 +423,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=
@@ -478,12 +503,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:
@@ -493,6 +524,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
@@ -569,6 +607,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[];
@@ -702,16 +750,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 {
@@ -997,7 +1120,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;
@@ -1009,6 +1135,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";
@@ -1030,6 +1166,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[];
@@ -1151,10 +1291,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.
@@ -1198,14 +1338,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. */
@@ -1215,10 +1362,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,
@@ -1229,14 +1376,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,
@@ -1264,6 +1411,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.
@@ -1284,7 +1433,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
@@ -1297,11 +1446,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,
@@ -1310,6 +1471,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
@@ -1345,6 +1512,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;
@@ -1467,12 +1659,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
@@ -1487,7 +1747,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;
     /**
@@ -1503,23 +1785,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:
@@ -1566,6 +1903,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
@@ -1585,6 +1943,22 @@ 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. */
@@ -1659,6 +2033,15 @@ declare class DocxDocument {
         iv?: string;
         genesisId?: 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
@@ -1680,6 +2063,776 @@ declare class DocxDocument {
     private readXmlOptional;
 }
 
+/** 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;
+    underline?: boolean;
+    strike?: boolean;
+    /** "#RRGGBB"; null removes the direct color. */
+    color?: string | null;
+    /** Word highlight name ("yellow", "cyan", …); null removes. */
+    highlight?: string | null;
+    /** Font size in points. */
+    fontSizePt?: number;
+    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;
+}
+
+/**
+ * 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;
+}
+/** 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];
+
+/** 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;
+}
+
+/** 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;
+}
+
+/**
+ * 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>>;
+    };
+    /** 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;
+    };
+}
+interface StylePatch {
+    name?: string;
+    basedOn?: string | null;
+    next?: string | null;
+    quickStyle?: boolean;
+    uiPriority?: number;
+    paragraph?: StyleParaPatch;
+    run?: StyleRunPatch;
+}
+
+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">>;
+
+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 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];
+/** 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];
+
+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];
+
+/**
+ * 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>;
+
 /**
  * Wire intents for replicated editing.
  *
@@ -1694,6 +2847,7 @@ declare class DocxDocument {
  * 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 {
@@ -1734,10 +2888,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 /
@@ -1752,6 +2909,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";
@@ -1793,6 +2981,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 —
@@ -1805,17 +2996,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)
@@ -1836,19 +3036,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;
     } | {
@@ -1860,10 +3064,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
@@ -1875,6 +3087,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
@@ -1970,11 +3190,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[];
 }
@@ -2000,6 +3223,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 {
@@ -2007,6 +3232,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). */
@@ -2050,7 +3277,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 | SetDrawingWordArtStyleIntent | 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";
@@ -2098,22 +3340,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[];
 }
@@ -2179,15 +3432,7 @@ interface SetDrawingFillIntent extends IntentBase, DrawingTarget {
 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, DrawingTarget {
@@ -2303,13 +3548,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";
@@ -2324,25 +3562,32 @@ 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[];
 }
@@ -2358,11 +3603,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";
@@ -2371,11 +3641,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 {
@@ -2387,21 +3652,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;
 }
 /** An intent minus its wire bookkeeping — distributive over the union so each
  * variant keeps its own fields (a plain Omit<Intent,…> would collapse to the
@@ -2477,11 +3738,8 @@ interface AgentEditCapability {
     required: string[];
     optional?: string[];
 }
-/**
- * The agent-facing coverage map for the complete canonical edit surface.
- * Record<Intent["kind"], ...> makes a new intent fail the agent build until
- * its tool contract is declared here.
- */
+/** The complete agent-facing coverage map: hand-written rows plus the rows
+ * the core operation registry declares. */
 declare const AGENT_EDIT_CAPABILITIES: Record<Intent["kind"], AgentEditCapability>;
 type JsonSchema$1 = Record<string, unknown>;
 declare function agentOperationSchema(kind: Intent["kind"]): JsonSchema$1;
@@ -2490,6 +3748,15 @@ declare function agentCapabilities(category?: AgentEditCapability["category"], r
     kind: Intent["kind"];
     inputSchema: Record<string, unknown>;
 }>;
+/**
+ * Collapse every repeated subschema that describes *what to write* into one
+ * `$defs` entry and a `$ref` at each site. Shapes that describe *where to
+ * write* (see `ADDRESSING_PROPERTIES`) and shapes that would cost more as a
+ * reference than as themselves are left alone. The resolved schema is
+ * identical to the input, so no caller and no model behaviour depends on which
+ * form it gets.
+ */
+declare function hoistRepeatedSubschemas(schema: JsonSchema$1): JsonSchema$1;
 
 type AgentReference = string;
 interface AgentCursor {
@@ -2738,6 +4005,44 @@ interface AgentSpatialResult {
     objects: AgentSpatialObject[];
     overlaps: AgentOverlap[];
 }
+/** One text-bearing drawing's frame measured against its own laid-out text. */
+interface AgentDrawingFit {
+    objectRef: AgentReference;
+    page: number;
+    /** The frame the shape draws, px. */
+    boxPx: {
+        w: number;
+        h: number;
+    };
+    /** The extent the text actually laid into, px. */
+    textPx: {
+        w: number;
+        h: number;
+    };
+    /** The text is taller than the box's insets leave room for. */
+    overflow: boolean;
+    /** Lines the box hides because they fall past its bottom. */
+    clippedLines: number;
+    /** The shape's bodyPr autofit mode. Only "resizeShape" makes an overflow
+     * resolve itself: Word paints "shrinkText" at full size and clips it. */
+    autofit: "none" | "resizeShape" | "shrinkText";
+}
+interface AgentFitResult {
+    revision: string;
+    layout: {
+        quality: "exact" | "approximate";
+        profile: string;
+    };
+    totalPages: number;
+    /** How full each requested page is: where its lowest body content ends, and
+     * where the body box ends. */
+    pages: Array<{
+        page: number;
+        contentBottomPx: number;
+        pageBottomPx: number;
+    }>;
+    drawings: AgentDrawingFit[];
+}
 type AgentInspectRequest = {
     kind: "overview";
 } | {
@@ -2767,8 +4072,86 @@ type AgentInspectRequest = {
         count: number;
     };
     includeOverlaps?: boolean;
+} | {
+    kind: "fit";
+    pages?: {
+        start: number;
+        count: number;
+    };
 };
-type AgentInspectResult = AgentOverview | AgentContextResult | AgentReadResult | AgentSearchResult | AgentObjectResult | AgentSpatialResult;
+type AgentInspectResult = AgentOverview | AgentContextResult | AgentReadResult | AgentSearchResult | AgentObjectResult | AgentSpatialResult | AgentFitResult;
+type AgentProjectionMode = "text" | "md" | "outline";
+/** One run of projected characters that came from one place in the document.
+ * `start`/`end` are columns in the projection line; `wireStart`/`wireEnd` are
+ * offsets in the run's wire space. An editable segment is backed by a `w:t`,
+ * so the two spaces line up one-to-one across it and a patch can address any
+ * column inside it. Everything else is an atom the patch path treats as
+ * opaque. */
+interface AgentAnchorSegment {
+    start: number;
+    end: number;
+    runRef: AgentReference;
+    wireStart: number;
+    wireEnd: number;
+    editable: boolean;
+}
+interface AgentAnchorLine {
+    line: number;
+    role: "paragraph" | "table" | "structure";
+    blockRef?: AgentReference;
+    /** Leading characters of the line that are markdown structure rather than
+     * document text (`## `, `- `, `1. `). Always 0 in `text` mode. */
+    marker: number;
+    editable: boolean;
+    segments: AgentAnchorSegment[];
+}
+interface AgentProjectRequest {
+    story?: string;
+    mode?: AgentProjectionMode;
+    cursor?: AgentCursor;
+    maxBlocks?: number;
+    maxCharacters?: number;
+}
+interface AgentProjectResult {
+    revision: string;
+    story: string;
+    mode: AgentProjectionMode;
+    text: string;
+    lines: number;
+    window: {
+        cursor: string | null;
+        startBlock: number;
+        endBlock: number;
+        maxBlocks: number;
+        maxCharacters: number;
+    };
+    anchors: AgentAnchorLine[];
+    next?: AgentCursor;
+    truncated: boolean;
+}
+interface AgentPatchHunk {
+    startLine: number;
+    endLine: number;
+    newText: string;
+}
+interface AgentPatchRequest {
+    revision: string;
+    story?: string;
+    mode?: AgentProjectionMode;
+    cursor?: AgentCursor;
+    maxBlocks?: number;
+    maxCharacters?: number;
+    edits?: AgentPatchHunk[];
+    diff?: string;
+    suggest?: boolean;
+}
+interface AgentPatchResult {
+    revision: string;
+    status: "applied" | "submitted";
+    operations: string[];
+    connection?: "local" | "live" | "offline" | "reconnecting";
+    projection: AgentProjectResult;
+}
 type AgentOperation = Record<string, unknown> & {
     kind: string;
 };
@@ -2838,13 +4221,14 @@ type AgentComposeBlock = {
 } | {
     type: "chart";
     chart: {
-        type: "column" | "bar" | "line" | "pie";
+        type: "column" | "bar" | "line" | "pie" | "doughnut" | "area" | "scatter";
         title?: string;
         categories: string[];
         series: Array<{
             name: string;
             values: number[];
         }>;
+        grouping?: "clustered" | "stacked" | "percentStacked";
     };
     widthPx?: number;
     heightPx?: number;
@@ -2872,7 +4256,7 @@ type AgentComposeBlock = {
     };
 } | {
     type: "shape";
-    preset: "line" | "verticalLine" | "rectangle" | "roundedRectangle" | "ellipse" | "diamond" | "textBox";
+    preset: string;
     text?: string;
     textStyle?: AgentComposeTextStyle;
     widthPx?: number;
@@ -2983,6 +4367,7 @@ declare class AgentDocument {
     private composeAvailable;
     private readonly listeners;
     private readonly inspectedTargets;
+    private readonly projections;
     private constructor();
     static load(bytes: ArrayBuffer | Uint8Array, options?: {
         provenance?: AgentProvenance;
@@ -2998,13 +4383,50 @@ declare class AgentDocument {
     subscribe(listener: (document: DocxDocument, revision: string) => void): () => void;
     addAsset(bytes: Uint8Array, mediaType: string): string;
     private inspector;
+    /**
+     * Read the document the way its READER reads it, whatever is on screen.
+     *
+     * The model these reads walk is derived per revision view, and markup view
+     * keeps deleted runs in it so a reviewer can see the strike-through. Right
+     * for a screen, wrong for an agent: the AI panel turns suggesting on for its
+     * turn, which forces markup, so a SECOND suggestion projected the pending
+     * insertion and the pending deletion interleaved — "The quick brown fox
+     * leajumps over the lazy dog" for a document that reads "leaps". The model
+     * then either rewrote a string no human had ever seen, or, because deleted
+     * runs are not editable text, got "cannot be rewritten across a non-text
+     * atom" and could not stack a second change at all.
+     *
+     * So every model-derived read runs in final view: insertions are text,
+     * deletions are gone — the document as it will read once the suggestions are
+     * accepted. Only the READS move. The operations they produce address runs by
+     * stable id, at offsets within a run's own text; both are properties of the
+     * XML and mean the same thing in either view, so applying them needs no
+     * switch and the view on screen never flickers.
+     */
+    private inFinalView;
     asset(ref: string): AgentAsset;
     inspect(request: AgentInspectRequest): AgentInspectResult;
+    private inspectFinal;
     private recordInspection;
+    /** Fingerprints are recorded during a final-view read, so they have to be
+     * re-taken in one: compared across views, every block holding a tracked
+     * change reads as concurrently edited and the patch dies as "stale". */
+    private fingerprintsMatch;
     private revisionMatchesEdit;
+    /** Render the document as deterministic text plus the anchor map that owns
+     * the rendered-to-wire translation. Read-only: nothing here mutates. */
+    project(request?: AgentProjectRequest): AgentProjectResult;
+    private projectFinal;
+    patch(request: AgentPatchRequest): Promise<AgentPatchResult>;
+    private patchWindow;
     capabilities(category?: AgentEditCapability["category"], kind?: Intent["kind"]): ReturnType<typeof agentCapabilities>;
     compose(request: AgentComposeRequest): Promise<AgentComposeResult>;
+    private composeDocument;
     edit(request: AgentEditRequest): Promise<AgentEditResult>;
+    /** The transaction itself. patch() and compose() call this rather than
+     * edit(), so each states the rollback in its own caller's terms instead of
+     * telling a patch author to resend "operations" it never sent. */
+    private editTransaction;
     private editLocal;
     private editCollaborative;
     save(): Uint8Array;
@@ -3050,8 +4472,23 @@ declare class LocalDocumentSession implements AgentCollaborativeTarget {
     allocIds: (count: number) => number[];
     subscribe(listener: () => void): () => void;
     takeRenderScope: () => Scope | null;
+    /**
+     * Called immediately before an intent mutates the document.
+     *
+     * A host that also renders this document — the desktop app, whose editor owns
+     * an undo stack — sets this to take a checkpoint, so an edit made by an agent
+     * is reachable with Cmd+Z like any other. Without it the agent's changes are
+     * applied behind the editor's back: undo cannot reverse them, and structural
+     * ones have no tracked form to reject either, leaving no way back.
+     */
+    onBeforeApply: (() => void) | null;
     submit: (operation: IntentBody) => void;
     submitOp: (operation: IntentBody) => void;
+    /** Record a local history undo/redo that mutated the shared doc outside the
+     * intent path (the editor already re-rendered itself). Matches the
+     * pre-applied contract: bump the revision so agent-side caches keyed on it
+     * (projections, inspection fingerprints) never serve the pre-undo tree. */
+    noteHistory: () => void;
     /** Record an operation that DocxView already applied to this same object. */
     submitPreApplied: (operation: IntentBody) => void;
     uploadMedia(bytes: Uint8Array): Promise<{
@@ -3059,6 +4496,15 @@ declare class LocalDocumentSession implements AgentCollaborativeTarget {
         bytesLen: number;
     }>;
     private fullIntent;
+    /**
+     * Fill the part an operation just reserved with the bytes this session is
+     * already holding.
+     *
+     * Keyed on the blobSha the operation carries, not on its kind: the sha IS
+     * the media reservation, and every operation that reserves media carries
+     * one (insertImage, insertPictureWatermark). Naming one kind here left
+     * every later one's picture pending forever.
+     */
     private installUploadedImage;
 }
 interface LocalDocumentViewBinding {
@@ -3072,6 +4518,7 @@ interface LocalDocumentViewBinding {
         blobSha: string;
         bytesLen: number;
     }>;
+    noteHistory(): void;
     takeRenderScope(): {
         kind: "doc";
     } | {
@@ -3085,8 +4532,39 @@ interface LocalDocumentViewBinding {
 }
 declare function localDocumentViewBinding(session: LocalDocumentSession): LocalDocumentViewBinding;
 
+/** Whether `suggest: true` on this kind records a revision. A kind outside the
+ * set applies outright, so the flag is dropped rather than promised. */
+declare function isSuggestable(kind: unknown): boolean;
+/** Whether a tableOp's `op` has a tracked form, so it may run while
+ * suggesting. The structural ops are plain strings and never qualify. */
+declare function isSuggestableTableOp(op: unknown): boolean;
+
 type JsonSchema = Record<string, unknown>;
 declare const AGENT_COMPOSE_SCHEMA: JsonSchema;
 declare function validateAgentComposeRequest(input: unknown): string | null;
 
-export { AGENT_COMPOSE_SCHEMA, AGENT_EDIT_CAPABILITIES, type AgentAsset, type AgentBlock, type AgentBorder, type AgentCollaborativeTarget, type AgentComponentSummary, type AgentComposeBlock, type AgentComposeCell, type AgentComposeRequest, type AgentComposeResult, type AgentComposeRun, type AgentComposeTextStyle, type AgentContextParagraph, type AgentContextResult, type AgentContextRun, type AgentContextStory, type AgentContextTable, type AgentCursor, AgentDocument, type AgentEditCapability, type AgentEditRequest, type AgentEditResult, type AgentInspectRequest, type AgentInspectResult, type AgentObjectResult, type AgentOperation, type AgentOverlap, type AgentOverview, type AgentPageBorders, type AgentParagraph, type AgentProvenance, type AgentReadResult, type AgentReference, type AgentRun, type AgentSearchResult, type AgentSectionLayout, type AgentSpatialObject, type AgentSpatialResult, type AgentTable, type AgentTool, LocalDocumentSession, type LocalDocumentViewBinding, type OutlineEntry, type SpatialBounds, agentCapabilities, agentOperationSchema, collaborativeAgentTarget, localDocumentViewBinding, validateAgentComposeRequest, validateAgentOperationShape };
+/**
+ * DocMD: a deterministic text projection of a story, produced in the same pass
+ * as the anchor map that owns the rendered-to-wire offset translation.
+ *
+ * Inspection offsets are rendered text and edit offsets are wire units, and
+ * reconciling the two used to be the caller's problem. Here the two spaces are
+ * derived together: every projected character belongs to exactly one anchor
+ * segment, and a segment is editable only when it came verbatim from one `w:t`
+ * — the one case where a projection column is also a wire offset. Agents read
+ * the text; the segments do the arithmetic.
+ */
+/** Single-character stand-ins for inline content with no editable text. One
+ * character each, so a projection column always names one whole atom and the
+ * anchor map can mark it opaque without span arithmetic. */
+declare const DOCMD_ATOMS: {
+    readonly tab: "␉";
+    readonly lineBreak: "␊";
+    readonly pageBreak: "␌";
+    readonly field: "␎";
+    readonly math: "␏";
+    readonly noteReference: "␅";
+    readonly object: "";
+};
+
+export { AGENT_COMPOSE_SCHEMA, AGENT_EDIT_CAPABILITIES, type AgentAnchorLine, type AgentAnchorSegment, type AgentAsset, type AgentBlock, type AgentBorder, type AgentCollaborativeTarget, type AgentComponentSummary, type AgentComposeBlock, type AgentComposeCell, type AgentComposeRequest, type AgentComposeResult, type AgentComposeRun, type AgentComposeTextStyle, type AgentContextParagraph, type AgentContextResult, type AgentContextRun, type AgentContextStory, type AgentContextTable, type AgentCursor, AgentDocument, type AgentDrawingFit, type AgentEditCapability, type AgentEditRequest, type AgentEditResult, type AgentFitResult, type AgentInspectRequest, type AgentInspectResult, type AgentObjectResult, type AgentOperation, type AgentOverlap, type AgentOverview, type AgentPageBorders, type AgentParagraph, type AgentPatchHunk, type AgentPatchRequest, type AgentPatchResult, type AgentProjectRequest, type AgentProjectResult, type AgentProjectionMode, type AgentProvenance, type AgentReadResult, type AgentReference, type AgentRun, type AgentSearchResult, type AgentSectionLayout, type AgentSpatialObject, type AgentSpatialResult, type AgentTable, type AgentTool, DOCMD_ATOMS, LocalDocumentSession, type LocalDocumentViewBinding, type OutlineEntry, type SpatialBounds, agentCapabilities, agentOperationSchema, collaborativeAgentTarget, hoistRepeatedSubschemas, isSuggestable, isSuggestableTableOp, localDocumentViewBinding, validateAgentComposeRequest, validateAgentOperationShape };