@docx-editor.dev/core/editor

alignmentAfterDirectionChangefunctionSource ↗

The physical alignment a paragraph shows after its direction flips, with its stored w:jc unchanged: leading and trailing edges trade sides. A dialog applies this to its Alignment field when Direction changes, so the field shows what OK will produce, the same result as the toolbar's direction buttons.

declare function alignmentAfterDirectionChange(alignment: ParagraphDialogFields['alignment']): ParagraphDialogFields['alignment'];

applyTableChromePickfunctionSource ↗

Build the engine command for one table chrome pick and the draft state after it. Target picks apply the current complete spec; none clears the active target only.

declare function applyTableChromePick(draft: TableChromeDraft, slot: TableChromeSlotId, value: unknown): TableChromePick | null;

applyThemeShadefunctionSource ↗

Blend toward black. keep is the fraction of the base colour retained (OOXML themeShade byte).

declare function applyThemeShade(hex: string, keep: number): string;

applyThemeTintfunctionSource ↗

Blend toward white. keep is the fraction of the base colour retained (OOXML themeTint byte).

declare function applyThemeTint(hex: string, keep: number): string;

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;

bookmarkDialogInitialNamefunctionSource ↗

The name the dialog starts with: the visible bookmark the selection is in, or an empty name.

declare function bookmarkDialogInitialName(bookmarks: readonly BookmarkSummary[]): string;

bookmarkDialogNameStatefunctionSource ↗

Evaluate the name typed in the Bookmark dialog against the document's bookmarks. writable is whether the document accepts edits; Go To works either way.

declare function bookmarkDialogNameState(bookmarks: readonly BookmarkSummary[], name: string, writable: boolean): BookmarkDialogNameState;

bookmarkDialogRowsfunctionSource ↗

The bookmarks the dialog lists. Hidden bookmarks show only when asked for. Names sort without case and with numbers in order, and location sorts by document order.

declare function bookmarkDialogRows(bookmarks: readonly BookmarkSummary[], options: {
    readonly sortBy: BookmarkSortOrder;
    readonly showHidden: boolean;
}): readonly BookmarkSummary[];

calendarDateForKeyfunctionSource ↗

Calendar keyboard destination. Shift+PageUp/PageDown moves one year.

declare function calendarDateForKey(iso: string, key: string, locale?: string, shift?: boolean): string | null;

calendarDateFromTextfunctionSource ↗

Parse a complete ISO or regional numeric date; ambiguous two-digit years are refused.

declare function calendarDateFromText(text: string, locale?: string): string | null;

calendarDateTextfunctionSource ↗

Format an ISO date for numeric entry in the editor locale.

declare function calendarDateText(iso: string, locale?: string): string;

calendarMonthfunctionSource ↗

Build the six-week grid for one month.

Bounded by construction: 42 cells whatever the month, and every value is derived from the year and month numbers, never from document text.

declare function calendarMonth(year: number, month: number, options?: CalendarMonthOptions): CalendarMonth;

calendarMonthNamesfunctionSource ↗

The twelve Gregorian month names for a month selector.

declare function calendarMonthNames(locale?: string): readonly string[];

calendarMonthTitlefunctionSource ↗

Month-and-year title for a grid, formatted in the calendar locale.

declare function calendarMonthTitle(year: number, month: number, locale?: string): string;

calendarWeekdaysfunctionSource ↗

Seven weekday labels starting on the locale's first weekday.

declare function calendarWeekdays(locale?: string): readonly string[];

canExecuteImageCommandfunctionSource ↗

Whether an insert or replace would be accepted — the can half of the can-before-exec pair.

Refuses in suggesting mode, since an image property edit has no tracked-change representation.

declare function canExecuteImageCommand(command: Extract<EditorCommand, {
    type: 'insertImage' | 'replaceImage';
}>, surface: PaginatedSurface | null): CanResult;

captureImageMutationPreconditionsfunctionSource ↗

Snapshot the state an image mutation was planned against: mount generation, package revision, and the selection anchor.

Taken at the START of a drag so the commit can be checked against it with [isStaleImageInteractionCommit](isStaleImageInteractionCommit). A pointer gesture spans many frames, and a document that moved underneath it must not have the gesture's final coordinates applied to it.

declare function captureImageMutationPreconditions(editor: Pick<DocxEditorInstance, 'surface' | 'mountGeneration'>): ImageMutationPreconditions | null;

changedFieldsfunctionSource ↗

The submission: ONLY the fields that moved since the dialog opened.

Sending the whole form would flatten every setting the selection disagrees about. A mixed keepNext would become off on every paragraph, and a mixed left indent would become an explicit zero — which is worse than wrong, because a zero BLOCKS the style cascade where leaving the setting alone would let the style keep supplying it. An untouched field is not a decision, so it is not written.

Returns null when nothing moved, which the caller treats as "just close": an empty write would still push an undo entry that restores nothing.

declare function changedFields(seed: ParagraphDialogFields, current: ParagraphDialogFields, 
seedMixed?: ParagraphDialogMixed, 
currentMixed?: ParagraphDialogMixed): ParagraphFormatUpdate | null;

chromeControlCountfunctionSource ↗

Total controls, so a parity test can assert none were dropped.

declare function chromeControlCount(): number;

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

chromeProbeForSlotfunctionSource ↗

The probe a slot uses to ask "would the engine honour this right now?" when its real command needs an argument the slot itself cannot supply.

text.link is the case: whether this selection could become a link is the engine's question, but WHICH link is a URL field's. toolbarCommandState answers the slot from this probe and from whether a link UI is registered, and runToolbarCommand opens that UI, so chrome reads the slot like any other.

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

chromeSlotIdfunctionSource ↗

The slot id of one control within its group. Only meaningful for entries of CHROME_GROUPS — the cast is sound because every group/control pair in the registry is, by construction, a member of the ChromeSlotId union.

declare function chromeSlotId(group: {
    readonly id: string;
}, control: {
    readonly id: string;
}): ChromeSlotId;

chromeSlotIsTogglefunctionSource ↗

Whether a slot's control renders as a TOGGLE — pressed or not — so it carries aria-pressed.

Shared rather than derived per adapter, because it is not derivable from the command table alone: the format painter has no fixed command (a press captures, arms, locks or stands down, which no single EditorCommand describes), so a rule that only read commandForSlot left it announcing nothing at all to a screen reader while it was armed.

declare function chromeSlotIsToggle(slotId: ChromeSlotId): boolean;

commandExecOptionsfunctionSource ↗

Ignore framework events passed to a command used directly as an event handler.

declare function commandExecOptions(value: unknown): EditorExecOptions | undefined;

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;

commandForTableChromeSlotValuefunctionSource ↗

Build an engine command for one table chrome slot using the caller's draft state.

declare function commandForTableChromeSlotValue(slotId: TableChromeSlotId, value: unknown, draft: TableChromeDraft): 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>;

computeImageResizeResultfunctionSource ↗

Resolve one resize frame from the pointer's current position.

Handles rotation and flips by mapping the SCREEN-space handle back to the drawing's local axes first: dragging the visually-right handle of a 90°-rotated image must change its stored height, and a flipped image's handles move in the opposite direction from where they appear.

declare function computeImageResizeResult(options: {
    readonly handle: ImageResizeHandle;
    readonly startWidthEmu: number;
    readonly startHeightEmu: number;
    readonly startBounds: {
        readonly x: number;
        readonly y: number;
        readonly width: number;
        readonly height: number;
    };
    readonly startPosition: DrawingPositionInput | null;
    readonly anchorFrameOrigin?: AnchorFrameOrigin | null;
    readonly deltaXPt: number;
    readonly deltaYPt: number;
    readonly transform: DrawingTransform;
    readonly preserveAspect: boolean;
    readonly kind: 'inline' | 'anchored';
}): ImageResizeResult;

