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

Block-level SDT (content control wrapping paragraphs/tables)

interface BlockSdt

Bookmark end marker (w:bookmarkEnd)

interface BookmarkEnd

Bookmark start marker (w:bookmarkStart)

interface BookmarkStart

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

Line break

interface BreakContent

Cell margins

interface CellMargins

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

Column definition

interface Column

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 range end marker in paragraph content

interface CommentRangeEnd

Comment range start marker in paragraph content

interface CommentRangeStart

Complex field (w:fldChar begin/separate/end with w:instrText)

interface ComplexField

Conditional format style

interface ConditionalFormatStyle

Deletion wrapper (w:del) — runs deleted by tracked changes

interface Deletion

Document defaults (w:docDefaults)

interface DocDefaults

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.

interface Document

```ts
import { parseDocx } from '@eigenpal/docx-editor-core/headless';
const doc = await parseDocx(buffer);
console.log(doc.package.document.content.length);
```

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 DocumentBody

Complete DOCX package structure

interface DocxPackage

Drawing/image reference

interface DrawingContent

Endnote (w:endnote)

interface Endnote

Endnote properties

interface EndnoteProperties

Field character (begin/separate/end)

interface FieldCharContent

Floating table properties

interface FloatingTableProperties

Font info from fontTable.xml

interface FontInfo

Font table from fontTable.xml

interface FontTable

interface FooterReference

Footnote (w:footnote)

interface Footnote

Footnote properties

interface FootnoteProperties

Header or footer content

interface HeaderFooter

Header or footer reference

interface HeaderReference

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

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

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

Image padding/margins

interface ImagePadding

Position for floating images

interface ImagePosition

Image size specification

interface ImageSize

Image transformation

interface ImageTransform

Image wrap type for floating images

interface ImageWrap

Inline SDT (content control within a paragraph)

interface InlineSdt

Insertion wrapper (w:ins) — runs inserted by tracked changes

interface Insertion

Field instruction text

interface InstrTextContent

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

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

Math equation content (m:oMath or m:oMathPara)

interface MathEquation

Media file from word/media/

interface MediaFile

Move-from wrapper (w:moveFrom) — content moved away from this position

interface MoveFrom

Move-from range end marker (w:moveFromRangeEnd)

interface MoveFromRangeEnd

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.

interface MoveFromRangeStart

Move-to wrapper (w:moveTo) — content moved into this position

interface MoveTo

Move-to range end marker (w:moveToRangeEnd)

interface MoveToRangeEnd

Move-to range start marker (w:moveToRangeStart) — ECMA-376 §17.13.5.24 Pairs with moveToRangeEnd to delimit the destination of a move.

interface MoveToRangeStart

Non-breaking hyphen

interface NoBreakHyphenContent

Footnote or endnote reference

interface NoteReferenceContent

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

Numbering instance (w:num)

interface NumberingInstance

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

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 property change (w:pPrChange)

interface ParagraphPropertyChange

Generic tracked property-change wrapper metadata (w:*PrChange)

interface PropertyChangeInfo extends TrackedChangeInfo

Relationship entry

interface Relationship

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.

interface Run

```ts
const run: Run = {
  type: 'run',
  formatting: { bold: true },
  content: [{ type: 'text', text: 'Hello' }],
};
```

Run property change (w:rPrChange)

interface RunPropertyChange

SDT properties (w:sdtPr)

