@eigenpal/docx-editor-core/headless

addRepeatingSectionItemfunctionSource ↗

Add a new repeating-section item, cloned from an existing one and inserted after it. afterIndex is the item ordinal to clone/insert after (default: the last item). Returns a new [Document](Document).

declare function addRepeatingSectionItem(doc: Document, filter: ContentControlFilter, options?: {
    afterIndex?: number;
}): Document;

attemptSelectiveSavefunctionSource ↗

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

blendColorsfunctionSource ↗

Blend two colors together

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

buildExtendedSelectionContextfunctionSource ↗

Build extended selection context with additional details

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

buildPatchedDocumentXmlfunctionSource ↗

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;

buildSelectionContextfunctionSource ↗

Build selection context for AI operations

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

buildSelectionContextFromContextfunction

Build selection context for AI operations

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

colorsEqualfunctionSource ↗

Check if two colors are equal

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

comparePositionsfunctionSource ↗

Compare two positions Returns: -1 if a b, 0 if equal, 1 if a b

declare function comparePositions(a: Position, b: Position): -1 | 0 | 1;

countCharactersfunctionSource ↗

Count characters in text

declare function countCharacters(text: string, includeSpaces?: boolean): number;

countWordsfunctionSource ↗

Count words in text

declare function countWords(text: string): number;

createAgentfunctionSource ↗

Create a DocumentAgent from a DOCX buffer

declare function createAgent(buffer: ArrayBuffer): Promise<DocumentAgent>;

createAgentFromDocumentfunctionSource ↗

Create a DocumentAgent from a parsed Document

declare function createAgentFromDocument(document: Document): DocumentAgent;

createCollapsedRangefunctionSource ↗

Create a collapsed range (cursor) at a position

declare function createCollapsedRange(position: Position): Range;

createCommandfunctionSource ↗

Create a command with generated ID

declare function createCommand<T extends AgentCommand>(command: Omit<T, 'id'>): T;

createDocumentWithTextfunctionSource ↗

Create a document with a single paragraph containing the given text

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

createDocxfunctionSource ↗

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

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