computeMovedImagePositionfunctionSource ↗

The position a move drag produces, preserving the anchoring the file already used.

A frame-mode position keeps its relativeToH/relativeToV bases and only shifts the offsets it actually had — writing an offset the file omitted would re-anchor the drawing to a different reference and move it somewhere the drag never pointed.

declare function computeMovedImagePosition(start: DrawingPositionInput, deltaXPt: number, deltaYPt: number): DrawingPositionInput;

computeResizedImageExtentEmufunctionSource ↗

The extent a resize drag produces, in EMU.

Computed from the drag's START extent rather than the previous frame's, so a drag that reverses direction lands exactly where it began instead of accumulating rounding error.

preserveAspect behaves the way Word's handles do: a corner handle scales by whichever axis moved further, while an edge handle drives the other axis from the original ratio. Both axes are floored at one point, so a drag past the opposite edge cannot invert the image.

declare function computeResizedImageExtentEmu(startWidthEmu: number, startHeightEmu: number, handle: ImageResizeHandle, deltaWidthPt: number, deltaHeightPt: number, preserveAspect: boolean): {
    readonly cx: number;
    readonly cy: number;
};

contentControlPopupKeyDownfunctionSource ↗

Keep keyboard input inside a popup; Escape cancels and Tab wraps visible controls.

declare function contentControlPopupKeyDown(panel: HTMLElement, event: KeyboardEvent, cancel: () => void): void;

contentControlPopupOpenerfunctionSource ↗

Capture a popup's opener, with the editable pages as fallback when no control had focus.

declare function contentControlPopupOpener(anchor: HTMLElement | null): HTMLElement | null;

copyEditorStylesfunctionSource ↗

Copy every stylesheet of from into to, and keep copying the ones from adds later.

Covers <link rel="stylesheet"> and <style> elements added, changed or removed at any time; rules inserted into a same-origin <style> through the CSSOM (CSS-in-JS libraries in production), checked every 250 ms on the pop-out's own clock while it is open; constructed adoptedStyleSheets, checked the same way; and the theme attributes on <html> such as class and data-theme. Rules inserted into a <link> sheet, or any sheet of another origin, are not copied. Returns a function that stops the mirroring.

declare function copyEditorStyles(from: Document, to: Document): () => void;

```ts
const stop = copyEditorStyles(document, popup.document);
// Later, when the pop-out closes:
stop();
```

createBrowserAutomationHostfunctionSource ↗

An automation host over a live editor.

The editor keeps its own lifetime: dispose() on the returned host releases the change subscription this adapter took and leaves the editor mounted and editable.

save() validates pending form input. Invalid values and saves during an active edit return transaction-refused. For autosaving from change callbacks, use the asynchronous editor.save(), which waits for the active edit to finish.

declare function createBrowserAutomationHost(editor: DocxEditorInstance): BrowserAutomationHost;

createContentControlListNavigationfunctionSource ↗

Create bounded, locale-aware typeahead and roving focus for a popup's options.

declare function createContentControlListNavigation(locale?: string): ContentControlListNavigation;

createDocumentRefreshfunctionSource ↗

Get the engine-owned controller for updated DOCX files. React and Vue use the same controller. Transport and processor jobs belong to your application. This is a host API, not an Office.js document member.

declare function createDocumentRefresh(editor: DocxEditorInstance): DocumentRefresh;

createDocumentSearchfunctionSource ↗

The shared search session of an editor. Every call for the same editor returns the same session, so the Find pane and your code read and drive one search.

declare function createDocumentSearch(editor: Editor): DocumentSearch;

```ts
const search = createDocumentSearch(editor);
const stop = search.showHighlights('all');
search.find('Supplier', { wholeWord: true });
search.next();
```

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

createImageOverlayScrollPortfunctionSource ↗

An [ImageOverlayScrollPort](ImageOverlayScrollPort) over a real scroll container.

Reports the delta the element ACTUALLY scrolled, converted back to points — at the end of the document that is less than asked for, and the overlay must not move the image further than the page travelled.

declare function createImageOverlayScrollPort(scroller: HTMLElement, paintScale: number): {
    scrollBy(deltaYPoints: number): number;
};

createLayoutShapingfunctionSource ↗

declare function createLayoutShaping(configuration: FontConfiguration, instrumentation?: LayoutShapingInstrumentation, execution?: FontShapingOptions): Promise<LayoutShapingOptions>;

cropPercentFromCropPermillefunctionSource ↗

Permille crop → UI percent.

declare function cropPercentFromCropPermille(crop: ImageCropPermille): ImageCropPercent;

cropPercentFromPermillefunctionSource ↗

OOXML permille → UI percent.

declare function cropPercentFromPermille(permille: number): number;

cropPercentFromSourceCropfunctionSource ↗

Projection fraction (0–1) → UI percent (0–100).

declare function cropPercentFromSourceCrop(crop: SourceCrop): ImageCropPercent;

cropPermilleFromCropPercentfunctionSource ↗

UI percent crop → permille for tree ops / a:srcRect.

declare function cropPermilleFromCropPercent(crop: ImageCropPercent): ImageCropPermille;

cropPermilleFromPercentfunctionSource ↗

UI percent → OOXML permille.

declare function cropPermilleFromPercent(percent: number): number;

cssPixelsToLayoutPointsfunctionSource ↗

CSS pixels back to layout points — what a pointer event's coordinates must go through.

declare function cssPixelsToLayoutPoints(pixels: number, paintScale: number): number;

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;

defaultChromeGroupsfunctionSource ↗

The groups of the DEFAULT toolbar arrangement, in bar order: every group that is not contextual. This is the registry's default bar — undo/redo through the editing-mode picker — and what both adapters render when the host composes nothing. Contextual slots (image.*, table.insert, file.save) remain available for explicit composition.

declare function defaultChromeGroups(): readonly ChromeGroup[];

defaultTableLabelfunctionSource ↗

The English label for a furniture-insertion control.

The FALLBACK, for a host that has not wired its own translator — adapters pass their useTranslation result instead so the control follows the app's locale.

declare function defaultTableLabel(key: TableInteractionLabelKey): string;

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

disposeLayoutShapingfunctionSource ↗

Release native resources held by a shaping environment.

declare function disposeLayoutShaping(shaping: LayoutShapingOptions): void;

dragIndentfunctionSource ↗

The indent a drag of handle to positionTwips produces.

Clamps differ from the MARGIN drags this ruler also carries, and deliberately:

- Indents may go NEGATIVE, pulling text into the margin, which Word allows. The floor is the sheet edge, not the margin. - There is no minimum text width. The 720-twip floor the margin drags use mirrors an engine refusal that does not exist for indents, and enforcing one here would make a narrow pull-quote unreachable. Left and right markers may MEET; they may not cross. - The left box needs a first-line clamp of its own. It does not move firstLine, so on a hanging paragraph dragging the box left can push the first-line marker off the sheet while the box itself is still in range. The drag stops when the LEADING marker lands.

declare function dragIndent(handle: RulerIndentHandle, positionTwips: number, indent: RulerIndent, page: RulerPageMetrics, options?: RulerDragOptions): RulerIndent;

drawingPreviewDocxfunctionSource ↗

A small DOCX that holds one drawing from the editor's current document, including unsaved edits, for an external renderer. It equals createDrawingPreviewPackage on the document as a save would write it now; see that function for the page and renderer rules.

Pass an occurrence that an UnsupportedElement component receives, and the editor from useDocxEditor(), returning early on null. The call is synchronous and serializes the drawing's parts: make it in an effect keyed on element.source, not during render, and spread out or queue the calls when there are many drawings. By default a package copies at most 64 parts and 64 MiB; pass limits to change that.

