@docx-editor.dev/core/store

addCommentfunctionSource ↗

Add a comment, or a reply, in ONE transaction.

The comment id and the w14:paraId are computed before the transaction opens, because the story markers have to carry the same id the body does and deriving each separately is how the two come to disagree.

w14:paraId is minted here and only here: on a comment WRITE. Allocating on load would rewrite a document nobody edited and break fingerprint equality on an untouched round trip.

declare function addComment(store: TreeDocumentStore, request: AddCommentRequest): AddCommentResult;

allocateContentControlIdfunctionSource ↗

The next w:id to write, seeded from the document's own maximum plus one.

Never a clock, a timestamp, a random source or a hash: those collide with ids already in the file and produce values Word rejects. Null when the document already reaches the signed 32-bit bound, so the caller refuses rather than wrapping into a negative id.

declare function allocateContentControlId(root: OoxmlNode): number | null;

allocateDrawingPropertyIdfunctionSource ↗

Mint a wp:docPr id unused anywhere in the package.

Package-wide rather than per-part: Word treats these ids as document-global, and a collision makes it renumber on open.

declare function allocateDrawingPropertyId(pkg: OoxmlPackage): DrawingPropertyIdResult;

allocateNoteIdfunctionSource ↗

Allocate the next positive signed 32-bit note id for a notes-part root. Seeds from max(existing)+1; never returns ≤0; null on exhaustion.

declare function allocateNoteId(notesRoot: OoxmlNode): number | null;

applyEditsfunctionSource ↗

Apply several primitives as ONE atomic step.

Each edit runs against the result of the previous one, and the whole sequence is validated once at the end. If any step fails, the ORIGINAL part is what the caller keeps — there is no partially-edited intermediate to publish. This is the shape a multi-DocOp store transaction needs.

declare function applyEdits(part: OoxmlPart, edits: readonly ((current: OoxmlPart) => OoxmlEditResult)[], options?: EditOptions): OoxmlEditResult;

applyHeaderFooterLifecycleOpfunctionSource ↗

Apply one furniture lifecycle op atomically. Rejected ops leave the input package untouched (pure function — callers discard the result).

declare function applyHeaderFooterLifecycleOp(pkg: OoxmlPackage, op: HeaderFooterLifecycleOp): HeaderFooterLifecycleResult;

applyNoteLifecycleOpfunctionSource ↗

Apply one note lifecycle op atomically. Rejected ops leave the input package untouched.

declare function applyNoteLifecycleOp(pkg: OoxmlPackage, op: NoteLifecycleOp, options?: NoteLifecycleOptions): NoteLifecycleResult;

applyTreeOpfunctionSource ↗

Apply one validated op to a part.

Validation runs first and returns before any tree work, so a rejected op is a true no-op: the caller keeps the part it passed in, unchanged and still frozen.

options.deferValidation passes through to the edit primitives: a transaction applying many ops re-validates the whole part once at its commit boundary rather than after every primitive, which is the difference between a paste that is linear and one that is quadratic in document size.

declare function applyTreeOp(part: OoxmlPart, op: TreeDocOp, options?: EditOptions): TreeOpResult;

asciiFoldfunctionSource ↗

ASCII-only lowercase fold. OPC part-name/extension equivalence is US-ASCII case-insensitive; a locale toLowerCase() mis-folds e.g. Turkish I/İ and could let two "equivalent" part names evade duplicate detection.

declare function asciiFold(s: string): string;

assertLimitInvariantsfunctionSource ↗

Assert the finite-default / hard-ceiling invariant holds for every limit.

declare function assertLimitInvariants(): void;

assertValidIdfunctionSource ↗

Validate an identifier, throwing when it is malformed.

Throws rather than returning: a bad id is an author mistake at registration time, not file input, and accepting it would produce a registry whose identities silently collide.

declare function assertValidId(id: string, kind?: IdKind): void;

assertValidQNamefunctionSource ↗

Validate a qualified name, throwing when it is malformed.

Guards the serializer: an invalid QName written into XML produces a file Word cannot open, so it fails here rather than at save.

declare function assertValidQName(name: string): void;

atomicFieldSpansOffunctionSource ↗

Collect well-formed atomic field spans in document order.

Demotion (no span emitted — callers surface interior text normally): - end without matching begin - orphan instrText outside an open field - missing end before paragraph end - nesting deeper than maxNesting - instruction longer than maxInstructionChars (still forms a span when begin/end pair closes, but callers may treat evaluation as inert; addressing stays atomic)

Cross-paragraph fields never form: this walk is per paragraph.

declare function atomicFieldSpansOf(paragraph: OoxmlParagraphNode, options?: {
    readonly maxNesting?: number;
    readonly maxInstructionChars?: number;
}): readonly AtomicFieldSpan[];

atomicNoteSpansOffunctionSource ↗

Collect typed note atoms in document order (one segment each).

Walks the same paragraph-inline surface as segmentsOf / walkParagraphInline: hyperlinks and content controls flatten; only direct run children contribute atoms. A demoted run-inner SDT husk stays opaque — no phantom addressable hit.

declare function atomicNoteSpansOf(paragraph: OoxmlParagraphNode): readonly AtomicNoteSpan[];

authorableHyperlinkTargetfunctionSource ↗

The target this engine would write for url, or null when it would write none.

The VALIDATION half of [ensureHyperlinkRelationship](ensureHyperlinkRelationship), exported so a caller that must decide "would this be authored?" before it is allowed to change the package can ask without changing it. A relationship outlives a refusal — it lives beside the trees, outside the undo stack — so a caller planning a batch that may yet be refused has to ask this and mint later.

Same rules, one implementation: sanitizeHref's allowlist, a bound on the length, XML-writable text, and the absolute-URI gate the READ side applies. There is no legitimate reason for this engine to author a scheme it would refuse to open.

declare function authorableHyperlinkTarget(url: string): string | null;

authoredDocumentEndnotePropertiesfunctionSource ↗

Authored document-level endnotePr from settings.

declare function authoredDocumentEndnoteProperties(settings: OoxmlPart | null | undefined): AuthoredNoteProperties | undefined;

authoredDocumentFootnotePropertiesfunctionSource ↗

Authored document-level footnotePr from settings.

declare function authoredDocumentFootnoteProperties(settings: OoxmlPart | null | undefined): AuthoredNoteProperties | undefined;

authoredEndnotePropertiesFromSectPrfunctionSource ↗

Authored endnotePr on a sectPr node.

declare function authoredEndnotePropertiesFromSectPr(sectPr: OoxmlNode | null | undefined): AuthoredNoteProperties | undefined;

authoredFootnotePropertiesFromSectPrfunctionSource ↗

Authored footnotePr on a sectPr node.

declare function authoredFootnotePropertiesFromSectPr(sectPr: OoxmlNode | null | undefined): AuthoredNoteProperties | undefined;

authoredPropertiesfunctionSource ↗

What a container itself authors, narrowed to the names an op is allowed to carry.

declare function authoredProperties(container: OoxmlNode | undefined, authorable: ReadonlySet<string>): readonly OoxmlProperty[];

beginOperationfunctionSource ↗

Begin an operation, capturing its immutable environment snapshot.

Resolves and freezes limits and configuration, carves the root budget, and creates the cancellation controller — everything downstream work needs, fixed for the operation's duration.

declare function beginOperation(init: OperationInit): OperationContext;

bodyStoryRootfunctionSource ↗

The main body story of a part, or null when the part holds none.

declare function bodyStoryRoot(part: OoxmlPart): OoxmlNode | null;

bookmarkPairNodesfunctionSource ↗

Create bookmarkStart/End pair nodes for insertion at the start of a paragraph.

declare function bookmarkPairNodes(mint: () => string, name: string, id: string): {
    readonly start: OoxmlNode;
    readonly end: OoxmlNode;
};

boundCustomXmlNodeIdOffunctionSource ↗

The node id one control binds to in the named store, or null when it binds to nothing there.

declare function boundCustomXmlNodeIdOf(control: OoxmlNode, storeItemId: string): string | null;

boundCustomXmlNodeIdsfunctionSource ↗

Every node id the story's controls bind to in one store, in document order.

This is the input the orphan sweep takes: a node whose id is not in here is one no control names, whether it was deleted in this editor or in Word. Reading it from the STORY rather than from a host's bookkeeping is what makes the two cases one mechanism.

declare function boundCustomXmlNodeIds(part: OoxmlPart, storeItemId: string): Set<string>;

boundCustomXmlNodeIdsInPackagefunctionSource ↗

Every node id ANY story in the package binds, in one store.

THE WHOLE PACKAGE, not one story. A payload is reachable from a header as easily as from the body — Word enumerates its data store from the main part, but nothing stops a control elsewhere quoting the same w:storeItemID — and the two callers that decide what is an orphan both destroy data when they are wrong. The sweep would collect a payload a header still paints; the export would strip a store a header still names, which is a document Word offers to repair.

Costs one walk per story per store, on open and on export. Neither is a keystroke.

declare function boundCustomXmlNodeIdsInPackage(pkg: OoxmlPackage, storeItemId: string): Set<string>;

buildBookmarkIndexfunctionSource ↗

Build name -> position for every bookmark start in a part, in document order.

FIRST IN DOCUMENT ORDER WINS on a duplicate name. Word treats a repeated bookmark name as the same bookmark and jumps to the first, and the alternative — last-wins — makes a jump target move when an edit far away happens to duplicate a name.

The offset is measured the way the ops measure: text of the runs before the marker inside its own paragraph, hyperlink runs included, so the position a jump places the caret at is a position setSelection accepts.

declare function buildBookmarkIndex(part: OoxmlPart): BookmarkIndex;

buildContentTypeIndexfunctionSource ↗

Build a resolved content-type index, failing closed on conflict/duplicate/MIME errors. maxRecords bounds the combined record count (N/N+1 gate).

declare function buildContentTypeIndex(records: ContentTypeRecords, maxRecords?: number): IndexResult;

buildRelationshipSetfunctionSource ↗

Group relationships by owner in authored order; reject duplicate ids per owner.

declare function buildRelationshipSet(records: readonly RelationshipRecord[]): RelationshipSetResult;

buildTocContentControlfunctionSource ↗

Build an SDT-wrapped complex TOC field with an already planned cached result.

declare function buildTocContentControl(mint: () => string, entries: readonly TocEntryPlan[], instruction: TocInstruction, alias: string): OoxmlNode;

buildTocEntryParagraphfunctionSource ↗

Build one TOC entry paragraph node.

declare function buildTocEntryParagraph(mint: () => string, entry: TocEntryPlan, instruction: TocInstruction, paragraphPropertiesTemplate?: OoxmlNode): OoxmlNode;

canonicalizefunctionSource ↗

Produce a canonical string for value, dropping any object key whose name is in ephemera at any depth. Numbers are emitted losslessly; -0 normalizes to 0; non-finite numbers are rejected (they must never enter a comparator input).

declare function canonicalize(value: unknown, ephemera?: ReadonlySet<string>): string;

canonicalOoxmlFingerprintfunctionSource ↗

Repository-owned namespace-aware semantic XML oracle.

declare function canonicalOoxmlFingerprint(value: OoxmlPart | OoxmlNode): string;

cascadeDeletedNoteReferencesfunctionSource ↗

Remove note bodies for references that disappeared between two package snapshots. Used when deleteText or deleteBlock removes a noteReference atom so body+ref stay one undo unit.

Each snapshot gets an independent full visited/part budget. If either scan truncates the cascade fails closed so a hostile package cannot skip body deletion silently — without accidentally halving capacity by charging both walks to one counter.

declare function cascadeDeletedNoteReferences(before: OoxmlPackage, after: OoxmlPackage, options?: CascadeDeletedNoteReferencesOptions): OoxmlPackage | null;

cascadeEmptiedCommentsfunctionSource ↗

Delete every comment the edit between before and after emptied.

The shape cascadeDeletedNoteReferences established: a before/after diff rather than a rule inside each op, because the ops that can empty a range are several (deleteText, deleteBlock, a row deletion, accepting a tracked deletion) and a rule written into each one drifts.

THE TEST, exactly. A comment dies when the words it covered are gone and nothing still places it: either every marker naming it went with them, or its markers are all still there with no characters left between them. What it deliberately does NOT do is read "no usable range" as "emptied" — a comment whose w:commentRangeStart was carried off by a deleted block still has its reference and its end, and Word keeps it, because the reference is the element that anchors a comment. Reaping there deleted a remark whose text was still on screen, which is the one mistake worse than leaving a stale card.

SKIPS rather than refuses when the package is too large to scan. Returning null there made transact roll the edit back, so on a package past the part cap every keystroke in a commented paragraph was silently refused and the document read as frozen. A skipped reap leaves a stale card — recoverable, visible, and the behaviour before any of this existed. Null is reserved for a removal that actually failed, which the caller must roll back.

declare function cascadeEmptiedComments(before: OoxmlPackage, after: OoxmlPackage): OoxmlPackage | null;

childElementsfunctionSource ↗

All direct child elements with the given name.

declare function childElements(node: Extract<XmlNode, {
    type: 'element';
}>, name: string): Extract<XmlNode, {
    type: 'element';
}>[];

collectFlowBlocksfunctionSource ↗

Collect paragraph and table blocks from a sibling list, flattening through content-control wrappers up to [MAX_CONTENT_CONTROL_NESTING](MAX_CONTENT_CONTROL_NESTING).

accept filters which typed blocks are kept (e.g. skip revision-removed paragraphs). When nesting exceeds the bound the wrapper is skipped entirely — same fail-closed rule as the historical storyBlocks walk.

declare function collectFlowBlocks(children: readonly OoxmlNode[], depth?: number, accept?: (block: OoxmlElement) => boolean): OoxmlElement[];

collectNodeIdsfunctionSource ↗

Every node id currently present in the part.

declare function collectNodeIds(part: OoxmlPart): Set<string>;

collectNoteReferencesfunctionSource ↗

Walk a part for addressable typed note references. Bounded by visited nodes; skips deep hostile nesting by marking the shared budget truncated. When budget is supplied it is shared and mutated in place. Hits are segment-aligned (segmentsOf); demoted wrappers never invent atomOffsets.

declare function collectNoteReferences(part: OoxmlPart, options?: {
    readonly maxHits?: number;
    readonly budget?: NoteReferenceScanBudget;
}): readonly NoteReferenceHit[];

collectPackageNoteReferencesfunctionSource ↗

Collect references across every XML part under one shared part + visited-node budget.

