@eigenpal/docx-editor-agents 0.5.0 → 1.0.0

package/dist/{server-DH5eszkm.d.mts → server-B7RHNVSu.d.mts}

@@ -8,7 +8,13 @@
  */
 type ThemeColorSlot = 'dk1' | 'lt1' | 'dk2' | 'lt2' | 'accent1' | 'accent2' | 'accent3' | 'accent4' | 'accent5' | 'accent6' | 'hlink' | 'folHlink' | 'background1' | 'text1' | 'background2' | 'text2';
 /**
- * Color value - can be direct RGB, theme reference, or auto
+ * ECMA-376 color reference — either a direct RGB hex, a theme slot
+ * reference (with optional tint/shade), or `auto` for context-dependent
+ * defaults (usually black for text on light backgrounds). When both
+ * `rgb` and `themeColor` are set, the theme wins on Word import and the
+ * `rgb` acts as a fallback for renderers without theme support.
+ *
+ * See ECMA-376 §17.18.39 (`ST_ThemeColor`).
  */
 interface ColorValue {
     /** RGB hex value without # (e.g., "FF0000") */
@@ -23,7 +29,12 @@ interface ColorValue {
     auto?: boolean;
 }
 /**
- * Border specification for any border (paragraph, table, page)
+ * One side of a border — style, color, width, spacing. Used by paragraph
+ * borders, table borders (per-cell or whole-table), and page borders.
+ * `size` is in eighths of a point (Word's wire format); `space` is in
+ * points.
+ *
+ * See ECMA-376 §17.18.2 (`ST_Border`).
  */
 interface BorderSpec {
     /** Border style */
@@ -40,7 +51,12 @@ interface BorderSpec {
     frame?: boolean;
 }
 /**
- * Shading/background properties
+ * Cell/paragraph/run shading — Word's combined "fill + pattern overlay"
+ * model. `fill` is the solid background; `color` is the pattern overlay
+ * drawn on top; `pattern` selects the pattern type (defaults to
+ * `'clear'` = solid `fill`, no pattern).
+ *
+ * See ECMA-376 §17.4.32 (`CT_Shd`).
  */
 interface ShadingProperties {
     /** Pattern fill color */
@@ -71,7 +87,14 @@ type TextEffect = 'none' | 'blinkBackground' | 'lights' | 'antsBlack' | 'antsRed
  */
 type EmphasisMark = 'none' | 'dot' | 'comma' | 'circle' | 'underDot';
 /**
- * Complete text formatting properties (w:rPr)
+ * Character-level formatting (`w:rPr`) — the full set of run properties
+ * Word supports: weight, slant, font, size, color, highlight, underline,
+ * strikethrough, vertical position, language, complex-script variants,
+ * spacing/kerning, emphasis marks, and more.
+ *
+ * Most fields mirror their ECMA-376 element names (see §17.3.2). Missing
+ * keys inherit from the run's paragraph style → linked style → document
+ * defaults chain.
  */
 interface TextFormatting {
     /** Bold (w:b) */
@@ -176,15 +199,24 @@ type LineSpacingRule = 'auto' | 'exact' | 'atLeast';
  */
 type ParagraphAlignment = 'left' | 'center' | 'right' | 'both' | 'distribute' | 'mediumKashida' | 'highKashida' | 'lowKashida' | 'thaiDistribute';
 /**
- * Complete paragraph formatting properties (w:pPr)
+ * Per-side flags identifying which `<w:spacing>` attrs were inline (not
+ * inherited from a style chain). Used to suppress style-only spacing on
+ * empty paragraphs per Word's behavior.
  */
-/** Per-side flags identifying which `<w:spacing>` attrs were inline (not
- *  inherited from a style chain). Used to suppress style-only spacing on
- *  empty paragraphs per Word's behavior. */
 type SpacingExplicit = {
     before?: boolean;
     after?: boolean;
 };
+/**
+ * Paragraph-level formatting (`w:pPr`) — alignment, indentation, spacing
+ * (before/after, line height), pagination flags (keepNext, keepLines,
+ * pageBreakBefore, widowControl), tabs, borders, shading, numbering
+ * reference, style reference, and frame/anchored-text properties.
+ *
+ * Most fields mirror their ECMA-376 element names (see §17.3.1).
+ * Inheritance: direct formatting beats the linked style which beats
+ * document defaults.
+ */
 interface ParagraphFormatting {
     /** Paragraph alignment (w:jc) */
     alignment?: ParagraphAlignment;
@@ -457,7 +489,12 @@ type NumberFormat = 'decimal' | 'upperRoman' | 'lowerRoman' | 'upperLetter' | 'l
  */
 type LevelSuffix = 'tab' | 'space' | 'nothing';
 /**
- * List level definition
+ * One indentation level of an abstract numbering definition (`w:lvl`).
+ * Carries the number format, the marker template (`lvlText` — e.g.
+ * `"%1.%2."`), the level's paragraph properties (indent, hanging) and
+ * character properties (font, size, color for the marker itself).
+ *
+ * `ilvl` ranges 0-8 in standard Word documents.
  */
 interface ListLevel {
     /** Level index (0-8) */
@@ -488,7 +525,13 @@ interface ListLevel {
     };
 }
 /**
- * Abstract numbering definition (w:abstractNum)
+ * Abstract numbering definition (`w:abstractNum`) — the reusable template
+ * for a list: which `NumberFormat` at each indentation level, what
+ * marker text, what paragraph/character formatting. Multiple
+ * `NumberingInstance`s (`w:num`) can reference one abstract numbering
+ * to share the template while keeping independent counters.
+ *
+ * See ECMA-376 §17.9.
  */
 interface AbstractNumbering {
     /** Abstract numbering ID */
@@ -520,7 +563,10 @@ interface NumberingInstance {
     }>;
 }
 /**
- * Computed list rendering info
+ * Computed list marker for one paragraph — what the layout engine and
+ * painter need to render the "1.", "a)", "•" prefix. Not part of the
+ * wire format; the parser fills this from the `numbering.xml` chain plus
+ * the paragraph's `numPr`. Paragraphs without list rendering omit it.
  */
 interface ListRendering {
     /** Computed marker text (e.g., "1.", "a)", "•") */
@@ -555,7 +601,10 @@ interface ListRendering {
     startOverride?: number;
 }
 /**
- * Complete numbering definitions
+ * Top-level numbering data from `numbering.xml` — the set of abstract
+ * templates and the per-document `NumberingInstance`s that reference
+ * them. Paragraphs reference a `numId` (instance), not an
+ * `abstractNumId` directly.
  */
 interface NumberingDefinitions {
     /** Abstract numbering definitions */
@@ -571,130 +620,20 @@ interface NumberingDefinitions {
  *   - `square` / `tight` / `through` — text wraps around the image
  *   - `topAndBottom` — text breaks above and below
  *   - `behind` / `inFront` (`wp:wrapNone`) — image paints out of flow
+ * @packageDocumentation
+ * @public
  */
 type WrapType = 'inline' | 'square' | 'tight' | 'through' | 'topAndBottom' | 'behind' | 'inFront';
 
 /**
- * Document Content Model
- *
- * All content-bearing types: runs, hyperlinks, bookmarks, fields,
- * images, shapes, tables, lists, paragraphs, headers/footers,
- * footnotes/endnotes, and sections.
- *
- * These types form a deeply interrelated tree (Paragraph ↔ Table ↔ ShapeTextBody)
- * and are kept together to avoid circular import issues.
+ * Hyperlinks (`w:hyperlink`), bookmark markers (`w:bookmarkStart`/`End`),
+ * and field types (`w:fldSimple`, complex `w:fldChar` runs).
  */
 
 /**
- * Plain text content
- */
-interface TextContent {
-    type: 'text';
-    /** The text string */
-    text: string;
-    /** Preserve whitespace (xml:space="preserve") */
-    preserveSpace?: boolean;
-}
-/**
- * Tab character
- */
-interface TabContent {
-    type: 'tab';
-}
-/**
- * Line break
- */
-interface BreakContent {
-    type: 'break';
-    /** Break type */
-    breakType?: 'page' | 'column' | 'textWrapping';
-    /** Clear type for text wrapping break */
-    clear?: 'none' | 'left' | 'right' | 'all';
-}
-/**
- * Symbol character (special font character)
- */
-interface SymbolContent {
-    type: 'symbol';
-    /** Font name */
-    font: string;
-    /** Character code */
-    char: string;
-}
-/**
- * Footnote or endnote reference
- */
-interface NoteReferenceContent {
-    type: 'footnoteRef' | 'endnoteRef';
-    /** Note ID */
-    id: number;
-}
-/**
- * Field character (begin/separate/end)
- */
-interface FieldCharContent {
-    type: 'fieldChar';
-    /** Field character type */
-    charType: 'begin' | 'separate' | 'end';
-    /** Field is locked */
-    fldLock?: boolean;
-    /** Field is dirty (needs update) */
-    dirty?: boolean;
-}
-/**
- * Field instruction text
- */
-interface InstrTextContent {
-    type: 'instrText';
-    /** Field instruction */
-    text: string;
-}
-/**
- * Soft hyphen
- */
-interface SoftHyphenContent {
-    type: 'softHyphen';
-}
-/**
- * Non-breaking hyphen
- */
-interface NoBreakHyphenContent {
-    type: 'noBreakHyphen';
-}
-/**
- * Drawing/image reference
- */
-interface DrawingContent {
-    type: 'drawing';
-    /** Image data */
-    image: Image;
-}
-/**
- * Shape reference
- */
-interface ShapeContent {
-    type: 'shape';
-    /** Shape data */
-    shape: Shape;
-}
-/**
- * All possible run content types
- */
-type RunContent = TextContent | TabContent | BreakContent | SymbolContent | NoteReferenceContent | FieldCharContent | InstrTextContent | SoftHyphenContent | NoBreakHyphenContent | DrawingContent | ShapeContent;
-/**
- * A run is a contiguous region of text with the same formatting
- */
-interface Run {
-    type: 'run';
-    /** Text formatting properties */
-    formatting?: TextFormatting;
-    /** Run-level tracked property changes (w:rPrChange) */
-    propertyChanges?: RunPropertyChange[];
-    /** Run content (text, tabs, breaks, etc.) */
-    content: RunContent[];
-}
-/**
- * Hyperlink (w:hyperlink)
+ * Hyperlink (`w:hyperlink`) — wraps runs in a clickable link. External
+ * targets resolve through the relationships part (`rId` → `href`);
+ * internal targets reference a `BookmarkStart` anchor by name.
  */
 interface Hyperlink {
     type: 'hyperlink';
@@ -774,241 +713,199 @@ interface ComplexField {
     /** Field is dirty */
     dirty?: boolean;
 }
+
 /**
- * Image size specification
+ * Math equations (`m:oMath`, `m:oMathPara`). OMML XML is round-tripped
+ * verbatim to preserve fidelity Word/Pages/Docs can disagree on.
  */
-interface ImageSize {
-    /** Width in EMUs (English Metric Units) */
-    width: number;
-    /** Height in EMUs */
-    height: number;
+/**
+ * Math equation content (m:oMath or m:oMathPara)
+ */
+interface MathEquation {
+    type: 'mathEquation';
+    /** Whether this is a block (oMathPara) or inline (oMath) equation */
+    display: 'inline' | 'block';
+    /** Raw OMML XML for round-trip preservation */
+    ommlXml: string;
+    /** Plain text representation for accessibility/fallback */
+    plainText?: string;
 }
+
 /**
- * Image wrap type for floating images
+ * Tracked-changes model — insertion/deletion/move wrappers, range
+ * markers, and per-element property-change wrappers (`w:rPrChange`,
+ * `w:pPrChange`, `w:tblPrChange`, `w:trPrChange`, `w:tcPrChange`) plus
+ * structural changes (row/cell insert/delete/merge).
  */
-interface ImageWrap {
-    type: WrapType;
-    /** Wrap text direction */
-    wrapText?: 'bothSides' | 'left' | 'right' | 'largest';
-    /** Distance from text */
-    distT?: number;
-    distB?: number;
-    distL?: number;
-    distR?: number;
+
+/**
+ * Tracked change metadata (w:ins, w:del attributes)
+ */
+interface TrackedChangeInfo {
+    /** Revision ID */
+    id: number;
+    /** Author who made the change */
+    author: string;
+    /** Date of the change */
+    date?: string;
 }
 /**
- * Position for floating images
+ * Generic tracked property-change wrapper metadata (w:*PrChange)
  */
-interface ImagePosition {
-    /** Horizontal positioning */
-    horizontal: {
-        relativeTo: 'character' | 'column' | 'insideMargin' | 'leftMargin' | 'margin' | 'outsideMargin' | 'page' | 'rightMargin';
-        alignment?: 'left' | 'right' | 'center' | 'inside' | 'outside';
-        posOffset?: number;
-    };
-    /** Vertical positioning */
-    vertical: {
-        relativeTo: 'insideMargin' | 'line' | 'margin' | 'outsideMargin' | 'page' | 'paragraph' | 'topMargin' | 'bottomMargin';
-        alignment?: 'top' | 'bottom' | 'center' | 'inside' | 'outside';
-        posOffset?: number;
-    };
+interface PropertyChangeInfo extends TrackedChangeInfo {
+    /** Optional revision session ID */
+    rsid?: string;
 }
 /**
- * Image transformation
+ * Insertion wrapper (w:ins) — runs inserted by tracked changes
  */
-interface ImageTransform {
-    /** Rotation in degrees */
-    rotation?: number;
-    /** Flip horizontal */
-    flipH?: boolean;
-    /** Flip vertical */
-    flipV?: boolean;
+interface Insertion {
+    type: 'insertion';
+    /** Tracked change metadata */
+    info: TrackedChangeInfo;
+    /** Inserted content */
+    content: (Run | Hyperlink)[];
 }
 /**
- * Image padding/margins
+ * Deletion wrapper (w:del) — runs deleted by tracked changes
  */
-interface ImagePadding {
-    top?: number;
-    bottom?: number;
-    left?: number;
-    right?: number;
+interface Deletion {
+    type: 'deletion';
+    /** Tracked change metadata */
+    info: TrackedChangeInfo;
+    /** Deleted content */
+    content: (Run | Hyperlink)[];
 }
 /**
- * Image crop, expressed as fractions of the source image to trim from each
- * edge. OOXML's `<a:srcRect l="10000" t="0" r="5000" b="0"/>` uses units of
- * 1/100000 (so 10000 → 0.1 → 10% trimmed from the left). We store the
- * normalised fraction so both the renderer and the saver can read it
- * directly without re-parsing units.
+ * Move-from wrapper (w:moveFrom) — content moved away from this position
  */
-interface ImageCrop {
-    left?: number;
-    top?: number;
-    right?: number;
-    bottom?: number;
+interface MoveFrom {
+    type: 'moveFrom';
+    /** Tracked change metadata */
+    info: TrackedChangeInfo;
+    /** Moved content */
+    content: (Run | Hyperlink)[];
 }
 /**
- * Embedded image (w:drawing)
+ * Move-to wrapper (w:moveTo) — content moved into this position
  */
-interface Image {
-    type: 'image';
-    /** Unique ID */
-    id?: string;
-    /** Relationship ID for the image data */
-    rId: string;
-    /** Resolved image data (base64 or blob URL) */
-    src?: string;
-    /** Image MIME type */
-    mimeType?: string;
-    /** Original filename */
-    filename?: string;
-    /** Alt text for accessibility */
-    alt?: string;
-    /** Title/description */
-    title?: string;
-    /** Image size */
-    size: ImageSize;
-    /** Original size before any transforms */
-    originalSize?: ImageSize;
-    /** Wrap settings */
-    wrap: ImageWrap;
-    /** Position for floating images */
-    position?: ImagePosition;
-    /** Image transformations */
-    transform?: ImageTransform;
-    /** Padding around image */
-    padding?: ImagePadding;
-    /** Source-image crop (fractional, OOXML `a:srcRect`). */
-    crop?: ImageCrop;
-    /** Opacity in [0, 1] (OOXML `a:alphaModFix amt`). Undefined = fully opaque. */
-    opacity?: number;
-    /** Whether this is a decorative image */
-    decorative?: boolean;
-    /**
-     * `wp:anchor layoutInCell` — when true (default), an anchored image inside
-     * a table cell is constrained to the cell. When false, the image escapes
-     * the cell into the page area. Round-tripped on save.
-     */
-    layoutInCell?: boolean;
-    /**
-     * `wp:anchor allowOverlap` — when true (default), anchored objects may
-     * overlap; when false, Word repositions them to avoid collisions. We
-     * don't currently reposition; we round-trip the flag so saving preserves
-     * the author's intent.
-     */
-    allowOverlap?: boolean;
-    /** Hyperlink URL for clickable image */
-    hlinkHref?: string;
-    /** Image outline/border */
-    outline?: ShapeOutline;
-    /** Image effects */
-    effects?: {
-        brightness?: number;
-        contrast?: number;
-        saturation?: number;
-    };
+interface MoveTo {
+    type: 'moveTo';
+    /** Tracked change metadata */
+    info: TrackedChangeInfo;
+    /** Moved content */
+    content: (Run | Hyperlink)[];
 }
 /**
- * Shape types
+ * Move-from range start marker (w:moveFromRangeStart) — ECMA-376 §17.13.5.22
+ * Pairs with moveFromRangeEnd to delimit the source of a move in the document.
  */
-type ShapeType = 'rect' | 'roundRect' | 'ellipse' | 'triangle' | 'rtTriangle' | 'parallelogram' | 'trapezoid' | 'pentagon' | 'hexagon' | 'heptagon' | 'octagon' | 'decagon' | 'dodecagon' | 'star4' | 'star5' | 'star6' | 'star7' | 'star8' | 'star10' | 'star12' | 'star16' | 'star24' | 'star32' | 'line' | 'straightConnector1' | 'bentConnector2' | 'bentConnector3' | 'bentConnector4' | 'bentConnector5' | 'curvedConnector2' | 'curvedConnector3' | 'curvedConnector4' | 'curvedConnector5' | 'rightArrow' | 'leftArrow' | 'upArrow' | 'downArrow' | 'leftRightArrow' | 'upDownArrow' | 'quadArrow' | 'leftRightUpArrow' | 'bentArrow' | 'uturnArrow' | 'leftUpArrow' | 'bentUpArrow' | 'curvedRightArrow' | 'curvedLeftArrow' | 'curvedUpArrow' | 'curvedDownArrow' | 'stripedRightArrow' | 'notchedRightArrow' | 'homePlate' | 'chevron' | 'rightArrowCallout' | 'downArrowCallout' | 'leftArrowCallout' | 'upArrowCallout' | 'leftRightArrowCallout' | 'quadArrowCallout' | 'circularArrow' | 'flowChartProcess' | 'flowChartAlternateProcess' | 'flowChartDecision' | 'flowChartInputOutput' | 'flowChartPredefinedProcess' | 'flowChartInternalStorage' | 'flowChartDocument' | 'flowChartMultidocument' | 'flowChartTerminator' | 'flowChartPreparation' | 'flowChartManualInput' | 'flowChartManualOperation' | 'flowChartConnector' | 'flowChartOffpageConnector' | 'flowChartPunchedCard' | 'flowChartPunchedTape' | 'flowChartSummingJunction' | 'flowChartOr' | 'flowChartCollate' | 'flowChartSort' | 'flowChartExtract' | 'flowChartMerge' | 'flowChartOnlineStorage' | 'flowChartDelay' | 'flowChartMagneticTape' | 'flowChartMagneticDisk' | 'flowChartMagneticDrum' | 'flowChartDisplay' | 'wedgeRectCallout' | 'wedgeRoundRectCallout' | 'wedgeEllipseCallout' | 'cloudCallout' | 'borderCallout1' | 'borderCallout2' | 'borderCallout3' | 'accentCallout1' | 'accentCallout2' | 'accentCallout3' | 'callout1' | 'callout2' | 'callout3' | 'accentBorderCallout1' | 'accentBorderCallout2' | 'accentBorderCallout3' | 'actionButtonBlank' | 'actionButtonHome' | 'actionButtonHelp' | 'actionButtonInformation' | 'actionButtonBackPrevious' | 'actionButtonForwardNext' | 'actionButtonBeginning' | 'actionButtonEnd' | 'actionButtonReturn' | 'actionButtonDocument' | 'actionButtonSound' | 'actionButtonMovie' | 'irregularSeal1' | 'irregularSeal2' | 'frame' | 'halfFrame' | 'corner' | 'diagStripe' | 'chord' | 'arc' | 'bracketPair' | 'bracePair' | 'leftBracket' | 'rightBracket' | 'leftBrace' | 'rightBrace' | 'can' | 'cube' | 'bevel' | 'donut' | 'noSmoking' | 'blockArc' | 'foldedCorner' | 'smileyFace' | 'heart' | 'lightningBolt' | 'sun' | 'moon' | 'cloud' | 'snip1Rect' | 'snip2SameRect' | 'snip2DiagRect' | 'snipRoundRect' | 'round1Rect' | 'round2SameRect' | 'round2DiagRect' | 'plaque' | 'teardrop' | 'mathPlus' | 'mathMinus' | 'mathMultiply' | 'mathDivide' | 'mathEqual' | 'mathNotEqual' | 'gear6' | 'gear9' | 'funnel' | 'pieWedge' | 'pie' | 'leftCircularArrow' | 'leftRightCircularArrow' | 'swooshArrow' | 'textBox';
+interface MoveFromRangeStart {
+    type: 'moveFromRangeStart';
+    id: number;
+    name: string;
+}
 /**
- * Shape fill type
+ * Move-from range end marker (w:moveFromRangeEnd)
  */
-interface ShapeFill {
-    type: 'none' | 'solid' | 'gradient' | 'pattern' | 'picture';
-    /** Solid fill color */
-    color?: ColorValue;
-    /** Gradient stops for gradient fill */
-    gradient?: {
-        type: 'linear' | 'radial' | 'rectangular' | 'path';
-        angle?: number;
-        stops: Array<{
-            position: number;
-            color: ColorValue;
-        }>;
-    };
+interface MoveFromRangeEnd {
+    type: 'moveFromRangeEnd';
+    id: number;
 }
 /**
- * Shape outline/stroke
+ * Move-to range start marker (w:moveToRangeStart) — ECMA-376 §17.13.5.24
+ * Pairs with moveToRangeEnd to delimit the destination of a move.
  */
-interface ShapeOutline {
-    /** Line width in EMUs */
-    width?: number;
-    /** Line color */
-    color?: ColorValue;
-    /** Line style */
-    style?: 'solid' | 'dot' | 'dash' | 'lgDash' | 'dashDot' | 'lgDashDot' | 'lgDashDotDot' | 'sysDot' | 'sysDash' | 'sysDashDot' | 'sysDashDotDot';
-    /** Line cap */
-    cap?: 'flat' | 'round' | 'square';
-    /** Line join */
-    join?: 'bevel' | 'miter' | 'round';
-    /** Head arrow */
-    headEnd?: {
-        type: 'none' | 'triangle' | 'stealth' | 'diamond' | 'oval' | 'arrow';
-        width?: 'sm' | 'med' | 'lg';
-        length?: 'sm' | 'med' | 'lg';
-    };
-    /** Tail arrow */
-    tailEnd?: {
-        type: 'none' | 'triangle' | 'stealth' | 'diamond' | 'oval' | 'arrow';
-        width?: 'sm' | 'med' | 'lg';
-        length?: 'sm' | 'med' | 'lg';
-    };
+interface MoveToRangeStart {
+    type: 'moveToRangeStart';
+    id: number;
+    name: string;
 }
 /**
- * Text body inside a shape
+ * Move-to range end marker (w:moveToRangeEnd)
  */
-interface ShapeTextBody {
-    /** Text direction */
-    vertical?: boolean;
-    /** Rotation */
-    rotation?: number;
-    /** Anchor/vertical alignment */
-    anchor?: 'top' | 'middle' | 'bottom' | 'distributed' | 'justified';
-    /** Anchor center */
-    anchorCenter?: boolean;
-    /** Auto fit */
-    autoFit?: 'none' | 'normal' | 'shape';
-    /** Text margins */
-    margins?: {
-        top?: number;
-        bottom?: number;
-        left?: number;
-        right?: number;
-    };
-    /** Paragraphs inside the shape */
-    content: Paragraph[];
+interface MoveToRangeEnd {
+    type: 'moveToRangeEnd';
+    id: number;
 }
 /**
- * Shape/drawing object (wps:wsp)
+ * Run property change (w:rPrChange)
  */
-interface Shape {
-    type: 'shape';
-    /** Shape type preset */
-    shapeType: ShapeType;
-    /** Unique ID */
-    id?: string;
-    /** Name */
-    name?: string;
-    /** Size in EMUs */
-    size: ImageSize;
-    /** Position for floating shapes */
-    position?: ImagePosition;
-    /** Wrap settings */
-    wrap?: ImageWrap;
-    /** Fill */
-    fill?: ShapeFill;
-    /** Outline/stroke */
-    outline?: ShapeOutline;
-    /** Transform */
-    transform?: ImageTransform;
-    /** Text content inside the shape */
-    textBody?: ShapeTextBody;
-    /** Custom geometry points */
-    customGeometry?: string;
+interface RunPropertyChange {
+    type: 'runPropertyChange';
+    /** Tracked change metadata */
+    info: PropertyChangeInfo;
+    /** Run properties before the tracked change */
+    previousFormatting?: TextFormatting;
+    /** Run properties after the tracked change (editor model convenience) */
+    currentFormatting?: TextFormatting;
+}
+/**
+ * Paragraph property change (w:pPrChange)
+ */
+interface ParagraphPropertyChange {
+    type: 'paragraphPropertyChange';
+    /** Tracked change metadata */
+    info: PropertyChangeInfo;
+    /** Paragraph properties before the tracked change */
+    previousFormatting?: ParagraphFormatting;
+    /** Paragraph properties after the tracked change (editor model convenience) */
+    currentFormatting?: ParagraphFormatting;
+}
+/**
+ * Table property change (w:tblPrChange)
+ */
+interface TablePropertyChange {
+    type: 'tablePropertyChange';
+    /** Tracked change metadata */
+    info: PropertyChangeInfo;
+    /** Table properties before the tracked change */
+    previousFormatting?: TableFormatting;
+    /** Table properties after the tracked change (editor model convenience) */
+    currentFormatting?: TableFormatting;
+}
+/**
+ * Table row property change (w:trPrChange)
+ */
+interface TableRowPropertyChange {
+    type: 'tableRowPropertyChange';
+    /** Tracked change metadata */
+    info: PropertyChangeInfo;
+    /** Row properties before the tracked change */
+    previousFormatting?: TableRowFormatting;
+    /** Row properties after the tracked change (editor model convenience) */
+    currentFormatting?: TableRowFormatting;
+}
+/**
+ * Table cell property change (w:tcPrChange)
+ */
+interface TableCellPropertyChange {
+    type: 'tableCellPropertyChange';
+    /** Tracked change metadata */
+    info: PropertyChangeInfo;
+    /** Cell properties before the tracked change */
+    previousFormatting?: TableCellFormatting;
+    /** Cell properties after the tracked change (editor model convenience) */
+    currentFormatting?: TableCellFormatting;
 }
 /**
- * Table cell
+ * Table structural tracked change metadata (row/cell insert/delete/merge)
+ */
+interface TableStructuralChangeInfo {
+    type: 'tableRowInsertion' | 'tableRowDeletion' | 'tableCellInsertion' | 'tableCellDeletion' | 'tableCellMerge';
+    /** Tracked change metadata */
+    info: TrackedChangeInfo;
+}
+
+/**
+ * Tables (`w:tbl`), rows (`w:tr`), and cells (`w:tc`).
+ */
+
+/**
+ * Table cell (`w:tc`). Holds nested block content (paragraphs and nested
+ * tables), cell-level formatting (borders, shading, vertical merge),
+ * tracked property changes, and tracked structural changes for cell
+ * insert/delete/merge operations.
  */
 interface TableCell {
     type: 'tableCell';
@@ -1022,7 +919,9 @@ interface TableCell {
     content: (Paragraph | Table)[];
 }
 /**
- * Table row
+ * Table row (`w:tr`) — an ordered list of `TableCell` plus row-level
+ * formatting (height, repeated header, cantSplit) and tracked changes
+ * for inserts/deletes.
  */
 interface TableRow {
     type: 'tableRow';
@@ -1036,7 +935,12 @@ interface TableRow {
     cells: TableCell[];
 }
 /**
- * Table (w:tbl)
+ * Table (`w:tbl`) — a block-level grid of rows × cells. Tables carry
+ * their own formatting layer (borders, shading, alignment, indent,
+ * floating placement) and an explicit column-width grid in twips. Tables
+ * can nest arbitrarily through `TableCell.content`.
+ *
+ * See ECMA-376 §17.4.
  */
 interface Table {
     type: 'table';
@@ -1049,265 +953,404 @@ interface Table {
     /** Table rows */
     rows: TableRow[];
 }
+
 /**
- * A comment (w:comment) from comments.xml
+ * Structured Document Tags / content controls (`w:sdt`) — inline and
+ * block variants, plus properties (alias, tag, lock, list items,
+ * checkbox state) for the supported SDT types.
  */
-interface Comment {
-    /** Comment ID (matches commentRangeStart/End) */
-    id: number;
-    /** Author name */
-    author: string;
-    /** Author initials */
-    initials?: string;
-    /** Date */
-    date?: string;
-    /** Comment content (paragraphs) */
-    content: Paragraph[];
-    /** Parent comment ID (for replies) */
-    parentId?: number;
-    /** Whether the comment is resolved/done */
-    done?: boolean;
-}
+
 /**
- * Comment range start marker in paragraph content
+ * SDT type (content control type)
  */
-interface CommentRangeStart {
-    type: 'commentRangeStart';
-    id: number;
+type SdtType = 'richText' | 'plainText' | 'date' | 'dropdown' | 'comboBox' | 'checkbox' | 'picture' | 'buildingBlockGallery' | 'group' | 'unknown';
+/**
+ * SDT properties (w:sdtPr)
+ */
+interface SdtProperties {
+    /** SDT type */
+    sdtType: SdtType;
+    /** Alias (friendly name) */
+    alias?: string;
+    /** Tag (developer identifier) */
+    tag?: string;
+    /** Lock content editing */
+    lock?: 'sdtLocked' | 'contentLocked' | 'sdtContentLocked' | 'unlocked';
+    /** Placeholder text */
+    placeholder?: string;
+    /** Whether showing placeholder */
+    showingPlaceholder?: boolean;
+    /** Date format for date controls */
+    dateFormat?: string;
+    /** Dropdown/combobox list items */
+    listItems?: {
+        displayText: string;
+        value: string;
+    }[];
+    /** Checkbox checked state */
+    checked?: boolean;
 }
 /**
- * Comment range end marker in paragraph content
+ * Inline SDT (content control within a paragraph)
  */
-interface CommentRangeEnd {
-    type: 'commentRangeEnd';
-    id: number;
+interface InlineSdt {
+    type: 'inlineSdt';
+    /** SDT properties */
+    properties: SdtProperties;
+    /**
+     * Inline content held inside the control. OOXML allows runs,
+     * hyperlinks, simple/complex fields, nested SDTs, and math at this
+     * level; the renderer must descend into all of them so docProps-bound
+     * fields and similar template content survive paged rendering.
+     */
+    content: (Run | Hyperlink | SimpleField | ComplexField | InlineSdt | MathEquation)[];
 }
 /**
- * Math equation content (m:oMath or m:oMathPara)
+ * Block-level SDT (content control wrapping paragraphs/tables)
  */
-interface MathEquation {
-    type: 'mathEquation';
-    /** Whether this is a block (oMathPara) or inline (oMath) equation */
-    display: 'inline' | 'block';
-    /** Raw OMML XML for round-trip preservation */
-    ommlXml: string;
-    /** Plain text representation for accessibility/fallback */
-    plainText?: string;
+interface BlockSdt {
+    type: 'blockSdt';
+    /** SDT properties */
+    properties: SdtProperties;
+    /** Block content inside the control */
+    content: (Paragraph | Table)[];
 }
+
 /**
- * Tracked change metadata (w:ins, w:del attributes)
+ * Comments (`w:comment` in `comments.xml`) and the inline range markers
+ * (`w:commentRangeStart`/`End`) that anchor them inside paragraphs.
  */
-interface TrackedChangeInfo {
-    /** Revision ID */
+
+/**
+ * A comment from `comments.xml` — the top-level entity for review
+ * comments and replies. `id` matches the inline `CommentRangeStart` /
+ * `CommentRangeEnd` markers that anchor it inside a paragraph; `parentId`
+ * threads replies under their parent; `done` reflects Word's "Resolve"
+ * state (`w15:done`).
+ */
+interface Comment {
+    /** Comment ID (matches commentRangeStart/End) */
     id: number;
-    /** Author who made the change */
+    /** Author name */
     author: string;
-    /** Date of the change */
+    /** Author initials */
+    initials?: string;
+    /** Date */
     date?: string;
+    /** Comment content (paragraphs) */
+    content: Paragraph[];
+    /** Parent comment ID (for replies) */
+    parentId?: number;
+    /** Whether the comment is resolved/done */
+    done?: boolean;
 }
 /**
- * Generic tracked property-change wrapper metadata (w:*PrChange)
+ * Comment range start marker in paragraph content
  */
-interface PropertyChangeInfo extends TrackedChangeInfo {
-    /** Optional revision session ID */
-    rsid?: string;
+interface CommentRangeStart {
+    type: 'commentRangeStart';
+    id: number;
 }
 /**
- * Insertion wrapper (w:ins) — runs inserted by tracked changes
+ * Comment range end marker in paragraph content
  */
-interface Insertion {
-    type: 'insertion';
-    /** Tracked change metadata */
-    info: TrackedChangeInfo;
-    /** Inserted content */
-    content: (Run | Hyperlink)[];
+interface CommentRangeEnd {
+    type: 'commentRangeEnd';
+    id: number;
 }
+
 /**
- * Deletion wrapper (w:del) — runs deleted by tracked changes
+ * Page furniture — headers (`w:hdr`), footers (`w:ftr`), footnotes
+ * (`w:footnote`), and endnotes (`w:endnote`), plus the section-level
+ * properties (`w:footnotePr`/`w:endnotePr`) that configure note layout.
  */
-interface Deletion {
-    type: 'deletion';
-    /** Tracked change metadata */
-    info: TrackedChangeInfo;
-    /** Deleted content */
-    content: (Run | Hyperlink)[];
-}
+
 /**
- * Move-from wrapper (w:moveFrom) — content moved away from this position
+ * Header/footer type
  */
-interface MoveFrom {
-    type: 'moveFrom';
-    /** Tracked change metadata */
-    info: TrackedChangeInfo;
-    /** Moved content */
-    content: (Run | Hyperlink)[];
-}
+type HeaderFooterType = 'default' | 'first' | 'even';
 /**
- * Move-to wrapper (w:moveTo) — content moved into this position
+ * Header or footer reference
  */
-interface MoveTo {
-    type: 'moveTo';
-    /** Tracked change metadata */
-    info: TrackedChangeInfo;
-    /** Moved content */
-    content: (Run | Hyperlink)[];
+interface HeaderReference {
+    type: HeaderFooterType;
+    rId: string;
+}
+interface FooterReference {
+    type: HeaderFooterType;
+    rId: string;
 }
 /**
- * Move-from range start marker (w:moveFromRangeStart) — ECMA-376 §17.13.5.22
- * Pairs with moveFromRangeEnd to delimit the source of a move in the document.
+ * Header or footer content
  */
-interface MoveFromRangeStart {
-    type: 'moveFromRangeStart';
-    id: number;
-    name: string;
+interface HeaderFooter {
+    type: 'header' | 'footer';
+    /** Header/footer type */
+    hdrFtrType: HeaderFooterType;
+    /** Content (paragraphs, tables, etc.) */
+    content: (Paragraph | Table)[];
 }
 /**
- * Move-from range end marker (w:moveFromRangeEnd)
+ * Footnote position
  */
-interface MoveFromRangeEnd {
-    type: 'moveFromRangeEnd';
-    id: number;
+type FootnotePosition = 'pageBottom' | 'beneathText' | 'sectEnd' | 'docEnd';
+/**
+ * Endnote position
+ */
+type EndnotePosition = 'sectEnd' | 'docEnd';
+/**
+ * Number restart type
+ */
+type NoteNumberRestart = 'continuous' | 'eachSect' | 'eachPage';
+/**
+ * Footnote properties
+ */
+interface FootnoteProperties {
+    position?: FootnotePosition;
+    numFmt?: NumberFormat;
+    numStart?: number;
+    numRestart?: NoteNumberRestart;
 }
 /**
- * Move-to range start marker (w:moveToRangeStart) — ECMA-376 §17.13.5.24
- * Pairs with moveToRangeEnd to delimit the destination of a move.
+ * Endnote properties
  */
-interface MoveToRangeStart {
-    type: 'moveToRangeStart';
-    id: number;
-    name: string;
+interface EndnoteProperties {
+    position?: EndnotePosition;
+    numFmt?: NumberFormat;
+    numStart?: number;
+    numRestart?: NoteNumberRestart;
 }
 /**
- * Move-to range end marker (w:moveToRangeEnd)
+ * Footnote (w:footnote)
  */
-interface MoveToRangeEnd {
-    type: 'moveToRangeEnd';
+interface Footnote {
+    type: 'footnote';
+    /** Footnote ID */
     id: number;
+    /** Special footnote type */
+    noteType?: 'normal' | 'separator' | 'continuationSeparator' | 'continuationNotice';
+    /**
+     * Content. Per ECMA-376 §17.11.10 footnotes can hold the same blocks as
+     * the body — paragraphs and tables. The parser previously only collected
+     * <w:p> children which silently dropped any <w:tbl> inside a footnote;
+     * widened to match HeaderFooter / TableCell shape so the body pipeline
+     * (toProseDoc → toFlowBlocks) can render them uniformly.
+     */
+    content: (Paragraph | Table)[];
 }
 /**
- * Run property change (w:rPrChange)
+ * Endnote (w:endnote)
  */
-interface RunPropertyChange {
-    type: 'runPropertyChange';
-    /** Tracked change metadata */
-    info: PropertyChangeInfo;
-    /** Run properties before the tracked change */
-    previousFormatting?: TextFormatting;
-    /** Run properties after the tracked change (editor model convenience) */
-    currentFormatting?: TextFormatting;
+interface Endnote {
+    type: 'endnote';
+    /** Endnote ID */
+    id: number;
+    /** Special endnote type */
+    noteType?: 'normal' | 'separator' | 'continuationSeparator' | 'continuationNotice';
+    /**
+     * Content. Per ECMA-376 §17.11.4 endnotes can hold the same blocks as
+     * the body — paragraphs and tables. See note on `Footnote.content`.
+     */
+    content: (Paragraph | Table)[];
 }
+
 /**
- * Paragraph property change (w:pPrChange)
+ * Section properties (`w:sectPr`) — page size and margins, columns,
+ * header/footer references, line numbers, page borders, document grid,
+ * paper sources — plus the section and document-body containers that
+ * group block-level content.
  */
-interface ParagraphPropertyChange {
-    type: 'paragraphPropertyChange';
-    /** Tracked change metadata */
-    info: PropertyChangeInfo;
-    /** Paragraph properties before the tracked change */
-    previousFormatting?: ParagraphFormatting;
-    /** Paragraph properties after the tracked change (editor model convenience) */
-    currentFormatting?: ParagraphFormatting;
-}
+
 /**
- * Table property change (w:tblPrChange)
+ * Page orientation
  */
-interface TablePropertyChange {
-    type: 'tablePropertyChange';
-    /** Tracked change metadata */
-    info: PropertyChangeInfo;
-    /** Table properties before the tracked change */
-    previousFormatting?: TableFormatting;
-    /** Table properties after the tracked change (editor model convenience) */
-    currentFormatting?: TableFormatting;
-}
+type PageOrientation = 'portrait' | 'landscape';
 /**
- * Table row property change (w:trPrChange)
+ * Section start type
  */
-interface TableRowPropertyChange {
-    type: 'tableRowPropertyChange';
-    /** Tracked change metadata */
-    info: PropertyChangeInfo;
-    /** Row properties before the tracked change */
-    previousFormatting?: TableRowFormatting;
-    /** Row properties after the tracked change (editor model convenience) */
-    currentFormatting?: TableRowFormatting;
-}
+type SectionStart = 'continuous' | 'nextPage' | 'oddPage' | 'evenPage' | 'nextColumn';
 /**
- * Table cell property change (w:tcPrChange)
+ * Vertical alignment
  */
-interface TableCellPropertyChange {
-    type: 'tableCellPropertyChange';
-    /** Tracked change metadata */
-    info: PropertyChangeInfo;
-    /** Cell properties before the tracked change */
-    previousFormatting?: TableCellFormatting;
-    /** Cell properties after the tracked change (editor model convenience) */
-    currentFormatting?: TableCellFormatting;
-}
+type VerticalAlign = 'top' | 'center' | 'both' | 'bottom';
 /**
- * Table structural tracked change metadata (row/cell insert/delete/merge)
+ * Line number restart type
  */
-interface TableStructuralChangeInfo {
-    type: 'tableRowInsertion' | 'tableRowDeletion' | 'tableCellInsertion' | 'tableCellDeletion' | 'tableCellMerge';
-    /** Tracked change metadata */
-    info: TrackedChangeInfo;
-}
+type LineNumberRestart = 'continuous' | 'newPage' | 'newSection';
 /**
- * SDT type (content control type)
+ * Column definition
  */
-type SdtType = 'richText' | 'plainText' | 'date' | 'dropdown' | 'comboBox' | 'checkbox' | 'picture' | 'buildingBlockGallery' | 'group' | 'unknown';
+interface Column {
+    /** Column width in twips */
+    width?: number;
+    /** Space after column in twips */
+    space?: number;
+}
 /**
- * SDT properties (w:sdtPr)
+ * Section properties (`w:sectPr`) — page geometry, margins, columns,
+ * header/footer references, and page numbering for one section of the
+ * document. Sections are introduced by inline `sectPr` markers on the
+ * terminating paragraph (`Paragraph.sectionProperties`) and the body's
+ * final `sectPr`.
+ *
+ * All distance units are twips (1/20 of a point) on the wire. The layout
+ * engine converts to pixels.
+ *
+ * See ECMA-376 §17.6.
  */
-interface SdtProperties {
-    /** SDT type */
-    sdtType: SdtType;
-    /** Alias (friendly name) */
-    alias?: string;
-    /** Tag (developer identifier) */
-    tag?: string;
-    /** Lock content editing */
-    lock?: 'sdtLocked' | 'contentLocked' | 'sdtContentLocked' | 'unlocked';
-    /** Placeholder text */
-    placeholder?: string;
-    /** Whether showing placeholder */
-    showingPlaceholder?: boolean;
-    /** Date format for date controls */
-    dateFormat?: string;
-    /** Dropdown/combobox list items */
-    listItems?: {
-        displayText: string;
-        value: string;
-    }[];
-    /** Checkbox checked state */
-    checked?: boolean;
+interface SectionProperties {
+    /** Page width in twips */
+    pageWidth?: number;
+    /** Page height in twips */
+    pageHeight?: number;
+    /** Page orientation */
+    orientation?: PageOrientation;
+    /** Top margin in twips */
+    marginTop?: number;
+    /** Bottom margin in twips */
+    marginBottom?: number;
+    /** Left margin in twips */
+    marginLeft?: number;
+    /** Right margin in twips */
+    marginRight?: number;
+    /** Header distance from top in twips */
+    headerDistance?: number;
+    /** Footer distance from bottom in twips */
+    footerDistance?: number;
+    /** Gutter margin in twips */
+    gutter?: number;
+    /** Number of columns */
+    columnCount?: number;
+    /** Space between columns in twips */
+    columnSpace?: number;
+    /** Equal width columns */
+    equalWidth?: boolean;
+    /** Separator line between columns */
+    separator?: boolean;
+    /** Individual column definitions */
+    columns?: Column[];
+    /** Section start type */
+    sectionStart?: SectionStart;
+    /** Vertical alignment of text */
+    verticalAlign?: VerticalAlign;
+    /** Right-to-left section */
+    bidi?: boolean;
+    /** Header references */
+    headerReferences?: HeaderReference[];
+    /** Footer references */
+    footerReferences?: FooterReference[];
+    /** Different first page header/footer */
+    titlePg?: boolean;
+    /** Different odd/even page headers/footers */
+    evenAndOddHeaders?: boolean;
+    /** Line numbering settings */
+    lineNumbers?: {
+        start?: number;
+        countBy?: number;
+        distance?: number;
+        restart?: LineNumberRestart;
+    };
+    /** Page borders */
+    pageBorders?: {
+        top?: BorderSpec;
+        bottom?: BorderSpec;
+        left?: BorderSpec;
+        right?: BorderSpec;
+        /** Display setting */
+        display?: 'allPages' | 'firstPage' | 'notFirstPage';
+        /** Offset from */
+        offsetFrom?: 'page' | 'text';
+        /** Z-order */
+        zOrder?: 'front' | 'back';
+    };
+    /** Page background */
+    background?: {
+        color?: ColorValue;
+        themeColor?: ThemeColorSlot;
+        themeTint?: string;
+        themeShade?: string;
+    };
+    /** Footnote properties for this section */
+    footnotePr?: FootnoteProperties;
+    /** Endnote properties for this section */
+    endnotePr?: EndnoteProperties;
+    /** Document grid */
+    docGrid?: {
+        type?: 'default' | 'lines' | 'linesAndChars' | 'snapToChars';
+        linePitch?: number;
+        charSpace?: number;
+    };
+    /** First page paper source */
+    paperSrcFirst?: number;
+    /** Other pages paper source */
+    paperSrcOther?: number;
 }
 /**
- * Inline SDT (content control within a paragraph)
+ * Block-level content types
  */
-interface InlineSdt {
-    type: 'inlineSdt';
-    /** SDT properties */
-    properties: SdtProperties;
-    /** Content runs inside the control */
-    content: (Run | Hyperlink)[];
+type BlockContent = Paragraph | Table | BlockSdt;
+/**
+ * One section of the document — a `SectionProperties` plus the block
+ * content (`Paragraph`s and `Table`s) that lives under those properties.
+ *
+ * Sections are derived during parse: every paragraph carrying an inline
+ * `sectPr` ends a section, and the body's final `sectPr` defines the
+ * last section. Each section may carry its own headers/footers map.
+ */
+interface Section {
+    /** Section properties */
+    properties: SectionProperties;
+    /** Content in this section */
+    content: BlockContent[];
+    /** Headers for this section */
+    headers?: Map<HeaderFooterType, HeaderFooter>;
+    /** Footers for this section */
+    footers?: Map<HeaderFooterType, HeaderFooter>;
 }
 /**
- * Block-level SDT (content control wrapping paragraphs/tables)
+ * Document body (`w:body`) — the editable content of the document.
+ *
+ * Contains the ordered block content (paragraphs and tables), the section
+ * layout chain derived from inline `sectPr` markers, the final `sectPr`,
+ * and any document-level comments. This is what most edit operations
+ * mutate; headers/footers/styles live elsewhere in the package.
  */
-interface BlockSdt {
-    type: 'blockSdt';
-    /** SDT properties */
-    properties: SdtProperties;
-    /** Block content inside the control */
-    content: (Paragraph | Table)[];
+interface DocumentBody {
+    /** All content (paragraphs, tables) */
+    content: BlockContent[];
+    /** Sections (derived from sectPr in paragraphs and final sectPr) */
+    sections?: Section[];
+    /** Final section properties (from body's sectPr) */
+    finalSectionProperties?: SectionProperties;
+    /** Comments from comments.xml */
+    comments?: Comment[];
 }
+
+/**
+ * Paragraph (`w:p`) — the union of inline content that can sit inside a
+ * paragraph (runs, hyperlinks, bookmarks, fields, SDT, comment ranges,
+ * tracked-change wrappers, math) plus paragraph-level metadata
+ * (formatting, list rendering, optional terminating section properties).
+ */
+
 /**
- * Paragraph content types
+ * Inline content that can appear inside a paragraph. Covers runs (text),
+ * hyperlinks, bookmarks, fields, structured document tags, comment range
+ * markers, tracked-change wrappers, and math equations. Every node in
+ * this union carries a `type` discriminator so consumers can narrow at
+ * runtime.
  */
 type ParagraphContent = Run | Hyperlink | BookmarkStart | BookmarkEnd | SimpleField | ComplexField | InlineSdt | CommentRangeStart | CommentRangeEnd | Insertion | Deletion | MoveFrom | MoveTo | MoveFromRangeStart | MoveFromRangeEnd | MoveToRangeStart | MoveToRangeEnd | MathEquation;
 /**
- * Paragraph (w:p)
+ * Paragraph (`w:p`) — the primary block-level container in a Word document.
+ *
+ * Every paragraph carries direct formatting (`formatting`), tracked
+ * property changes (`propertyChanges`), inline content (`content`), and
+ * optional list rendering / section break metadata. `paraId` is Word's
+ * stable identifier (`w14:paraId`) and is what `EditorBridge` and the
+ * agent toolkit use to address paragraphs.
+ *
+ * See ECMA-376 §17.3.1.
  */
 interface Paragraph {
     type: 'paragraph';
@@ -1328,238 +1371,387 @@ interface Paragraph {
     /** Section properties (if this paragraph ends a section) */
     sectionProperties?: SectionProperties;
 }
+
 /**
- * Header/footer type
+ * DrawingML shapes (`wps:wsp`) and text boxes — preset shape types,
+ * fill, outline, shape text body, transform.
  */
-type HeaderFooterType = 'default' | 'first' | 'even';
+
 /**
- * Header or footer reference
+ * Shape types
  */
-interface HeaderReference {
-    type: HeaderFooterType;
-    rId: string;
+type ShapeType = 'rect' | 'roundRect' | 'ellipse' | 'triangle' | 'rtTriangle' | 'parallelogram' | 'trapezoid' | 'pentagon' | 'hexagon' | 'heptagon' | 'octagon' | 'decagon' | 'dodecagon' | 'star4' | 'star5' | 'star6' | 'star7' | 'star8' | 'star10' | 'star12' | 'star16' | 'star24' | 'star32' | 'line' | 'straightConnector1' | 'bentConnector2' | 'bentConnector3' | 'bentConnector4' | 'bentConnector5' | 'curvedConnector2' | 'curvedConnector3' | 'curvedConnector4' | 'curvedConnector5' | 'rightArrow' | 'leftArrow' | 'upArrow' | 'downArrow' | 'leftRightArrow' | 'upDownArrow' | 'quadArrow' | 'leftRightUpArrow' | 'bentArrow' | 'uturnArrow' | 'leftUpArrow' | 'bentUpArrow' | 'curvedRightArrow' | 'curvedLeftArrow' | 'curvedUpArrow' | 'curvedDownArrow' | 'stripedRightArrow' | 'notchedRightArrow' | 'homePlate' | 'chevron' | 'rightArrowCallout' | 'downArrowCallout' | 'leftArrowCallout' | 'upArrowCallout' | 'leftRightArrowCallout' | 'quadArrowCallout' | 'circularArrow' | 'flowChartProcess' | 'flowChartAlternateProcess' | 'flowChartDecision' | 'flowChartInputOutput' | 'flowChartPredefinedProcess' | 'flowChartInternalStorage' | 'flowChartDocument' | 'flowChartMultidocument' | 'flowChartTerminator' | 'flowChartPreparation' | 'flowChartManualInput' | 'flowChartManualOperation' | 'flowChartConnector' | 'flowChartOffpageConnector' | 'flowChartPunchedCard' | 'flowChartPunchedTape' | 'flowChartSummingJunction' | 'flowChartOr' | 'flowChartCollate' | 'flowChartSort' | 'flowChartExtract' | 'flowChartMerge' | 'flowChartOnlineStorage' | 'flowChartDelay' | 'flowChartMagneticTape' | 'flowChartMagneticDisk' | 'flowChartMagneticDrum' | 'flowChartDisplay' | 'wedgeRectCallout' | 'wedgeRoundRectCallout' | 'wedgeEllipseCallout' | 'cloudCallout' | 'borderCallout1' | 'borderCallout2' | 'borderCallout3' | 'accentCallout1' | 'accentCallout2' | 'accentCallout3' | 'callout1' | 'callout2' | 'callout3' | 'accentBorderCallout1' | 'accentBorderCallout2' | 'accentBorderCallout3' | 'actionButtonBlank' | 'actionButtonHome' | 'actionButtonHelp' | 'actionButtonInformation' | 'actionButtonBackPrevious' | 'actionButtonForwardNext' | 'actionButtonBeginning' | 'actionButtonEnd' | 'actionButtonReturn' | 'actionButtonDocument' | 'actionButtonSound' | 'actionButtonMovie' | 'irregularSeal1' | 'irregularSeal2' | 'frame' | 'halfFrame' | 'corner' | 'diagStripe' | 'chord' | 'arc' | 'bracketPair' | 'bracePair' | 'leftBracket' | 'rightBracket' | 'leftBrace' | 'rightBrace' | 'can' | 'cube' | 'bevel' | 'donut' | 'noSmoking' | 'blockArc' | 'foldedCorner' | 'smileyFace' | 'heart' | 'lightningBolt' | 'sun' | 'moon' | 'cloud' | 'snip1Rect' | 'snip2SameRect' | 'snip2DiagRect' | 'snipRoundRect' | 'round1Rect' | 'round2SameRect' | 'round2DiagRect' | 'plaque' | 'teardrop' | 'mathPlus' | 'mathMinus' | 'mathMultiply' | 'mathDivide' | 'mathEqual' | 'mathNotEqual' | 'gear6' | 'gear9' | 'funnel' | 'pieWedge' | 'pie' | 'leftCircularArrow' | 'leftRightCircularArrow' | 'swooshArrow' | 'textBox';
+/**
+ * Shape fill type
+ */
+interface ShapeFill {
+    type: 'none' | 'solid' | 'gradient' | 'pattern' | 'picture';
+    /** Solid fill color */
+    color?: ColorValue;
+    /** Gradient stops for gradient fill */
+    gradient?: {
+        type: 'linear' | 'radial' | 'rectangular' | 'path';
+        angle?: number;
+        stops: Array<{
+            position: number;
+            color: ColorValue;
+        }>;
+    };
 }
-interface FooterReference {
-    type: HeaderFooterType;
-    rId: string;
+/**
+ * Shape outline/stroke
+ */
+interface ShapeOutline {
+    /** Line width in EMUs */
+    width?: number;
+    /** Line color */
+    color?: ColorValue;
+    /** Line style */
+    style?: 'solid' | 'dot' | 'dash' | 'lgDash' | 'dashDot' | 'lgDashDot' | 'lgDashDotDot' | 'sysDot' | 'sysDash' | 'sysDashDot' | 'sysDashDotDot';
+    /** Line cap */
+    cap?: 'flat' | 'round' | 'square';
+    /** Line join */
+    join?: 'bevel' | 'miter' | 'round';
+    /** Head arrow */
+    headEnd?: {
+        type: 'none' | 'triangle' | 'stealth' | 'diamond' | 'oval' | 'arrow';
+        width?: 'sm' | 'med' | 'lg';
+        length?: 'sm' | 'med' | 'lg';
+    };
+    /** Tail arrow */
+    tailEnd?: {
+        type: 'none' | 'triangle' | 'stealth' | 'diamond' | 'oval' | 'arrow';
+        width?: 'sm' | 'med' | 'lg';
+        length?: 'sm' | 'med' | 'lg';
+    };
 }
 /**
- * Header or footer content
+ * Text body inside a shape
  */
-interface HeaderFooter {
-    type: 'header' | 'footer';
-    /** Header/footer type */
-    hdrFtrType: HeaderFooterType;
-    /** Content (paragraphs, tables, etc.) */
-    content: (Paragraph | Table)[];
+interface ShapeTextBody {
+    /** Text direction */
+    vertical?: boolean;
+    /** Rotation */
+    rotation?: number;
+    /** Anchor/vertical alignment */
+    anchor?: 'top' | 'middle' | 'bottom' | 'distributed' | 'justified';
+    /** Anchor center */
+    anchorCenter?: boolean;
+    /** Auto fit */
+    autoFit?: 'none' | 'normal' | 'shape';
+    /** Text margins */
+    margins?: {
+        top?: number;
+        bottom?: number;
+        left?: number;
+        right?: number;
+    };
+    /** Paragraphs inside the shape */
+    content: Paragraph[];
 }
 /**
- * Footnote position
+ * Shape/drawing object (wps:wsp)
  */
-type FootnotePosition = 'pageBottom' | 'beneathText' | 'sectEnd' | 'docEnd';
+interface Shape {
+    type: 'shape';
+    /** Shape type preset */
+    shapeType: ShapeType;
+    /** Unique ID */
+    id?: string;
+    /** Name */
+    name?: string;
+    /** Size in EMUs */
+    size: ImageSize;
+    /** Position for floating shapes */
+    position?: ImagePosition;
+    /** Wrap settings */
+    wrap?: ImageWrap;
+    /** Fill */
+    fill?: ShapeFill;
+    /** Outline/stroke */
+    outline?: ShapeOutline;
+    /** Transform */
+    transform?: ImageTransform;
+    /** Text content inside the shape */
+    textBody?: ShapeTextBody;
+    /** Custom geometry points */
+    customGeometry?: string;
+}
+
 /**
- * Endnote position
+ * Embedded images (`w:drawing` → `pic:pic`): size, wrap, position,
+ * transform, padding, crop.
  */
-type EndnotePosition = 'sectEnd' | 'docEnd';
+
 /**
- * Number restart type
+ * Image size specification
  */
-type NoteNumberRestart = 'continuous' | 'eachSect' | 'eachPage';
+interface ImageSize {
+    /** Width in EMUs (English Metric Units) */
+    width: number;
+    /** Height in EMUs */
+    height: number;
+}
 /**
- * Footnote properties
+ * Image wrap type for floating images
  */
-interface FootnoteProperties {
-    position?: FootnotePosition;
-    numFmt?: NumberFormat;
-    numStart?: number;
-    numRestart?: NoteNumberRestart;
+interface ImageWrap {
+    type: WrapType;
+    /** Wrap text direction */
+    wrapText?: 'bothSides' | 'left' | 'right' | 'largest';
+    /** Distance from text */
+    distT?: number;
+    distB?: number;
+    distL?: number;
+    distR?: number;
 }
 /**
- * Endnote properties
+ * Position for floating images
  */
-interface EndnoteProperties {
-    position?: EndnotePosition;
-    numFmt?: NumberFormat;
-    numStart?: number;
-    numRestart?: NoteNumberRestart;
+interface ImagePosition {
+    /** Horizontal positioning */
+    horizontal: {
+        relativeTo: 'character' | 'column' | 'insideMargin' | 'leftMargin' | 'margin' | 'outsideMargin' | 'page' | 'rightMargin';
+        alignment?: 'left' | 'right' | 'center' | 'inside' | 'outside';
+        posOffset?: number;
+    };
+    /** Vertical positioning */
+    vertical: {
+        relativeTo: 'insideMargin' | 'line' | 'margin' | 'outsideMargin' | 'page' | 'paragraph' | 'topMargin' | 'bottomMargin';
+        alignment?: 'top' | 'bottom' | 'center' | 'inside' | 'outside';
+        posOffset?: number;
+    };
+}
+/**
+ * Image transformation
+ */
+interface ImageTransform {
+    /** Rotation in degrees */
+    rotation?: number;
+    /** Flip horizontal */
+    flipH?: boolean;
+    /** Flip vertical */
+    flipV?: boolean;
+}
+/**
+ * Image padding/margins
+ */
+interface ImagePadding {
+    top?: number;
+    bottom?: number;
+    left?: number;
+    right?: number;
+}
+/**
+ * Image crop, expressed as fractions of the source image to trim from each
+ * edge. OOXML's `<a:srcRect l="10000" t="0" r="5000" b="0"/>` uses units of
+ * 1/100000 (so 10000 → 0.1 → 10% trimmed from the left). We store the
+ * normalised fraction so both the renderer and the saver can read it
+ * directly without re-parsing units.
+ */
+interface ImageCrop {
+    left?: number;
+    top?: number;
+    right?: number;
+    bottom?: number;
+}
+/**
+ * Embedded image (`w:drawing` with an inline or anchored picture). Carries
+ * the relationship-id pointer to the binary in `word/media/`, its
+ * resolved data URL (`src`), display dimensions, optional crop /
+ * transform / wrap behaviors, and anchor positioning for floating
+ * images.
+ *
+ * See ECMA-376 §20.4 (DrawingML wordprocessingDrawing).
+ */
+interface Image {
+    type: 'image';
+    /** Unique ID */
+    id?: string;
+    /** Relationship ID for the image data */
+    rId: string;
+    /** Resolved image data (base64 or blob URL) */
+    src?: string;
+    /** Image MIME type */
+    mimeType?: string;
+    /** Original filename */
+    filename?: string;
+    /** Alt text for accessibility */
+    alt?: string;
+    /** Title/description */
+    title?: string;
+    /** Image size */
+    size: ImageSize;
+    /** Original size before any transforms */
+    originalSize?: ImageSize;
+    /** Wrap settings */
+    wrap: ImageWrap;
+    /** Position for floating images */
+    position?: ImagePosition;
+    /** Image transformations */
+    transform?: ImageTransform;
+    /** Padding around image */
+    padding?: ImagePadding;
+    /** Source-image crop (fractional, OOXML `a:srcRect`). */
+    crop?: ImageCrop;
+    /** Opacity in [0, 1] (OOXML `a:alphaModFix amt`). Undefined = fully opaque. */
+    opacity?: number;
+    /** Whether this is a decorative image */
+    decorative?: boolean;
+    /**
+     * `wp:anchor layoutInCell` — when true (default), an anchored image inside
+     * a table cell is constrained to the cell. When false, the image escapes
+     * the cell into the page area. Round-tripped on save.
+     */
+    layoutInCell?: boolean;
+    /**
+     * `wp:anchor allowOverlap` — when true (default), anchored objects may
+     * overlap; when false, Word repositions them to avoid collisions. We
+     * don't currently reposition; we round-trip the flag so saving preserves
+     * the author's intent.
+     */
+    allowOverlap?: boolean;
+    /** Hyperlink URL for clickable image */
+    hlinkHref?: string;
+    /** Image outline/border */
+    outline?: ShapeOutline;
+    /** Image effects */
+    effects?: {
+        brightness?: number;
+        contrast?: number;
+        saturation?: number;
+    };
+}
+
+/**
+ * Run content (`w:r`) and the inline pieces that live inside a run —
+ * text, tab, break, symbol, footnote/endnote references, field chars,
+ * instruction text, soft/no-break hyphens, drawings, shapes.
+ */
+
+/**
+ * Plain text run content (`w:t`). `preserveSpace` mirrors the
+ * `xml:space="preserve"` attribute and matters for runs that begin or end
+ * with whitespace — without it, Word collapses leading/trailing spaces.
+ */
+interface TextContent {
+    type: 'text';
+    /** The text string */
+    text: string;
+    /** Preserve whitespace (xml:space="preserve") */
+    preserveSpace?: boolean;
+}
+/**
+ * Tab character
+ */
+interface TabContent {
+    type: 'tab';
+}
+/**
+ * Line break
+ */
+interface BreakContent {
+    type: 'break';
+    /** Break type */
+    breakType?: 'page' | 'column' | 'textWrapping';
+    /** Clear type for text wrapping break */
+    clear?: 'none' | 'left' | 'right' | 'all';
 }
 /**
- * Footnote (w:footnote)
+ * Symbol character (special font character)
  */
-interface Footnote {
-    type: 'footnote';
-    /** Footnote ID */
-    id: number;
-    /** Special footnote type */
-    noteType?: 'normal' | 'separator' | 'continuationSeparator' | 'continuationNotice';
-    /**
-     * Content. Per ECMA-376 §17.11.10 footnotes can hold the same blocks as
-     * the body — paragraphs and tables. The parser previously only collected
-     * <w:p> children which silently dropped any <w:tbl> inside a footnote;
-     * widened to match HeaderFooter / TableCell shape so the body pipeline
-     * (toProseDoc → toFlowBlocks) can render them uniformly.
-     */
-    content: (Paragraph | Table)[];
+interface SymbolContent {
+    type: 'symbol';
+    /** Font name */
+    font: string;
+    /** Character code */
+    char: string;
 }
 /**
- * Endnote (w:endnote)
+ * Footnote or endnote reference
  */
-interface Endnote {
-    type: 'endnote';
-    /** Endnote ID */
+interface NoteReferenceContent {
+    type: 'footnoteRef' | 'endnoteRef';
+    /** Note ID */
     id: number;
-    /** Special endnote type */
-    noteType?: 'normal' | 'separator' | 'continuationSeparator' | 'continuationNotice';
-    /**
-     * Content. Per ECMA-376 §17.11.4 endnotes can hold the same blocks as
-     * the body — paragraphs and tables. See note on `Footnote.content`.
-     */
-    content: (Paragraph | Table)[];
 }
 /**
- * Page orientation
- */
-type PageOrientation = 'portrait' | 'landscape';
-/**
- * Section start type
+ * Field character (begin/separate/end)
  */
-type SectionStart = 'continuous' | 'nextPage' | 'oddPage' | 'evenPage' | 'nextColumn';
+interface FieldCharContent {
+    type: 'fieldChar';
+    /** Field character type */
+    charType: 'begin' | 'separate' | 'end';
+    /** Field is locked */
+    fldLock?: boolean;
+    /** Field is dirty (needs update) */
+    dirty?: boolean;
+}
 /**
- * Vertical alignment
+ * Field instruction text
  */
-type VerticalAlign = 'top' | 'center' | 'both' | 'bottom';
+interface InstrTextContent {
+    type: 'instrText';
+    /** Field instruction */
+    text: string;
+}
 /**
- * Line number restart type
+ * Soft hyphen
  */
-type LineNumberRestart = 'continuous' | 'newPage' | 'newSection';
+interface SoftHyphenContent {
+    type: 'softHyphen';
+}
 /**
- * Column definition
+ * Non-breaking hyphen
  */
-interface Column {
-    /** Column width in twips */
-    width?: number;
-    /** Space after column in twips */
-    space?: number;
+interface NoBreakHyphenContent {
+    type: 'noBreakHyphen';
 }
 /**
- * Section properties (w:sectPr)
+ * Drawing/image reference
  */
-interface SectionProperties {
-    /** Page width in twips */
-    pageWidth?: number;
-    /** Page height in twips */
-    pageHeight?: number;
-    /** Page orientation */
-    orientation?: PageOrientation;
-    /** Top margin in twips */
-    marginTop?: number;
-    /** Bottom margin in twips */
-    marginBottom?: number;
-    /** Left margin in twips */
-    marginLeft?: number;
-    /** Right margin in twips */
-    marginRight?: number;
-    /** Header distance from top in twips */
-    headerDistance?: number;
-    /** Footer distance from bottom in twips */
-    footerDistance?: number;
-    /** Gutter margin in twips */
-    gutter?: number;
-    /** Number of columns */
-    columnCount?: number;
-    /** Space between columns in twips */
-    columnSpace?: number;
-    /** Equal width columns */
-    equalWidth?: boolean;
-    /** Separator line between columns */
-    separator?: boolean;
-    /** Individual column definitions */
-    columns?: Column[];
-    /** Section start type */
-    sectionStart?: SectionStart;
-    /** Vertical alignment of text */
-    verticalAlign?: VerticalAlign;
-    /** Right-to-left section */
-    bidi?: boolean;
-    /** Header references */
-    headerReferences?: HeaderReference[];
-    /** Footer references */
-    footerReferences?: FooterReference[];
-    /** Different first page header/footer */
-    titlePg?: boolean;
-    /** Different odd/even page headers/footers */
-    evenAndOddHeaders?: boolean;
-    /** Line numbering settings */
-    lineNumbers?: {
-        start?: number;
-        countBy?: number;
-        distance?: number;
-        restart?: LineNumberRestart;
-    };
-    /** Page borders */
-    pageBorders?: {
-        top?: BorderSpec;
-        bottom?: BorderSpec;
-        left?: BorderSpec;
-        right?: BorderSpec;
-        /** Display setting */
-        display?: 'allPages' | 'firstPage' | 'notFirstPage';
-        /** Offset from */
-        offsetFrom?: 'page' | 'text';
-        /** Z-order */
-        zOrder?: 'front' | 'back';
-    };
-    /** Page background */
-    background?: {
-        color?: ColorValue;
-        themeColor?: ThemeColorSlot;
-        themeTint?: string;
-        themeShade?: string;
-    };
-    /** Footnote properties for this section */
-    footnotePr?: FootnoteProperties;
-    /** Endnote properties for this section */
-    endnotePr?: EndnoteProperties;
-    /** Document grid */
-    docGrid?: {
-        type?: 'default' | 'lines' | 'linesAndChars' | 'snapToChars';
-        linePitch?: number;
-        charSpace?: number;
-    };
-    /** First page paper source */
-    paperSrcFirst?: number;
-    /** Other pages paper source */
-    paperSrcOther?: number;
+interface DrawingContent {
+    type: 'drawing';
+    /** Image data */
+    image: Image;
 }
 /**
- * Block-level content types
+ * Shape reference
  */
-type BlockContent = Paragraph | Table | BlockSdt;
+interface ShapeContent {
+    type: 'shape';
+    /** Shape data */
+    shape: Shape;
+}
 /**
- * Section (implicit or explicit based on sectPr)
+ * All possible run content types
  */
-interface Section {
-    /** Section properties */
-    properties: SectionProperties;
-    /** Content in this section */
-    content: BlockContent[];
-    /** Headers for this section */
-    headers?: Map<HeaderFooterType, HeaderFooter>;
-    /** Footers for this section */
-    footers?: Map<HeaderFooterType, HeaderFooter>;
-}
+type RunContent = TextContent | TabContent | BreakContent | SymbolContent | NoteReferenceContent | FieldCharContent | InstrTextContent | SoftHyphenContent | NoBreakHyphenContent | DrawingContent | ShapeContent;
 /**
- * Document body (w:body)
+ * A run (`w:r`) — a contiguous span of inline content sharing one set of
+ * character properties (bold, italic, font, color, etc.). Runs are the
+ * atomic unit of character formatting; toggling bold on a selection that
+ * spans different formatting creates new runs.
+ *
+ * See ECMA-376 §17.3.2.
+ *
+ * @example
+ * ```ts
+ * const run: Run = {
+ *   type: 'run',
+ *   formatting: { bold: true },
+ *   content: [{ type: 'text', text: 'Hello' }],
+ * };
+ * ```
  */
-interface DocumentBody {
-    /** All content (paragraphs, tables) */
-    content: BlockContent[];
-    /** Sections (derived from sectPr in paragraphs and final sectPr) */
-    sections?: Section[];
-    /** Final section properties (from body's sectPr) */
-    finalSectionProperties?: SectionProperties;
-    /** Comments from comments.xml */
-    comments?: Comment[];
+interface Run {
+    type: 'run';
+    /** Text formatting properties */
+    formatting?: TextFormatting;
+    /** Run-level tracked property changes (w:rPrChange) */
+    propertyChanges?: RunPropertyChange[];
+    /** Run content (text, tabs, breaks, etc.) */
+    content: RunContent[];
 }
 
 /**
@@ -1573,7 +1765,13 @@ interface DocumentBody {
  */
 type StyleType = 'paragraph' | 'character' | 'numbering' | 'table';
 /**
- * Style definition
+ * Style definition from `styles.xml` — a named, reusable bundle of
+ * paragraph and/or character formatting. Word's "Heading 1", "Normal",
+ * "Title", and "List Bullet" are styles; user-defined styles look the
+ * same. `basedOn` chains styles for inheritance; `link` pairs a paragraph
+ * style with a matching character style.
+ *
+ * See ECMA-376 §17.7.4.
  */
 interface Style {
     /** Style ID */
@@ -1798,6 +1996,8 @@ interface MediaFile {
  * - lists.ts       — Numbering and list definitions
  * - content.ts     — Content model (runs, images, shapes, tables, paragraphs, sections)
  * - styles.ts      — Styles, theme, fonts, relationships, media
+ * @packageDocumentation
+ * @public
  */
 
 /**
@@ -1840,22 +2040,30 @@ interface DocxPackage {
     };
 }
 /**
- * Complete parsed DOCX document
+ * Top-level parsed DOCX document — the result of `parseDocx(buffer)`.
+ *
+ * Wraps the unzipped DOCX package (`document.xml`, `styles.xml`, etc.),
+ * the original buffer for round-trip saves, and any template variables /
+ * parse warnings detected during ingestion.
+ *
+ * @example
+ * ```ts
+ * import { parseDocx } from '@eigenpal/docx-editor-core/headless';
+ * const doc = await parseDocx(buffer);
+ * console.log(doc.package.document.content.length);
+ * ```
  */
 interface Document {
-    /** DOCX package with all parsed content */
+    /** Parsed DOCX package — body, styles, numbering, theme, media, headers/footers. */
     package: DocxPackage;
-    /** Original ArrayBuffer for round-trip */
+    /** Original DOCX buffer. Kept for round-trip saves that preserve untouched parts. */
     originalBuffer?: ArrayBuffer;
-    /** Detected template variables ({{...}}) */
+    /** Detected docxtemplater variables (e.g. `{name}`, `{address}`). Populated when the document is recognized as a template. */
     templateVariables?: string[];
-    /** Parsing warnings/errors */
+    /** Non-fatal parser diagnostics — malformed parts, unsupported features, fallbacks. */
     warnings?: string[];
 }
 
-/**
- * Types for @eigenpal/docx-editor-agents
- */
 interface HeadingBlock {
     type: 'heading';
     index: number;
@@ -1990,7 +2198,7 @@ interface FoundMatch {
     before: string;
     after: string;
 }
-/** Snapshot of the user's current selection / cursor. */
+/** @public */
 interface SelectionInfo {
     paraId: string | null;
     selectedText: string;
@@ -2063,6 +2271,8 @@ interface PageContent {
  * Snapshot of what the user is looking at — pass this to your agent's system
  * prompt so it knows the current selection / page without an extra
  * `read_selection` round-trip.
+ *
+ * @public
  */
 interface AgentContextSnapshot {
     /** User's current selection or cursor (null if editor isn't focused). */
@@ -2097,25 +2307,28 @@ interface BatchResult {
 }
 
 /**
- * DocxReviewer — Word-like API for AI document review.
+ * Headless DOCX reviewer — parse a file, read/comment/track changes
+ * against the document model, write the modified DOCX back out. No DOM,
+ * no editor instance. Pair with `createReviewerBridge()` to drive the
+ * built-in agent tools against a file on disk.
  *
  * @example
  * ```ts
  * const reviewer = await DocxReviewer.fromBuffer(buffer, 'AI Reviewer');
- * const text = reviewer.getContentAsText();
  * reviewer.addComment(5, 'Fix this paragraph.');
  * reviewer.replace(5, '$50k', '$500k');
  * const output = await reviewer.toBuffer();
  * ```
+ *
+ * @public
  */
-
 declare class DocxReviewer {
     private doc;
     /** Default author for comments and tracked changes. Set once, used everywhere. */
     readonly author: string;
     /**
      * Create a reviewer from a parsed Document.
-     * @param document - Parsed Document from @eigenpal/docx-core
+     * @param document - Parsed Document from the core package
      * @param author - Default author name for comments and changes. (default: 'AI')
      * @param originalBuffer - Original DOCX buffer, needed for toBuffer()
      */
@@ -2204,37 +2417,6 @@ declare class DocxReviewer {
     toBuffer(): Promise<ArrayBuffer>;
 }
 
-/**
- * useAgentChat — React hook that wires agent tools to a live DocxEditor.
- *
- * @example
- * ```tsx
- * import { useAgentChat } from '@eigenpal/docx-editor-agents/bridge';
- *
- * const { executeToolCall, toolSchemas } = useAgentChat({ editorRef, author: 'Assistant' });
- *
- * // Pass toolSchemas to your AI provider, execute tool calls on the client
- * const result = executeToolCall('add_comment', { paragraphIndex: 3, text: 'Fix this.' });
- * ```
- */
-
-interface UseAgentChatOptions {
-    /** Reference to the DocxEditor (must match EditorRefLike interface). */
-    editorRef: React.RefObject<EditorRefLike | null>;
-    /** Default author name for comments and changes. Default: 'AI' */
-    author?: string;
-}
-interface UseAgentChatReturn {
-    /** Execute a tool call through the bridge. */
-    executeToolCall: (toolName: string, input: Record<string, unknown>) => AgentToolResult;
-    /** Tool schemas in OpenAI function calling format. Pass to your AI provider. */
-    toolSchemas: ReturnType<typeof getToolSchemas>;
-}
-/**
- * Hook that creates an EditorBridge and provides tool execution.
- */
-declare function useAgentChat(options: UseAgentChatOptions): UseAgentChatReturn;
-
 /**
  * Reviewer bridge — wraps a `DocxReviewer` (static document) in the same
  * `EditorBridge` interface the live editor exposes. Lets the same MCP server
@@ -2262,12 +2444,16 @@ declare function useAgentChat(options: UseAgentChatOptions): UseAgentChatReturn;
  * disk. Call `reviewer.toBuffer()` afterwards to get the modified DOCX.
  *
  * @param reviewer - A DocxReviewer instance. The bridge mutates it in place.
+ *
+ * @public
  */
 declare function createReviewerBridge(reviewer: DocxReviewer): EditorBridge;
 
 /**
- * Minimal DocxEditorRef interface — only the methods the bridge needs.
- * This avoids importing the full React package at type level.
+ * Agent-bridge contract every editor adapter (React, Vue, future) MUST satisfy.
+ * Versioning: additions are coordinated minor bumps across the fixed group;
+ * signature changes / removals are major. See
+ * `openspec/changes/vue-editor-robust-implementation/design.md` Decision 18.
  */
 interface EditorRefLike {
     getDocument(): unknown | null;
@@ -2322,6 +2508,13 @@ interface EditorRefLike {
     onContentChange(listener: (doc: unknown) => void): () => void;
     onSelectionChange(listener: (selection: unknown) => void): () => void;
 }
+/**
+ * High-level agent surface over a live editor (or a headless reviewer).
+ * Every built-in tool calls into this contract — implement it once and
+ * the agent toolkit works against your editor.
+ *
+ * @public
+ */
 interface EditorBridge {
     /** Get document content as paraId-tagged text lines for LLM prompts. */
     getContentAsText(options?: GetContentOptions): string;
@@ -2400,6 +2593,12 @@ declare function createEditorBridge(editorRef: EditorRefLike, author?: string):
  * Agent tool type definitions.
  */
 
+/**
+ * Definition of an agent tool — name, JSON-schema input, handler.
+ * Use this to build custom tools alongside the built-in `agentTools`.
+ *
+ * @public
+ */
 interface AgentToolDefinition<TInput = Record<string, unknown>> {
     /** Tool name (used in tool_use blocks) */
     name: string;
@@ -2417,6 +2616,12 @@ interface AgentToolDefinition<TInput = Record<string, unknown>> {
     /** Handler — receives parsed input + bridge, returns result */
     handler: (input: TInput, bridge: EditorBridge) => AgentToolResult;
 }
+/**
+ * Result returned by a tool handler. `success: false` carries an `error`
+ * message; `success: true` may carry tool-specific `data`.
+ *
+ * @public
+ */
 interface AgentToolResult {
     success: boolean;
     data?: unknown;
@@ -2432,11 +2637,19 @@ interface AgentToolResult {
  * `resolve_comment` / `scroll`). paraId anchors are stable across edits.
  */
 
-/** All built-in agent tools. */
+/**
+ * All built-in agent tools — read/write document content, comments, and
+ * tracked changes. Use `getToolSchemas()` to feed them to an LLM and
+ * `executeToolCall()` to run the handlers against an `EditorBridge`.
+ *
+ * @public
+ */
 declare const agentTools: AgentToolDefinition<any>[];
 /**
  * Execute a tool call against an EditorBridge.
  * Returns the result (never throws).
+ *
+ * @public
  */
 declare function executeToolCall(toolName: string, input: Record<string, unknown>, bridge: EditorBridge): AgentToolResult;
 /**
@@ -2446,6 +2659,8 @@ declare function executeToolCall(toolName: string, input: Record<string, unknown
  *
  * @example getToolDisplayName('add_comment') // → 'Adding comment'
  * @example getToolDisplayName('fetch_clause_template') // → 'Fetch clause template'
+ *
+ * @public
  */
 declare function getToolDisplayName(name: string): string;
 /**
@@ -2454,6 +2669,8 @@ declare function getToolDisplayName(name: string): string;
  * LangChain, or other agent runtimes, transform this output to that
  * runtime's required shape — see `examples/agent-chat-demo/` for a
  * Vercel AI SDK example. The package stays runtime-agnostic.
+ *
+ * @public
  */
 declare function getToolSchemas(): {
     type: "function";
@@ -2464,4 +2681,4 @@ declare function getToolSchemas(): {
     };
 }[];
 
-export { type AgentToolDefinition as A, type BatchError as B, type ContentBlock as C, DocxReviewer as D, type EditorRefLike as E, type FoundMatch as F, type GetContentOptions as G, type ProposeChangeOptions as P, type ReviewComment as R, type SelectionInfo as S, type UseAgentChatOptions as U, type AgentToolResult as a, type AgentContextSnapshot as b, type UseAgentChatReturn as c, getToolDisplayName as d, type CommentFilter as e, type ChangeFilter as f, getToolSchemas as g, type ReviewChange as h, type AddCommentByParaIdOptions as i, type ReplyOptions as j, type ApplyFormattingOptions as k, type SetParagraphStyleOptions as l, type PageContent as m, type ContentChangeEvent as n, type SelectionChangeEvent as o, type BatchResult as p, type BatchReviewOptions as q, agentTools as r, createReviewerBridge as s, executeToolCall as t, useAgentChat as u, type EditorBridge as v, createEditorBridge as w };
+export { type AddCommentByParaIdOptions as A, type BatchError as B, type ContentBlock as C, DocxReviewer as D, type EditorBridge as E, type FoundMatch as F, type GetContentOptions as G, type ProposeChangeOptions as P, type ReviewComment as R, type SelectionInfo as S, type CommentFilter as a, type ChangeFilter as b, type ReviewChange as c, type ReplyOptions as d, type ApplyFormattingOptions as e, type SetParagraphStyleOptions as f, type PageContent as g, type ContentChangeEvent as h, type SelectionChangeEvent as i, type AgentToolDefinition as j, type AgentToolResult as k, type BatchResult as l, type BatchReviewOptions as m, agentTools as n, createReviewerBridge as o, executeToolCall as p, getToolSchemas as q, type EditorRefLike as r, type AgentContextSnapshot as s, getToolDisplayName as t, createEditorBridge as u };