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

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

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

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

DocLocationinterfaceSource ↗

Structural addressing for content the paraId map cannot reach.

interface DocLocation

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

DocumentProtectionStateinterfaceSource ↗

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

interface DocumentProtectionState

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

ExtentinterfaceSource ↗

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

interface Extent

FontDefinitioninterfaceSource ↗

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

interface FontDefinition

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

HistoryGroupOutcomeinterfaceSource ↗

The history authority's result for this frame.

interface HistoryGroupOutcome

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

NumberingRefinterfaceSource ↗

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

interface NumberingRef

PageMarginsinterfaceSource ↗

Page margins in twips.

interface PageMargins

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

ParagraphTabStopinterfaceSource ↗

One custom tab stop, as a command states it.

interface ParagraphTabStop

PointinterfaceSource ↗

A position in points.

interface Point

RectinterfaceSource ↗

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

interface Rect

ResolvedReviewPaneinterfaceSource ↗

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

interface ResolvedReviewPane

ResolvedRevisionMarkupinterfaceSource ↗

Fully resolved, immutable viewer preferences.

interface ResolvedRevisionMarkup

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

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

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

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

TableCellinterfaceSource ↗

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

interface TableCell

TableRowinterfaceSource ↗

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

interface TableRow

ThemeinterfaceSource ↗

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

interface Theme

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;

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 ↗

The outcome of one compare.

type CompareDocumentsOutcome = {
    readonly ok: true;
    readonly revisionCount: number;
    readonly changed: boolean;
} | {
    readonly ok: false;
    readonly code: CompareDocumentsErrorCode;
    readonly reason?: CompareDocumentsRefusalReason;
    readonly message: string;
};

CompareDocumentsPhasetypeSource ↗

A step of a compare that runs in the background. The steps run in this order:

1. reading: read both documents. 2. comparing: find their differences. 3. checking: check that accepting and rejecting all changes give back each document. 4. applying: apply the result to the open document.

type CompareDocumentsPhase = 'reading' | 'comparing' | 'checking' | 'applying';

CompareDocumentsRefusalReasontypeSource ↗

What an unsupportedContent refusal is about, as a stable code. compareDocuments.reasons.<reason> in @docx-editor.dev/i18n translates every reason.

type CompareDocumentsRefusalReason = 
/** The documents differ inside a content control that is locked or bound to data. */
'lockedContent'
/** A document holds tracked changes that cannot be accepted, so its final state is unknown. */
 | 'unresolvedRevisions'
/** The documents differ in content with no tracked-change form, such as an embedded file. */
 | 'untrackedContent'
/** The revised document adds section or table settings that a reject cannot restore. */
 | 'unrecordedSettings'
/** A header or footer of an earlier section cannot be paired with one of the original. */
 | 'headerFooter'
/** The result needs a part type that the original document does not declare. */
 | 'packageStructure'
/**
 * The result fails the check: accepting all changes does not give the revised text, rejecting
 * them does not give the original text, or a tracked change cannot be accepted or rejected.
 */
 | 'unverified';

ContainerReftypeSource ↗

Which STORY a location belongs to.

The body is one container; every header, footer and note is another. A path alone is ambiguous without it, because block index 0 exists in every story a document has.

type ContainerRef = {
    part: 'body';
} | {
    part: 'header' | 'footer';
    rId: string;
} | {
    part: 'footnote' | 'endnote';
    noteId: number;
};

ContentControlTypetypeSource ↗

Which kind of control a w:sdt is, and therefore what a value written into it must be.

type ContentControlType = 'richText' | 'plainText' | 'checkbox' | 'dropdown' | 'comboBox' | 'date' | 'picture' | 'buildingBlockGallery' | 'repeatingSection';

DocTargettypeSource ↗

Anything an operation can be pointed at: a paragraph-relative [DocAnchor](DocAnchor), a structural [DocLocation](DocLocation), or a [DocRange](DocRange) spanning two of them.

type DocTarget = DocAnchor | DocLocation | DocRange;

DocumentProtectionEdittypeSource ↗

ST_DocProtect: the restriction a document asks for. none also stands for "no element".

type DocumentProtectionEdit = 'none' | 'readOnly' | 'comments' | 'trackedChanges' | 'forms';

ExecErrorCodetypeSource ↗

Why a write was refused, as a value to branch on.

Deliberately finer-grained than a boolean: "no-op", "target not found" and "content control is locked" are different outcomes, and a caller retrying the first should not retry the third.

type ExecErrorCode = 'notFound' | 'ambiguous' | 'locked' | 'bound' | 'typeMismatch' | 'kindMismatch' | 'outOfBounds' | 'unsupported' | 'invalidArgs';

ExecResulttypeSource ↗

Every write returns this rather than boolean.

A bare boolean cannot distinguish "no-op" from "target not found" from "content control is locked", and the editor layer already throws eight distinct ContentControl error classes that a boolean would flatten.