interface SdtProperties

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 (`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 SectionProperties

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

Shape/drawing object (wps:wsp)

interface Shape

Shape reference

interface ShapeContent

Shape fill type

interface ShapeFill

Shape outline/stroke

interface ShapeOutline

Text body inside a shape

interface ShapeTextBody

Simple field (w:fldSimple)

interface SimpleField

Soft hyphen

interface SoftHyphenContent

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 definitions from styles.xml

interface StyleDefinitions

Symbol character (special font character)

interface SymbolContent

Tab character

interface TabContent

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

Table borders

interface TableBorders

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

Table cell formatting properties (w:tcPr)

interface TableCellFormatting

Table cell property change (w:tcPrChange)

interface TableCellPropertyChange

Table formatting properties (w:tblPr)

interface TableFormatting

Table look flags (for table styles)

interface TableLook

Table measurement (width or height)

interface TableMeasurement

Table property change (w:tblPrChange)

interface TablePropertyChange

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

Table row formatting properties (w:trPr)

interface TableRowFormatting

Table row property change (w:trPrChange)

interface TableRowPropertyChange

Table structural tracked change metadata (row/cell insert/delete/merge)

interface TableStructuralChangeInfo

Tab stop definition

interface TabStop

Text box (floating text container)

interface TextBox

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

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

Theme (from theme1.xml)

interface Theme

Theme color scheme (a:clrScheme)

interface ThemeColorScheme

Theme font (with script variants)

interface ThemeFont

Theme font scheme (a:fontScheme)

interface ThemeFontScheme

Tracked change metadata (w:ins, w:del attributes)

interface TrackedChangeInfo

Block-level content types

type BlockContent = Paragraph | Table | BlockSdt;

Emphasis mark type

type EmphasisMark = 'none' | 'dot' | 'comma' | 'circle' | 'underDot';

Endnote position

type EndnotePosition = 'sectEnd' | 'docEnd';

type Field = SimpleField | ComplexField;

Known field types

type FieldType = 'PAGE' | 'NUMPAGES' | 'NUMWORDS' | 'NUMCHARS' | 'DATE' | 'TIME' | 'CREATEDATE' | 'SAVEDATE' | 'PRINTDATE' | 'AUTHOR' | 'TITLE' | 'SUBJECT' | 'KEYWORDS' | 'COMMENTS' | 'FILENAME' | 'FILESIZE' | 'TEMPLATE' | 'DOCPROPERTY' | 'DOCVARIABLE' | 'REF' | 'PAGEREF' | 'NOTEREF' | 'HYPERLINK' | 'TOC' | 'TOA' | 'INDEX' | 'SEQ' | 'STYLEREF' | 'AUTONUM' | 'AUTONUMLGL' | 'AUTONUMOUT' | 'IF' | 'MERGEFIELD' | 'NEXT' | 'NEXTIF' | 'ASK' | 'SET' | 'QUOTE' | 'INCLUDETEXT' | 'INCLUDEPICTURE' | 'SYMBOL' | 'ADVANCE' | 'EDITTIME' | 'REVNUM' | 'SECTION' | 'SECTIONPAGES' | 'USERADDRESS' | 'USERNAME' | 'USERINITIALS' | 'UNKNOWN';

Footnote position

type FootnotePosition = 'pageBottom' | 'beneathText' | 'sectEnd' | 'docEnd';

Header/footer type

type HeaderFooterType = 'default' | 'first' | 'even';

Multi-level suffix (what follows the number)

type LevelSuffix = 'tab' | 'space' | 'nothing';

Line number restart type

type LineNumberRestart = 'continuous' | 'newPage' | 'newSection';

Line spacing rule

type LineSpacingRule = 'auto' | 'exact' | 'atLeast';

Number restart type

type NoteNumberRestart = 'continuous' | 'eachSect' | 'eachPage';

Number format type

type NumberFormat = 'decimal' | 'upperRoman' | 'lowerRoman' | 'upperLetter' | 'lowerLetter' | 'ordinal' | 'cardinalText' | 'ordinalText' | 'hex' | 'chicago' | 'ideographDigital' | 'japaneseCounting' | 'aiueo' | 'iroha' | 'decimalFullWidth' | 'decimalHalfWidth' | 'japaneseLegal' | 'japaneseDigitalTenThousand' | 'decimalEnclosedCircle' | 'decimalFullWidth2' | 'aiueoFullWidth' | 'irohaFullWidth' | 'decimalZero' | 'bullet' | 'ganada' | 'chosung' | 'decimalEnclosedFullstop' | 'decimalEnclosedParen' | 'decimalEnclosedCircleChinese' | 'ideographEnclosedCircle' | 'ideographTraditional' | 'ideographZodiac' | 'ideographZodiacTraditional' | 'taiwaneseCounting' | 'ideographLegalTraditional' | 'taiwaneseCountingThousand' | 'taiwaneseDigital' | 'chineseCounting' | 'chineseLegalSimplified' | 'chineseCountingThousand' | 'koreanDigital' | 'koreanCounting' | 'koreanLegal' | 'koreanDigital2' | 'vietnameseCounting' | 'russianLower' | 'russianUpper' | 'none' | 'numberInDash' | 'hebrew1' | 'hebrew2' | 'arabicAlpha' | 'arabicAbjad' | 'hindiVowels' | 'hindiConsonants' | 'hindiNumbers' | 'hindiCounting' | 'thaiLetters' | 'thaiNumbers' | 'thaiCounting';

Page orientation

type PageOrientation = 'portrait' | 'landscape';

Paragraph alignment/justification

type ParagraphAlignment = 'left' | 'center' | 'right' | 'both' | 'distribute' | 'mediumKashida' | 'highKashida' | 'lowKashida' | 'thaiDistribute';

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;

Relationship map (keyed by rId)

type RelationshipMap = Map<string, Relationship>;

Relationship type

type RelationshipType = 'http://schemas.openxmlformats.org/officeDocument/2006/relationships/image' | 'http://schemas.openxmlformats.org/officeDocument/2006/relationships/hyperlink' | 'http://schemas.openxmlformats.org/officeDocument/2006/relationships/header' | 'http://schemas.openxmlformats.org/officeDocument/2006/relationships/footer' | 'http://schemas.openxmlformats.org/officeDocument/2006/relationships/footnotes' | 'http://schemas.openxmlformats.org/officeDocument/2006/relationships/endnotes' | 'http://schemas.openxmlformats.org/officeDocument/2006/relationships/styles' | 'http://schemas.openxmlformats.org/officeDocument/2006/relationships/numbering' | 'http://schemas.openxmlformats.org/officeDocument/2006/relationships/fontTable' | 'http://schemas.openxmlformats.org/officeDocument/2006/relationships/theme' | 'http://schemas.openxmlformats.org/officeDocument/2006/relationships/settings' | 'http://schemas.openxmlformats.org/officeDocument/2006/relationships/webSettings' | 'http://schemas.openxmlformats.org/officeDocument/2006/relationships/oleObject' | 'http://schemas.openxmlformats.org/officeDocument/2006/relationships/chart' | 'http://schemas.openxmlformats.org/officeDocument/2006/relationships/diagramData' | string;

All possible run content types

type RunContent = TextContent | TabContent | BreakContent | SymbolContent | NoteReferenceContent | FieldCharContent | InstrTextContent | SoftHyphenContent | NoBreakHyphenContent | DrawingContent | ShapeContent;

SDT type (content control type)

type SdtType = 'richText' | 'plainText' | 'date' | 'dropdown' | 'comboBox' | 'checkbox' | 'picture' | 'buildingBlockGallery' | 'group' | 'unknown';

Section start type

type SectionStart = 'continuous' | 'nextPage' | 'oddPage' | 'evenPage' | 'nextColumn';

Shape types

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';

Style type

type StyleType = 'paragraph' | 'character' | 'numbering' | 'table';

Tab leader character

type TabLeader = 'none' | 'dot' | 'hyphen' | 'underscore' | 'heavy' | 'middleDot';

Table width type

type TableWidthType = 'auto' | 'dxa' | 'nil' | 'pct';

Tab stop alignment

type TabStopAlignment = 'left' | 'center' | 'right' | 'decimal' | 'bar' | 'clear' | 'num';

Text effect animations

type TextEffect = 'none' | 'blinkBackground' | 'lights' | 'antsBlack' | 'antsRed' | 'shimmer' | 'sparkle';

Theme color slots from theme1.xml

type ThemeColorSlot = 'dk1' | 'lt1' | 'dk2' | 'lt2' | 'accent1' | 'accent2' | 'accent3' | 'accent4' | 'accent5' | 'accent6' | 'hlink' | 'folHlink' | 'background1' | 'text1' | 'background2' | 'text2';

Run-level tracked wrappers represented in WordprocessingML.

type TrackedRunChange = Insertion | Deletion | MoveFrom | MoveTo;

Underline style options

type UnderlineStyle = 'none' | 'single' | 'words' | 'double' | 'thick' | 'dotted' | 'dottedHeavy' | 'dash' | 'dashedHeavy' | 'dashLong' | 'dashLongHeavy' | 'dotDash' | 'dashDotHeavy' | 'dotDotDash' | 'dashDotDotHeavy' | 'wave' | 'wavyHeavy' | 'wavyDouble';

Vertical alignment

type VerticalAlign = 'top' | 'center' | 'both' | 'bottom';