@docx-editor.dev/core

bindHistoryGroupfunctionSource ↗

Bind native gesture events. Framework change handlers apply values; this binding ends groups. Native color change means value commitment, not portable popup closure. Controls without a terminal change event end on the next activation, Escape, blur, or disposal. Range/repeat controls end on pointer release/cancel or keyup, including outside releases. Terminal events close after propagation so the final value can use the same handle.

declare function bindHistoryGroup(editor: Editor, element: HTMLElement, config: HistoryGroupBindingOptions): HistoryGroupBinding;

blankDocumentBytesfunctionSource ↗

A blank document, freshly zipped per call (the caller may hand the bytes to a loader that takes ownership). Calibri 11pt and Word's Normal paragraph spacing are authored in w:docDefaults, Word's built-in style gallery in styles.xml, and US Letter geometry in the section. Word opens the saved file.

A right-to-left interface usually wants { direction: 'rtl', bidiLanguage: 'ar-SA' } (or the reader's own language), so the first paragraph is ready for right-to-left typing.

declare function blankDocumentBytes(options?: BlankDocumentOptions): Uint8Array;

chromeMenuSlotsfunctionSource ↗

Every slot a menu places, in menu order, submenus flattened. What a parity test asserts against, and what a host enumerates to know which capabilities the menu bar reaches.

declare function chromeMenuSlots(): readonly ChromeSlotId[];

commandForSlotfunctionSource ↗

The public editor command behind one chrome slot, or null when the slot is not wired to a command yet (parity-only chrome, or save — which is not a command). The single source of command truth for both adapters.

declare function commandForSlot(slotId: ChromeSlotId): EditorCommand | null;

commandForSlotValuefunctionSource ↗

The engine command for a VALUE-TYPED slot carrying the picked value, or null for a slot that does not take a value.

Two families: the run-property pickers (font.family, font.size, text.color, text.highlight) resolve to setMarkAttr, and styles.style resolves to setParagraphStyle — a paragraph styleId, not a mark. Either way the value is validated by the engine's own gate (can refuses a malformed one with invalidArgs; a styleId the document does not define is refused at exec), so a host can pass user input through unmodified.

declare function commandForSlotValue(slotId: ChromeSlotId, value: unknown): EditorCommand | null;

compareDocumentsErrorKeyfunctionSource ↗

The @docx-editor.dev/i18n key of the message for a refused compare: compareDocuments.reasons.<reason> when the refusal names a reason, else compareDocuments.errors.<code>.

declare function compareDocumentsErrorKey(refusal: {
    readonly code: CompareDocumentsErrorCode;
    readonly reason?: CompareDocumentsRefusalReason;
}): `compareDocuments.errors.${CompareDocumentsErrorCode}` | `compareDocuments.reasons.${CompareDocumentsRefusalReason}`;

```ts
const outcome = await session.apply({ revised });
if (!outcome.ok) showError(t(compareDocumentsErrorKey(outcome)));
```

composeFontConfigurationfunctionSource ↗

Merge a base and any number of fragments into one frozen FontConfiguration.

A bare fragment IS a valid base, so the single-origin case is one argument: composeFontConfiguration(await loadDefaultFonts()). Pass extra fragments to layer origins, and set epoch/maxFontBytes/defaultFont on the base only when you need something other than the documented defaults.

- Sources dedupe first-wins by (family, weight, style), in argument order — base before fragments, earlier fragments before later ones. - Substitutions dedupe first-wins by their from face, in the same order, and every substitution whose from face has a direct source anywhere in the composition is dropped: a real face always beats a stand-in. - The result is frozen (arrays included); the byte arrays themselves are the callers' and are not copied here — the resource snapshot takes its own defensive copy.

declare function composeFontConfiguration(base: FontConfigurationBase, ...fragments: readonly FontConfigurationFragment[]): FontConfiguration;

composeFontOriginsfunctionSource ↗

Resolve a list of [FontOrigin](FontOrigin)s against one document's needs and merge them, first-wins in list order.

Origins resolve IN ORDER, one after another, and each is told which faces the ones before it can already paint ([FontResolutionRequest.resolvedFaces](FontResolutionRequest.resolvedFaces)). Sequential rather than a Promise.all, and that is a real cost — one extra origin's latency on the critical path — bought deliberately: composition is first-wins, so a later origin's copy of a face an earlier one supplied can never be used, and fetching it anyway spends the bytes twice and tells a font host which families the document uses for a result that gets thrown away. Order origins cheapest-first.

A resolver that ignores resolvedFaces still composes correctly; it just spends more.

ONE ORIGIN CANNOT SINK THE REST. An origin that throws, answers null, or answers something malformed is reported and skipped whole, and the origins around it still compose — an app that listed a flaky network origin behind a bundled one keeps the bundled faces. Skipped WHOLE: an answer is read completely before any of it is committed, so a half-ingested origin can never reach composition.

The result carries NO epoch: it is a fragment for the engine to stamp with the load sequence. A fixed epoch from here would label every document's byte set as the same one. undefined means no origin contributed anything, which is a normal answer — the document stays on the fixed measurer.

declare function composeFontOrigins(origins: readonly FontOrigin[], request: FontResolutionRequest, options?: ComposeFontOriginsOptions): Promise<FontConfigurationFragment | undefined>;

createDocxEditorfunctionSource ↗

Build an editor: the full Editor contract over a paginated surface.

Construction is separate from mounting. Pass a container and the document mounts immediately; omit it and nothing touches the DOM until attach(el) — the provider-first shape. detach() parks the live document and a later attach(el) moves it in, with undo, selection and collaboration intact, even into another window (a pop-out or an iframe).

snapshot() is version-cached: the same reference until state actually moves, with reference-stable sub-objects, so it is safe as a useSyncExternalStore source.

declare function createDocxEditor(config: DocxEditorConfig): DocxEditorInstance;

```ts
const editor = createDocxEditor({ document: bytes, modules: [reviewModule()] });
editor.attach(element);
editor.on('change', () => setDirty(true));
```

createFontSourcefunctionSource ↗

Turn font bytes you ALREADY hold into a FontSource — a file input, IndexedDB, a bundler import. loadFonts covers URLs; this covers everything else, so no caller has to hand-assemble the record or reach for a hashing helper.

Returns a typed failure instead of throwing when the descriptor or the bytes are unusable, matching loadFonts: one bad face degrades itself, never its neighbours.

declare function createFontSource(bytes: Uint8Array, request: FontFaceRequest & {
    readonly faceIndex?: number;
}, options?: {
    readonly id?: string;
    readonly maxFontBytes?: number;
}): {
    readonly source: FontSource;
} | {
    readonly failure: FontLoadFailure;
};

customFontsfunctionSource ↗

Supply application fonts without manual resolver wiring.

Loads all listed faces when the editor resolves fonts, including families the document does not use yet. This makes company fonts available in the font picker for new documents. Faces supplied by earlier origins are skipped by family, weight, and style; family matching ignores case. URLs always come from sources, never from document text.

Uses [loadFonts](loadFonts) for validation, optional hash checks, and browser caching. The editor registers the returned bytes under private aliases. This function does not change the document's selected fonts or register page-wide family names.

Constructing the resolver does not fetch. Cancellation of the document load rejects with signal.reason, without warnings or onFailure calls. Other face failures are reported once per resolution, and successful faces remain available to the editor.

ts const fonts = useFonts( customFonts({ sources: companyFontFiles, onFailure: reportFontFailure }), packagedFonts(), googleFonts(), );

Use [loadFonts](loadFonts) directly to load every listed face eagerly.

declare function customFonts(options: CustomFontsOptions): CustomFontsResolver;

deferFontsfunctionSource ↗

Load an origin's faces after the document first paints, instead of before.

The editor opens the document with the faces the other origins supply, then lays it out again when these arrive. Use it for faces that are large or slow to fetch. Leave an origin unwrapped to install its faces with the document's other waiting fonts: a large document (over about 512 KB of uncompressed content) waits up to 2 seconds for them before its first paint.

ts const fonts = [packagedFonts(), deferFonts(myBrandFonts())];

A document export that receives this origin waits for its faces, so exported pages use them. The faces never change the configuration settings, such as defaultFont or maxFontBytes: those come from the origins that answer at once, so the document does not change its default font after it paints.

declare function deferFonts(origin: FontOrigin): MarkedFontResolver;

defineFontResolverfunctionSource ↗

Mark a function as an on-demand [FontResolver](FontResolver).

Wrap every resolver you put in a fonts list — useFonts(...), useDocxSource's fonts option, composeFontOrigins. The fonts PROP needs no marking, because a function there is always a resolver; a list also accepts the older zero-argument loader form ({ fonts: defaultFonts }), and this is what keeps the two apart.

Returns the same function object, mutated, so the mark survives being passed around and a marked resolver stays === to itself. It does NOT survive .bind() or being wrapped: both make a new function object. Re-mark the result.

ts const brandFonts = defineFontResolver(async ({ families }) => ({ sources: await loadMine(families), }));

Throws a TypeError on a frozen or sealed function, which cannot take the mark. That is deliberate: returning it unmarked would compile — the return TYPE says marked — and then lose every font at runtime.

declare function defineFontResolver<T extends FontResolver>(resolve: T): MarkedFontResolver<T>;

diagnosticCausesfunctionSource ↗

Every engine reason a diagnostic can carry as its cause. Causes are the engine's own reasons and can change between engine versions; match on the public code, and read the cause when you report or fix a failure.

declare function diagnosticCauses(): readonly string[];

diagnosticCodeOfRefusalfunctionSource ↗

The public code for a refused edit. A raw reason the tables do not know, such as a sentence written at one call site, falls back to the exec result code and then to edit.refused. The raw text never leaves this function.

declare function diagnosticCodeOfRefusal(reason: string, execCode?: ExecErrorCode): EditDiagnosticCode;

```ts
const reason = editor.snapshot().lastRejection;
if (reason) console.warn(explainDiagnostic(diagnosticCodeOfRefusal(reason)).hint);
```

diagnosticCodesfunctionSource ↗

Every public code, in declaration order. For coverage tests and catalogs.

declare function diagnosticCodes(): readonly DiagnosticCode[];

diagnosticCommandsfunctionSource ↗

Every built-in command type a diagnostic can name in its command field. A telemetry check uses it to refuse any other value.

declare function diagnosticCommands(): readonly EditorCommand['type'][];

explainDiagnosticfunctionSource ↗

What a diagnostic code means and what to do about it.

declare function explainDiagnostic(code: DiagnosticCode): DiagnosticExplanation;

```ts
editor.on('diagnostic', (event) => {
  if (event.kind === 'edit.rejected') console.warn(explainDiagnostic(event.code).hint);
});
```

initialChromePrintSettingsfunctionSource ↗

The settings a print form starts with: the editor's current display mode, with comments shown, as the PDF converter does by default. All Markup prints comments in a pane beside each page. The other modes print them as PDF annotations on the commented text.

declare function initialChromePrintSettings(snapshot: Pick<EditorSnapshot, 'reviewDisplayMode'> | null | undefined): ResolvedChromePrintSettings;

isChromePrintShortcutfunctionSource ↗

True for the print shortcut: Cmd+P on Apple platforms, Ctrl+P elsewhere. On macOS, Ctrl+P moves the caret to the previous line, so it is not a print shortcut there. The P key matches by code too when it types no Latin letter, as on Cyrillic or Hebrew layouts.

declare function isChromePrintShortcut(event: KeyboardEvent): boolean;

isFontResolverfunctionSource ↗

Whether a value is a function marked by [defineFontResolver](defineFontResolver).

False for an unmarked function, which callers read as a zero-argument loader. Calling a resolver that way reads request.defaultFamily off undefined and throws, so the callers that make this choice say so rather than swallowing it — and the type-level mark on [MarkedFontResolver](MarkedFontResolver) is there to stop it reaching runtime at all.

declare function isFontResolver(value: unknown): value is MarkedFontResolver;

loadFontsfunctionSource ↗

Fetch app-specified font URLs into verified, cache-backed FontSources.

Fetches ONLY the URLs listed — never a default host or engine-chosen CDN — and never rejects for a per-source failure: the result carries every admitted source and a typed entry for every drop. Cancellation instead rejects with signal.reason. Compose the result with composeFontConfiguration.

declare function loadFonts(request: LoadFontsRequest): Promise<LoadFontsResult>;

resolveReviewPanefunctionSource ↗

Merge options over base. Throws a TypeError for an unknown field or value, so a misspelled setting fails loudly instead of being ignored. Returns base itself when nothing changes, so the snapshot keeps its reference.

declare function resolveReviewPane(options: ReviewPaneOptions | undefined, base?: ResolvedReviewPane): ResolvedReviewPane;

resolveRevisionMarkupfunctionSource ↗

Validate and merge preferences without modifying the input.

declare function resolveRevisionMarkup(input?: RevisionMarkupOptions, previous?: ResolvedRevisionMarkup): ResolvedRevisionMarkup;

reviewCodeOfRefusalfunctionSource ↗

The review code a tracked-change refusal leads with, such as retained-structure: ... for a row that stays to keep a nested table, or null when the refusal names no review reason. A card or an Accept All or Reject All that a content control lock or a data binding keeps gives review.locked-content or review.bound-content.

declare function reviewCodeOfRefusal(reason: string): ReviewDiagnosticCode | null;

```ts
const result = editor.exec({ type: 'resolveAllReviewChanges', action: 'reject' });
if (!result.ok) console.warn(reviewCodeOfRefusal(result.reason));
```

reviewCodeOfSkipfunctionSource ↗

The public code for a skipped tracked change, such as an entry of reviewChangesResolved's skipped list: the detail's own code when it has one (review.locked-content, review.bound-content), else the reason's.

declare function reviewCodeOfSkip(skip: {
    readonly reason: string;
    readonly detail?: string;
}): ReviewDiagnosticCode | null;

```ts
editor.on('reviewChangesResolved', ({ skipped }) => {
  for (const skip of skipped) console.warn(reviewCodeOfSkip(skip));
});
```

reviewPaneListsItemfunctionSource ↗

Whether the review pane lists a card for item under revisionsIn.

With 'balloons', a balloon at the text shows every tracked change and every comment that replies to a tracked change, so the pane lists neither. Give the item as an unfiltered getReviewItems() read returns it: a query that excludes revision kinds removes parentRevisionId from replies to the changes it drops.

The engine applies this rule to every review item when it decides whether the pane opens by itself or closes after a settings change. A review pane must apply the same rule before its own filters, such as a hidden kind or a host filter. Those filters can hide every card, and then the pane that the engine opens is empty.

declare function reviewPaneListsItem(revisionsIn: RevisionDisplay, item: ReviewPaneItemFields): boolean;

revisionMarkupColorfunctionSource ↗

CSS token for a validated named color.

declare function revisionMarkupColor(color: RevisionMarkupColor, authorColor: string, auto?: string): string;

revisionMarkupStylefunctionSource ↗

Select the visual style without changing revision identity.

declare function revisionMarkupStyle(settings: ResolvedRevisionMarkup, kind: 'insert' | 'delete' | 'moveFrom' | 'moveTo' | 'format'): RevisionMarkupTextStyle<RevisionDeletionMark>;

runChromeExportfunctionSource ↗

Saves the current document and converts those bytes through the configured handler. Missing handlers fail before saving. Conversion never changes the editor document. settings overrides the captured view for PDF conversion, such as print settings.

declare function runChromeExport(editor: Pick<Editor, 'save'> & Partial<Pick<DocxEditorInstance, 'snapshot' | 'getReviewAuthors'>>, format: ChromeExportFormat, handlers?: ChromeExportHandlers, settings?: ChromePrintSettings): Promise<ChromeExportResult>;

runChromePrintfunctionSource ↗

Saves the current document, converts it with the configured PDF handler, and prepares the result for printing. Uses the same handler and checks as File Export PDF, so a missing handler rejects with ChromeExportError before the document is saved. Saving commits pending form input and can refresh field results with an undo step. container receives the hidden print frame. For an editor inside a modal dialog, pass an element inside that dialog. settings carries the user's print settings, such as the display mode and whether comments print. Omitted settings keep the current view.

declare function runChromePrint(editor: Pick<Editor, 'save'> & Partial<Pick<DocxEditorInstance, 'snapshot' | 'getReviewAuthors'>>, handlers?: ChromeExportHandlers, container?: Document | Element, settings?: ChromePrintSettings): Promise<ChromePrintJob>;

runToolbarCommandfunctionSource ↗

Run a toolbar control: can first, then exec only if it said yes. Returns the engine's refusal untouched when it said no, so a caller cannot mistake a declined command for a no-op.

declare function runToolbarCommand(editor: Editor | null, id: ChromeSlotId): ExecResult;

runToolbarCommandfunctionSource ↗

declare function runToolbarCommand(editor: Editor | null, id: Exclude<ChromeSlotId, ToolbarValueSlot>, options: EditorExecOptions): ExecResult;

runToolbarCommandfunctionSource ↗

declare function runToolbarCommand<K extends keyof ToolbarValueMap>(editor: Editor | null, id: K, value: ToolbarValueMap[NoInfer<K>], options?: EditorExecOptions): ExecResult;

runToolbarCommandfunctionSource ↗

declare function runToolbarCommand(editor: Editor | null, id: TableChromeSlotId, value: unknown, options?: EditorExecOptions): ExecResult;

runToolbarCommandfunctionSource ↗

declare function runToolbarCommand(editor: Editor | null, id: ChromeSlotId, value: undefined, options: EditorExecOptions): ExecResult;

toolbarCommandStatefunctionSource ↗

Ask the engine whether one control should be enabled.

declare function toolbarCommandState(editor: Editor | null, id: ChromeSlotId): ToolbarCommandState;

ChromeExportErrorclassSource ↗

An export has no configured converter.

declare class ChromeExportError extends Error

ChromePrintErrorclassSource ↗

The browser could not print the converted PDF. The PDF at ChromePrintJob.url is still available, so the user can open it and print from the PDF viewer.

declare class ChromePrintError extends Error

EditorFontErrorclassSource ↗

Typed adapter error reported both through onFontError and accessible alert UI.

declare class EditorFontError extends Error

AnchorHighlightAnimationinterfaceSource ↗

Opacity fade settings. Reduced motion limits fades to 125 milliseconds.

interface AnchorHighlightAnimation

AnchorHighlightOptionsinterfaceSource ↗

Presentation for temporary paragraph highlights. Each call starts from these defaults. Document refresh RefreshHighlightOptions extends this type, so one style object serves both.

interface AnchorHighlightOptions

ApplyResultinterfaceSource ↗

What applying a batch of edits produced: the new document, and a per-edit verdict.

results is positionally aligned with the input, so an edit that failed is identified by its index rather than by anything the caller has to correlate.

interface ApplyResult

AttachOptionsinterfaceSource ↗

How [DocxEditorInstance.attach](DocxEditorInstance.attach) moves an open document.

interface AttachOptions

```ts
// Bring the editor home from a pop-out and keep typing there.
editor.attach(mainSlot, { focus: true });
```

AuthoredNoteNumberinginterfaceSource ↗

Authored note-numbering fields as Word's properties dialog writes them.

interface AuthoredNoteNumbering

BlankDocumentOptionsinterfaceSource ↗

How a blank document starts.

interface BlankDocumentOptions

BookmarkChromeHandlersinterfaceSource ↗

Host chrome for bookmarks.

interface BookmarkChromeHandlers

BookmarkMarkInfointerfaceSource ↗

One painted bookmark mark, as BookmarkMarkOptions callbacks see it.

interface BookmarkMarkInfo

BookmarkMarkOptionsinterfaceSource ↗

How Show bookmarks paints its marks. Register with setBookmarkMarks.

interface BookmarkMarkOptions

BookmarkSummaryinterfaceSource ↗

One bookmark, as the bookmarks query lists it.

interface BookmarkSummary

ChromeExportHandlersinterfaceSource ↗

Conversion handlers for File Export. Install the corresponding converter package. Use exportMarkdown for Markdown. PDF requires exportPdf on a Node.js server. Browser hosts supply a PDF handler that calls that server after the user selects Export.

interface ChromeExportHandlers

ChromeExportResultinterfaceSource ↗

Download data from a completed conversion.

interface ChromeExportResult

ChromeExportViewinterfaceSource ↗

Viewer settings captured before PDF conversion.

interface ChromeExportView

ChromeMenuinterfaceSource ↗

One menu of the menu bar.

interface ChromeMenu

ChromeMenuItemEntryinterfaceSource ↗

A row that runs one chrome slot.

interface ChromeMenuItemEntry

ChromeMenuSeparatorEntryinterfaceSource ↗

A horizontal rule between groups of rows.

interface ChromeMenuSeparatorEntry

ChromeMenuSubmenuEntryinterfaceSource ↗

A row that opens a nested panel of rows (Insert › Break).

It carries its own label and icon rather than a slot, because a submenu PARENT has no command: clicking it opens the panel. Giving it a slot would mint a public id for a control that can never be enabled, and toolbarCommandState would have to invent an answer about it.

interface ChromeMenuSubmenuEntry

ChromePrintJobinterfaceSource ↗

A converted PDF, ready for the browser print dialog. Call dispose() when the job ends: it removes the print frame and revokes url.

interface ChromePrintJob

ChromePrintOptionsinterfaceSource ↗

Options for ChromePrintJob.print.

interface ChromePrintOptions

ChromePrintSettingsinterfaceSource ↗

Settings the user picks before printing. Each omitted setting keeps the editor's current view: the review display mode, and comments shown.

interface ChromePrintSettings

ClearAnchorHighlightOptionsinterfaceSource ↗

Explicit highlight dismissal.

interface ClearAnchorHighlightOptions

CollaborationModuleContributioninterfaceSource ↗

What a collaboration module contributes: the replica the surface attaches.

interface CollaborationModuleContribution

CollaborationParticipantsDiagnosticinterfaceSource ↗

The number of people in the collaboration room changed.

interface CollaborationParticipantsDiagnostic extends DiagnosticBase

CollaborationStatusDiagnosticinterfaceSource ↗

A collaboration session changed status: it joined, disconnected, failed, or healed.

interface CollaborationStatusDiagnostic extends DiagnosticBase

CommentDraftChromeHandlersinterfaceSource ↗

Host chrome for comment drafts: the review rail, or the host's own comment UI.

interface CommentDraftChromeHandlers

CommentRecordinterfaceSource ↗

One comment as authored in word/comments.xml.

interface CommentRecord

CompareDocumentsChromeHandlersinterfaceSource ↗

Host rendering for the Compare documents dialog.

interface CompareDocumentsChromeHandlers

CompareDocumentsDialoginterfaceSource ↗

Compare documents dialog supplied by the review module.

interface CompareDocumentsDialog

CompareDocumentsDialogHostinterfaceSource ↗

What the Compare documents dialog may use: its session, mount, and strings.

interface CompareDocumentsDialogHost extends CompareDocumentsDialogSession

CompareDocumentsDialogSessioninterfaceSource ↗

One open Compare documents dialog. The editor owns it: the session aborts when the dialog closes, is replaced, or the document, mount, or editor goes away.

interface CompareDocumentsDialogSession

CompareDocumentsEngineOptionsinterfaceSource ↗

Options of one document compare.

interface CompareDocumentsEngineOptions

CompareDocumentsProgressinterfaceSource ↗

How far a background compare is.

interface CompareDocumentsProgress

CompareDocumentsRequestinterfaceSource ↗

What one compare request carries: the revised DOCX and its options.

interface CompareDocumentsRequest

ComposeFontOriginsOptionsinterfaceSource ↗

Diagnostics hook for ordered font-origin composition.

interface ComposeFontOriginsOptions

ContentControlinterfaceSource ↗

Structured document tag (w:sdt).

interface ContentControl

ContentControlFilterinterfaceSource ↗

Narrows a content-control query. Fields combine with AND; an empty filter matches every control.

interface ContentControlFilter

ContentControlSummaryinterfaceSource ↗

A content control reduced to what a listing needs: its identity, kind, and lock state.

interface ContentControlSummary

ContentControlWidgetChromeHandlersinterfaceSource ↗

Framework rendering for content-control value widgets.

interface ContentControlWidgetChromeHandlers

ContentControlWidgetSessioninterfaceSource ↗

A core-owned content-control value edit.

kind names the widget that was pressed. A checkbox session carries the current state as 'true' / 'false' and expects the opposite (or the same) back through apply; the packaged pop-ups apply the toggle at once, so a host only sees it when it renders the widget itself. A buildingBlockGallery session is a list session: items are the glossary's blocks for the control's gallery, named by w:docPartPr/w:name, and apply takes a name. A picture session carries the control's drawing node id as value and takes new image bytes through replaceImage; apply refuses, since no text stands for an image.

interface ContentControlWidgetSession

ContentLockPolicyinterfaceSource ↗

An opt-in relaxation of ST_Lock for hosts that protect WHAT a control says, not how it looks.

ECMA-376 contentLocked forbids editing the control's contents and Word reads formatting as part of that, which is the default here. A host that puts protected text in a control (a template placeholder the user must not retype) but lets authors style it sets allowFormattingInLockedContent: a run-property write (bold, colour, font, size, highlight …), on runs or on a paragraph mark, then passes the CONTENT half of the lock. The exception never admits a property that hides text (w:vanish, w:specVanish, w:webHidden), which the run-property vocabulary refuses today anyway. Text edits, deletion of the content, paragraph properties, removal of a sdtLocked wrapper and w:dataBinding refusals are unchanged.

interface ContentLockPolicy

ContentTypeIndexinterfaceSource ↗

The resolved lookup: Override by case-folded part name, Default by case-insensitive extension.

interface ContentTypeIndex

CustomFontsOptionsinterfaceSource ↗

Options for loading application fonts when the editor resolves its font configuration.

interface CustomFontsOptions extends Omit<LoadFontsRequest, 'signal'>

CustomNodeDiagnosticEventinterfaceSource ↗

A custom node's stored payload could not be read. The node and its data are not named.

interface CustomNodeDiagnosticEvent extends DiagnosticBase

DiagnosticBaseinterfaceSource ↗

Fields every diagnostic carries.

interface DiagnosticBase

DiagnosticExplanationinterfaceSource ↗

What a diagnostic code means and what to do about it.

Both strings are constants written for developers. They never contain document content, so an exporter can send them with the event.

interface DiagnosticExplanation

DiagnosticFailureDetailinterfaceSource ↗

Anonymous detail of a failure, for the engineer who fixes it. Every field is optional and comes from a closed list: never a part name, an element name, a message, or document text.

interface DiagnosticFailureDetail

DocAnchorinterfaceSource ↗

The LLM- and JSON-facing address for a piece of a document.

paraId is the 8-hex w14:paraId, matched case-insensitively. search is a phrase that must match EXACTLY ONCE inside that paragraph; ambiguous or missing matches fail with 'ambiguous' / 'notFound' rather than falling back to first-match.

Offset-based addressing was tried and abandoned: an agent cannot compute a character offset it has not seen, and offsets do not survive concurrent edits. Do not reintroduce { blockId, offset }.

interface DocAnchor

DocAnchorRangeinterfaceSource ↗

A position in one story: a paragraph and a UTF-16 offset inside it.

The same offset space the ops and the caret use, so an anchor read here can be handed straight back to a selection without re-deriving anything.

interface DocAnchorRange

DocCommentinterfaceSource ↗

One comment or reply, as comments.xml records it.

A reply is a comment with a parentId; OOXML gives replies no separate element, so the thread is reconstructed from that link rather than from nesting.

interface DocComment

DocEditsinterfaceSource ↗

The document-executable edit vocabulary.

An interface rather than a closed union so extensions can widen it by declaration merging. A sealed union cannot be extended by a plugin, and the runtime dispatch is already registry-backed.

interface DocEdits

DocLocationinterfaceSource ↗

Structural addressing for content the paraId map cannot reach.

interface DocLocation

DocQueriesinterfaceSource ↗

The document-readable query vocabulary, keyed identically to [DocQueryResults](DocQueryResults).

An interface rather than a closed union for the same reason [DocEdits](DocEdits) is: an extension widens it by declaration merging, and the runtime dispatch is registry-backed.

interface DocQueries

DocQueryResultsinterfaceSource ↗

What each query returns. Keyed identically to DocQueries.

interface DocQueryResults

DocRangeinterfaceSource ↗

A span between two positions. The endpoints may be addressed either way, independently.

interface DocRange

DocumentBodyinterfaceSource ↗

The main story: its blocks in reading order, plus the sections derived from them.

interface DocumentBody

DocumentChangeinterfaceSource ↗

The payload of the change event / onChange. It carries revision + identity deltas, NOT serialized bytes: serializing a whole DOCX on every keystroke would be prohibitive for large documents. Call save() to get bytes on demand.

interface DocumentChange

DocumentHandleinterfaceSource ↗

An opaque handle to a loaded document — its stable identity and current revision. The canonical authored state is the engine's PackageModel, NOT a simplified tree; advanced automation (DocxEditor.run(handle, …)) addresses a document through this handle rather than a serialized structure. Kept deliberately minimal and open so it can carry more identity later without a breaking change.

interface DocumentHandle

DocumentOpenFailureinterfaceSource ↗

A document the editor refused to open. It carries a stable code only, never the file's content or name, so a host can show it, log it, or send it with a support request.

Each refusal is a new object, so a host can compare it by reference to tell a second refusal of the same file from the first.

interface DocumentOpenFailure

DocumentProtectionStateinterfaceSource ↗

The document's protection, as the file states it.

interface DocumentProtectionState

DocumentShapeinterfaceSource ↗

The bucketed shape of an opened document.

interface DocumentShape

DocxDocumentinterfaceSource ↗

A parsed .docx.

NOT JSON-round-trippable: it holds Maps and Dates, plus an internal side-table of verbatim XML used for lossless round-tripping. Use toJSON / fromJSON before sending it over JSON-RPC or handing it to a model.

interface DocxDocument

DocxDocumentJSONinterfaceSource ↗

The JSON-safe projection of a document.

interface DocxDocumentJSON

DocxEditorConfiginterfaceSource ↗

Everything [createDocxEditor](createDocxEditor) accepts. Every field is optional.

container is the one that changes the shape of the whole lifecycle: omitting it produces an instance that does no DOM work until attach(el), which is what lets a provider own the editor before any component has rendered a mount point.

interface DocxEditorConfig

DocxEditorInstanceinterfaceSource ↗

The concrete facade type: the full Editor contract plus the instance-only surface.

surface, stateVersion, attach and detach live HERE rather than on Editor: they are what a store binding and a mounting host need, not what document commands need. Production adapters program against Editor for everything else.

interface DocxEditorInstance extends Editor

DrawingLocksinterfaceSource ↗

What a drawing refuses: selection, movement, resizing, aspect change.

Read and honoured rather than advisory — chrome that offered a handle the store will refuse would promise an edit that cannot happen.

interface DrawingLocks

DrawingPositionInputinterfaceSource ↗

An anchored drawing's position: offsets, and the frames they are relative to.

The relative-to bases matter as much as the offsets. Writing an offset without preserving its base re-anchors the drawing against a different reference and moves it somewhere nobody asked.

interface DrawingPositionInput

EditorinterfaceSource ↗

The engine's whole public surface: load and save, execute and query, observe and subscribe.

Commands go through can before exec — the same check chrome uses to decide whether a control is enabled, so a button and the engine never disagree about what is possible.

snapshot() is version-cached: the same reference until state actually moves, with reference-stable sub-objects, which is what makes it safe as a useSyncExternalStore source.

interface Editor extends EditorAnchorNavigation, EditorHighlights, EditorReviewHits

```ts
const editor = createDocxEditor({ container });
editor.load(bytes);
if (editor.can({ type: 'toggleBold' }).ok) editor.exec({ type: 'toggleBold' });
const bytesOut = await editor.save();
```

EditorAnchorNavigationinterfaceSource ↗

Navigation and temporary highlights for external paragraph references.

interface EditorAnchorNavigation

EditorBookmarkCommandsinterfaceSource ↗

The bookmark commands an editor accepts.

interface EditorBookmarkCommands

EditorCommandsinterfaceSource ↗

Every command the editor accepts, keyed by name with its payload as the value.

Extends the document-level [DocEdits](DocEdits) vocabulary with the things only a LIVE editor has: selection, view state, chrome modes, header/footer and note editing. An interface rather than a closed union so an extension can widen it by declaration merging.

interface EditorCommands extends EditorCommandShape<DocEdits>, EditorHeaderFooterCommands, EditorNoteCommands, EditorFormatPainterCommands, EditorBookmarkCommands

EditorErrorinterfaceSource ↗

An error the engine raised, carrying a machine-readable code alongside the message.

code is optional because an Error from deeper down (a parser, a codec) is surfaced as-is rather than wrapped in a fabricated code. The editor's own codes: invalidTarget (attach cannot mount there), unsupported (a source it refuses to open), and hostCallback (a host callback such as a bookmark mark's decorate threw; the editor kept its default behavior).

