@docx-editor.dev/core/contracts/editor

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

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;

reviewPaneListsItemfunctionSource ↗

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

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

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

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

revisionMarkupColorfunctionSource ↗

CSS token for a validated named color.

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

revisionMarkupStylefunctionSource ↗

Select the visual style without changing revision identity.

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

EditorFontErrorclassSource ↗

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

declare class EditorFontError extends Error

AnchorHighlightAnimationinterfaceSource ↗

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

interface AnchorHighlightAnimation

AnchorHighlightOptionsinterfaceSource ↗

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

interface AnchorHighlightOptions

AuthoredNoteNumberinginterfaceSource ↗

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

interface AuthoredNoteNumbering

BookmarkSummaryinterfaceSource ↗

One bookmark, as the bookmarks query lists it.

interface BookmarkSummary

ClearAnchorHighlightOptionsinterfaceSource ↗

Explicit highlight dismissal.

interface ClearAnchorHighlightOptions

CollaborationParticipantsDiagnosticinterfaceSource ↗

The number of people in the collaboration room changed.

interface CollaborationParticipantsDiagnostic extends DiagnosticBase

CollaborationStatusDiagnosticinterfaceSource ↗

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

interface CollaborationStatusDiagnostic extends DiagnosticBase

CommentRecordinterfaceSource ↗

One comment as authored in word/comments.xml.

interface CommentRecord

CompareDocumentsChromeHandlersinterfaceSource ↗

Host rendering for the Compare documents dialog.

interface CompareDocumentsChromeHandlers

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

CompareDocumentsProgressinterfaceSource ↗

How far a background compare is.

interface CompareDocumentsProgress

CompareDocumentsRequestinterfaceSource ↗

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

interface CompareDocumentsRequest

ContentControlinterfaceSource ↗

Structured document tag (w:sdt).

interface ContentControl

ContentControlFilterinterfaceSource ↗

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

interface ContentControlFilter

ContentControlSummaryinterfaceSource ↗

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

interface ContentControlSummary

CustomNodeDiagnosticEventinterfaceSource ↗

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

interface CustomNodeDiagnosticEvent extends DiagnosticBase

DiagnosticBaseinterfaceSource ↗

Fields every diagnostic carries.

interface DiagnosticBase

DiagnosticExplanationinterfaceSource ↗

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

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

interface DiagnosticExplanation

DiagnosticFailureDetailinterfaceSource ↗

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

interface DiagnosticFailureDetail

DocAnchorinterfaceSource ↗

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

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

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

interface DocAnchor

DocAnchorRangeinterfaceSource ↗

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

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

interface DocAnchorRange

DocCommentinterfaceSource ↗

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

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

interface DocComment

DocEditsinterfaceSource ↗

The document-executable edit vocabulary.

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

interface DocEdits

DocLocationinterfaceSource ↗

Structural addressing for content the paraId map cannot reach.

interface DocLocation

DocQueriesinterfaceSource ↗

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

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

interface DocQueries

DocQueryResultsinterfaceSource ↗

What each query returns. Keyed identically to DocQueries.

interface DocQueryResults

DocRangeinterfaceSource ↗

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

interface DocRange

DocumentBodyinterfaceSource ↗

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

interface DocumentBody

DocumentChangeinterfaceSource ↗

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

interface DocumentChange

DocumentHandleinterfaceSource ↗

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

interface DocumentHandle

DocumentOpenFailureinterfaceSource ↗

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

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

interface DocumentOpenFailure

DocumentProtectionStateinterfaceSource ↗

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

interface DocumentProtectionState

DocumentShapeinterfaceSource ↗

The bucketed shape of an opened document.

interface DocumentShape

DocxDocumentinterfaceSource ↗

A parsed .docx.

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

interface DocxDocument

DocxDocumentJSONinterfaceSource ↗

The JSON-safe projection of a document.

interface DocxDocumentJSON

DrawingLocksinterfaceSource ↗

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

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

