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

EditorFontErrorclassSource ↗

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

declare class EditorFontError extends Error

AuthoredNoteNumberinginterfaceSource ↗

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

interface AuthoredNoteNumbering

CommentRecordinterfaceSource ↗

One comment as authored in word/comments.xml.

interface CommentRecord

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

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

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

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

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

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.

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

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

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

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

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

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

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

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

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

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 after document/section cascade.

interface ResolvedNoteNumbering

ReviewActivationOptionsinterfaceSource ↗

How activating a review item places it in the viewport.

interface ReviewActivationOptions

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

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.

Both fields exist to keep the review rail cheap: filtering revision kinds is how a host hides structural cards it has no UI for, and placement: false skips the layout pass entirely when only metadata is wanted.

interface ReviewItemQuery

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

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: its numeric id plus the PART it lives in.

Both, 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.

interface RevisionAddress

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

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

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 captured from the store revision when the target is built. Commit MUST refuse when it does not equal the current store revision, even if an older layout remains published for geometry.

interface TableColumnDividerResizeTarget

TableColumnOccurrenceTargetinterfaceSource ↗

Explicit column occurrence for furniture/context commands.

interface TableColumnOccurrenceTarget

TableContextinterfaceSource ↗

Where the caret sits inside a table: the table's shape, and the cell holding it.

Null from the tableContext query when the selection is not in a table at all, which is how table-only chrome decides whether to render.

interface TableContext

TableRightEdgeResizeTargetinterfaceSource ↗

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

sourceRevision is captured from the store revision when the target is built. Commit MUST refuse when it does not equal the current store revision, even if an older layout remains published for geometry.

interface TableRightEdgeResizeTarget

TableRowinterfaceSource ↗

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

interface TableRow

TableRowOccurrenceTargetinterfaceSource ↗

Explicit row occurrence for furniture/context commands.

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.

interface TextMatch

ThemeinterfaceSource ↗

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

interface Theme

ValidatedImageBytesHandleinterfaceSource ↗

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

interface ValidatedImageBytesHandle

WatermarkinterfaceSource ↗

A watermark, which OOXML expresses as either text or an image — never both meaningfully.

interface Watermark

BlocktypeSource ↗

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

type Block = Paragraph | Table | ContentControl;

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

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

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

DocumentEditingModetypeSource ↗

How a keystroke reaches the document.

'suggesting' changes what an edit MEANS rather than whether it is allowed: typing writes w:ins and deleting writes w:del over the words it would have removed, so every change arrives as a proposal somebody else accepts or rejects.

type DocumentEditingMode = 'editing' | 'suggesting' | 'viewing';

DocumentSourcetypeSource ↗

What createDocxEditor/load accept as a document: raw DOCX bytes, or an existing in-memory DocumentHandle (shared/handed off). The engine is byte-native (PackageModel is canonical); there is intentionally no structured-tree input, which would be lossy against the canonical package.

type DocumentSource = ArrayBuffer | Uint8Array | DocumentHandle;

DrawingHorizontalReferenceFrametypeSource ↗

type DrawingHorizontalReferenceFrame = 'character' | 'column' | 'insideMargin' | 'leftMargin' | 'margin' | 'outsideMargin' | 'page' | 'rightMargin';

DrawingKindtypeSource ↗

Whether a drawing sits in the text flow or is positioned against a frame.

The distinction that decides everything downstream: an inline drawing occupies a character position, while an anchored one has offsets relative to a page, margin or column.

type DrawingKind = 'inline' | 'anchored';

DrawingVerticalReferenceFrametypeSource ↗

type DrawingVerticalReferenceFrame = 'bottomMargin' | 'insideMargin' | 'line' | 'margin' | 'outsideMargin' | 'page' | 'paragraph' | 'topMargin';

EditorCommandtypeSource ↗

One command, as a discriminated union derived from [EditorCommands](EditorCommands).

This is what can and exec take. Widening EditorCommands widens it automatically.

type EditorCommand = {
    [K in keyof EditorCommands]: {
        type: K;
    } & EditorCommands[K];
}[keyof EditorCommands];

EditorCommandShapetypeSource ↗

In the editor a command targets the current selection unless told otherwise, and authoring is ambient — the author comes from DocxEditorConfig/the session, the way the Office JS API sources it from context — so the document layer's required target and author both become optional here.

type EditorCommandShape<T> = {
    [K in keyof T]: Omit<T[K], 'target' | 'author'> & (T[K] extends {
        target: infer G;
    } ? {
        target?: G;
    } : unknown) & (T[K] extends {
        author: infer A;
    } ? {
        author?: A;
    } : unknown);
};

EditorFontErrorCodetypeSource ↗

Why a font was not admitted.

Distinguished rather than collapsed because the responses differ: overLimit and malformed are the caller's own bytes, while forbidden and hashMismatch mean the source was not what it claimed and the load should not be retried.