interface EditorError extends Error

EditorEventsinterfaceSource ↗

What editor.on(...) can be subscribed to, and what each handler receives.

These are PUSH notifications and are not interchangeable with reading snapshot(): a snapshot read cannot observe an event that was never emitted, which is why adapter behaviour is asserted against these rather than against the snapshot.

interface EditorEvents

EditorExecOptionsinterfaceSource ↗

Options for a command's editing view and explicit gesture.

interface EditorExecOptions extends HistoryGroupOptions

EditorFormatPainterCommandsinterfaceSource ↗

Word's Format Painter, as the two halves a keyboard user drives separately.

The pair is deliberately NOT one command with a direction flag: copyFormatting reads and pasteFormatting writes, so they answer can differently — copying is allowed on a document open for viewing, and applying is not.

interface EditorFormatPainterCommands

EditorHeaderFooterCommandsinterfaceSource ↗

Header/footer lifecycle and page-field commands on [EditorCommands](EditorCommands).

Kept as a mixin so editor.ts can extend it without inlining the furniture vocabulary.

interface EditorHeaderFooterCommands

EditorHighlightsinterfaceSource ↗

Paint-only text highlights: search results, glossary terms, review findings.

Highlights are view state. They never change the document, selection, focus, or undo history, they are never saved, and they are not shared with collaborators.