interface DrawingLocks

DrawingPositionInputinterfaceSource ↗

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

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

interface DrawingPositionInput

EditorinterfaceSource ↗

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

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

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

interface Editor extends EditorAnchorNavigation, EditorHighlights, EditorReviewHits

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

EditorAnchorNavigationinterfaceSource ↗

Navigation and temporary highlights for external paragraph references.

interface EditorAnchorNavigation

EditorBookmarkCommandsinterfaceSource ↗

The bookmark commands an editor accepts.

interface EditorBookmarkCommands

EditorCommandsinterfaceSource ↗

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

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

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

EditorErrorinterfaceSource ↗

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

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

interface EditorError extends Error

EditorEventsinterfaceSource ↗

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

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

interface EditorEvents

EditorExecOptionsinterfaceSource ↗

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

interface EditorExecOptions extends HistoryGroupOptions

EditorFormatPainterCommandsinterfaceSource ↗

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

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

interface EditorFormatPainterCommands

EditorHeaderFooterCommandsinterfaceSource ↗

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

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

interface EditorHeaderFooterCommands

EditorHighlightsinterfaceSource ↗

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

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

interface EditorHighlights

EditorHostChangeinterfaceSource ↗

The payload of the hostChange event.

interface EditorHostChange

EditorNoteCommandsinterfaceSource ↗

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

interface EditorNoteCommands

EditorQueriesinterfaceSource ↗

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

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

interface EditorQueries extends DocQueries

EditorQueryResultsinterfaceSource ↗

What each editor query returns. Keyed identically to EditorQueries.

interface EditorQueryResults extends DocQueryResults

EditorReviewHitsinterfaceSource ↗

Hit testing for hosts that draw their own review chrome.

interface EditorReviewHits

EditorSnapshotinterfaceSource ↗

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

interface EditorSnapshot

EditRejectedDiagnosticinterfaceSource ↗

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

interface EditRejectedDiagnostic extends DiagnosticBase, DiagnosticFailureDetail

ExtentinterfaceSource ↗

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

interface Extent

FontConfigurationinterfaceSource ↗

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

interface FontConfiguration

FontDefinitioninterfaceSource ↗

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

interface FontDefinition

FontFaceRequestinterfaceSource ↗

A concrete font face requested by authored document content.

interface FontFaceRequest

FontFailedDiagnosticinterfaceSource ↗

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

interface FontFailedDiagnostic extends DiagnosticBase

FontSourceinterfaceSource ↗

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

interface FontSource

FontSourceSubstitutioninterfaceSource ↗

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

interface FontSourceSubstitution

FormatPainterSurfaceStateinterfaceSource ↗

Painter state, as the editor publishes it.

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

interface FormatPainterSurfaceState

HeaderFooterSetinterfaceSource ↗

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

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

interface HeaderFooterSet

HeaderFooterSlotArgsinterfaceSource ↗

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

interface HeaderFooterSlotArgs

HeaderFooterStateinterfaceSource ↗

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

interface HeaderFooterState

HighlightHitinterfaceSource ↗

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

interface HighlightHit<R extends HighlightRange = HighlightRange>

HighlightOptionsinterfaceSource ↗

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

interface HighlightOptions

HighlightRangeinterfaceSource ↗

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

interface HighlightRange

HighlightRectinterfaceSource ↗

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

interface HighlightRect

HighlightResultinterfaceSource ↗

What setHighlights() resolved against the open document.

interface HighlightResult

HistoryDiagnosticinterfaceSource ↗

Optional diagnostic notification; subscribing does not change history behavior.

interface HistoryDiagnostic

HistoryDiagnosticEventinterfaceSource ↗

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

interface HistoryDiagnosticEvent extends DiagnosticBase

HistoryGroupinterfaceSource ↗

interface HistoryGroup

HistoryGroupOptionsinterfaceSource ↗

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

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

interface HistoryGroupOptions

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