declare function drawingPreviewDocx(editor: DocxEditorInstance, element: Pick<UnsupportedElement, 'ownerPartName' | 'nodeId'>, limits?: DrawingPreviewPackageLimits): DrawingPreviewPackageResult;

editorHostDocumentfunctionSource ↗

The document editor is mounted in: a pop-out window's or an iframe's when it is attached there. While the editor is detached, the script's own document.

Use it in custom chrome that is not inside the editor's own DOM, such as a toolbar popover, to add document listeners and to read focus.

declare function editorHostDocument(editor: Editor): Document;

```ts
const doc = editorHostDocument(editor);
doc.addEventListener('keydown', onShortcut);
```

editorHostElementfunctionSource ↗

The element editor is mounted in, or null while it is detached or headless.

Use it to tell which editor an event belongs to when several share a window.

declare function editorHostElement(editor: Editor): Element | null;

```ts
const mine = editorHostElement(editor)?.contains(event.target as Node) ?? false;
```

editorHostWindowfunctionSource ↗

The window editor is mounted in: its timers, frames, viewport size and clipboard. While the editor is detached, the script's own window.

declare function editorHostWindow(editor: Editor): HostWindow;

```ts
const win = editorHostWindow(editor);
await win.navigator.clipboard.writeText(text);
```

emuToOverlayPointsfunctionSource ↗

EMU to points. Unrounded, so overlay geometry keeps sub-point precision during a drag.

declare function emuToOverlayPoints(emu: number): number;

equationAtPositionfunctionSource ↗

Boundary-inclusive lookup, matching the hyperlink and field atom popovers.

declare function equationAtPosition(equations: readonly SurfaceEquation[], position: SemanticPosition): SurfaceEquation | null;

executeImageCommandfunctionSource ↗

Run an insert or replace, re-checking the same gates [canExecuteImageCommand](canExecuteImageCommand) applies.

Async because image bytes must be decoded to derive their natural extent before the drawing can be projected — the one editor command that cannot complete synchronously. It runs outside exec, so it reports a refusal to the editor's diagnostics itself.

declare function executeImageCommand(editor: DocxEditorInstance, command: Extract<EditorCommand, {
    type: 'insertImage' | 'replaceImage';
}>): Promise<ExecResult>;

finalizeImageOverlayInteractionfunctionSource ↗

Recompute the committed overlay result from release pointer coordinates.

declare function finalizeImageOverlayInteraction(options: {
    readonly session: ImageInteractionSession;
    readonly deltaXPt: number;
    readonly deltaYPt: number;
    readonly accumulatedScrollPt: number;
    readonly aspectLocked: boolean;
    readonly shiftKey: boolean;
    readonly textbox?: boolean;
    readonly anchorFrameOrigin: AnchorFrameOrigin | null;
}): FinalizedImageOverlayInteraction;

firstDayOfWeekfunctionSource ↗

First day of the week for a locale, as Date#getDay counts it (0 = Sunday).

Asks the runtime's week data when it has any, and otherwise falls back to a region table so a server without ICU week info still starts a US calendar on Sunday.

declare function firstDayOfWeek(locale?: string): number;

focusCompareDocumentsControlfunctionSource ↗

Move focus to the control that is useful at moment in a Compare documents dialog:

- busy: a compare started and Compare is disabled. Cancel when it stays enabled (a background compare), else the busy status, else the dialog itself. - refused: a compare was refused, or the file could not be read. The file input. - unchanged: the documents have no differences. Compare, else the file input.

The dialog's controls carry data-docx-part markers (cancel, apply) and the file field data-docx-field="revised". Focus never moves out of dialog.

declare function focusCompareDocumentsControl(dialog: HTMLElement | null | undefined, moment: 'busy' | 'refused' | 'unchanged'): void;

formatInchesfunctionSource ↗

Inches for DISPLAY, in the BROWSER's number format.

0.5 and 0,5 are the same measurement, and roughly half the locales this ships with write the second one. Interpolating a raw Number into a string picks the first for everyone. The catalogue supplies the surrounding words; this supplies the number.

Not the editor's locale: nothing in the i18n layer exposes one to read, so a German editor in an American browser still renders 0.5. The browser's guess beats a hardcoded . for every reader whose browser matches their language, which is most of them.

formatInches: (twips: number) => string

formattingBarChromeGroupsfunctionSource ↗

The formatting-bar groups for one editor snapshot: the default bar, the contextual image group when a drawing is selected, and the direction group when options.direction asks. Insertion without a selection lives in the packaged Insert menu (CHROME_MENUS), not in the bar — a host that wants a bar button places DocxEditor.Toolbar.ImageInsert itself.

declare function formattingBarChromeGroups(image: ImageContext | null, options?: FormattingBarOptions): readonly ChromeGroup[];

generateRulerTicksfunctionSource ↗

Ticks across one page dimension, matching the legacy cadence: eighth-inch minors with labelled inches, or millimetre minors with labelled centimetres.

declare function generateRulerTicks(lengthPx: number, unit: RulerUnit): RulerTick[];

goToBookmarkGroupsfunctionSource ↗

The rows of a Go To list grouped by place: the main text, then headers, footers, footnotes and endnotes. Places with no row are left out. Rows keep their order within a place.

declare function goToBookmarkGroups(rows: readonly BookmarkSummary[]): readonly GoToBookmarkGroup[];

goToBookmarkMatchfunctionSource ↗

Where the typed text sits in a bookmark name, compared without case, for showing the match. Null when the text is empty or the name does not contain it.

declare function goToBookmarkMatch(name: string, query: string): {
    readonly start: number;
    readonly end: number;
} | null;

goToBookmarkRowsfunctionSource ↗

The bookmarks a Go To name box offers for what was typed: those whose name contains it, compared without case, in the dialog's order. Names that start with it come first. An empty query offers every row. Sorted by location, the rows are in the order [goToBookmarkGroups](goToBookmarkGroups) shows them: by place first, so moving through the list follows the screen.

declare function goToBookmarkRows(bookmarks: readonly BookmarkSummary[], options: {
    readonly query: string;
    readonly sortBy: BookmarkSortOrder;
    readonly showHidden: boolean;
}): readonly BookmarkSummary[];

goToBookmarkTargetfunctionSource ↗

The bookmark a Go To name box means: the one whose name equals what was typed, compared without case, hidden or not; else the first row offered. Null when there is none.

declare function goToBookmarkTarget(bookmarks: readonly BookmarkSummary[], query: string, offered: readonly BookmarkSummary[]): BookmarkSummary | null;

handlePositionfunctionSource ↗

Where a handle sits, in twips from the page's LEFT SHEET EDGE (not the margin).

With indent.rtl, indent.left is the leading indent and sits on the right margin.

declare function handlePosition(handle: RulerIndentHandle, indent: RulerIndent, page: RulerPageMetrics): number;

historyShortcutOffunctionSource ↗

Which history step a keydown asks for, or null for any other key.

Ctrl+Y is the Windows redo; Ctrl/Cmd+Shift+Z is the macOS one. Both are accepted on every platform. Focused chrome, such as the picture selection overlay, calls this so history keys reach the editor instead of stopping at the control that holds focus.

declare function historyShortcutOf(event: HistoryShortcutKeys): 'undo' | 'redo' | null;

hostDocumentOffunctionSource ↗

The document that owns node, or the script's own document when node is absent. Without a DOM (server rendering) and without a node, this is undefined despite its type: call it from effects and event handlers, not during render.

Use it to add document-level listeners (selectionchange, pointerup, keydown) and to read activeElement for an editor that may live in another window.

declare function hostDocumentOf(node: Node | null | undefined): Document;

```ts
const doc = hostDocumentOf(menuElement);
doc.addEventListener('pointerdown', onOutsidePress, true);
```

hostTimersfunctionSource ↗

[HostTimers](HostTimers) bound to whatever window node() lives in when each call runs.