declare function collectPackageNoteReferences(pkg: OoxmlPackage, options?: {
    readonly budget?: NoteReferenceScanBudget;
    readonly maxHits?: number;
}): readonly NoteReferenceHit[];

collectReviewItemsfunctionSource ↗

Everything the review surface lists, in document order.

Order is by paragraph position within the story, then by offset. A comment and the revision it covers therefore arrive together, which is what lets a surface group them. Furniture stories rank after the body in one merged order — their geometry (the page they first paint on) is a layout question the queue deliberately does not answer.

declare function collectReviewItems(input: ReviewModelInput): ReviewItem[];

collectRevisionSitesfunctionSource ↗

Every revision-bearing element in the part, with the classification that decides whether it can be resolved.

One walk, so accept-all does not pay a traversal per revision — and paragraphs the last commit did not touch are answered from [paragraphSitesCache](paragraphSitesCache) rather than re-walked.

declare function collectRevisionSites(part: OoxmlPart): RevisionSite[];

collectSectionPropertyNodesfunctionSource ↗

w:sectPr nodes in section order, aligned with layout's enumerateDocumentSections.

null means a section with no w:sectPr node (Word defaults, inherits HF from previous). Paragraph-level breaks first; the final entry covers remaining blocks (body-level or null).

declare function collectSectionPropertyNodes(root: OoxmlNode): Array<OoxmlElement | null>;

collectStoryParagraphsfunctionSource ↗

The block walk itself, appending into out.

Exported so allParagraphs in the binding lane is the same traversal rather than a second copy of it.

declare function collectStoryParagraphs(children: readonly OoxmlNode[], out: OoxmlNode[], sdtDepth: number): void;

commentAnchorsOfStoryfunctionSource ↗

Every comment anchor in one story, in document order.

Overlapping and nested ranges are supported because each anchor is resolved independently — Word produces both, and a model that assumed ranges nest cleanly would mis-anchor them.

A start with no matching end anchors to the end of its own paragraph and is reported orphaned rather than guessed at: extending it to the next end marker would attach a reviewer's remark to text they never saw.

declare function commentAnchorsOfStory(part: OoxmlPart): CommentAnchor[];

commentBodyTextfunctionSource ↗

Plain text of a comment's body, so a card never re-implements the run walk.

declare function commentBodyText(comment: CommentRecord): string;

commentInitialsfunctionSource ↗

Author initials for an avatar, from @w:initials or the name.

declare function commentInitials(comment: CommentRecord): string;

commentItemsOffunctionSource ↗

Comment cards, threaded however the file says so and flat when nothing says so.

ECMA-376 §17.13.4.2 gives CT_Comment no parent pointer, so threading is never something the standard states outright. Three sources, strongest first: @w15:paraIdParent, then @w16cid:parentId — both in namespaces outside Part 1 — and finally a COINCIDENT anchor, a comment whose w:commentRangeStart/End cover exactly the characters an earlier comment's cover. The ranges are Part 1's own vocabulary and the only part of a thread that survives a producer dropping the extension parts. Coincidence is the last resort and never overrides a stated link.

Deliberately not containment. A remark on one word inside another remark's sentence nests without being a reply, and reading that as a thread would bury an independent comment inside someone else's.

declare function commentItemsOf(comments: readonly CommentRecord[], anchors: readonly {
    commentId: string;
    partName: string;
    start: ReviewPosition;
    end: ReviewPosition;
    orphaned: boolean;
}[], threadState: ReadonlyMap<string, CommentThreadState>): ReviewCommentItem[];

commentPartNameOffunctionSource ↗

Exposed so a surface can tell "no comment part yet" from "no comments".

declare function commentPartNameOf(pkg: OoxmlPackage, storyPartName: string): string;

commentsExtendedPartNameOffunctionSource ↗

The commentsExtended.xml a story points at.

Exported for the same reason as [commentPartNameOf](commentPartNameOf): the READER has to resolve the same name the writer does. Hardcoding /word/comments.xml on one side and following the relationship on the other is a split that shows up as a comment written and never read back.

declare function commentsExtendedPartNameOf(pkg: OoxmlPackage, storyPartName: string): string;

commentsOfPartfunctionSource ↗

The comments in word/comments.xml, in authored order.

Every value here comes from a file an attacker fully controls, so nothing is interpreted: author, initials and date are carried verbatim for a surface that will set them as TEXT.

declare function commentsOfPart(part: OoxmlPart): CommentRecord[];

compareArtifactsfunctionSource ↗

Compare two artifacts under a named comparator. canonical-exact and exact compare canonical forms (exact drops no ephemera). tolerance requires an epsilon and compares finite numbers structurally. sync-optimization-only throws — such artifacts are never an equivalence basis.

declare function compareArtifacts(name: ComparatorName, left: unknown, right: unknown, opts?: {
    epsilon?: number;
}): ComparisonResult;

compareSemVerfunctionSource ↗

Order two versions: negative, zero or positive, by major then minor then patch.

declare function compareSemVer(a: SemVer, b: SemVer): -1 | 0 | 1;

containsCssFetchfunctionSource ↗

Whether a file-derived CSS fragment contains a url() or @import (must be rejected).

declare function containsCssFetch(value: string): boolean;

contentControlContentChildrenfunctionSource ↗

The children of a wrapper's w:sdtContent, typed or demoted, in order.

The one place that knows a control's content is reached through an intermediate element, so the four flattening walks (story blocks, layout, header/footer references, list resolution) ask the same question rather than each re-deriving it.

declare function contentControlContentChildren(wrapper: OoxmlNode): readonly OoxmlNode[];

contentControlContentNodeOffunctionSource ↗

A control's w:sdtContent, or null when the wrapper has none.

declare function contentControlContentNodeOf(control: OoxmlNode): OoxmlContentControlContentNode | undefined;

contentControlContentOffunctionSource ↗

Children of the first w:sdtContent under a control, or null when absent or not a control.

declare function contentControlContentOf(node: OoxmlNode): readonly OoxmlNode[] | null;

contentControlEndPropertiesNodeOffunctionSource ↗

A control's w:sdtEndPr — the run properties applied to its closing marker.

declare function contentControlEndPropertiesNodeOf(control: OoxmlNode): OoxmlContentControlEndPropertiesNode | undefined;

contentControlLevelOffunctionSource ↗

How deeply a control is nested inside other controls.

Bounded by [MAX_CONTENT_CONTROL_NESTING](MAX_CONTENT_CONTROL_NESTING): nesting depth comes from a file and is a recursion bound.

declare function contentControlLevelOf(control: OoxmlNode): ContentControlLevel;

contentControlPropertiesNodeOffunctionSource ↗

A control's w:sdtPr, or null. Matches structurally, so a Word-demoted node still resolves.

declare function contentControlPropertiesNodeOf(control: OoxmlNode): OoxmlContentControlPropertiesNode | undefined;

contentControlPropertiesOffunctionSource ↗

Read a control's properties.

Total: a control with no w:sdtPr at all answers the same shape with the defaults an absent property means, so no caller has to branch on the container's existence.

declare function contentControlPropertiesOf(control: OoxmlNode): ContentControlProperties;

contentControlsInfunctionSource ↗

Every control under a node, in document order, bounded in depth and in count.

ONE walk, shared. The nesting bound is the same one layout flattens with, so a control a lane can address is a control every lane can address — and a file that nests past it keeps its content in the tree (the serializer never stops) while no walk recurses further.

declare function contentControlsIn(root: OoxmlNode, options?: {
    readonly maxDepth?: number;
    readonly limit?: number;
}): readonly ContentControlEntry[];

contentControlTextOffunctionSource ↗

The plain text a control's content holds, in reading order.

w:delText is excluded: struck text is not the control's value, and a dropdown whose old item is still present as a tracked deletion would otherwise report both.

declare function contentControlTextOf(control: OoxmlNode): string;

contentTypesPartBytesfunctionSource ↗

Locate [Content_Types].xml bytes regardless of zip key spelling.

declare function contentTypesPartBytes(pkg: OoxmlPackage): {
    readonly storageKey: string;
    readonly bytes: Uint8Array;
} | null;

createImageResourceCachefunctionSource ↗

Build the per-document image cache. Validated bytes only; refusals are remembered too.

declare function createImageResourceCache(initialPkg: OoxmlPackage, options: CreateImageResourceCacheOptions): ImageResourceLookup;

createNodeIdAllocatorfunctionSource ↗

Mint ids for nodes an edit introduces.

