Attempt a selective save — patch only changed paragraphs in document.xml. Also updates comments, headers/footers, and core properties so that all document parts stay in sync even when only paragraphs are patched.

Returns the saved ArrayBuffer, or null if selective save is not possible (caller should fall back to full repack).

declare function attemptSelectiveSave(doc: Document, originalBuffer: ArrayBuffer, options: SelectiveSaveOptions): Promise<ArrayBuffer | null>;

Blend two colors together

declare function blendColors(color1: ColorValue | undefined | null, color2: ColorValue | undefined | null, ratio: number, theme: Theme | null | undefined): string;

Build extended selection context with additional details

declare function buildExtendedSelectionContext(doc: Document, range: Range, options?: SelectionContextOptions): ExtendedSelectionContext;

Build footnote content for all footnotes referenced in the document. Display numbers are assigned by first-appearance order (the same way Word renders them).

declare function buildFootnoteContentMap(footnotes: Footnote[], footnoteRefs: Array<{
    footnoteId: number;
}>, contentWidth: number, options: ConvertFootnoteOptions): Map<number, FootnoteContent>;

Turn the page→footnote-id map into the per-page render payload that `renderPages` consumes via `footnotesByPage`. Skips non-`normal` notes (separators, continuation notices), reads the display number out of the content map, and pulls plain text via `getFootnoteText`.

Lives in core (not in either adapter) so React + Vue both call the same helper — same rule as the rest of this module.

declare function buildFootnoteRenderItems(pageFootnoteMap: Map<number, number[]>, footnoteContentMap: Map<number, FootnoteContent>, doc: Document | null): Map<number, FootnoteRenderItem[]>;

Build a patched document.xml by splicing new paragraph XML into the original at the correct offsets. Only changed paragraphs are replaced; everything else is preserved byte-for-byte.

Returns null if any step fails.

declare function buildPatchedDocumentXml(originalXml: string, serializedXml: string, changedIds: Set<string>): string | null;

Build selection context for AI operations

declare function buildSelectionContext(doc: Document, range: Range, options?: SelectionContextOptions): SelectionContext;

Calculate per-page footnote reserved heights. Returns MappageNumber, reservedHeight.

declare function calculateFootnoteReservedHeights(pageFootnoteMap: Map<number, number[]>, footnoteContentMap: Map<number, {
    height: number;
}>): Map<number, number>;

Check if a font is available on the system using canvas measurement

This uses the technique of comparing text width with the target font vs a known fallback font. If they differ, the font is available.

declare function canRenderFont(fontFamily: string, fallbackFont?: string): boolean;

Scan FlowBlocks for runs with footnoteRefId set. Returns a list of footnoteId, pmPos in document order.

declare function collectFootnoteRefs(blocks: FlowBlock[]): Array<{
    footnoteId: number;
    pmPos: number;
}>;

Check if two colors are equal

declare function colorsEqual(color1: ColorValue | undefined | null, color2: ColorValue | undefined | null, theme: Theme | null | undefined): boolean;

Convert HeaderFooter (document type) to HeaderFooterContent (render type).

Routes through the same pipeline as the body: HF.content → headerFooterToProseDoc → toFlowBlocks → measureBlocks. The inline editor uses the same conversion chain, so block support (paragraph, table, image, textBox, fields) and the inline editor's content stay in lockstep.

declare function convertHeaderFooterToContent(headerFooter: HeaderFooter | null | undefined, contentWidth: number, metrics: HeaderFooterMetrics, options: ConvertHeaderFooterOptions): HeaderFooterContent | undefined;

Count page breaks in a document

declare function countPageBreaks(doc: Document): number;

Create a column break content element

declare function createColumnBreak(): BreakContent;

Create a document with a single paragraph containing the given text

declare function createDocumentWithText(text: string, options?: Omit<CreateEmptyDocumentOptions, 'initialText'>): Document;

Create a new DOCX from a Document (without requiring original buffer)

declare function createDocx(doc: Document): Promise<ArrayBuffer>;