createEmptyDocumentfunctionSource ↗

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!'
});
```

createPluginRegistrarfunctionSource ↗

Create a plugin registration helper with options pre-configured

declare function createPluginRegistrar(options: PluginOptions): (plugin: CorePlugin) => PluginRegistrationResult;

createRangefunctionSource ↗

Create a range from two positions

declare function createRange(start: Position, end: Position): Range;

createRgbColorfunctionSource ↗

Create a ColorValue from RGB hex

declare function createRgbColor(hex: string): ColorValue;

createTemplateProcessorfunctionSource ↗

Create a template processor with preset options

declare function createTemplateProcessor(defaultOptions?: ProcessTemplateOptions): (buffer: ArrayBuffer, variables: Record<string, string>) => ArrayBuffer;

createThemeColorfunctionSource ↗

Create a ColorValue from theme color reference

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

darkenColorfunctionSource ↗

Darken a color by a percentage

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

detectVariablesfunctionSource ↗

Detect all template variables in a document

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

detectVariablesDetailedfunctionSource ↗

Detect variables with detailed information

declare function detectVariablesDetailed(doc: Document): VariableDetectionResult;

detectVariablesInBodyfunctionSource ↗

Detect variables in document body

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

detectVariablesInParagraphfunctionSource ↗

Detect variables in a paragraph

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

documentHasVariablesfunctionSource ↗

Check if document has any template variables

declare function documentHasVariables(doc: Document): boolean;

emuToPixelsfunctionSource ↗

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;

emuToTwipsfunctionSource ↗

Convert EMUs to twips

declare function emuToTwips(emu: number): number;

executeCommandfunctionSource ↗

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;

executeCommandsfunctionSource ↗

Execute multiple commands in sequence

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

extractVariablesFromTextfunctionSource ↗

Extract variable names from text

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

findContentControlfunctionSource ↗

Convenience: the first control matching filter, or undefined.

declare function findContentControl(input: Document | DocumentBody, filter: ContentControlFilter): ContentControlInfo | undefined;

findContentControlsfunctionSource ↗

Find every block-level content control in the document, optionally filtered by tag/alias/id/type. Results are in document order; nested controls follow their parent. Searches the body and controls nested inside controls. Table cells are not searched (the current model/parser does not surface cell-level controls), and headers/footers live in a separate content tree.

declare function findContentControls(input: Document | DocumentBody, filter?: ContentControlFilter): ContentControlInfo[];

formatPxfunctionSource ↗

Format a pixel value as CSS string

declare function formatPx(px: number): string;

formatSdtDatefunctionSource ↗

Format an ISO date (yyyy-mm-dd) with a subset of OOXML date tokens.

declare function formatSdtDate(iso: string, pattern?: string): string;

formatVariablefunctionSource ↗

Format a variable name with braces (standard docxtemplater syntax)

declare function formatVariable(name: string): string;

getActionDescriptionfunctionSource ↗

Get action description

declare function getActionDescription(action: AIAction): string;

getActionLabelfunctionSource ↗

Get action label

declare function getActionLabel(action: AIAction): string;

getAgentContextfunctionSource ↗

Build agent context from a document

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

getBlockIndexForParagraphfunctionSource ↗

Get block index for a paragraph index

declare function getBlockIndexForParagraph(body: DocumentBody, paragraphIndex: number): number;

getBodyCharacterCountfunctionSource ↗

Get character count from document body

declare function getBodyCharacterCount(body: DocumentBody): number;

getBodyTextfunctionSource ↗

Get plain text from document body

declare function getBodyText(body: DocumentBody): string;

getBodyWordCountfunctionSource ↗

Get word count from document body

declare function getBodyWordCount(body: DocumentBody): number;

getContentControlTextfunctionSource ↗

Plain text of a control's content, descending into tables and nested SDTs.

declare function getContentControlText(control: BlockSdt): string;

getContrastingColorfunctionSource ↗

Get contrasting text color for a background

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

getDocumentSummaryfunctionSource ↗

Get a simple document summary for quick context

declare function getDocumentSummary(doc: Document): string;

getDocumentWatermarkfunctionSource ↗

Read the document's watermark (the first header that carries one).

declare function getDocumentWatermark(doc: Document | null | undefined): Watermark | undefined;

getFormattingAtPositionfunctionSource ↗

Get formatting at a specific position in a paragraph

declare function getFormattingAtPosition(paragraph: Paragraph, offset: number): Partial<TextFormatting>;

getHyperlinkAtPositionfunctionSource ↗

Get hyperlink at position

declare function getHyperlinkAtPosition(paragraph: Paragraph, offset: number): Hyperlink | undefined;

getHyperlinkTextfunctionSource ↗

Get plain text from a hyperlink

declare function getHyperlinkText(hyperlink: Hyperlink): string;

getMissingVariablesfunctionSource ↗

Check if all required variables have values

declare function getMissingVariables(tags: string[], variables: Record<string, string>): string[];

getParagraphAtIndexfunctionSource ↗

Get paragraph at index from document body

declare function getParagraphAtIndex(body: DocumentBody, index: number): Paragraph | undefined;

getParagraphsfunctionSource ↗

Get all paragraphs from document body

declare function getParagraphs(body: DocumentBody): Paragraph[];

getParagraphTextfunctionSource ↗

Get plain text from a paragraph

declare function getParagraphText(paragraph: Paragraph): string;

getRunTextfunctionSource ↗

Get plain text from a run

declare function getRunText(run: Run): string;

getSelectionFormattingSummaryfunctionSource ↗

Get formatting summary for a selection

declare function getSelectionFormattingSummary(doc: Document, range: Range): FormattingSummary;

getTableTextfunctionSource ↗

Get plain text from a table

declare function getTableText(table: Table): string;

getTemplateTagsfunctionSource ↗

Get all template tags in a document without processing

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

getTextAfterfunctionSource ↗

Get text after a position

declare function getTextAfter(paragraphs: Paragraph[], position: Position, maxChars: number): string;

getTextBeforefunctionSource ↗

Get text before a position

declare function getTextBefore(paragraphs: Paragraph[], position: Position, maxChars: number): string;

halfPointsToPixelsfunctionSource ↗

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;

hasHyperlinksfunctionSource ↗

Check if document body has hyperlinks

declare function hasHyperlinks(body: DocumentBody): boolean;

hasImagesfunctionSource ↗

Check if document body has images

declare function hasImages(body: DocumentBody): boolean;

hasTablesfunctionSource ↗

Check if document body has tables

declare function hasTables(body: DocumentBody): boolean;

hasTemplateVariablesfunctionSource ↗

Check if text contains template variables

declare function hasTemplateVariables(text: string): boolean;

isBlackfunctionSource ↗

Check if a color is effectively black

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

isHeadingStylefunctionSource ↗

Check if style ID represents a heading

declare function isHeadingStyle(styleId?: string): boolean;

isPositionInHyperlinkfunctionSource ↗

Check if position is within a hyperlink

declare function isPositionInHyperlink(paragraph: Paragraph, offset: number): boolean;

isPositionInRangefunctionSource ↗

Check if a position is within a range

declare function isPositionInRange(position: Position, range: Range): boolean;

isRepeatingSectionfunctionSource ↗

The control's raw w:sdtPr declares it a repeating section (the container).

declare function isRepeatingSection(props: SdtProperties): boolean;

isRepeatingSectionItemfunctionSource ↗

The control's raw w:sdtPr declares it a repeating-section item.

declare function isRepeatingSectionItem(props: SdtProperties): boolean;

isValidVariableNamefunctionSource ↗

Check if a variable name is valid

declare function isValidVariableName(name: string): boolean;

isWhitefunctionSource ↗

Check if a color is effectively white

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

isZodSchemafunctionSource ↗

Check if a schema is Zod-like

declare function isZodSchema(schema: unknown): schema is ZodSchemaLike;

lightenColorfunctionSource ↗

Lighten a color by a percentage

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

mapHexToHighlightNamefunctionSource ↗

declare function mapHexToHighlightName(hex: string): string | null;

parseColorStringfunctionSource ↗

Parse a color string (various formats) to ColorValue

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

parseDocxfunctionSource ↗

Parse a DOCX file into a complete Document model

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

parseHeadingLevelfunctionSource ↗

Parse heading level from style ID

declare function parseHeadingLevel(styleId?: string): number | undefined;

parseVariablefunctionSource ↗

Parse a variable string to get the name

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

pixelsToEmufunctionSource ↗

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;

pixelsToTwipsfunctionSource ↗

Convert pixels to twips

declare function pixelsToTwips(px: number): number;

pointsToHalfPointsfunctionSource ↗

Convert points to half-points

declare function pointsToHalfPoints(points: number): number;

pointsToPixelsfunctionSource ↗

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;

previewTemplatefunctionSource ↗

Preview what the document will look like after processing Returns the document text with variables replaced (for preview purposes)

declare function previewTemplate(buffer: ArrayBuffer, variables: Record<string, string>): string;

processTemplatefunctionSource ↗

Process a DOCX template with variable substitution

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

processTemplateAdvancedfunctionSource ↗

Process template with conditional sections Supports #if, #unless, #each loops

declare function processTemplateAdvanced(buffer: ArrayBuffer, data: Record<string, unknown>, options?: ProcessTemplateOptions): ArrayBuffer;

processTemplateAsBlobfunctionSource ↗

Process template and return as Blob

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

processTemplateDetailedfunctionSource ↗

Process template with detailed result

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

registerPluginsfunctionSource ↗

Register multiple plugins at once

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

removeContentControlfunctionSource ↗

Remove the first control matching filter from the document. With keepContent: true the control's blocks are unwrapped in place (the box goes away, the content stays) — useful for "resolve this conditional section into plain content". Otherwise the whole region is deleted.

Unwrapping a repeating-section (item) is refused unless force, since lifting its blocks out would orphan the (w15) repeating structure.

Throws [ContentControlNotFoundError](ContentControlNotFoundError) / [ContentControlLockedError](ContentControlLockedError) as [setContentControlContent](setContentControlContent) does.

declare function removeContentControl(doc: Document, filter: ContentControlFilter, options?: {
    force?: boolean;
    keepContent?: boolean;
}): Document;

removeRepeatingSectionItemfunctionSource ↗

Remove the repeating-section item at ordinal index. Keeps at least one item (Word does not allow removing the last). Returns a new [Document](Document).

declare function removeRepeatingSectionItem(doc: Document, filter: ContentControlFilter, index: number): Document;

removeVariablesfunctionSource ↗

Replace all variables in text with a placeholder

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

repackDocxfunctionSource ↗

Repack a Document into a valid DOCX file

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

replaceVariablesfunctionSource ↗

Replace variables in text with values

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

resolveColorfunctionSource ↗

Resolve a ColorValue to a CSS color string

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

resolveHighlightColorfunctionSource ↗

Resolve a highlight color name to CSS

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

resolveShadingColorfunctionSource ↗

Resolve a shading fill or pattern color to CSS

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

sanitizeVariableNamefunctionSource ↗

Sanitize a variable name

declare function sanitizeVariableName(name: string): string;

serializeDocumentBodyfunctionSource ↗

Serialize a DocumentBody to document.xml body content

declare function serializeDocumentBody(body: DocumentBody): string;

serializeDocxfunction

Serialize a complete Document to valid document.xml

declare function serializeDocument(doc: Document): string;

serializeSectionPropertiesfunctionSource ↗

Serialize section properties (w:sectPr)

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

setContentControlContentfunctionSource ↗

Replace the content of the first control matching filter. replacement may be a string (split into paragraphs on newlines) or block content. The control's properties, tag/alias, and lossless raw w:sdtPr are preserved — only the contained blocks change, so the result still round-trips.

When the control was showing its placeholder (w:showingPlcHdr), that flag is cleared so Word doesn't render the new content as placeholder text.

Throws [ContentControlNotFoundError](ContentControlNotFoundError) if nothing matches, [ContentControlLockedError](ContentControlLockedError) if the control's lock forbids editing, and [ContentControlTypeError](ContentControlTypeError) if the control is a typed (dropdown/date/…) control whose value shouldn't be set as free text. Pass { force: true } to override the lock/type guards.

declare function setContentControlContent(doc: Document, filter: ContentControlFilter, replacement: string | BlockContent[], options?: {
    force?: boolean;
}): Document;

setContentControlValuefunctionSource ↗

Set a typed value (dropdown selection / checkbox / date) on the first control matching filter, returning a new [Document](Document). Updates both the visible content and the structured raw state, so the result round-trips and Word shows the new value. Throws [ContentControlNotFoundError](ContentControlNotFoundError) if nothing matches, [ContentControlLockedError](ContentControlLockedError) if content-locked, [ContentControlBoundError](ContentControlBoundError) if data-bound (the store would override the write), and [ContentControlValueError](ContentControlValueError) if the value doesn't fit the control type. The lock/bound guards are overridable with { force: true }.

declare function setContentControlValue(doc: Document, filter: ContentControlFilter, value: ContentControlValue, options?: {
    force?: boolean;
}): Document;

setDocumentWatermarkfunctionSource ↗

Return a new Document with the watermark applied to all headers, or removed when watermark is null. Creates the header parts a section needs but lacks (default for a headerless doc; first/even for title/even pages) so the watermark shows on every page MS Word would show it.

declare function setDocumentWatermark(doc: Document, watermark: Watermark | null): Document;

twipsToEmufunctionSource ↗

Convert twips to EMUs

declare function twipsToEmu(twips: number): number;

twipsToPixelsfunctionSource ↗

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;

updateMultipleFilesfunctionSource ↗

Update multiple files in a DOCX buffer

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

validatePatchSafetyfunctionSource ↗

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;

validateTemplatefunctionSource ↗

Validate that a document is a valid docxtemplater template

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

ContentControlBoundErrorclassSource ↗

The control is bound to a Custom XML data store (w:dataBinding). Writing its content won't stick — Word re-renders the control from the bound XML node — so the write is refused. Update the data store instead, or pass { force: true }.

declare class ContentControlBoundError extends Error

ContentControlLockedErrorclassSource ↗

The matched control's lock forbids the attempted edit (pass force to override).

declare class ContentControlLockedError extends Error

ContentControlNotFoundErrorclassSource ↗

No control matched the filter.

declare class ContentControlNotFoundError extends Error

ContentControlTypeErrorclassSource ↗

The control's type doesn't support free text/block replacement (e.g. a dropdown, date, checkbox, or picture control), so writing arbitrary content would desync the type marker from its value. Use a type-specific setter, or pass { force: true } to override.

declare class ContentControlTypeError extends Error

ContentControlValueErrorclassSource ↗

The control doesn't support the requested value kind, or the value is invalid.

declare class ContentControlValueError extends Error

DocumentAgentclassSource ↗

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();
```