Deterministic and collision-checked against the whole part: a structural-path id from the original parse (/word/document.xml#0.1.2) and a minted one (/word/document.xml#new:3) can never coincide, and the counter skips anything already taken so repeated edits in one session stay unique.

Checks the part's node index directly rather than copying every id into a fresh set: the copy was O(document) per op, and an allocator is created for every op.

declare function createNodeIdAllocator(part: OoxmlPart): () => string;

createNoteReferenceScanBudgetfunctionSource ↗

A bounded budget for scanning note references, so a crafted document cannot stall a load.

declare function createNoteReferenceScanBudget(maxVisited?: number, maxParts?: number): NoteReferenceScanBudget;

customMarkFollowsfunctionSource ↗

Read @w:customMarkFollows on a note reference. Returns undefined when absent; otherwise the OOXML on/off interpretation.

declare function customMarkFollows(node: OoxmlNode): boolean | undefined;

customNodeBindingfunctionSource ↗

The binding for one node in one store, or null when the id cannot be addressed by an XPath.

Refuses rather than escapes: XPath 1.0 has no escape for a quote inside a literal, so an id carrying one could close the predicate and append an expression of the sender's choosing. The ids are minted by a host, so refusing is honest — see ADDRESSABLE_ID.

declare function customNodeBinding(part: CustomXmlDataPart, rootLocalName: string, nodeId: string): CustomNodeBinding | null;

customNodePayloadsByControlfunctionSource ↗

The payload every control in a story binds to, keyed by the CONTROL's canonical node id.

Keyed by the control rather than by the store node because that is the question a reader actually has — "what does this chip carry" — and because two stores may each hold a cx1. Resolved here rather than by a capability package: the stores are package parts, and a derivation that only gets story parts has no way to reach them.

Every store the story relates to, so a document carrying two definitions' payloads answers for both without anyone naming a namespace.

declare function customNodePayloadsByControl(pkg: OoxmlPackage, storyPartName: string): ReadonlyMap<string, CustomNodePayloadRead>;

customNodePayloadsOffunctionSource ↗

Every payload one store holds, for a caller resolving a control's data.

declare function customNodePayloadsOf(pkg: OoxmlPackage, storyPartName: string, namespaceUri: string): ReadonlyMap<string, {
    readonly label: string;
    readonly data: string;
}>;

customXmlDataPartsfunctionSource ↗

The data parts a story relates to, in relationship order.

Reads the relationships rather than scanning /customXml/ by name: a part nothing relates to is not part of the document, and a package from a hostile sender can hold as many plausibly-named files as it likes.

declare function customXmlDataParts(pkg: OoxmlPackage, storyPartName: string): CustomXmlDataPart[];

customXmlLabelXPathfunctionSource ↗

The w:xpath a binding uses to reach a node's label, or null when the id cannot be addressed.

Word needs a prefix for the payload namespace even when the store declares it as a default — an unprefixed step in an XPath means "no namespace", so /docxEditor/node would match nothing in a namespaced store. The prefix is declared in w:prefixMappings beside it.

declare function customXmlLabelXPath(prefix: string, rootLocalName: string, nodeId: string): string | null;

customXmlNodesfunctionSource ↗

Every node a store holds, in document order.

declare function customXmlNodes(pkg: OoxmlPackage, partName: string): CustomXmlNode[];

customXmlPrefixMappingsfunctionSource ↗

The w:prefixMappings value declaring that prefix, or null when it cannot be written. The namespace sits inside single quotes inside a double-quoted attribute, so a namespace carrying either quote character has no representation here.

declare function customXmlPrefixMappings(prefix: string, namespaceUri: string): string | null;

datastoreItemIdForfunctionSource ↗

A ds:itemID derived from the seed rather than drawn at random.

Exported so a caller that authors a store OUTSIDE a package — a template engine splicing markup it will assemble into a .docx later — mints the id the same way this does, rather than inventing a second GUID shape Word has to be tolerant of.

The store is a pure function of what it is asked to write: the same document written twice has to produce the same bytes, or a save/reopen/save round trip stops being a fixed point and every digest taken over saved bytes moves. A GUID's job here is uniqueness within one package, not unguessability, so four FNV-1a passes over a salted seed carry it.

declare function datastoreItemIdFor(seed: string): string;

deepParagraphOrderOfPartfunctionSource ↗

Like [paragraphOrderOfPart](paragraphOrderOfPart), but descends INTO paragraphs, so paragraphs nested in a run's content — a textbox's w:txbxContent — rank right after their host.

A separate function on purpose: the shallow order feeds the review queue's card ordering, and re-ranking nested paragraphs there would move cards. This one exists for position containment tests ("is the caret inside this range"), where a paragraph the shallow order cannot see is a position that can never match.

declare function deepParagraphOrderOfPart(part: OoxmlPart): ReadonlyMap<string, number>;

deleteCommentThreadfunctionSource ↗

Delete a comment thread outright: body, thread state and story markers.

Returns the package unchanged when the id names no comment, and null when a removal was refused — a caller inside a transaction rolls back rather than committing a package whose comment is half gone.

declare function deleteCommentThread(pkg: OoxmlPackage, commentId: string): OoxmlPackage | null;

deobfuscateFontfunctionSource ↗

Undo Word's embedded-font obfuscation (ECMA-376 Part 4 §2.8.1).

The key is the w:fontKey GUID's 16 bytes in REVERSED order — not the per-group little-endian reading a GUID usually gets. It is XORed over the first 32 bytes of the part, applied twice. Getting the order wrong produces a font that looks corrupt rather than obfuscated, which is indistinguishable from a damaged file at the point it fails.

Pure XOR, so the same operation obfuscates and deobfuscates.

declare function deobfuscateFont(bytes: Uint8Array, fontKey: string): Uint8Array | null;

deriveOoxmlIndexesfunctionSource ↗

Derive every index from one canonical package revision.

Pure: the same package and revision always produce the same index, which is what makes "rebuild rather than mutate" a safe invalidation strategy.

declare function deriveOoxmlIndexes(pkg: OoxmlPackage, revision: number): OoxmlIndexes;

detectBodyTocsfunctionSource ↗

Discover refreshable body TOCs without evaluating any field instruction.

declare function detectBodyTocs(part: OoxmlPart): readonly DetectedToc[];

detectDuplicateNamesfunctionSource ↗

Detect archive entries that collide after normalization (before inflation). Returns the case-folded keys that more than one raw name maps to.

declare function detectDuplicateNames(rawNames: readonly string[]): {
    readonly duplicates: readonly string[];
    readonly rejected: readonly {
        raw: string;
        reason: NameRejection;
    }[];
};

diagnoseNoteReferencesfunctionSource ↗

Load diagnostics for dangling note references. Fail-open: never throws or mutates; returns diagnostics for callers to surface. Does not invent missing note bodies.

When the hard visited/part budget truncates or the soft hit cap binds, appends a single note-reference-scan-truncated entry so incomplete coverage is visible without breaking consumers that filter on dangling-note-reference.

declare function diagnoseNoteReferences(pkg: OoxmlPackage): readonly NoteDiagnostic[];

diffSemanticDigestsfunctionSource ↗

Every way two digests differ, as readable paths.

Returns the differences rather than a boolean because "the round trip lost something" is useless without saying what — the failure this oracle exists to catch is a silent drop, and a bare false reproduces the silence.

declare function diffSemanticDigests(before: SemanticDigest, after: SemanticDigest): DigestDifference[];

digestPartfunctionSource ↗

Digest one part: its paragraphs, and the structure that holds them.

declare function digestPart(part: OoxmlPart): StoryDigest | null;

directParagraphMarkPropertiesfunctionSource ↗

What a paragraph MARK itself authors: w:pPr/w:rPr, narrowed to the run vocabulary.

Same rule as a run's own w:rPr, for the same reason — the mark is a run property container, and setParagraphMarkProperties rewrites the names its op carries.

declare function directParagraphMarkProperties(part: OoxmlPart, paragraphId: string): readonly OoxmlProperty[];

directParagraphPropertiesfunctionSource ↗

What a paragraph itself authors: its own w:pPr, narrowed to what an op can express.

Properties outside the vocabulary are dropped from the OP, not from the paragraph: the applier keeps every w:pPr child an op cannot name (the mark, w:sectPr, w:pBdr, w:outlineLvl) exactly as authored.

declare function directParagraphProperties(part: OoxmlPart, paragraphId: string): readonly OoxmlProperty[];

drawingOpImpactfunctionSource ↗

Impact class for a drawing op — metadata/locks are text-local; geometry/wrap are flow-structural.

declare function drawingOpImpact(op: DrawingTreeDocOp): ImpactClass;

endOperationfunctionSource ↗

Release the operation's root budget (requires every child/reservation released).

declare function endOperation(ctx: OperationContext): void;

ensureHyperlinkRelationshipfunctionSource ↗

The external hyperlink relationship for url on ownerPart (default: main document), reusing an existing one with the same target, or null when the URL is not something to write.

REUSE IS BY EXACT TARGET, matching Word: linking twice to the same address produces one relationship. It is safe because a hyperlink relationship carries nothing but its target — two links sharing one are indistinguishable from two links with identical targets, and retargeting one always mints rather than rewriting (see the edit op).

Ownership follows the story that holds the w:hyperlink: a header/footer or notes part mints into that part's .rels, never into document.xml.rels. Passing an owner the package does not declare fails closed (null) so a scoped insert cannot leave a stray body relationship behind.

The URL is refused unless sanitizeHref admits it. Storing a javascript: target that a FILE authored is required — round-tripping never rewrites a document — but AUTHORING one here is not: there is no legitimate reason for this engine to write a scheme it would then refuse to open, and writing it would hand the next reader a live target this reader made.

declare function ensureHyperlinkRelationship(pkg: OoxmlPackage, url: string, ownerPart?: string): EnsuredHyperlinkRelationship | null;

ensureListDefinitionfunctionSource ↗

Find or create a list definition of kind, returning the package that holds it.

An existing definition of the same kind is REUSED rather than duplicated: Word does the same, and a document that gains one w:abstractNum per toggled paragraph becomes unreadable. Returns null only when the part cannot be built at all.

declare function ensureListDefinition(pkg: OoxmlPackage, kind: ListKind): EnsuredListDefinition | null;

ensureNumberingLevelfunctionSource ↗

Declare level in the definition numId names, with Word's default format for that level, or refuse.

Word never greys Increase Indent out on a list item: demoting past the deepest level a w:abstractNum declares makes Word DEFINE the level, cycling its stock bullets (Symbol •, Courier o, Wingdings ▪) or number formats (decimal, lowerLetter, lowerRoman) by depth. This is that write. An already-declared level returns the package unchanged, so callers may ask first and act second without a second lookup.

A delegating definition (w:numStyleLink, 17.9.21) is refused: its levels live on the linked style's definition, and a w:lvl grafted here would be shadowed the moment the link resolves.

declare function ensureNumberingLevel(pkg: OoxmlPackage, numId: string, level: number, kind: ListKind): OoxmlPackage | null;

escapeCssStringfunctionSource ↗

CSS string-escape a file-derived value (e.g. an @font-face family name or an inline style value). Emits \<hex> escapes for quotes, backslash, and controls so the value cannot break out of its CSS string.

declare function escapeCssString(value: string): string;

escapeXmlfunctionSource ↗

XML-escape a value for validated serialization back into owned OOXML.

declare function escapeXml(value: string): string;

extensionKeyfunctionSource ↗

ASCII-case-insensitive extension key (leading dot removed; ASCII-only fold).

declare function extensionKey(extension: string): string;

fieldAtomTextfunctionSource ↗

Model text contributed by one atomic field unit.

declare function fieldAtomText(): typeof FIELD_ATOM_CHAR;

fieldOnOffAttributefunctionSource ↗

Read an on/off WML attribute (dirty / fldLock).

Returns undefined when absent, otherwise the OOXML on/off interpretation (present without val, or val not explicitly off → true).

declare function fieldOnOffAttribute(node: OoxmlNode, localName: 'dirty' | 'fldLock'): boolean | undefined;

findContentControlfunctionSource ↗

Find one control by canonical node id, with the same bounded walk.

declare function findContentControl(root: OoxmlNode, nodeId: string): ContentControlEntry | null;

findCustomXmlDataPartfunctionSource ↗

The data part carrying this namespace, or null when the document has none yet.

declare function findCustomXmlDataPart(pkg: OoxmlPackage, storyPartName: string, namespaceUri: string): CustomXmlDataPart | null;

findDetectedTocfunctionSource ↗

Locate the table of contents containing a position, or null.

declare function findDetectedToc(tocs: readonly DetectedToc[], tocId: string): DetectedToc | null;

findElementfunctionSource ↗

Find the first descendant element with the given qualified name.

declare function findElement(nodes: readonly XmlNode[], name: string): Extract<XmlNode, {
    type: 'element';
}> | undefined;

findNodefunctionSource ↗

Read a node back out of a part by id.

declare function findNode(part: OoxmlPart, nodeId: string): OoxmlNode | null;

findNoteByIdfunctionSource ↗

Find a typed note by id inside a notes-part root.

declare function findNoteById(root: OoxmlNode, noteId: number): OoxmlNoteNode | undefined;

findOccurrencesfunctionSource ↗

Every occurrence of query in text, in order, NON-OVERLAPPING.

Non-overlapping is what a find dialog counts: aa in aaaa is two, not three. limit is the caller's remaining budget, so a caller scanning many paragraphs enforces ONE global cap rather than one per paragraph.

declare function findOccurrences(text: string, query: string, limit: number, options?: TextMatchOptions): TextOccurrences;

fingerprintfunctionSource ↗

Fingerprint an artifact under a named comparator's canonicalization policy.

declare function fingerprint(name: ComparatorName, value: unknown): string;

firstReviewRangefunctionSource ↗

The range an item is anchored at — where its card belongs and how it sorts.

declare function firstReviewRange(item: ReviewItem): ReviewRange | null;

flattenContentControlsfunctionSource ↗

A container's children with every content-control wrapper flattened away, bounded in depth.

ONE unwrap rule, for the places where a control sits between a container and the children that container is defined in terms of. CT_SdtRow puts it between w:tbl and w:tr, CT_SdtCell between w:tr and w:tc, and a walk that filtered on the child's kind dropped the row or cell entirely: not measured, not painted, not addressable. Flattening at the point of the filter means a controlled row is the same row to the grid pass, the pagination pass and the story walk.

Returns the SAME array identity when there is nothing to unwrap, so the tables that carry no controls — nearly all of them — allocate nothing and the incremental layout cache still sees its own inputs.

declare function flattenContentControls(children: readonly OoxmlNode[], maxDepth?: number): readonly OoxmlNode[];

fldCharTypefunctionSource ↗

Read @w:fldCharType when present and schema-legal.

declare function fldCharType(node: OoxmlNode): FldCharType | null;

fldSimpleInstrfunctionSource ↗

@w:instr on w:fldSimple, or undefined when absent.

declare function fldSimpleInstr(node: OoxmlNode): string | undefined;

fnv1a32functionSource ↗

FNV-1a over UTF-16 code units — the deterministic mint every id derivation shares.

declare function fnv1a32(value: string): number;

foldCasefunctionSource ↗

Lower-case text WITHOUT changing its length.

String.prototype.toLowerCase can expand (Turkish dotted capital I lowercases to two code units), and an expansion mid-paragraph would slide every offset after it — the match would be reported at the wrong place. The per-unit fallback folds only the characters that stay one unit, so an expanding character simply compares case-sensitively. That is a real degradation and it is the safe direction: a missed case-insensitive match beats a match reported at an offset an editor then selects.

declare function foldCase(text: string): string;

formatNoteScopeIdfunctionSource ↗

Canonical EditorScope { kind: 'note'; id } encoding.

Footnote id 1 and endnote id 1 coexist, so the kind is part of the string: footnote:2 / endnote:-1. Do not invent a parallel scope union arm.

declare function formatNoteScopeId(noteKind: NoteKind, noteId: number): string;

formatOwnedRunIdsfunctionSource ↗

Runs that own field-result formatting for atoms in this paragraph.

declare function formatOwnedRunIds(paragraph: Extract<OoxmlNode, {
    kind: 'paragraph';
}>): ReadonlySet<string>;

hardBreakAttributesfunctionSource ↗

Attributes for a newly authored w:br.

declare function hardBreakAttributes(kind: 'line' | 'page'): OoxmlHardBreakNode['attributes'];

hardBreakKindfunctionSource ↗

Read the semantic break kind from a typed w:br node.

declare function hardBreakKind(node: OoxmlHardBreakNode): HardBreakKind;

hardBreakTextfunctionSource ↗

Text projection for a w:br node — one UTF-16 code unit per break.

declare function hardBreakText(node: OoxmlHardBreakNode): string;

hasAnyCommentfunctionSource ↗

Whether the package holds any comment record at all — the cheap gate before a reap.

declare function hasAnyComment(pkg: OoxmlPackage): boolean;

hasBoundedSvgRootfunctionSource ↗

Bounded scan for an <svg document root (optional <?xml prolog only).

declare function hasBoundedSvgRoot(bytes: Uint8Array): boolean;

hasCommentPartfunctionSource ↗

A comment part exists and declares the comment content type.

declare function hasCommentPart(pkg: OoxmlPackage, storyPartName: string): boolean;

hashAuthoredfunctionSource ↗

Hash a store's authored state, so two runtimes replaying one fixture can be compared.

declare function hashAuthored(authoredState: unknown): string;

hasNodefunctionSource ↗

Whether a node id exists in the part.

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

hyperlinkAnchorOffunctionSource ↗

A typed hyperlink's w:anchor, or undefined.

declare function hyperlinkAnchorOf(link: OoxmlNode): string | undefined;

hyperlinkRelationshipIdOffunctionSource ↗

A typed hyperlink's r:id, or undefined.

declare function hyperlinkRelationshipIdOf(link: OoxmlNode): string | undefined;

hyperlinkTargetOffunctionSource ↗

Read a typed w:hyperlink into its target record.

r:id wins over w:anchor when a link carries both, matching Word: the relationship names the document and the anchor names a place inside it, so the pair is a link to a bookmark in ANOTHER file — which this engine will not follow, but whose external half is the part that decides where it points.

A link with neither is unresolved: it paints its runs and does nothing.

declare function hyperlinkTargetOf(link: OoxmlNode, resolve: RelationshipTargetResolver): HyperlinkTarget;

imageResourceLookupForfunctionSource ↗

Derived cache for one immutable package snapshot. Registry identity is (package snapshot, decodePort object, normalized limits) — the first caller never imposes its decoder or limits on later callers with different options.

declare function imageResourceLookupFor(pkg: OoxmlPackage, options: CreateImageResourceCacheOptions): ImageResourceLookup;

indexStylesfunctionSource ↗

Style definitions, read out of the generic w:styles tree.

declare function indexStyles(part: OoxmlPart | undefined): Map<string, StyleIndexEntry>;

inlineControlEndingAtfunctionSource ↗

The innermost inline content control whose content ends exactly at offset — the caret at its right outer edge. What Backspace consults to delete the node as ONE unit (pro-review-and-custom-nodes 4.6): deleting its last character from outside would either strip one letter from a content-locked label (refused, so the key looks dead) or leave a half-deleted chip whose tag still claims the full payload.

declare function inlineControlEndingAt(paragraph: OoxmlParagraphNode, offset: number): InlineControlSpan | null;

inlineControlStartingAtfunctionSource ↗

The forward-delete mirror: the control whose content STARTS exactly at offset.

declare function inlineControlStartingAt(paragraph: OoxmlParagraphNode, offset: number): InlineControlSpan | null;

insertChildrenfunctionSource ↗

Insert children into a node at index (clamped to the child list).

declare function insertChildren(part: OoxmlPart, nodeId: string, index: number, children: readonly OoxmlNode[], options?: EditOptions): OoxmlEditResult;

insertCustomNodeWritefunctionSource ↗

Insert one custom node, with its payload, as a single transaction.

Answers the store transaction's own change so the caller can publish it — a payload write is a package write reaching through a story store, exactly as a comment is, and the coordinator needs the change to know which paragraphs went dirty.

declare function insertCustomNodeWrite(store: TreeDocumentStore, write: InsertCustomNodeWrite, 
dataOwnerPartName?: string): CustomNodeWriteResult;

instrTextValuefunctionSource ↗

Concatenated text descendants of w:instrText (instruction only — never executed).

declare function instrTextValue(node: OoxmlNode): string;

isAuthorableRunPropertyfunctionSource ↗

Whether an op may name this run property at all.

The stored-marks lane needs this AT ARM TIME. Every other write reaches the store in the same turn as the press, so a name the store refuses surfaces immediately; an ARMED property is not applied until the user types, and it rides the keystroke's own transaction — a name outside the vocabulary would take the typed characters down with it, silently, on every keystroke until the caret moved.

declare function isAuthorableRunProperty(localName: string): boolean;

isContentControlfunctionSource ↗

Block or inline structured-document-tag wrapper — typed or generic during migration.

Generic fallback requires the WordprocessingML namespace so foreign-namespace <x:sdt> elements stay opaque wrappers and are never treated as Word controls.

declare function isContentControl(node: OoxmlNode): node is ContentControlLike;

isContentControlContentfunctionSource ↗

True when node is the control's content container (w:sdtContent).

Generic sdtContent requires the WML namespace — same foreign-namespace rule as [isContentControl](isContentControl).

declare function isContentControlContent(node: OoxmlNode): node is ContentControlContentLike;

isContentControlContentNodefunctionSource ↗

Whether a node is a w:sdtContent — the container holding a control's actual content.

declare function isContentControlContentNode(node: OoxmlNode): node is OoxmlContentControlContentNode;

isContentControlNodefunctionSource ↗

Whether a node is a w:sdt wrapper.

declare function isContentControlNode(node: OoxmlNode): node is OoxmlContentControlNode;

isContentControlWrapperfunctionSource ↗

A w:sdt wrapper, TYPED or DEMOTED.

Flattening predates typing and must not stop at a control the reader refused to type: a demoted wrapper still renders its content in place in Word, so a walk that only saw the typed kind would drop every paragraph inside a malformed control out of the story.

declare function isContentControlWrapper(node: OoxmlNode): boolean;

isContentRevisionKindfunctionSource ↗

The four content-position revision wrappers, which nest and carry runs.

declare function isContentRevisionKind(kind: OoxmlNode['kind']): kind is 'revisionInsert' | 'revisionDelete' | 'revisionMoveFrom' | 'revisionMoveTo';

isContinuationSeparatorNodefunctionSource ↗

Whether a node is the w:continuationSeparator rule used on continuation pages.

declare function isContinuationSeparatorNode(node: OoxmlNode): node is OoxmlContinuationSeparatorNode;

isDangerousKeyfunctionSource ↗

Whether a key is one of [DANGEROUS_KEYS](DANGEROUS_KEYS).

declare function isDangerousKey(key: string): boolean;

isDrawingTreeDocOpfunctionSource ↗

Whether an op is one of the drawing ops. Narrows the type.

declare function isDrawingTreeDocOp(op: TreeDocOp): op is DrawingTreeDocOp;

isEndnotesNodefunctionSource ↗

Whether a node is a w:endnotes part root.

declare function isEndnotesNode(node: OoxmlNode): node is OoxmlEndnotesNode;

isEvaluableFieldfunctionSource ↗

Whether a field instruction's leading keyword is safe to evaluate.

declare function isEvaluableField(instruction: string): boolean;

isFieldChromefunctionSource ↗

True when a node is field chrome that never contributes its own model text outside an atomic span (markers + instruction). Cached result w:t is separate.

declare function isFieldChrome(node: OoxmlNode): boolean;

isFldCharfunctionSource ↗

Typed or generic w:fldChar with the given type.

declare function isFldChar(node: OoxmlNode, type: FldCharType): boolean;

isFldCharNodefunctionSource ↗

Whether a node is a w:fldChar field boundary marker.

declare function isFldCharNode(node: OoxmlNode): node is OoxmlFldCharNode;

isFldSimplefunctionSource ↗

Typed or generic w:fldSimple.

declare function isFldSimple(node: OoxmlNode): boolean;

isFldSimpleNodefunctionSource ↗

Whether a node is w:fldSimple — a field whose instruction and result are one element.

declare function isFldSimpleNode(node: OoxmlNode): node is OoxmlFldSimpleNode;

isFootnotesNodefunctionSource ↗

Whether a node is a w:footnotes part root.

declare function isFootnotesNode(node: OoxmlNode): node is OoxmlFootnotesNode;

isHeaderFooterLifecycleOpfunctionSource ↗

Whether an op is a header/footer lifecycle op rather than a story-level one.

declare function isHeaderFooterLifecycleOp(op: {
    readonly op: string;
}): op is HeaderFooterLifecycleOp;

isHyperlinkNodefunctionSource ↗

Whether a node is a typed w:hyperlink.

declare function isHyperlinkNode(node: OoxmlNode): boolean;

isInertExecutablefunctionSource ↗

Whether a content kind is one this engine refuses to execute or auto-resolve.

declare function isInertExecutable(kind: string): boolean;

isInstrTextfunctionSource ↗

Typed or generic w:instrText.

declare function isInstrText(node: OoxmlNode): boolean;

isInstrTextNodefunctionSource ↗

Whether a node is w:instrText — a field's instruction.

Instructions are never EXECUTED or auto-resolved: DDE and INCLUDE* render inert.

declare function isInstrTextNode(node: OoxmlNode): node is OoxmlInstrTextNode;

isLegalEndnotePositionfunctionSource ↗

Validate an authored endnote position write — refuse pageBottom.

declare function isLegalEndnotePosition(pos: string): pos is EndnotePosition;

isLegalFldCharTypefunctionSource ↗

Whether fldCharType is a legal ST_FldCharType value (used by tests / guards).

declare function isLegalFldCharType(value: string): boolean;

isLegalFootnotePositionfunctionSource ↗

Validate an authored footnote position write.

declare function isLegalFootnotePosition(pos: string): pos is FootnotePosition;

isLegalNumRestartfunctionSource ↗

Whether a file-supplied string is a legal w:numRestart value. Narrows the type.

declare function isLegalNumRestart(value: string): value is NoteNumRestart;

isNormalNotefunctionSource ↗

Whether a note is a normal (body) note — absent type and explicit normal both count.

declare function isNormalNote(node: OoxmlNode): boolean;

isNoteAtomNodefunctionSource ↗

True when a run-inner node is a typed note atom that contributes one UTF-16 unit. Demoted/malformed known locals stay generic and contribute nothing.

declare function isNoteAtomNode(node: OoxmlNode): boolean;

isNoteLifecycleOpfunctionSource ↗

Whether an op is a note lifecycle op rather than a story-level one.

declare function isNoteLifecycleOp(op: {
    readonly op: string;
}): op is NoteLifecycleOp;

isNoteNodefunctionSource ↗

Whether a node is a w:footnote or w:endnote body.

declare function isNoteNode(node: OoxmlNode): node is OoxmlNoteNode;

isNoteReferenceNodefunctionSource ↗

Whether a node is a body-side w:footnoteReference / w:endnoteReference.

declare function isNoteReferenceNode(node: OoxmlNode): node is OoxmlNoteReferenceNode;

isNoteRefNodefunctionSource ↗

Whether a node is the w:footnoteRef / w:endnoteRef mark inside a note's own body.

declare function isNoteRefNode(node: OoxmlNode): node is OoxmlNoteRefNode;

isPageBreakNodefunctionSource ↗

Whether a node is a w:br with w:type="page".

declare function isPageBreakNode(node: OoxmlNode): node is OoxmlHardBreakNode;

isRangeMarkerKindfunctionSource ↗

Move-range and comment-range boundary markers, which are empty and sit between runs.

declare function isRangeMarkerKind(kind: OoxmlNode['kind']): kind is 'moveFromRangeStart' | 'moveFromRangeEnd' | 'moveToRangeStart' | 'moveToRangeEnd' | 'commentRangeStart' | 'commentRangeEnd';

isSearchableQueryfunctionSource ↗

Whether a query is one this module will scan for at all.

declare function isSearchableQuery(query: unknown): query is string;

isSeparatorNodefunctionSource ↗

Whether a node is the w:separator rule drawn above the note area.

declare function isSeparatorNode(node: OoxmlNode): node is OoxmlSeparatorNode;

isValidIdfunctionSource ↗

Whether a string is a well-formed identifier in either accepted grammar.

Reverse-domain (dev.docx-editor.core.command.insert-text) or package-owned (@docx-editor.dev/engine-core#command/insert-text). Ids are opaque once validated.

declare function isValidId(id: string): boolean;

isValidMimefunctionSource ↗

Whether a string is syntactically a MIME type. Syntax only — no registry lookup.

declare function isValidMime(value: string): boolean;

isValidNCNamefunctionSource ↗

Whether a string is a valid XML NCName — a name with no colon.

declare function isValidNCName(name: string): boolean;

isValidParaIdfunctionSource ↗

Valid per MS-DOCX: 8 hex digits, non-zero, below 0x80000000.

declare function isValidParaId(value: string): boolean;

isValidQNamefunctionSource ↗

A QName is an optional prefix: (both NCNames) — never attacker-derived.

declare function isValidQName(name: string): boolean;

isWholeWordfunctionSource ↗

Whether a match at [start, end) in text stands alone as a word.

declare function isWholeWord(text: string, start: number, end: number): boolean;

linkRevisionRepliesfunctionSource ↗

Attach each comment that answers a tracked change to the change it answers.

The evidence is the RANGE, exactly as it is for a coincident comment thread: replying to a revision writes a comment over that revision's own characters, because OOXML gives w:ins and w:del nowhere else to put the text. Without this the reply came back as an independent card in the rail, sitting beside the change rather than inside it, and the reader had no way to see which change their answer belonged to.

Three things keep it from over-claiming. A ZERO-WIDTH range is evidence of nothing — the same rule the comment threading uses, and a format or paragraph-mark revision decorates no characters at all. A comment already stated to be a REPLY to another comment is not claimed directly, because a stated link always beats an inferred one. And the FIRST revision on a span wins, so a card cannot claim a reply another card already holds.

The WHOLE conversation moves, not its head. A change's card renders replyIds as a flat list, so linking only the top comment of a thread left every answer to that answer rendered by nobody: reply twice to one change and the second reply existed in comments.xml and appeared nowhere on screen. Descendants ride along, in the order they were authored.

IDEMPOTENT, and that is load-bearing. The session re-runs this over a list whose comments are ALREADY linked, so a pass that only ever added links left a stale parentRevisionId behind when a keystroke shifted the revision's offsets out from under it — the rail filters such a comment out of its roots, and with no revision claiming it any more the card vanished until the next full re-derivation. Every link is rebuilt from the ranges on every pass.

declare function linkRevisionReplies<T extends LinkableReviewItem>(items: readonly T[]): T[];

liveDrawingReferenceCountfunctionSource ↗

Package-wide live drawing references to a media part name.

declare function liveDrawingReferenceCount(pkg: OoxmlPackage, partName: string): number;

locateSitesfunctionSource ↗

Locate every revision site in one walk.

One walk rather than a lookup per site: resolveRevisions learned the same lesson the hard way, where a per-site tree walk inside a per-site loop made accept-all quadratic.

Offsets come from paragraphOffsetIndex, which is segmentsOf's walk. A private one here measured a run by summing its text and gave a note reference, an atomic field and a field's instruction text the wrong lengths, so every card in a paragraph holding one reported a range the caret and the ops disagreed with.

declare function locateSites(part: OoxmlPart): ReadonlyMap<string, SiteLocation>;

lockForbidsEditfunctionSource ↗

Whether a resolved lock forbids editing the content it covers.

declare function lockForbidsEdit(lock: ContentControlLock): boolean;

lockForbidsRemovalfunctionSource ↗

Whether a resolved lock forbids removing the control itself.

declare function lockForbidsRemoval(lock: ContentControlLock): boolean;

makeLimitCounterfunctionSource ↗

A phase-scoped overflow-safe counter for one limit.

declare function makeLimitCounter(limits: ResourceLimits, key: keyof ResourceLimits): BoundedCounter;

mergedPropertiesfunctionSource ↗

Merge properties into a set, replacing any entry with the same name.

setRunProperties and setParagraphProperties REPLACE the whole container, so sending one property alone deleted every other: pressing Bold stripped a run's font, size and colour, and pressing Centre stripped a paragraph's style, numbering and indents.

Takes one property or a list, because a toolbar press carries one and an object-model formatting write carries several at once — and applying several one at a time would be the same fold written at every call site.

declare function mergedProperties(existing: readonly OoxmlProperty[], incoming: OoxmlProperty | readonly OoxmlProperty[]): OoxmlProperty[];

mintedParagraphIdentityAttributesfunctionSource ↗

The minted [w14:paraId, w14:textId] pair. textId mirrors paraId: it has no uniqueness requirement, no consumer reads it, and one allocator is simpler than two — but Word writes both, so we write both.

declare function mintedParagraphIdentityAttributes(prefix: string, value: string): readonly OoxmlAttribute[];

mintParaIdfunctionSource ↗

Deterministic 8-hex mint in (0x00000000, 0x80000000), collision-free against used (uppercase hex). Same seed + same used-set → same value, which is what keeps splitParagraphMany byte-identical to its equivalent single splits and a reopened save identical to the session that produced it.

declare function mintParaId(seed: string, used: ReadonlySet<string>): string;

normalizeParagraphIdentityfunctionSource ↗

Load-time paragraph-identity normalization for a session's main part.

Keeps every valid, first-seen paraId verbatim; mints (deterministically, seeded by the paragraph's structural node id) for paragraphs whose id is missing, malformed, zero, out of range, or a duplicate. Adds the root xmlns binding the minted attributes need. Returns the INPUT PART REFERENCE when there is nothing to do — a document Word saved yesterday re-serializes byte-identical.

Attribute-only rebuilds move no child, so every node keeps its structural-path id; the copy respreads only the ancestors of changed paragraphs.

Fail-open: if the rebuilt part does not validate (a bug, or a pathology the prefix choice could not defuse), the original part is returned — a document must never become unopenable over an identity enhancement.

declare function normalizeParagraphIdentity(part: OoxmlPart): OoxmlPart;

normalizePartNamefunctionSource ↗

Normalize a ZIP entry name or OPC part name into a canonical part name (/word/document.xml). Accepts leading-slash and no-leading-slash inputs; rejects traversal, dot segments, and the attack surface. Duplicate detection folds ASCII case (OPC part-name equivalence).

declare function normalizePartName(raw: string): NameResult;

normalNoteIdsfunctionSource ↗

List normal (body) note ids in document order, bounded.

declare function normalNoteIds(part: OoxmlPart): readonly number[];

noteAtomTextfunctionSource ↗

Model text contributed by one atomic note unit.

declare function noteAtomText(): typeof NOTE_ATOM_CHAR;

noteIdOffunctionSource ↗

Authored @w:id on a note or noteReference when parseable.

declare function noteIdOf(node: OoxmlNode): number | null;

noteKindOffunctionSource ↗

Typed or generic w:footnote / w:endnote.

declare function noteKindOf(node: OoxmlNode): NoteKind | null;

noteReferenceKindOffunctionSource ↗

Typed or generic footnote/endnote reference kind.

declare function noteReferenceKindOf(node: OoxmlNode): NoteKind | null;

noteRefKindOffunctionSource ↗

Typed or generic w:footnoteRef / w:endnoteRef.

declare function noteRefKindOf(node: OoxmlNode): NoteKind | null;

notesOffunctionSource ↗

Collect note bodies from a footnotes/endnotes root, bounded.

declare function notesOf(root: OoxmlNode): readonly OoxmlNoteNode[];

notesPartHasIdfunctionSource ↗

Whether a notes-part root contains a note with the given id (any type).

declare function notesPartHasId(part: OoxmlPart, noteId: number): boolean;

noteTypeOffunctionSource ↗

Authored @w:type (ST_FtnEdn) when present and schema-legal; else undefined.

declare function noteTypeOf(node: OoxmlNode): NoteType | undefined;

nullRecordfunctionSource ↗

A fresh null-prototype record — the only object shape parser intermediates use.

declare function nullRecord<T = unknown>(): Record<string, T>;

ooxmlTreesEqualfunctionSource ↗

Structural equality of two canonical trees, ignoring node ids.

Ids differ between two parses of the same bytes, so comparing them would report every reopen as a change. This compares what the document SAYS.

declare function ooxmlTreesEqual(left: OoxmlPart | OoxmlNode, right: OoxmlPart | OoxmlNode): boolean;

orderedContentControlPropertiesfunctionSource ↗

Rebuild a w:sdtPr's children in schema order.

Modelled children sort to their declared position and the type element follows them, as the sequence requires. Everything else — a w15:repeatingSection, a vendor extension, the w14:checkbox that is not part of the ECMA-376 choice — keeps the order it was authored in and follows the modelled block, so a write that touches one property neither drops nor reorders anything it does not name.

declare function orderedContentControlProperties(children: readonly OoxmlNode[]): readonly OoxmlNode[];

paragraphOffsetIndexfunctionSource ↗

THE paragraph offset authority: maps a paragraph's UTF-16 offsets to the nodes holding them.

One authority on purpose. An atomic field spans many nodes but is ONE unit to an offset, and a second implementation that disagreed would place edits inside content that cannot be split.

declare function paragraphOffsetIndex(paragraph: OoxmlParagraphNode): ParagraphOffsetIndex;

paragraphOrderOfPartfunctionSource ↗

Paragraph node id → document position, from the TREE rather than from a layout.

Memoized on the immutable root: one full derivation pass asks this question three times (replacement pairing, the queue's merged order, the session's cached order), and each answer was a fresh full-tree walk. The instance is SHARED, so the return type is ReadonlyMap: a caller mutating it would poison every later reader of this root.

declare function paragraphOrderOfPart(part: OoxmlPart): ReadonlyMap<string, number>;

paragraphTextOffunctionSource ↗

Paragraph text as the ops address it, for tests and callers computing offsets.

declare function paragraphTextOf(part: OoxmlPart, paragraphId: string): string | null;

paraIdOffunctionSource ↗

The authored w14:paraId value of an element, verbatim, or null.

declare function paraIdOf(node: OoxmlNode): string | null;

parentNodeOffunctionSource ↗

The element that holds a node, or null for the root and for unknown ids.

declare function parentNodeOf(part: OoxmlPart, nodeId: string): OoxmlElement | null;

parseAuthoredNotePropertiesfunctionSource ↗

Parse authored CT_FtnProps / CT_EdnProps without inventing defaults.

declare function parseAuthoredNoteProperties(propsNode: OoxmlNode | null | undefined): AuthoredNoteProperties | undefined;

parseContentControlIdfunctionSource ↗

A signed 32-bit ST_DecimalNumber, or undefined when the file wrote something else.

declare function parseContentControlId(raw: string | undefined): number | undefined;

parseNoteIdfunctionSource ↗

Parse a signed decimal note id; reject non-integers and out-of-int32 values.

declare function parseNoteId(raw: string | undefined): number | null;

parseNoteScopeIdfunctionSource ↗

Parse [formatNoteScopeId](formatNoteScopeId). Returns null for malformed / out-of-range ids.

declare function parseNoteScopeId(id: string): {
    readonly noteKind: NoteKind;
    readonly noteId: number;
} | null;

parseSemVerfunctionSource ↗

Parse a semantic version, rejecting anything the registry's rules do not need.

Deliberately narrow: an unsupported range form is refused rather than accepted, so a malformed range can never masquerade as "compatible".

declare function parseSemVer(input: string): SemVer;

parseTocInstructionfunctionSource ↗

Parse a TOC field instruction string.

Returns null when the leading keyword is not TOC, the string is over-long, or the outline range is hostile. Does not evaluate or fetch anything.

declare function parseTocInstruction(raw: string): TocInstruction | null;

partNameKeyfunctionSource ↗

Case-folded key for OPC part-name equivalence / duplicate detection.

declare function partNameKey(partName: string): string;

planTocEntriesfunctionSource ↗

Plan TOC entries from the outline and existing bookmarks.

declare function planTocEntries(part: OoxmlPart, outline: readonly TocOutlineHeading[], instruction: TocInstruction, pageNumberByParagraphId: ReadonlyMap<string, string>, excludeParagraphIds: ReadonlySet<string>): {
    readonly entries: readonly TocEntryPlan[];
    readonly bookmarksToCreate: readonly {
        paragraphId: string;
        name: string;
    }[];
};

projectDrawingfunctionSource ↗

Project one w:drawing into the resolved shape layout and chrome read.

Bounded throughout: extents, crops and nesting all come from a file. Returns a projection that reports hidden and its locks rather than throwing, so an unusable drawing degrades to something the surface can skip.

declare function projectDrawing(drawing: OoxmlDrawingNode, context: Readonly<{
    ownerPartName: string;
    supportedMcRequires: ReadonlySet<string>;
    limits: DrawingProjectionLimits;
    namespaceScope?: ReadonlyMap<string, string>;
    resolveRelationship?: RelationshipTargetResolver;
}>): DrawingProjection | null;

propertyContainerfunctionSource ↗

A node's own property container (w:pPr, w:rPr) among its children.

A container the canonical read demoted to generic is still the node's own properties — matching only the typed kind lost the whole set.

declare function propertyContainer(parent: OoxmlNode | null | undefined, kind: 'paragraphProperties' | 'runProperties', localName: 'pPr' | 'rPr'): OoxmlNode | undefined;

readCustomXmlNodefunctionSource ↗

One node by id, or null.

declare function readCustomXmlNode(pkg: OoxmlPackage, partName: string, nodeId: string): CustomXmlNode | null;

readEmbeddedFontsfunctionSource ↗

Every font the package embeds, deobfuscated.

Silently skips anything malformed rather than rejecting the document: a broken font table is a reason to fall back to substitution, never a reason to refuse to open the file.

declare function readEmbeddedFonts(pkg: OoxmlPackage, fontTable: OoxmlPart | undefined, options?: ReadEmbeddedFontsOptions): EmbeddedFont[];

readOnOffChildfunctionSource ↗

OOXML on/off toggle: on only when a same-namespace child is present and its w:val (same namespace as the child) does not explicitly disable. Foreign-namespace siblings with the same local name cannot turn the flag on.

declare function readOnOffChild(parent: OoxmlNode, localName: string, namespaceUri?: string): boolean;

readOoxmlPackagefunctionSource ↗

Load DOCX bytes into canonical trees, bounded at every step.

THE trust boundary for a document. Composes the hardened primitives — zip limits and OPC name normalization, content-type indexing, relationship validation, entity-free XML — into one loader, and returns a typed rejection rather than throwing from inside a decoder.

declare function readOoxmlPackage(bytes: Uint8Array, limits?: OoxmlPackageLimits): OoxmlPackageResult;

readOoxmlPartfunctionSource ↗

Read one XML part into the additive typed/generic foundation. Existing package parsing and DocumentStore models intentionally remain unchanged until their later migration tasks; this tree is not yet the repository's sole runtime authority. Structural-path IDs are deterministic across normalized reopen. Preserving an identity through moves and edits is deferred to PackageModel/DocumentStore integration.

declare function readOoxmlPart(xml: string, metadata: OoxmlPartMetadata, limits?: XmlLimits): OoxmlReadResult;

readTrackingSettingsfunctionSource ↗

Read the tracking settings from a settings.xml root, or the defaults when it has none.

declare function readTrackingSettings(settingsRoot: OoxmlNode | null | undefined): DocumentTrackingSettings;

readXmlfunctionSource ↗

Read XML at the trust boundary: bounded, entity-free, and fidelity-preserving.

Pre-rejects DTDs and entity constructs, disables expansion and value coercion, and keeps child order, attributes, whitespace and raw lexical form — everything a lossless re-emit needs.

declare function readXml(xml: string, limits?: XmlLimits): XmlResult;

readZipfunctionSource ↗

Inflate a ZIP archive with bounds + OPC name normalization. Entry name, count, compression-ratio, and total-uncompressed-size limits are enforced BEFORE each entry is decompressed (via fflate's pre-inflation filter), so a zip bomb or a traversal name is rejected without ever being inflated. Keys are canonical part names.

declare function readZip(bytes: Uint8Array, limits?: ZipLimits): ZipReadResult;

relationshipsOffunctionSource ↗

Relationship records owned by one part, in authored order.

declare function relationshipsOf(pkg: OoxmlPackage, ownerPart: string): readonly RelationshipRecord[];

relationshipTargetInfunctionSource ↗

What a part's relationships answer for one r:id, over both maps.

relationships holds the internal records and externalTargets the external ones, so a resolver reading only the first sees every hyperlink as dangling.

declare function relationshipTargetIn(pkg: OoxmlPackage, ownerPart: string, relationshipId: string): {
    readonly target: string;
    readonly external: boolean;
    readonly sinkSafe?: boolean;
} | null;

relsPartNameForfunctionSource ↗

The .rels part that owns a part's relationships, by OPC convention.

declare function relsPartNameFor(partName: string): string;

removeCustomNodeWritefunctionSource ↗

Remove a control and, in the same transaction, the payload it bound.

The sweep would collect the node eventually — that is what makes deletion in Word survivable — but "eventually" is the next open, and a document saved in between carries a payload for a chip that is gone. Doing it here means the ordinary case is exact and the sweep is a backstop.

declare function removeCustomNodeWrite(store: TreeDocumentStore, controlNodeId: string): CustomNodeWriteResult;

removeNodefunctionSource ↗

Remove a node and its subtree.

declare function removeNode(part: OoxmlPart, nodeId: string, options?: EditOptions): OoxmlEditResult;

replaceChildrenfunctionSource ↗

Replace one node's children wholesale.

declare function replaceChildren(part: OoxmlPart, nodeId: string, children: readonly OoxmlNode[], options?: EditOptions): OoxmlEditResult;

replaceNodefunctionSource ↗

Replace one node with another, keeping its position among its siblings.

declare function replaceNode(part: OoxmlPart, nodeId: string, replacement: OoxmlNode, options?: EditOptions): OoxmlEditResult;

replayFixturefunctionSource ↗

Replay a fixture against a store and check every step's outcome, committed revision, and authored-state fingerprint against the fixture's expectations.

declare function replayFixture(fixture: ConformanceFixture, store: ReplayStore): ReplayReport;

resolvefunctionSource ↗

Resolve a set of bundles into one registry, or throw.

Deterministic and registration-order independent: selection is by (kind, id) plus version, and ties break only on declared policy. Array order never decides anything.

declare function resolve(bundles: readonly FeatureBundle[], options?: ResolveOptions): ResolvedRegistry;

resolveContentControlLockfunctionSource ↗

Resolve the lock a position inherits from the controls enclosing it.

CONSERVATIVE, because a template that says a field cannot be edited and sits inside a section that says it cannot be removed means both. Each half of ST_Lock is taken independently and the strongest wins, so an unlocked control inside a contentLocked one is still content-locked — a nested control cannot grant a permission its parent withheld, which is the only reading under which a lock is a lock.

declare function resolveContentControlLock(chain: readonly ContentControlLock[]): ContentControlLock;

resolveContentTypefunctionSource ↗

Resolve a part's content type: Override wins over Default; else unknown.

declare function resolveContentType(index: ContentTypeIndex, partName: string): ResolveResult;

resolveContentTypeOffunctionSource ↗

The content type that resolves for a part name, or null when nothing declares one.

declare function resolveContentTypeOf(pkg: OoxmlPackage, partName: string): string | null;

resolveEndnotePropertiesfunctionSource ↗

Resolve endnote properties: section → document → defaults. pageBottom is never a legal endnote position — falls back.

declare function resolveEndnoteProperties(section?: AuthoredNoteProperties, document?: AuthoredNoteProperties): ResolvedEndnoteProperties;

resolveFootnotePropertiesfunctionSource ↗

Resolve footnote properties: section → document → defaults. Illegal position strings fall through to the next layer / default.

declare function resolveFootnoteProperties(section?: AuthoredNoteProperties, document?: AuthoredNoteProperties): ResolvedFootnoteProperties;

resolveHeaderFooterPartsfunctionSource ↗

Resolve the main-document header/footer references to their parts, gated by the settings the section actually declares.

Returns the FINAL section's effective parts (after inheritance). Multi-section hosts should prefer resolveHeaderFooterPartsBySection.

declare function resolveHeaderFooterParts(pkg: OoxmlPackage): HeaderFooterParts;

resolveHeaderFooterPartsBySectionfunctionSource ↗

Resolve header/footer parts for every section, applying OOXML inheritance.

Index aligns with enumerateDocumentSections in the layout package.

declare function resolveHeaderFooterPartsBySection(pkg: OoxmlPackage): readonly HeaderFooterParts[];

resolveHeaderFooterResolutionBySectionfunctionSource ↗

Resolve header/footer parts for every section with declared-vs-inherited metadata.

Index aligns with enumerateDocumentSections in the layout package. Existing merged maps stay available via [resolveHeaderFooterPartsBySection](resolveHeaderFooterPartsBySection).

declare function resolveHeaderFooterResolutionBySection(pkg: OoxmlPackage): readonly HeaderFooterSectionResolution[];

resolveImageRelationshipfunctionSource ↗

Resolve an image relationship id from an owner part. Internal targets resolve owner-relative; external targets are never fetched; a missing id is missing.

declare function resolveImageRelationship(records: readonly RelationshipRecord[] | undefined, ownerPart: string, relationshipId: string): ImageRelationshipResolution;

resolveImageResourceLimitsfunctionSource ↗

Resolve caller overrides into frozen image limits; hard ceilings cannot be raised.

declare function resolveImageResourceLimits(overrides?: Partial<ImageResourceLimits>): ImageResourceLimits;

resolveInternalTargetfunctionSource ↗

Resolve an internal relationship target against its owner part, without escaping the package root. ownerPartName is a canonical part name; the base is its containing folder. A leading "/" target is package-absolute. ./.. segments resolve on a stack; popping above root is traversal-escape.

declare function resolveInternalTarget(ownerPartName: string, rawTarget: string): NameResult;

resolveLimitsfunctionSource ↗

Resolve caller overrides into a frozen, always-finite limit set. Each value is min(override>0 ? override : default, ceiling). Infinity/0/negative/NaN can never disable a limit — the hard ceiling always wins.

declare function resolveLimits(overrides?: Partial<ResourceLimits>): ResourceLimits;

resolveNotesPartfunctionSource ↗

Resolve the footnotes or endnotes part via safe Internal document relationships.

Unusable matching relationships (External, unsafe target, missing part, wrong root) are skipped — never fetched, never accepted — so a decoy first match cannot hide a later usable Internal notes part (same continue-past-bad pattern as settingsPartOf).

declare function resolveNotesPart(pkg: OoxmlPackage, noteKind: NoteKind): OoxmlPart | null;

resolveRelationshipfunctionSource ↗

Resolve a relationship to a runtime projection while the raw target stays authored. Internal - owner-relative part name; External - sink-safe validation only (never owner-resolved, never fetched). raw is always the verbatim authored target.

declare function resolveRelationship(rec: RelationshipRecord): ResolvedRelationship;

resolveTocRowHeadingsfunctionSource ↗

The heading each cached result row stands for, aligned with toc.resultParagraphIds.

null for a row that names no heading this document still has — a stale row, or the chrome/blank paragraphs a cached result can carry. Callers leave those alone rather than writing another row's number into them.

declare function resolveTocRowHeadings(part: OoxmlPart, toc: DetectedToc, outline: readonly TocOutlineHeading[], excludeParagraphIds: ReadonlySet<string>): readonly (string | null)[];

reviewItemKeyfunctionSource ↗

The stable key a surface uses for the active item and for a React list.

declare function reviewItemKey(item: ReviewItem): string;

reviewItemRangesfunctionSource ↗

Every range a decision touches. One card can cover several, in different paragraphs.

Exported because the geometry half in the layout lane asks the same question, and a second copy of "which ranges does this item cover" is how a card comes to be painted over one range and activated by another.

declare function reviewItemRanges(item: ReviewItem): readonly ReviewRange[];

revisionItemsOffunctionSource ↗

Every revision in one story, one card per DECISION.

Sites sharing an (id, author, date) triple are ONE revision — a tracked row insertion is w:trPr/w:ins plus w:cellIns on every cell — so they coalesce into one card listing every range it touches. Keying per site would show the reviewer four decisions where there is one, and accepting any of them would make the other three vanish.

Memoized per part root like the indexes it reads, and for the same reason: a heavily tracked document produces tens of thousands of cards, and rebuilding them per read cost more than everything the memos above saved. The paragraph-scoped view the local review patch derives (revisionItemsOfParagraph's synthetic paragraph-root part) is NOT cached: each keystroke would insert a fresh root and churn the bounded ring. The instance is SHARED, so the return type is readonly.

declare function revisionItemsOf(part: OoxmlPart): readonly ReviewRevisionItem[];

runAddressRangesfunctionSource ↗

Per-run UTF-16 ranges from segmentsOf (fields/notes collapse to one unit on begin).

declare function runAddressRanges(paragraph: Extract<OoxmlNode, {
    kind: 'paragraph';
}>): Map<string, {
    start: number;
    end: number;
}>;

runPropertyEditsfunctionSource ↗

A range run-property change, split into ONE edit per run it covers, each merged over that run's own w:rPr.

Neither half of that is optional. The base MUST be the run's own properties (see this file's header). And the split MUST be per run: the op REPLACES the properties it names across its whole range, so one op carrying one run's bag over a mixed selection homogenised it — bolding hello + Georgia rewrote the second run's w:rFonts with the first's. Runs are addressed by offset rather than by id because these edits apply in sequence and the applier splits runs at the range edges; offsets are unmoved by a property write, ids are not.

declare function runPropertyEdits(part: OoxmlPart, paragraphId: string, start: number, end: number, incoming: OoxmlProperty | readonly OoxmlProperty[]): readonly RunPropertyEdit[];

runsCoveringfunctionSource ↗

Every run that contributes at least one character of [start, end), in document order.

A COLLAPSED range answers the run it sits inside, which is what a caret reads. Callers that want the empty answer for a collapsed range check the offsets themselves.

declare function runsCovering(part: OoxmlPart, paragraphId: string, start: number, end: number): readonly OoxmlNode[];

sanitizeHreffunctionSource ↗

Project a file-derived URL for a DOM/navigation sink. Strips embedded tab/LF/CR (used to smuggle java\nscript:), allows relative URLs and the scheme allowlist, and renders everything else inert. Never fetches.

declare function sanitizeHref(raw: string): HrefProjection;

satisfiesfunctionSource ↗

Whether version satisfies range. Supported range grammar: - * any version - 1.2.3 exact - ^1.2.3 caret: same major, and = the floor (major 0 pins the minor) - >=1.2.3 <2.0.0 a single lower (inclusive) + upper (exclusive) bound pair Any other shape throws — an unparseable range is a registration error, not a pass.

declare function satisfies(version: string, range: string): boolean;

scrubExportfunctionSource ↗

Explicit scrub export: remove inert executable classes, report removals.

declare function scrubExport(items: readonly ContentItem[]): ScrubResult;

segmentsOffunctionSource ↗

Flatten a paragraph into UTF-16 addressable segments, in document order.

A HYPERLINK's runs are addressed too. w:hyperlink is a run container, not a leaf, and the characters inside a link are ordinary paragraph text: the user selects them, types over them and deletes them like any other. Skipping the container — which is what iterating only direct w:r children did — left every link's text with no offsets at all, so paragraphTextOf read "Visit or ." for a sentence that says "Visit Example.com or Anthropic's website." and layout, selection and the ops all agreed on the wrong string.

Inline CONTENT CONTROLS are the same class of wrapper: their w:sdtContent runs join the paragraph's offset stream with no break opportunity at the boundary. Nesting is bounded (MAX_CONTENT_CONTROL_NESTING); beyond the bound the wrapper is opaque so recursion cannot exhaust the stack.

runId stays the id of the run the content actually lives in, at whatever depth: the appliers resolve it with findNode and rebuild that run's children, so nesting costs them nothing.

declare function segmentsOf(paragraph: OoxmlParagraphNode): Segment[];

semanticDigestfunctionSource ↗

Digest every part, in the given order.

declare function semanticDigest(parts: Iterable<OoxmlPart>): SemanticDigest;

serializeOoxmlPartfunctionSource ↗

Serialize normalized XML from a canonical part using repository-controlled prefixes and validated, escaped names and values. This does not yet replace writeDocx; package integration belongs to the subsequent migration pass.

declare function serializeOoxmlPart(part: OoxmlPart): string;

setCommentResolvedfunctionSource ↗

Mark a comment thread resolved, or reopen it.

A THREAD, not one remark: Word resolves a conversation, and its own pane greys the replies with the comment they answer. Resolving only the parent would leave a file whose reply still reads as open under a closed remark — a state Word does not produce and no reader would draw sensibly.

@w15:done lives in commentsExtended.xml, which many documents do not have: a file with no reply has no thread state to record. So the part is created when it is missing, exactly as [addComment](addComment) creates it, and every comment being resolved gets an entry — a comment with no w14:paraId gets one minted, because the state is keyed by it and there is nothing else to key it by.

ONE package transaction: the part, its relationship, its content-type override and the entries commit together, so a resolved thread is never half-recorded.

declare function setCommentResolved(store: TreeDocumentStore, commentId: string, resolved: boolean): SetCommentResolvedResult;

settingsPartOffunctionSource ↗

Locate settings.xml via the main document relationship when present.

declare function settingsPartOf(pkg: OoxmlPackage): OoxmlPart | null;

sniffImageMimefunctionSource ↗

Signature sniffing — authoritative over declared content type.

declare function sniffImageMime(bytes: Uint8Array): RenderableImageMime | PreservedImageMime | 'unknown';

stableHashfunctionSource ↗

64-bit FNV-1a over the canonical form, returned as a 16-char hex string.

declare function stableHash(value: unknown, ephemera?: ReadonlySet<string>): string;

storyParagraphsfunctionSource ↗

Every paragraph of one story, in reading order.

Descends through tables (rows, cells, nested tables) and flattens block-level content controls. The returned nodes are paragraph elements; a caller addresses them by id.

declare function storyParagraphs(root: OoxmlNode): readonly OoxmlNode[];

storyRootsOffunctionSource ↗

Every story root in a part, in document order.

Does not descend INTO a story: a story's blocks are the walk below, and a story root never contains another story root.

declare function storyRootsOf(part: OoxmlPart): readonly OoxmlStoryRoot[];

stylesPartOffunctionSource ↗

The package's style definitions part, if it has one.

declare function stylesPartOf(pkg: OoxmlPackage): OoxmlPart | undefined;

sweepCustomNodePayloadsfunctionSource ↗

Drop every payload no control binds, in the stores whose namespaces a host claims.

ON OPEN, NOT ON SAVE. A chip cut to the clipboard is unbound for as long as it sits there, so a save mid-cut would destroy the payload the user is about to paste. On open the only unbound nodes are ones a control genuinely lost — deleted here, or deleted in Word, which is the case nothing else can collect.

namespaces is the claim, and it is what keeps this off other people's stores: Word's own Cover Page Properties store rides in most templates, and a sweep that walked every customXml part would be deleting from it on the strength of a name collision.

declare function sweepCustomNodePayloads(pkg: OoxmlPackage, storyPartName: string, namespaces: readonly string[]): CustomNodeSweepResult;

textContentfunctionSource ↗

Concatenated text content of an element (all descendant text nodes).

declare function textContent(node: Extract<XmlNode, {
    type: 'element';
}>): string;

threadStateOfPartfunctionSource ↗

Thread state by w14:paraId, from commentsExtended.xml.

The part being PRESENT is not evidence of threading. issue-68-large-comments-suggestions.docx ships it with 212 entries carrying @w15:done and not one @w15:paraIdParent, so it records resolved state for a flat list. Absent parent means top-level, and that is a fact about the file rather than a default this code chose.

declare function threadStateOfPart(part: OoxmlPart): Map<string, CommentThreadState>;

tocEntryTextfunctionSource ↗

Word flattens manual line/tab breaks from a heading into spaces in its TOC cache. Carrying them verbatim makes a short title wrap even when the row has ample room, and the same normalization is what lets a cached row be matched back to the heading it came from.

declare function tocEntryText(text: string): string;

tocLeftIndentTwipsfunctionSource ↗

Bounded left-indent twips for a TOC entry level (0-based heading depth).

declare function tocLeftIndentTwips(level: number): number;

toSafeRecordfunctionSource ↗

Recursively convert value into null-prototype records, rejecting any dangerous object key. Arrays and primitives pass through (arrays rebuilt so no inherited prototype pollution survives). Throws DangerousKeyError on the first unsafe key, naming its path. Cyclic inputs are rejected.

declare function toSafeRecord(value: unknown, path?: string): unknown;

usedParaIdsfunctionSource ↗

Every valid w14:paraId in the tree, uppercased. Memoized per root object.

declare function usedParaIds(root: OoxmlElement): ReadonlySet<string>;

validateDrawingOpfunctionSource ↗

Validate a drawing op's extents, crops and positions before it reaches the store.

declare function validateDrawingOp(part: OoxmlPart, op: DrawingTreeDocOp): TreeOpRejection | null;

validateExternalTargetfunctionSource ↗

Validate an external-mode relationship target. It MUST be an absolute URI, is retained verbatim by the caller, and is NEVER owner-resolved or fetched here. Unsafe schemes (javascript/vbscript/data/file) are rejected for runtime sinks; the raw lexical form is still preserved separately by the authored record.

declare function validateExternalTarget(raw: string): NameResult;

validateFixturefunctionSource ↗

Structurally validate a fixture against the frozen format rules.

declare function validateFixture(fixture: ConformanceFixture): ValidationResult;

validateGifHeaderfunctionSource ↗

Structural GIF logical screen descriptor validation before decode.

declare function validateGifHeader(bytes: Uint8Array): ValidatedRasterHeader | null;

validateJpegHeaderfunctionSource ↗

Bounded JPEG marker scan through the first supported SOF marker.

declare function validateJpegHeader(bytes: Uint8Array): ValidatedRasterHeader | null;

validateOoxmlPartfunctionSource ↗

Validate a parser-created or copy-modified immutable part before publication. Future tree-edit primitives can retain shared nodes and their IDs, while any replacement chooses explicitly whether to retain or allocate identity.

declare function validateOoxmlPart(part: OoxmlPart): OoxmlInvariantResult;

validatePackageInvariantsfunctionSource ↗

The two invariants a package must satisfy before it is published.

Both describe the half-written state that splitting a multi-part write across transactions produces, and both make a package Word refuses to open:

- a relationship pointing at a part nobody created; - a part with no content type, which is unopenable even though the XML is well formed.

Checked at the commit boundary rather than inside each primitive, for the same reason part validation moved there: a transaction is allowed to pass through an inconsistent intermediate as long as nothing can observe it.

declare function validatePackageInvariants(pkg: OoxmlPackage): PackageInvariantResult;

validatePngHeaderfunctionSource ↗

Structural PNG IHDR validation before decode.

declare function validatePngHeader(bytes: Uint8Array): ValidatedRasterHeader | null;

validateRasterHeaderfunctionSource ↗

Validate a raster image's header structurally and report its real MIME type and extent.

Content type is a CLAIM; this is what makes it a fact. A file declaring image/png over JPEG bytes is caught here rather than at decode.

declare function validateRasterHeader(bytes: Uint8Array, mime: SupportedImageMime): ValidatedRasterHeader | null;

validateTreeOpfunctionSource ↗

Structural validation, run before any tree work so a rejection changes nothing.

declare function validateTreeOp(part: OoxmlPart, op: TreeDocOp): TreeOpRejection | null;

w14RootPrefixfunctionSource ↗

The non-empty prefix the part ROOT binds to the w14 namespace, or null.

Minted attributes require an in-scope binding (the invariant validator reports invalid-qname otherwise, and the serializer would allocate an nsN alias). Only the root binding counts: a binding authored on some descendant does not cover paragraphs elsewhere in the tree.

declare function w14RootPrefix(root: OoxmlElement): string | null;

walkAllStoryParagraphsfunctionSource ↗

Every story paragraph in reading order — body, table cells, and flattened block controls.

declare function walkAllStoryParagraphs(children: readonly OoxmlNode[], sdtDepth: number, visit: (paragraph: OoxmlElement) => void): void;

walkParagraphInlinefunctionSource ↗

Paragraph-level inline sequence — runs, hyperlinks, and inline content controls in order.

visit receives each direct w:r and any other inline node the caller treats as opaque (bookmarks, drawings, …). Hyperlinks and content controls are descended transparently.

declare function walkParagraphInline(children: readonly OoxmlNode[], depth: number, visit: (child: OoxmlNode) => void): void;

walkStoryBlocksfunctionSource ↗

Story blocks in document order, flattening block-level content controls — same shape as layout's storyBlocks and store bodyBlocks.

declare function walkStoryBlocks(children: readonly OoxmlNode[], depth: number, visit: (block: OoxmlElement) => void): void;

withBinaryPartfunctionSource ↗

Store raw bytes for a part and declare its exact content type.

Does not create a relationship; callers decide which owner points at the part.

declare function withBinaryPart(pkg: OoxmlPackage, partName: string, bytes: Uint8Array, contentType: string): OoxmlPackage;

withContentTypeOverridefunctionSource ↗

Declare a content type for a part, by upserting an <Override> in the content-types tree.

A no-op when the part already resolves to the same type, so repeating a write does not append a duplicate entry. Resolving to a DIFFERENT type replaces the existing Override in place. forceOverride writes an explicit Override even when a Default already matches.

declare function withContentTypeOverride(pkg: OoxmlPackage, partName: string, contentType: string, options?: {
    readonly forceOverride?: boolean;
}): OoxmlPackage;

withCustomXmlDataPartfunctionSource ↗

Ensure the document carries a data part for this namespace, creating it and everything it needs — properties, both relationships, the properties content type — when it does not.

Idempotent: a package that already has one for the namespace comes back untouched, so a second node added to the same store does not author a second store.

declare function withCustomXmlDataPart(pkg: OoxmlPackage, storyPartName: string, namespaceUri: string, rootLocalName: string): CustomXmlDataPartResult;

withCustomXmlNodefunctionSource ↗

Write a node, replacing one that already has the id.

Replace rather than append: a second node with the same id makes the binding xpath ambiguous, and Word resolves an ambiguous xpath to the first match — so an "update" that appended would leave the control showing its old text forever.

declare function withCustomXmlNode(pkg: OoxmlPackage, partName: string, node: CustomXmlNode): OoxmlPackage;

withEmbeddedImagefunctionSource ↗

Add image bytes to the package: the media part, its content type, and the relationship.

All three together — bytes with no relationship are unreachable, and a relationship with no content-type record makes the package invalid.

declare function withEmbeddedImage(pkg: OoxmlPackage, ownerPartName: string, input: Readonly<{
    bytes: Uint8Array;
    mime: SupportedImageMime;
}>): Readonly<{
    ok: true;
    pkg: OoxmlPackage;
    partName: string;
    relationshipId: string;
    docPrId: number;
}> | Readonly<{
    ok: false;
    reason: 'invalidArgs' | 'invalid-image';
}>;

withExportedCustomNodesfunctionSource ↗

Apply the policy, then take the payloads and the stores the policy orphaned.

Order matters and is the reverse of the write's. The BODY goes first, so the sweep that follows sees the controls that actually survive; the stores go last, once nothing binds them. Doing it the other way would strip a store while a control still quoted its w:storeItemID, which is a document Word opens and offers to repair.

declare function withExportedCustomNodes(pkg: OoxmlPackage, request: CustomNodeExportRequest): CustomNodeExportResult;

withNewPartfunctionSource ↗

Add a part that does not exist yet, with the content-type override it needs to be openable.

Deliberately does NOT create a relationship: a part is reachable because something points at it, and which part points at it is the caller's decision. Creating one here would guess.

declare function withNewPart(pkg: OoxmlPackage, partName: string, root: OoxmlElement, contentType: string): OoxmlPackage;

withoutCustomXmlDataPartfunctionSource ↗

Remove a store from a document: both parts, both relationships, the Override.

PACKAGE ONLY. It does not touch the body, so a w:sdt bound to the store keeps its w:dataBinding, its w:storeItemID and its w:tag, and Word then opens a control bound to a store that is not there. Stripping those is the export path's job and is not built; this is the half that removes the payload, which is the half a caller can rely on.

ok: false means nothing was removed and the package is unchanged — most often because an owner's .rels was never parsed into a tree, which [withoutPart](withoutPart) refuses to work around. A caller exporting a document has to treat that as a failure to export rather than as a document with nothing to strip, or it ships the payload it meant to remove.

declare function withoutCustomXmlDataPart(pkg: OoxmlPackage, storyPartName: string, namespaceUri: string): WithoutPartResult;

withoutCustomXmlNodefunctionSource ↗

Drop one node by id. A store that never held it comes back unchanged.

declare function withoutCustomXmlNode(pkg: OoxmlPackage, partName: string, nodeId: string): OoxmlPackage;

withoutOrphanCustomXmlNodesfunctionSource ↗

Drop every node no longer referenced, given the ids the document still binds.

This is the whole deletion story. Deleting a control in THIS editor can remove its node directly, but a control deleted in Word leaves the node behind — Word has no lifecycle link between the two and no way to run our code. Reconciling against what the story actually binds collects both, and is the only thing that can collect the second.

Takes the referenced ids rather than reading the story itself: the caller already walked it, and a sweep that guessed at which controls exist would delete a payload on a mistake.

declare function withoutOrphanCustomXmlNodes(pkg: OoxmlPackage, partName: string, referencedIds: ReadonlySet<string>): {
    readonly pkg: OoxmlPackage;
    readonly removed: readonly string[];
};

withoutUnreferencedImagePartfunctionSource ↗

Remove an orphaned image media part after a package-wide internal relationship target check.

declare function withoutUnreferencedImagePart(pkg: OoxmlPackage, partName: string): OoxmlPackage;

withPartfunctionSource ↗

Replace one part's tree, returning a new package. Pure, like the tree edits themselves.

declare function withPart(pkg: OoxmlPackage, part: OoxmlPart): OoxmlPackage;

withRelationshipfunctionSource ↗

Add or replace one relationship on a part, returning a new package.

declare function withRelationship(pkg: OoxmlPackage, ownerPart: string, type: string, rawTarget: string): {
    readonly pkg: OoxmlPackage;
    readonly relationshipId: string;
    readonly ok: boolean;
};

wrapTargetToAnchorSpecfunctionSource ↗

Map the nine wrap targets to anchor wrap element + behindDoc.

declare function wrapTargetToAnchorSpec(target: ImageWrapTarget): {
    readonly behindDocument: boolean;
    readonly wrapLocalName: 'wrapNone' | 'wrapSquare' | 'wrapTight' | 'wrapThrough' | 'wrapTopAndBottom';
    readonly wrapText?: 'bothSides' | 'left' | 'right' | 'largest';
};

writeOoxmlPackagefunctionSource ↗

Serialize a canonical package back to DOCX bytes.

Starts from the ORIGINAL entry bytes and overwrites only the parts held as trees. A part the loader did not model — media, fonts, an XML part outside the modeled set — passes through untouched, so round-tripping a document cannot lose a part the engine never claimed to understand.

The modeled parts are re-emitted NORMALIZED from the tree rather than patched as text. That is the whole point of the canonical tree: correctness is judged by the two D9 oracles (the namespace-aware fingerprint and the save/reopen semantic digest), not by byte equality, so a different-but-equivalent spelling is not a defect.

writeZip re-validates every part name, so a name that became unsafe between load and save cannot be smuggled into the archive.

declare function writeOoxmlPackage(pkg: OoxmlPackage): Uint8Array;

writeZipfunctionSource ↗

Deflate a set of canonical-part-name - bytes into a ZIP archive. Every part name is re-validated through the OPC normalization profile before writing, so a traversal/encoded/normalized-alias name from an untrusted serialized model can never be smuggled into a ZIP entry (write-side path-traversal guard).

declare function writeZip(entries: ReadonlyMap<string, Uint8Array>): Uint8Array;

BoundedCounterclassSource ↗

Overflow-safe counting against a fixed limit.

Never silently wraps: it rejects the increment that would cross its limit AND any arithmetic that would exceed Number.MAX_SAFE_INTEGER. That second guard is the point — a file-supplied count must never be trusted into an allocation, and a wrapped counter reads as small.

declare class BoundedCounter

BudgetclassSource ↗

One node in the hierarchical resource budget tree.

An operation owns a root budget; parsers, extensions, workers, layout, transport and output carve children from it, so no subsystem can consume more than the operation as a whole allows.

dispose() REFUSES while children or reservations are outstanding, then runs registered cleanups LIFO — spill files, worker termination — even if one throws. A leaked child budget is a leaked worker, so the refusal is the diagnostic.

declare class Budget

BudgetErrorclassSource ↗

A budget was misused: over-carved, over-reserved, or disposed with children outstanding.

declare class BudgetError extends Error

CancellationControllerclassSource ↗

The write side of cancellation, and the owner of the phase.

Whoever starts an operation holds this; everything it calls gets only the token.

declare class CancellationController

CancellationErrorclassSource ↗

Thrown from a checkpoint() when the operation has been cancelled.

declare class CancellationError extends Error

DangerousKeyErrorclassSource ↗

A file-derived key that would pollute a prototype. Refused, never sanitized-and-accepted.

declare class DangerousKeyError extends Error

DeterministicClockclassSource ↗

Deterministic clock: starts at start and advances by step each call.

declare class DeterministicClock implements ClockPort

DeterministicMemoryMeterclassSource ↗

Deterministic memory substitute. Tracks current and peak "allocated" units against a hard byte ceiling; allocate fails closed (LimitExceededError) past the limit. Used in place of process RSS so memory-limit tests are reproducible and cancellation/cleanup can be asserted without a real allocator.

declare class DeterministicMemoryMeter

LimitExceededErrorclassSource ↗

A counter's limit was reached. Carries the label, the limit, and what was attempted.

Thrown at the N → N+1 boundary, so the increment that would have crossed the limit never happens rather than being detected afterwards.

declare class LimitExceededError extends Error

PortRegistryclassSource ↗

The environment-dependent services an engine instance may reach.

Everything outside pure computation — the clock, identity minting, scheduling, fonts, images — is reached only through here, which is what lets browser, worker and server adapters supply only what their runtime actually offers.

declare class PortRegistry

PortResolutionErrorclassSource ↗

A required port the runtime did not provide.

Thrown rather than falling back: silently reaching for a browser global when a worker or server adapter did not supply a port is exactly the coupling ports exist to prevent.

declare class PortResolutionError extends Error

PrefixAllocatorclassSource ↗

Controlled namespace-prefix allocation: deterministic, collision-free prefixes for namespace URIs. A known URI always yields the same registered prefix; new URIs get a generated ns{n} prefix, never one derived from file content.

declare class PrefixAllocator

RegistryErrorclassSource ↗

A resolution failure naming every responsible party.

Thrown rather than returned: an unresolvable registry is a build-time composition mistake, and an engine running with a half-resolved registry would fail later in ways that do not point back to the bundle that caused it.

declare class RegistryError extends Error

SequentialIdentityclassSource ↗

Sequential identity for tests and deterministic fixtures.

declare class SequentialIdentity implements IdentityPort

TreeDocumentStoreclassSource ↗

The document store: one transaction is one atomic publication and one history entry.

apply STAGES ops against a working part and nothing is visible until transact returns, so a batch rejected halfway leaves the revision, the tree, the indexes and every subscriber exactly as they were. That all-or-nothing property is what lets a caller compose ops without having to reason about partial application.

declare class TreeDocumentStore

TreePackageStoreclassSource ↗

Package-level mutation authority: routes TreeDocOps to the store for a story part, publishes one ModelChange / undo unit per transaction, and keeps currentPackage() coherent for save/reopen.

declare class TreePackageStore

AddCommentRequestinterfaceSource ↗

What adding a comment needs: where it anchors, who wrote it, and its body.

author is required because CT_Comment makes @w:author mandatory — a comment without one writes invalid XML, so the write is refused rather than filled with an empty attribute.

interface AddCommentRequest

AnchorSnapshotinterfaceSource ↗

Where anchors sat after a step — how a fixture proves positions survived an edit.

interface AnchorSnapshot

AtomicFieldSpaninterfaceSource ↗

One atomic field span inside a paragraph for caret / delete / selection.

removeNodeIds lists every node that must leave with the unit (begin…end chrome and cached-result content for complex fields; the fldSimple element for simple fields).

formatRunIds lists the runs whose w:rPr owns displayed result formatting — result-phase runs with measurable cache text for complex fields, child w:rs for fldSimple, or the separate/begin run when the result is empty. Delete / caret addressing still uses runId (the begin / simple node); formatting must not rewrite chrome-only begin runs when the painted glyphs come from a different result run.

interface AtomicFieldSpan

AtomicNoteSpaninterfaceSource ↗

One atomic note span inside a paragraph for caret / delete / selection.

Each typed note atom is a single-node span (removeNodeIds = that node).

interface AtomicNoteSpan

AuditPortinterfaceSource ↗

Redacted observability sink (raw text never enters here — design D5).

interface AuditPort

AuthoredNotePropertiesinterfaceSource ↗

Authored subset — only keys present in the file appear.

interface AuthoredNoteProperties

AuthorizationPortinterfaceSource ↗

Read/write/export authorization decisions.

interface AuthorizationPort

BookmarkAnchorinterfaceSource ↗

One bookmark's name and the range its marker pair currently encloses.

interface BookmarkAnchor

CancellationPortinterfaceSource ↗

Cancellation source for the current operation.

interface CancellationPort

CancellationTokeninterfaceSource ↗

The read side of cancellation, handed to cooperative work.

Cooperative rather than pre-emptive: long work calls checkpoint() at declared intervals, which is what lets an operation unwind promptly without the engine having to interrupt it mid-mutation.

interface CancellationToken

CapabilityIdinterfaceSource ↗

A validated (kind, id, version) triple — the registry's unit of identity.

interface CapabilityId

CascadeDeletedNoteReferencesOptionsinterfaceSource ↗

How deleting text cascades into the notes it referenced.

A note's body and the citation reaching it are one thing to a reader, so removing the reference must remove the body too or the notes part keeps an entry nothing points at.

interface CascadeDeletedNoteReferencesOptions

ClockPortinterfaceSource ↗

Injectable time source — the engine never calls Date.now directly (determinism).

interface ClockPort

CommentAnchorinterfaceSource ↗

Where a comment is anchored, as a range.

orphaned records that the file did not give this comment a usable range — a reference with no range markers, or a start with no end. The comment is still listed, marked orphaned, rather than dropped: a reviewer's remark disappearing silently is worse than one that says it lost its text.

interface CommentAnchor

CommentAnchorRequestinterfaceSource ↗

Where a comment is anchored, in the model offset space of one story.

interface CommentAnchorRequest

CommentPositioninterfaceSource ↗

A position in one story: a paragraph node id plus a UTF-16 offset inside it.

interface CommentPosition

CommentRecordinterfaceSource ↗

One comment as authored in word/comments.xml.

interface CommentRecord

CommentThreadStateinterfaceSource ↗

Thread state for one comment, read from commentsExtended.xml.

interface CommentThreadState

ComparatorDescriptorinterfaceSource ↗

One artifact class's comparison mode and its declared ephemera — fields excluded from equality.

interface ComparatorDescriptor

ComparisonResultinterfaceSource ↗

Whether two artifacts matched, and where they diverged when they did not.

interface ComparisonResult

ConformanceFixtureinterfaceSource ↗

The frozen conformance container: revisions, origins, operations, changes, snapshots and hashes.

The CONTAINER is what is frozen — field names, origin membership, revision monotonicity, hash format. The op and change payloads travel opaquely, so their schemas can evolve without invalidating every recorded fixture.

interface ConformanceFixture

ContentControlCheckboxinterfaceSource ↗

A checkbox's state and the two glyphs it chooses between.

Both glyphs matter on a write: setting the value has to update w14:checked AND the run's character, or the document's glyph and its recorded state disagree.

interface ContentControlCheckbox

ContentControlCheckboxStateinterfaceSource ↗

One of a checkbox's two glyphs: the font and code point it is drawn with.

interface ContentControlCheckboxState

ContentControlDataBindinginterfaceSource ↗

w:dataBinding — the custom-XML part and XPath a control's value is bound to.

interface ContentControlDataBinding

ContentControlDateFormatinterfaceSource ↗

A date picker's authored format and locale, for rendering and for parsing what it stores.

interface ContentControlDateFormat

ContentControlEntryinterfaceSource ↗

One control, plus how deeply it is nested and the controls that enclose it.

interface ContentControlEntry

ContentControlListIteminterfaceSource ↗

One declared option of a dropdown or combo box: its display text and its stored value.

interface ContentControlListItem

ContentControlPropertiesinterfaceSource ↗

A control's whole w:sdtPr, projected into one typed shape.

What every other lane reads instead of walking localName strings — which also means a Word re-save that demotes the properties node to generic does not break the projection.

interface ContentControlProperties

ContentIteminterfaceSource ↗

One item a scrub pass considers: its kind, and where in the package it sits.

interface ContentItem

ContentTypeIndexinterfaceSource ↗

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

interface ContentTypeIndex

ContentTypeRecordsinterfaceSource ↗

The authored [Content_Types].xml records, in significant order.

Retained rather than collapsed into a lookup, because the file's lexical form and ordering are part of what a lossless save re-emits.

interface ContentTypeRecords

ContributioninterfaceSource ↗

One thing a bundle contributes: a command, a query, a schema, a port, keyed by (kind, id).

interface Contribution

CreateImageResourceCacheOptionsinterfaceSource ↗

How the image cache decodes, and what it will spend doing so.

interface CreateImageResourceCacheOptions

CustomNodeBindinginterfaceSource ↗

The three attributes a w:dataBinding carries.

interface CustomNodeBinding

CustomNodeExportRequestinterfaceSource ↗

How [withExportedCustomNodes](withExportedCustomNodes) decides, and which stores it may tidy afterwards.

interface CustomNodeExportRequest

CustomNodePayloadReadinterfaceSource ↗

One control's payload, as the store holds it. Both strings are untrusted file input.

interface CustomNodePayloadRead

CustomNodePayloadWriteinterfaceSource ↗

The payload half of an insert: which store, which node, and what it holds.

data is opaque here. The lane that owns a schema is the one that declared it, and a store that parsed payloads would be a second opinion about what a host's node means.

interface CustomNodePayloadWrite

CustomXmlDataPartinterfaceSource ↗

A data part located in a package: where it lives, and the GUID an SDT binds to.

interface CustomXmlDataPart

CustomXmlDataPartResultinterfaceSource ↗

What [withCustomXmlDataPart](withCustomXmlDataPart) answers.

interface CustomXmlDataPartResult

CustomXmlNodeinterfaceSource ↗

One node in a store: its id, the bound text, and the payload beside it.

interface CustomXmlNode

DefaultRecordinterfaceSource ↗

One <Default>: a file extension mapped to a content type.

interface DefaultRecord

DetectedTocinterfaceSource ↗

A table of contents found in a document, whether wrapped in an SDT or a bare field.

interface DetectedToc

DocumentTrackingSettingsinterfaceSource ↗

What the document asks for. Every field defaults to "the document said nothing".

interface DocumentTrackingSettings

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

EditOptionsinterfaceSource ↗

How an edit primitive validates its result.

By default every primitive runs the full-part invariant validation before handing its result back — the safe reading for an isolated call. A TRANSACTION applying many ops pays that full-tree walk once per primitive, which is what made a hundred-paragraph paste quadratic; it defers instead, and runs the same validation ONCE on the final tree before anything is published. Deferring is only sound for a caller that owns a commit boundary: nothing may escape between the unvalidated intermediate and the validated result.

interface EditOptions

EmbeddedFontinterfaceSource ↗

One font whose bytes travel inside the package.

The family name is the DOCUMENT's and is not validated — it is attacker-controlled, so it is escaped into CSS and never registered globally on document.fonts, where it would shadow the host application's own fonts.

interface EmbeddedFont

EncodedEnvelopeinterfaceSource ↗

Opaque encoded backend bytes (snapshot or replication update).

interface EncodedEnvelope

EnsuredHyperlinkRelationshipinterfaceSource ↗

The package with a hyperlink relationship guaranteed present, and that relationship's id.

interface EnsuredHyperlinkRelationship

ExternalResourceConsentPortinterfaceSource ↗

Explicit consent gate for any remote/external resource (no zero-click fetch).

interface ExternalResourceConsentPort

FeatureBundleinterfaceSource ↗

A unit of engine functionality: its identity, version, dependencies, conflicts, required ports, and contributions.

The registry's whole input. Everything a bundle needs and everything it offers is DECLARED, so resolution can be deterministic and order-independent.

interface FeatureBundle

FixtureExpectationinterfaceSource ↗

What one step must produce: its outcome, its change summary, and its authored-state hash.

interface FixtureExpectation

FixtureStepinterfaceSource ↗

One recorded operation and what it was expected to do.

interface FixtureStep

FontPortinterfaceSource ↗

Where font bytes come from. Opaque marker until its milestone.

interface FontPort

HeaderFooterPartsinterfaceSource ↗

A section's resolved header and footer parts, by variant.

The even variant is only honoured when w:evenAndOddHeaders is set in settings.xml — without it Word ignores an authored even header, and so does this.

interface HeaderFooterParts

HeaderFooterSectionResolutioninterfaceSource ↗

Per-section resolution including declared-vs-inherited metadata.

interface HeaderFooterSectionResolution

HeaderFooterSlotMetainterfaceSource ↗

One resolved furniture slot with enough metadata for "Same as previous" chrome.

inherited: true means this section has no declared reference for the slot and the part comes from a predecessor. The first section never reports inherited — omitting a ref there is blank furniture, not inheritance from a later section.

interface HeaderFooterSlotMeta

HyperlinkTargetinterfaceSource ↗

A resolved hyperlink: its kind, its target, and the tooltip Word shows on hover.

interface HyperlinkTarget

IdentityPortinterfaceSource ↗

Stable id minting for sessions, commits, and allocator seeds.

interface IdentityPort

ImageDecodePortinterfaceSource ↗

The injected image decoder.

A port rather than a direct Image/createImageBitmap call, so a worker or server runtime supplies its own and the engine never reaches for a browser global.

interface ImageDecodePort

ImagePortinterfaceSource ↗

How image bytes are decoded. Opaque marker until its milestone.

interface ImagePort

ImageResourceLimitsinterfaceSource ↗

Trust-boundary caps specific to image decoding and embedding.

interface ImageResourceLimits

ImageResourceLookupinterfaceSource ↗

Resolves a relationship id to a validated image resource, or reports why it could not.

interface ImageResourceLookup

InlineControlSpaninterfaceSource ↗

One inline content control's identity and the UTF-16 span its content covers.

interface InlineControlSpan

InsertCustomNodeWriteinterfaceSource ↗

Where the control goes, what it says, and the payload it carries.

interface InsertCustomNodeWrite

LimitSpecinterfaceSource ↗

One limit's unit and enforcement phase — the metadata that makes limits testable uniformly.

interface LimitSpec

LinkableReviewIteminterfaceSource ↗

The shape [linkRevisionReplies](linkRevisionReplies) needs, stated STRUCTURALLY.

The store's queue is revisions and comments; the layout lane's adds a third kind for custom nodes, and neither union is assignable to the other. Both lanes have to run this pass — the store on the full derivation, the session on the locally patched list — so the pass is written against the fields it actually reads rather than against either union, and hands back the caller's own item type.

interface LinkableReviewItem

ModelChangeSummaryinterfaceSource ↗

The change one step produced, summarized to what a fixture can compare across runtimes.

interface ModelChangeSummary

NoteLifecycleOptionsinterfaceSource ↗

Attribution and limits applied to one note lifecycle op.

interface NoteLifecycleOptions

NoteReferenceHitinterfaceSource ↗

One note reference found in a story, with where it sits.

interface NoteReferenceHit

NoteReferenceScanBudgetinterfaceSource ↗

Mutable visited-node + part budget shared across parts / package snapshots.

interface NoteReferenceScanBudget

OffsetSpaninterfaceSource ↗

Half-open [start, end) of one node in its paragraph's model offset space.

interface OffsetSpan

OoxmlBodyNodeinterfaceSource ↗

w:body — the main story's block content.

interface OoxmlBodyNode extends OoxmlElementBase<readonly (OoxmlParagraphNode | OoxmlTableNode | OoxmlContentControlNode | OoxmlGenericElementNode)[], readonly OoxmlKnownNodeAttribute[]>

OoxmlBookmarkEndNodeinterfaceSource ↗

w:bookmarkEnd — the closing point anchor (@w:id), zero-length like its start.

interface OoxmlBookmarkEndNode extends OoxmlElementBase<readonly [], readonly OoxmlKnownNodeAttribute[]>

OoxmlBookmarkStartNodeinterfaceSource ↗

w:bookmarkStart — a ZERO-LENGTH point anchor (@w:id, @w:name).

It takes no text offset and paints nothing; it only marks a position, which is what an internal hyperlink's w:anchor names. Split and join place it by that position, the behaviour tree-op-split-anchors.test.ts pins.

interface OoxmlBookmarkStartNode extends OoxmlElementBase<readonly [], readonly OoxmlKnownNodeAttribute[]>

OoxmlContentControlCalendarNodeinterfaceSource ↗

w:calendar — which calendar system a date picker uses (Gregorian, Hijri, …).

interface OoxmlContentControlCalendarNode extends OoxmlElementBase<readonly [], readonly (OoxmlKnownNodeAttribute | OoxmlWmlValAttribute)[]>

OoxmlContentControlCheckboxNodeinterfaceSource ↗

w14:checkbox — Microsoft extension, not an ECMA-376 type choice. Distinguishable from untyped rich-text controls that merely wrap a w:sym.

interface OoxmlContentControlCheckboxNode extends OoxmlElementBase<readonly (OoxmlContentControlCheckedNode | OoxmlContentControlCheckedStateNode | OoxmlContentControlUncheckedStateNode | OoxmlGenericElementNode)[], readonly OoxmlKnownNodeAttribute[]>

OoxmlContentControlCheckedNodeinterfaceSource ↗

w14:checked — a checkbox's recorded state, independent of the glyph drawn for it.

interface OoxmlContentControlCheckedNode extends OoxmlElementBase<readonly [], readonly OoxmlKnownNodeAttribute[]>

OoxmlContentControlCheckedStateNodeinterfaceSource ↗

w14:checkedState — the font and code point drawn when a checkbox is checked.

interface OoxmlContentControlCheckedStateNode extends OoxmlElementBase<readonly [], readonly OoxmlKnownNodeAttribute[]>

OoxmlContentControlComboBoxNodeinterfaceSource ↗

w:comboBox — same payload shape as dropdown; free entry is an editing concern.

interface OoxmlContentControlComboBoxNode extends OoxmlElementBase<readonly (OoxmlContentControlListItemNode | OoxmlGenericElementNode)[], readonly OoxmlKnownNodeAttribute[]>

OoxmlContentControlContentNodeinterfaceSource ↗

w:sdtContent — control contents for every placement. Block content is paragraphs/tables; inline content is runs/hyperlinks; row/cell content is rows/cells. Nested controls stay typed.

interface OoxmlContentControlContentNode extends OoxmlElementBase<readonly OoxmlNode[], readonly OoxmlKnownNodeAttribute[]>