@docx-editor.dev/core/binding

bodyParagraphsfunctionSource ↗

Body paragraphs of a part, in document order.

declare function bodyParagraphs(part: OoxmlPart): OoxmlNode[];

docToTreeOpsfunctionSource ↗

Map an edited ProseMirror doc back into typed tree ops (task 6.2), or refuse (6.3).

Handles a paragraph count delta of 0 (in-place edits), +1 (a clean split) and -1 (a clean join). Anything else — a reorder, a multi-paragraph paste, a structural change combined with an edit elsewhere — is refused rather than approximated, because the approximation is what silently loses content.

declare function docToTreeOps(part: OoxmlPart, doc: Node): MapResult;

mountTreeSurfacefunctionSource ↗

Mount an editable ProseMirror view over a session's body story.

The reference binding, not the production surface — mountPaginatedSurface is what the shipped editor uses. This one exists to exercise the tree↔ProseMirror contract directly, without pagination or painting in the way.

Call [TreeSurface.destroy](TreeSurface.destroy) to release the view.

declare function mountTreeSurface(mount: HTMLElement, session: TreeDocxSession, options?: TreeSurfaceOptions): TreeSurface;

openTreeSessionfunctionSource ↗

Open DOCX bytes into a tree-backed session.

Returns a typed rejection rather than throwing: every failure here is a property of the FILE, and a host needs to tell "this is not a package" from "this package is malicious" from "this document has no body".

The read is BOUNDED — decompression ratio, part count, XML depth and element counts are all capped — because the bytes are untrusted by definition.

declare function openTreeSession(bytes: Uint8Array, options?: OpenTreeSessionOptions): OpenTreeSessionResult;

partHasNodefunctionSource ↗

Whether a tree node id is still present, for reconciliation checks.

declare function partHasNode(part: OoxmlPart, nodeId: string): boolean;

reconcileDocfunctionSource ↗

Rebuild a projected doc from a new tree revision, reusing untouched paragraphs (task 6.4).

A full reprojection is always CORRECT, so this only ever narrows the work: paragraphs the change did not name are carried over by reference, which lets ProseMirror keep their node identity and redraw nothing. When the change is structural — a paragraph created, deleted, split or joined — positions shift in ways a per-paragraph patch cannot express, so it falls back to a full projection rather than guessing.

Passing null means "no evidence available", which also takes the full path. Reconciling on partial evidence is how a projection silently diverges from the model.

declare function reconcileDoc(previousDoc: Node, part: OoxmlPart, change: {
    readonly dirty: readonly string[];
    readonly created: readonly string[];
    readonly deleted: readonly string[];
    readonly splitJoin: readonly unknown[];
} | null): Node;

runPropsOffunctionSource ↗

The accepted run properties carried by a text node, or an empty list.

declare function runPropsOf(node: Node): readonly OoxmlProperty[];

treeToDocfunctionSource ↗

Project one tree revision into a ProseMirror doc (task 6.1).

declare function treeToDoc(part: OoxmlPart): Node;

DocumentStyleEntryinterfaceSource ↗

One w:style definition, projected for a style picker.

interface DocumentStyleEntry

ParagraphAttrsinterfaceSource ↗

Attributes carried by a projected paragraph.

interface ParagraphAttrs

TreeApplyResultinterfaceSource ↗

What applying ops produced: whether it committed, and why not when it did not.

committed and rejected are separate flags because they are not opposites — a batch of zero ops neither commits nor is rejected.

interface TreeApplyResult

TreeDocxSessioninterfaceSource ↗

One open document: the canonical tree, and the only write path into it.

applyTreeOps is that path. Every mutation is a TreeDocOp addressed by node id plus UTF-16 offset, applied in one transaction, which is what makes cell and nested paragraphs ordinary rather than special cases.

Holds the whole package, not just the body — headers, footers, notes, comments and styles are all reachable through it, and parts the engine does not model are preserved verbatim.

interface TreeDocxSession

TreeSurfaceinterfaceSource ↗

A mounted ProseMirror view bound to a [TreeDocxSession](TreeDocxSession).

Every committed transaction becomes tree ops through the binding; a transaction the binding cannot explain is refused and reported through [TreeSurfaceState.lastRejection](TreeSurfaceState.lastRejection), leaving the tree untouched.