PluginRegistryclassSource ↗

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

RepeatingSectionErrorclassSource ↗

Raised when an operation targets something that isn't a repeating section/item.

declare class RepeatingSectionError extends Error

AgentContextinterfaceSource ↗

Document context for AI agents

interface AgentContext

AgentContextOptionsinterfaceSource ↗

Options for building agent context

interface AgentContextOptions

AgentResponseinterfaceSource ↗

Response from an agent action

interface AgentResponse

AIActionRequestinterfaceSource ↗

AI action request

interface AIActionRequest

ApplyStyleCommandinterfaceSource ↗

Apply a named style to a paragraph

interface ApplyStyleCommand extends BaseCommand

ApplyVariablesCommandinterfaceSource ↗

Apply all template variables

interface ApplyVariablesCommand extends BaseCommand

CommandResultinterfaceSource ↗

Result of command execution

interface CommandResult

Comment_2interface

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

CommentRangeEndinterfaceSource ↗

Comment range end marker in paragraph content

interface CommentRangeEnd

CommentRangeStartinterfaceSource ↗

Comment range start marker in paragraph content

interface CommentRangeStart

ContentControlFilterinterfaceSource ↗

Filter for [findContentControls](findContentControls). All provided fields must match (AND).

interface ContentControlFilter

ContentControlInfointerfaceSource ↗