Use it for debounces and frames in chrome that can end up in a pop-out window: the opener's timers are throttled while it is hidden, and a pop-out's never run once it closes.

declare function hostTimers(node: () => Node | null | undefined): HostTimers;

```ts
const timers = hostTimers(() => panelElement);
let pending: number | null = null;
function schedule() {
  timers.clearTimeout(pending);
  pending = timers.setTimeout(refresh, 150);
}
```


 A window that goes away (a pop-out the user closes) never runs what is pending in it, and a dropped commit, notification or search is worse than a late one. So each window with pending work is watched for `pagehide`, and its pending timers and frames move to the window the node lives in by then, or to the script's own window.

hostWindowOffunctionSource ↗

The window that owns node: its timers, animation frames, observers and viewport size.

Falls back to the script's own window when the node's document has no window (an inert document from DOMParser, or a window that closed), and to globalThis without a DOM.

declare function hostWindowOf(node: Node | null | undefined): HostWindow;

```ts
const win = hostWindowOf(anchorElement);
const handle = win.setTimeout(close, 300);
const maxX = win.innerWidth - menuWidth;
```

inchesToTwipsfunctionSource ↗

inchesToTwips: (inches: number) => number

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;

initialSplitCellCountsfunctionSource ↗

The counts a Split cells dialog opens with: two columns, else two rows, else as many rows as a merged cell spans, whichever the engine honours first.

declare function initialSplitCellCounts(limits: SplitCellLimits | null, can: (command: Extract<EditorCommand, {
    type: 'splitCell';
}>) => CanResult): {
    readonly columns: string;
    readonly rows: string;
};

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;

isDomNodefunctionSource ↗

Whether value is a DOM node of any window.

declare function isDomNode(value: unknown): value is Node;

```ts
if (isDomNode(event.target) && panel.contains(event.target)) return;
```

isElementNodefunctionSource ↗

Whether value is a DOM element of any window. Use it instead of instanceof Element, which is false for an element of a pop-out window or an iframe.

declare function isElementNode(value: unknown): value is Element;

```ts
if (isElementNode(event.target)) event.target.closest('[data-docx-hf]');
```

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;

isGoToChordfunctionSource ↗

The Go To chord: Ctrl+G, or Cmd+Option+G on Apple platforms. F5 is not used: browsers reload on it. Cmd+G alone is left to the browser's find-next on macOS.

declare function isGoToChord(event: KeyboardEvent, apple?: boolean): boolean;

isHTMLElementNodefunctionSource ↗

Whether value is an HTML (not SVG or MathML) element of any window.

declare function isHTMLElementNode(value: unknown): value is HTMLElement;

```ts
if (isHTMLElementNode(event.target)) event.target.focus();
```

isInputEventfunctionSource ↗

Whether event is an input or beforeinput event, from any window.

declare function isInputEvent(event: Event): event is InputEvent;

```ts
if (isInputEvent(event) && event.inputType === 'insertText') track(event.data);
```

isKeyboardEventfunctionSource ↗

Whether event is a keyboard event, from any window.

declare function isKeyboardEvent(event: Event): event is KeyboardEvent;

```ts
if (isKeyboardEvent(event) && event.key === 'Escape') close();
```

isMouseEventfunctionSource ↗

Whether event is a mouse (or pointer) event, from any window.

declare function isMouseEvent(event: Event): event is MouseEvent;

```ts
const point = isMouseEvent(event) ? { x: event.clientX, y: event.clientY } : null;
```

isoDateOffunctionSource ↗

Format a local date as YYYY-MM-DD.

declare function isoDateOf(date: Date): string;

isPointerEventfunctionSource ↗

Whether event is a pointer event, from any window.

declare function isPointerEvent(event: Event): event is PointerEvent;

```ts
if (isPointerEvent(event) && event.button !== 0) return;
```

isStaleImageInteractionCommitfunctionSource ↗

Whether a drag's commit should be refused because the document moved under it — the refusal to return, or null when the commit is still valid.

Checks the mount generation and both revisions captured by [captureImageMutationPreconditions](captureImageMutationPreconditions). A gesture spans many frames, so this is the one place that decides its coordinates still describe the document they were measured against.

declare function isStaleImageInteractionCommit(editor: Pick<DocxEditorInstance, 'surface' | 'mountGeneration'>, session: ImageInteractionSession): ExecResult | null;

isTableChromeSlotfunctionSource ↗

Whether a chrome slot is one of the table-only ones. Narrows the type.

declare function isTableChromeSlot(slot: ChromeSlotId): slot is TableChromeSlotId;

isTextNodefunctionSource ↗

Whether value is a DOM text node of any window.

declare function isTextNode(value: unknown): value is Text;

```ts
const anchor = selection.anchorNode;
const element = isTextNode(anchor) ? anchor.parentElement : anchor;
```

layoutPointsToCssPixelsfunctionSource ↗

Layout points to CSS pixels. Pair with [surfacePaintScale](surfacePaintScale) for the current zoom.

declare function layoutPointsToCssPixels(points: number, paintScale: number): number;

lineSpacingMenuRowLabelfunctionSource ↗

A row's visible label, with its number in locale's format (1,5 in German).

label resolves an i18n key without interpolation, as a toolbar's host translation does, so the {value} placeholder is filled here. Without a locale the number reads as text does.

declare function lineSpacingMenuRowLabel(row: LineSpacingMenuRow, label: (key: string) => string, locale?: string): string;

lineSpacingMenuRowsfunctionSource ↗

The line-spacing menu rows for the spacing in force.

A current multiple that is not a preset joins the list in order, ticked; a current exact or atLeast leads the list as its own ticked row. A selection whose paragraphs disagree (current null) ticks nothing, because no one row is true of all of it.

declare function lineSpacingMenuRows(current: SurfaceFormatting['lineSpacing']): readonly LineSpacingMenuRow[];

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

lowerColorValueForBorderfunctionSource ↗

Lower a public colour for table border ops. Theme colours require a resolved literal for paint; auto preserves OOXML automatic semantics with a black render fallback.

declare function lowerColorValueForBorder(color: ColorValue, themeColors: readonly DocumentThemeColorEntry[]): ColorLowerResult;

lowerColorValueForFillfunctionSource ↗

Lower a public colour for cell fill. auto refuses because the cascade literal cannot be named honestly at commit time.

declare function lowerColorValueForFill(color: ColorValue, themeColors: readonly DocumentThemeColorEntry[]): ColorLowerResult;

mixedFieldsOffunctionSource ↗

A checkbox over a setting the selection disagrees about is INDETERMINATE, not unchecked — unchecked would claim the paragraphs agree it is off. The read reports null for exactly this, and a control that collapses it to a boolean throws the distinction away.

declare function mixedFieldsOf(format: ParagraphFormatRead): ParagraphDialogMixed;

mountPaginatedSurfacefunctionSource ↗

Mount a paginated surface over DOCX bytes.

Returns a typed rejection rather than throwing: a failure here is a property of the file, and a host must be able to tell "not a package" from "no body" without parsing an error message.

declare function mountPaginatedSurface(container: HTMLElement, bytes: Uint8Array, options?: PaginatedSurfaceOptions): OpenPaginatedResult;

observeContentControlPopupfunctionSource ↗

Follow scrolling, zoom, and size changes. Call the returned cleanup when the popup closes.

declare function observeContentControlPopup(panel: HTMLElement, anchor: HTMLElement): () => void;

observeUnsupportedElementsfunctionSource ↗

Observe placeholder mounts across repaint, pagination, and document replacement. The returned function disconnects the observer. Component mutations do not publish another list unless the engine's mount points change.

declare function observeUnsupportedElements(container: HTMLElement, listener: (hosts: readonly UnsupportedElementHost[]) => void): () => void;

openEditorWindowfunctionSource ↗

Open a pop-out window ready for the editor: same origin, styled like this page, with an empty mount point that fills it.