interface TreeSurface

TreeSurfaceOptionsinterfaceSource ↗

How a tree surface is mounted.

interface TreeSurfaceOptions

TreeSurfaceStateinterfaceSource ↗

Everything observable about a mounted tree surface.

lastRejection is part of the state rather than a thrown error because a refused edit is an ordinary outcome here — the binding refuses anything it cannot explain, and the host shows why instead of the edit vanishing.

interface TreeSurfaceState

MapResulttypeSource ↗

The ops explaining one edit, or the reason it could not be explained.

ops is the SMALLEST set that accounts for the difference, so anything the projection does not model — unknown nodes, lexical form, node identities — stays carried by the tree rather than round-tripping through the editor.

type MapResult = {
    readonly ok: true;
    readonly ops: readonly TreeDocOp[];
} | {
    readonly ok: false;
    readonly reason: TreeBindingRejection;
    readonly detail?: string;
};

OpenTreeSessionResulttypeSource ↗

An open session, or a typed refusal.

A result rather than a throw: every failure here is a property of the FILE, and a host needs to tell "this is not a package" from "this package is malicious" from "this document has no body".

type OpenTreeSessionResult = {
    readonly ok: true;
    readonly session: TreeDocxSession;
} | {
    readonly ok: false;
    readonly reason: TreeSessionRejection;
    readonly detail?: string;
};

StoryScopetypeSource ↗

Editable story target.

Body and headerFooter mirror EditorScope. Notes use one lazy store per notes part (notesPart) — not one store per note — resolved through safe document relationships.

type StoryScope = {
    readonly kind: 'body';
} | {
    readonly kind: 'headerFooter';
    readonly rId: string;
} | {
    readonly kind: 'notesPart';
    readonly noteKind: NoteKind;
};

StoryTargetRejectiontypeSource ↗

Why a story scope could not be resolved to a part.

Several of these are FILE-hostile shapes rather than caller mistakes: external-relationship and bad-relationship-target are how a crafted document tries to point a story at something outside the package, and both are refused rather than followed.

type StoryTargetRejection = 'unknown-scope' | 'dangling-relationship' | 'wrong-relationship-type' | 'external-relationship' | 'bad-relationship-target' | 'missing-part' | 'not-a-story-part' | 'too-many-story-stores';

TreeBindingRejectiontypeSource ↗

Why an edited projection could not be mapped back into tree ops.

A refusal, not a fallback. The reverse direction never RECONSTRUCTS the tree from the projection — it explains a difference — so a shape it cannot explain is rejected outright. A silently-dropped edit is worse than a refused one, because only the refusal can be reconciled.

type TreeBindingRejection = 'paragraph-count-unexplained' | 'paragraph-reordered' | 'unknown-paragraph-id' | 'unknown-content-moved' | 'unsupported-node' | 'split-not-clean' | 'join-not-clean';

TreeSessionRejectiontypeSource ↗

Why bytes could not be opened: any bounded-reader rejection, plus the package that parsed but carried no main document tree.

type TreeSessionRejection = OoxmlPackageRejection | 'no-main-document-tree';

PROJECTION_ORIGINconstSource ↗

The origin a host should use when committing a reconciliation rather than a user edit.

PROJECTION_ORIGIN: "dev.docx-editor.core.origin.projection"

treeSchemaconstSource ↗

The ProseMirror schema the canonical tree projects into.

Deliberately minimal. It models only what an editing surface must manipulate directly — paragraphs, text, tabs, breaks, and run properties as marks — because everything it does NOT model stays on the tree and is preserved losslessly there. Widening this schema moves content out of the tree's custody, which is the opposite of what it is for.

The node and mark unions are written out rather than inferred from the spec below. Inferred, tsup's dts worker emits their members in an order that varies run to run, so the generated binding.api.md differed between builds of identical source and api:check failed at random. An explicit annotation pins the emitted order. Adding a node or mark to the spec means adding it here too — the compiler rejects the assignment otherwise.

treeSchema: Schema<'doc' | 'paragraph' | 'text' | 'tab' | 'hardBreak' | 'pageBreak' | 'unknownInline', 'runProps'>