interface EditorHighlights

EditorHostChangeinterfaceSource ↗

The payload of the hostChange event.

interface EditorHostChange

EditorModuleinterfaceSource ↗

One registered capability module. Registration is construction-time (createDocxEditor({ modules })) and immutable for the instance's lifetime.

interface EditorModule

EditorNoteCommandsinterfaceSource ↗

Footnote/endnote lifecycle and properties commands on [EditorCommands](EditorCommands).

interface EditorNoteCommands

EditorQueriesinterfaceSource ↗

Every query the editor answers, keyed by name with its arguments as the value.

Extends [DocQueries](DocQueries) with the reads that only mean something against a live, laid-out document: the selection, its formatting, the table or hyperlink under the caret.

interface EditorQueries extends DocQueries

EditorQueryResultsinterfaceSource ↗

What each editor query returns. Keyed identically to EditorQueries.

interface EditorQueryResults extends DocQueryResults

EditorReviewHitsinterfaceSource ↗

Hit testing for hosts that draw their own review chrome.

interface EditorReviewHits

EditorSnapshotinterfaceSource ↗

A read model of the current editor state, safe to hand to framework rendering. Named EditorSnapshot rather than EditorState so it never collides with an editing engine's own state type.

interface EditorSnapshot

EditRejectedDiagnosticinterfaceSource ↗