HistoryGroupOutcomeinterfaceSource ↗

The history authority's result for this frame.

interface HistoryGroupOutcome

HyperlinkInfointerfaceSource ↗

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

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

interface HyperlinkInfo

ImageCropPercentinterfaceSource ↗

Crop edge in UI percent (0–100).

interface ImageCropPercent

IndentFormattinginterfaceSource ↗

Indent at the selection, in twips.

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

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

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

interface IndentFormatting

NotePropertiesSideinterfaceSource ↗

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

interface NotePropertiesSide

NotePropertiesStateinterfaceSource ↗

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

interface NotePropertiesState

NumberingRefinterfaceSource ↗

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

interface NumberingRef

PageMarginsinterfaceSource ↗

Page margins in twips.

interface PageMargins

PageSetupinterfaceSource ↗

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

interface PageSetup

ParagraphinterfaceSource ↗

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

interface Paragraph

ParagraphDisagreementsinterfaceSource ↗

Which paragraph-level reads the selection disagrees about.

interface ParagraphDisagreements

ParagraphFlagsinterfaceSource ↗

The five paragraph flags a Paragraph dialog shows as checkboxes.

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

interface ParagraphFlags

ParagraphFormatCommandinterfaceSource ↗

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

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

interface ParagraphFormatCommand

ParagraphSummaryinterfaceSource ↗

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

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

interface ParagraphSummary

ParagraphTabStopinterfaceSource ↗

One custom tab stop, as a command states it.

interface ParagraphTabStop

PerformanceDiagnosticinterfaceSource ↗

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

interface PerformanceDiagnostic extends DiagnosticBase

PointinterfaceSource ↗

A position in points.

interface Point

RectinterfaceSource ↗

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

interface Rect

ResolvedNoteNumberinginterfaceSource ↗

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

interface ResolvedNoteNumbering

ResolvedReviewPaneinterfaceSource ↗

The review pane settings in force, with every field resolved.

interface ResolvedReviewPane

ResolvedRevisionMarkupinterfaceSource ↗

Fully resolved, immutable viewer preferences.

interface ResolvedRevisionMarkup

ResolveReviewChangesOptionsinterfaceSource ↗

Selection and unsupported-change policy for a bulk review decision.

interface ResolveReviewChangesOptions

ReviewActivationOptionsinterfaceSource ↗

How activating a review item places it in the viewport, and whether it announces the reveal.

interface ReviewActivationOptions

ReviewChangesAttributioninterfaceSource ↗

Who and when a change of tracked-change author records. Shared by both selections.

interface ReviewChangesAttribution

ReviewChangesResolvedEventinterfaceSource ↗

The payload of the reviewChangesResolved event.

interface ReviewChangesResolvedEvent

ReviewCommentIteminterfaceSource ↗

One comment as a review card. A reply carries parentId; OOXML gives replies no separate element, so threads are reconstructed from that link.

interface ReviewCommentItem

ReviewCommentPlacementinterfaceSource ↗

A comment thread's card.

interface ReviewCommentPlacement extends ReviewItemPlacementBase

ReviewCustomIteminterfaceSource ↗

A card contributed by a recognized custom node (defineCustomNode with a reviewCard hook), anchored at the node's range.