A discovered content control plus enough context to address and edit it.

interface ContentControlInfo

ContextSelectionOptionsinterface

Options for building selection context

interface SelectionContextOptions$1

CorePlugininterfaceSource ↗

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

CreateEmptyDocumentOptionsinterfaceSource ↗

Options for creating an empty document

interface CreateEmptyDocumentOptions

DeleteTextCommandinterfaceSource ↗

Delete text in a range

interface DeleteTextCommand extends BaseCommand

DeletioninterfaceSource ↗

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

interface Deletion

Document_2interface

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);
```

DocumentBodyinterfaceSource ↗

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

DocxPackageinterfaceSource ↗

Complete DOCX package structure

interface DocxPackage

EndnoteinterfaceSource ↗

Endnote (w:endnote)

interface Endnote

ExtendedSelectionContextinterfaceSource ↗

Extended selection context with additional details

interface ExtendedSelectionContext extends SelectionContext

FootnoteinterfaceSource ↗

Footnote (w:footnote)

interface Footnote

FormatParagraphCommandinterfaceSource ↗

Apply paragraph formatting

interface FormatParagraphCommand extends BaseCommand

FormattedTextSegmentinterfaceSource ↗

Formatted text segment

interface FormattedTextSegment

FormatTextCommandinterfaceSource ↗

Apply formatting to a range

interface FormatTextCommand extends BaseCommand

FormattingSummaryinterfaceSource ↗

Selection formatting summary

interface FormattingSummary

HyperlinkinterfaceSource ↗

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

Image_2interface

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

InsertHyperlinkCommandinterfaceSource ↗

Insert a hyperlink at a range

interface InsertHyperlinkCommand extends BaseCommand

InsertHyperlinkOptionsinterfaceSource ↗

Options for inserting hyperlink

interface InsertHyperlinkOptions

InsertImageCommandinterfaceSource ↗

Insert an image at a position

interface InsertImageCommand extends BaseCommand

InsertImageOptionsinterfaceSource ↗

Options for inserting image

interface InsertImageOptions

InsertioninterfaceSource ↗

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

interface Insertion

InsertTableCommandinterfaceSource ↗

Insert a table at a position

interface InsertTableCommand extends BaseCommand

InsertTableOptionsinterfaceSource ↗

Options for inserting table

interface InsertTableOptions

InsertTextCommandinterfaceSource ↗

Insert text at a position

interface InsertTextCommand extends BaseCommand

InsertTextOptionsinterfaceSource ↗

Options for inserting text

interface InsertTextOptions

JsonSchemainterfaceSource ↗

JSON Schema definition (subset)

interface JsonSchema

ListLevelinterfaceSource ↗

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

LoadedDocumentinterfaceSource ↗

A loaded document in the session

interface LoadedDocument

McpSessioninterfaceSource ↗

MCP session state

Maintains state across tool calls within a session.

interface McpSession

McpToolAnnotationsinterfaceSource ↗

MCP tool annotations

interface McpToolAnnotations

McpToolContextinterfaceSource ↗

Context passed to MCP tool handlers

interface McpToolContext

McpToolDefinitioninterfaceSource ↗

MCP tool definition

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

interface McpToolDefinition

McpToolResultinterfaceSource ↗

MCP tool result

interface McpToolResult

MoveFrominterfaceSource ↗

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

interface MoveFrom

MoveTointerfaceSource ↗

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

interface MoveTo

NumberingDefinitionsinterfaceSource ↗

Top-level numbering data from numbering.xml — the set of abstract templates and the per-document NumberingInstances that reference them. Paragraphs reference a numId (instance), not an abstractNumId directly.

interface NumberingDefinitions

ParagraphinterfaceSource ↗

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

ParagraphContextinterfaceSource ↗

Paragraph context for selection

interface ParagraphContext

ParagraphFormattinginterfaceSource ↗

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

ParagraphOutlineinterfaceSource ↗

Paragraph outline for context

interface ParagraphOutline

PluginCommandinterfaceSource ↗

Extended command type for plugins

Plugins can define custom command types beyond the built-in AgentCommand types.

interface PluginCommand

PluginOptionsinterfaceSource ↗

Plugin configuration options

interface PluginOptions

PluginRegistrationResultinterfaceSource ↗

Result of plugin registration

interface PluginRegistrationResult

Position_2interface

Position within a document

interface Position

ProcessTemplateOptionsinterfaceSource ↗

Options for template processing

interface ProcessTemplateOptions

ProcessTemplateResultinterfaceSource ↗

Result of template processing

interface ProcessTemplateResult

Range_2interface

Range within a document

interface Range

RelationshipinterfaceSource ↗

Relationship entry

interface Relationship

ReplaceTextCommandinterfaceSource ↗

Replace text in a range

interface ReplaceTextCommand extends BaseCommand

RuninterfaceSource ↗

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

SectionInfointerfaceSource ↗

Section information

interface SectionInfo

SectionPropertiesinterfaceSource ↗

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

SelectionContextinterfaceSource ↗

Context about the current selection

interface SelectionContext

SelectionContextOptionsinterfaceSource ↗

Options for building selection context

interface SelectionContextOptions

SetVariableCommandinterfaceSource ↗

Set template variable value

interface SetVariableCommand extends BaseCommand

StyleinterfaceSource ↗

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

StyleDefinitionsinterfaceSource ↗

Style definitions from styles.xml

interface StyleDefinitions

StyleInfointerfaceSource ↗

Style information for context

interface StyleInfo

SuggestedActioninterfaceSource ↗

Suggested action for context menu

interface SuggestedAction

TableinterfaceSource ↗

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

TableCellinterfaceSource ↗

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

TableRowinterfaceSource ↗

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

TemplateErrorinterfaceSource ↗

Error details from template processing

interface TemplateError

TextContentinterfaceSource ↗

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

TextFormattinginterfaceSource ↗

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

ThemeinterfaceSource ↗

Theme (from theme1.xml)

interface Theme

TrackedChangeInfointerfaceSource ↗

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

interface TrackedChangeInfo

VariableDetectionResultinterfaceSource ↗

Result of variable detection

interface VariableDetectionResult

VariableOccurrenceinterfaceSource ↗

A single variable occurrence with location info

interface VariableOccurrence

ZodSchemaLikeinterfaceSource ↗

Zod-like schema interface for compatibility

interface ZodSchemaLike

AgentCommandtypeSource ↗

Union of all command types

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

AIActiontypeSource ↗

AI action types for context menu

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

BlockContenttypeSource ↗

Block-level content types

type BlockContent = Paragraph | Table | BlockSdt;

CommandHandlertypeSource ↗

Command handler function type

Receives a document and a command, returns a modified document. Must be pure/immutable - always return a new document.

type CommandHandler = (doc: Document, command: PluginCommand) => Document;

ContentControlValuetypeSource ↗

A typed value to apply to a content control.

type ContentControlValue = {
    kind: 'dropdown';
    value: string;
} | {
    kind: 'checkbox';
    checked: boolean;
} | {
    kind: 'date';
    date: string;
};

McpToolContenttypeSource ↗

MCP tool content types

type McpToolContent = {
    type: 'text';
    text: string;
} | {
    type: 'image';
    data: string;
    mimeType: string;
} | {
    type: 'resource';
    uri: string;
    mimeType?: string;
    text?: string;
};

McpToolHandlertypeSource ↗

MCP tool handler function

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

ParagraphContenttypeSource ↗

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;

PluginEventtypeSource ↗

Plugin lifecycle events

type PluginEvent = {
    type: 'registered';
    plugin: CorePlugin;
} | {
    type: 'unregistered';
    pluginId: string;
} | {
    type: 'error';
    pluginId: string;
    error: Error;
};

PluginEventListenertypeSource ↗

Plugin event listener

type PluginEventListener = (event: PluginEvent) => void;

RunContenttypeSource ↗

All possible run content types

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

TrackedRunChangetypeSource ↗

Run-level tracked wrappers represented in WordprocessingML.

type TrackedRunChange = Insertion | Deletion | MoveFrom | MoveTo;

DEFAULT_AI_ACTIONSconstSource ↗

Default AI actions for context menu

DEFAULT_AI_ACTIONS: AIAction[]

pluginRegistryconstSource ↗

Global plugin registry instance

Use this for registering plugins and accessing their capabilities.

pluginRegistry: PluginRegistry

VERSIONconstSource ↗

eigenpal/docx-editor-core/headless

Headless aggregate for Node.js scripts, CLI tools, and server-side processing. Same surface as the default . entry, named to make the "no DOM" intent explicit. Prefer the smaller subpaths (./docx, ./agent, ./utils, etc.) for new code — they tree-shake better.

VERSION = "0.0.2"

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

// Register plugins
pluginRegistry.register(docxtemplaterPlugin);

// Load and manipulate document
const buffer = fs.readFileSync('template.docx');
const agent = await DocumentAgent.fromBuffer(buffer);

// Get document info
console.log('Word count:', agent.getWordCount());
console.log('Variables:', agent.getVariables());

// Edit document
const newAgent = agent
  .insertText({ paragraphIndex: 0, offset: 0 }, 'Hello ')
  .applyStyle(0, 'Heading1');

// Apply template variables
const finalAgent = await newAgent.applyVariables({
  customer_name: 'Jane Doe',
  date: '2024-02-15',
});

// Export
const output = await finalAgent.toBuffer();
fs.writeFileSync('output.docx', Buffer.from(output));
```