@wordinweb/agent 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,3092 @@
+/**
+ * Minimal, fast XML parser producing a lightweight element tree.
+ *
+ * OOXML parts are machine-generated, namespace-prefixed, well-formed XML with
+ * no DTDs. This parser handles exactly that subset: elements, attributes,
+ * text, CDATA, comments, processing instructions, and the built-in + numeric
+ * character entities. Namespace prefixes are kept verbatim (`w:p`), and
+ * lookups match on either the full name or the local name, which is robust
+ * for every mainstream producer (Word, LibreOffice, Google Docs export).
+ */
+interface XmlElement {
+    name: string;
+    attrs: Record<string, string>;
+    children: XmlElement[];
+    /** Concatenated character data directly inside this element. */
+    text: string;
+    /** Editor placeholder retained in memory but omitted from XML while empty. */
+    omitWhenEmpty?: boolean;
+}
+
+/**
+ * Typed document model produced by the parser and consumed by the layout
+ * engine. All lengths are CSS px (see units.ts) unless a field name says
+ * otherwise. Property bags are Partial-style: `undefined` means "not set at
+ * this level" so the style-inheritance merge can distinguish absence from an
+ * explicit value.
+ *
+ * Model nodes keep `src` references to the XML elements they were parsed
+ * from: the XML tree is the source of truth for editing — commands mutate it
+ * and the model is re-derived, which preserves round-trip fidelity for
+ * everything untouched.
+ */
+
+type BorderStyle = "none" | "single" | "double" | "dotted" | "dashed" | "thick" | "wave" | "dotDash" | "dotDotDash" | "thinThickSmallGap" | "triple";
+interface Border {
+    style: BorderStyle;
+    /** Stroke width in px. */
+    width: number;
+    /** CSS color. */
+    color: string;
+    /** Gap between border and content in px (w:space, points in OOXML). */
+    space: number;
+    /** Declared stroke width in px BEFORE the 0.75px paint floor (w:sz/8 pt).
+     * Word's LAYOUT math (table row border share) uses this true width — a
+     * sz-4 rule contributes 0.5pt, not the floored 0.5625pt (phase23 p66:
+     * 45 rows drift 2.5px down without it). */
+    rawWidth?: number;
+}
+interface ParagraphBorders {
+    top?: Border;
+    bottom?: Border;
+    left?: Border;
+    right?: Border;
+    /** Drawn between consecutive paragraphs that both specify it. */
+    between?: Border;
+}
+type LineSpacingRule = "auto" | "atLeast" | "exact";
+interface LineSpacing {
+    rule: LineSpacingRule;
+    /**
+     * For "auto": multiple of single line height (240ths in OOXML, stored here
+     * as the multiplier, e.g. 1.15). For atLeast/exact: px.
+     */
+    value: number;
+}
+type Alignment = "left" | "center" | "right" | "justify";
+interface TabStop {
+    /** px from the left text edge */
+    pos: number;
+    align: "left" | "center" | "right" | "decimal" | "bar";
+    leader: "none" | "dot" | "hyphen" | "underscore" | "middleDot";
+    /** w:val="clear": removes the inherited stop at this pos when tab lists
+     * merge down the style chain (never a live stop itself). */
+    clear?: boolean;
+}
+interface RunProps {
+    bold?: boolean;
+    italic?: boolean;
+    underline?: string;
+    strike?: boolean;
+    doubleStrike?: boolean;
+    /** Resolved primary font family name (ascii/hAnsi, theme-resolved). */
+    font?: string;
+    /** East Asian font (rFonts w:eastAsia): used for CJK codepoints. */
+    fontEastAsia?: string;
+    /** hAnsi font (rFonts w:hAnsi, theme-resolved): Word uses this channel for
+     * non-ASCII, non-CJK, non-complex characters (curly quotes, ≤, dashes). A
+     * run that declares only w:ascii leaves it inherited from the style chain. */
+    fontHAnsi?: string;
+    /** Complex-script font (rFonts w:cs): used for RTL/complex runs. */
+    fontComplex?: string;
+    /** w:rtl — this run's text is right-to-left (Arabic/Hebrew). */
+    rtl?: boolean;
+    /** Font size in px. */
+    size?: number;
+    /** CSS color; "auto" resolved to inherit/black by renderer. */
+    color?: string;
+    highlight?: string;
+    /** Character shading fill (w:shd). */
+    shading?: string;
+    /** Run border (w:bdr): a box painted around the run. Word merges adjacent
+     * runs with identical borders into one box; a run wrapping across lines
+     * closes the box on every line segment. */
+    border?: Border;
+    verticalAlign?: "baseline" | "superscript" | "subscript";
+    caps?: boolean;
+    smallCaps?: boolean;
+    /** Letter spacing px (w:spacing, twips in OOXML). */
+    letterSpacing?: number;
+    /** Minimum font size in px at which w:kern enables pair kerning; null is
+     * the explicit w:kern=0 override. */
+    kerningThreshold?: number | null;
+    /** Paint-only letter spacing when layout advances intentionally differ. */
+    paintLetterSpacing?: number;
+    /** w:w horizontal character scaling as a fraction (1.5 = 150%). */
+    textScale?: number;
+    /** w:fitText target width in px: the run's advances scale so its text
+     * occupies exactly this width (resolved to textScale at layout time). */
+    fitText?: number;
+    /** w:position baseline shift in px, positive = raised. */
+    raise?: number;
+    /** w:outline — hollow stroked glyphs. */
+    outline?: boolean;
+    /** w:emboss / w:imprint — Word triple-draws offset copies. */
+    emboss?: boolean;
+    imprint?: boolean;
+    vanish?: boolean;
+    /** Character style id (w:rStyle). */
+    styleId?: string;
+    lang?: string;
+}
+interface NumberingRef {
+    numId: number;
+    ilvl: number;
+}
+interface ParaProps {
+    styleId?: string;
+    alignment?: Alignment;
+    /** The exact OOXML w:jc value when it is a "justify" flavor whose behavior
+     * differs from plain "both": `distribute` also stretches the LAST line, and
+     * the Arabic `*Kashida` levels elongate glyphs (kashida) so lines pack fewer
+     * words and — at medium/high — wrap to more lines. Absent for plain "both".
+     * `alignment` stays "justify" for all of these. */
+    justifyKind?: "distribute" | "lowKashida" | "mediumKashida" | "highKashida";
+    /** w:bidi — right-to-left paragraph: lines assemble RTL and default
+     * alignment flips to the right edge. */
+    bidi?: boolean;
+    /** px */
+    indentLeft?: number;
+    indentRight?: number;
+    /** Positive px; mutually exclusive with hanging in effect. */
+    indentFirstLine?: number;
+    /** Positive px hanging indent. */
+    indentHanging?: number;
+    spacingBefore?: number;
+    spacingAfter?: number;
+    /** w:beforeAutospacing/afterAutospacing: HTML-style automatic paragraph
+     * spacing — Word ignores the literal before/after and inserts one blank
+     * line's worth of space. */
+    beforeAutospacing?: boolean;
+    afterAutospacing?: boolean;
+    /** Word's default when absent is auto/1.0 via docDefaults. */
+    lineSpacing?: LineSpacing;
+    /** w:snapToGrid: whether this paragraph's lines use the section docGrid. */
+    snapToGrid?: boolean;
+    contextualSpacing?: boolean;
+    keepNext?: boolean;
+    /** w:framePr w:dropCap: the paragraph is a drop-cap letter frame. */
+    dropCap?: {
+        mode: "drop" | "margin";
+        lines: number;
+        hSpace: number;
+        pageAnchored?: boolean;
+    };
+    /** w:framePr positioned text frame (absolute-positioned paragraph the body
+     * text wraps around). Geometry in px. Individual attributes are optional so a
+     * framePr merges attribute-by-attribute across the style cascade (a direct
+     * framePr that sets only h/x/y keeps the style framePr's width/anchor — IEEE
+     * authors); the engine normalizes defaults at layout time. */
+    frame?: {
+        w?: number;
+        h?: number;
+        hRule?: "auto" | "atLeast" | "exact";
+        x?: number;
+        y?: number;
+        hAnchor?: "page" | "margin" | "text" | "column";
+        vAnchor?: "page" | "margin" | "text" | "paragraph";
+        xAlign?: "left" | "center" | "right" | "inside" | "outside";
+        yAlign?: "top" | "center" | "bottom" | "inside" | "outside" | "inline";
+        wrap?: "around" | "auto" | "notBeside" | "through" | "tight" | "none";
+        /** w:hSpace / w:vSpace: horizontal/vertical margin around the frame (px). */
+        hSpace?: number;
+        vSpace?: number;
+    };
+    keepLines?: boolean;
+    pageBreakBefore?: boolean;
+    widowControl?: boolean;
+    borders?: ParagraphBorders;
+    /** Paragraph shading fill as CSS color. */
+    shading?: string;
+    numbering?: NumberingRef | null;
+    /** A numPr that carries ilvl but no numId (Heading3 basedOn Heading2)
+     * overrides only the list LEVEL, keeping the inherited numId; the style
+     * chain applies it to `numbering` on merge. */
+    numberingLevelOverride?: number;
+    tabs?: TabStop[];
+    outlineLevel?: number;
+    /** Run props declared on pPr/rPr — apply to the paragraph mark & numbering label. */
+    markRunProps?: RunProps;
+    /**
+     * styleId of the enclosing table (set on cell paragraphs at parse time).
+     * A table style's own pPr layers between docDefaults and the paragraph
+     * style, e.g. TableGrid's `spacing after=0 line=240` overrides docDefaults'
+     * `after=200 line=276` so list cells lay out compactly.
+     */
+    tableStyleId?: string;
+    /**
+     * Grid position of the enclosing cell plus the table's tblLook (set on cell
+     * paragraphs at parse time, like tableStyleId). Lets run/paragraph
+     * resolution layer the applicable w:tblStylePr conditional formats (e.g.
+     * firstRow bold + white) between the table style's own rPr and the
+     * paragraph style chain.
+     */
+    tableCellCond?: {
+        look?: TableLook;
+        rowIdx: number;
+        nRows: number;
+        colStart: number;
+        colSpan: number;
+        nCols: number;
+    };
+}
+interface TextContent {
+    kind: "text";
+    text: string;
+    /** Source w:t element inside the run, when this text came verbatim from one. */
+    srcT?: XmlElement;
+    /** When this text is the glyph of a modern checkbox content control, the
+     * source `w14:checkbox` element (in the enclosing w:sdt's sdtPr). Its
+     * presence makes the glyph a click-to-toggle target rather than plain text. */
+    checkbox?: XmlElement;
+}
+interface BreakContent {
+    kind: "break";
+    breakType: "line" | "page" | "column";
+}
+interface TabContent {
+    kind: "tab";
+}
+interface PTabContent {
+    kind: "ptab";
+    /** Absolute-position tab: jump to left/center/right of the base. */
+    alignment: "left" | "center" | "right";
+    relativeTo: "margin" | "indent";
+}
+interface ImageContent {
+    kind: "image";
+    /** Part path of the image inside the package. */
+    part: string;
+    width: number;
+    height: number;
+    /** True when the drawing is floating (wp:anchor); v1 lays it out inline. */
+    anchored?: boolean;
+    /** a:srcRect crop, fractions of the source bitmap. */
+    crop?: {
+        l: number;
+        t: number;
+        r: number;
+        b: number;
+    };
+    /** a:xfrm rotation, degrees clockwise. */
+    rotation?: number;
+    /** a:ln picture outline (Word draws it just outside the image). */
+    border?: {
+        color: string;
+        width: number;
+    };
+    /** Source w:drawing (or pict) element, for resize/move editing. */
+    srcDrawing?: XmlElement;
+    /** Native Office 3D model shown through its saved poster raster. */
+    model3D?: Model3DReference;
+    /** Word online-video metadata shown through its saved poster raster. */
+    webVideo?: WebVideoReference;
+    /** Embedded OLE package activated as a safe download in the browser. */
+    embeddedObject?: EmbeddedObjectReference;
+}
+interface Model3DReference {
+    part: string;
+    posterPart: string;
+    /** Native Office model orientation, in degrees around the X/Y/Z axes. */
+    rotation?: {
+        x: number;
+        y: number;
+        z: number;
+    };
+}
+interface WebVideoReference {
+    url: string;
+    embeddedHtml: string;
+    width: number;
+    height: number;
+}
+interface EmbeddedObjectReference {
+    part: string;
+    filename: string;
+    progId: string;
+}
+/** OMML equation node (subset: runs, scripts, fractions, radicals). */
+type MathNode = {
+    t: "run";
+    text: string;
+    normal?: boolean;
+    /** m:func function name (cos, log, …): Word kerns a thin space on
+     * both sides of the name. */
+    fname?: boolean;
+} | {
+    t: "sup" | "sub";
+    base: MathNode[];
+    script: MathNode[];
+} | {
+    t: "frac";
+    num: MathNode[];
+    den: MathNode[];
+    bar?: boolean;
+}
+/** Radical; deg is the optional m:deg index (∛), absent when m:degHide. */
+ | {
+    t: "rad";
+    e: MathNode[];
+    deg?: MathNode[];
+}
+/** n-ary operator (sum/integral); chr defaults to the integral sign. */
+ | {
+    t: "nary";
+    chr: string;
+    sub: MathNode[];
+    sup: MathNode[];
+    e: MathNode[];
+}
+/** Delimiters grown to the content height; beg/end default to parens.
+ * An empty beg/end string means that side has no delimiter (cases "{"). */
+ | {
+    t: "dlm";
+    beg: string;
+    end: string;
+    e: MathNode[][];
+}
+/** Matrix: rows x cells. */
+ | {
+    t: "mat";
+    rows: MathNode[][][];
+}
+/** m:eqArr equation array (cases/piecewise rows). */
+ | {
+    t: "eqarr";
+    rows: MathNode[][];
+}
+/** m:acc combining accent (hat/bar/vector) over the base. */
+ | {
+    t: "acc";
+    chr: string;
+    e: MathNode[];
+}
+/** m:groupChr horizontal group character (over/under brace). */
+ | {
+    t: "grp";
+    chr: string;
+    pos: "top" | "bot";
+    vertJc: "top" | "bot";
+    e: MathNode[];
+}
+/** m:limLow / m:limUpp limit stacked under/over a text operator. */
+ | {
+    t: "lim";
+    pos: "low" | "upp";
+    e: MathNode[];
+    lim: MathNode[];
+};
+interface MathContent {
+    kind: "math";
+    nodes: MathNode[];
+    /** Source m:oMath element (math editing). */
+    src?: XmlElement;
+    /** Display equation (wrapped in m:oMathPara): centered on its own line with
+     * display-style layout - larger n-ary operators with limits stacked
+     * above/below, and full-size fraction numerators/denominators. */
+    display?: boolean;
+    /** Display group with several direct equations. Word leaves a small
+     * advance after script clusters in these grouped displays. */
+    multiEquationDisplay?: boolean;
+    /** m:oMathParaPr/m:jc - display-equation justification. Absent: the
+     * document default (settings m:mathPr/m:defJc, itself "centerGroup" when
+     * unset). */
+    jc?: "left" | "right" | "center" | "centerGroup";
+}
+interface FieldContent {
+    kind: "field";
+    /** Raw field instruction, e.g. ` PAGE \\* MERGEFORMAT `. */
+    instruction: string;
+    /** Last cached result text from the file, used for unsupported fields. */
+    cachedResult: string;
+    /** When this field is a legacy FORMCHECKBOX, the source `w:checkBox` element
+     * (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;
+}
+/** What an anchored shape's coordinates are measured from. "char" (relH=
+ * "character") measures from the anchor run's pen position; "line" (relV=
+ * "line") from the top of the line holding the anchor — both resolved from
+ * the anchor paragraph's first-pass layout. */
+type AnchorRel = "page" | "margin" | "text" | "column" | "char" | "line";
+interface ShapeLine {
+    type: "line";
+    x1: number;
+    y1: number;
+    x2: number;
+    y2: number;
+    color: string;
+    /** Stroke weight px. */
+    weight: number;
+    style?: "single" | "dotted" | "dashed";
+    hRel: AnchorRel;
+    vRel: AnchorRel;
+    /** Source VML v:line for selection and save-back editing. */
+    src?: XmlElement;
+}
+interface ShapeTextbox {
+    type: "textbox";
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+    hRel: AnchorRel;
+    vRel: AnchorRel;
+    blocks: Block[];
+    /** Background fill (CSS color) painted behind the text. */
+    fill?: string;
+    /** Outline. */
+    stroke?: {
+        color: string;
+        weight: number;
+    };
+    /** Alignment-based positioning (mso-position-horizontal/vertical). */
+    hAlign?: "left" | "center" | "right";
+    vAlign?: "top" | "center" | "bottom";
+    /** Percent-of-base geometry, 0..1 (mso-*-percent / wp14 pct offsets).
+     * Bases: pctWidthRel/pctHeightRel say page vs margin. */
+    pctX?: number;
+    pctY?: number;
+    pctWidth?: number;
+    pctHeight?: number;
+    pctWidthRel?: "page" | "margin";
+    pctHeightRel?: "page" | "margin";
+    /** Vertical anchoring of the text INSIDE the box (v-text-anchor). */
+    textAnchor?: "top" | "middle" | "bottom";
+    /** How body text flows around a DrawingML textbox (wp:wrap*). */
+    wrap?: WrapMode;
+    /** behindDoc: paint under the body text, never displace it. */
+    behind?: boolean;
+    /** wp:anchor @allowOverlap="0": Word shifts this shape clear of earlier
+     * overlapping floats rather than letting them overlap. Default true. */
+    allowOverlap?: boolean;
+    /** Wrap distances px (wp:anchor distT/B/L/R). */
+    dist?: {
+        t: number;
+        b: number;
+        l: number;
+        r: number;
+    };
+    /** a:xfrm rotation, degrees clockwise (rotates the whole box). */
+    rotation?: number;
+    /** Text insets px (bodyPr lIns/tIns/rIns/bIns); default 9.6/4.8. For
+     * non-rect preset geometries these INCLUDE the geometry's text-rectangle
+     * insets (ellipse: inscribed rect; diamond: middle-half rect). */
+    insets?: {
+        l: number;
+        t: number;
+        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. */
+    geom?: {
+        d: string;
+        viewW: number;
+        viewH: number;
+    };
+    /** 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:
+     * "Was 0 / B" visible, the wrapped tail rows hidden). */
+    clipText?: boolean;
+    /** bodyPr a:spAutoFit: the box grows in height to exactly fit its laid text
+     * plus the top/bottom insets (the stored cy is only Word's last cached
+     * value). Width is fixed. */
+    autofitHeight?: 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
+     * overflow. */
+    chainId?: string;
+    /** Position in the linked chain (0 = the content box). */
+    chainSeq?: number;
+    /** Source w:drawing element, attached at parse time so the shape's fill can
+     * be an interactive hit target (select the shape instead of the body text
+     * behind it). */
+    srcDrawing?: XmlElement;
+    /** Header/footer-owned textbox whose text is edited as an independent story. */
+    textboxStory?: boolean;
+    /** DrawingML WordArt, including the identity textNoShape preset. */
+    wordArt?: boolean;
+    /** WordArt glyph fill from w14:textFill or the fallback run color. */
+    wordArtFill?: string;
+    /** WordArt glyph alpha, 0..1. */
+    wordArtOpacity?: number;
+    /** bodyPr a:prstTxWarp preset name (textArchUp, textWave1, textChevron,
+     * textCirclePour, …): the shape's text is bent onto the preset's envelope
+     * rather than flowed as ordinary lines. "textNoShape" (no warp) is dropped. */
+    warp?: string;
+}
+/** WordArt (VML v:textpath, e.g. a "CONFIDENTIAL" watermark): text scaled to
+ * fill a box, optionally rotated, painted semi-transparent behind the body. */
+interface ShapeWordArt {
+    type: "wordart";
+    text: string;
+    fontFamily: string;
+    bold?: boolean;
+    italic?: boolean;
+    /** CSS fill color. */
+    fill: string;
+    /** 0..1 alpha. */
+    opacity: number;
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+    hRel: AnchorRel;
+    vRel: AnchorRel;
+    hAlign?: "left" | "center" | "right";
+    vAlign?: "top" | "center" | "bottom";
+    /** Clockwise degrees. */
+    rotation: number;
+    behind?: boolean;
+    /** The source v:textpath font-size (px). */
+    fontSize?: number;
+    /** The referenced v:shapetype has a malformed text-guide path (missing
+     * coordinates), so Word collapses its horizontal glyph outlines into a thin
+     * vertical band instead of painting a box-filling watermark. */
+    noFit?: boolean;
+    /** Source VML shape element (v:shape / v:rect) for interactive editing:
+     * the v:textpath string, fill/opacity, and rotation live under it. */
+    src?: XmlElement;
+}
+interface ShapeArt {
+    type: "art";
+    srcDrawing?: XmlElement;
+    /** A freehand stroke, selectable by the Draw ribbon's stroke eraser. */
+    ink?: boolean;
+    x: number;
+    y: number;
+    /** Percent-of-page offsets (wp14:pctPos*Offset), 0..1. */
+    pctX?: number;
+    pctY?: number;
+    width: number;
+    height: number;
+    hRel: AnchorRel;
+    vRel: AnchorRel;
+    hAlign?: "left" | "center" | "right";
+    vAlign?: "top" | "center" | "bottom";
+    behind?: boolean;
+    /** a:xfrm rotation, degrees clockwise. */
+    rotation?: number;
+    lines: DrawingLine[];
+    images: DrawingImage[];
+    paths: DrawingPath[];
+    /** Positioned text bodies inside the group (wps textboxes, dsp:sp txBody). */
+    texts?: DrawingTextShape[];
+}
+/** How text interacts with a floating image. */
+type WrapMode = "square" | "topAndBottom" | "none";
+interface ShapeImage {
+    type: "image";
+    part: string;
+    /** Offset from the anchor origin, px. */
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+    hRel: AnchorRel;
+    vRel: AnchorRel;
+    /** Horizontal alignment when the file uses wp:align instead of an offset. */
+    hAlign?: "left" | "center" | "right";
+    /** Vertical alignment keyword (VML mso-position-vertical; watermarks center). */
+    vAlign?: "top" | "center" | "bottom";
+    wrap: WrapMode;
+    /** behindDoc anchors render under the text and never displace it. */
+    behind?: boolean;
+    /** Wrap distances px (wp:anchor distT/B/L/R); text clears the image by these. */
+    dist?: {
+        t: number;
+        b: number;
+        l: number;
+        r: number;
+    };
+    crop?: {
+        l: number;
+        t: number;
+        r: number;
+        b: number;
+    };
+    rotation?: number;
+    /** Watermark "washout" recolor (VML v:imagedata gain/blacklevel, 0..1). */
+    washout?: {
+        gain: number;
+        blacklevel: number;
+    };
+    /** Source w:drawing element (editing). */
+    srcDrawing?: XmlElement;
+    model3D?: Model3DReference;
+    webVideo?: WebVideoReference;
+    embeddedObject?: EmbeddedObjectReference;
+}
+type Shape = (ShapeLine | ShapeTextbox | ShapeImage | ShapeArt | ShapeWordArt) & {
+    /** wp:anchor relativeHeight, used for object stacking order. */
+    z?: number;
+};
+/**
+ * Floating/anchored object: does not occupy inline space; positioned against
+ * page/margin/paragraph during layout. (How classic pleading paper draws its
+ * margin line numbers and vertical rules.)
+ */
+interface AnchorContent {
+    kind: "anchor";
+    shape: Shape;
+}
+/** A stroked segment inside a composite drawing, px relative to its box. */
+interface DrawingLine {
+    x1: number;
+    y1: number;
+    x2: number;
+    y2: number;
+    color: string;
+    weight: number;
+    style?: "single" | "dotted" | "dashed";
+}
+interface DrawingImage {
+    part: string;
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+    crop?: {
+        l: number;
+        t: number;
+        r: number;
+        b: number;
+    };
+    rotation?: number;
+    /** a:ln picture outline (Word draws it just outside the image). */
+    border?: {
+        color: string;
+        width: number;
+    };
+}
+/**
+ * Composite inline drawing (DrawingML groups): vector lines + placed images
+ * inside a width×height box that flows like an image.
+ */
+interface DrawingContent {
+    kind: "drawing";
+    width: number;
+    height: number;
+    lines: DrawingLine[];
+    images: DrawingImage[];
+    /** Native ChartML chart data resolved from the related chart part. */
+    chart?: ChartData;
+    /** Native SmartArt diagram data resolved from its diagram parts. */
+    smartArt?: SmartArtData;
+    /** Freeform vector shapes (a:custGeom), as SVG path data. */
+    paths?: DrawingPath[];
+    /** An INLINE wps text box (wp:inline wps:txbx): a fixed-extent box that
+     * flows in the text (occupying its width x height like an inline image) and
+     * carries a fill/border + its own block content. Distinct from the floating
+     * ShapeTextbox, which is absolutely placed via a wp:anchor. */
+    textbox?: {
+        blocks: Block[];
+        fill?: string;
+        stroke?: {
+            color: string;
+            weight: number;
+        };
+        insets?: {
+            l: number;
+            t: number;
+            r: number;
+            b: number;
+        };
+        textAnchor?: "top" | "middle" | "bottom";
+    };
+    /** Source w:drawing element (select/move as a group). */
+    srcDrawing?: XmlElement;
+    /** Positioned text bodies inside the drawing (multi-textbox groups and
+     * SmartArt cached-drawing shapes). Painted above lines/paths. */
+    texts?: DrawingTextShape[];
+}
+type ChartType = "column" | "bar" | "line" | "pie";
+interface ChartSeries {
+    name: string;
+    values: number[];
+}
+interface ChartData {
+    type: ChartType;
+    title?: string;
+    categories: string[];
+    series: ChartSeries[];
+}
+type SmartArtLayout = "process" | "cycle" | "hierarchy" | "list";
+interface SmartArtData {
+    layout: SmartArtLayout;
+    items: string[];
+}
+/** A text body positioned inside a composite drawing (a wps textbox in a
+ * group, or a SmartArt dsp:sp txBody), px relative to the drawing's box. */
+interface DrawingTextShape {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+    blocks: Block[];
+    /** Background fill painted behind the text box. */
+    fill?: string;
+    /** Outline. */
+    stroke?: {
+        color: string;
+        weight: number;
+    };
+    /** Text insets px (bodyPr lIns/tIns/rIns/bIns). */
+    insets: {
+        l: number;
+        t: number;
+        r: number;
+        b: number;
+    };
+    /** Vertical anchoring of the text inside the box (bodyPr anchor). */
+    textAnchor?: "top" | "middle" | "bottom";
+    /** DrawingML cached text paint-only baseline adjustment in px. */
+    paintOffsetY?: number;
+}
+interface DrawingPath {
+    /** Position/size inside the drawing, px. */
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+    /** SVG path in the `viewW x viewH` source coordinate space. */
+    d: string;
+    viewW: number;
+    viewH: number;
+    fill?: string;
+    stroke?: {
+        color: string;
+        width: number;
+        opacity?: number;
+    };
+    /** Zero-based visible SmartArt node this path paints. */
+    smartArtNodeIndex?: number;
+}
+/**
+ * Footnote/endnote reference mark. In body text (w:footnoteReference /
+ * w:endnoteReference) `id` points into the notes part. Inside a note body,
+ * w:footnoteRef / w:endnoteRef render the note's own mark: `self` is true and
+ * `id` is meaningless.
+ */
+interface NoteRefContent {
+    kind: "noteRef";
+    noteType: "footnote" | "endnote";
+    id: number;
+    self?: boolean;
+    /** The document supplies the visible mark in the following run content. */
+    customMarkFollows?: boolean;
+}
+/** w:ruby — an East-Asian ruby (furigana) cluster: an annotation run (w:rt)
+ * riding above a base run (w:rubyBase). Both sides render as their own runs;
+ * the annotation is centered over the base and raised above its baseline. */
+interface RubyContent {
+    kind: "ruby";
+    base: Run;
+    rt: Run;
+    /** w:rubyPr/w:hpsRaise — annotation baseline raise above the base baseline,
+     * half-points. */
+    hpsRaise?: number;
+    /** w:rubyPr/w:rubyAlign — how the annotation distributes over the base. */
+    align?: "center" | "distributeLetter" | "distributeSpace" | "left" | "right" | "rightVertical";
+}
+type RunContent = MathContent | TextContent | BreakContent | TabContent | PTabContent | ImageContent | FieldContent | AnchorContent | DrawingContent | NoteRefContent | RubyContent;
+interface Run {
+    type: "run";
+    props: RunProps;
+    content: RunContent[];
+    /** Source w:r element. */
+    src?: XmlElement;
+    /** Element whose children array contains src (w:p, w:hyperlink, …). */
+    srcParent?: XmlElement;
+}
+interface Hyperlink {
+    type: "hyperlink";
+    href?: string;
+    anchor?: string;
+    runs: Run[];
+}
+type ParaChild = Run | Hyperlink;
+interface Paragraph {
+    type: "paragraph";
+    props: ParaProps;
+    children: ParaChild[];
+    /** Section break attached to this paragraph's pPr (ends a section). */
+    sectionBreak?: SectionProps;
+    /** w:bookmarkStart names in this paragraph (PAGEREF targets). */
+    bookmarks?: string[];
+    /** Final revision view: the paragraph mark AND all content are tracked
+     * deletions — the paragraph does not exist (no line, no numbering). */
+    revisionHidden?: boolean;
+    /** Source w:p element. */
+    src?: XmlElement;
+}
+interface TableCellProps {
+    /** Preferred width px (from tcW when dxa). */
+    width?: number;
+    /** The source explicitly declares tcW type="auto" (distinct from no tcW). */
+    widthAuto?: boolean;
+    gridSpan: number;
+    vMerge?: "restart" | "continue";
+    borders?: {
+        top?: Border;
+        bottom?: Border;
+        left?: Border;
+        right?: Border;
+        tl2br?: Border;
+        tr2bl?: Border;
+    };
+    shading?: string;
+    /** Cell margins px. */
+    margins?: {
+        top?: number;
+        right?: number;
+        bottom?: number;
+        left?: number;
+    };
+    verticalAlign?: "top" | "center" | "bottom";
+    textDirection?: "btLr" | "tbRl";
+}
+interface TableCell {
+    props: TableCellProps;
+    blocks: Block[];
+}
+interface TableRowProps {
+    /** px; undefined = auto */
+    height?: number;
+    heightRule?: "auto" | "atLeast" | "exact";
+    cantSplit?: boolean;
+    /** Repeat as header row on each page. */
+    tblHeader?: boolean;
+}
+interface TableRow {
+    props: TableRowProps;
+    cells: TableCell[];
+}
+interface TableProps {
+    styleId?: string;
+    /** px table indent from left margin. */
+    indent?: number;
+    alignment?: Alignment;
+    /** w:bidiVisual — RTL table: column order reverses and the table hugs the
+     * right margin. */
+    bidiVisual?: boolean;
+    borders?: {
+        top?: Border;
+        bottom?: Border;
+        left?: Border;
+        right?: Border;
+        insideH?: Border;
+        insideV?: Border;
+    };
+    /** Default cell margins px. */
+    cellMargins?: {
+        top?: number;
+        right?: number;
+        bottom?: number;
+        left?: number;
+    };
+    /** w:tblCellSpacing px — old-style separated cell borders: every cell gets
+     * its own border box inset by this much from the grid slot on all sides
+     * (adjacent cells end up 2x apart), and the table outline is a separate box
+     * around everything. */
+    cellSpacing?: number;
+    /** w:tblpPr — floating table: absolutely positioned against page/margin/
+     * column, painted over an opaque white sheet, with body text (including
+     * text EARLIER in the flow on the same page) wrapping square around it. */
+    floating?: {
+        hAnchor: "page" | "margin" | "text";
+        vAnchor: "page" | "margin" | "text";
+        /** tblpX/tblpY px (absent when an alignment keyword is used). */
+        x?: number;
+        y?: number;
+        xAlign?: "left" | "center" | "right";
+        yAlign?: "top" | "center" | "bottom";
+        /** Wrap distances px (leftFromText, …). */
+        dist: {
+            l: number;
+            r: number;
+            t: number;
+            b: number;
+        };
+        /** w:tblOverlap "never": shift clear of earlier floating tables. */
+        allowOverlap: boolean;
+    };
+    /** Preferred total width px (tblW dxa) or undefined for auto. */
+    width?: number;
+    /** Preferred total width as a fraction of available width (tblW pct). */
+    widthPct?: number;
+    layout?: "fixed" | "autofit";
+    /** w:tblLook flags controlling which conditional formats apply. */
+    tblLook?: TableLook;
+}
+/** w:tblLook flags controlling which conditional table-style formats apply. */
+interface TableLook {
+    firstRow: boolean;
+    lastRow: boolean;
+    firstColumn: boolean;
+    lastColumn: boolean;
+    noHBand: boolean;
+    noVBand: boolean;
+}
+interface Table {
+    type: "table";
+    props: TableProps;
+    /** Column grid widths px (tblGrid). */
+    grid: number[];
+    rows: TableRow[];
+    /** Source w:tbl element. */
+    src?: XmlElement;
+}
+type Block = Paragraph | Table;
+interface HeaderFooterRefs {
+    default?: string;
+    first?: string;
+    even?: string;
+}
+interface ColumnSpec {
+    count: number;
+    /** Space between columns px. */
+    space: number;
+    /** Explicit widths px when equalWidth=false. */
+    widths?: number[];
+    /** Per-column trailing space px (w:col w:space), when explicit w:col
+     * entries are present. spaces[i] separates column i from column i+1. */
+    spaces?: number[];
+    /** w:cols w:sep: paint a vertical rule centered in each inter-column gap. */
+    sep?: boolean;
+}
+interface SectionProps {
+    pageWidth: number;
+    pageHeight: number;
+    marginTop: number;
+    marginRight: number;
+    marginBottom: number;
+    marginLeft: number;
+    /** Distance of header top from page top, px (w:headerReference distance). */
+    headerDistance: number;
+    footerDistance: number;
+    gutter: number;
+    headerRefs: HeaderFooterRefs;
+    footerRefs: HeaderFooterRefs;
+    /** Different first-page header/footer enabled. */
+    titlePage: boolean;
+    /** Page numbering restart value, if set. */
+    pageNumberStart?: number;
+    pageNumberFormat?: string;
+    columns: ColumnSpec;
+    /** w:docGrid type=lines/linesAndChars: minimum single-line height (px) that
+     * the line-spacing multiplier is applied over. Word snaps every line's font
+     * height up to this grid pitch (CJK documents). */
+    docGridLinePitch?: number;
+    /** Present w:docGrid type; omitted w:type means "default". */
+    docGridType?: "default" | "lines" | "linesAndChars" | "snapToChars";
+    /** w:docGrid type="charsAndLines": a combined char+line grid that (in compat
+     * 15) keeps natural East-Asian line pitch. Drives the CJK line-height
+     * correction during measurement. */
+    docGridCharGrid?: boolean;
+    type?: "nextPage" | "continuous" | "evenPage" | "oddPage" | "nextColumn";
+    /** Vertical alignment of page content. */
+    vAlign?: "top" | "center" | "both" | "bottom";
+    /** w:pgBorders. Offsets (border.space, px) measure from text or page edge. */
+    pageBorders?: {
+        top?: Border;
+        bottom?: Border;
+        left?: Border;
+        right?: Border;
+        offsetFrom: "text" | "page";
+    };
+    /** w:lnNumType: margin line numbering. distance px from the text edge. */
+    lineNumbering?: {
+        countBy: number;
+        start: number;
+        distance: number;
+        restart: "continuous" | "newPage" | "newSection";
+    };
+    /** Footnote/endnote mark numbering (w:footnotePr / w:endnotePr). */
+    footnoteNumFmt?: string;
+    footnoteNumStart?: number;
+    endnoteNumFmt?: string;
+    endnoteNumStart?: number;
+    /** w:textDirection tbRl: the whole section flows as East-Asian vertical
+     * writing — lines run top-to-bottom, progressing right-to-left. */
+    textDirection?: "tbRl";
+}
+interface Section {
+    props: SectionProps;
+    blocks: Block[];
+}
+/** A review comment from word/comments.xml. */
+interface DocComment {
+    id: string;
+    author: string;
+    initials?: string;
+    /** ISO timestamp from w:date, verbatim. */
+    date?: string;
+    /** Plain text of the comment body (paragraphs joined with newlines). */
+    text: string;
+    /** w14:paraId of the comment's last body paragraph (threading key). */
+    paraId?: string;
+    /** Parent comment id when this comment is a reply (commentsExtended). */
+    parentId?: string;
+}
+interface HeaderFooter {
+    blocks: Block[];
+}
+/** One w:tblStylePr conditional-formatting block (firstRow, band1Horz, …). */
+interface TableCondFormat {
+    /** Cell shading fill as CSS color. */
+    shd?: string;
+    /** Conditional cell borders. */
+    borders?: {
+        top?: Border;
+        bottom?: Border;
+        left?: Border;
+        right?: Border;
+        insideH?: Border;
+        insideV?: Border;
+    };
+    /** Conditional run bold (firstRow/firstCol headers). */
+    bold?: boolean;
+    /** Full conditional run props (w:tblStylePr > w:rPr). */
+    rPr?: RunProps;
+}
+type TableCondType = "wholeTable" | "band1Vert" | "band2Vert" | "band1Horz" | "band2Horz" | "firstRow" | "lastRow" | "firstCol" | "lastCol" | "nwCell" | "neCell" | "swCell" | "seCell";
+interface Style {
+    id: string;
+    type: "paragraph" | "character" | "table" | "numbering";
+    name?: string;
+    basedOn?: string;
+    isDefault?: boolean;
+    pPr?: ParaProps;
+    rPr?: RunProps;
+    tblPr?: TableProps;
+    /** w:tblStylePr conditional formats, by type (table styles only). */
+    condFormats?: Map<TableCondType, TableCondFormat>;
+    /** w:tblStyleRowBandSize / ColBandSize (default 1). */
+    rowBandSize?: number;
+    colBandSize?: number;
+}
+interface Styles {
+    byId: Map<string, Style>;
+    defaultParagraphStyle?: string;
+    defaultRPr: RunProps;
+    defaultPPr: ParaProps;
+}
+interface NumberingLevel {
+    ilvl: number;
+    start: number;
+    format: string;
+    /** Template like "%1." */
+    text: string;
+    alignment: Alignment;
+    /** Paragraph props contributed by the level (indents). */
+    pPr?: ParaProps;
+    rPr?: RunProps;
+    suffix: "tab" | "space" | "nothing";
+    restartAfter?: number;
+}
+interface AbstractNum {
+    id: number;
+    levels: Map<number, NumberingLevel>;
+    numStyleLink?: string;
+}
+interface NumInstance {
+    numId: number;
+    abstractNumId: number;
+    overrides: Map<number, {
+        startOverride?: number;
+        level?: NumberingLevel;
+    }>;
+}
+interface Numbering {
+    abstract: Map<number, AbstractNum>;
+    instances: Map<number, NumInstance>;
+}
+interface Theme {
+    majorFont: string;
+    minorFont: string;
+    majorBidiFont?: string;
+    minorBidiFont?: string;
+    /** East Asian faces from theme <a:ea> (fontScheme major/minorFont). Word's
+     * eastAsiaTheme="minor/majorEastAsia" resolves through these, NOT the Latin
+     * minor/major font — routing a CJK run's theme reference to the Latin face
+     * (Calibri) leaves East Asian text in a glyphless Latin font. */
+    majorEastAsiaFont?: string;
+    minorEastAsiaFont?: string;
+    colors: Map<string, string>;
+}
+
+/** A read-only view over the OPC (zip) package inside a .docx file. */
+declare class Package {
+    private files;
+    constructor(data: Uint8Array);
+    static from(data: ArrayBuffer | Uint8Array): Package;
+    has(name: string): boolean;
+    binary(name: string): Uint8Array | undefined;
+    text(name: string): string | undefined;
+    names(): string[];
+    /** Raw entry map (shared, do not mutate) — used for write-back. */
+    raw(): Record<string, Uint8Array>;
+    /** OPC part names never start with '/' inside the zip; tolerate both. */
+    private normalize;
+}
+
+/**
+ * Stable node identity for replicated editing.
+ *
+ * Positions on the wire cannot be object references, and numeric child paths
+ * shift under concurrent structural edits — so blocks (w:p, w:tbl) and runs
+ * (w:r) get stable numeric ids held in an in-memory side table. The table is
+ * identity-keyed and NEVER serialized into the XML: writing ids as attributes
+ * would dirty every part on open and break the byte-identical round-trip
+ * guarantee for untouched parts.
+ *
+ * Assignment is deterministic: a document-order walk over the given roots,
+ * so two replicas that parse the same document derive the same table. Nodes
+ * created later by edits get ids explicitly (locally via `assign`, or from a
+ * replicated edit that carries the originating client's allocation) — a
+ * re-walk after edits only fills gaps and never renumbers survivors, because
+ * the table is keyed by element identity and in-place XML mutation preserves
+ * identity across `refresh()`.
+ */
+type StableId$1 = number;
+interface EncodedCaret {
+    blockId: StableId$1;
+    runId: StableId$1;
+    /** 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.
+     * Counting separators makes encoding ONE-TO-ONE: a caret at the end of
+     * the w:t before a tab and one at the start of the w:t after it are
+     * different physical positions and get different wire offsets — without
+     * the separator unit both collapsed to the same number and the decoder
+     * had to guess (review bug: boundary intents applied into the wrong w:t
+     * on remote replicas, and boundary-starting ranges always rejected). */
+    offset: number;
+}
+declare class StableIds {
+    private byEl;
+    private byId;
+    private next;
+    /** Document-order assignment over the given roots (typically
+     * `doc.editableRoots()`). Idempotent: elements that already have ids keep
+     * them; untracked ids are assigned in walk order. Call after load and
+     * after any edit that created tracked nodes without explicit ids. */
+    assignFromRoots(roots: XmlElement[]): void;
+    /**
+     * Assign ids inside the given subtrees only — the scoped counterpart of
+     * assignFromRoots, for an edit that is known to have created nodes in one
+     * or two paragraphs (dirty-scoped reconciliation, perf B9/B10).
+     *
+     * EQUIVALENCE (the property the scoped hot path rests on): this produces
+     * the same table a full assignFromRoots would, PROVIDED every tracked node
+     * outside the subtrees already has an id. Assignment is order-dependent —
+     * fresh nodes take sequential numbers from `next` in walk order — and a
+     * subtree walk visits exactly a contiguous slice of the document-order
+     * walk, in the same order. So the only way the two can disagree is an
+     * un-id'd node elsewhere that the full walk would have numbered first.
+     * That invariant holds inductively: load/importSidecar ids everything, and
+     * every apply either ids the nodes it creates (carried ids), reports
+     * document scope (full refresh + full assign), or creates nodes only
+     * inside the subtrees passed here. Callers that cannot establish it must
+     * fall back to assignFromRoots.
+     */
+    assignFromSubtrees(subtrees: XmlElement[]): void;
+    private walk;
+    /** 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;
+    /** 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;
+    private install;
+    idOf(el: XmlElement): StableId$1 | undefined;
+    elOf(id: StableId$1): 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. */
+    prune(roots: XmlElement[]): void;
+    size(): number;
+    /** Snapshot the table as [id, element] pairs against a parallel clone of
+     * 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>;
+    /** Replace the table wholesale from a captured mapping (restore path). */
+    restore(fromCapture: Map<StableId$1, XmlElement>, nextId: StableId$1): void;
+    nextId(): StableId$1;
+    /**
+     * Export the table as `(id, path)` pairs, where a path is the structural
+     * location of the id'd element within the given roots: `[rootIndex,
+     * childIndex, childIndex, …]`. This is the checkpoint ID sidecar (plan doc
+     * 03): it lets a replica that reloads a snapshot reproduce the exact id
+     * table — parse-order re-derivation cannot, because split-created nodes
+     * carry non-sequential ids. Also carries `next` so id allocation resumes
+     * consistently.
+     */
+    exportSidecar(roots: XmlElement[]): {
+        next: StableId$1;
+        entries: [StableId$1, 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[]][];
+    }): 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,
+     * the block the nearest tracked block above that. Returns null when the
+     * position isn't inside id-tracked content (e.g. math internals) — such
+     * positions are not yet addressable on the wire. */
+    encodeCaret(t: XmlElement, offset: number, parentOf: (el: XmlElement) => XmlElement | null): EncodedCaret | null;
+    /** Resolve an encoded caret back to a concrete (w:t, offset) in THIS
+     * table's tree — the inverse of encodeCaret, for restoring a caret across
+     * a reconciliation reload (the ids survive via the sidecar; the node
+     * references do not). When the exact run is gone (deleted or replaced by
+     * a concurrent edit) the caret falls back to the block's first text; null
+     * when nothing addressable remains. */
+    decodeCaret(pos: EncodedCaret): {
+        t: XmlElement;
+        offset: number;
+    } | null;
+}
+
+interface Relationship {
+    id: string;
+    type: string;
+    target: string;
+    external: boolean;
+}
+type Relationships = Map<string, Relationship>;
+
+/**
+ * A fully parsed .docx: sections of blocks, styles, numbering, theme, and
+ * header/footer parts, with helpers to resolve effective formatting.
+ */
+declare class DocxDocument {
+    /** Changes whenever refresh() rebuilds the parsed model. Plain in-place text
+     * edits can keep this stable so incremental layout reuses model-only caches. */
+    private _modelVersion;
+    private _packageResourceVersion;
+    get modelVersion(): number;
+    /** Invalidate layout derived from related parts such as ChartML. */
+    markPackageResourceChanged(): void;
+    readonly pkg: Package;
+    readonly theme: Theme;
+    styles: Styles;
+    numbering: Numbering;
+    sections: Section[];
+    /** 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). */
+    readonly footnotes: Map<number, Block[]>;
+    readonly endnotes: Map<number, Block[]>;
+    /** The separator paragraph controls the gap between its rule and the first
+     * footnote. */
+    readonly footnoteSeparator: Block[];
+    /** `_Ref` cross-reference bookmark ranges (name → captured runs). REF
+     * fields re-render the referenced text from these — Word recomputes REF on
+     * open, so the cached field result in the file is stale. */
+    refBookmarks: Map<string, Run[]>;
+    readonly documentRels: Relationships;
+    /** settings.xml w:evenAndOddHeaders — enables the "even" header/footer variants. */
+    readonly evenAndOddHeaders: 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:defaultTabStop in px (Word default 0.5"). */
+    readonly defaultTabStop: number;
+    /** settings.xml w:compat compatibilityMode (12=Word2007, 14=Word2010,
+     * 15=Word2013+). Word 2013 (mode 15) introduced suppressing a paragraph's
+     * space-before when it lands at the top of a page; mode 14 and earlier keep
+     * it (nccih: a Heading1/2 after a page break sits at margin + its before).
+     * Absent → treated as current (15). */
+    readonly compatibilityMode: number;
+    /** 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
+     * the group is centered in the column). */
+    readonly mathDefJc: "left" | "right" | "center" | "centerGroup";
+    /** settings.xml m:mathPr/m:wrapIndent in px (Word default 1440tw = 1"):
+     * indent of auto-wrapped display-equation continuation rows from the
+     * equation group's left edge (dense p13: the "+Dc(...)" continuations sit
+     * exactly 72pt right of the explicit rows). */
+    readonly mathWrapIndent: number;
+    /** Review comments from word/comments.xml (empty when the part is absent).
+     * Re-derived from the retained comments XML on every refresh(). */
+    comments: DocComment[];
+    /** Retained comments.xml tree (editing + save round-trip), when present. */
+    private commentsPart;
+    private commentsRoot;
+    /** Retained commentsExtended.xml tree (comment threading), when present. */
+    private commentsExtPart;
+    private commentsExtRoot;
+    private commentsExtDirty;
+    /** Conditional table formats per table style id, keyed by the Styles object
+     * so re-parsing styles.xml (edits) naturally invalidates the cache. */
+    private tableCondCache;
+    /** Retained styles.xml tree (built-in style injection + save). */
+    private stylesPart;
+    private stylesRoot;
+    /** Retained numbering.xml tree (list creation + save round-trip). */
+    private numberingPart;
+    private numberingRoot;
+    private numberingDirty;
+    /** Retained footnotes.xml tree (footnote insertion + save round-trip). */
+    private footnotesPart;
+    private footnotesRoot;
+    private footnotesDirty;
+    private footnotesRels;
+    /** Serialize retained optional parts only once actually mutated, keeping
+     * untouched parts byte-identical through save(). */
+    private stylesDirty;
+    private commentsDirty;
+    /** Retained XML roots — source of truth for editing and save(). */
+    private readonly docPart;
+    /** Retained settings.xml tree. A synthetic empty root keeps history root
+     * indices stable for documents that did not originally contain the part. */
+    private readonly settingsPart;
+    private readonly settingsRoot;
+    private settingsDirty;
+    /** Parsed document.xml root (read-only outside the class; the layout engine
+     * scans it for incremental-reuse eligibility, tests walk it). */
+    readonly docRoot: XmlElement;
+    private readonly hfParts;
+    private readonly ctxBase;
+    /** Tracked-changes display mode; refresh() re-derives after changes. */
+    revisionView: "final" | "markup";
+    private readonly relsPath;
+    private relsRoot;
+    private contentTypesRoot;
+    /** Canonical XML as first parsed from each always-modeled package part.
+     * If the retained tree still matches on save, keep the part's original
+     * bytes instead of replacing producer formatting such as CRLF line ends. */
+    private readonly originalModeledXml;
+    private docPrIdCounter;
+    /** Transient layout state: set by the engine while laying out a docGrid
+     * type="charsAndLines" section so line measurement can give East-Asian
+     * glyphs their true (uninflated) grid line height. Off outside such a
+     * section. Safe as document-scoped mutable state because layout is
+     * single-threaded and sequential per section. */
+    charGridEa: boolean;
+    private constructor();
+    /** Resolve content controls mapped to standard package core properties.
+     * Word refreshes these bindings on open, so the serialized sdtContent can
+     * be stale even though the visible value comes from docProps/core.xml. */
+    private hydrateCorePropertyControls;
+    /** Repair only objects emitted by older WordInWeb builds that Word rejects. */
+    private repairLegacyWordInWebObjects;
+    /**
+     * Re-derive the document model from the retained XML trees. Called after
+     * edit commands mutate the XML.
+     */
+    /** Switch tracked-changes display and re-derive the model. */
+    setRevisionView(view: "final" | "markup"): void;
+    /** Invalidated on refresh; see layoutGlobalSig. */
+    private _layoutGlobalSig;
+    /** Signature of everything OUTSIDE a paragraph's own XML that affects how it
+     * breaks into lines: style + numbering definitions, doc-level layout scalars,
+     * and the tracked-changes view mode. The line-break cache (layout/inline.ts)
+     * combines this with a paragraph's own content signature so a style/numbering/
+     * settings edit invalidates cached breaks even though the paragraph XML is
+     * unchanged. Memoized until the next refresh() (styles/numbering trees are
+     * stable across a plain text edit). */
+    layoutGlobalSig(): string;
+    refresh(): void;
+    /** Stable node-id side table for replicated editing. Null (and zero cost)
+     * for local-only documents; call `enableStableIds()` to populate and
+     * maintain it. Kept in memory only — never serialized into the XML. */
+    stableIds: StableIds | null;
+    /** Populate the stable-id table from current content and keep it updated
+     * on every subsequent refresh(). Idempotent. */
+    enableStableIds(): StableIds;
+    /** Reparse the two sibling body-story paragraphs created by Enter without
+     * rebuilding the complete document model. Paragraphs nested in table cells
+     * are included because legal documents spend most of their body inside
+     * tables; revisions, bookmarks, fields, and section breaks use refresh(). */
+    reparseDirectBodyParagraphSplit(beforeSource: XmlElement, afterSource: XmlElement): {
+        before: Paragraph;
+        after: Paragraph;
+    } | null;
+    /**
+     * The parsed body-story block list holding the paragraph parsed from
+     * `source`, and its index in it — searching sections and, recursively,
+     * table cells. Null when the model doesn't hold that paragraph (it lives in
+     * a header/footer/footnote part, or the model predates its creation), which
+     * is every targeted-reparse helper's signal to fall back to a full
+     * refresh(). Shared by those helpers and by paragraphBySource.
+     */
+    private locateParagraph;
+    private _paraLoc;
+    /** The parsed Paragraph for a retained w:p in the body story (table cells
+     * included), or null when the model doesn't hold it. Lets a caller that
+     * already knows which paragraph an edit addresses reach that paragraph's
+     * runs without walking the whole model. */
+    paragraphBySource(source: XmlElement): Paragraph | null;
+    /** Insert a new paragraph immediately before a retained body paragraph
+     * without rebuilding the complete document model. Used by Enter at the
+     * exact paragraph start, where the existing paragraph itself is unchanged. */
+    insertDirectBodyParagraphBefore(referenceSource: XmlElement, insertedSource: XmlElement): Paragraph | null;
+    /** Reparse a body paragraph plus several new siblings created by
+     * click-and-type without rebuilding the complete document model. */
+    reparseDirectBodyParagraphSplits(beforeSource: XmlElement, afterSources: XmlElement[]): Paragraph[] | null;
+    /** Reparse one retained body-story paragraph after a structural edit that
+     * leaves its surrounding block list unchanged, such as inserting ink. */
+    reparseBodyParagraph(source: XmlElement): Paragraph | null;
+    /** Reparse two sibling body-story paragraphs after Backspace/Delete merged
+     * their XML into one. Keeps the parsed model generation stable so long
+     * documents can use incremental layout instead of repaginating in full. */
+    reparseDirectBodyParagraphMerge(beforeSource: XmlElement, afterSource: XmlElement, survivorSource: XmlElement): Paragraph | null;
+    private deriveComments;
+    /** Retained comments tree for edit commands (null when the doc has none). */
+    /**
+     * Retained comments tree. With create=true, a missing comments.xml part is
+     * created and registered (content type + document relationship) so newly
+     * added comments serialize and round-trip through Word.
+     */
+    commentsTree(create?: boolean): XmlElement | null;
+    /**
+     * Make sure a paragraph style is usable: Word ships built-in definitions
+     * for Heading 1-6/Title even when a file doesn't declare them, so applying
+     * one to such a file must inject a standard definition (otherwise the
+     * paragraph would reference an undefined style and render as Normal).
+     */
+    ensureParagraphStyle(styleId: string): boolean;
+    /**
+     * Retained numbering tree. With create=true, a missing numbering.xml part
+     * is created and registered (content type + document relationship) so list
+     * definitions added by editing serialize and round-trip.
+     */
+    numberingTree(create?: boolean): XmlElement | null;
+    markNumberingChanged(): 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;
+    /**
+     * Create an empty header/footer part (with a default-type reference in
+     * every sectPr) when the document has none - Word does this implicitly the
+     * first time you edit the header area. Returns the part's root.
+     */
+    /** Whether the document declares any section properties at all. A blank
+     * minimal document has none; see ensureHfPart. */
+    private hasSectPr;
+    /** Whether a header (or footer) part already exists — the precondition
+     * `ensureHfPart` tests internally, exposed so a caller can tell a real
+     * creation from a no-op before mutating (the collab apply needs to know
+     * whether an ensureHeaderFooter intent has anything to do). */
+    hasHfPart(kind: "header" | "footer"): boolean;
+    ensureHfPart(kind: "header" | "footer"): XmlElement;
+    markFootnotesChanged(): void;
+    /** Called by comment edit commands after mutating the comments tree. */
+    markCommentsChanged(): void;
+    /**
+     * Retained commentsExtended tree (threading). With create=true, a missing
+     * part is created and registered (content type + document relationship) so
+     * Word picks up reply threading.
+     */
+    commentsExtendedTree(create?: boolean): XmlElement | null;
+    markCommentsExtendedChanged(): void;
+    /**
+     * The w:t elements covered by each comment's range, in document order.
+     * Point comments (a bare commentReference with no range) anchor to the
+     * 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. */
+    markDirtyIfFootnote(t: XmlElement): 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[];
+    /** Toggle the document-global facing-page margin mode in settings.xml. */
+    setMirrorMargins(enabled: boolean): void;
+    /**
+     * 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. */
+    revisionRoots(): XmlElement[];
+    /**
+     * Memoized child→parent links. Nothing invalidates this map — the tree is
+     * spliced constantly — so every answer is RE-DERIVED before it is returned:
+     * the memoized parent must still list the target among its children, and
+     * must still hang off a root (see memoIsLive). A stale entry can then only
+     * cost a cache miss, never a wrong answer.
+     *
+     * Both halves are needed. Containment alone is not proof of a live parent:
+     * a run split for formatting is spliced OUT of its paragraph while its own
+     * `children` array still lists the elements that moved into the replacement
+     * runs, so a containment-only check would hand back the detached run where a
+     * walk from the roots finds the new one.
+     */
+    private _parentMemo;
+    private memoIsLive;
+    findParentOf(target: XmlElement): XmlElement | undefined;
+    /** Record a parent link the caller just created (a splice), so the next
+     * lookup skips the full-document walk. Advisory only — findParentOf
+     * verifies every memo against the live tree before trusting it. */
+    noteParent(child: XmlElement, parent: XmlElement): void;
+    /**
+     * Serialize the (possibly edited) document back to .docx bytes. Only the
+     * XML parts we model are re-serialized; every other part round-trips
+     * byte-for-byte.
+     */
+    private rememberOriginalXml;
+    private writeModeledXml;
+    /**
+     * Canonicalize producer shorthand that Google Docs otherwise interprets as
+     * a fixed, few-twip table. Word treats `tblW="100%"` plus a placeholder
+     * grid as autofit; Google needs the standard pct value and a usable cached
+     * grid. The cached widths follow the same content-dominant shape and do not
+     * change Word's autofit result.
+     */
+    /** Undo closures recorded by save-time fixups while `saveJournal` is
+     * active, so `save()` can revert every live-tree mutation and remain
+     * side-effect-free. Collaborative checkpoints re-serialize the
+     * authoritative document repeatedly; a save that mutated the tree would
+     * change its hash outside the intent stream and desync the fleet. */
+    private saveJournal;
+    private journalSetAttr;
+    private normalizePercentageTableGrids;
+    save(): Uint8Array;
+    saveAsync(): Promise<Uint8Array>;
+    private buildPackage;
+    private buildPackageFiles;
+    /** 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
+     * already carries drawings never gets a colliding id. */
+    nextDrawingId(): number;
+    /** Next unused revision id (w:id on w:ins/w:del). Seeded once past the
+     * highest id already present in any editable root so a document that
+     * already has tracked changes never collides. */
+    private revIdCounter;
+    nextRevisionId(): number;
+    /**
+     * Add image bytes as a new media part + relationship (+ content-type
+     * default). Returns the relationship id for use in a w:drawing.
+     */
+    private ensureRelsRoot;
+    /** Register an external hyperlink relationship and return its rId. */
+    addHyperlinkRel(url: string): string;
+    /** Retarget an existing external relationship (hyperlink href edit). */
+    setRelTarget(relId: string, url: string): boolean;
+    private addImageResourceAt;
+    addImageResource(bytes: Uint8Array, ext: string): string;
+    /** Add a GLB model part and its Office 2019 model3d relationship. */
+    addModel3DResource(bytes: Uint8Array): {
+        relId: string;
+        part: string;
+    };
+    /** Add an OLE package part used by a Word w:object. */
+    addEmbeddedObjectResource(bytes: Uint8Array): {
+        relId: string;
+        part: string;
+    };
+    /** Add a DOCX package embedded as an activatable Word.Document.12 object. */
+    addEmbeddedWordDocumentResource(bytes: Uint8Array): {
+        relId: string;
+        part: string;
+    };
+    /** Add a native ChartML part and its embedded editable workbook. */
+    addChartResource(chartXml: string, workbook: Uint8Array): {
+        relId: string;
+        part: string;
+    };
+    /** Add the SmartArt data/layout/style/color parts and its cached diagram drawing. */
+    addSmartArtResources(layoutXml: string, styleXml: string, colorsXml: string, drawingXml: string, dataXml: (drawingRelId: string) => string): {
+        dataRelId: string;
+        layoutRelId: string;
+        styleRelId: string;
+        colorsRelId: string;
+        drawingRelId: string;
+    };
+    static load(data: ArrayBuffer | Uint8Array): DocxDocument;
+    media(part: string): Uint8Array | undefined;
+    /**
+     * Pending-media registry (plan doc 05 change 1 / doc 16 §6): parts whose
+     * XML registration (rels + content-type + extent geometry) exists but
+     * whose BYTES have not arrived yet — the out-of-band media model. Layout
+     * needs no bytes (extents live in the XML), so a doc with pending parts
+     * lays out pixel-identically; the renderer shows a placeholder until
+     * `installMedia`. Keyed by part name; the value is the doc-16 §5.3
+     * metadata (declared sha + optional E2EE iv/epoch for re-supply).
+     */
+    readonly pendingMedia: Map<string, {
+        sha: string;
+        iv?: string;
+        genesisId?: string;
+    }>;
+    /** DISPLAY-ONLY transfer state for a pending part (doc 16 §5.2 step 4), so
+     * the skeleton can say "fetching" versus "nobody online has this yet".
+     * Written by the media transfer layer, read by the renderer; never part of
+     * the document's identity and never serialized. */
+    readonly mediaTransferState: Map<string, "fetching" | "waiting" | "unavailable">;
+    /** Per-part media metadata that PERSISTS after install (doc 16 §5.3):
+     * holder duty needs the sha (and E2EE iv/epoch) of READY parts to answer
+     * re-supply requests; pendingMedia above only tracks not-yet-arrived. */
+    readonly mediaMeta: Map<string, {
+        sha: string;
+        iv?: string;
+        genesisId?: string;
+    }>;
+    /** "ready" = bytes present; "pending" = registered, bytes absent (doc 05).
+     * Unregistered parts report "pending" too — a rel pointing at a missing
+     * zip entry after a save/parse round-trip IS the pending state (a hole is
+     * detectable, never corrupt — doc 16 §6 round-trip rule). */
+    mediaStatus(part: string): "ready" | "pending";
+    /**
+     * Register an image part + relationship WITHOUT bytes (doc 16 §2: the
+     * intent carries the sha; bytes travel out of band). Same deterministic
+     * naming/rId scan as addImageResource so every replica applying the same
+     * canonical intent derives identical registration.
+     */
+    registerPendingImage(sha: string, ext: string, meta?: {
+        iv?: string;
+        genesisId?: string;
+    }, source?: XmlElement): 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
+     * clears the pending record. Returns false for unknown parts. */
+    installMedia(part: string, bytes: Uint8Array): boolean;
+    /** Effective paragraph properties: docDefaults → table style → style chain → direct. */
+    effectiveParaProps(para: Paragraph): ParaProps;
+    /**
+     * Run props contributed by the enclosing table style's conditional
+     * w:tblStylePr blocks for this paragraph's cell (undefined when the
+     * paragraph isn't in a styled table cell or nothing applies).
+     */
+    private tableCondRPr;
+    /** Effective run properties for a run inside a paragraph. */
+    effectiveRunProps(para: Paragraph, runProps: RunProps): RunProps;
+    numberingLevel(numId: number, ilvl: number): NumberingLevel | undefined;
+    numberingInstance(numId: number): NumInstance | undefined;
+    private findDocumentPart;
+    private readXmlOptional;
+}
+
+/**
+ * Wire intents for replicated editing.
+ *
+ * Positions address content by stable id (plan doc 02): `{ blockId, runId,
+ * offset }`, where offset is a character offset within the run's text. Ids
+ * come from the core StableIds side table; the server validates every
+ * client-supplied id before applying (validate-then-install, doc 11) — the
+ * types here are the transport shape, not a trust boundary.
+ *
+ * `base` is the last server sequence number the originating client had
+ * applied when it produced the intent; the server transforms the intent
+ * 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 {
+    blockId: StableId;
+    runId: StableId;
+    offset: number;
+}
+interface IntentBase {
+    /** Originating client (authenticated identity; the server never trusts a
+     * claimed id — see doc 11). */
+    clientId: string;
+    /** Per-client monotonic counter; `(clientId, clientSeq)` is the idempotency
+     * key that dedups re-sends after reconnect (doc 03). */
+    clientSeq: number;
+    /** Last applied server seq at production time. */
+    base: number;
+}
+/**
+ * Tracked-change marks (plan doc 14 §3 L2): strike text ranges as w:del
+ * revisions and/or mark paragraph glyphs (split "ins" marks, merge "del"
+ * suggestions) — the SUGGESTING counterparts of deleteText/mergeParagraph.
+ * Nothing is removed: Word keeps both sides until accept/reject (the
+ * already-collab-wired accept/reject revision intents).
+ * Author/date travel IN the intent (doc 05 rule a: nondeterministic values
+ * are generated once by the originator); revision w:ids are scan-derived
+ * from identical tree state on every replica. Positional offsets were
+ * client-resolved (rule b — no Intl re-derivation at apply).
+ */
+interface SuggestRevisionIntent extends IntentBase {
+    kind: "suggestRevision";
+    ranges?: {
+        blockId: StableId;
+        runId: StableId;
+        start: number;
+        end: number;
+    }[];
+    marks?: {
+        blockId: StableId;
+        glyph: "ins" | "del";
+    }[];
+    suggest: {
+        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 /
+ * suggesting mode), rather than a plain insert. */
+interface InsertTextIntent extends IntentBase {
+    kind: "insertText";
+    at: Position;
+    text: string;
+    /** Tracked-change (suggesting) metadata; omit for a plain insert. */
+    suggest?: {
+        author: string;
+        date: string;
+    };
+}
+/** Delete `[start, end)` characters within a single run. */
+interface DeleteTextIntent extends IntentBase {
+    kind: "deleteText";
+    blockId: StableId;
+    runId: StableId;
+    start: number;
+    end: number;
+}
+/**
+ * Split a paragraph at a position. Text after `at.offset` in run `at.runId`
+ * (and following runs) moves to a new paragraph. The originating client
+ * allocates the ids for the new paragraph and the new run holding the moved
+ * tail; every replica installs these recorded values (doc 03), and they also
+ * let the transform remap concurrent positions that fall in the moved tail.
+ */
+interface SplitParagraphIntent extends IntentBase {
+    kind: "splitParagraph";
+    at: Position;
+    newBlockId: StableId;
+    newRunId: StableId;
+    /** With metadata, Enter remains a tracked paragraph-break suggestion. */
+    suggest?: {
+        author: string;
+        date: string;
+    };
+}
+/**
+ * Character-format an entire run (bold/italic/underline/…). Whole-run only:
+ * it mutates the run's w:rPr in place, so no run splits, no new ids, and the
+ * run id is preserved — which makes its transform identity (formatting moves
+ * no text). Sub-range formatting splits the run into up to three, needing the
+ * run-split id-inheritance + position remapping (plan doc 03 F3); that is a
+ * documented extension, not implemented here.
+ */
+interface FormatRunIntent extends IntentBase {
+    kind: "formatRun";
+    blockId: StableId;
+    runId: StableId;
+    /** RunFormatPatch (bold/italic/underline/strike/color/…). Structural shape
+     * mirrors @wordinweb/core's RunFormatPatch; carried verbatim. */
+    patch: Record<string, unknown>;
+}
+/**
+ * Paragraph-level formatting: alignment and/or paragraph style. Block-level —
+ * it mutates the paragraph's w:pPr, creates no tracked nodes, and moves no
+ * text, so the block id is preserved and its transform is identity.
+ */
+interface FormatParagraphIntent extends IntentBase {
+    kind: "formatParagraph";
+    blockId: StableId;
+    align?: "left" | "center" | "right" | "justify";
+    /** Paragraph style id; null clears to Normal. Omit to leave unchanged. */
+    styleId?: string | null;
+}
+/**
+ * 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.
+ */
+interface SetListTypeIntent extends IntentBase {
+    kind: "setListType";
+    blockId: StableId;
+    listKind: "bullet" | "number" | null;
+}
+/**
+ * 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)
+ * (formatted), after [end,len) — replacing the original run. The originating
+ * client allocates ids for the pieces that exist and carries them so every
+ * replica addresses the pieces identically; the transform remaps any
+ * concurrent position in the old run into the correct piece.
+ */
+interface FormatRangeIntent extends IntentBase {
+    kind: "formatRange";
+    blockId: StableId;
+    runId: StableId;
+    start: number;
+    end: number;
+    patch: Record<string, unknown>;
+    /** Piece ids, present iff the piece exists: before when start>0, after when
+     * end<runLen. middle always. */
+    beforeId?: StableId;
+    middleId: StableId;
+    afterId?: StableId;
+}
+/**
+ * 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.
+ */
+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" | {
+        kind: "cellShading";
+        fill: string | null;
+    } | {
+        kind: "cellVAlign";
+        v: "top" | "center" | "bottom";
+    } | {
+        kind: "textWrapping";
+        wrapping: "none" | "around";
+        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. */
+    nodeIds?: StableId[];
+}
+/**
+ * Merge a paragraph into its predecessor (Backspace at paragraph start). The
+ * paragraph's runs MOVE into the previous paragraph (element identity
+ * preserved), so run-addressed positions survive unchanged — an identity
+ * transform. The merged paragraph's block id is retired.
+ */
+interface MergeParagraphIntent extends IntentBase {
+    kind: "mergeParagraph";
+    /** The paragraph to merge into the one before it. */
+    blockId: StableId;
+}
+/**
+ * Add a review comment anchored to an entire run. Comment markers
+ * (commentRangeStart/End + a commentReference run) are inserted as run
+ * siblings and the comment body goes into comments.xml — no commented run's
+ * text moves, so the transform is identity. The nondeterministic values
+ * (w14:paraId, w:date) are generated once by the originating client and
+ * carried here (plan doc 05) so every replica writes identical XML. Sub-range
+ * comments (splitting the run) are the documented harder extension.
+ */
+interface CommentRunIntent extends IntentBase {
+    kind: "commentRun";
+    runId: StableId;
+    text: string;
+    author: string;
+    initials?: string;
+    /** Carried provenance for deterministic XML across replicas. */
+    date: string;
+    paraId: string;
+}
+/**
+ * Rich paste: splice validated OOXML paragraph blocks after a target
+ * paragraph. The pasting client converts clipboard HTML to OOXML locally
+ * (browser-only, engine-dependent — doc 02 M4) and carries the serialized
+ * blocks; the server VALIDATES them against the positive allowlist before
+ * applying (doc 11 gate 2). `nodeIds` are carried ids for the new tracked
+ * nodes (p / r) in document order, so every replica addresses them alike.
+ * Inserting separate blocks shifts no existing run's offsets — identity
+ * transform.
+ */
+interface PasteBlocksIntent extends IntentBase {
+    kind: "pasteBlocks";
+    /** Paragraph after which to insert the pasted blocks. */
+    afterBlockId: StableId;
+    /** Serialized OOXML block list (w:p elements), validated at apply. */
+    blocksXml: string;
+    /** Carried ids for the new p/r nodes, in document order. */
+    nodeIds: StableId[];
+}
+/**
+ * Insert an image at a run (as a sibling drawing run — no text split, identity
+ * transform). The plan's media design carries bytes out-of-band via presigned
+ * upload with the intent carrying (part, extents, sha) — modeled here with the
+ * bytes inline (base64), which is correct for small images and keeps the whole
+ * flow testable headlessly; the out-of-band path is a transport optimization
+ * over the same convergence. Client-measured dimensions (widthPx/heightPx) are
+ * carried so layout reserves space deterministically. `nodeIds` are carried
+ * ids for the new drawing run(s).
+ */
+interface InsertImageIntent extends IntentBase {
+    kind: "insertImage";
+    runId: StableId;
+    /**
+     * sha256 hex of the BLOB (plan doc 16 §2): plaintext bytes in plaintext
+     * mode, ciphertext in E2EE mode. This is the reservation's hash
+     * COMMITMENT — every replica registers the part pending and verifies any
+     * later-arriving bytes against it (the swap-proofing trust chain, doc 16
+     * §1.1). Bytes NEVER ride the intent (doc 06: sequencer bandwidth is
+     * proportional to typing, not content).
+     */
+    blobSha: string;
+    /** Blob length in bytes — validate.ts bounds it (doc 13 blocker 3). */
+    bytesLen: number;
+    /** File extension without dot (png/jpg/gif…) — drives the content type. */
+    ext: string;
+    /** E2EE only: base64 12-byte GCM IV, recorded so any holder can re-seal
+     * byte-identically for re-supply (doc 16 §5.3). */
+    iv?: string;
+    widthPx: number;
+    heightPx: number;
+    nodeIds: StableId[];
+}
+/**
+ * Insert a page/column break at the END of a run (inserts sibling break + tail
+ * runs — no text split, identity transform). Mid-run breaks (which split the
+ * run) follow the carried-id-split pattern (formatRange) and are the
+ * documented extension. `nodeIds` are carried ids for the new runs.
+ */
+interface InsertBreakIntent extends IntentBase {
+    kind: "insertBreak";
+    runId: StableId;
+    breakKind: "page" | "column";
+    nodeIds: StableId[];
+}
+/**
+ * Insert a math (OMML) formula from a linear expression at the end of a run
+ * (sibling insertion — identity transform). `nodeIds` for any new tracked
+ * nodes.
+ */
+interface InsertMathIntent extends IntentBase {
+    kind: "insertMath";
+    runId: StableId;
+    mathText: string;
+    nodeIds: StableId[];
+}
+/** Insert a shape/textbox drawing at the end of a run (sibling — identity). */
+interface InsertShapeIntent extends IntentBase {
+    kind: "insertShape";
+    runId: StableId;
+    preset: "line" | "verticalLine" | "rectangle" | "roundedRectangle" | "ellipse" | "diamond" | "textBox";
+    text?: string;
+    nodeIds: StableId[];
+}
+/**
+ * Reply to an existing comment (threading). Addressed by the parent comment's
+ * id (a deterministic string). Carries provenance (w14:paraId candidates in
+ * consumption order + the w:date) so every replica writes identical XML. No
+ * document run's text moves — identity transform.
+ */
+interface ReplyCommentIntent extends IntentBase {
+    kind: "replyComment";
+    parentId: string;
+    text: string;
+    author: string;
+    initials?: string;
+    date: string;
+    /** paraId candidates in the order replyToComment consumes them: the reply's
+     * paraId, preceded by the parent's if the parent lacks one. */
+    paraIds: string[];
+}
+/** Adjust a paragraph's indent (Tab/Shift-Tab). Block-level, identity. */
+interface AdjustIndentIntent extends IntentBase {
+    kind: "adjustIndent";
+    blockId: StableId;
+    direction: 1 | -1;
+}
+/** Set paragraph line/before/after spacing. Block-level, identity. */
+interface SetSpacingIntent extends IntentBase {
+    kind: "setSpacing";
+    blockId: StableId;
+    /** ParagraphSpacingPatch (before/after/line/lineRule) — carried verbatim. */
+    patch: Record<string, unknown>;
+}
+/** Insert a page-number field at the end of a run (sibling insertion,
+ * identity). Page fields are deterministic (no clock). */
+interface InsertPageFieldIntent extends IntentBase {
+    kind: "insertPageField";
+    runId: StableId;
+    fieldKind: "page" | "pageOfTotal";
+    nodeIds: StableId[];
+}
+/** Wrap a run in a hyperlink to `url`. The url is scheme-validated at apply
+ * (rejects javascript:/data: etc. — doc 11 gate 1). Run-level, identity. */
+interface SetLinkIntent extends IntentBase {
+    kind: "setLink";
+    runId: StableId;
+    url: string;
+    nodeIds: StableId[];
+}
+/** Insert a footnote reference at the end of a run + its footnote text. */
+interface InsertFootnoteIntent extends IntentBase {
+    kind: "insertFootnote";
+    runId: StableId;
+    text: string;
+    nodeIds: StableId[];
+}
+/** Set/clear a drop cap on a paragraph. Block-level. */
+interface SetDropCapIntent extends IntentBase {
+    kind: "setDropCap";
+    blockId: StableId;
+    mode: "drop" | "margin" | null;
+    nodeIds: StableId[];
+}
+/** Set/clear a paragraph divider (horizontal rule). Block-level, identity. */
+interface SetDividerIntent extends IntentBase {
+    kind: "setDivider";
+    blockId: StableId;
+    divider: Record<string, unknown> | null;
+}
+/** Insert a bookmark anchor at the end of a run. */
+interface InsertBookmarkIntent extends IntentBase {
+    kind: "insertBookmark";
+    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;
+/** Insert a blank page at the end of a run. */
+interface InsertBlankPageIntent extends IntentBase {
+    kind: "insertBlankPage";
+    runId: StableId;
+    nodeIds: StableId[];
+}
+/** Insert a section break at the end of a run. */
+interface InsertSectionBreakIntent extends IntentBase {
+    kind: "insertSectionBreak";
+    runId: StableId;
+    breakType: "nextPage" | "continuous";
+    nodeIds: StableId[];
+}
+/** Insert a cross-reference to a bookmark at the end of a run. */
+interface InsertCrossRefIntent extends IntentBase {
+    kind: "insertCrossRef";
+    runId: StableId;
+    bookmark: string;
+    refKind: "text" | "page";
+    nodeIds: StableId[];
+}
+/** Insert a cover page (document-level). */
+interface InsertCoverPageIntent extends IntentBase {
+    kind: "insertCoverPage";
+    /** CoverPageContent ({title, subtitle?, author?, …}) — carried verbatim. */
+    content: Record<string, unknown>;
+    nodeIds: StableId[];
+}
+/** Update page setup: margins/size/orientation/columns/borders. When target is
+ * omitted it applies to every section; document-level, identity transform. */
+interface SetPageLayoutIntent extends IntentBase {
+    kind: "setPageLayout";
+    /** PageLayoutPatch ({margins?, size?, orientation?, columns?, …}) — carried
+     * verbatim; validated against a shape+range allowlist. */
+    patch: Record<string, unknown>;
+}
+/** Indent (+1) or outdent (-1) a paragraph's list nesting level. Block-level. */
+interface SetListLevelIntent extends IntentBase {
+    kind: "setListLevel";
+    blockId: StableId;
+    delta: 1 | -1;
+}
+/** Insert decorative WordArt (a text drawing) at the end of a run. */
+interface InsertWordArtIntent extends IntentBase {
+    kind: "insertWordArt";
+    runId: StableId;
+    text: string;
+    preset: "plain" | "archUp" | "archDown" | "wave" | "chevron";
+    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. */
+interface InsertChartIntent extends IntentBase {
+    kind: "insertChart";
+    runId: StableId;
+    chart: {
+        type: "column" | "bar" | "line" | "pie";
+        title?: string;
+        categories: string[];
+        series: {
+            name: string;
+            values: number[];
+        }[];
+    };
+    nodeIds: StableId[];
+}
+/** Insert a SmartArt diagram (process/cycle/hierarchy/list) at end of a run. */
+interface InsertSmartArtIntent extends IntentBase {
+    kind: "insertSmartArt";
+    runId: StableId;
+    smartArt: {
+        layout: "process" | "cycle" | "hierarchy" | "list";
+        items: string[];
+    };
+    nodeIds: StableId[];
+}
+/** Toggle/configure margin line numbering for the section(s). Document-level. */
+interface SetLineNumberingIntent extends IntentBase {
+    kind: "setLineNumbering";
+    patch: {
+        enabled: boolean;
+        countBy?: number;
+        restart?: "continuous" | "newPage" | "newSection";
+        start?: number;
+    };
+}
+/** Insert an auto-updating DATE or TIME field at the end of a run. The picture
+ * (format string) is carried so every replica renders identical field XML. */
+interface InsertDateTimeFieldIntent extends IntentBase {
+    kind: "insertDateTimeField";
+    runId: StableId;
+    dtKind: "date" | "time";
+    picture: string;
+    nodeIds: StableId[];
+}
+/** Insert a Word field (e.g. PAGE, NUMPAGES, REF) at the end of a run. The
+ * instruction is restricted to a safe positive allowlist (no INCLUDETEXT/DDE/
+ * LINK external-content fields). */
+interface InsertFieldIntent extends IntentBase {
+    kind: "insertField";
+    runId: StableId;
+    instruction: string;
+    cachedResult?: string;
+    nodeIds: StableId[];
+}
+interface DrawingTarget {
+    runId: StableId;
+    /** Parsed run-content index. It disambiguates several drawings carried by one run. */
+    objectIndex?: number;
+}
+/** Rotate the drawing carried by a run. Identity transform (run-addressed). */
+interface SetDrawingRotationIntent extends IntentBase, DrawingTarget {
+    kind: "setDrawingRotation";
+    runId: StableId;
+    degrees: number;
+}
+/** Set/clear the solid fill of the drawing carried by a run. `color` is a
+ * 6-hex-digit RGB (no #) or null to clear. */
+interface SetDrawingFillIntent extends IntentBase, DrawingTarget {
+    kind: "setDrawingFill";
+    runId: StableId;
+    color: string | null;
+}
+/** Replace the data of the chart carried by a run (same shape as insertChart's
+ * chart). Edits an existing chart in place. */
+interface SetChartDataIntent extends IntentBase, DrawingTarget {
+    kind: "setChartData";
+    runId: StableId;
+    chart: {
+        type: "column" | "bar" | "line" | "pie";
+        title?: string;
+        categories: string[];
+        series: {
+            name: string;
+            values: number[];
+        }[];
+    };
+}
+/** Set the text of one node of the SmartArt diagram carried by a run. */
+interface SetSmartArtNodeTextIntent extends IntentBase, DrawingTarget {
+    kind: "setSmartArtNodeText";
+    runId: StableId;
+    index: number;
+    text: string;
+}
+/** Replace the text of the WordArt drawing carried by a run. */
+interface SetDrawingWordArtTextIntent extends IntentBase, DrawingTarget {
+    kind: "setDrawingWordArtText";
+    runId: StableId;
+    text: string;
+}
+/** Set the glyph fill and alpha of the WordArt drawing carried by a run. */
+interface SetDrawingWordArtStyleIntent extends IntentBase, DrawingTarget {
+    kind: "setDrawingWordArtStyle";
+    runId: StableId;
+    color: string;
+    opacity: number;
+}
+/** Set or clear the outline of the drawing carried by a run. */
+type SetDrawingLineStyleIntent = IntentBase & DrawingTarget & {
+    kind: "setDrawingLineStyle";
+    runId: StableId;
+} & ({
+    color: null;
+    widthPx?: number;
+    dash?: "solid" | "dashed" | "dotted";
+} | {
+    color: string;
+    widthPx: number;
+    dash: "solid" | "dashed" | "dotted";
+});
+/** Set/clear the alt text (accessibility description) of the image/drawing
+ * carried by a run. Empty string clears it. */
+interface SetImageAltTextIntent extends IntentBase, DrawingTarget {
+    kind: "setImageAltText";
+    runId: StableId;
+    alt: string;
+}
+/** Remove the hyperlink wrapping a run's text (inverse of setLink). */
+interface RemoveLinkIntent extends IntentBase {
+    kind: "removeLink";
+    runId: StableId;
+}
+/** Set the text-wrap mode of the drawing carried by a run. A floating mode
+ * converts an inline drawing to an anchor. */
+interface SetImageWrapIntent extends IntentBase, DrawingTarget {
+    kind: "setImageWrap";
+    runId: StableId;
+    mode: "inline" | "square" | "topAndBottom" | "none" | "behind";
+}
+/** Bring the (floating) drawing carried by a run to front/back. */
+interface SetDrawingOrderIntent extends IntentBase, DrawingTarget {
+    kind: "setDrawingOrder";
+    runId: StableId;
+    order: "front" | "back";
+}
+/** Replace the whole SmartArt diagram (layout + items) carried by a run. */
+interface SetSmartArtDataIntent extends IntentBase, DrawingTarget {
+    kind: "setSmartArtData";
+    runId: StableId;
+    smartArt: {
+        layout: "process" | "cycle" | "hierarchy" | "list";
+        items: string[];
+    };
+}
+/** Set/clear the fill of a SmartArt node (or all nodes when nodeIndex omitted).
+ * `color` is 6-hex RGB (no #) or null to clear. */
+interface SetSmartArtFillIntent extends IntentBase, DrawingTarget {
+    kind: "setSmartArtFill";
+    runId: StableId;
+    color: string | null;
+    nodeIndex?: number;
+}
+/** Set the text format of a SmartArt node (or all nodes). */
+interface SetSmartArtTextFormatIntent extends IntentBase, DrawingTarget {
+    kind: "setSmartArtTextFormat";
+    runId: StableId;
+    format: {
+        fontFamily: string;
+        fontSizePt: number;
+        color: string;
+        bold: boolean;
+        italic: boolean;
+        alignment: "left" | "center" | "right";
+    };
+    nodeIndex?: number;
+}
+/** Position the (floating) drawing carried by a run relative to the page. */
+interface SetFloatingPagePositionIntent extends IntentBase, DrawingTarget {
+    kind: "setFloatingPagePosition";
+    runId: StableId;
+    xPx: number;
+    yPx: number;
+}
+/** Resize the drawing carried by a run (extent in px; the mutation clamps to
+ * a 1px-EMU floor and keeps line geometry degenerate on its minor axis). */
+interface ResizeDrawingIntent extends IntentBase, DrawingTarget {
+    kind: "resizeDrawing";
+    runId: StableId;
+    widthPx: number;
+    heightPx: number;
+}
+/** Drag-resize a table column boundary. Addressed like tableOp: a paragraph
+ * inside the table. `renderedWidths` (the dragger's measured column widths)
+ * rides as DATA so every replica applies the identical mutation. */
+interface ResizeTableColumnIntent extends IntentBase {
+    kind: "resizeTableColumn";
+    cellParagraphId: StableId;
+    boundary: number;
+    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";
+    cellParagraphId: StableId;
+    xPx: number;
+    yPx: number;
+    preservePageStart: boolean;
+    pageDelta: number;
+}
+/** Delete the drawing at the supplied run-content target. */
+interface RemoveDrawingIntent extends IntentBase, DrawingTarget {
+    kind: "removeDrawing";
+    runId: StableId;
+}
+/** Replace the equation of the math object in a paragraph (linear syntax).
+ * Math (m:oMath) lives at paragraph level, so this is block-addressed. */
+interface SetMathLinearIntent extends IntentBase {
+    kind: "setMathLinear";
+    blockId: StableId;
+    mathText: string;
+}
+/** Delete the math object in a paragraph. */
+interface DeleteMathIntent extends IntentBase {
+    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
+ * 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 {
+    kind: "moveMath";
+    blockId: StableId;
+    at: Position;
+    nodeIds: StableId[];
+}
+/** Create the document's header (or footer) part the way Word does on first
+ * entry into the margin band: a new part + relationship + content-type
+ * override, referenced from every sectPr (one is materialized when a minimal
+ * document has none). Applies as a clean no-op when the part already exists,
+ * so it is safe for two participants to open the header at the same moment.
+ * The created paragraph and run take carried ids — every later edit in the
+ * header addresses them. */
+interface EnsureHeaderFooterIntent extends IntentBase {
+    kind: "ensureHeaderFooter";
+    hfKind: "header" | "footer";
+    nodeIds: StableId[];
+}
+/** Delete a comment (and its reply thread) by id. */
+interface DeleteCommentIntent extends IntentBase {
+    kind: "deleteComment";
+    commentId: string;
+}
+/** Wrap a sub-range of a run's text in a named bookmark. */
+interface InsertBookmarkRangeIntent extends IntentBase {
+    kind: "insertBookmarkRange";
+    runId: StableId;
+    name: string;
+    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 {
+    kind: "acceptRevision";
+    index: number;
+}
+/** Reject one tracked change, addressed by document-order index. */
+interface RejectRevisionIntent extends IntentBase {
+    kind: "rejectRevision";
+    index: number;
+}
+/** Accept every tracked change in the document. */
+interface AcceptAllRevisionsIntent extends IntentBase {
+    kind: "acceptAllRevisions";
+}
+/** Reject every tracked change in the document. */
+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[];
+}
+/** 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
+ * shared keys only). Used by the editor producer and the undo inverse. */
+type IntentBody = Intent extends infer T ? (T extends Intent ? Omit<T, "clientId" | "clientSeq" | "base"> : never) : never;
+
+/**
+ * How much of the document an applied intent disturbed — the input to
+ * dirty-scoped reconciliation (perf B9/B10). Reconciling an edit used to cost
+ * O(document) on every path (full model reparse + full id walk), so per-op
+ * cost grew with the document; the scope lets the caller pay for THE EDIT.
+ *
+ * `doc` is the conservative default and means exactly today's behavior: full
+ * refresh() + assignFromRoots(). Only intents whose blast radius is provably
+ * one paragraph (or the two sides of a split) report a narrower scope; every
+ * structural, document-level, or exotic intent keeps the document scope.
+ */
+type Scope = {
+    kind: "doc";
+}
+/** Only these paragraphs' contents changed. */
+ | {
+    kind: "block";
+    blocks: XmlElement[];
+}
+/** `before` was split; `after` is the new sibling that follows it. */
+ | {
+    kind: "split";
+    before: XmlElement;
+    after: XmlElement;
+};
+
+/**
+ * Wire protocol between a collab client and the server host. Transport-
+ * agnostic: the hub speaks these messages; a WebSocket (or in-memory test)
+ * adapter serializes them. Kept deliberately small (plan doc 06).
+ */
+/** One highlighted stretch of a remote participant's selection: a half-open
+ * `[start, end)` inside ONE run, in the same WIRE offset basis carets and
+ * suggestRevision use (cumulative within the run, inline separators counting
+ * one unit each — see core `EncodedCaret`). The sender emits one entry per
+ * selection segment, and a segment never straddles a w:t, so a range stays
+ * inside a single run by construction. */
+interface PresenceRange {
+    blockId: number;
+    runId: number;
+    start: number;
+    end: number;
+}
+/** An ephemeral cursor/selection position on the presence channel: stable-id
+ * addresses (plan doc 03). Never logged, never persisted. */
+interface PresencePosition {
+    anchor: {
+        blockId: number;
+        runId: number;
+        offset: number;
+    };
+    focus?: {
+        blockId: number;
+        runId: number;
+        offset: number;
+    };
+    /** Selection highlight (Google-Docs style): the stretches the participant
+     * has selected, drawn in their presence color under the remote caret.
+     * OPTIONAL and additive — a payload from an older client carries only the
+     * anchor and still renders a caret. Absent/empty ⇒ no selection. */
+    ranges?: PresenceRange[];
+}
+
+interface AgentEditCapability {
+    category: "text" | "paragraph" | "review" | "table" | "insert" | "drawing" | "math" | "document";
+    description: string;
+    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.
+ */
+declare const AGENT_EDIT_CAPABILITIES: Record<Intent["kind"], AgentEditCapability>;
+type JsonSchema$1 = Record<string, unknown>;
+declare function agentOperationSchema(kind: Intent["kind"]): JsonSchema$1;
+declare function validateAgentOperationShape(input: unknown): string | null;
+declare function agentCapabilities(category?: AgentEditCapability["category"], requestedKind?: Intent["kind"]): Array<AgentEditCapability & {
+    kind: Intent["kind"];
+    inputSchema: Record<string, unknown>;
+}>;
+
+type AgentReference = string;
+interface AgentCursor {
+    value: string;
+}
+interface AgentOverview {
+    revision: string;
+    sections: number;
+    mirrorMargins: boolean;
+    sectionLayouts: AgentSectionLayout[];
+    stories: Array<{
+        id: string;
+        kind: "body" | "header" | "footer" | "footnote" | "endnote" | "textbox";
+        blocks: number;
+    }>;
+    blocks: {
+        paragraphs: number;
+        tables: number;
+    };
+    characters: number;
+    comments: number;
+    components: Record<string, number>;
+    objectCounts: Record<string, number>;
+    outline: OutlineEntry[];
+}
+interface AgentSectionLayout {
+    index: number;
+    page: {
+        width: number;
+        height: number;
+    };
+    margins: {
+        top: number;
+        right: number;
+        bottom: number;
+        left: number;
+    };
+    headerDistance: number;
+    footerDistance: number;
+    gutter: number;
+    columns: {
+        count: number;
+        space: number;
+        widths?: number[];
+        spaces?: number[];
+        separator?: boolean;
+    };
+    titlePage: boolean;
+    pageNumberStart?: number;
+    pageNumberFormat?: string;
+    breakType?: "nextPage" | "continuous" | "evenPage" | "oddPage" | "nextColumn";
+    verticalAlignment?: "top" | "center" | "both" | "bottom";
+    pageBorders?: AgentPageBorders;
+    lineNumbering?: {
+        countBy: number;
+        start: number;
+        distance: number;
+        restart: "continuous" | "newPage" | "newSection";
+    };
+}
+interface AgentBorder {
+    style: "none" | "single" | "double" | "dotted" | "dashed" | "thick" | "wave" | "dotDash" | "dotDotDash" | "thinThickSmallGap" | "triple";
+    width: number;
+    color: string;
+    space: number;
+    rawWidth?: number;
+}
+interface AgentPageBorders {
+    top?: AgentBorder;
+    bottom?: AgentBorder;
+    left?: AgentBorder;
+    right?: AgentBorder;
+    offsetFrom: "text" | "page";
+}
+interface OutlineEntry {
+    ref: AgentReference;
+    level: number;
+    text: string;
+    styleId?: string;
+}
+interface AgentRun {
+    ref: AgentReference;
+    editable: boolean;
+    paragraphStart: number;
+    paragraphEnd: number;
+    wireLength: number;
+    text: string;
+    formatting: Record<string, unknown>;
+    hyperlink?: {
+        href?: string;
+        anchor?: string;
+    };
+    components: AgentComponentSummary[];
+}
+interface AgentParagraph {
+    type: "paragraph";
+    ref: AgentReference;
+    editable: boolean;
+    story: string;
+    styleId?: string;
+    outlineLevel?: number;
+    alignment?: string;
+    list?: {
+        numId: number;
+        level: number;
+    } | null;
+    text: string;
+    textRange: {
+        start: number;
+        end: number;
+        total: number;
+    };
+    runs: AgentRun[];
+    bookmarks: string[];
+}
+interface AgentTable {
+    type: "table";
+    ref: AgentReference;
+    editable: boolean;
+    story: string;
+    rows: number;
+    columns: number;
+    styleId?: string;
+    floating: boolean;
+    cells: Array<{
+        row: number;
+        column: number;
+        blocks: AgentReference[];
+    }>;
+}
+type AgentBlock = AgentParagraph | AgentTable;
+interface AgentReadResult {
+    revision: string;
+    story: string;
+    blocks: AgentBlock[];
+    next?: AgentCursor;
+    truncated: boolean;
+}
+interface AgentContextRun {
+    ref: AgentReference;
+    start: number;
+    end: number;
+    wireLength?: number;
+}
+interface AgentContextParagraph {
+    type: "paragraph";
+    ref: AgentReference;
+    text: string;
+    range?: {
+        start: number;
+        end: number;
+        total: number;
+    };
+    runs: AgentContextRun[];
+    styleId?: string;
+    outlineLevel?: number;
+    list?: {
+        numId: number;
+        level: number;
+    };
+    bookmarks?: string[];
+    objects?: AgentComponentSummary[];
+}
+interface AgentContextTable {
+    type: "table";
+    ref: AgentReference;
+    rows: number;
+    columns: number;
+}
+interface AgentContextStory {
+    story: string;
+    kind: "body" | "header" | "footer" | "footnote" | "endnote" | "textbox";
+    blocks: Array<AgentContextParagraph | AgentContextTable>;
+    next?: AgentCursor;
+}
+interface AgentContextResult {
+    revision: string;
+    contents: AgentContextStory[];
+    truncated: boolean;
+    remainingStories?: string[];
+}
+interface AgentSearchResult {
+    revision: string;
+    matches: Array<{
+        blockRef: AgentReference;
+        runRef: AgentReference;
+        editable: boolean;
+        start: number;
+        end: number;
+        excerpt: string;
+    }>;
+    truncated: boolean;
+}
+interface AgentComponentSummary {
+    ref: AgentReference;
+    editRef?: AgentReference;
+    type: string;
+    label?: string;
+}
+interface AgentObjectResult {
+    revision: string;
+    ref: AgentReference;
+    editRef?: AgentReference;
+    type: string;
+    detail: Record<string, unknown>;
+}
+interface AgentAsset {
+    ref: AgentReference;
+    bytes: Uint8Array;
+    mediaType: string;
+}
+interface SpatialBounds {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+interface AgentSpatialObject {
+    ref: AgentReference;
+    editRef?: AgentReference;
+    type: string;
+    page: number;
+    bounds: SpatialBounds;
+    rotation?: number;
+    layer: "behind-text" | "body" | "in-front-of-text";
+    zOrder?: number;
+}
+interface AgentOverlap {
+    objects: [AgentReference, AgentReference];
+    overlapBounds: SpatialBounds;
+    overlapArea: number;
+    topObject?: AgentReference;
+}
+interface AgentSpatialResult {
+    revision: string;
+    layout: {
+        quality: "exact" | "approximate";
+        profile: string;
+    };
+    totalPages: number;
+    pages: Array<{
+        index: number;
+        width: number;
+        height: number;
+    }>;
+    objects: AgentSpatialObject[];
+    overlaps: AgentOverlap[];
+}
+type AgentInspectRequest = {
+    kind: "overview";
+} | {
+    kind: "context";
+    stories?: string[];
+    maxBlocks?: number;
+    maxCharacters?: number;
+    include?: Array<"bookmarks" | "objects">;
+    includeEmpty?: boolean;
+} | {
+    kind: "read";
+    story?: string;
+    cursor?: AgentCursor;
+    maxBlocks?: number;
+    maxCharacters?: number;
+} | {
+    kind: "search";
+    query: string;
+    maxResults?: number;
+} | {
+    kind: "object";
+    ref: AgentReference;
+} | {
+    kind: "spatial";
+    pages?: {
+        start: number;
+        count: number;
+    };
+    includeOverlaps?: boolean;
+};
+type AgentInspectResult = AgentOverview | AgentContextResult | AgentReadResult | AgentSearchResult | AgentObjectResult | AgentSpatialResult;
+type AgentOperation = Record<string, unknown> & {
+    kind: string;
+};
+interface AgentEditRequest {
+    revision: string;
+    operations: AgentOperation[];
+}
+interface AgentEditResult {
+    revision: string;
+    status: "applied" | "submitted";
+    operations: string[];
+    connection?: "local" | "live" | "offline" | "reconnecting";
+}
+interface AgentComposeRun {
+    text: string;
+    bold?: boolean;
+    italic?: boolean;
+    underline?: boolean;
+    color?: string;
+    highlight?: string;
+    fontSizePt?: number;
+    fontFamily?: string;
+}
+interface AgentComposeCell {
+    text?: string;
+    runs?: AgentComposeRun[];
+    fill?: string;
+    align?: "left" | "center" | "right";
+    verticalAlign?: "top" | "center" | "bottom";
+}
+interface AgentComposeTextStyle {
+    bold?: boolean;
+    italic?: boolean;
+    underline?: boolean;
+    color?: string;
+    fontSizePt?: number;
+    fontFamily?: string;
+    align?: "left" | "center" | "right";
+}
+type AgentComposeBlock = {
+    type: "paragraph";
+    text?: string;
+    runs?: AgentComposeRun[];
+    styleId?: "Normal" | "Title" | "Subtitle" | "Heading1" | "Heading2" | "Heading3";
+    align?: "left" | "center" | "right" | "both";
+    spacing?: {
+        beforePt?: number;
+        afterPt?: number;
+        lineMultiple?: number;
+    };
+    list?: "bullet" | "number";
+} | {
+    type: "heading";
+    level: 1 | 2 | 3;
+    text: string;
+} | {
+    type: "table";
+    rows: Array<Array<string | AgentComposeCell>>;
+    headerRows?: number;
+    headerFill?: string;
+    headerTextColor?: string;
+    columnWidths?: number[];
+} | {
+    type: "equation";
+    mathText: string;
+    align?: "left" | "center" | "right";
+} | {
+    type: "chart";
+    chart: {
+        type: "column" | "bar" | "line" | "pie";
+        title?: string;
+        categories: string[];
+        series: Array<{
+            name: string;
+            values: number[];
+        }>;
+    };
+    widthPx?: number;
+    heightPx?: number;
+    align?: "left" | "center" | "right";
+} | {
+    type: "smartArt";
+    smartArt: {
+        layout: "process" | "cycle" | "hierarchy" | "list";
+        items: string[];
+    };
+    widthPx?: number;
+    heightPx?: number;
+    align?: "left" | "center" | "right";
+} | {
+    type: "image";
+    assetRef: string;
+    widthPx: number;
+    heightPx: number;
+    alt?: string;
+    align?: "left" | "center" | "right";
+    wrap?: "inline" | "square" | "topAndBottom" | "none" | "behind";
+    position?: {
+        xPx: number;
+        yPx: number;
+    };
+} | {
+    type: "shape";
+    preset: "line" | "verticalLine" | "rectangle" | "roundedRectangle" | "ellipse" | "diamond" | "textBox";
+    text?: string;
+    textStyle?: AgentComposeTextStyle;
+    widthPx?: number;
+    heightPx?: number;
+    position?: {
+        xPx: number;
+        yPx: number;
+    };
+    fill?: string | null;
+    line?: {
+        color: string;
+        widthPx: number;
+        dash: "solid" | "dashed" | "dotted";
+    } | null;
+    wrap?: "inline" | "square" | "topAndBottom" | "none" | "behind";
+    order?: "front" | "back";
+} | {
+    type: "wordArt";
+    text: string;
+    preset: "plain" | "archUp" | "archDown" | "wave" | "chevron";
+    widthPx?: number;
+    heightPx?: number;
+    position?: {
+        xPx: number;
+        yPx: number;
+    };
+    rotation?: number;
+    fill?: string;
+    opacity?: number;
+    wrap?: "inline" | "square" | "topAndBottom" | "none" | "behind";
+    order?: "front" | "back";
+} | {
+    type: "pageNumber";
+    fieldKind: "page" | "pageOfTotal";
+    align?: "left" | "center" | "right";
+    color?: string;
+    fontSizePt?: number;
+    fontFamily?: string;
+    bold?: boolean;
+} | {
+    type: "pageBreak";
+};
+interface AgentComposeRequest {
+    revision: string;
+    body: AgentComposeBlock[];
+    header?: AgentComposeBlock[];
+    footer?: AgentComposeBlock[];
+    firstHeader?: AgentComposeBlock[];
+    firstFooter?: AgentComposeBlock[];
+    page?: {
+        margins?: {
+            top?: number;
+            right?: number;
+            bottom?: number;
+            left?: number;
+        };
+        size?: {
+            width: number;
+            height: number;
+        };
+        orientation?: "portrait" | "landscape";
+        columns?: number;
+        columnSeparator?: boolean;
+        mirrorMargins?: boolean;
+    };
+}
+interface AgentComposeResult {
+    revision: string;
+    status: "applied";
+    blocks: number;
+    components: number;
+    overview: AgentOverview;
+    createdObjects: AgentComponentSummary[];
+    createdObjectsTruncated: boolean;
+}
+interface AgentCollaborativeTarget {
+    getDocument(): DocxDocument | null;
+    getRevision(): string | number;
+    allocateIds(count: number): number[];
+    submit(operation: IntentBody): void | Promise<void>;
+    setPresence?(position: PresencePosition | null): void;
+    uploadMedia?(bytes: Uint8Array): Promise<{
+        blobSha: string;
+        bytesLen: number;
+        iv?: string;
+    } | null>;
+    getConnectionState?(): "local" | "live" | "offline" | "reconnecting";
+}
+interface AgentProvenance {
+    author: string;
+    now?: () => string;
+    nextId?: () => string;
+}
+interface AgentTool {
+    name: string;
+    description: string;
+    inputSchema: Record<string, unknown>;
+    execute(input: unknown): Promise<unknown>;
+}
+
+declare class AgentDocument {
+    private localDoc;
+    private localRevision;
+    private readonly target;
+    private readonly provenance;
+    private readonly addedAssets;
+    private assetCounter;
+    private composeAvailable;
+    private readonly listeners;
+    private readonly inspectedTargets;
+    private constructor();
+    static load(bytes: ArrayBuffer | Uint8Array, options?: {
+        provenance?: AgentProvenance;
+    }): AgentDocument;
+    static create(options?: {
+        provenance?: AgentProvenance;
+    }): AgentDocument;
+    static connect(target: AgentCollaborativeTarget, options?: {
+        provenance?: AgentProvenance;
+    }): AgentDocument;
+    get revision(): string;
+    get document(): DocxDocument;
+    subscribe(listener: (document: DocxDocument, revision: string) => void): () => void;
+    addAsset(bytes: Uint8Array, mediaType: string): string;
+    private inspector;
+    asset(ref: string): AgentAsset;
+    inspect(request: AgentInspectRequest): AgentInspectResult;
+    private recordInspection;
+    private revisionMatchesEdit;
+    capabilities(category?: AgentEditCapability["category"], kind?: Intent["kind"]): ReturnType<typeof agentCapabilities>;
+    compose(request: AgentComposeRequest): Promise<AgentComposeResult>;
+    edit(request: AgentEditRequest): Promise<AgentEditResult>;
+    private editLocal;
+    private editCollaborative;
+    save(): Uint8Array;
+    tools(): AgentTool[];
+}
+interface CollabSessionLike {
+    doc: DocxDocument | null;
+    version: number;
+    submitOp(operation: IntentBody): void;
+    setPresence?(position: PresencePosition | null): void;
+    allocIds(count: number): number[];
+    uploadMedia?(bytes: Uint8Array): Promise<{
+        blobSha: string;
+        bytesLen: number;
+        iv?: string;
+    } | null>;
+    connection: "live" | "reconnecting" | "lost";
+}
+/** Adapt the existing browser CollabSession without adding a React dependency.
+ * The accessor must return the latest hook value after each render. */
+declare function collaborativeAgentTarget(getSession: () => CollabSessionLike): AgentCollaborativeTarget;
+
+/**
+ * A canonical document session for one process. It lets a browser editor and
+ * an AgentDocument share one DocxDocument without a server or a DOM dependency.
+ */
+declare class LocalDocumentSession implements AgentCollaborativeTarget {
+    readonly doc: DocxDocument;
+    private revision;
+    private renderRevision;
+    private clientSequence;
+    private nextId;
+    private dirtyScope;
+    private readonly listeners;
+    private readonly uploadedMedia;
+    constructor(source: ArrayBuffer | Uint8Array | DocxDocument);
+    get version(): number;
+    get renderSignal(): number;
+    getDocument(): DocxDocument;
+    getRevision(): number;
+    getConnectionState(): "local";
+    allocateIds(count: number): number[];
+    allocIds: (count: number) => number[];
+    subscribe(listener: () => void): () => void;
+    takeRenderScope: () => Scope | null;
+    submit: (operation: IntentBody) => void;
+    submitOp: (operation: IntentBody) => void;
+    /** Record an operation that DocxView already applied to this same object. */
+    submitPreApplied: (operation: IntentBody) => void;
+    uploadMedia(bytes: Uint8Array): Promise<{
+        blobSha: string;
+        bytesLen: number;
+    }>;
+    private fullIntent;
+    private installUploadedImage;
+}
+interface LocalDocumentViewBinding {
+    subscribe(listener: () => void): () => void;
+    getSnapshot(): number;
+    doc: DocxDocument;
+    submit(operation: IntentBody): void;
+    submitOp(operation: IntentBody): void;
+    allocIds(count: number): number[];
+    uploadMedia(bytes: Uint8Array): Promise<{
+        blobSha: string;
+        bytesLen: number;
+    }>;
+    takeRenderScope(): {
+        kind: "doc";
+    } | {
+        kind: "block";
+        blocks: XmlElement[];
+    } | {
+        kind: "split";
+        before: XmlElement;
+        after: XmlElement;
+    } | null;
+}
+declare function localDocumentViewBinding(session: LocalDocumentSession): LocalDocumentViewBinding;
+
+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 };