Informational, never resolvable: there is nothing to accept or reject, so the engine refuses those verbs on it. title and detail are HOST-authored (the definition's hook produced them), but attrs and text originate in a file an attacker controls — a surface renders every one of these as text, never markup.

interface ReviewCustomItem

ReviewCustomPlacementinterfaceSource ↗

A custom node's card (defineCustomNode with a reviewCard hook).

interface ReviewCustomPlacement extends ReviewItemPlacementBase

ReviewItemHitinterfaceSource ↗

One review item under a client point.

interface ReviewItemHit

ReviewItemPlacementBaseinterfaceSource ↗

What every review card carries, whatever kind of decision it represents.

Presentation-ready by design: author, initials, date and text are derived by the ENGINE, because deriving them means walking runs and reading w15:commentsEx. An adapter doing that walk would put document derivation in the host and would have to be written once per framework.

interface ReviewItemPlacementBase

ReviewItemQueryinterfaceSource ↗

Narrows what getReviewItems returns.

Filtering revision kinds is how a host hides structural cards it has no UI for, placement: false skips the layout pass entirely when only metadata is wanted, and pairReplacements: false lists a typed-over selection as its two halves.

interface ReviewItemQuery

ReviewItemRevealEventinterfaceSource ↗

The payload of the reviewItemReveal event.

interface ReviewItemRevealEvent

ReviewPaneItemFieldsinterfaceSource ↗

The fields of a review item that decide whether the review pane lists it. A ReviewItem and a review item placement both have them.

interface ReviewPaneItemFields

ReviewPaneOptionsinterfaceSource ↗

Review pane settings to change. Every field is optional, and an omitted field keeps its current value.

interface ReviewPaneOptions

ReviewPositioninterfaceSource ↗

A position in the model offset space of one story.

interface ReviewPosition

ReviewRangeinterfaceSource ↗

Where an item is anchored: a range in one story.

interface ReviewRange

ReviewRevisionIteminterfaceSource ↗

One tracked change as a review card.

Keyed per DECISION rather than per site: a revision spanning three ranges is one card, because accepting it accepts all three.

interface ReviewRevisionItem

ReviewRevisionPlacementinterfaceSource ↗

A tracked change's card.

interface ReviewRevisionPlacement extends ReviewItemPlacementBase

ReviewSkippedDiagnosticinterfaceSource ↗

An accept, reject or re-author request skipped one or more tracked changes. One event for each code and kind of change in the request.

interface ReviewSkippedDiagnostic extends DiagnosticBase

RevisioninterfaceSource ↗

One tracked change.

Addressing needs BOTH id and part: @w:id is unique only within a part, so an id alone names two revisions in any package that has a header or a comments part.

interface Revision

RevisionAddressinterfaceSource ↗

How a tracked change is addressed: @w:id, @w:author and @w:date together, within a part.

All of them, always. @w:id is unique only within a part, so an id alone names two revisions in any package with a header or a comments part — and it is not author-scoped either, so (part, id) would merge two authors' distinct revisions. One logical revision is also deliberately many elements sharing an id, as a tracked row insertion is, which no uniqueness rule could express.

interface RevisionAddress

RevisionAuthorEntryinterfaceSource ↗

One reattributed change. key and author describe the change after the update, because review keys include the author.

interface RevisionAuthorEntry extends RevisionBatchEntry

RevisionAuthorResultinterfaceSource ↗

Outcome of one attribution change. Counts refer to review decisions, not XML markers.

interface RevisionAuthorResult

RevisionBatchEntryinterfaceSource ↗

A canonical review decision. Keys are valid only in the open document.

interface RevisionBatchEntry

RevisionBatchResultinterfaceSource ↗

Outcome of one selected-set decision. Counts refer to review decisions, not XML markers.

interface RevisionBatchResult

RevisionMarkupChromeHandlersinterfaceSource ↗

Host rendering for the Track changes options dialog.

interface RevisionMarkupChromeHandlers

RevisionMarkupDialogSessioninterfaceSource ↗

A local settings draft owned by the editor.

interface RevisionMarkupDialogSession

RevisionMarkupStyleinterfaceSource ↗

interface RevisionMarkupStyle<Mark extends string = RevisionMarkupMark>

RevisionMarkupTextStyleinterfaceSource ↗

Viewer-only text styling. Document highlighting remains unchanged.

interface RevisionMarkupTextStyle<Mark extends string = RevisionMarkupMark> extends RevisionMarkupStyle<Mark>

RuninterfaceSource ↗

A stretch of text sharing one set of character properties.

interface Run

RunFormattinginterfaceSource ↗

Character formatting, and — at selection level — the paragraph properties a toolbar reads alongside it.

One type serves both roles so a toolbar reads alignment, style and script state from the same object as bold and italic. On a [Run](Run) the selection-level fields stay absent: a run has no alignment or paragraph style of its own.

interface RunFormatting

ScrollToAnchorOptionsinterfaceSource ↗

Scroll settings for [EditorAnchorNavigation.scrollToAnchor](EditorAnchorNavigation.scrollToAnchor). Every field is optional. The fields match document refresh NavigateToChangeOptions.

interface ScrollToAnchorOptions

SectioninterfaceSource ↗

One section: the page it lays out on, and the header/footer stories it declares.

interface Section

SectionPropertiesinterfaceSource ↗

w:sectPr: the page a section lays out on. Twips throughout, as the file stores them.

interface SectionProperties

SelectedImageStateinterfaceSource ↗

Canonical selected-image read model shared by [EditorSnapshot.image](EditorSnapshot.image) and [Editor.getSelectedImage](Editor.getSelectedImage).

interface SelectedImageState

SemanticIdentityinterfaceSource ↗

Model-derived stable identity within a scope. Positions resolve through this index, not accumulated display-item lengths or editing-engine coordinates.

interface SemanticIdentity

SemanticPositioninterfaceSource ↗

A caret position in the model.

interface SemanticPosition

SemanticSelectioninterfaceSource ↗

A selection as two semantic positions — never as DOM nodes.

anchor is where the selection started and head is where it currently ends, so head before anchor is an ordinary backwards selection rather than an error. Collapsed when the two are equal, which is what a caret is.

interface SemanticSelection

SessionActivityinterfaceSource ↗

What an editor did over a window of use or over its whole session. Counts and milliseconds only: no key, position, command argument or text.

interface SessionActivity

StyleDefinitioninterfaceSource ↗

One style: the ID content references, the name a reader sees, and its inheritance link.

interface StyleDefinition

StyleDefinitionsinterfaceSource ↗

styles.xml, split by the three style families that address separately.

Keyed by style ID rather than by the name a reader sees, because the ID is what a paragraph or run actually references.

interface StyleDefinitions

TableinterfaceSource ↗

A table: its rows, and the table style they resolve through.

interface Table

TableBorderSpecinterfaceSource ↗

Complete border spec for [EditorCommands.setTableBorders](EditorCommands.setTableBorders). Size is in eighths of a point.

interface TableBorderSpec

TableCellinterfaceSource ↗

One cell. Its content is ordinary blocks, so a cell may hold paragraphs, nested tables and content controls alike.

interface TableCell

TableColumnDividerResizeTargetinterfaceSource ↗

Adjacent grid columns addressed by an internal divider resize gesture.

sourceRevision is the PACKAGE revision of the layout the target was read from — the number getDocumentHandle() reports, never one story's own. Commit MUST refuse when it no longer equals the current one, even if an older layout remains published for geometry.

interface TableColumnDividerResizeTarget

TableColumnOccurrenceTargetinterfaceSource ↗

Explicit column occurrence. sourceRevision per [TableColumnDividerResizeTarget](TableColumnDividerResizeTarget).

interface TableColumnOccurrenceTarget

TableContextinterfaceSource ↗

Where the caret sits inside a table: its shape and current cell.

interface TableContext

TableRightEdgeResizeTargetinterfaceSource ↗

Last grid column and table width addressed by an outer-right-edge resize gesture.

sourceRevision follows the same rule as [TableColumnDividerResizeTarget](TableColumnDividerResizeTarget): the package revision of the layout the target was read from, and commit refuses once it no longer equals the current one.

interface TableRightEdgeResizeTarget

TableRowinterfaceSource ↗

One table row. Cell count may vary between rows: colSpan and vertical merges reshape it.

interface TableRow

TableRowOccurrenceTargetinterfaceSource ↗

Explicit row occurrence. sourceRevision per [TableColumnDividerResizeTarget](TableColumnDividerResizeTarget).

interface TableRowOccurrenceTarget

TextMatchinterfaceSource ↗

One occurrence of a search query in the document.

Carries TWO addresses on purpose. blockId + start is the engine's own: stable across edits and independent of ordering. paragraphIndex + runIndex + runOffset is the positional one a find/replace UI needs to show and navigate results, and it is derived from the same walk rather than left to the caller to reconstruct — a caller guessing at run boundaries would send the selection to the wrong place.

A match can span runs when formatting changes mid-word; the run address is where it STARTS. scope identifies a non-body story so navigation opens the correct surface. A frame scope selects its anchoring drawing and never places a caret inside its story. A match inside a field result reports the field atom's model range. Its length is one, while text carries the visible match and can be longer. Select with start and length. Never derive the selected length from text.length.

interface TextMatch

ThemeinterfaceSource ↗

theme1.xml — what a [ColorValue](ColorValue) of kind theme resolves against.

interface Theme

TimingSummaryinterfaceSource ↗

Timings of one kind over a performance window. Every value is in milliseconds, rounded to whole milliseconds.

interface TimingSummary

ValidatedImageBytesHandleinterfaceSource ↗

Opaque handle — bytes are reachable only through [mintValidatedImageBytes](mintValidatedImageBytes).

interface ValidatedImageBytesHandle

WatermarkinterfaceSource ↗

A document watermark: text or a picture drawn behind the text of every page.

Set text for a text watermark or imageData for a picture watermark, never both. Omitted options take the defaults in each field's description. The watermark goes into every header the document shows; a section with no header gets one.

Text options apply only with text; scale and washout apply only with imageData. setWatermark refuses a mixed or out-of-range value with invalidArgs and a reason naming the field, and writes nothing.

interface Watermark

```ts
// A red, horizontal text watermark at 72pt.
editor.exec({
  type: 'setWatermark',
  watermark: { text: 'CONFIDENTIAL', color: 'C00000', fontSizePt: 72, layout: 'horizontal' },
});
// A washed-out picture watermark at its natural size.
editor.exec({ type: 'setWatermark', watermark: { imageData: pngBytes, scale: 1 } });
```

WatermarkStateinterfaceSource ↗

The watermark a document shows, as Editor.getWatermark() reads it.

The text fields are present for a text watermark, washout for a picture watermark.

interface WatermarkState

BlocktypeSource ↗

Anything that can sit at block level in a story. Discriminate on kind.

type Block = Paragraph | Table | ContentControl;

BookmarkPlacetypeSource ↗

Where a bookmark is, finer than [BookmarkStory](BookmarkStory): the main text, a header, a footer, a footnote or an endnote.

type BookmarkPlace = 'body' | 'header' | 'footer' | 'footnote' | 'endnote';

BookmarkStorytypeSource ↗

Which kind of story a bookmark is in: the main text, a header or footer, or a note.

type BookmarkStory = 'body' | 'headerFooter' | 'note';

ByteSizeBuckettypeSource ↗

A coarse size, in powers of two, so a size cannot single out one document. '0-64KiB' covers everything under 64 KiB; '512MiB+' everything above.

type ByteSizeBucket = '0-64KiB' | '64-128KiB' | '128-256KiB' | '256-512KiB' | '512KiB-1MiB' | '1-2MiB' | '2-4MiB' | '4-8MiB' | '8-16MiB' | '16-32MiB' | '32-64MiB' | '64-128MiB' | '128-256MiB' | '256-512MiB' | '512MiB+';

CanResulttypeSource ↗

Whether a command would be accepted, and why not when it would not.

The reason is the ENGINE's own words, which is what lets disabled chrome explain itself instead of guessing — see toolbarCommandState.

type CanResult = {
    ok: true;
} | {
    ok: false;
    code: ExecErrorCode;
    reason: string;
};

CollaborationDiagnosticCodetypeSource ↗

Why a collaboration session failed or refused work: collab. and the session's own public [CollaborationFailureCode](CollaborationFailureCode), such as collab.authentication-failed.

type CollaborationDiagnosticCode = `collab.${CollaborationFailureCode}`;

CollaborationFailureCodetypeSource ↗

Why a replica refused work, left ready, or failed a schema check.

Free-form extras (a transport phrase, a blob key, a store refusal) travel in [CollaborationFailure.detail](CollaborationFailure.detail), not here. Branch on the code; log the detail.

Codes are grouped by cause, and each group comment names the host action. In error, only a remote update that is not applied yet, or one refused local edit, heals on its own. The failure codes table in the collaboration reference lists every code. transport-disconnected and authentication-failed need opposite answers: wait for the first; refresh the credential and rejoin for the second. room-generation-changed means the server compacted the room while this replica was away: save a copy if it holds unsent changes, then rejoin.

type CollaborationFailureCode = 
/** Edit refused by the session gate. The status does not change. Wait for `ready`. */
'collaboration-session-destroyed' | 'collaboration-session-not-attached' | 'collaboration-session-not-ready' | 'collaboration-text-limit' | 'experimental-collaboration-body-text-only'
/** Factory input rejected before joining. Fix the value the host passed. */
 | 'invalid-document-id' | 'invalid-identity' | 'invalid-identity-color' | 'invalid-session-id'
/** Join or seed did not complete. Connect the provider, check the room id, and retry. */
 | 'already-initialized' | 'document-id-mismatch' | 'initialization-aborted' | 'initialization-timeout' | 'not-initialized'
/** The seed document cannot seed a room. Fix the file. */
 | 'baseline-too-large' | 'blob-read' | 'invalid-baseline' | 'missing-local-blob' | 'no-main-document-part'
/** This client and the room have different formats. Terminal. Save local work. */
 | 'collaboration-format-mismatch' | 'protocol-version-mismatch' | 'schema-version-mismatch'
/** The room is unusable. Terminal. Create a new room from saved bytes. */
 | 'blob-digest-mismatch' | 'concurrent-seed' | 'port-already-attached'
/** A remote update is not applied yet. Heals when a later update arrives. Wait. */
 | 'duplicate-paragraph-id' | 'invalid-relationships' | 'materialize-dropped-content' | 'missing-blob' | 'missing-root' | 'remote-apply-failed' | 'unknown-paragraph-id'
/** Over a resource limit. A local edit realigns; shared state over a limit is terminal. */
 | 'blob-store-full' | 'blob-too-large' | 'invalid-blob-descriptor' | 'invalid-bound' | 'invalid-logical-id' | 'invalid-string' | 'prototype-key' | 'text-too-long' | 'too-many-attributes' | 'too-many-children' | 'too-many-nodes' | 'too-many-parts' | 'too-many-relationships' | 'tree-too-deep' | 'unknown-logical-id' | 'unsafe-part-name'
/** Transport state. Only `transport-disconnected` recovers on its own. */
 | 'authentication-failed' | 'room-generation-changed' | 'transport' | 'transport-disconnected'
/** Reserved for a room server that refuses a saved room. Passed through, never emitted. */
 | 'invalid-saved-room' | 'saved-room-unavailable'
/** @deprecated Emitted by nothing. Kept for compatibility; do not branch on these. */
 | 'baseline-digest-mismatch' | 'experimental-collaboration-existing-paragraphs-only' | 'experimental-collaboration-text-only' | 'experimental-collaboration-untracked-text-only' | 'immutable-baseline-changed' | 'immutable-metadata-changed' | 'invalid-shared-metadata' | 'local-mirror-failed' | 'paragraph-set-mismatch' | 'shared-schema-invalid' | 'unsupported-root-key';

CollaborationStatustypeSource ↗

Lifecycle state of one collaboration replica.

One axis, because the only question a host has to answer is whether to tell the reader to wait or to reload:

- initializing — joining. Edits are refused. Recovers on its own. - ready — replicating. Accepts edits. - disconnected — the transport dropped. The replica is intact and recovers on its own, so wait rather than reload. Edits continue by default, and the buffered updates merge on reconnect. A session created with offlineEditing: false refuses them until reconnect. - error — this replica does not agree with the room. Edits are refused. [CollaborationStatusSnapshot.reason](CollaborationStatusSnapshot.reason) says why. A remote update the replica could not apply yet heals when a later update completes shared state ([CollaborationStatusSnapshot.recovering](CollaborationStatusSnapshot.recovering)). A format or version mismatch needs an upgrade of this client or the room; every other cause needs a rejoin. - destroyed — torn down. Terminal.

type CollaborationStatus = 'initializing' | 'ready' | 'disconnected' | 'error' | 'destroyed';

ColorValuetypeSource ↗

A colour as the FILE expresses it, not as a resolved RGB string.

A theme colour stays a theme reference — slot plus tint or shade — so that changing the theme repaints the document the way Word does. Flattening to hex at read time would freeze the resolved value and break that link. auto is Word's "let the renderer decide", usually black on white.

type ColorValue = {
    readonly kind: 'hex';
    readonly value: string;
} | {
    readonly kind: 'theme';
    readonly slot: string;
    readonly tint?: number;
    readonly shade?: number;
} | {
    readonly kind: 'auto';
};

CommentMarkerStyletypeSource ↗

How a collapsed comment marker looks.

- 'initials': a badge with the thread author's initials in the author's color, a reply count, and a check mark when the thread is resolved. - 'icon': the comment icon.

type CommentMarkerStyle = 'initials' | 'icon';

CompareDocumentsEngineErrorCodetypeSource ↗

Why the compare engine refused a compare, as a stable code: the codes that the engine, compareDocuments, and a background engine return. compareDocuments.errors.<code> in @docx-editor.dev/i18n translates every code.

type CompareDocumentsEngineErrorCode = 
/**
 * An option has a value of the wrong type, such as a `detectFormatChanges` that is not a
 * boolean, or the revised document is not a `Uint8Array`.
 */
'invalidOptions'
/** The original document is not a readable DOCX package. */
 | 'invalidOriginal'
/** The revised document is not a readable DOCX package. */
 | 'invalidRevised'
/** The documents exceed the compare's size limits. */
 | 'tooLarge'
/**
 * The original document enforces protection that the compare would break: read-only,
 * comments, forms, or tracked-changes protection. A compare also writes differences that
 * have no tracked form, such as style definitions and content control properties, so
 * tracked-changes protection refuses too.
 */
 | 'protected'
/** The differences include content that no tracked change can record. */
 | 'unsupportedContent';

CompareDocumentsErrorCodetypeSource ↗

Why a compare was refused, as a stable code. compareDocuments.errors.<code> in @docx-editor.dev/i18n translates every code. The engine and compareDocuments return [CompareDocumentsEngineErrorCode](CompareDocumentsEngineErrorCode) values. The editor command and dialog can also return the editor-only codes.

type CompareDocumentsErrorCode = CompareDocumentsEngineErrorCode
/** Editor only: no review module, no open document, or no mount. */
 | 'unavailable'
/** Editor only: a collaboration session is attached. */
 | 'collaboration'
/** Editor only: the document is open for viewing only. */
 | 'viewing'
/** Editor only: the dialog closed, or the compare was canceled, before it finished. */
 | 'closed'
/** Editor only: the revised file is a `Uint8Array` with no bytes. */
 | 'empty'
/**
 * Editor only: another compare of the same dialog runs, or a preview or an external document
 * refresh blocks writes to the document. Try again when it ends.
 */
 | 'busy'
/**
 * Editor only: the open document changed while a background compare ran, so its result
 * no longer applies. The editor never retries by itself.
 */
 | 'documentChanged'
/** Editor only: any other failure. */
 | 'failed';

CompareDocumentsOutcometypeSource ↗