type EditorFontErrorCode = 'initializationFailed' | 'missing' | 'forbidden' | 'overLimit' | 'malformed' | 'hashMismatch' | 'metadataMismatch' | 'fontFaceLoadFailed' | 'unsupportedFaceIndex' | 'missingFont' | 'hashInvalid' | 'fontMismatch' | 'unsupportedFace' | 'loadFailed';

EditorPositiontypeSource ↗

A selection endpoint, in either vocabulary the engine resolves.

[DocAnchor](DocAnchor) addresses a paragraph by its w14:paraId, which is what an LLM or an automation script can name in a payload. [SemanticPosition](SemanticPosition) addresses it by the paragraph id the painted surface and the ops already use, with a UTF-16 offset inside it.

Neither subsumes the other. A paraId survives being written to a file and read back, so it is the one an out-of-process caller can hold; but it is OPTIONAL in the document, and ParagraphSummary.paraId says so — a paragraph the file gave no w14:paraId cannot be reached by a DocAnchor at all. The paragraph id reaches every paragraph.

type EditorPosition = DocAnchor | SemanticPosition;

EditorQuerytypeSource ↗

One query, as a discriminated union derived from [EditorQueries](EditorQueries).

This is what query takes; [EditorQueryResults](EditorQueryResults) says what each answers.

type EditorQuery = {
    [K in keyof EditorQueries]: {
        type: K;
    } & EditorQueries[K];
}[keyof EditorQueries];

EditorScopetypeSource ↗

The editor is N+1 editing views: one body plus one per header/footer relationship, plus footnotes, text boxes, and other addressable regions. Commands must say which one they target, or they silently hit the wrong surface when a header is focused.

Intentionally open-ended: this set is expected to grow (notes, frames, and whatever regions later prove addressable), so treat it as non-exhaustive rather than a closed enum.

type EditorScope = {
    kind: 'body';
} | {
    kind: 'headerFooter';
    rId: string;
}
/**
 * A footnote/endnote region.
 *
 * `id` encodes kind + signed note id as `footnote:<id>` or `endnote:<id>`
 * (e.g. `footnote:2`). Use `formatNoteScopeId` / `parseNoteScopeId` from the
 * store package. Do not invent a parallel `{ noteKind, noteId }` scope arm.
 */
 | {
    kind: 'note';
    id: string;
}
/** A text box or floating frame with its own content, addressed by id. */
 | {
    kind: 'frame';
    id: string;
}
/** Read-only aggregate across every view. Valid for queries, not for writes. */
 | {
    kind: 'all';
};

EditorSelectiontypeSource ↗

A selection, in one endpoint vocabulary or the other.

The two do NOT mix: a range is a pair of paraId anchors, or a semantic anchor/head pair, and can() refuses anything else with the engine's own reason. Spelled as two arms rather than { from: EditorPosition; to: EditorPosition } for exactly that reason — the looser shape would type a mixed pair the engine rejects at runtime.

type EditorSelection = SemanticSelection | {
    from: DocAnchor;
    to: DocAnchor;
};

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;
} | {
    ok: false;
    code: ExecErrorCode;
    reason: string;
    target?: DocTarget;
};

FurnitureVarianttypeSource ↗

Furniture variant selected by section title-page / even-and-odd flags.

type FurnitureVariant = 'default' | 'first' | 'even';

ImageContexttypeSource ↗

The selected image and what may be done to it — the imageContext query's answer.

An alias of SelectedImageState, kept as its own name because it is the query's result type and chrome is written against it.

type ImageContext = SelectedImageState;

ImageResourceStatetypeSource ↗

What is known about one embedded image: validated, refused, or still decoding.

Content type is a CLAIM. Signature sniffing, structural header validation and the decode port are authoritative, and bytes that fail them never enter public state.

type ImageResourceState = {
    readonly kind: 'ready';
    readonly partName: string;
    readonly contentId: string;
    readonly resourceKey: string;
    readonly validatedHandle: ValidatedImageBytesHandle;
    readonly mime: RenderableImageMime;
    readonly pixelWidth: number;
    readonly pixelHeight: number;
    readonly dpiX: number;
    readonly dpiY: number;
} | {
    readonly kind: 'unrenderable';
    readonly partName: string | null;
    readonly mime: RenderableImageMime | PreservedImageMime | 'unknown';
    readonly reason: 'unsupported-format' | 'non-picture-graphic' | 'signature-mismatch' | 'decode-failed' | 'resource-limit';
} | {
    readonly kind: 'external';
    readonly relationshipId: string;
    readonly sinkSafe: boolean;
} | {
    readonly kind: 'missing';
    readonly relationshipId: string;
} | {
    readonly kind: 'pending';
    readonly resourceKey: string;
};

ImageWrapTargettypeSource ↗