type ExecResult = {
    ok: true;
    changed: boolean;
    revisions?: RevisionBatchResult;
    revisionAuthors?: RevisionAuthorResult;
    history?: HistoryGroupOutcome;
    compareDocuments?: CompareDocumentsOutcome;
} | {
    ok: false;
    code: ExecErrorCode;
    reason: string;
    target?: DocTarget;
    revisions?: RevisionBatchResult;
    compareDocuments?: CompareDocumentsOutcome;
    revisionAuthors?: RevisionAuthorResult;
};

InsertableContentControlTypetypeSource ↗

The control kinds an insertion can author.

A NARROWING of [ContentControlType](ContentControlType), not a separate vocabulary: a kind read off an existing control can be handed straight back to insertContentControl. Three kinds are absent because an insertion would have to invent what they carry — a checkbox needs its two declared glyph states, a picture needs an image part, a building block gallery needs a glossary to list, and a repeating section is a container whose items have their own verbs. Reading still answers the wider type; a document may hold kinds this cannot create.

dropDownList is the same kind as dropdown, spelt as OOXML spells it. Both are accepted, so a type read off a control can be handed back without translating it — and the OOXML spelling is the one the automation protocol takes, so a caller who uses both surfaces can write that one everywhere.

type InsertableContentControlType = Extract<ContentControlType, 'richText' | 'plainText' | 'dropdown' | 'comboBox' | 'date'> | 'dropDownList';

ReviewPaneOpeningtypeSource ↗

When the review pane opens by itself.

- 'auto': the pane opens when a document with review items loads, and when a tracked change is made while it is closed, in both cases when the pane has items to list. With revisionsIn: 'balloons' the pane lists no tracked change and no reply to one, so tracked changes and their replies alone do not open it. - 'manual': the pane stays closed until the host or the user opens it. Use it when the host shows review items its own way, such as in balloons or margin markers.

type ReviewPaneOpening = 'auto' | 'manual';

ReviewPaneOverflowtypeSource ↗

What the open review pane does when its full card column does not fit beside the page at the page's zoom.

- 'float': the pane shrinks to a strip of markers, and the open card floats over the page. - 'shrinkPage': under a fit zoom mode, the page may shrink down to the mode's minZoom (or 10%) so that the full column fits. The pane changes to the marker strip only when the column does not fit at that floor either. A fixed zoom behaves as 'float'. - 'scroll': the page keeps the size it has beside the closed pane's marker strip, and the full column stands beside it. The document and the column scroll together: the viewport scrolls sideways to reach the cards.

The setting applies to the review pane only. The navigation pane stays docked at its side in every mode: it never scrolls with the document, and it takes its room beside the page exactly as it does with no review pane.

type ReviewPaneOverflow = 'float' | 'shrinkPage' | 'scroll';

ReviewRevisionKindtypeSource ↗

What kind of decision a revision card represents.

Wider than the four content wrappers, because a reviewer has to be shown every pending decision, including the ones that decorate no characters. A card the surface cannot show is a change the reviewer never learns about — and acceptAllRevisions refuses if ANY revision in the document is one the engine cannot resolve, so an invisible one makes Accept All fail for a reason nothing on screen explains.

type ReviewRevisionKind = 'insert' | 'delete'
/**
 * A combined deletion and insertion decision. The built-in reader lists them separately,
 * unless a review query asks to pair replacements or a custom review provider combines them.
 */
 | 'replace' | 'moveFrom' | 'moveTo'
/** `w:rPrChange` / `w:pPrChange` — the words are unchanged, their formatting is not. */
 | 'format'
/** `w:pPr/w:rPr/w:ins|w:del` — a paragraph split or merge. */
 | 'paragraphMark'
/** A row, cell, section or grid revision. Supported row revisions are resolvable. */
 | 'structural';

RevisionAuthorSkipReasontypeSource ↗

Why a requested change keeps its attribution.

type RevisionAuthorSkipReason = 'unknown-revision' | 'unsupported-revision';

RevisionBatchSkipDetailtypeSource ↗

The structure behind a skip.

For unsupported-revision: a refused site, a formatting change whose earlier properties were not recorded so it cannot be rejected, a read-only review item, a change with no sites, a change a content control lock keeps (locked-content), or a change in a data-bound content control (bound-content). The last two have their own codes, review.locked-content and review.bound-content; reviewCodeOfSkip reads them.

For incomplete-group, the change the decision would also decide: the other half of a move or merge (paired-change), a change inside content the decision removes (removed-content) or inside properties a reject replaces (replaced-properties), a change the decision would empty (emptied-change), a change that encloses the selected one (enclosing-change), or another site of a group the planner keeps together (grouped-change).

For retained-structure: a row kept for the table nested in it (nested-table).

type RevisionBatchSkipDetail = RevisionSiteRefusal | 'unrecorded-properties' | 'read-only' | 'no-sites' | 'paired-change' | 'removed-content' | 'replaced-properties' | 'emptied-change' | 'enclosing-change' | 'grouped-change' | 'nested-table' | 'locked-content' | 'bound-content';

RevisionBatchSkipReasontypeSource ↗

Why a requested decision remains pending.

type RevisionBatchSkipReason = 'unsupported-revision' | 'incomplete-group' | 'retained-structure' | 'unknown-revision';