Resolves to null when the browser blocks the window, so call it from a user gesture such as a button click. The React DocxEditor.Window and Vue DocxEditorWindow components use it; call it directly when you mount the editor without an adapter.

declare function openEditorWindow(options?: OpenEditorWindowOptions): Promise<EditorWindow | null>;

```ts
const popup = await openEditorWindow({ title: 'Contract' });
if (popup) {
  editor.attach(popup.element);
  popup.onClose(() => editor.attach(homeElement));
}
```

overlayFrameToSheetCssPixelsfunctionSource ↗

Page-content frame → sheet-space CSS pixels (matches paintSelectionOverlay).

declare function overlayFrameToSheetCssPixels(layout: SemanticLayout, frame: OverlayFrameRect, coordinates: SurfaceOverlayCoordinates): {
    readonly left: number;
    readonly top: number;
    readonly width: number;
    readonly height: number;
};

overlayHostOriginfunctionSource ↗

Where the painted surface's box begins inside overlay chrome's containing block, in CSS pixels.

[overlayFrameToSheetCssPixels](overlayFrameToSheetCssPixels) produces coordinates relative to the surface element — the box the pages paint into — but overlay chrome portals OUTSIDE that element, and its absolutely positioned pieces resolve against the nearest positioned ancestor. The surface centres itself inside that ancestor with a stylesheet margin, so a frame placed without this origin lands at the far left of the viewport, one full centring margin off the image it rings. offsetLeft/offsetTop measure against the same positioned ancestor the chrome resolves against — every element between the two is static — which is what makes the two spaces agree.

declare function overlayHostOrigin(surfaceElement: HTMLElement | null): {
    readonly left: number;
    readonly top: number;
};

parseIsoDatefunctionSource ↗

Parse the leading YYYY-MM-DD of an ISO value as a LOCAL date, or null.

A control's w:fullDate is YYYY-MM-DDT00:00:00Z; only its calendar date matters here, and reading it through Date in a western time zone would show the previous day.

declare function parseIsoDate(value: string): Date | null;

partOfNodeIdfunctionSource ↗

The part a NODE lives in, WITHOUT opening a story store.

session.partFor(scope) resolves a scope by opening that story's store, and an open store is retained for as long as its part is in the package. The cap is 64. So routing a pure READ — "is this control locked", "what is its tab index" — through partFor spent a permanent slot per part touched, and an id naming no node at all still spent one, because the part name is matched from the id's prefix before anything is looked up. Sixty-four such reads and no further header could be opened for the rest of the session, silently.

Read straight from the live package instead. Ids carry the canonical part name, so this is a map lookup.

A collaboration session names the nodes it creates by logical id, which carries no part name. Those ids are looked up in each story part's node index, which opens no story store either. A view without storyParts has no session ids, so it answers null for them.

declare function partOfNodeId(session: Pick<TreeDocxSessionView, 'currentPackage' | 'part'> & Partial<Pick<TreeDocxSessionView, 'storyParts'>>, nodeId: string | undefined): OoxmlPart | null;

pointsToEmufunctionSource ↗

Points to EMU, rounded — EMUs are integral in the file.

declare function pointsToEmu(points: number): number;

positionContentControlPopupfunctionSource ↗

Place a popup against an anchor, within the viewport or its visible sheet.

declare function positionContentControlPopup(panel: HTMLElement, anchor: HTMLElement): void;

positionInputFromPropertiesCommandfunctionSource ↗

Extract the position input from an image-properties command, or null when it carries none.

declare function positionInputFromPropertiesCommand(command: {
    readonly horizontalEmu?: number;
    readonly verticalEmu?: number;
    readonly relativeToH?: string;
    readonly relativeToV?: string;
}, selected: {
    readonly position?: DrawingPositionInput | null;
} | null): DrawingPositionInput;

probeTableChromeCommandfunctionSource ↗

Probe command for Editor.can — uses the draft's active target and a well-formed value.

declare function probeTableChromeCommand(slot: TableChromeSlotId, draft?: TableChromeDraft): EditorCommand | null;

propertiesCommandHasPositionFieldsfunctionSource ↗

Whether an image-properties command carries any positioning fields at all.

declare function propertiesCommandHasPositionFields(command: {
    readonly horizontalEmu?: number;
    readonly verticalEmu?: number;
    readonly relativeToH?: string;
    readonly relativeToV?: string;
}): boolean;

readSplitCellCountsfunctionSource ↗

Read the typed column and row counts of a Split cells dialog.

declare function readSplitCellCounts(columns: string, rows: string, limits: SplitCellLimits | null): SplitCellCounts;

reportAutomationExceptionfunctionSource ↗

Report an editing API batch that threw an engine error, not a refusal, into the diagnostics of the editor it ran on: edit.internal-invariant with the error's class, never its message. Does nothing for an object that is not an editor.

declare function reportAutomationException(editor: object, error: unknown, tracked: boolean): void;

reportAutomationRefusalfunctionSource ↗

Report a refused editing API batch into the diagnostics of the editor it ran on. A runtime from DocxEditor.createBrowser calls this, so its refusals reach the editor's telemetry. Does nothing for an object that is not an editor. cause is the engine reason behind the refusal; a value the engine does not know is left out of the diagnostic.

declare function reportAutomationRefusal(editor: object, code: EditDiagnosticCode, tracked: boolean, cause?: string): void;

reportAutomationReviewSkipfunctionSource ↗

Report a tracked-change decision an editing API batch refused into the diagnostics of the editor it ran on, as one review.skipped event. cause is the structure behind the skip; a value the engine does not know is left out. Does nothing for an object that is not an editor.

declare function reportAutomationReviewSkip(editor: object, code: ReviewDiagnosticCode, operation?: ReviewOperation, cause?: string): void;

resizePreservesAspectfunctionSource ↗

Whether this handle drag should preserve aspect ratio.

declare function resizePreservesAspect(handle: ImageResizeHandle, aspectLocked: boolean, shiftKey: boolean, textbox?: boolean): boolean;

resolveColorValueToCssfunctionSource ↗

Resolve any public colour to a CSS #RRGGBB string for chrome display.

declare function resolveColorValueToCss(color: ColorValue | undefined | null, themeColors: readonly DocumentThemeColorEntry[], defaultHex?: string): string;

resolveEditorModulesfunctionSource ↗

Resolve construction-time modules into the registry the instance dispatches over.

declare function resolveEditorModules(modules: readonly EditorModule[] | undefined): EditorModuleRegistry;

resolveImageResourceLimitsfunctionSource ↗

Resolve caller overrides into frozen image limits; hard ceilings cannot be raised.

declare function resolveImageResourceLimits(overrides?: Partial<ImageResourceLimits>): ImageResourceLimits;

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;

resolveSvgIntrinsicSizefunctionSource ↗

Intrinsic size of an SVG, resolved the way a browser sizes one: absolute width/height first, then viewBox for the missing axis or ratio, then the CSS 300x150 default.

This is metadata for insert and reset-to-natural-size only. Layout uses the authored wp:extent and the browser rasterizes into that box, so nothing here sizes an allocation and an out-of-range value is clamped rather than refused.

declare function resolveSvgIntrinsicSize(bytes: Uint8Array, limits: ImageResourceLimits): ValidatedRasterHeader | null;

resolveThemeColorHexfunctionSource ↗

Resolve a theme colour to literal hex. When both tint and shade are present, ECMA-376 §17.3.2.6 / §17.3.4 / §17.3.5 require tint precedence — shade is ignored for paint.

declare function resolveThemeColorHex(color: Extract<ColorValue, {
    kind: 'theme';
}>, themeColors: readonly DocumentThemeColorEntry[]): {
    ok: true;
    hex: string;
} | {
    ok: false;
    reason: string;
};

resolveZoomModefunctionSource ↗

