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

resolveEditorModulesfunctionSource ↗

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

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

CollaborationModuleContributioninterfaceSource ↗

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

interface CollaborationModuleContribution

CommentRecordinterfaceSource ↗

One comment as authored in word/comments.xml.

interface CommentRecord

CompareDocumentsDialoginterfaceSource ↗

Compare documents dialog supplied by the review module.

interface CompareDocumentsDialog

CompareDocumentsDialogHostinterfaceSource ↗

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

interface CompareDocumentsDialogHost extends CompareDocumentsDialogSession

CompareDocumentsDialogSessioninterfaceSource ↗

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

interface CompareDocumentsDialogSession

CompareDocumentsEngineOptionsinterfaceSource ↗

Options of one document compare.

interface CompareDocumentsEngineOptions

CompareDocumentsProgressinterfaceSource ↗

How far a background compare is.

interface CompareDocumentsProgress

CompareDocumentsRequestinterfaceSource ↗

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

interface CompareDocumentsRequest

ContentTypeIndexinterfaceSource ↗

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

interface ContentTypeIndex

EditorModuleinterfaceSource ↗

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

interface EditorModule

EditorModuleRegistryinterfaceSource ↗

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

interface EditorModuleRegistry

OoxmlExternalTargetinterfaceSource ↗

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

interface OoxmlExternalTarget

OoxmlPackageinterfaceSource ↗

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

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

interface OoxmlPackage

OoxmlPartinterfaceSource ↗

One XML part of the package, parsed into a canonical tree.

interface OoxmlPart

RelationshipRecordinterfaceSource ↗

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

interface RelationshipRecord

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

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

ReviewModelInputinterfaceSource ↗

What the review queue derivation reads: one story part plus its comment parts.

interface ReviewModelInput

ReviewModuleContributioninterfaceSource ↗

What a review module contributes: the queue derivation, and the revision display modes the editor may enter beyond the free tier's final-state projection.

interface ReviewModuleContribution

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

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

RevisionMarkupDialoginterfaceSource ↗

Viewer settings dialog supplied by the review module.

interface RevisionMarkupDialog

RevisionMarkupDialogHostinterfaceSource ↗

Local settings access for review chrome. No document mutations occur here.

interface RevisionMarkupDialogHost extends RevisionMarkupDialogSession

CollectReviewItemstypeSource ↗

Derives the review queue — every pending revision decision and comment thread — from one story part plus its comment parts. Implemented by the pro review module; the free engine has no implementation and reports an empty queue.

type CollectReviewItems = (input: ReviewModelInput) => readonly ReviewItem[];

CompareDocumentsBackgroundEnginetypeSource ↗

Runs a compare off the page's main thread, for example in a worker. The editor's Compare documents dialog uses it when the review module provides one. It reports progress, and it stops when signal aborts: the promise then rejects with the signal's reason.

type CompareDocumentsBackgroundEngine = (original: Uint8Array, revised: Uint8Array, options: CompareDocumentsEngineOptions, control: {
    readonly signal: AbortSignal;
    readonly onProgress: (progress: CompareDocumentsProgress) => void;
}) => Promise<CompareDocumentsBackgroundResult>;

CompareDocumentsBackgroundResulttypeSource ↗

Result of one background compare: like [CompareDocumentsEngineResult](CompareDocumentsEngineResult), as bytes.

type CompareDocumentsBackgroundResult = {
    readonly ok: true;
    readonly bytes: Uint8Array | null;
    readonly revisionCount: number;
    readonly changed: boolean;
} | {
    readonly ok: false;
    readonly code: CompareDocumentsEngineErrorCode;
    readonly reason?: CompareDocumentsRefusalReason;
    readonly message: string;
};

CompareDocumentsEnginetypeSource ↗

Compares the open document (the original) with a revised DOCX and returns the original with the differences as tracked changes. Synchronous, DOM-free, and free of side effects.

type CompareDocumentsEngine = (original: OoxmlPackage, revised: Uint8Array, options: CompareDocumentsEngineOptions) => CompareDocumentsEngineResult;

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

CompareDocumentsEngineResulttypeSource ↗

Result of one document compare.

type CompareDocumentsEngineResult = {
    readonly ok: true;
    readonly package: OoxmlPackage;
    readonly revisionCount: number;
    readonly changed: boolean;
} | {
    readonly ok: false;
    readonly code: CompareDocumentsEngineErrorCode;
    readonly reason?: CompareDocumentsRefusalReason;
    readonly message: string;
};

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

ReviewDisplayModetypeSource ↗

The views the review chrome offers, in Word's terms: the three layout projections plus Simple Markup, which reads as the proposed result with a red change bar beside every line a change touched — the document as accepting everything would leave it, and where.

type ReviewDisplayMode = RevisionDisplayMode | 'simple-markup';

ReviewItemtypeSource ↗

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

The store's own derivation (collectReviewItems) only ever produces the first two; the kind: 'custom' card is contributed by the pro review module, which recognizes the node.

type ReviewItem = ReviewRevisionItem | ReviewCommentItem | ReviewCustomItem;

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

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

TargetModetypeSource ↗

Whether a relationship points inside the package or out of it.

The security-relevant distinction: an External target is retained VERBATIM and never owner-resolved or fetched, because auto-loading a file-supplied remote target is a zero-click external fetch.

type TargetMode = 'Internal' | 'External';