@eigenpal/docx-editor-core/agent

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;

buildExtendedSelectionContextfunctionSource ↗

Build extended selection context with additional details

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

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;

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;

createRangefunctionSource ↗

Create a range from two positions

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

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;

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

formatSdtDatefunctionSource ↗

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

declare function formatSdtDate(iso: string, pattern?: 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;

getDocumentSummaryfunctionSource ↗

Get a simple document summary for quick context

declare function getDocumentSummary(doc: Document): string;

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;

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;

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;

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;

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;

parseHeadingLevelfunctionSource ↗

Parse heading level from style ID

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

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;

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;

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

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

AgentSelectionContextinterface

Context about the current selection

interface SelectionContext

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

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

DeleteTextCommandinterfaceSource ↗

Delete text in a range

interface DeleteTextCommand extends BaseCommand

ExtendedSelectionContextinterfaceSource ↗

Extended selection context with additional details

interface ExtendedSelectionContext extends SelectionContext

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

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

InsertParagraphBreakCommandinterfaceSource ↗

Insert a paragraph break

interface InsertParagraphBreakCommand extends BaseCommand

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

MergeParagraphsCommandinterfaceSource ↗

Merge paragraphs

interface MergeParagraphsCommand extends BaseCommand

ParagraphContextinterfaceSource ↗

Paragraph context for selection

interface ParagraphContext

ParagraphOutlineinterfaceSource ↗

Paragraph outline for context

interface ParagraphOutline

Position_2interface

Position within a document

interface Position

Range_2interface

Range within a document

interface Range

RemoveHyperlinkCommandinterfaceSource ↗

Remove a hyperlink but keep the text

interface RemoveHyperlinkCommand extends BaseCommand

ReplaceTextCommandinterfaceSource ↗

Replace text in a range

interface ReplaceTextCommand extends BaseCommand

SectionInfointerfaceSource ↗

Section information

interface SectionInfo

SelectionContextOptionsinterfaceSource ↗

Options for building selection context

interface SelectionContextOptions

SetVariableCommandinterfaceSource ↗

Set template variable value

interface SetVariableCommand extends BaseCommand

SplitParagraphCommandinterfaceSource ↗

Split a paragraph

interface SplitParagraphCommand extends BaseCommand

StyleInfointerfaceSource ↗

Style information for context

interface StyleInfo

SuggestedActioninterfaceSource ↗

Suggested action for context menu

interface SuggestedAction

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

ContentControlValuetypeSource ↗

A typed value to apply to a content control.

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

DEFAULT_AI_ACTIONSconstSource ↗

Default AI actions for context menu

DEFAULT_AI_ACTIONS: AIAction[]