Create an empty document with a single paragraph

declare function createEmptyDocument(options?: CreateEmptyDocumentOptions): Document;

```ts
// Create a blank document
const doc = createEmptyDocument();

// Create with custom margins
const doc = createEmptyDocument({
  marginTop: 720,  // 0.5 inch
  marginBottom: 720,
});

// Create with initial text
const doc = createEmptyDocument({
  initialText: 'Hello, World!'
});
```

Create a horizontal rule paragraph Uses a paragraph with bottom border to simulate horizontal rule

declare function createHorizontalRule(): Paragraph;

Create a text wrapping break (line break)

declare function createLineBreak(clear?: 'none' | 'left' | 'right' | 'all'): BreakContent;

Create a page break content element

declare function createPageBreak(): BreakContent;

Create an empty paragraph with a page break before it

declare function createPageBreakParagraph(): Paragraph;

Create a run containing a page break

declare function createPageBreakRun(): Run;

Create a ColorValue from RGB hex

declare function createRgbColor(hex: string): ColorValue;

Create a ClipboardSelection from the current DOM selection.

declare function createSelectionFromDOM(): ClipboardSelection | null;

Create a ColorValue from theme color reference

declare function createThemeColor(themeColor: ThemeColorSlot, tint?: number, shade?: number): ColorValue;

Darken a color by a percentage

declare function darkenColor(color: ColorValue | undefined | null, theme: Theme | null | undefined, percent: number): string;

Detect all template variables in a document

declare function detectVariables(doc: Document): string[];

Detect variables with detailed information

declare function detectVariablesDetailed(doc: Document): VariableDetectionResult;

Detect variables in document body

declare function detectVariablesInBody(body: DocumentBody): string[];

Detect variables in a paragraph

declare function detectVariablesInParagraph(paragraph: Paragraph): string[];

Check if document has any template variables

declare function documentHasVariables(doc: Document): boolean;

Convert EMUs to pixels (at 96 DPI)

1 inch = 914400 EMUs = 96 pixels Returns 0 for null/undefined/NaN inputs.

declare function emuToPixels(emu: number | undefined | null): number;

Convert EMUs to twips

declare function emuToTwips(emu: number): number;

Ensure a hex color string has a '#' prefix.

declare function ensureHexPrefix(hex: string): string;

Execute an agent command on a document Returns a new document with the command applied (immutable)

Dispatch order: 1. Try plugin handlers first (allows plugins to override built-in commands) 2. Fall back to built-in handlers

declare function executeCommand(doc: Document, command: AgentCommand): Document;

Execute multiple commands in sequence

declare function executeCommands(doc: Document, commands: AgentCommand[]): Document;

Extract formatting from an HTML element's computed styles.

declare function extractFormattingFromElement(element: HTMLElement): Run['formatting'];

Extract variable names from text

declare function extractVariablesFromText(text: string): string[];

Find all page break positions in a document

declare function findPageBreaks(doc: Document): InsertPosition[];

ProseMirror position range for the paragraph (or any textblock) whose `paraId` attribute equals `paraId`. Returns the inclusive `from` and exclusive `to` positions, plus the node, so callers can both target the paragraph (e.g. addMark over its text range) and inspect it.

`from` is the position immediately before the textblock; `to` is `from + node.nodeSize`. The text content lives at `[from + 1, to - 1]`.

Returns null if no textblock with that paraId exists.

declare function findParagraphByParaId(doc: Node, paraId: string): {
    node: Node;
    from: number;
    to: number;
} | null;

ProseMirror position immediately before the first textblock whose `paraId` attribute equals `paraId` (Word `w14:paraId` / OOXML paragraph id).

Match is strict string equality on `node.attrs.paraId`.

declare function findStartPosForParaId(doc: Node, paraId: string): number | null;

Compare two per-page footnote reservation maps. Used by the React + Vue adapters to detect when the multi-pass loop has converged.