An edit, a command or a tracked change was refused.

interface EditRejectedDiagnostic extends DiagnosticBase, DiagnosticFailureDetail

EquationActivationinterfaceSource ↗

A user click on one painted equation.

interface EquationActivation

EquationChromeHandlersinterfaceSource ↗

Host chrome that edits a clicked Office Math equation.

interface EquationChromeHandlers

ExtentinterfaceSource ↗

A size in EMUs, the unit DrawingML stores extents in. 914400 EMU = 1 inch.

interface Extent

FontConfigurationinterfaceSource ↗

Public font source configuration sampled when an adapter mounts. It must be immutable for that editor lifetime; remount the adapter to replace bytes or substitutions atomically.

interface FontConfiguration

FontConfigurationBaseinterfaceSource ↗

The base of a composition: everything a FontConfiguration carries, all optional. Omitted fields take the documented defaults (epoch 0, maxFontBytes at the engine hard maximum, defaultFont Calibri at 11pt — Word's own default face and size).

interface FontConfigurationBase extends FontConfigurationFragment

FontConfigurationFragmentinterfaceSource ↗

A partial font configuration one origin contributes: sources, substitutions, or both. loadDefaultFonts() (the substitute package) and loadFonts() (the fetch helper) both return this shape, so every origin composes through composeFontConfiguration the same way.

interface FontConfigurationFragment

FontDefinitioninterfaceSource ↗

A font the document names, and whether its bytes travel inside the package.

interface FontDefinition

FontFaceRequestinterfaceSource ↗

A concrete font face requested by authored document content.

interface FontFaceRequest

FontFailedDiagnosticinterfaceSource ↗

A font failed to load. The editor kept working with a substitute.

interface FontFailedDiagnostic extends DiagnosticBase

FontLoadFailureinterfaceSource ↗

One face that did not load, with whatever evidence the failure produced.

Non-fatal: [LoadFontsResult](LoadFontsResult) still carries every source that succeeded, and the affected family falls back to the engine's fixed measurement.

interface FontLoadFailure

FontMeasurementStateinterfaceSource ↗

Which measurer the current document's layout runs on, and whether shaped resolution is still in flight. Returned by [DocxEditorInstance.fontMeasurement](DocxEditorInstance.fontMeasurement).

interface FontMeasurementState

FontOriginFailureinterfaceSource ↗

A failed font origin or a partial failure in an otherwise usable fragment.

interface FontOriginFailure

FontResolutionRequestinterfaceSource ↗

What the document turned out to need, handed to an on-demand resolver.

The families are the ones the file actually names — already name-validated and capped, so a resolver may treat them as a list to look up, never as URLs or paths to build.

interface FontResolutionRequest

FontResolverMarkinterfaceSource ↗

The type-level half of the mark: what [defineFontResolver](defineFontResolver) adds to a function's type so a FontOrigin list can REQUIRE it.

Declared with a string key so @docx-editor.dev/fonts can declare an identical interface and have the two unify without importing anything from the engine. Set at runtime as well as in the type — non-enumerable, so it stays out of Object.keys and out of a host's own spread.

interface FontResolverMark

FontShapingOptionsinterfaceSource ↗

Host-selected execution limits, separate from font admission limits.

interface FontShapingOptions

FontSourceinterfaceSource ↗

Immutable, byte-backed font face supplied to layout and browser paint.

interface FontSource

FontSourceSubstitutioninterfaceSource ↗

An explicit authored-font substitution. No implicit platform fallback is performed.

interface FontSourceSubstitution

FontUrlSourceinterfaceSource ↗

One URL to fetch and the face it claims to be.

interface FontUrlSource

FormatPainterSurfaceStateinterfaceSource ↗

Painter state, as the editor publishes it.

Chrome state rather than document state, so it moves through the same report every other observable surface state uses — a toolbar's pressed state has one source. It lives in the CONTRACTS lane rather than beside the surface implementation because EditorSnapshot names it, and the contracts lane may not reach into the editor lane.

interface FormatPainterSurfaceState

GoToChromeHandlersinterfaceSource ↗

Host chrome for Go To: the Go to tab of DocxEditor.Navigation, or the host's own.

interface GoToChromeHandlers

HeaderFooterSetinterfaceSource ↗

A section's three header (or footer) variants, each a relationship id.

All optional: a variant a section does not declare inherits the previous section's, and one absent everywhere means the document simply has none.

interface HeaderFooterSet

HeaderFooterSlotArgsinterfaceSource ↗

Optional slot targeting shared by remove / link / unlink furniture commands.

interface HeaderFooterSlotArgs

HeaderFooterStateinterfaceSource ↗

Header/footer editing state: which region is being edited, if any.

interface HeaderFooterState

HighlightHitinterfaceSource ↗

One painted mark under a point. R is your range type: pass ranges with extra fields, such as a glossary definition, and read them back from range.

interface HighlightHit<R extends HighlightRange = HighlightRange>

HighlightOptionsinterfaceSource ↗

Presentation for one named highlight set. Every field is optional.

interface HighlightOptions

HighlightRangeinterfaceSource ↗

One text range to mark. A TextMatch from findMatches() is a valid range, so search results pass straight through.

interface HighlightRange

HighlightRectinterfaceSource ↗

A client-space rectangle, compatible with DOMRect readers such as positioning libraries.

interface HighlightRect

HighlightResultinterfaceSource ↗

What setHighlights() resolved against the open document.

interface HighlightResult

HistoryDiagnosticinterfaceSource ↗

Optional diagnostic notification; subscribing does not change history behavior.

interface HistoryDiagnostic

HistoryDiagnosticEventinterfaceSource ↗

The undo history did not group edits as the gesture intended. Informational.

interface HistoryDiagnosticEvent extends DiagnosticBase

HistoryGroupinterfaceSource ↗

interface HistoryGroup

HistoryGroupBindinginterfaceSource ↗

Dispose when the element or editor changes.

interface HistoryGroupBinding

HistoryGroupBindingOptionsinterfaceSource ↗

Native event policy for one continuous control gesture.

interface HistoryGroupBindingOptions

HistoryGroupOptionsinterfaceSource ↗

Options for a review write that can join an explicit history group.

Every write that names one open handle becomes part of one undo step, across commands, review methods, and browser automation runs. A closed handle, or a handle from another editor, refuses the write with code: 'unsupported' and changes nothing.

interface HistoryGroupOptions

```ts
const decision = editor.beginHistoryGroup();
// Reply first: the card's key no longer exists after the change is accepted.
const reply = editor.replyToReviewItem(key, 'Accepted with one change.', {
  historyGroup: decision,
});
const accepted = editor.acceptReviewItem(key, { historyGroup: decision });
decision.end();
if (!reply.ok || !accepted.ok) throw new Error('the review card was refused');
editor.exec({ type: 'undo' }); // reverts both writes
```

HistoryGroupOutcomeinterfaceSource ↗

The history authority's result for this frame.

interface HistoryGroupOutcome

HyperlinkActivationinterfaceSource ↗

A click on a painted link, after native navigation was refused.

interface HyperlinkActivation

HyperlinkChromeHandlersinterfaceSource ↗

The host chrome that answers the engine's hyperlink gestures.

A CLICK on an external link and Ctrl/Cmd+K both mean "the user wants the link UI", and the engine deliberately does not know what that looks like. Registered rather than passed at construction because the chrome mounts after the editor does, and it survives a document reload — the surface is rebuilt, the handlers are not.

interface HyperlinkChromeHandlers

HyperlinkInfointerfaceSource ↗

The hyperlink under a position: where it points, how far it reaches, and what Word shows on hover.

href has already been through sanitizeHref — it comes from a file, so a javascript: or data: target is dropped at the parse boundary rather than here.

interface HyperlinkInfo

ImageCropPercentinterfaceSource ↗

Crop edge in UI percent (0–100).

interface ImageCropPercent

ImageDecodePortinterfaceSource ↗

The injected image decoder.

A port rather than a direct Image/createImageBitmap call, so a worker or server runtime supplies its own and the engine never reaches for a browser global.

interface ImageDecodePort

ImageResourceLimitsinterfaceSource ↗

Trust-boundary caps specific to image decoding and embedding.

interface ImageResourceLimits

IndentFormattinginterfaceSource ↗

Indent at the selection, in twips.

Unlike every other field here, this does NOT go absent when the selection's paragraphs disagree. A ruler has to draw its handles somewhere, and Word draws them at the FIRST selected paragraph's values — Select All is the commonest indent gesture, and hiding the handles for it would be worse than showing one paragraph's truth. The values are therefore always the first touched paragraph's, and [mixed](mixed) records per field whether the rest agree.

firstLine is ONE SIGNED offset: negative is a hanging indent. OOXML spells it as two mutually exclusive attributes and this collapses them hanging-wins (§17.3.1.12), which is the model Word itself keeps.

Absent inside a table. The value would be correct there, but it is measured from the cell's content edge while a ruler is drawn against the page's margin, and the ruler does not know the cell.

interface IndentFormatting

InvalidTextFormFieldChromeHandlersinterfaceSource ↗

Framework rendering for invalid protected-field acknowledgements.

interface InvalidTextFormFieldChromeHandlers

InvalidTextFormFieldSessioninterfaceSource ↗

An invalid protected-field acknowledgement.

interface InvalidTextFormFieldSession

LoadFontsRequestinterfaceSource ↗

What to fetch, and under what limits.

Only sources is required. Each carries its own expected hash, so bytes are trusted by CONTENT rather than by origin — a swapped asset fails admission even from a trusted host.

interface LoadFontsRequest

LoadFontsResultinterfaceSource ↗

What one loadFonts call produced: the faces that arrived, plus the ones that did not.

A FontConfigurationFragment, so it composes straight into composeFontConfiguration alongside other font sources. Partial success is the normal case — compose it even with failures present.

interface LoadFontsResult extends FontConfigurationFragment

NotePropertiesSideinterfaceSource ↗

One note kind's resolved + authored properties for the caret section.

interface NotePropertiesSide

NotePropertiesStateinterfaceSource ↗

Resolved and authored note properties for the caret section — properties dialog read-model.

interface NotePropertiesState

NumberingRefinterfaceSource ↗

A paragraph's list membership: which numbering.xml definition, and at which level.

interface NumberingRef

OoxmlExternalTargetinterfaceSource ↗

An external relationship target. Retained verbatim as authored evidence, with the sink-safety verdict alongside it. Never resolved against the package, never fetched.

interface OoxmlExternalTarget

OoxmlPackageinterfaceSource ↗

A loaded package: every XML part as a canonical tree, plus the non-XML parts kept verbatim.

The preservation model in one value. Modelled parts re-emit normalized; everything else is byte-identical, which is why an unrecognized part never costs a document anything.

interface OoxmlPackage

PageMarginsinterfaceSource ↗

Page margins in twips.

interface PageMargins

PageSetupinterfaceSource ↗

Section page setup — size, orientation and margins, in twips — as getPageSetup() and snapshot().pageSetup report it and the setPageSetup command writes it. In a multi-section document this is the setup of the section the SELECTION is in, which is what a ruler or a dialog reflects — Word's behaviour.

interface PageSetup

ParagraphinterfaceSource ↗

One paragraph: its runs, the style it names, and its list membership.

interface Paragraph

ParagraphDisagreementsinterfaceSource ↗

Which paragraph-level reads the selection disagrees about.

interface ParagraphDisagreements

ParagraphFlagsinterfaceSource ↗

The five paragraph flags a Paragraph dialog shows as checkboxes.

contextualSpacing is Word's "Don't add space between paragraphs of the same style"; the rest are its Pagination block. null means the selection disagrees.

interface ParagraphFlags

ParagraphFormatCommandinterfaceSource ↗

Every field of the Paragraph dialog, as setParagraphFormat takes it.

An omitted field is left as authored. null REMOVES a setting so the style supplies it again — not the same as a zero, which blocks the cascade.

interface ParagraphFormatCommand

ParagraphSummaryinterfaceSource ↗

A paragraph reduced to what a listing needs: its stable handle, its text, and its style.

paraId is what a follow-up edit addresses, so a summary without one names a paragraph the file gave no w14:paraId and that a DocAnchor cannot reach.

interface ParagraphSummary

ParagraphTabStopinterfaceSource ↗

One custom tab stop, as a command states it.

interface ParagraphTabStop

PerformanceDiagnosticinterfaceSource ↗

How the editor performed while it was used: one summary per window, never one event per key press. Sent after a minute of use, when the page is hidden, and when the editor is destroyed, if anything was measured since the last summary.

interface PerformanceDiagnostic extends DiagnosticBase

PointinterfaceSource ↗

A position in points.

interface Point

PopupChromeRegistrationOptionsinterfaceSource ↗

Priority of an editor-owned popup renderer.

interface PopupChromeRegistrationOptions

RectinterfaceSource ↗

An axis-aligned rectangle in points, the unit layout works in throughout.

interface Rect

RelationshipRecordinterfaceSource ↗

One authored relationship, with nothing materialized away: owner part, id, type, raw target lexical form, mode, and position.

interface RelationshipRecord

ResolvedNoteNumberinginterfaceSource ↗

Resolved note-numbering fields for one section. Numbering and the footnote position come from the section's own properties and the defaults; the endnote position comes from the document settings.

interface ResolvedNoteNumbering