Normalize the 'auto' shorthand a host may pass anywhere a [ZoomMode](ZoomMode) is accepted.

Returns null for a value that is neither, so callers refuse rather than silently substituting a mode the caller did not ask for.

declare function resolveZoomMode(mode: ZoomMode | 'auto'): ZoomMode | null;

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;

rulerMarginTicksfunctionSource ↗

Horizontal ruler ticks counted from the margin the paragraph starts at: the left margin, or the right margin when indent.rtl is set. Labels count whole units outward on both sides, so the margin zone also reads 1, 2, and so on toward the sheet edge.

declare function rulerMarginTicks(page: RulerPageMetrics, indent: Pick<RulerIndent, 'rtl'>, unit: RulerUnit): RulerMarginTick[];

rulerPageBoxfunctionSource ↗

The first page's box, which the rulers measure against.

declare function rulerPageBox(pages: readonly {
    readonly index: number;
    readonly box: {
        width: number;
        height: number;
    };
}[]): {
    width: number;
    height: number;
} | null;

rulerTabPositionfunctionSource ↗

Where a tab stop sits, in twips from the page's left sheet edge. tabTwips counts from the paragraph's leading margin, as w:tab/@w:pos does: leftward from the right margin when indent.rtl is set.

declare function rulerTabPosition(tabTwips: number, page: RulerPageMetrics, indent: Pick<RulerIndent, 'rtl'>): number;

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

runSavefunctionSource ↗

Save goes straight to Editor.save() — it is not a command.

declare function runSave(editor: Editor | null): Promise<ArrayBuffer>;

runTableChromeCommandfunctionSource ↗

Run one table chrome pick with explicit draft state; returns the post-pick draft on success.

declare function runTableChromeCommand(editor: Editor | null, slot: TableChromeSlotId, value: unknown, draft: TableChromeDraft): RunTableChromeCommandResult;

runTableCommandfunctionSource ↗

Run a table command: planner-backed can first, then exec only when allowed.

declare function runTableCommand(editor: Editor | null, command: EditorCommand, options?: EditorExecOptions): ExecResult;

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;

sameTabStopsfunctionSource ↗

Whether two stop lists say the same thing. A list needs more than reference equality. *

declare function sameTabStops(a: readonly ParagraphTabStop[], b: readonly ParagraphTabStop[]): boolean;

sameZoomModefunctionSource ↗

Whether two modes say the same thing.

snapshotsEqual compares zoomMode by IDENTITY, and a host's zoomMode prop is an object — <DocxEditor zoomMode={{ type: 'fit', fit: 'pageWidth' }} /> is a fresh literal on every render, which is the spelling the docs show. Without a value comparison somewhere, each of those renders reinstalled the observer, refitted, bumped the tick, and re-rendered every useEditorState consumer in the tree — including the page selector that the slice memoization exists to keep asleep. The lane holds its object and compares by value here.

declare function sameZoomMode(a: ZoomMode, b: ZoomMode): boolean;

seedFieldsfunctionSource ↗

Open the form on the selection.

A null field means the selection DISAGREES about that setting. There is no third checkbox state to show it with, so the control opens on the least surprising value and [changedFields](changedFields) keeps the disagreement alive by not writing what the user did not touch. widowControl opens ON because that is the Word default a document inherits when nothing says otherwise.

declare function seedFields(format: ParagraphFormatRead): ParagraphDialogFields;

selectedDrawingOverlayTargetOffunctionSource ↗

The painted geometry of the selected drawing, for the resize/move overlay — or null.

Stricter than [selectedImageStateOf](selectedImageStateOf): it also requires a COLLAPSED selection, because a range that merely contains a drawing is a text selection, and drawing handles over it would claim an object the user did not single out.

declare function selectedDrawingOverlayTargetOf(surface: PaginatedSurface | null): SelectedDrawingOverlayTarget | null;

selectedImageStateOffunctionSource ↗

The selected image and what may be done to it, or null when nothing image-like is selected.

Unsupported placeholders, hidden drawings, and select-locked drawings cannot be selected.

declare function selectedImageStateOf(surface: PaginatedSurface | null): SelectedImageState | null;

shiftMonthfunctionSource ↗

The month after or before (year, month), wrapping the year.

declare function shiftMonth(year: number, month: number, delta: 1 | -1): {
    readonly year: number;
    readonly month: number;
};

signedFirstLineOffunctionSource ↗

Fold the "Special" pair back into the ONE signed value the engine takes. *

signedFirstLineOf: (kind: SpecialIndent, magnitudeTwips: number) => number

snapTwipsfunctionSource ↗

Round to the ruler's grid, or to the twip when the drag is precise.

declare function snapTwips(value: number, unit: RulerUnit, precise: boolean): number;

sniffImageMimefunctionSource ↗

Signature sniffing — authoritative over declared content type.

declare function sniffImageMime(bytes: Uint8Array): RenderableImageMime | PreservedImageMime | 'unknown';

sourceCropFromCropPercentfunctionSource ↗

UI percent (0–100) → projection fraction (0–1).

declare function sourceCropFromCropPercent(crop: ImageCropPercent): SourceCrop;

specialOffunctionSource ↗

specialOf: (signedTwips: number | null) => SpecialIndent

storyLabelTopfunctionSource ↗

Where to place the label bar of an open header, footer, or note, in viewport pixels.

The bar sits just above its story. A story with no room above it on its sheet, such as a header that starts at the paper edge, takes the bar just below it instead, so the bar never covers the gap between sheets or the ruler.

declare function storyLabelTop(storyRect: {
    readonly top: number;
    readonly bottom: number;
}, sheetTop: number | undefined, barHeight: number, clearance: number): number;

```ts
const top = storyLabelTop(band.getBoundingClientRect(), sheet.getBoundingClientRect().top, 28, 6);
```

surfaceExtentfunctionSource ↗

declare function surfaceExtent(layout: SemanticLayout, materialize: ReadonlySet<number> | undefined): SurfaceExtent;

surfacePaintScalefunctionSource ↗

Points → CSS pixels at the given zoom (matches mountPaginatedSurface / semantic paint).

declare function surfacePaintScale(zoom: number): number;

tableChromeIconPathsfunctionSource ↗

Material Symbol paths for one table chrome icon name.

declare function tableChromeIconPaths(name: keyof typeof GENERATED_ICON_PATHS): readonly string[];

tableChromeLabelKeyForTargetfunctionSource ↗

The i18n key naming one border target, for a trigger that shows the active scope.

Falls back to the "all" key rather than throwing: a label is chrome, and a missing one should not take the toolbar down.

declare function tableChromeLabelKeyForTarget(target: TableBorderEdgeTarget): string;

tableChromeToolbarStatefunctionSource ↗

Enabled state for one table chrome slot using explicit draft state.

declare function tableChromeToolbarState(editor: Editor | null, slot: TableChromeSlotId, draft?: TableChromeDraft): ToolbarCommandState;

tableChromeVisiblefunctionSource ↗

Contextual table chrome is visible when the engine reports table context.

declare function tableChromeVisible(table: TableContext | null | undefined): boolean;

tableCommandStatefunctionSource ↗

Planner-backed can/plan pair — production gate for table commands. Task 9 maps chrome slots.

declare function tableCommandState(command: EditorCommand, surface: PaginatedSurface): {
    readonly can: CanResult;
    readonly plan: TableCommandPlan;
};

tableCommandToolbarStatefunctionSource ↗

Enabled state for a table command when the caller holds the paginated surface.

Uses the same planner-backed tableCommandState as Editor.can/gateTableCommand. Chrome slot mapping for table controls is Task 9 — this helper is the shared can-before-exec seam for arbitrary table commands.

declare function tableCommandToolbarState(surface: PaginatedSurface | null, command: EditorCommand): Pick<ToolbarCommandState, 'enabled' | 'disabledReason'>;