declare function footnoteReservedHeightsEqual(a: Map<number, number>, b: Map<number, number>): boolean;

Format last save time for display

declare function formatLastSaveTime(date: Date | null): string;

Format a pixel value as CSS string

declare function formatPx(px: number): string;

Format storage size for display

declare function formatStorageSize(bytes: number): string;

Format a variable name with braces (standard docxtemplater syntax)

declare function formatVariable(name: string): string;

Generate the 10×6 theme color matrix for an advanced color picker.

Columns: lt1, dk1, lt2, dk2, accent1-6 (matches Word's order) Rows: base, 80% tint, 60% tint, 40% tint, 25% shade, 50% shade

declare function generateThemeTintShadeMatrix(colorScheme?: ThemeColorScheme | null): ThemeMatrixCell[][];

Build agent context from a document

declare function getAgentContext(doc: Document, options?: AgentContextOptions): AgentContext;

Get auto-save status label

declare function getAutoSaveStatusLabel(status: AutoSaveStatus): string;

Get storage size used by auto-save

declare function getAutoSaveStorageSize(storageKey?: string): number;

Get contrasting text color for a background

declare function getContrastingColor(backgroundColor: ColorValue | undefined | null, theme: Theme | null | undefined): string;

Get a simple document summary for quick context

declare function getDocumentSummary(doc: Document): string;

Get list of all loaded fonts

declare function getLoadedFonts(): string[];

Get selected runs from the current DOM selection.

declare function getSelectionRuns(): Run[];

Get all template tags in a document without processing

declare function getTemplateTags(buffer: ArrayBuffer): string[];

Compute a single tinted or shaded hex color from a base color.

declare function getThemeTintShadeHex(baseHex: string, type: 'tint' | 'shade', fraction: number): string;

Convert half-points to pixels (at 96 DPI)

Half-points are commonly used for font sizes in OOXML (w:sz).

declare function halfPointsToPixels(halfPoints: number): number;

Check if a paragraph has pageBreakBefore

declare function hasPageBreakBefore(paragraph: Paragraph): boolean;

Check if text contains template variables

declare function hasTemplateVariables(text: string): boolean;

Inject CSS styles into the document head. Returns a cleanup function.

declare function injectStyles(pluginId: string, css: string): () => void;

Insert a horizontal rule at a position in the document

declare function insertHorizontalRule(doc: Document, position: InsertPosition): Document;

Insert a page break at a position in the document This inserts a new paragraph with pageBreakBefore: true

declare function insertPageBreak(doc: Document, position: InsertPosition): Document;

Check if auto-save is supported

declare function isAutoSaveSupported(): boolean;

Check if a color is effectively black

declare function isBlack(color: ColorValue | undefined | null, theme: Theme | null | undefined): boolean;

Check if content is any type of break

declare function isBreakContent(content: RunContent): content is BreakContent;

Check if content is a column break

declare function isColumnBreak(content: RunContent): boolean;

Check if a font is loaded

declare function isFontLoaded(fontFamily: string): boolean;

Check if any fonts are currently loading

declare function isLoading(): boolean;

Check if content is a line break

declare function isLineBreak(content: RunContent): boolean;

Check if content is a page break

declare function isPageBreak(content: RunContent): boolean;

Check if a variable name is valid

declare function isValidVariableName(name: string): boolean;

Check if a color is effectively white

declare function isWhite(color: ColorValue | undefined | null, theme: Theme | null | undefined): boolean;

Lighten a color by a percentage

declare function lightenColor(color: ColorValue | undefined | null, theme: Theme | null | undefined, percent: number): string;

Load a font from Google Fonts

declare function loadFont(fontFamily: string, options?: {
    weights?: number[];
    styles?: ('normal' | 'italic')[];
}): Promise<boolean>;

Load a font from a raw buffer (e.g., embedded in DOCX)

declare function loadFontFromBuffer(fontFamily: string, buffer: ArrayBuffer, options?: {
    weight?: number | string;
    style?: 'normal' | 'italic';
}): Promise<boolean>;

Load multiple fonts from Google Fonts

declare function loadFonts(families: string[], options?: {
    weights?: number[];
    styles?: ('normal' | 'italic')[];
}): Promise<void>;

After layout, determine which footnotes appear on which pages. Checks each page's fragments to see if any footnoteRef PM positions fall within.

Returns MappageNumber, footnoteId[] in document order.

declare function mapFootnotesToPages(pages: Page[], footnoteRefs: Array<{
    footnoteId: number;
    pmPos: number;
}>): Map<number, number[]>;

Register a callback to be notified when fonts are loaded

declare function onFontsLoaded(callback: (fonts: string[]) => void): () => void;

Parse a color string (various formats) to ColorValue

declare function parseColorString(colorString: string | undefined): ColorValue | undefined;

Parse a DOCX file into a complete Document model

declare function parseDocx(input: DocxInput, options?: ParseOptions): Promise<Document>;

Parse a variable string to get the name

declare function parseVariable(variable: string): string | null;

Convert pixels to EMUs. EMU coordinates in OOXML are integer-typed (xs:long); rounding here keeps floating-point drift (e.g. 52 px → 495299.99999999994) out of the document.

declare function pixelsToEmu(px: number): number;

Convert pixels to twips

declare function pixelsToTwips(px: number): number;

Convert points to pixels (at 96 DPI)

1 inch = 72 points = 96 pixels → 1 point = 96/72 pixels = 4/3 pixels

declare function pointsToPixels(points: number): number;

Preload a list of common document fonts

This preloads fonts commonly used in DOCX documents that have Google Fonts equivalents.

declare function preloadCommonFonts(): Promise<void>;

Process a DOCX template with variable substitution

declare function processTemplate(buffer: ArrayBuffer, variables: Record<string, string>, options?: ProcessTemplateOptions): ArrayBuffer;

Process template and return as Blob

declare function processTemplateAsBlob(buffer: ArrayBuffer, variables: Record<string, string>, options?: ProcessTemplateOptions): Blob;

Process template with detailed result

declare function processTemplateDetailed(buffer: ArrayBuffer, variables: Record<string, string>, options?: ProcessTemplateOptions): ProcessTemplateResult;

Register multiple plugins at once

declare function registerPlugins(plugins: CorePlugin[], options?: PluginOptions): PluginRegistrationResult[];

Remove a page break at a specific position

declare function removePageBreak(doc: Document, position: InsertPosition): Document;

Replace all variables in text with a placeholder

declare function removeVariables(text: string, placeholder?: string): string;

Repack a Document into a valid DOCX file

declare function repackDocx(doc: Document, options?: RepackOptions): Promise<ArrayBuffer>;

Replace variables in text with values

declare function replaceVariables(text: string, values: Record<string, string>): string;

Resolve a ColorValue to a CSS color string

declare function resolveColor(color: ColorValue | undefined | null, theme: Theme | null | undefined, defaultColor?: string): string;

Resolve a highlight color name to CSS

declare function resolveHighlightColor(highlight: string | undefined): string;

Resolve a highlight color value to a CSS-ready string. Tries OOXML named highlight first, then ensures hex prefix.

declare function resolveHighlightToCss(value: string): string;

Resolve a shading fill or pattern color to CSS

declare function resolveShadingColor(color: ColorValue | undefined | null, theme: Theme | null | undefined): string;

Sanitize a variable name

declare function sanitizeVariableName(name: string): string;

Serialize a DocumentBody to document.xml body content

declare function serializeDocumentBody(body: DocumentBody): string;

Serialize a complete Document to valid document.xml

declare function serializeDocument(doc: Document): string;

Serialize section properties (w:sectPr)

declare function serializeSectionProperties(props: SectionProperties | undefined): string;

Run the multi-pass footnote layout loop. Reserving footnote space on a page can move a reference to another page, which changes the reservation, which can move references again. Iterate until the page→height contract is the same one used by the latest layout, or `MAX_FOOTNOTE_LAYOUT_PASSES` passes have run.

Lives in core so the React + Vue adapters call the same loop and stay in lockstep on convergence behaviour. Writes `page.footnoteIds` onto each page in the returned layout so renderers can paint footnote areas.

declare function stabilizeFootnoteLayout(args: StabilizeFootnoteLayoutArgs): StabilizeFootnoteLayoutResult;

Normalize any [DocxInput](DocxInput) into an `ArrayBuffer` for internal use.

declare function toArrayBuffer(input: DocxInput): Promise<ArrayBuffer>;

Convert twips to EMUs

declare function twipsToEmu(twips: number): number;

Convert twips to pixels (at 96 DPI)

1 inch = 1440 twips = 96 pixels → 1 twip = 96/1440 pixels = 1/15 pixels

declare function twipsToPixels(twips: number): number;

Update multiple files in a DOCX buffer

declare function updateMultipleFiles(originalBuffer: ArrayBuffer, updates: Map<string, string | ArrayBuffer>, options?: RepackOptions): Promise<ArrayBuffer>;

Validate that a selective patch can be safely applied.

Checks: - All changed paraIds exist in original XML (exactly once) - All changed paraIds exist in serialized XML (exactly once) - Paragraph count matches between original and serialized

declare function validatePatchSafety(originalXml: string, serializedXml: string, changedIds: Set<string>): PatchValidationResult;

Validate that a document is a valid docxtemplater template

declare function validateTemplate(buffer: ArrayBuffer): {
    valid: boolean;
    errors: TemplateError[];
    tags: string[];
};

AutoSaveManager

Framework-agnostic class for auto-saving documents to localStorage. Extracted from the React `useAutoSave` hook.

Usage with React:

```ts const snapshot = useSyncExternalStore(manager.subscribe, manager.getSnapshot); ```

declare class AutoSaveManager extends Subscribable<AutoSaveSnapshot>

DocumentAgent provides a fluent API for document manipulation

declare class DocumentAgent

```ts
const agent = new DocumentAgent(buffer);

// Read operations
const text = agent.getText();
const wordCount = agent.getWordCount();
const variables = agent.getVariables();

// Write operations (returns new agent)
const newAgent = agent
  .insertText({ paragraphIndex: 0, offset: 0 }, 'Hello ', { formatting: { bold: true } })
  .applyStyle({ paragraphIndex: 0, offset: 0 }, { paragraphIndex: 0, offset: 5 }, 'Heading1');

// Export
const newBuffer = await newAgent.toBuffer();
```

declare class EditorCoordinator extends Subscribable<EditorCoordinatorSnapshot>

ErrorManager

Framework-agnostic pub/sub error notification system. Replaces React's `componentDidCatch` + context pattern for error notifications.

Usage with React:

```ts const { notifications } = useSyncExternalStore(manager.subscribe, manager.getSnapshot); ```

declare class ErrorManager extends Subscribable<ErrorManagerSnapshot>

declare class LayoutCoordinator extends Subscribable<LayoutCoordinatorSnapshot>

declare class PluginLifecycleManager extends Subscribable<PluginLifecycleSnapshot>

Plugin Registry - manages core plugins

declare class PluginRegistry

```ts
import { pluginRegistry, docxtemplaterPlugin } from '@eigenpal/docx-editor/core-plugins';

// Register plugins
pluginRegistry.register(docxtemplaterPlugin);

// Get all MCP tools for MCP server
const tools = pluginRegistry.getMcpTools();

// Get command handler for executor
const handler = pluginRegistry.getCommandHandler('insertTemplateVariable');
```

Subscribable Base Class

Framework-agnostic base for manager classes that need to notify UI frameworks of state changes.

Compatible with: - React: useSyncExternalStore(manager.subscribe, manager.getSnapshot) - Vue: watchEffect(() = manager.subscribe(triggerRef) )

declare abstract class Subscribable<TSnapshot>

Document context for AI agents

interface AgentContext

Options for building agent context

interface AgentContextOptions

Response from an agent action

interface AgentResponse

AI action request

interface AIActionRequest

Apply a named style to a paragraph

interface ApplyStyleCommand extends BaseCommand

Configuration for AutoSaveManager

interface AutoSaveManagerOptions

AutoSaveManager snapshot for UI consumption

interface AutoSaveSnapshot

Bookmark end marker (w:bookmarkEnd)

interface BookmarkEnd

Bookmark start marker (w:bookmarkStart)

interface BookmarkStart

Caret position for rendering the blinking cursor

interface CaretPosition

Cell coordinates in a table

interface CellCoordinates

Selection data for clipboard operations

interface ClipboardSelection

Column resize tracking state

interface ColumnResizeState

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

Core plugin interface - headless, works in Node.js

Plugins can: - Register command handlers that DocumentAgent dispatches to - Declare MCP tools that the MCP server exposes to AI clients - Have optional initialization logic - Declare dependencies on other plugins

interface CorePlugin

Options for creating an empty document

interface CreateEmptyDocumentOptions

Delete text in a range

interface DeleteTextCommand extends BaseCommand

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

interface Deletion

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

Configuration for EditorCoordinator

interface EditorCoordinatorOptions

The full snapshot exposed to UI frameworks

interface EditorCoordinatorSnapshot

Framework-agnostic interface for an imperatively mounted editor instance.

Returned by `renderAsync()` implementations (React, Vue, etc.). Consumers use this to interact with the editor programmatically.

interface EditorHandle

Framework-agnostic core plugin interface.

Contains all non-UI plugin capabilities: - ProseMirror plugins (decorations, keymaps, etc.) - State management (initialize, onStateChange, destroy) - CSS injection - Panel configuration

Framework adapters (ReactEditorPlugin, VueEditorPlugin) extend this with their own Panel component type and renderOverlay function.

interface EditorPluginCore<TState = any>

Endnote (w:endnote)

interface Endnote

ErrorManager snapshot

interface ErrorManagerSnapshot

Error notification

interface ErrorNotification

Extended selection context with additional details

interface ExtendedSelectionContext extends SelectionContext

interface FooterReference

Footnote (w:footnote)

interface Footnote

Apply formatting to a range

interface FormatTextCommand extends BaseCommand

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

Info about the currently selected/hovered image

interface ImageSelectionInfo

Insert a hyperlink at a range

interface InsertHyperlinkCommand extends BaseCommand

Insert an image at a position

interface InsertImageCommand extends BaseCommand

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

interface Insertion

Insert position in the document

interface InsertPosition

Insert a table at a position

interface InsertTableCommand extends BaseCommand

Insert text at a position

interface InsertTextCommand extends BaseCommand

The full snapshot exposed to UI frameworks

interface LayoutCoordinatorSnapshot

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

MCP session state

Maintains state across tool calls within a session.

interface McpSession

MCP tool definition

Describes a tool that can be called by AI clients through the MCP server.

interface McpToolDefinition

MCP tool result

interface McpToolResult

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

interface MoveFrom

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

interface MoveTo

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

Configuration for plugin panel rendering.

interface PanelConfig

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 context for selection

interface ParagraphContext

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

Plugin lifecycle configuration

interface PluginLifecycleConfig

PluginLifecycleManager snapshot

interface PluginLifecycleSnapshot

Props passed to plugin panel components (framework-agnostic base).

interface PluginPanelProps<TState = unknown>

Position within a document

interface Position

Coordinates returned by position lookup in the rendered DOM.

interface PositionCoordinates

Options for template processing

interface ProcessTemplateOptions

Result of template processing

interface ProcessTemplateResult

Range within a document

interface Range

Relationship entry

interface Relationship

Context for accessing the rendered DOM in the paged editor.

Provides DOM-based position mapping that works with the LayoutPainter output (visible pages). Use this for rendering overlays, annotations, and other visual elements positioned relative to rendered content.

The rendered DOM uses data-pm-start/data-pm-end attributes on spans to map between ProseMirror positions and DOM elements.

interface RenderedDomContext

Replace text in a range

interface ReplaceTextCommand extends BaseCommand

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' }],
};
```

Saved document data structure

interface SavedDocumentData

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

Context about the current selection

interface SelectionContext

Options for building selection context

interface SelectionContextOptions

Selection rectangle for rendering selection overlays

interface SelectionRect

Set template variable value

interface SetVariableCommand extends BaseCommand

Shape/drawing object (wps:wsp)

interface Shape

interface StabilizeFootnoteLayoutArgs

interface StabilizeFootnoteLayoutResult

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

Suggested action for context menu

interface SuggestedAction

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 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 row (`w:tr`) — an ordered list of `TableCell` plus row-level formatting (height, repeated header, cantSplit) and tracked changes for inserts/deletes.

interface TableRow

TableSelectionManager snapshot

interface TableSelectionSnapshot

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

Theme color matrix cell

interface ThemeMatrixCell

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

interface TrackedChangeInfo

Result of variable detection

interface VariableDetectionResult

A single variable occurrence with location info

interface VariableOccurrence

Union of all command types

type AgentCommand = InsertTextCommand | ReplaceTextCommand | DeleteTextCommand | FormatTextCommand | FormatParagraphCommand | ApplyStyleCommand | InsertTableCommand | InsertImageCommand | InsertHyperlinkCommand | RemoveHyperlinkCommand | InsertParagraphBreakCommand | MergeParagraphsCommand | SplitParagraphCommand | SetVariableCommand | ApplyVariablesCommand;

AI action types for context menu

type AIAction = 'askAI' | 'rewrite' | 'expand' | 'summarize' | 'translate' | 'explain' | 'fixGrammar' | 'makeFormal' | 'makeCasual' | 'custom';

Auto-save status

type AutoSaveStatus = 'idle' | 'saving' | 'saved' | 'error';

Block-level content types

type BlockContent = Paragraph | Table | BlockSdt;

Options for [convertFootnoteToContent](convertFootnoteToContent).

type ConvertFootnoteOptions = {
    styles?: StyleDefinitions | null;
    theme?: Theme | null;
    measureBlocks: MeasureBlocksFn;
};

type ConvertHeaderFooterOptions = {
    styles?: StyleDefinitions | null;
    theme?: Theme | null;
    measureBlocks: MeasureBlocksFn;
};

Any binary representation of a DOCX file that the editor can consume.

- `ArrayBuffer` — from `FileReader.readAsArrayBuffer()` or `fetch().arrayBuffer()` - `Uint8Array` — from Node.js `fs.readFile()` or streaming APIs - `Blob` — from drag-and-drop or `<input type="file">` - `File` — subclass of Blob, from `<input type="file">`

type DocxInput = ArrayBuffer | Uint8Array | Blob | File;

Editor loading state

type EditorLoadingState = 'idle' | 'parsing' | 'loading-fonts' | 'ready' | 'error';

Error severity levels

type ErrorSeverity = 'error' | 'warning' | 'info';

type Field = SimpleField | ComplexField;

Union of every block kind the layout engine knows about.

Three switches over `block.kind` must stay in sync with this type: - `runLayoutPipeline` in `layout-engine/index.ts` (this package) - `measureBlock` in `packages/react/src/paged-editor/PagedEditor.tsx` - `measureBlock` in `packages/vue/src/composables/useDocxEditor.ts`

All three end in `assertExhaustiveFlowBlock(block, '<site>')` so adding a new variant here without updating every site is a typecheck error.

type FlowBlock = ParagraphBlock | TableBlock | ImageBlock | TextBoxBlock | SectionBreakBlock | PageBreakBlock | ColumnBreakBlock;

Pre-calculated footnote content for layout and rendering.

type FootnoteContent = {
    id: number;
    displayNumber: number;
    blocks: FlowBlock[];
    measures: Measure[];
    height: number;
};

Header / Footer Layout Utilities

The header/footer rendering pipeline lives here so any rendering adapter (React, Vue, etc.) can share the conversion logic and just supply its platform-specific [MeasureBlocksFn](MeasureBlocksFn). Mirrors the footnote pipeline in `footnoteLayout.ts`.

Pipeline: HF.content → headerFooterToProseDoc → toFlowBlocks → measureBlocks (caller-supplied, Canvas-aware) → HeaderFooterContent (blocks, measures, height, visualTop/Bottom)

The render side uses the normalized block list so paint and measurement stay in lockstep. Visual-bounds calculation still inspects the original block list because floating images can paint above/below the nominal flow box even when they do not contribute to flow height.

type HeaderFooterMetrics = {
    section: 'header' | 'footer';
    pageSize: {
        w: number;
        h: number;
    };
    margins: PageMargins;
};

Final layout output ready for rendering/painting.

type Layout = {
    pageSize: {
        w: number;
        h: number;
    };
    pages: Page[];
    columns?: ColumnLayout;
    headers?: Record<string, HeaderFooterLayout>;
    footers?: Record<string, HeaderFooterLayout>;
    pageGap?: number;
};

MCP tool handler function

type McpToolHandler = (input: unknown, context: McpToolContext) => Promise<McpToolResult> | McpToolResult;

Union of all measurement types.

type Measure = ParagraphMeasure | ImageMeasure | TableMeasure | TextBoxMeasure | SectionBreakMeasure | PageBreakMeasure | ColumnBreakMeasure;

Adapter-supplied block measurement function. The caller (React / Vue / etc.) supplies its platform's measure routine — at minimum paragraph + table + image + textBox — so this core helper stays Canvas-free.

type MeasureBlocksFn = (blocks: FlowBlock[], contentWidth: number) => Measure[];

A rendered page containing positioned fragments.

type Page = {
    number: number;
    fragments: Fragment[];
    margins: PageMargins;
    size: {
        w: number;
        h: number;
    };
    orientation?: 'portrait' | 'landscape';
    sectionIndex?: number;
    headerFooterRefs?: {
        headerDefault?: string;
        headerFirst?: string;
        headerEven?: string;
        footerDefault?: string;
        footerFirst?: string;
        footerEven?: string;
    };
    footnoteIds?: number[];
    footnoteReservedHeight?: number;
    columns?: ColumnLayout;
};

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;

All possible run content types

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

Run-level tracked wrappers represented in WordprocessingML.

type TrackedRunChange = Insertion | Deletion | MoveFrom | MoveTo;

Docxtemplater plugin for template variable functionality.

Dependency validation is handled lazily by `processTemplate` at call time, so no eager `initialize()` is needed.

docxtemplaterPlugin: CorePlugin

Separator line height + vertical padding in pixels.

FOOTNOTE_SEPARATOR_HEIGHT = 12

Hard cap on the multi-pass footnote layout loop. Reserving footnote space can move a reference to another page, so adapters keep remapping until the page→height contract is stable. Dense layouts converge in 2–3 passes in practice; 6 is a safe ceiling.

MAX_FOOTNOTE_LAYOUT_PASSES = 6

Global plugin registry instance

Use this for registering plugins and accessing their capabilities.

pluginRegistry: PluginRegistry

rgbToHex: typeof cssColorToHex

eigenpal/docx-editor-core (default entry point)

Fat barrel that re-exports the parser, serializer, agent, plugin registry, and the most-used types. No React/DOM imports.

**When to import from `.` vs `./headless`:** identical for Node.js use; `.` is the convenient aggregate, `./headless` is its mirror with a slightly different name suffix. Adapter authors who only need a specific slice should prefer the smaller subpaths (`./docx`, `./agent`, `./prosemirror`, `./layout-*`, `./utils`) — they tree-shake better.

VERSION = "0.0.2"

```ts
import { parseDocx, serializeDocx, resolveColor } from '@eigenpal/docx-editor-core';
```