RevisionChangedLinesMarktypeSource ↗

type RevisionChangedLinesMark = 'none' | 'leftBorder' | 'rightBorder' | 'outsideBorder';

RevisionDeletionMarktypeSource ↗

type RevisionDeletionMark = RevisionMarkupMark | 'hidden' | 'caret' | 'pound';

RevisionDisplaytypeSource ↗

Where tracked changes open.

- 'pane': the review pane lists tracked changes as cards beside the comments. - 'balloons': the pane lists comments only, except comments that reply to a tracked change: the change's balloon shows those. A tracked change opens in a balloon at its text when the reader clicks it, or when Next Change, Previous Change, or setActiveReviewItem(key, { announce: true }) reaches it. A replacement is one balloon. In both settings, Next Change and Previous Change stop on a replacement once.

type RevisionDisplay = 'pane' | 'balloons';

RevisionDisplayModetypeSource ↗

Which revisions layout resolves before producing pages.

- all-markup shows both halves of every change. - proposed shows what the document becomes if every change is accepted. - original shows what it was before any of them.

The last two are specified as equal to accept-all and reject-all OUTPUT, which is what makes them testable, without either applying an op.

type RevisionDisplayMode = 'all-markup' | 'proposed' | 'original';

RevisionMarkupColortypeSource ↗

type RevisionMarkupColor = RevisionMarkupNamedColor | 'byAuthor' | 'auto';

RevisionMarkupMarktypeSource ↗

type RevisionMarkupMark = 'none' | 'colorOnly' | 'bold' | 'italic' | 'underline' | 'doubleUnderline' | 'strikethrough' | 'doubleStrikethrough';

RevisionMarkupNamedColortypeSource ↗

type RevisionMarkupNamedColor = (typeof REVISION_MARKUP_COLORS)[number];

RevisionMarkupOptionstypeSource ↗

Partial viewer preferences. Omitted values keep the previous value.

type RevisionMarkupOptions = {
    readonly [K in keyof ResolvedRevisionMarkup]?: ResolvedRevisionMarkup[K] extends boolean ? boolean : Partial<ResolvedRevisionMarkup[K]>;
};

RevisionSiteRefusaltypeSource ↗

Why a revision site cannot be resolved: no w:id or author, a content marker where content cannot be, a wrapper whose content is itself marked, a structural revision outside tables and numbering, or a move whose ranges do not pair up.

type RevisionSiteRefusal = 'unaddressed' | 'misplaced-marker' | 'nested-marker' | 'unsupported-structure' | 'unsupported-move';

RevisionTypetypeSource ↗

What kind of decision a revision represents.

Wider than insert/delete/format, and it has to be. w:moveFrom/w:moveTo are not a deletion and an insertion — resolving one half alone duplicates or loses the content; w:pPr/w:rPr/w:ins|w:del decorates no characters at all and merges paragraphs when resolved; a row or cell revision is structural. A reviewer shown only three kinds is a reviewer who never learns about the rest.

type RevisionType = 'insert' | 'delete'
/** A deletion and an insertion that are one edit: text typed over a selection. */
 | 'replace' | 'moveFrom' | 'moveTo'
/** `w:rPrChange` / `w:pPrChange` — the words are unchanged, their formatting is not. */
 | 'format'
/** `w:pPr/w:rPr/w:ins|w:del` — a paragraph split or merge. */
 | 'paragraphMark'
/** A row, cell, section or grid revision. */
 | 'structural';

SelectionPintypeSource ↗

Ownership token for one retained selection highlight.

type SelectionPin = symbol;

ThemeColorSchemetypeSource ↗

Theme colour slots (accent1, dk1, lt2, …) to hex.

type ThemeColorScheme = Readonly<Record<string, string>>;

UnsubscribetypeSource ↗

What every subscription returns. Calling it twice is safe.

type Unsubscribe = () => void;

WatermarkLayouttypeSource ↗

How a text watermark crosses the page.

type WatermarkLayout = 'diagonal' | 'horizontal';

COMPARE_DOCUMENTS_ACCEPTconstSource ↗

The accept value for a file input that picks the revised document: DOCX files only.

COMPARE_DOCUMENTS_ACCEPT = ".docx,application/vnd.openxmlformats-officedocument.wordprocessingml.document"

DEFAULT_REVIEW_PANEconstSource ↗

The settings an editor starts with when nothing sets them.

DEFAULT_REVIEW_PANE: ResolvedReviewPane

DEFAULT_REVISION_MARKUPconstSource ↗

Initial viewer preferences.

DEFAULT_REVISION_MARKUP: ResolvedRevisionMarkup

REVISION_MARKUP_COLORSconstSource ↗

Named revision colors. Identifiers are stable and never contain CSS.

REVISION_MARKUP_COLORS: readonly ['black', 'blue', 'turquoise', 'green', 'pink', 'red', 'yellow', 'white', 'darkBlue', 'teal', 'darkGreen', 'violet', 'darkRed', 'darkYellow', 'gray50', 'gray25', 'lightBlue', 'lightYellow', 'lightOrange', 'lightPurple', 'lightGreen', 'gray']