textboxFrameReasonfunctionSource ↗

The message key saying why a selected text box frame takes no caret or offers no handles, or null when it does both. Not in viewing mode: viewing refuses the edit itself, so the box is not what stops it.

declare function textboxFrameReason(target: {
    readonly textbox?: boolean;
    readonly textEditable?: boolean;
    readonly canMove: boolean;
    readonly canResize: boolean;
}, editingMode: string): 'imageOverlay.textLocked' | 'imageOverlay.locked' | null;

```ts
const key = textboxFrameReason(target, editor.surface!.editingMode());
const title = key ? t(key) : undefined;
```

toEditorFontErrorfunctionSource ↗

declare function toEditorFontError(error: unknown): EditorFontError;

toolbarCommandStatefunctionSource ↗

Ask the engine whether one control should be enabled.

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

toolbarCommandStatesfunctionSource ↗

Enabled state for several controls in one pass.

declare function toolbarCommandStates(editor: Editor | null, ids: readonly ChromeSlotId[]): readonly ToolbarCommandState[];

trapTabWithinfunctionSource ↗

Keep Tab inside the dialog.

aria-modal tells assistive tech the rest of the page is inert; it does not stop Tab, so without this the third Tab lands on the document behind the dialog — which is the editable surface, so the next keystroke types into the paragraph being formatted.

Returns true when the event was handled, so a caller only has to call preventDefault.

declare function trapTabWithin(panel: HTMLElement, event: KeyboardEvent): boolean;

twipsToInchesfunctionSource ↗

twipsToInches: (twips: number) => number

unsupportedElementRuleMatchesfunctionSource ↗

Whether a rule claims an occurrence. Adapters use it to pick the first matching declaration; hosts with their own registration can use it the same way.

declare function unsupportedElementRuleMatches(rule: UnsupportedElementRule, element: UnsupportedElement): boolean;

validateDrawingPositionInputfunctionSource ↗

Validate a position input, refusing offsets or bases outside what OOXML allows.

declare function validateDrawingPositionInput(position: DrawingPositionInput): boolean;

validateImageCropPercentfunctionSource ↗

Whether a crop is expressible: every edge finite and in range, and opposite edges not overlapping.

Opposite edges matter — a left plus right crop summing past 100% describes a negative width, which DrawingML has no way to store.

declare function validateImageCropPercent(crop: ImageCropPercent): boolean;

validateRasterHeaderfunctionSource ↗

Validate a raster image's header structurally and report its real MIME type and extent.

Content type is a CLAIM; this is what makes it a fact. A file declaring image/png over JPEG bytes is caught here rather than at decode.

declare function validateRasterHeader(bytes: Uint8Array, mime: SupportedImageMime): ValidatedRasterHeader | null;

validateSetImagePositionCommandfunctionSource ↗

Validate a set-position command before it reaches the store.

declare function validateSetImagePositionCommand(command: {
    readonly horizontalEmu?: number;
    readonly verticalEmu?: number;
    readonly relativeToH?: string;
    readonly relativeToV?: string;
}, mode: 'frame' | 'simple'): boolean;

validateThemeModifierfunctionSource ↗

Clamp and validate an OOXML theme modifier fraction (0, 1].

declare function validateThemeModifier(value: unknown): value is number;

watchHighlightsfunctionSource ↗

Highlight a named set and keep it current as the document changes.

declare function watchHighlights(editor: Editor, name: string, source: HighlightSource, options?: WatchHighlightsOptions): HighlightWatch;

```ts
const glossary = watchHighlights(editor, 'glossary', (editor) =>
  editor.findMatches(terms, { wholeWord: true }).flat()
);
// Later:
glossary.stop();
```

watermarkShapeBoxfunctionSource ↗

The shape box, in points, that setWatermark writes for watermark on a page whose text area (page size less margins) is area. The box is centered on the text area, and a diagonal text box turns 45 degrees counterclockwise about its center. Null when the options name no text and no readable picture. Pass a measurer for the exact text advance; without one the advance is an estimate.

declare function watermarkShapeBox(watermark: Watermark, area: WatermarkSize, measurer?: TextMeasurer): WatermarkSize | null;

```ts
const box = watermarkShapeBox({ text: 'DRAFT' }, { width: 468, height: 648 });
```

withTabStopfunctionSource ↗

Add one stop, replacing any stop already at that position, and keep the list sorted. *

declare function withTabStop(stops: readonly ParagraphTabStop[], stop: ParagraphTabStop): readonly ParagraphTabStop[];

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

DocumentRefreshErrorclassSource ↗

A capture failure with a stable code. applyUpdate() failures use RefreshResult instead.

declare class DocumentRefreshError extends Error

AnchorFrameOrigininterfaceSource ↗

Where an anchored drawing's positioning frame begins, in layout points.

An anchored drawing's offsets are relative to a base the file names (page, margin, column, …), so a move drag needs that base's origin to turn a pointer delta into a stored offset.

interface AnchorFrameOrigin

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

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

BlankDocumentOptionsinterfaceSource ↗

How a blank document starts.

interface BlankDocumentOptions

BookmarkChromeHandlersinterfaceSource ↗

Host chrome for bookmarks.

interface BookmarkChromeHandlers

BookmarkDialogNameStateinterfaceSource ↗

What the typed name allows in the Bookmark dialog.

interface BookmarkDialogNameState

BookmarkMarkInfointerfaceSource ↗

One painted bookmark mark, as BookmarkMarkOptions callbacks see it.

interface BookmarkMarkInfo

BookmarkMarkOptionsinterfaceSource ↗

How Show bookmarks paints its marks. Register with setBookmarkMarks.

interface BookmarkMarkOptions

BookmarkMarkOptionsSourceinterfaceSource ↗

The surface's view of the mark options.

interface BookmarkMarkOptionsSource

BrowserAutomationHostinterfaceSource ↗

An automation host over a live editor.

interface BrowserAutomationHost extends AutomationHost

CalendarDayinterfaceSource ↗

One cell of a month grid.

interface CalendarDay

CalendarMonthinterfaceSource ↗

A six-week month grid plus its labels.

interface CalendarMonth

CalendarMonthOptionsinterfaceSource ↗

Inputs for [calendarMonth](calendarMonth).

interface CalendarMonthOptions

ChromeControlinterfaceSource ↗

One toolbar control as the registry describes it — what it renders as, never whether it is enabled.

Enabled state has exactly ONE source, toolbarCommandState, which asks the engine. A descriptor carrying its own disabled flag would be a second answer that goes stale the moment the engine wires the slot.

interface ChromeControl<Id extends string = string>

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

ChromeGroupinterfaceSource ↗

One toolbar group: the taxonomy both adapters derive their default arrangement FROM.

Never hand-list controls in an adapter — a default toolbar is built by walking CHROME_GROUPS, so a slot added here appears in React and Vue without either being edited.

interface ChromeGroup<Id extends string = string, ControlId extends string = string>

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

CommentDraftChromeHandlersinterfaceSource ↗

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

interface CommentDraftChromeHandlers

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

ContentControlListNavigationinterfaceSource ↗

The stateful keyboard behavior used by all value lists.

interface ContentControlListNavigation

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

CustomFontsOptionsinterfaceSource ↗

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

interface CustomFontsOptions extends Omit<LoadFontsRequest, 'signal'>

DocumentRefreshinterfaceSource ↗

External file transport stays in your application. Reload resets selection and undo history.

interface DocumentRefresh

DocumentRefreshStateinterfaceSource ↗

Observable controller state. Document editing stays available during processing.

interface DocumentRefreshState

DocumentSearchinterfaceSource ↗

The shared search of one editor. Get it with [createDocumentSearch](createDocumentSearch).

interface DocumentSearch

DocumentSearchFindOptionsinterfaceSource ↗