Nine Word wrap menu targets (inline plus eight floating modes).

type ImageWrapTarget = 'inline' | 'square' | 'squareLeft' | 'squareRight' | 'tight' | 'through' | 'topAndBottom' | 'behind' | 'inFront';

InteractionAffinitytypeSource ↗

Bidi/grapheme affinity for a text caret or hit target.

type InteractionAffinity = 'upstream' | 'downstream';

InteractionOutcometypeSource ↗

The result of one interaction attempt.

A rejection carries the ENGINE's own reason, which is what lets a caller surface why an interaction was refused instead of guessing.

type InteractionOutcome<T> = {
    readonly ok: true;
    readonly value: T;
} | {
    readonly ok: false;
    readonly code: InteractionOutcomeCode;
    readonly reason: string;
};

InteractionOutcomeCodetypeSource ↗

Typed rejection for pending, read-only, invalid, or unsupported interaction.

type InteractionOutcomeCode = 'pendingLayout' | 'pendingSelection' | 'readOnly' | 'invalidTarget' | 'unsupported';

NoteKindtypeSource ↗

Footnote vs endnote — the public Editor vocabulary.

type NoteKind = 'footnote' | 'endnote';

PreservedImageMimetypeSource ↗

Media kept in the package byte-for-byte that the painter cannot hand to an <img>. A decode port may rasterize it; without one it paints as a labelled placeholder.

type PreservedImageMime = 'image/tiff' | 'image/x-emf' | 'image/x-wmf';

RenderableImageMimetypeSource ↗

Every mime the painter can hand to an <img>.

type RenderableImageMime = SupportedImageMime | VectorImageMime;

ReviewItemtypeSource ↗

One pending decision in the review queue: a tracked change, a comment thread, or a pro custom-node card. Discriminate on kind.

type ReviewItem = ReviewRevisionItem | ReviewCommentItem | ReviewCustomItem;

ReviewItemPlacementtypeSource ↗

A DISCRIMINATED union on [ReviewItemPlacementBase.kind](ReviewItemPlacementBase.kind): narrowing the kind narrows item and the kind-specific fields with it, so a consumer never writes the placement.kind === 'custom' && placement.item.kind === 'custom' double check.

type ReviewItemPlacement = ReviewCommentPlacement | ReviewRevisionPlacement | ReviewCustomPlacement;

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 deletion and an insertion that are one edit: text typed over a selection.
 *
 * Word shows these as a single `Replaced "x" with "y"` card, and resolving one half
 * without the other is never what the reviewer meant — accepting the deletion alone
 * leaves the replacement text unproposed, rejecting it alone leaves both.
 */
 | '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';

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

SemanticTargettypeSource ↗

A PM-free semantic caret, range endpoint, or atomic selection target.

type SemanticTarget = {
    readonly kind: 'text';
    readonly scope: ViewScope;
    readonly identity: SemanticIdentity;
    readonly graphemeOffset: number;
    readonly affinity: InteractionAffinity;
} | {
    readonly kind: 'atomic';
    readonly scope: ViewScope;
    readonly objectId: string;
};

SupportedImageMimetypeSource ↗

Raster media the decode port measures and any authoring path may write.

BMP and WebP are here for the same reason the other three are: an <img> decodes them natively, so they need a signature and a structural header and nothing else. BMP is what older documents carry; WebP is what current Word writes.

type SupportedImageMime = 'image/png' | 'image/jpeg' | 'image/gif' | 'image/bmp' | 'image/webp';

TableBorderEdgeTargettypeSource ↗

Concrete scopes that apply a complete border spec.

type TableBorderEdgeTarget = Exclude<TableBorderTarget, 'none'>;

TableBorderStyletypeSource ↗

Allowlisted OOXML table border line styles.

Kept identical to store/table-border-style.ts; table-border-style-parity.test-d.ts fails if the contract and store vocabularies drift.

type TableBorderStyle = 'single' | 'dashed' | 'dotted' | 'double' | 'triple' | 'thick';

TableBorderTargettypeSource ↗

Which cell edges a table border command targets.

type TableBorderTarget = 'all' | 'outside' | 'inside' | 'none' | 'top' | 'bottom' | 'left' | 'right';

TableCellVerticalAlignmenttypeSource ↗

Vertical placement of content inside selected table cells.

type TableCellVerticalAlignment = 'top' | 'center' | 'bottom';

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;

VectorImageMimetypeSource ↗

Vector media painted straight from validated bytes. An <img> renders SVG in the browser's secure static mode — no script, no external subresource loads — so there is no decode step and no raster buffer sized by a file-supplied number.

type VectorImageMime = 'image/svg+xml';

ViewScopetypeSource ↗

A concrete editing view — every scope except the read-only all aggregate.

type ViewScope = Exclude<EditorScope, {
    kind: 'all';
}>;