Options for [DocumentSearch.find](DocumentSearch.find).

interface DocumentSearchFindOptions extends DocumentSearchOptions

DocumentSearchNavigateOptionsinterfaceSource ↗

How a search moves to a match.

interface DocumentSearchNavigateOptions

DocumentSearchOptionsinterfaceSource ↗

Search options that narrow a query.

interface DocumentSearchOptions

DocumentSearchStateinterfaceSource ↗

A snapshot of the shared search. The same object until something changes.

interface DocumentSearchState

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

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

DrawingPreviewPackageLimitsinterfaceSource ↗

Caps for [createDrawingPreviewPackage](createDrawingPreviewPackage).

interface DrawingPreviewPackageLimits

DrawingSupportIssueinterfaceSource ↗

A drawing feature that the editor does not show as authored. Each code means:

- unsupported-effect: the editor ignores an explicit effect, such as a:blur, a:duotone, or a14:imgProps. The drawing renders without it. - renderer-required: an optional effect, such as a:glow, needs the drawing module: drawingModule() or installDrawing() from @docx-editor.dev/pro/drawing. It appears only while that module is not installed in the current process, for occurrences and reports alike. - unverified-3d: the drawing has 3-D properties (a:scene3d, a:sp3d), which render flat. - saved-fallback: the editor shows the saved mc:Fallback content, not the main content. - unplaced-drawing: the drawing has no layout position, so the editor does not show it. - inspection-limit: a scan budget stopped the check, so the result is incomplete. - projection-diagnostic: the source is malformed or partly unusable. detail holds the diagnostic code, such as invalid-geometry or resource-refused.

The check reads the drawing's own XML. It does not read chart or diagram parts, inherited theme effects, or image bytes, so an empty list does not prove full fidelity.

interface DrawingSupportIssue

EditorCommandExecuteinterfaceSource ↗

A command hook keeps its nullary event-handler form and accepts explicit options.

interface EditorCommandExecute

EditorModuleinterfaceSource ↗

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

interface EditorModule

EditorModuleRegistryinterfaceSource ↗

The resolved registry the editor instance holds: at most one review contribution and at most one collaboration contribution (first registration wins for each), all custom node definitions in registration order.

interface EditorModuleRegistry

EditorWindowinterfaceSource ↗

A pop-out window opened by [openEditorWindow](openEditorWindow).

interface EditorWindow

EquationActivationinterfaceSource ↗

A user click on one painted equation.

interface EquationActivation

EquationChromeHandlersinterfaceSource ↗

Host chrome that edits a clicked Office Math equation.

interface EquationChromeHandlers

EquationOpsinterfaceSource ↗

Surface equation reads and atomic replace/remove writes.

interface EquationOps

FinalizedImageOverlayInteractioninterfaceSource ↗

The committed result of a whole drag, recomputed from the release coordinates.

Recomputed rather than accumulated from the per-frame previews, so rounding applied once per frame cannot add up into a final extent that differs from where the pointer actually stopped.

interface FinalizedImageOverlayInteraction extends ImageResizeResult

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

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

FontUrlSourceinterfaceSource ↗

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

interface FontUrlSource

FormattingBarOptionsinterfaceSource ↗

Options for [formattingBarChromeGroups](formattingBarChromeGroups).

interface FormattingBarOptions

GoToBookmarkGroupinterfaceSource ↗

One section of a Go To list sorted by location: the rows of one place, each with its index in the full list.

interface GoToBookmarkGroup

GoToChromeHandlersinterfaceSource ↗

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

interface GoToChromeHandlers

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

HighlightWatchinterfaceSource ↗

A highlight set that [watchHighlights](watchHighlights) keeps current.

interface HighlightWatch

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

HistoryShortcutKeysinterfaceSource ↗

Modifier and key state of one keydown, as both DOM and framework key events carry it.

interface HistoryShortcutKeys

HostTimersinterfaceSource ↗

Timers that run on the window node belongs to, resolved at each call.

A handle is cleared on the window that issued it, so a timer set before the editor moved to another window is still cancelled after the move. Handles are this object's own numbers: two windows count their native handles independently, so a native number alone could name a timer in either one. Clear them with this object, never with the global clearTimeout.

interface HostTimers

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

HyperlinkOpsinterfaceSource ↗

Reading and writing hyperlinks on the surface.

Every href that leaves here has already been through sanitizeHref — targets come from files, so javascript:, data: and vbscript: are dropped at the parse boundary rather than trusted to be filtered by whoever renders them.

interface HyperlinkOps

ImageCropPercentinterfaceSource ↗

Crop edge in UI percent (0–100).

interface ImageCropPercent

ImageCropPermilleinterfaceSource ↗

Crop edge in OOXML permille (0–100000).

interface ImageCropPermille

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

ImageInteractionSessioninterfaceSource ↗

One in-flight image drag: where it started, and everything needed to decide at commit time whether the document still describes what the gesture was planned against.

Both revisions are captured because they move independently — layout can re-flow without the package changing, and vice versa.

interface ImageInteractionSession

ImageOverlayScrollPortinterfaceSource ↗

How an image drag scrolls the page when it reaches the viewport edge.

Returns the delta ACTUALLY applied rather than the one requested, because a drag at the end of the document cannot scroll further and the overlay must not move the image by a distance the page did not travel.

interface ImageOverlayScrollPort

ImageResizeResultinterfaceSource ↗

One resize frame: the extent to store, and the box to draw while the pointer is still down.

Both, because they are different spaces — the extent is EMU for the file, the preview is points for the overlay — and computing them separately would let the handle drift from the rectangle it is dragging.

interface ImageResizeResult

ImageResourceLimitsinterfaceSource ↗

Trust-boundary caps specific to image decoding and embedding.

interface ImageResourceLimits

InvalidTextFormFieldChromeHandlersinterfaceSource ↗

Framework rendering for invalid protected-field acknowledgements.

interface InvalidTextFormFieldChromeHandlers

InvalidTextFormFieldSessioninterfaceSource ↗

An invalid protected-field acknowledgement.

interface InvalidTextFormFieldSession

LineSpacingMenuRowinterfaceSource ↗

One row of the line-spacing menu.

interface LineSpacingMenuRow

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

NavigateToChangeOptionsinterfaceSource ↗

Explicit change navigation. Does not change the default scroll preservation during refresh.

interface NavigateToChangeOptions extends ScrollToAnchorOptions

OpenEditorWindowOptionsinterfaceSource ↗

Options for [openEditorWindow](openEditorWindow).

interface OpenEditorWindowOptions

OpeningIndicatorHostinterfaceSource ↗

Receives the element that shows the loading indicator below the laid-out pages, while a large document lays out its remaining pages.

interface OpeningIndicatorHost

```ts
editor.setOpeningIndicatorHost({
  publish(element) {
    // Render your indicator into `element`, or remove it when `element` is null.
  },
});
```

OverlayFrameRectinterfaceSource ↗

A rectangle in one page's content frame, in layout points.

interface OverlayFrameRect

PaginatedSurfaceinterfaceSource ↗

The mounted, painted, editable document — the layer createDocxEditor builds its contract on.

The painted pages ARE the editable surface: they are contenteditable, but the DOM is a picture. Browser mutations are prevented and re-expressed as tree ops, and selection maps only through data-paragraph-id/data-start, never through DOM node identity.

Every write goes through the guarded mutation path on this object. Reaching past it into session to apply ops directly bypasses the layout invalidation and the caret bookkeeping.

interface PaginatedSurface extends SurfaceIndentAndListOps

PaginatedSurfaceOptionsinterfaceSource ↗

How a paginated surface opens. Every field is optional.

measurer is the injection seam that keeps layout DOM-free — supply one to lay a document out on a server, or leave it off in a browser to get the canvas measurer.

interface PaginatedSurfaceOptions