@docx-editor.dev/core/layout

activeReviewItemfunctionSource ↗

The item the caret is in, or null.

A resolved comment never activates: a settled thread must not reopen itself as the reviewer types near it.

A REPLY resolves to the thread it belongs to. A reply is anchored over its parent's range, so both cover the caret — and the reply, being newer, wins the innermost test. It is not a card of its own (it renders inside its parent's), so the thread would have gone active with nothing on screen showing it: the reply box vanished from a comment the moment somebody replied to it.

declare function activeReviewItem(items: readonly ReviewItem[], position: ReviewPosition, order: ReadonlyMap<string, number>): ReviewItem | null;

anchorLineYfunctionSource ↗

The y of the line a position sits on, measured from the anchor's own origin.

An ordinary line answers from its own range, exactly as it always did. On a merged fragment's join line the range names one of the two paragraphs, so an offset compared against it either overshot — putting a card in the absorbed half beside the wrong line — or matched the first line every time.

declare function anchorLineY(anchor: ReviewParagraphAnchor, paragraphId: string, offset: number): number;

appliedSpaceBeforefunctionSource ↗

Applied before-spacing for placement (Word 2013+ / compat mode 15).

Adjacent before/after still collapse to the larger gap, but before is dropped entirely when the paragraph begins at the top of a page mid-section. The first paragraph of a document or section retains before. Callers publish this applied value on the fragment so shading, borders, selection, and paint share one geometry.

declare function appliedSpaceBefore(before: number, previousAfter: number, atTopOfPage: boolean, firstParagraphOfSection: boolean): number;

applyLineSpacingfunctionSource ↗

Apply resolved line spacing to a line's natural (glyph-derived) box.

Word places auto / atLeast extras BELOW the line (the last line's multiple spacing still separates it from the next paragraph). Putting that delta above inverted cover-page rhythm: w:line="460" on "between" opened a large gap above the word and almost none before "MERIDIAN". exact taller than the glyphs centers the text (ECMA-376 17.3.1.33). An exact box smaller than the glyphs keeps the baseline inside so clipped text still sits on it.

declare function applyLineSpacing(spacing: ParagraphLineSpacing, naturalHeight: number, naturalBaseline: number): {
    height: number;
    baseline: number;
};

attachNotesToLayoutfunctionSource ↗

Attach footnote/endnote areas onto a body layout. Does not re-paginate — callers that need reservation must re-run body layout with [pageBottomReserves](pageBottomReserves) first.

declare function attachNotesToLayout(layout: SemanticLayout, allRefs: readonly PageRefHit[], input: NotesLayoutInput, options?: {
    readonly fallbackReasons?: readonly NotePaginationFallbackReason[];
    readonly paragraphSectionIndex?: ReadonlyMap<string, number>;
    readonly memo?: unknown;
}): NotesAttachResult;

baselineShiftPtOffunctionSource ↗

How far a run's glyphs are lifted off the line's baseline, in points. Positive is up.

Super and subscript move the GLYPHS without moving the run's box, so the box keeps tiling the line and the selection band stays continuous. Anything drawing at the glyphs — the painter, and the caret — has to apply this itself, and from one place, or the two drift.

declare function baselineShiftPtOf(style: ResolvedRunStyle): number;

borderExtentPtfunctionSource ↗

Width contribution of a resolved edge for content inset / row sizing.

declare function borderExtentPt(edge: ResolvedTableBorderEdge | TableBorderSide | undefined): number;

borderWeightfunctionSource ↗

Conflict weight: the authored width in eighths of a point, and nothing else.

Word-matching, not conformance — §17.4.39 (w:tblBorders) and §17.4.66 (w:tcBorders) describe the elements and specify no conflict algorithm. Word picks the heavier RULE, so a 6pt dashed rule beats a hairline single. Folding the style rank into the weight (an sz × border-number product) made a 0.5pt double outrank a 1pt single and made every dashed or dotted rule weigh 1 regardless of w:sz, which erased its width entirely.

declare function borderWeight(side: TableBorderSide): number;

bottomBorderExtentPtfunctionSource ↗

Vertical extent a bottom border adds below the last line (gap + rule).

declare function bottomBorderExtentPt(edge: ParagraphBorderEdge | undefined): number;

boundedFallbackWordSegmentsfunctionSource ↗

Bounded deterministic fallback — not full UAX #29 word conformance.

declare function boundedFallbackWordSegments(text: string): readonly WordSegment[];

buildNumberingIndexfunctionSource ↗

Project numbering.xml into the bounded index.

Every ceiling here exists because the input is file-derived: definition counts, override counts, indent magnitudes and style-link hop depth are all capped, and nothing from the file becomes a loop bound or an allocation size.

declare function buildNumberingIndex(root: OoxmlElement | null | undefined): NumberingIndex;

buildPageRefIndexfunctionSource ↗

Build a reusable paragraph-id index (document order preserved per paragraph).

declare function buildPageRefIndex(allRefs: readonly PageRefHit[]): PageRefIndex;

buildStyleCascadeTablefunctionSource ↗

Build a cascade table from a styles part root.

Only direct w:style children of the root participate (bounded count). Duplicate styleId values keep the last definition, matching Word's reader for this fixture class. Default paragraph/character style ids track w:default="1" with the same last-wins rule.

declare function buildStyleCascadeTable(stylesRoot: OoxmlElement | null, themeFonts?: ThemeFonts, settingsRoot?: OoxmlElement | null): StyleCascadeTable;

captureOperationSnapshotfunctionSource ↗

Capture, validate, and freeze the environment used throughout one derived operation.

captureOperationSnapshot: (source: OperationSnapshot) => OperationSnapshot

caretAtfunctionSource ↗

Geometry for one model position, or null when it is not laid out.

declare function caretAt(layout: SemanticLayout, position: SemanticPosition, measurerOrOptions?: TextMeasurer | CaretAtOptions): CaretGeometry | null;

caretBoxOnLinefunctionSource ↗

Where a caret sits on a line: its x, and the box it should be drawn at.

The height comes from the RUN at the insertion point, not from the line. A line is as tall as its largest run, so a caret in 11pt text on a line that also carries 36pt text was drawn three times the height of the text it sits in. Word sizes the insertion point to the run it would type into, which is also how the painter already draws the selection band: every run is its own inline box, and the band steps with the text.

Affinity at a shared model boundary: - after a layout-sized atom (tab / projected field), prefer the DOWNSTREAM span so the caret sits at the aligned destination (e.g. before CONFIDENTIAL after a right tab), matching hit-testing and caretStops; - otherwise the run BEFORE the offset wins — the run a keystroke would continue — except at the start of the line, where there is nothing before it.

declare function caretBoxOnLine(line: LineRecord, offset: number, measurer: TextMeasurer | undefined, segment?: {
    readonly spans: readonly StyleSpanRecord[];
    readonly drawings: readonly InlineDrawingRecord[];
} | null): {
    x: number;
    y: number;
    height: number;
};

caretStopsfunctionSource ↗

declare function caretStops(layout: SemanticLayout, measurer?: TextMeasurer): CaretGeometry[];

caretStopsForBlocksfunctionSource ↗

Caret stops for one story's block fragments (header/footer), in reading order.

Coordinates stay story-relative — the same space hitTestFragments and furniture paint use — so arrow motion follows tab-stop geometry and projected field atoms without mixing body sheet offsets.

declare function caretStopsForBlocks(layout: SemanticLayout, pageIndex: number, fragments: readonly BlockFragmentRecord[], measurer?: TextMeasurer): CaretGeometry[];

cascadedBottomBorderfunctionSource ↗

Bottom border after cascade: a later w:pBdr replaces an earlier one; absence inherits. nil/none clear the edge via paragraphBorders.

declare function cascadedBottomBorder(paragraphPropertyNodes: readonly OoxmlNode[]): ParagraphBorderEdge | undefined;

cascadedParagraphBordersfunctionSource ↗

w:pBdr after the style cascade: a later w:pBdr replaces an earlier one WHOLESALE.

Word does not merge edges across the cascade. A style that states only w:bottom discards the box its basedOn ancestor declared, so folding edge by edge would leave a lone underline surrounded by a box no one authored. Absence inherits; nil/none clear.

declare function cascadedParagraphBorders(paragraphPropertyNodes: readonly OoxmlNode[]): ParagraphBorders;

cascadedTabStopsfunctionSource ↗

Resolve tab stops from cascaded w:pPr nodes (docDefaults → style chain → direct).

Each w:tabs merges with clear support; absence inherits. The leader travels with the stop that declared it — a clear at the same position discards both together.

declare function cascadedTabStops(paragraphPropertyNodes: readonly OoxmlNode[]): ResolvedTabStops;

cascadeParagraphFormattingfunctionSource ↗

Cascade paragraph + inherited run properties for one paragraph's direct w:pPr.

Order: docDefaults → table style → basedOn ancestors → paragraph style → direct formatting, which is the style hierarchy of 17.7.2: a table style sits above the document defaults and below the paragraph style a cell paragraph names for itself. When w:pStyle is absent, the document's default paragraph style (w:default="1") is used. Direct formatting is last so it overrides inherited values inside the existing resolvers.

declare function cascadeParagraphFormatting(table: StyleCascadeTable, directPPr: OoxmlNode | undefined, tableCellStyle?: TableCellStyleFormatting): CascadedParagraphFormatting;

cascadeRunPropertiesfunctionSource ↗

Merge inherited paragraph-style run props with a run's direct rPr (direct last).

When a cascade table is supplied, also resolves w:rStyle character styles (basedOn chain, cycle/depth capped). Runs without an explicit rStyle pick up the default character style (w:default="1"). Precedence: inherited → character style chain → direct formatting.

PASS inheritedRunProperties BY IDENTITY. It must be an array [cascadeParagraphFormatting](cascadeParagraphFormatting) returned — runProperties or markRunProperties — and not a copy of one. A toggle property (ECMA-376 §17.7.3) resolves per level of the style hierarchy, and the levels below the character style resolve to more than a true or a false: whether the document defaults' short circuit is still standing decides what the character style's own toggle does next, and no single w:b element can spell that. The paragraph cascade attaches that state to the array it returns, so spreading, filtering or sorting the list drops it. (Object.freeze returns the same object, so that one is safe.) A list without it is read as one ordinary level, which is the most a bare property list can say and is what a caller assembling its own list gets.

declare function cascadeRunProperties(inheritedRunProperties: readonly OoxmlProperty[], directRunProperties: readonly OoxmlProperty[], table?: StyleCascadeTable): readonly OoxmlProperty[];

cellSelectionBetweenfunctionSource ↗

The rectangle two cells define.

Grown to a fixpoint rather than taken literally: a cell that spans two columns cannot be half selected, and a vertically merged run cannot be selected in the middle. Word grows the rectangle until every cell it touches is wholly inside it, so dragging into a merged cell pulls the selection out to that cell's full extent.

declare function cellSelectionBetween(layout: SemanticLayout, anchor: TableCellAddress, head: TableCellAddress): CellSelection | null;

cellSelectionRectsfunctionSource ↗

One rectangle per painted occurrence of a selected cell, in page-content coordinates.

declare function cellSelectionRects(layout: SemanticLayout, cellIds: readonly string[]): readonly {
    pageIndex: number;
    x: number;
    y: number;
    width: number;
    height: number;
}[];

cellSelectionTextfunctionSource ↗

A cell selection as plain text: tabs between cells, newlines between rows.

What a spreadsheet and every other word processor put on the clipboard for a rectangle, and the only shape that survives the trip: the text range a rectangle stands in for would paste back as one run of characters with the grid gone.

declare function cellSelectionText(layout: SemanticLayout, selection: CellSelection): string;

clampListValuefunctionSource ↗

Clamp a list counter into a safe non-negative integer Word can format.

declare function clampListValue(value: number): number;

collapsedSpaceBeforefunctionSource ↗

Gap to insert before a paragraph once the previous paragraph's after is already in the flow cursor — Word takes the larger of the two rather than summing them.

declare function collapsedSpaceBefore(before: number, previousAfter: number): number;

collectFlowBlocksfunctionSource ↗

Collect paragraph and table blocks from a sibling list, flattening through transparent block 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[];

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;

compositionAnchorfunctionSource ↗

The anchor an IME composition is attached to.

Composition needs a position that survives the intermediate transactions it produces, so it is expressed in model coordinates and re-resolved against each new layout rather than cached as geometry.

declare function compositionAnchor(layout: SemanticLayout, position: SemanticPosition, 
measurer?: TextMeasurer): CaretGeometry | null;

computeDoubleBorderMetricsPtfunctionSource ↗

Deterministic double stroke / gap / extent in layout points (scale-independent).

Thin authored widths inflate to a 1+1+1 point compound so a w:sz="3" double remains visible at paint scale 1 — matching Word's hairline-double floor.

declare function computeDoubleBorderMetricsPt(widthPt: number): CompoundBorderMetrics;

computeFootnoteReservesfunctionSource ↗

Compute per-page bottom reserves (points) needed for footnotes given a provisional layout. Used by the bounded reflow loop before final attach.

Height is measured against a column-derived note budget (not leftover body slack). Measuring from slack makes stable true on the first pass and never shrinks the body — references and notes then compete for the same band. Oversized notes still split/continue within the budget; [MIN_FOOTNOTE_BODY_BAND_PT](MIN_FOOTNOTE_BODY_BAND_PT) keeps a body band so reflow cannot chase blank sheets.

declare function computeFootnoteReserves(layout: SemanticLayout, allRefs: readonly PageRefHit[], input: NotesLayoutInput, noteMarks: NoteMarkContext, 
passMemo?: unknown, 
previousReserves?: ReadonlyMap<number, number>): {
    readonly reserves: ReadonlyMap<number, number>;
    readonly stable: boolean;
    readonly reasons: readonly NotePaginationFallbackReason[];
};

contentControlAtPointfunctionSource ↗

Innermost content control whose published boundary geometry contains point on pageIndex.

Nested controls that share the same content box resolve to the deepest nesting depth.

declare function contentControlAtPoint(layout: SemanticLayout, pageIndex: number, point: HitPoint): ContentControlBoundaryRecord | null;

contentControlAtSemanticfunctionSource ↗

Innermost content-control boundary at a page-content point, or null outside every control.

Prefers the deepest nesting depth when nested boundaries share geometry.

declare function contentControlAtSemantic(layout: SemanticLayout, point: {
    readonly x: number;
    readonly y: number;
    readonly pageIndex?: number;
}): ContentControlBoundaryRecord | null;

contentControlBoundariesfunctionSource ↗

Derive one boundary record per control the part declares, in document order.

A control whose content the layout never placed — one inside a story this layout is not of, or one holding nothing — answers no fragments rather than a zero-sized box at the origin: a rectangle nothing painted is a rectangle a hit test would match.

declare function contentControlBoundaries(part: OoxmlPart, layout: SemanticLayout): readonly ContentControlBoundaryRecord[];

contentControlContentChildrenfunctionSource ↗

Children of every w:sdtContent under a control, in document order.

Does not recurse into nested controls. Block callers use [MAX_CONTENT_CONTROL_NESTING](MAX_CONTENT_CONTROL_NESTING); paragraph callers use [MAX_INLINE_CONTAINER_DEPTH](MAX_INLINE_CONTAINER_DEPTH) across all transparent containers.

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

contentControlHoldingParagraphfunctionSource ↗

The innermost content control holding paragraphId, in part.

Deepest wins, matching the geometry path's innermost-by-nesting rule: a control inside a control is the one the caret is actually in.

declare function contentControlHoldingParagraph(part: OoxmlPart, paragraphId: string): ContentControlBoundaryRecord$1 | null;

contentControlRecordsInPartfunctionSource ↗

Every content control a part declares, in document order, WITHOUT geometry.

For callers that want the ROSTER rather than the rectangles — the Tab walk through form fields is the one, and it needs story order, not boxes. fragments comes back empty here by design; a caller that needs geometry reads layout.contentControls, which covers every story the layout draws.

declare function contentControlRecordsInPart(part: OoxmlPart, 
withinParagraphs?: ReadonlySet<string>): readonly ContentControlBoundaryRecord$1[];

contentControlsInLayoutfunctionSource ↗

Layout-published content-control boundaries in document order.

declare function contentControlsInLayout(layout: SemanticLayout): readonly ContentControlBoundaryRecord[];

contentControlsOfLayoutfunctionSource ↗

Every content-control boundary on a layout, preferring the layout-level list.

declare function contentControlsOfLayout(layout: SemanticLayout): readonly ContentControlBoundaryRecord$1[];

createBoundedFallbackWordBoundaryfunctionSource ↗

Explicit bounded fallback boundary (grapheme-safe, narrower than Intl).

declare function createBoundedFallbackWordBoundary(): WordBoundary;

createDefaultWordBoundaryfunctionSource ↗

Resolve production word boundary: Intl when available/construction succeeds, else bounded fallback.

declare function createDefaultWordBoundary(deps?: WordBoundaryResolverDeps): WordBoundary;

createDocumentFurnitureSourcefunctionSource ↗

Build section-aware header/footer layout from a neutral document view.

declare function createDocumentFurnitureSource(options: CreateDocumentFurnitureSourceOptions): DocumentFurnitureSource;

createDocumentLinkProjectorsfunctionSource ↗

Sanitized body and per-part link projectors over one neutral document view.

declare function createDocumentLinkProjectors(view: HeadlessDocumentView): DocumentLinkProjectors;

createDocumentNotesInputfunctionSource ↗

Build note layout input from the neutral package view, or undefined when unused.

declare function createDocumentNotesInput(options: CreateDocumentNotesInputOptions): NotesLayoutInput | undefined;

createDocumentStyleDependenciesfunctionSource ↗

Build the cascade and numbering projections layout consumes.

declare function createDocumentStyleDependencies(view: HeadlessDocumentView): DocumentStyleDependencies;

createFieldLinkRegistryfunctionSource ↗

Create a bounded, content-keyed field-link registry.

declare function createFieldLinkRegistry(): FieldLinkRegistry;

createFixedMeasurerfunctionSource ↗

A deterministic measurer for tests and headless use.

Monospace by construction: every character is the same width and every line the same height, scaled by w:sz when present. Real shaping is the HarfBuzz path; this exists so layout behaviour can be asserted without a font stack deciding the answer.

declare function createFixedMeasurer(charWidth?: number, lineHeight?: number): TextMeasurer;

createFontResourceSnapshotfunctionSource ↗

Admit a set of faces and return the immutable snapshot layout resolves against.

Admission is the trust boundary for font bytes: counts and sizes are checked against the hard ceilings, each face's hash is re-derived and compared, and the bytes are handed to the injected validator. A face failing any of these is recorded as a typed refusal rather than dropped, so resolve can explain itself instead of answering "missing".

createFontResourceSnapshot: (options: FontResourceSnapshotOptions) => FontResourceSnapshot

createHarfBuzzTextShaperfunctionSource ↗

Build a HarfBuzz-backed shaper.

Requires initializeHarfBuzz() to have resolved — shaping is synchronous, so the WASM runtime must already be loaded. Dispose the result when the editor goes away, or its cached faces leak.

createHarfBuzzTextShaper: (options?: HarfBuzzTextShaperOptions) => HarfBuzzTextShaper

createIntlWordBoundaryfunctionSource ↗

Intl.Segmenter word boundary for the invariant locale.

declare function createIntlWordBoundary(): WordBoundary;

createLayoutSchedulerfunctionSource ↗

Build the scheduler that turns a stream of commits into coalesced layout passes.

Keystrokes arrive faster than a document can be laid out, so changes accumulate into one scope and are laid out together rather than once per commit.

declare function createLayoutScheduler(options: LayoutSchedulerOptions): LayoutScheduler;

createLayoutSessionfunctionSource ↗

A layout session, retained across revisions by the caller.

declare function createLayoutSession(): LayoutSession;

createLayoutShapedMeasurerfunctionSource ↗

Bind measurement directly to the environment whose operation identity keys layout caches. Production browser/server hosts use this adapter so fingerprinted and executed shaping cannot drift through independently forwarded fields.

declare function createLayoutShapedMeasurer(shaping: LayoutShapingOptions, options: Pick<ShapedMeasurerOptions, 'resolveFont' | 'fallback'>): TextMeasurer;

createLayoutShapingfunctionSource ↗

Build one shaped-layout environment without importing an editor or DOM lane.

declare function createLayoutShaping(configuration: LayoutFontConfiguration | PreparedLayoutFontConfiguration, instrumentation?: LayoutShapingInstrumentation): Promise<LayoutShapingOptions>;

createListCounterStatefunctionSource ↗

Create a fresh counter bag for one story (body, or one header/footer part).

declare function createListCounterState(index: NumberingIndex): ListCounterState;

createParagraphLayoutCachefunctionSource ↗

A bounded least-recently-used cache with generation-scoped retention.

Bounded because a long editing session touches far more paragraph states than a document contains — every keystroke mints a new key for the paragraph being typed in — and an unbounded cache would hold every intermediate state of the session.

The bound never evicts the CURRENT working set: entries stamped by this generation's retain or touched since it began are skipped, and the map grows past maxEntries when a document is larger than the configured cap — evicting live entries made every full pass on a 500-page document re-measure the whole document.

declare function createParagraphLayoutCache<T>(options?: ParagraphLayoutCacheOptions): ParagraphLayoutCache<T>;

createShapedMeasurerfunctionSource ↗

A [TextMeasurer](TextMeasurer) that measures through the shaper rather than through a canvas.

The accurate path: advances come from the same shaping run that will position the glyphs, so measurement and paint cannot disagree. Falls back per-run when a font is unavailable rather than throwing, because a document naming a font nobody has must still lay out.

declare function createShapedMeasurer(options: ShapedMeasurerOptions): TextMeasurer;

createShapedMeasurerfunctionSource ↗

declare function createShapedMeasurer(options: LayoutEnvironmentShapedMeasurerOptions): TextMeasurer;

createShapedRunfunctionSource ↗

Validate and freeze a shaped run against the environment that produced it.

Checks the internal consistency a shaper must satisfy: direction matches the environment, cluster ranges tile the text without gaps or overlap, glyph ranges stay in bounds, font spans cover every glyph, and caret edges are monotonic. A shaper that violates any of these produces a caret that lands in the wrong place, which is far harder to diagnose downstream than here.

createShapedRun: (input: ShapedRun, environmentInput: ShapingEnvironmentInput) => ShapedRun

createShapingEnvironmentfunctionSource ↗

Validate and freeze a shaping environment.

Checks every field that could silently corrupt a measurement: OpenType tags must be four ASCII bytes, script and language must be non-blank and control-character free, fonts must already be validated. Throws rather than coercing — a bad tag that shapes anyway produces a document that measures wrong everywhere and looks fine.

createShapingEnvironment: (input: ShapingEnvironmentInput) => ShapingEnvironment

defaultNoteSeparatorRuleStylefunctionSource ↗

Word-default paint style for a separator marker.

Footnote and endnote separators both use a short single rule. A full-width double border on a body heading (e.g. the comprehensive fixture’s end banner) is ordinary paragraph w:pBdr ownership and must not transfer onto the note separator record. Authored separator stories with real paragraph/run/border content bypass this via fragment paint.

declare function defaultNoteSeparatorRuleStyle(_noteKind: NoteKind, _kind: 'separator' | 'continuationSeparator'): NoteSeparatorRuleStyle;

defaultTabIntervalFromSettingsfunctionSource ↗

Read w:settings/w:defaultTabStop (ECMA-376 §17.15.1.25), in points.

Word's own interval, not a constant: a metric-locale template writes w:val="1134" (2cm) and every default-interval tab in the document lands on that grid instead of the 0.5" one. The value is FILE-DERIVED, so a non-integer, non-positive or out-of-range val falls back to the schema default rather than being trusted into layout arithmetic.

ST_TwipsMeasure also admits a universal measure ("2cm"); Word writes plain twips, and the spelled form falls back to the default rather than being parsed here.

declare function defaultTabIntervalFromSettings(settings: OoxmlNode | null | undefined): number;

deletedTextBoundariesfunctionSource ↗

Visible deletion boundaries split words without changing canonical text offsets.

declare function deletedTextBoundaries(layout: SemanticLayout, paragraphId: string): ReadonlySet<number>;

deriveNoteDisplayMarksfunctionSource ↗

Derive display marks for references of one note kind in document order.

Restart rules: - continuous — single sequence across the document from numStart - eachSect — restart at numStart when sectionIndex changes - eachPage — restart when pageIndex changes (falls back to continuous if unknown)

IDs are stable; only display numbers change. Non-mutating.

declare function deriveNoteDisplayMarks(noteKind: NoteKind, references: readonly NoteReferenceSite[], properties: ResolvedNoteProperties): readonly NoteDisplayMark[];

deriveNoteDisplayMarksResolvedfunctionSource ↗

Derive marks using per-reference-section resolved properties (numFmt / numStart / numRestart). Restart rules consult each site's own section props.

declare function deriveNoteDisplayMarksResolved(_noteKind: NoteKind, references: readonly NoteReferenceSite[], resolveProps: (sectionIndex: number) => ResolvedNoteProperties): readonly NoteDisplayMark[];

displayTextfunctionSource ↗

The text as it is DRAWN, after case transforms. Measurement must use this, not the source.

declare function displayText(text: string, style: ResolvedRunStyle): string;

disposeLayoutShapingfunctionSource ↗

Release native resources held by a shaping environment.

declare function disposeLayoutShaping(shaping: LayoutShapingOptions): void;

documentOrderfunctionSource ↗

Paragraph ids in document order, deduplicated across fragments.

declare function documentOrder(layout: SemanticLayout): string[];

documentRelationshipTargetInfunctionSource ↗

Resolve a relationship in a non-body story for shared link projection.

declare function documentRelationshipTargetIn(view: HeadlessDocumentView, partName: string, relationshipId: string): ReturnType<typeof relationshipTargetIn>;

effectiveBorderSidefunctionSource ↗

What one cell side is before any ADJACENT cell has its say.

- omitted → the table's own rule for that position (tblBorders, insideH/insideV) - edge → the cell wins outright; no weight fight with the table - none → an explicit w:val="nil". Suppresses a matching table border on interior and perimeter sides alike, so a table whose cells all declare none paints borderless like Word even when tblBorders still carry single rules.

declare function effectiveBorderSide(authored: TableBorderSide, tableSide: TableBorderSide, _options?: {
    readonly interior?: boolean;
}): TableBorderSide;

effectiveContentControlLockfunctionSource ↗

Collapse raw + ancestor locks into one ST_Lock vocabulary value.

declare function effectiveContentControlLock(locks: readonly ContentControlLock[]): ContentControlLock;

emptyTocPlaceholderParagraphIdsfunctionSource ↗

Begin-paragraph ids of TOCs that have no visible cached result rows.

Layout keeps a single caret-height line on these ids so paint can host an identifiable empty-TOC furniture placeholder; ordinary field chrome on the same ids stays suppressed.

declare function emptyTocPlaceholderParagraphIds(part: OoxmlPart): ReadonlySet<string>;

emptyTocSuppressedResultParagraphIdsfunctionSource ↗

Empty result-paragraph ids inside an empty TOC.

Suppressed like field chrome so blank cached rows do not stack under the empty placeholder.

declare function emptyTocSuppressedResultParagraphIds(part: OoxmlPart): ReadonlySet<string>;

enumerateDocumentSectionsfunctionSource ↗

Split the body story into sections.

A paragraph carrying w:pPr/w:sectPr ends the current section (that paragraph is IN the section being ended). The body-level w:sectPr ends the final section. A document with neither yields one section of Word defaults covering every block.

Enumeration is capped at [MAX_DOCUMENT_SECTIONS](MAX_DOCUMENT_SECTIONS). Further paragraph-level section breaks are ignored and remaining blocks fold into the last accepted section (fail closed).

displayMode MUST match the one the caller passes to storyBlocks. blockStart / blockEndExclusive are indices into that list, and the list changes shape with the mode: the proposed view drops a paragraph whose mark and content a revision both removed. Slicing a filtered list with indices counted over an unfiltered one puts body text under another section's page geometry — the wrong paper size, the wrong margins, the wrong header.

declare function enumerateDocumentSections(part: OoxmlPart, displayMode?: RevisionDisplayMode, authorFilter?: RevisionAuthorFilter): DocumentSection[];

enumerateDocumentSectionsBoundedfunctionSource ↗

Like [enumerateDocumentSections](enumerateDocumentSections), but reports whether the section bound clipped hostile input. Prefer the plain enumerator for normal layout; use this when a caller needs a named fail-closed diagnostic.

declare function enumerateDocumentSectionsBounded(part: OoxmlPart, displayMode?: RevisionDisplayMode, authorFilter?: RevisionAuthorFilter): DocumentSectionsEnumeration;

everyStoryOrderfunctionSource ↗

Paragraph ids of EVERY story the layout paints, in the order they sit on the page.

Body, then each page's header and footer, then its note areas — per page, so a story's own paragraphs stay adjacent and in reading order. That is all any caller needs: a selection cannot span two stories (the engine refuses one), so only the order WITHIN a story is ever compared, and this gets that right for all of them at once.

What a caller passes when it has no story in hand — selectionRects and spansInSelection both REQUIRE an order rather than defaulting to one, deliberately. [documentOrder](documentOrder) is the body alone, and using it as a default is what let selection reads silently answer about the wrong story — two paragraphs selected in a header both ranked -1, the walk gave up, and the run properties came back short. A caller that DOES know its story should still pass that story's order: it is smaller, and it cannot match a paragraph the caret is not among.

declare function everyStoryOrder(layout: SemanticLayout): string[];

expandLvlTextfunctionSource ↗

Expand w:lvlText placeholders %1…%9 using per-level counters and formats.

formats[i] / counters[i] correspond to ilvl i. Missing slots use decimal / 1. Literal percent signs that are not %1…%9 are kept. Output is hard-capped.

declare function expandLvlText(lvlText: string, counters: readonly number[], formats: readonly string[]): string;

exportSourceRangeOffunctionSource ↗

Return the model address exporters may use, excluding layout-projected atoms.

declare function exportSourceRangeOf(span: StyleSpanRecord): SourceRange | null;

filterRefsOnPagefunctionSource ↗

Collect note references that appear in laid-out body fragments on a page. Matches [ParagraphFragmentRecord.range](ParagraphFragmentRecord.range) ownership (half-open + boundary affinity).

Pass [buildPageRefIndex](buildPageRefIndex) result as refIndex for O(fragments + matching refs) instead of scanning every document ref against every page fragment.

declare function filterRefsOnPage(page: PageRecord, allRefs: readonly PageRefHit[], refIndex?: PageRefIndex): readonly PageRefHit[];

findDrawingOverlayFrameInLayoutfunctionSource ↗

Locate a drawing's painted extent on the published layout.

Coordinates are page-content relative — the same space [hitTestPage](hitTestPage) uses — so an overlay can position from records without reading painted DOM geometry.

declare function findDrawingOverlayFrameInLayout(layout: SemanticLayout, drawingNodeId: string): DrawingOverlayFrame | null;

findSeparatorNotefunctionSource ↗

Find separator / continuationSeparator note body in a notes part.

declare function findSeparatorNote(part: OoxmlPart | null | undefined, kind: 'separator' | 'continuationSeparator'): OoxmlElement | undefined;

firstReviewRangefunctionSource ↗

The first range of an item, in authored order, or null when it has none.

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

fixedPointfunctionSource ↗

Brand a safe integer as a [FixedPoint](FixedPoint) coordinate.

Fixed point rather than float throughout shaping so that two runs shaped identically compare EQUAL — float accumulation would make the same text measure differently depending on how it was split, and pagination is decided on those measurements.

fixedPoint: (value: number) => FixedPoint

fontRequestKeyfunctionSource ↗

The canonical string identifying one face request.

Case- and whitespace-normalized, so "Times New Roman" and "times new roman" are one key — a document may name a family either way and both must reach the same face.

fontRequestKey: (request: FontRequest) => string

forEachSemanticDrawingfunctionSource ↗

Visit every drawing through the canonical root-story and recursive textbox walks.

declare function forEachSemanticDrawing(layout: SemanticLayout, visit: (drawing: SemanticDrawingVisit) => void): void;

forEachSemanticSpanfunctionSource ↗

Visit every published span in page/story order without consulting the source package.

declare function forEachSemanticSpan(layout: SemanticLayout, visitor: (visit: SemanticSpanVisit) => void): void;

forEachSemanticStoryfunctionSource ↗

Visit every root story in a semantic layout, preserving page/story order.

declare function forEachSemanticStory(layout: SemanticLayout, visit: (story: SemanticStoryVisit) => void): void;

forEachStoryParagraphFragmentfunctionSource ↗

Visit every paragraph fragment one story paints — its own (table interiors flattened, header repeats included) and the fragments inside each anchored drawing's text-box story, recursively.

The fragment sibling of [forEachStoryDrawing](forEachStoryDrawing), sharing its depth bound, for consumers that read per-paragraph published fields (list markers) rather than drawings. The furniture list-marker token walks with this; a fragment it misses leaves a reused page showing a stale marker.

declare function forEachStoryParagraphFragment(story: StoryDrawingHost, visit: (fragment: ParagraphFragmentRecord, context: StoryParagraphFragmentContext) => void, rootOrigin?: Readonly<{
    x: number;
    y: number;
}>, rootDrawingOrigin?: RootDrawingOrigin): void;

formatDecimalfunctionSource ↗

decimal (§17.18.59). Clamped, because the counter derives from file-declared restarts.

declare function formatDecimal(value: number): string;

formatDecimalZerofunctionSource ↗

decimalZero (§17.18.59): single digits zero-padded to two.

declare function formatDecimalZero(value: number): string;

formatLowerLetterfunctionSource ↗

lowerLetter (§17.18.59): the [formatUpperLetter](formatUpperLetter) sequence, lower-cased.

declare function formatLowerLetter(value: number): string;

formatLowerRomanfunctionSource ↗

lowerRoman (§17.18.59).

declare function formatLowerRoman(value: number): string;

formatNumFmtfunctionSource ↗

Format one counter for a w:numFmt value (ST_NumberFormat, §17.18.59).

none prints NOTHING — it is the format Word uses for a level that contributes only literal text, and formatting it as decimal invents a number the document never had. bullet is not formatted here — callers use the literal lvlText.

The remaining enumerants (japaneseCounting, hebrew1, thaiNumbers, ganada, …) are per-script numeral sequences we do not carry glyph tables for. They fall back to decimal deliberately: the ORDINAL is still the authored one, only the script differs, which reads as a number in the wrong alphabet rather than as a missing or wrong marker.

declare function formatNumFmt(numFmt: string, value: number): string;

formatPageNumberfunctionSource ↗

Format a displayed PAGE value through the shared ST_NumberFormat resolver.

Unknown / script-specific formats fall back to decimal (same convention as list markers). none / bullet are meaningless for page numbers and also fall back to decimal so a hostile fmt cannot blank the furniture.

declare function formatPageNumber(value: number, format: string | undefined): string;

formatRevisionOffunctionSource ↗

The tracked FORMAT change on a property list, from w:rPrChange or w:pPrChange.

A property change alters no characters, so it has no span of its own to strike or underline. Word marks the affected text and says what changed; the minimum a reader needs is to see that this text's formatting is itself a pending decision.

Read from the flattened property list because that is what layout already carries — the change wrapper is a w:rPr/w:pPr child like any other.

declare function formatRevisionOf(properties: readonly {
    readonly localName: string;
    readonly attributes?: Readonly<Record<string, string>>;
}[]): RevisionAttribution | null;

formatUpperLetterfunctionSource ↗

Excel-style letter sequence: 1→A … 26→Z, 27→AA. Caps length so a hostile counter cannot grow without bound.

declare function formatUpperLetter(value: number): string;

formatUpperRomanfunctionSource ↗

upperRoman (§17.18.59). Saturates at 3999, the largest value classical Roman numerals express — beyond it there is nothing correct to emit, so it stops rather than inventing notation.

declare function formatUpperRoman(value: number): string;

fragmentOwnsAtomOffsetfunctionSource ↗

Whether a paragraph fragment owns a note atom at atomOffset.

Fragment ranges are half-open for content ownership: [start, end). The shared boundary offset belongs to the later fragment (downstream affinity), matching line splits where fragmentStart = previous.range.end.

declare function fragmentOwnsAtomOffset(fragment: ParagraphFragmentRecord, atomOffset: number): boolean;

fragmentsOfParagraphfunctionSource ↗

Every fragment belonging to one paragraph, in order, across page boundaries.

declare function fragmentsOfParagraph(layout: SemanticLayout, paragraphId: string): ParagraphFragmentRecord[];

geometryOfSectionfunctionSource ↗

Section properties as the geometry layout paginates against.

The gutter is added to the LEFT margin: it is binding allowance, extra space on the inner edge, and folding it into the content width instead would silently narrow every line.

declare function geometryOfSection(section: SectionProperties): PageGeometry;

graphemeBoundaryEpochfunctionSource ↗

Current boundary generation, for callers that cache segmentation-derived answers.

declare function graphemeBoundaryEpoch(): number;

graphemeCountfunctionSource ↗

How many user-perceived characters the text holds.

declare function graphemeCount(text: string): number;

graphemeOffsetToUtf16functionSource ↗

The UTF-16 offset a grapheme index starts at. Clamps rather than throwing.

declare function graphemeOffsetToUtf16(text: string, graphemeOffset: number): number;

guardOperationSnapshotfunctionSource ↗

Compare the current environment against the one an operation captured, naming what changed.

guardOperationSnapshot: (captured: OperationSnapshot, current: OperationSnapshot) => OperationSnapshotGuard

hitTestPagefunctionSource ↗

Hit test a point given in PAGE-CONTENT coordinates, the space the fragment boxes use.

declare function hitTestPage(layout: SemanticLayout, pageIndex: number, point: HitPoint, options?: HitTestOptions): SemanticHit | null;

hitTestSemanticfunctionSource ↗

The caret position nearest a point, in PAGE-CONTENT coordinates.

Never returns null for a point inside the document: a click in the margin, past the end of a line, or below the last line still has an obvious intended caret, and refusing to answer would make those clicks do nothing.

The rules live in semantic-hit-test.ts, which answers with the cell address and the on-glyphs flag a pointer controller needs too; this keeps the geometry-only shape for callers that want nothing else.

declare function hitTestSemantic(layout: SemanticLayout, point: {
    readonly x: number;
    readonly y: number;
    readonly pageIndex?: number;
}): CaretGeometry | null;

hitTestSheetfunctionSource ↗

Hit test a point given in SHEET coordinates — the space page.box lives in, and the space a surface's own pixel offsets convert into.

declare function hitTestSheet(layout: SemanticLayout, point: HitPoint, options?: HitTestOptions): SemanticHit | null;

initializeHarfBuzzfunctionSource ↗

Load and verify the HarfBuzz WASM runtime without adding top-level await to import graphs.

declare function initializeHarfBuzz(): Promise<void>;

isCanvasMeasurementAvailablefunctionSource ↗

Whether an injected canvas text context is usable for measurement.

Availability is decided by the editor seam (which alone may create a canvas). Layout never probes document — a missing context is simply "unavailable".

declare function isCanvasMeasurementAvailable(context?: CanvasTextContext | null | undefined): 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;

isCumulativeGeometryTrustedFromLineOriginfunctionSource ↗

Whether the distance from a line's start to an offset can be trusted as exact.

Requires BOTH ends to be shaped boundaries: accumulating advances across an offset the shaper cannot place would produce a caret x that drifts further along the line.

declare function isCumulativeGeometryTrustedFromLineOrigin(run: ShapedRun, lineStartUtf16Offset: number, utf16Offset: number): boolean;

isFurniturePointfunctionSource ↗

True when a sheet-space point falls inside a page's header or footer box.

declare function isFurniturePoint(layout: SemanticLayout, point: HitPoint): boolean;

isGeometryTrustedCaretOffsetfunctionSource ↗

Every published shaped boundary has exact geometry from the shaping result.

declare function isGeometryTrustedCaretOffset(run: ShapedRun, utf16Offset: number): boolean;

isHarfBuzzInitializedfunctionSource ↗

Whether the WASM runtime is loaded and shaping can proceed synchronously.

declare function isHarfBuzzInitialized(): boolean;

isIntlSegmenterAvailablefunctionSource ↗

Whether this runtime provides Intl.Segmenter, which the default boundary requires.

declare function isIntlSegmenterAvailable(): boolean;

isIntlWordSegmenterAvailablefunctionSource ↗

Whether this runtime provides word-granularity Intl.Segmenter.

declare function isIntlWordSegmenterAvailable(): boolean;

isMarkerOnlySeparatorNotefunctionSource ↗

True when a separator note contains only OOXML separator markers (and empty noteRef atoms Word often authors beside them) — no measurable text or paragraph borders.

declare function isMarkerOnlySeparatorNote(note: OoxmlNode, displayMode?: RevisionDisplayMode, revisionAuthorFilter?: RevisionAuthorFilter): boolean;

isValidStyleIdfunctionSource ↗

declare function isValidStyleId(raw: string | undefined): raw is string;

isWholeGraphemeHorizontalBoundaryfunctionSource ↗

Whether an offset is a real caret position: both a grapheme boundary and a shaped cluster edge.

Both conditions, because they disagree. A ligature is one cluster spanning two graphemes, and an offset inside it has no geometry the shaper can answer for — placing a caret there would mean inventing an x coordinate.

declare function isWholeGraphemeHorizontalBoundary(run: ShapedRun, utf16Offset: number): boolean;

itemizeScriptFontSlotsfunctionSource ↗

Split text into shapeable runs by script, bidi level and font slot.

Consumes the bidi levels rather than re-deriving direction, so itemization and reordering agree by construction instead of by two implementations happening to match.

declare function itemizeScriptFontSlots(text: string, paragraphOffset: number, embedding: BidiEmbeddingLevels): readonly ScriptItem[];

keyedRangeRectsfunctionSource ↗

Rectangles for MANY ranges in ONE pass over the lines.

Not selectionRects in a loop. That walks every page, fragment and line per range, and a contract with two hundred comments would re-walk the whole document two hundred times on every layout — the highlight would cost more than the layout it decorates. One pass tests each line against every range instead, which is the same work a single selection does.

declare function keyedRangeRects(layout: SemanticLayout, ranges: readonly KeyedRange[], 
pages?: ReadonlySet<number>, 
measurer?: TextMeasurer): Map<string, SelectionRect[]>;

layoutEquationfunctionSource ↗

Compose one bounded OMML projection into paint-ready point geometry.

declare function layoutEquation(projection: OmmlEquationProjection, measurer: TextMeasurer, style: ResolvedRunStyle): EquationSpanRecord;

layoutFontConfigurationFingerprintfunctionSource ↗

Stable identity for every layout-affecting font configuration input.

declare function layoutFontConfigurationFingerprint(configuration: LayoutFontConfiguration): string;

layoutHeaderFooterStoryfunctionSource ↗

Lay one header/footer part out at contentWidth.

Line ids are namespaced by part so the body's line-N counter — which incremental convergence compares — never moves because a header changed.

When pageContext is set, allowlisted PAGE/NUMPAGES/SECTIONPAGES instructions project live values; otherwise those fields contribute only cached result text (often empty). Field-free stories ignore pageContext and share one baseline layout.

defaultTabStopPt is the document's w:settings/w:defaultTabStop (ECMA-376 §17.15.1.25) in points; absent keeps the 0.5" schema default. Furniture tabs on the SAME grid as the body — a page-number tab in a metric-locale footer belongs on the document's interval, not on a constant. It sits at the tail because the parameters ahead of it are already positional; new callers should keep passing undefined for what they do not set.

NEW inputs belong in [HeaderFooterStoryInputs](HeaderFooterStoryInputs), the trailing bag, rather than as a sixteenth position. Fifteen is what stopped numberingIndex being threaded here at all.

declare function layoutHeaderFooterStory(part: OoxmlPart, contentWidth: number, measurer: TextMeasurer, producer: string, cache?: ParagraphLayoutCache<readonly PendingLine[]>, styleCascade?: StyleCascadeTable, pageContext?: FieldPageContext, maxPageContextEntries?: number, defaultTabStopPt?: number, displayMode?: RevisionDisplayMode, inlineDrawingLayout?: InlineDrawingLayoutContext, drawingTokenForParagraph?: (paragraph: OoxmlNode) => string, drawingLayoutToken?: string, hfPageContext?: HeaderFooterPageContext, documentProperties?: DocumentProperties, inputs?: HeaderFooterStoryInputs): HeaderFooterStoryLayout;

layoutNoteByIdfunctionSource ↗

Layout a note by id from a notes part; null when missing.

declare function layoutNoteById(part: OoxmlPart | null | undefined, noteId: number, contentWidth: number, options: LayoutNoteStoryOptions): NoteStoryLayout | null;

layoutNoteSeparatorfunctionSource ↗

Layout the document's separator note, or synthesize a short horizontal rule.

Marker-only / missing separators emit no paragraph fragments — paint draws the rule from [NoteSeparatorLayout.ruleStyle](NoteSeparatorLayout.ruleStyle) + box geometry. Authored separators with real paragraph/run/border content keep their fragment story (including w:pBdr).

When maxFlowHeightPt is set and an authored separator exceeds it, the engine fails closed to a short synthetic rule ({@link note-separator-height-cap}) so note pagination cannot burn the overflow budget on zero-progress separator-only pages.

declare function layoutNoteSeparator(part: OoxmlPart | null | undefined, kind: 'separator' | 'continuationSeparator', contentWidth: number, options: LayoutNoteStoryOptions, noteKind: NoteKind, maxFlowHeightPt?: number): NoteSeparatorLayout;

layoutNoteStoryfunctionSource ↗

Lay one note node out at contentWidth.

Does not paginate. Callers that need splits ask for fragments and cut at paragraph/line boundaries in the note-pagination layer.

declare function layoutNoteStory(note: OoxmlNode, contentWidth: number, options: LayoutNoteStoryOptions): NoteStoryLayout | null;

layoutSemanticDocumentfunctionSource ↗

Lay one story part out into pages.

The engine's layout entry point. Walks body, header, footer and note roots, flattens block SDTs, paginates tables with header-row repeats and vertical merges, and resolves every paragraph through the style cascade.

Incremental when given a [LayoutSession](LayoutSession): per-block cache keys plus flow checkpoints mean a pass that changes nothing returns the previous pages by identity.

declare function layoutSemanticDocument(part: OoxmlPart, revision: number, options: SemanticLayoutOptions): SemanticLayout;

lineAtPositionfunctionSource ↗

The line containing a model position, or null when the position is not laid out.

declare function lineAtPosition(layout: SemanticLayout, paragraphId: string, offset: number, 
candidates?: Iterable<LineRecord>): LineRecord | null;

lineEndOffsetfunctionSource ↗

Logical line end, excluding the wrap space or hard break whose following position belongs to the next line. Page breaks are excluded even on the paragraph's last line.

declare function lineEndOffset(layout: SemanticLayout, line: LineRecord): number;

lineSegmentsfunctionSource ↗

Every paragraph a line carries, in visual order. One entry for an ordinary line.

declare function lineSegments(line: LineRecord): readonly LineSegment[];

linesOffunctionSource ↗

Every line in a layout, in reading order — the order caret navigation walks.

declare function linesOf(layout: SemanticLayout): LineRecord[];

listMarkerBoxfunctionSource ↗

Horizontal marker box inside the first-line indent slot.

Coordinates are relative to the same origin as paragraph content (indent.left is the text start). Returns null when there is nothing to paint.

w:hanging and a positive w:firstLine are one mutually exclusive slot (§17.3.1.10, §17.3.1.12), so the marker has two placements, not an interaction: a hanging level puts the marker BEFORE the text start (left - hanging); a positive-firstLine level puts it AFTER (left + firstLine) — the standard legal shape w:ind w:left="0" w:firstLine="720" numbers at 0.5" while continuation lines return to the margin. Reading only the hanging model painted every such marker at the left margin.

declare function listMarkerBox(item: ResolvedListItem, markerWidth: number, lineY: number, lineHeight: number): {
    x: number;
    y: number;
    width: number;
    height: number;
} | null;

markRevisionRemovesMarkfunctionSource ↗

Does this decision, taken, remove the paragraph mark?

A deletion does, and so does a moveFrom: the copy the paragraph moved OUT of goes away when the move is accepted. insert and moveTo are the other half of each pair, and they keep the break. Paint, the change bar and the resolved views all ask this one question, so a moveFrom cannot end up struck through in the margin and blue on the glyph.

declare function markRevisionRemovesMark(revision: RevisionAttribution): boolean;

measureDisplayTextfunctionSource ↗

Measure run text the way layout breaks lines and paints glyphs (caps/small-caps aware).

declare function measureDisplayText(text: string, style: ResolvedRunStyle, measurer: TextMeasurer): number;

mergeListIndentfunctionSource ↗

The effective indent of a list paragraph: STYLE, then the numbering LEVEL, then DIRECT.

Word applies a level's w:pPr/w:ind between the paragraph style and the paragraph's own formatting, per attribute — and the ordering matters on real documents. A converted agreement numbers its (a) items with a level stating left=1512 hanging=738 under a ListParagraph style stating left=775 hanging=624, and states only hanging="737" on the paragraph itself. Reading the flattened cascade as "the paragraph's indent" gave the STYLE's 775 to a level that had overridden it, so every lettered sub-item hung a full indent step to the left of where Word puts it.

inherited is the cascade WITHOUT the paragraph's own w:pPr (defaults, table cell style, style chain); direct is that w:pPr alone.

declare function mergeListIndent(levelIndent: NumberingLevelIndent, inherited: readonly OoxmlProperty[], direct?: readonly OoxmlProperty[]): NumberingLevelIndent;

moveCaretfunctionSource ↗

Move a caret; vertical movement carries a desired X through shorter lines.

declare function moveCaret(layout: SemanticLayout, position: SemanticPosition, command: NavigationCommand, desiredX?: number | null, options?: MoveCaretOptions): {
    position: SemanticPosition;
    desiredX: number | null;
} | null;

nextTabDestinationfunctionSource ↗

Next tab destination strictly past currentX, preferring custom stops then the default interval. Destination is clamped to rightEdge so stops cannot escape the content box.

declare function nextTabDestination(tabs: ResolvedTabStops, currentX: number, rightEdge: number): TabDestination;

normalNotesOffunctionSource ↗

Collect normal (body) notes from a notes part, bounded.

declare function normalNotesOf(part: OoxmlPart | null | undefined): readonly OoxmlElement[];

noteDisplayMarkMapfunctionSource ↗

Map noteId → formatted mark for quick lookup (last site wins if duplicated).

declare function noteDisplayMarkMap(marks: readonly NoteDisplayMark[]): ReadonlyMap<number, string | null>;

noteLineIdPrefixfunctionSource ↗

Stable line-id namespace for one note. Body line counters compare these as opaque strings and must not collide with line-N / hf-… ids.

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

noteMarkKeyfunctionSource ↗

The key one note's mark is stored under — footnote:N / endnote:N.

The same encoding EditorScope uses for note ids, so a mark context and a scope address name the same note without a translation step.

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

noteSeparatorAreaBoxfunctionSource ↗

Absolute separator box: short rule for marker/synthetic, full width for authored stories.

declare function noteSeparatorAreaBox(separator: NoteSeparatorLayout, contentX: number, contentWidth: number, areaTop: number): LayoutBox;

noteStoryBlocksfunctionSource ↗

Blocks of one typed footnote/endnote node — a separate semantic story root.

The footnotes/endnotes part root is never a story; each note is laid out independently so line ids and incremental convergence stay namespaced by note identity.

declare function noteStoryBlocks(note: OoxmlNode, displayMode?: RevisionDisplayMode, authorFilter?: RevisionAuthorFilter): OoxmlElement[];

pageAtYfunctionSource ↗

The page a sheet-space y belongs to.

The gutter between page *i* and page *i+1* resolves to page *i*, because the nearest text to a point in that gap is the last line of the page above it. That falls out of searching for the last page whose top is at or above the point, with no special case: the gutter is inside [top(i), top(i+1)) by construction. A point above the first page clamps to it, and a point past the last page clamps to that.

declare function pageAtY(layout: SemanticLayout, sheetY: number): number;

pageBorderFramefunctionSource ↗

The frame for one sheet, or undefined when this page does not carry one.

isFirstPageOfSection is the SECTION's first page, not the document's: w:display is a section property, so in a three-section document a firstPage frame draws three times.

The four rules close a rectangle rather than each spanning its own side. Word draws one box, and horizontal rules that stopped at the text column while the verticals sat outside it read as two rules with two detached bars beside them — the same thing w:pBdr gets right by spanning from the left rule's outer edge to the right rule's.

declare function pageBorderFrame(borders: SectionPageBorders | undefined, geometry: PageGeometry, isFirstPageOfSection: boolean): PageBorderFrameRecord | undefined;

pageBordersFingerprintfunctionSource ↗

Identity of one section's page frame, for incremental-layout context keys.

A w:pgBorders edit changes nothing the flow measures — the frame is drawn beside the text, never through it — so no per-paragraph key moves and every reuse path would hand back the previous sheets with the previous frame. This token goes in the pass context so it does not.

declare function pageBordersFingerprint(borders: SectionPageBorders | undefined): string;

pageRefPageNumbersFromLayoutfunctionSource ↗

A [RefFieldRefreshOptions.pageRefPageNumberOf](RefFieldRefreshOptions.pageRefPageNumberOf) source over one finalized layout.

Builds the target → host-page index once, on first demand, and answers every field from it — the same walk finalize substitution takes, so the saved number is the painted one.

declare function pageRefPageNumbersFromLayout(layout: SemanticLayout): (targetParagraphId: string) => string | null;

pagesToMaterializefunctionSource ↗

The page indices to build in detail.

Returns indices rather than records so a caller can compare cheaply against what it already has mounted, and so the decision can be made without touching the layout.

declare function pagesToMaterialize(input: MaterializationInput): Set<number>;

paragraphBorderExtentPtfunctionSource ↗

Extent one border edge occupies away from the text it decorates: gap plus rule, in points.

Vertically that is flow height — a top rule pushes the first line down, a bottom rule holds the page open below the last one — so pagination has to see it. Horizontally it is publish-only: Word draws left/right paragraph rules OUTSIDE the text column and never re-breaks the lines, which is why adding a box to a paragraph in Word does not reflow it.

declare function paragraphBorderExtentPt(edge: ParagraphBorderEdge | undefined): number;

paragraphBordersfunctionSource ↗

Resolve w:pBdr from the paragraph-properties node.

Nested — every edge is a child of pBdr, not an attribute — so this reads the typed tree rather than the flattened OoxmlProperty[] bag propertiesOf builds for leaf props.

declare function paragraphBorders(pPr: OoxmlNode | undefined): ParagraphBorders;

paragraphBordersFingerprintfunctionSource ↗

Identity of a paragraph's border set, for the w:between group rule.

Word treats consecutive paragraphs whose border settings are IDENTICAL as ONE bordered block: the top rule draws above the first, the bottom rule below the last, and each interior boundary gets w:between or nothing (§17.3.1.24). That is why applying a box to three selected paragraphs in Word draws one box and not three.

Empty string means "no borders", which never groups with anything.

declare function paragraphBordersFingerprint(borders: ParagraphBorders): string;

paragraphBorderStrokeWidthPtfunctionSource ↗

Visual stroke thickness layout publishes for one edge (points).

Compound ST_Border values (double, …) use the shared inflated band so a thin w:sz="3" double still occupies a visible double-line box — matching table borders.

declare function paragraphBorderStrokeWidthPt(edge: ParagraphBorderEdge): number;

paragraphBreaksBeforefunctionSource ↗

Whether a paragraph must start a new page (w:pageBreakBefore).

LAST WINS, like every other toggle read off the cascade (paragraphKeeps does the same for w:keepNext). An any-wins .some() cannot be switched off: a Chapter or Heading style carries w:pageBreakBefore, and Word writes w:val="0" on the one instance whose author unchecked the box — that paragraph still broke, so the document grew a blank page and every page number after it was wrong.

An absent w:val is on (§17.17.4), and the off vocabulary is the whole of it — off is a spelling too, which [isOn](isOn) beside this already accepts.

declare function paragraphBreaksBefore(props: readonly OoxmlProperty[]): boolean;

paragraphContextualSpacingfunctionSource ↗

w:contextualSpacing (17.3.1.9): drop before/after between paragraphs of the SAME style. Word's built-in ListParagraph sets it, so every list authored in Word gets a paragraph gap between items without this.

declare function paragraphContextualSpacing(props: readonly OoxmlProperty[]): boolean;

paragraphFragmentsOffunctionSource ↗

Depth-first paragraph fragments of one page, in reading order.

Table interiors flatten through rows and cells; header-repeat rows are skipped unless asked for, so interaction sees each caret stop exactly once while paint sees everything.

declare function paragraphFragmentsOf(page: PageRecord, includeHeaderRepeats?: boolean): ParagraphFragmentRecord[];

paragraphFragmentsOfBlocksfunctionSource ↗

declare function paragraphFragmentsOfBlocks(blocks: readonly BlockFragmentRecord[], includeHeaderRepeats?: boolean): ParagraphFragmentRecord[];

paragraphLayoutKeyfunctionSource ↗

The cache key for one paragraph's measured break.

Folds in the content, the available width, and the measurement producer. Anything that changes where lines fall must be in here, or the cache serves a break taken under different conditions.

declare function paragraphLayoutKey(inputs: ParagraphKeyInputs): ParagraphLayoutKey;

paragraphLineSpacingfunctionSource ↗

Resolve w:line / w:lineRule from flat paragraph properties.

Merged per attribute for the same reason as before/after: w:spacing is one element carrying independent attributes, and a style that states only @line must not reset the rule an earlier entry in the cascade set.

declare function paragraphLineSpacing(props: readonly OoxmlProperty[]): ParagraphLineSpacing;

paragraphMarkDeletedfunctionSource ↗

w:pPr/w:rPr/w:del or w:moveFrom — a tracked revision REMOVES the paragraph mark.

Both say the break goes away once the decision is taken: a deletion outright, a moveFrom because the paragraph left this place for another. Read from the paragraph-mark run properties only. A w:del anywhere else in the paragraph deletes run content, which is a different statement entirely.

declare function paragraphMarkDeleted(paragraph: OoxmlNode): boolean;

paragraphMarkFormatRevisionOffunctionSource ↗

The tracked FORMAT change on a paragraph's own mark, from w:pPr/w:rPr/w:rPrChange.

CT_ParaRPr ends with it (§17.13.5.32), and Word writes it when a user changes the mark's own run properties with tracking on. It reaches the fragment rather than a span because it decorates no characters, and it is not in props: a fragment's props carry the mark's w:rPr by NAME only, with none of its children.

Note that w:rPrChange/w:rPr is CT_ParaRPrOriginal, which may carry its own revision marks. Those describe the mark as it WAS and must not be read as live ones, which is why this reads the change element's own attributes and never descends into it.

declare function paragraphMarkFormatRevisionOf(paragraph: OoxmlNode): RevisionAttribution | null;

paragraphMarkRevisionOffunctionSource ↗

Deprecated. Reads one of the revisions a mark can carry. Use [paragraphMarkRevisionsOf](paragraphMarkRevisionsOf), which answers with all of them.

The one decision on a paragraph's mark that a single-field reader sees.

declare function paragraphMarkRevisionOf(paragraph: OoxmlNode): RevisionAttribution | null;

paragraphMarkRevisionsOffunctionSource ↗

Every revision on a paragraph's own MARK, from w:pPr/w:rPr/w:ins|w:del|w:moveFrom|w:moveTo.

All four members of EG_ParaRPrTrackChanges. A moved paragraph carries w:moveFrom on the mark of the copy it left and w:moveTo on the mark of the copy it arrived at, so a move that spans whole paragraphs is recorded here and nowhere else.

EG_ParaRPrTrackChanges records that the pilcrow itself was inserted or deleted, which is how Word writes a paragraph split or merge. It is not content — there is no text to decorate — so a surface shows it as a mark of its own beside the paragraph, the way Word draws a struck- through ¶.

A LIST, because the group is ins? del? moveFrom? moveTo? and the first two can both be there: that pair is what Word writes when a second author proposes removing a mark the first proposed adding, and it is what this engine's own writer emits (tree-op-tracked.ts). Answering with the first one hid the second author's decision from the PAGE. The review pane walks the tree itself and always listed both, which is the worse shape of the two: a card offering a decision the reader could see no sign of.

Ordered as the file orders them, which is the order the group declares.

Property-position w:ins/w:del stay generic in the tree deliberately, so this reads them by name rather than by kind.

declare function paragraphMarkRevisionsOf(paragraph: OoxmlNode): readonly RevisionAttribution[];

paragraphOrderOfPartfunctionSource ↗

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

Memoized on the immutable root: a derivation pass can ask repeatedly, and the shared answer stays read-only so a caller cannot poison later readers.

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

paragraphSectionNodefunctionSource ↗

w:sectPr nested under a paragraph's w:pPr, if present.

declare function paragraphSectionNode(paragraph: OoxmlElement): OoxmlElement | undefined;

paragraphShadingfunctionSource ↗

Resolve paragraph shading from cascaded flat w:pPr properties.

Later w:shd entries win (defaults → style → direct), matching spacing/border cascade.

declare function paragraphShading(props: readonly OoxmlProperty[]): string | undefined;

paragraphShadingBoxfunctionSource ↗

Page-content box for paragraph shading: union of this fragment's line boxes.

Excludes collapsed before/after spacing and bottom-border extent so the painted band matches Word's content-area fill (character shading height on a single line).

declare function paragraphShadingBox(lines: readonly {
    readonly box: LayoutBox;
}[], x: number, width: number): LayoutBox | undefined;

paragraphsInCellsfunctionSource ↗

Paragraph ids inside a set of cells, in document order, each once.

declare function paragraphsInCells(layout: SemanticLayout, cellIds: readonly string[]): readonly string[];

paragraphSpacingfunctionSource ↗

Resolve w:spacing before/after from flat paragraph properties.

Line spacing (w:line / w:lineRule) is a separate concern — it changes measured line height, not the gap between paragraphs — and is not resolved here.

w:beforeAutospacing / w:afterAutospacing REPLACE the authored measurement on their own side rather than adding to it; see [AUTO_PARAGRAPH_SPACING_PT](AUTO_PARAGRAPH_SPACING_PT).

declare function paragraphSpacing(props: readonly OoxmlProperty[], context?: ParagraphAutoSpacingContext): ParagraphSpacing;

paragraphTabStopsfunctionSource ↗

Direct w:pPr only — used when no style cascade table is present.

declare function paragraphTabStops(pPr: OoxmlNode | undefined): ResolvedTabStops;

paragraphTextFromLayoutfunctionSource ↗

The text of one paragraph, read back from the layout records.

Word boundaries need characters, and the records carry them: every span holds the text it was laid out from, keyed by the source range it covers. Reading them back keeps word motion in the interaction lane instead of making it a second consumer of the model.

declare function paragraphTextFromLayout(layout: SemanticLayout, paragraphId: string): string;

parseAutonumInstructionfunctionSource ↗

Recognize AUTONUM | AUTONUMLGL | AUTONUMOUT [\* <format>] [\e] [\* MERGEFORMAT], or null for anything else. Any unrecognized switch fails the parse so the field stays inert (paints nothing — its historical rendering), never the raw instruction, never a guessed number.

declare function parseAutonumInstruction(raw: string): AutonumFieldSpec | null;

parsePageBordersfunctionSource ↗

Parse w:pgBorders off one w:sectPr.

Undefined when the element is absent AND when it paints nothing — every edge off, or every edge an art border. Unlike w:pgNumType, an empty-but-present element is not distinguished: these properties are a LAYOUT input, serialization re-emits the canonical tree, and a frame with no edges has exactly one meaning downstream.

declare function parsePageBorders(sectPr: OoxmlNode): SectionPageBorders | undefined;

parsePageNumberingfunctionSource ↗

Parse authored w:pgNumType without inventing schema defaults.

Returns undefined when the element is absent. An empty element yields {} so callers can tell "present but unauthored" from "missing" and serialization can re-emit empty. Hostile / out-of-range attribute values are dropped rather than clamped into meaning.

declare function parsePageNumbering(sectPr: OoxmlNode): SectionPageNumbering | undefined;

parseRefInstructionfunctionSource ↗

Recognize REF <bookmark> [\r|\w|\n] [\t] [\h] [\* MERGEFORMAT] or NOTEREF <bookmark> [\h] [\* MERGEFORMAT], or null for anything else.

The keyword matches case-insensitively; the bookmark name keeps its authored case (it is a lookup key into a Map, never an object property, so hostile names like __proto__ are just names that resolve to nothing). Any unrecognized switch fails the parse so the field falls back to its cached result — never the raw instruction, never a guess. NOTEREF's \p (above/below position text) and \f (note-style formatting) are unrecognized on purpose.

declare function parseRefInstruction(raw: string): RefFieldSpec | null;

parseSectionPropertiesfunctionSource ↗

Parse one w:sectPr into geometry/break properties (null reads as Word's defaults).

declare function parseSectionProperties(sectPr: OoxmlNode | null | undefined): SectionProperties;

planRefFieldResultRefreshfunctionSource ↗

Plan the refresh for one body part, or null when every supported REF result is already fresh (the no-op save path — no transaction, no revision bump, no undo entry).

declare function planRefFieldResultRefresh(part: OoxmlPart, options: RefFieldRefreshOptions): RefreshFieldResultsOp | null;

positionPastDeletionfunctionSource ↗

Where an INSERT aimed at this position actually lands: past any deletion it sits inside.

The caret may rest anywhere in struck text — Word's rule, and the tracked lane's (tree-op-tracked.ts): all-markup shows the words, so the reader can put the caret between two of them. What may NOT happen is new content landing inside the w:del, where it would serialize as w:t under a wrapper that requires w:delText and be taken down by an accept of someone else's deletion. A deletion stays contiguous, so the words go after it — the order a replacement reads in.

RANGE endpoints are not this function's business: a drag may legitimately cover deleted text, so callers adjust only collapsed insertion points.

declare function positionPastDeletion(layout: SemanticLayout, position: SemanticPosition): SemanticPosition;

prepareLayoutFontConfigurationfunctionSource ↗

Copy and hash each usable face once for shared cache identity and admission.

declare function prepareLayoutFontConfiguration(configuration: LayoutFontConfiguration, instrumentation?: LayoutShapingInstrumentation): PreparedLayoutFontConfiguration;

projectedNoteMarkTextfunctionSource ↗

Resolve display text for a noteReference / noteRef node under a mark context.

declare function projectedNoteMarkText(node: OoxmlNode, context: NoteMarkContext | undefined): ProjectedNoteMark | null;

projectedSectionSourceIndexesfunctionSource ↗

Canonical section index behind each section in a revision-projected body.

A removed paragraph mark can collapse an entire section. The projected section keeps the surviving paragraph's geometry, while package APIs such as header/footer resolution remain indexed over the canonical tree. This bridge prevents those two index spaces from being paired positionally.

declare function projectedSectionSourceIndexes(part: OoxmlPart, displayMode?: RevisionDisplayMode, authorFilter?: RevisionAuthorFilter): readonly number[];

provisionalNoteMarksfunctionSource ↗

Build a continuous (pre-page) mark context for the first body layout pass. eachPage reserves digit width; [reprojectBodyNoteMarks](reprojectBodyNoteMarks) publishes final marks onto body citations after page assignment in [attachNotesToLayout](attachNotesToLayout).

declare function provisionalNoteMarks(refs: readonly PageRefHit[], input: NotesLayoutInput): NoteMarkContext;

readBorderSidefunctionSource ↗

Read one OOXML border child into the three-state model.

declare function readBorderSide(node: OoxmlElement | undefined): TableBorderSide;

readCellBordersfunctionSource ↗

Read one cell's w:tcBorders, under the same bounds [readTableBorders](readTableBorders) applies.

declare function readCellBorders(tcPr: OoxmlElement | undefined): CellBorderBox;

readNumPrfunctionSource ↗

Read w:numPr from cascaded paragraph-property nodes (lowest precedence first).

Flat OoxmlProperty[] bags drop nested ilvl/numId, so this walks the tree nodes the same way borders and tabs do.

w:ilvl and w:numId inherit INDEPENDENTLY through the style chain and the direct w:pPr (§17.3.1.19): a tier stating only the level keeps the id it inherits — Word's standard Heading2–Heading9 shape, where only Heading1 names the w:num — and a tier stating only the id keeps the inherited level. Treating each w:numPr node as a full replacement dropped the id at every level-only tier and unnumbered the paragraph. A stated w:numId w:val="0" (or an invalid value) still switches numbering off at that tier even when a lower tier set one; a higher tier stating a valid id re-enables. A level-only tier with no id inherited from below resolves to no numbering.

declare function readNumPr(paragraphPropertyNodes: readonly OoxmlNode[]): {
    numId: string;
    ilvl: number;
} | null;

readSectionPropertiesfunctionSource ↗

The section properties a part declares, or Word's defaults where it says nothing.

Returns the FINAL section (body-level w:sectPr, else the last paragraph-level one). Multi-section geometry belongs to enumerateDocumentSections; chrome that needs "the document's page" still reads the last section, which is what Word's body-level sectPr is.

declare function readSectionProperties(part: OoxmlPart): SectionProperties;

readTableBordersfunctionSource ↗

Read a table's w:tblBorders, dropping or clamping hostile values.

Widths and colours come from a file: an out-of-range w:sz becomes a layout dimension, so it is bounded here rather than downstream.

declare function readTableBorders(tblPr: OoxmlElement | undefined): TableBorderBox;

readTableStructurefunctionSource ↗

Read one typed table node into a bounded structure, or null when the node is not a typed table or sits beyond the nesting ceiling.

declare function readTableStructure(table: OoxmlNode, contentWidthPt: number, depth: number, styleCascade?: StyleCascadeTable, 
displayMode?: RevisionDisplayMode, authorFilter?: RevisionAuthorFilter, compatibilityMode?: number): SemanticTableStructure | null;

resetGraphemeBoundaryfunctionSource ↗

Restore the default Intl.Segmenter boundary and clear the memo.

declare function resetGraphemeBoundary(): void;

resolveBorderConflictfunctionSource ↗

Pick the winner between two candidates on a shared grid line (zero cell spacing).

none loses to any edge; two none/omitted yield omitted (no paint). Width decides; equal widths rank by style, then prefer the darker color, then preferFirst (reading-order / first candidate).

declare function resolveBorderConflict(first: TableBorderSide, second: TableBorderSide, preferFirst?: boolean): TableBorderSide;

resolveDefaultSurfaceMeasurerfunctionSource ↗

The surface's default measurer: canvas when a 2d context was injected, otherwise fixed.

Host-supplied and shaping measurers override this entirely — call only when the options did not already name one. The editor seam is responsible for creating the canvas context.

declare function resolveDefaultSurfaceMeasurer(scale?: number, options?: CanvasMeasurerOptions): ResolvedSurfaceMeasurer;

resolveDefaultWordBoundaryfunctionSource ↗

Cached immutable production boundary (first resolved instance only).

declare function resolveDefaultWordBoundary(): WordBoundary;

resolveNumberingLevelfunctionSource ↗

The effective level for one paragraph's numbering reference, after overrides and style links.

Answers null for a reference the index cannot resolve — a paragraph naming a definition the file never declared is an unnumbered paragraph, not an error.

declare function resolveNumberingLevel(index: NumberingIndex, numId: string, ilvl: number): {
    readonly abstractNumId: string;
    readonly level: NumberingLevel;
    readonly startOverride?: number;
} | null;

resolveOoxmlShadingFillfunctionSource ↗

Resolve a w:shd attribute bag to a validated RRGGBB fill, or undefined.

w:themeFill is a REFERENCE, and Word always writes the value it resolved to alongside it: <w:shd w:val="clear" w:fill="D9E2F3" w:themeFill="accent1" w:themeFillTint="33"/>. Reading w:fill in that case is not inventing a colour from the theme — it is reading the colour the producer computed. Dropping the fill because a theme reference sat next to it left every accent-shaded cell and paragraph unpainted.

val="nil" clears shading. Pattern vals are not rendered; a valid solid fill still paints as a clear fill until pattern support lands. A theme reference with no usable w:fill still resolves to nothing rather than a guess.

declare function resolveOoxmlShadingFill(attributes: Readonly<Record<string, string>> | undefined): string | undefined;

resolveParagraphLayoutInputsfunctionSource ↗

Resolve every paragraph input semantic layout / table cells share: cascaded props when a style table is present, otherwise direct formatting only.

When listItem is provided, its merged level indent becomes the paragraph indent (list hanging / left from numbering.xml), which is what Word uses for fixture list paragraphs that author no direct w:ind.

tableCellStyle carries what the enclosing table's style says about this cell's paragraphs; body paragraphs pass nothing.

inTableCell is asked for separately because a cell paragraph may have no table style to inherit at all, and w:beforeAutospacing still needs to know it is in a cell.

declare function resolveParagraphLayoutInputs(paragraph: OoxmlElement, contentWidth: number, styleCascade: StyleCascadeTable | undefined, listItem?: ResolvedListItem, tableCellStyle?: TableCellStyleFormatting, inTableCell?: boolean, lineUnitPt?: number): ParagraphLayoutInputs;

resolveRunStylefunctionSource ↗

Resolve one run's direct formatting.

Unrecognised values are DROPPED rather than guessed: a w:sz of "large" leaves the default size rather than inventing one, because a wrong measurement moves every glyph after it and a missing one is visible immediately.

themeFonts resolves w:rFonts theme references. Absent, a theme-only rFonts leaves the family inherited — which is what every run of a theme-fonted document does, so the whole document falls back to the surface default face.

declare function resolveRunStyle(props: readonly OoxmlProperty[], themeFonts?: ThemeFonts): ResolvedRunStyle;

resolveStoryListItemsfunctionSource ↗

Resolve every list paragraph in a story to a [ResolvedListItem](ResolvedListItem), keyed by node id.

Non-list paragraphs are absent from the map. Hostile / missing numbering resolves inertly (paragraph omitted — laid out as ordinary text).

declare function resolveStoryListItems(blocks: readonly OoxmlElement[], index: NumberingIndex, styleCascade: StyleCascadeTable | undefined, isFontAvailable?: (family: string) => boolean): ReadonlyMap<string, ResolvedListItem>;

resolveStoryRefFieldsfunctionSource ↗

Resolve the document's REF fields for one layout pass, or null when it has none.

Bookmarks and REF fields resolve across the body story and (when notes is given) the footnote/endnote stories, against ONE shared target index — a footnote REF finds the body bookmark it cites. Header/footer and text-box stories are not given a context and keep painting cached results.

declare function resolveStoryRefFields(blocks: readonly OoxmlElement[], listItems: ReadonlyMap<string, ResolvedListItem> | undefined, notes?: RefNoteParts): RefFieldContext | null;

resolveStrictHexFillfunctionSource ↗

Strict hex fill: exactly six hex digits. Rejects auto, nil, and any non-hex payload (CSS functions, URLs, short hex, theme tokens).

declare function resolveStrictHexFill(raw: string | undefined): string | undefined;

resolveTableCellBorderGridfunctionSource ↗

Resolve borders for every cell in a laid-out table fragment.

Shared vertical edges: conflict(left.right, right.left) → assigned to the left cell, segmented per row when a vMerge restart faces differing neighbors. Shared horizontal edges: conflict(above.bottom, below.top) → assigned to the above cell, segmented per grid column when a gridSpan cell faces differing below neighbors; vMerge interior seams are suppressed per interval.

When geometry is provided, compound edges expand into explicit stroke records with corner-adjusted endpoints in cell-local points.

declare function resolveTableCellBorderGrid(rows: readonly (readonly BorderGridCell[])[], table: TableBorderBox, columnCount: number, geometry?: BorderGridGeometry, work?: TableBorderGridResolveWork, ownershipBudget?: TableBorderOwnershipBudget): ResolvedCellBorders[][];

reviewAnchorIndexfunctionSource ↗

Paragraph id to its place on the page, in ONE pass over the layout.

Built once per layout and reused by every card. The straightforward version — scan the pages until the paragraph turns up, per card — is a full-document walk per card, and a contract with two hundred comments walked the document two hundred times every time the caret moved. Toggling the pane was visibly slow for exactly that reason.

declare function reviewAnchorIndex<TPage extends {
    readonly index: number;
    readonly contentBox: {
        readonly y: number;
    };
}>(layout: {
    readonly pages: readonly TPage[];
}, paragraphFragments: (page: TPage) => readonly {
    readonly paragraphId: string;
    readonly box: {
        readonly y: number;
    };
    readonly lines?: readonly {
        readonly range: {
            readonly end: number;
        };
        readonly box: {
            readonly y: number;
        };
        readonly spans?: readonly {
            readonly range: {
                readonly paragraphId: string;
                readonly end: number;
            };
        }[];
    }[];
}[]): Map<string, ReviewParagraphAnchor>;

reviewItemGeometryfunctionSource ↗

Where a card belongs beside the page, from LAYOUT RECORDS.

The one question the tree cannot answer, and the one a surface must not answer for itself: measuring painted DOM puts the sidebar a repaint behind the document and breaks outright while pagination is in flight.

Returns null when the item has no resolvable range, or when its paragraph is not in this layout — a comment anchored in a header belongs to a story the body layout never saw.

declare function reviewItemGeometry(item: ReviewItem, index: ReadonlyMap<string, ReviewParagraphAnchor>): {
    readonly pageIndex: number;
    readonly y: number;
} | null;

reviewItemKeyfunctionSource ↗

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

declare function reviewItemKey(item: ReviewItem): string;

reviewItemPositionRankfunctionSource ↗

A single comparable number for document order.

Paragraph index dominates offset, so a revision spanning paragraphs still sorts by where it STARTS. An item with no resolvable range sorts last rather than to position zero, which is where an orphan used to land — tearing an orphaned reply out of its own thread.

declare function reviewItemPositionRank(item: ReviewItem, order: ReadonlyMap<string, number>): number;

reviewItemRangesfunctionSource ↗

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

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

reviewItemsAtfunctionSource ↗

Every item covering a position, innermost first.

Returning the whole stack rather than one winner is what lets a surface offer cycling, a stacked card, or a "1 of 3" affordance. A comment wrapping a revision used to be unreachable because only the tightest range was ever returned.

declare function reviewItemsAt(items: readonly ReviewItem[], position: ReviewPosition, order: ReadonlyMap<string, number>): ReviewItem[];

reviewThreadRootOffunctionSource ↗

Walk a reply up to the card that heads its thread. Guarded against a cyclic file.

The head is not always a comment. A reply to a tracked change renders inside the REVISION's card, so resolving it to itself opened an item nothing on screen was drawing — the reply box vanished the moment somebody answered a change.

EXPORTED because the paginated surface answers "which card is open" itself, against its own dismissed-key state, rather than through [activeReviewItem](activeReviewItem). Two copies of the innermost-wins rule was survivable while a reply could only be a comment — the parent came first in comments.xml order and won the tie by accident. It stopped being survivable the moment a reply could answer a revision, which outranks it outright.

declare function reviewThreadRootOf(items: readonly ReviewItem[], comment: ReviewCommentItem): ReviewItem;

revisionAuthorFilterfunctionSource ↗

Build a canonical reviewer filter. An empty input returns undefined for the fast path.

declare function revisionAuthorFilter(hiddenAuthors: Iterable<string>): RevisionAuthorFilter | undefined;

revisionRemovesParagraphfunctionSource ↗

True when a tracked revision has removed this paragraph from the rendered document, so layout should emit no box for it at all.

declare function revisionRemovesParagraph(paragraph: OoxmlNode, displayMode?: RevisionDisplayMode, authorFilter?: RevisionAuthorFilter): boolean;

revisionsAreDeletionfunctionSource ↗

True when this stack of revisions marks its content as deleted from the live document.

declare function revisionsAreDeletion(revisions: readonly RevisionAttribution[]): boolean;

revisionsVisiblefunctionSource ↗

Whether content under this stack of revisions is laid out in the given mode.

Containment governs, so a single enclosing wrapper the mode resolves away suppresses everything inside it regardless of what the inner wrappers say. An insertion inside a deletion does not survive the proposed result: the deletion it sits in was accepted.

declare function revisionsVisible(revisions: readonly RevisionAttribution[], mode: RevisionDisplayMode, authorFilter?: RevisionAuthorFilter): boolean;

roundFontUnitToFixedPointfunctionSource ↗

Convert signed font units by an exact rational multiplier using the declared tie rule.

roundFontUnitToFixedPoint: (fontUnits: number, denominator: number, numerator: number, mode: FixedPointRoundingMode) => FixedPoint

runStylesEqualfunctionSource ↗

Whether two resolved styles are identical, for span merging and cache keys.

declare function runStylesEqual(a: ResolvedRunStyle, b: ResolvedRunStyle): boolean;

segmentGraphemesfunctionSource ↗

Split text into graphemes through the active boundary.

Memoized on the last texts seen, because paragraph layout asks about the same string repeatedly and a full segmentation pass per call made layout quadratic in paragraph length.

declare function segmentGraphemes(text: string): readonly GraphemeSegment[];

segmentWordsfunctionSource ↗

Split text into word segments through the given boundary, or the resolved default.

declare function segmentWords(text: string, boundary?: WordBoundary): readonly WordSegment[];

selectionRectsfunctionSource ↗

The physical rectangles covering a selection, including disjoint bands within bidi lines.

BODY fragments only, and a selection outside the body paints nothing. That is a real gap — a retained pin in a header shows no highlight, and a comment anchored in one draws no band even though the review queue lists it — but it is the honest shape of what this can answer today. Widening the walk to the other stories is not enough on its own: header and footer fragments carry positions relative to their own story box, note fragments relative to their note area, and one header story object is attached to EVERY page it applies to. Fed straight into a page-content-relative rect, those produce a band per page, at coordinates belonging to a different box. Measured, that put a header comment's band on all six pages of a document at the top-left of the body text. Painting nothing is wrong; painting over the wrong words is worse, so the walk stays here until the geometry is carried with it.

declare function selectionRects(layout: SemanticLayout, selection: SemanticSelection, 
order: readonly string[], 
measurer?: TextMeasurer): SelectionRect[];

semanticHorizontalBoundariesfunctionSource ↗

Grapheme offsets corresponding to exact shaped boundaries.

declare function semanticHorizontalBoundaries(run: ShapedRun): readonly number[];

setGraphemeBoundaryfunctionSource ↗

Install a different segmentation strategy, invalidating the memo.

For tests and for runtimes lacking Intl.Segmenter. Call [resetGraphemeBoundary](resetGraphemeBoundary) to restore the default.

declare function setGraphemeBoundary(boundary: GraphemeBoundary): void;

setHarfBuzzWasmUrlfunctionSource ↗

Point the text shaper at an externally hosted copy of harfbuzz.wasm.

Needed only under bundlers that do not emit new URL(..., import.meta.url) assets. esbuild and Bun are the common ones, and so is any build that inlines dynamic imports, such as a library bundle. There, the build succeeds and the shaper fails at runtime with an EditorFontError whose code is wasmUnavailable; this function is the fix. Webpack, Turbopack and Vite emit the binary on their own, and passing a URL there simply overrides theirs.

ts import { setHarfBuzzWasmUrl } from '@docx-editor.dev/core/layout'; setHarfBuzzWasmUrl('/static/harfbuzz.wasm');

Pass a URL your application controls. It is fetched and instantiated as WebAssembly, so never derive it from user input, a query parameter, or remote configuration. Serving it cross-origin needs that origin in your connect-src CSP directive, and WebAssembly needs wasm-unsafe-eval in script-src either way.

Call it before the first editor is created. The runtime reads the location once and caches the result, so a call afterwards warns and does nothing: fix the call site and reload. The file to serve is exported as @docx-editor.dev/core/harfbuzz.wasm, and it must be the copy from the installed package version, because the runtime refuses a version mismatch at load rather than shaping with unverified metrics.

declare function setHarfBuzzWasmUrl(url: string | URL): void;

sha256FontBytesfunctionSource ↗

Synchronous platform-neutral SHA-256 used before font bytes cross into a shaping implementation.

sha256FontBytes: (bytes: Uint8Array) => string

shadingFillFromElementfunctionSource ↗

Read w:shd from a typed/generic element (table tcPr, nested pPr, …).

declare function shadingFillFromElement(shd: OoxmlElement | undefined): string | undefined;

shapedHorizontalBoundariesfunctionSource ↗

UTF-16 boundaries that are both whole-grapheme and HarfBuzz cluster edges.

declare function shapedHorizontalBoundaries(run: ShapedRun): readonly number[];

shapedRunComparatorInputsfunctionSource ↗

Reduce a shaped run to its comparable form, validating it on the way through.

What the D9 determinism oracles compare: two shaping runs of the same text in the same environment must produce byte-identical structures here.

shapedRunComparatorInputs: (input: ShapedRun, environment: ShapingEnvironmentInput) => ShapedRunComparatorInputs

shapingEnvironmentFingerprintfunctionSource ↗

Canonical serialization of every shaping variable, including byte hash and provenance.

shapingEnvironmentFingerprint: (environment: ShapingEnvironmentInput) => string

shapingEnvironmentFingerprintInputsfunctionSource ↗

Reduce an environment to its comparable form, with records sorted so key order cannot affect the result.

shapingEnvironmentFingerprintInputs: (input: ShapingEnvironmentInput) => ShapingEnvironmentFingerprintInputs

shownMarkRevisionfunctionSource ↗

The single decision a one-field reader sees.

A DELETION wins when a mark carries both, for the reason paint draws it that way: a break proposed and then unproposed ends up removed, so that is the decision a reader who can only see one must see. One function decides it, so the deprecated field, the deprecated function and the painted glyph cannot answer differently.

declare function shownMarkRevision(revisions: readonly RevisionAttribution[]): RevisionAttribution | undefined;

spanOffsetXfunctionSource ↗

The x of a model offset inside a span — the inverse of [offsetWithinSpan](offsetWithinSpan).

Shares the measurement, and the cache, with the hit test. Interpolating across the span's advance instead is exact only for a uniform one: in a proportional face the caret for offset 4 of an 8-character span is drawn at half its width, which lands in the middle of a glyph rather than between two.

declare function spanOffsetX(span: StyleSpanRecord, offset: number, measurer: TextMeasurer | undefined): number;

spansInCellsfunctionSource ↗

The style spans a cell selection covers, for reporting active formatting.

declare function spansInCells(layout: SemanticLayout, cellIds: readonly string[]): readonly StyleSpanRecord[];

spansInSelectionfunctionSource ↗

The style spans a selection touches, for reporting active formatting.

declare function spansInSelection(layout: SemanticLayout, selection: SemanticSelection, 
order: readonly string[]): StyleSpanRecord[];

storyBlocksfunctionSource ↗

The story's blocks — paragraphs and tables — in document order, flattening through block-level content-control wrappers under the shared nesting budget.

Repeated calls with the same part and display mode return the SAME array instance, shared by every caller — treat it as read-only; mutating it corrupts later callers.

declare function storyBlocks(part: OoxmlPart, displayMode?: RevisionDisplayMode, authorFilter?: RevisionAuthorFilter): OoxmlElement[];

styleForFontSlotfunctionSource ↗

The style a piece's text is MEASURED AND PAINTED in, given the font slot it carries.

This is the measurer-boundary resolution: pieces and spans keep the run's real resolved style — with fontFamily and fontFamilyEastAsia both intact, so formatting readback and the format painter see the run as authored — and every consumer that turns text into geometry or ink resolves the face through here. The derived object is memoized per (style, family) by [withFontFamily](withFontFamily), so measurers amortizing over style identity keep their caches.

declare function styleForFontSlot(style: ResolvedRunStyle, slot: FontSlot | undefined): ResolvedRunStyle;

syntheticSeparatorBoxfunctionSource ↗

Default rule geometry for a synthetic / marker-only separator, story-relative.

declare function syntheticSeparatorBox(contentWidth: number, flowHeight: number): LayoutBox;

tabAdvanceWidthfunctionSource ↗

Width of a tab glyph so the following segment lands on the destination.

segmentWidth / decimalOffset are already measured in points. Decimal offset is the advance from the segment start to the decimal point (0 when none — treated like right).

declare function tabAdvanceWidth(alignment: TabAlignment, currentX: number, destinationX: number, segmentWidth: number, decimalOffset: number): number;

tableContextAtfunctionSource ↗

The table context of one paragraph — what a toolbar reflects when the caret is in a cell.

Answers for a plain caret, not only for a cell selection, because "am I in a table" is a question about where the caret is and a toolbar that only knew during a rectangle drag would show its table controls disabled while the user was typing in a cell.

declare function tableContextAt(layout: SemanticLayout, paragraphId: string): TableCellContext | null;

tableOriginXfunctionSource ↗

Where a table's left edge sits inside the box that contains it.

Ordinary left-aligned tables start at their indent; centered/right-aligned tables use the remaining width. A verified legacy content-aligned table instead aligns the leading cell's content edge with the text column, without changing its indent.

declare function tableOriginX(structure: SemanticTableStructure, containerWidthPt: number): number;

tabStopsFingerprintfunctionSource ↗

Stable fingerprint for layout cache keys — nested w:tabs are not in flat OoxmlProperty bags, so style-inherited stops must be named explicitly or breaks would collide.

declare function tabStopsFingerprint(tabs: ResolvedTabStops): string;

tocFieldChromeParagraphIdsfunctionSource ↗

Paragraph ids for TOC field begin/end chrome that must not reserve vertical flow when empty.

declare function tocFieldChromeParagraphIds(part: OoxmlPart): ReadonlySet<string>;

tryCreateCanvasMeasurerfunctionSource ↗

Build a canvas-backed measurer, or null when no 2d context was injected.

Prefer [resolveDefaultSurfaceMeasurer](resolveDefaultSurfaceMeasurer) at the editor surface: that keeps the fixed fallback for SSR/tests in one place.

declare function tryCreateCanvasMeasurer(options?: CanvasMeasurerOptions): TextMeasurer | null;

unionLayoutBoxesfunctionSource ↗

Axis-aligned union of boxes, or null when the list is empty.

Used when a control's content spans several fragments or spans on one page.

declare function unionLayoutBoxes(boxes: readonly LayoutBox[]): LayoutBox | null;

utf16OffsetToGraphemefunctionSource ↗

The grapheme index containing a UTF-16 offset. Clamps rather than throwing.

Backed by a single-entry index cache: this runs once per character during paragraph layout, and re-segmenting per call is what made a 20,000-character paragraph take minutes to open. One entry rather than a map, because the keys are file-derived strings of unbounded size.

declare function utf16OffsetToGrapheme(text: string, utf16Offset: number): number;

walkStoryParagraphsfunctionSource ↗

Collect paragraphs of a block list in document order, descending into tables.

Caps nesting so a hostile nested-table document cannot recurse without bound.

declare function walkStoryParagraphs(blocks: readonly OoxmlElement[], maxTableDepth?: number): OoxmlElement[];

withDefaultTabIntervalfunctionSource ↗

Republish stops under a document-wide default-tab interval (w:defaultTabStop).

The cascade resolves stops from the paragraph's own property chain, which cannot see settings.xml; the interval is a document constant that arrives from the session. Returns the input unchanged when nothing moves, so a cache-key fingerprint stays stable.

declare function withDefaultTabInterval(tabs: ResolvedTabStops, defaultIntervalPt: number | undefined): ResolvedTabStops;

withNumberingStyleLinksfunctionSource ↗

Resolve w:numStyleLink delegation using the document's styles (§17.9.21).

Without a style table there is nothing to follow, so the index is returned unchanged — and so it is when nothing delegates, which keeps layout cache identity.

declare function withNumberingStyleLinks(index: NumberingIndex, styleCascade: StyleCascadeTable | undefined): NumberingIndex;

withResolvedListItemsfunctionSource ↗

Attach a full-story list-item map to layout options.

Resolves once over blocks (body story including table cells) so counters continue across section boundaries. No-ops when numbering is absent.

declare function withResolvedListItems<T extends {
    readonly numberingIndex?: NumberingIndex;
    readonly listItems?: ReadonlyMap<string, ResolvedListItem>;
    readonly styleCascade?: StyleCascadeTable;
    readonly isFontAvailable?: (family: string) => boolean;
}>(options: T, blocks: readonly OoxmlElement[]): T & {
    readonly numberingIndex: NumberingIndex;
    readonly listItems?: ReadonlyMap<string, ResolvedListItem>;
};

wordBoundaryfunctionSource ↗

The next word boundary from offset, in direction.

Word-LEFT skips any whitespace immediately behind the caret and then the word behind that, which makes repeated presses walk words rather than alternate with the preceding space.

stops are offsets a word may not run THROUGH even when the characters either side are word characters. They exist because the text this walks is what the VIEW is showing, and a view can show two versions of the document side by side: struck text and the text proposed to replace it abut with no separator, so ALL CAPS deleted and fsdfsd inserted read as the single word CAPSfsdfsd. Those characters are never adjacent in any one version, and a double-click that took both selected across a decision the reader had not made. See deletedTextBoundaries.

declare function wordBoundary(text: string, offset: number, direction: -1 | 1, stops?: ReadonlySet<number>): number;

wordSegmentsToGraphemeRecordsfunctionSource ↗

Map UTF-16 word segments to grapheme-safe half-open ranges within one paragraph.

declare function wordSegmentsToGraphemeRecords(text: string, segments: readonly WordSegment[]): readonly GraphemeWordSegmentRecord[];

FontResolutionErrorclassSource ↗

A face that could not be admitted, carrying whatever evidence the refusal produced.

RETURNED rather than thrown by FontResourceSnapshot.resolve, because a missing face is an ordinary condition — layout falls back and carries on. It extends Error so a caller that would rather throw can.

declare class FontResolutionError extends Error

HarfBuzzShapingErrorclassSource ↗

A shaping call that was refused, carrying the limit it exceeded where there was one.

Thrown rather than returned: unlike a missing font, a run that cannot be shaped has no sensible fallback measurement, and continuing would lay text out at made-up widths.

declare class HarfBuzzShapingError extends Error

LayoutShapingConfigurationErrorclassSource ↗

Invalid host configuration caught before any bytes reach HarfBuzz.

declare class LayoutShapingConfigurationError extends Error

ResolvedCacheclassSource ↗

The layout measurement cache, keyed by fingerprint rather than by revision.

An entry may be reused ACROSS revisions: the model revision is recorded as PROVENANCE, not as an equality condition. Reuse is proven only when the transitive dependency fingerprint, the unit's own input fingerprint, and every non-model environment input all match — which is what lets an edit in one paragraph leave the rest of a long document measured.

declare class ResolvedCache<V>

TablePaginationErrorclassSource ↗

Bounded table pagination failure. Prefer this over emitting a fragment that overflows the page content box.

declare class TablePaginationError extends Error

UnsupportedScriptErrorclassSource ↗

A code point whose script this engine does not itemize.

Carries the offending codePoint so the caller can report which character stopped it, rather than failing anonymously somewhere in the middle of a paragraph.

declare class UnsupportedScriptError extends Error

AbstractNumDefinitioninterfaceSource ↗

One w:abstractNum — the shape of a list, without being a list.

Never referenced by a paragraph directly. Paragraphs name a [NumDefinition](NumDefinition), which names one of these, so several lists can share a definition and still count separately.

interface AbstractNumDefinition

AnchoredDrawingRecordinterfaceSource ↗

interface AnchoredDrawingRecord extends Omit<InlineDrawingRecord, 'kind' | 'baselineOffset' | 'advanceStart' | 'advanceEnd' | 'distL' | 'distR' | 'distT' | 'distB'>

AutonumFieldSpecinterfaceSource ↗

One recognized AUTONUM-family instruction: the kind and its supported switches.

interface AutonumFieldSpec

BidiEmbeddingLevelsinterfaceSource ↗

UAX #9 embedding levels, one per UTF-16 code unit, plus the paragraph ranges they were resolved within.

The level is EXACT, not a direction: its parity gives direction, but the numeric value is what reordering needs, and collapsing it early loses nested isolates.

interface BidiEmbeddingLevels

BorderGridGeometryinterfaceSource ↗

The absolute grid a table's borders are drawn on: column widths, and per-row tops and heights.

Shared by every edge so adjacent cells resolve to the SAME line, rather than each computing its own and leaving a hairline gap between them.

interface BorderGridGeometry

CacheProvenanceinterfaceSource ↗

Everything recorded with a cache entry: the model revision (provenance only) + the fingerprints and snapshot that DO gate reuse.

interface CacheProvenance extends OperationSnapshot

CanvasMeasurerOptionsinterfaceSource ↗

How the canvas measurer resolves fonts, scales, and bounds its caches. Every field optional.

Layout never creates a canvas itself: without a context this measurer does not exist and the surface falls back to fixed metrics.

interface CanvasMeasurerOptions

CanvasTextContextinterfaceSource ↗

The slice of a 2D canvas context measurement needs.

A structural subset rather than CanvasRenderingContext2D, so layout stays DOM-free and a test can supply a deterministic stub.

interface CanvasTextContext

CanvasTextMetricsinterfaceSource ↗

The canvas text-metrics surface the editor injects.

Structural subset of CanvasRenderingContext2D — declared here so the layout lane stays off the DOM lib. Hosts pass a real 2d context; tests pass a controllable mock.

interface CanvasTextMetrics

CaretAtOptionsinterfaceSource ↗

How caret geometry is resolved.

preferPage disambiguates a paragraph that paints on SEVERAL pages — a shared header appears once per page, and without a preference the caret could be placed on any of its copies.

interface CaretAtOptions

CaretGeometryinterfaceSource ↗

A caret position with the geometry that renders it.

interface CaretGeometry

CascadedParagraphFormattinginterfaceSource ↗

A paragraph's properties after the cascade, plus the same list WITHOUT its own w:pPr.

Both, because a writer needs to know what a paragraph INHERITS to decide whether setting a value is a change or a no-op — and writing back an inherited value freezes it into the paragraph as though the author had chosen it.

interface CascadedParagraphFormatting

CellBorderBoxinterfaceSource ↗

The four resolved edges of one cell, after conflict resolution against its neighbours.

interface CellBorderBox

CellMarginsPtinterfaceSource ↗

Resolved cell padding in points, after the table default and any per-cell override.

interface CellMarginsPt

CellSelectioninterfaceSource ↗

A rectangle of table cells.

interface CellSelection

CjkTypographySettingsinterfaceSource ↗

Document-wide East Asian line-break and whitespace policy.

interface CjkTypographySettings

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

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

CompoundBorderMetricsinterfaceSource ↗

How a multi-line border style (double, triple) is drawn: stroke width, gap, and total extent.

The band is CENTRED on the authored width, so a double border occupies the space Word gives it rather than growing the cell it surrounds.

interface CompoundBorderMetrics

ContentControlBoundaryRecordinterfaceSource ↗

Layout-published boundary for one content control (w:sdt / typed contentControl).

Chrome, lock feedback, and hit resolution read this record — never painted DOM. The wrapper itself is not a layout box; fragments cover the content that already flowed in place.

interface ContentControlBoundaryRecord

ContentControlFragmentRecordinterfaceSource ↗

One page-local rectangle covering the part of a control that sits on that page.

interface ContentControlFragmentRecord extends LayoutBox

ContentControlGeometryFragmentinterfaceSource ↗

One piece of a control's content geometry.

A block control that crosses a page break publishes one fragment per page rather than a single rectangle covering the inter-page gap. An inline control publishes one fragment per LINE it touches, covering the text's vertical extent (line-spacing leading excluded), so a wrapped control never claims the words beside it. Coordinates match fragment boxes (page-content space).

interface ContentControlGeometryFragment

CreateDocumentFurnitureSourceOptionsinterfaceSource ↗

Inputs that remain valid for the lifetime of one furniture source.

interface CreateDocumentFurnitureSourceOptions

CreateDocumentNotesInputOptionsinterfaceSource ↗

Inputs for projecting notes through the same semantic layout pass.

interface CreateDocumentNotesInputOptions

DeclaredFontSubstitutioninterfaceSource ↗

A host-declared redirect: requests for from resolve to to.

How a metric-compatible substitute is wired in — a document naming Calibri resolves to Carlito without the document being rewritten.

interface DeclaredFontSubstitution

DocumentFurnitureSourceinterfaceSource ↗

Page furniture supplied to semantic layout.

interface DocumentFurnitureSource

DocumentLinkProjectorsinterfaceSource ↗

Sanitized projectors paired with the cache identities required to use them safely.

Keep this object intact when passing it to a document composition helper. Projected text and its dependency tokens are one contract: accepting either half independently permits stale paragraph caches after relationship- or property-only revisions.

interface DocumentLinkProjectors extends StoryProjectionDependencies

DocumentSectioninterfaceSource ↗

One section of the body story: contiguous top-level blocks plus the properties that end it.

blockStart / blockEndExclusive index into storyBlocks(part).

interface DocumentSection

DocumentSectionsEnumerationinterfaceSource ↗

Every section in a document, with a flag saying whether the list was cut short.

truncated is reported rather than silent: section count comes from a file, so a crafted document declaring thousands of paragraph-level w:sectPr marks is bounded, and a reader should be able to tell that happened.

interface DocumentSectionsEnumeration

DocumentStyleDependenciesinterfaceSource ↗

Memoized style inputs shared by every story in one document view.

interface DocumentStyleDependencies

DrawingAccessibilityinterfaceSource ↗

interface DrawingAccessibility

DrawingGeometryinterfaceSource ↗

interface DrawingGeometry

DrawingImageEffectsinterfaceSource ↗

Picture color adjustments shared by projection, layout, and paint.

interface DrawingImageEffects

DrawingInsetsinterfaceSource ↗

interface DrawingInsets

DrawingOverlayFrameinterfaceSource ↗

Page-content overlay rectangle for a drawing's painted extent.

interface DrawingOverlayFrame

DrawingPointinterfaceSource ↗

interface DrawingPoint

DrawingTransforminterfaceSource ↗

interface DrawingTransform

EquationFractionGeometryinterfaceSource ↗

interface EquationFractionGeometry extends EquationGeometryBase

EquationNaryGeometryinterfaceSource ↗

interface EquationNaryGeometry extends EquationGeometryBase

EquationRadicalGeometryinterfaceSource ↗

interface EquationRadicalGeometry extends EquationGeometryBase

EquationRowGeometryinterfaceSource ↗

interface EquationRowGeometry extends EquationGeometryBase

EquationScriptGeometryinterfaceSource ↗

interface EquationScriptGeometry extends EquationGeometryBase

EquationSpanRecordinterfaceSource ↗

Equation metadata carried by one atomic semantic span.

interface EquationSpanRecord

EquationTextGeometryinterfaceSource ↗

interface EquationTextGeometry extends EquationGeometryBase

FieldAtomMarkerinterfaceSource ↗

What a piece says about the FIELD result it came from, for Word's shading.

Carried from layout rather than decided at paint time because only the walk knows an atom was a field at all — by paint the result is just text. Whether the shading is actually drawn is a view decision made downstream, so this states the fact and nothing about the appearance.

interface FieldAtomMarker

FieldLinkRegistryinterfaceSource ↗

Per-layout registry for projected HYPERLINK fields.

interface FieldLinkRegistry

FontFingerprintInputsinterfaceSource ↗

A font reduced to the values that identify it for fingerprinting.

Includes the content hash and faceIndex, so two faces with the same family name but different bytes fingerprint differently — which is what stops a cached measurement being reused against a substituted face.

interface FontFingerprintInputs

FontRequestinterfaceSource ↗

A face, as something asks for it: family plus the two axes this engine admits.

Only static weights and slants. Variable-font axes are deliberately outside this vocabulary — the shaper refuses variation axes, and a variable file admitted here would render bold at regular weight.

interface FontRequest

FontResourceDefinitioninterfaceSource ↗

One face offered to a snapshot, before admission.

hash is checked against the bytes, so a source cannot claim a face it did not supply. Setting availability to forbidden declares a face that exists but must not be used, which resolves as a typed refusal rather than as "missing".

interface FontResourceDefinition

FontResourceInstrumentationinterfaceSource ↗

Optional counters for the operations font admission is expected to do RARELY.

Exists so tests can assert the absence of work: hashing and byte-copying a 64 MB face on every resolve would not be visible in output, only in a stalled document, so the checks assert these fire once rather than per call.

interface FontResourceInstrumentation

FontResourceSnapshotinterfaceSource ↗

An immutable set of admitted faces, and the only way to reach one.

epoch identifies the snapshot: fonts change by REPLACING it, never by mutation, so a layout pass holds one snapshot for its whole run and cannot observe a face appearing or vanishing midway.

interface FontResourceSnapshot

FontResourceSnapshotOptionsinterfaceSource ↗

How a snapshot is built: which faces, under what limits, validated how.

maxFontBytes is clamped to [HARD_MAX_FONT_BYTES](HARD_MAX_FONT_BYTES) — a caller may tighten the budget but never widen it past the engine's own ceiling.

interface FontResourceSnapshotOptions

FontSubstitutioninterfaceSource ↗

A request that was answered by a DIFFERENT face than the one asked for.

Recorded rather than silently applied, because a substitution changes measurement: it is part of the shaping fingerprint, so a cached run shaped against a substitute is never reused for the real face.

interface FontSubstitution

GlyphOutlineinterfaceSource ↗

A glyph's outline as SVG path data, in font design units.

interface GlyphOutline

GraphemeBoundaryinterfaceSource ↗

The replaceable segmentation strategy.

An explicit seam rather than a direct Intl.Segmenter call, so tests can install a deterministic boundary and a runtime without Intl.Segmenter can be given one.

interface GraphemeBoundary

GraphemeSegmentinterfaceSource ↗

One user-perceived character, and the UTF-16 range that encodes it.

The unit a caret moves by. An emoji with a skin-tone modifier is ONE segment spanning several UTF-16 code units, so stepping by code unit would put the caret inside it.

interface GraphemeSegment

GraphemeWordSegmentRecordinterfaceSource ↗

A word span expressed in GRAPHEME offsets rather than UTF-16 ones.

What selection actually uses: a range whose ends are UTF-16 offsets could land inside a grapheme, and selecting half an emoji is not a word.

interface GraphemeWordSegmentRecord

HarfBuzzFaceCacheEventinterfaceSource ↗

One face-cache transition, for instrumentation.

interface HarfBuzzFaceCacheEvent

HarfBuzzOutlineCacheEventinterfaceSource ↗

One outline-cache transition, for instrumentation.

interface HarfBuzzOutlineCacheEvent

HarfBuzzShapeCacheEventinterfaceSource ↗

One shape-cache transition, for instrumentation.

interface HarfBuzzShapeCacheEvent

HarfBuzzTextShaperinterfaceSource ↗

A [TextShaper](TextShaper) backed by HarfBuzz, holding WASM resources.

[HarfBuzzTextShaper.dispose](HarfBuzzTextShaper.dispose) is not optional housekeeping: the cached faces are WASM allocations that garbage collection cannot reclaim, so a shaper outliving its editor leaks until the page goes away.

interface HarfBuzzTextShaper extends TextShaper

HarfBuzzTextShaperInstrumentationinterfaceSource ↗

Optional counters for the work a shaper is expected to do rarely.

Exists so tests can assert the ABSENCE of work — re-opening a face or re-copying its bytes per shape call would not change any output, only make typing slow, which no rendering assertion would catch.

interface HarfBuzzTextShaperInstrumentation

HarfBuzzTextShaperOptionsinterfaceSource ↗

Resource budgets and cache sizes for one shaper. Every field optional.

The caches exist because shaping is the expensive step: a face is opened once and reused, and identical runs return their previous result. The caps exist because file-derived input decides how much work is asked for.

interface HarfBuzzTextShaperOptions

HeaderFooterStoryRecordinterfaceSource ↗

One header or footer story as it sits on one page.

box is absolute (sheet coordinates) and sized to the story's FLOW height — never to any anchored-object extent, which is the rule that keeps a decorated header's hit area from covering the body. fragments are story-relative (origin at the box's top-left). Baseline furniture may be shared across pages of the same variant when the story has no allowlisted PAGE/NUMPAGES/SECTIONPAGES fields; after page-field finalize, projections are per page (or per distinct field values for count-only stories).

interface HeaderFooterStoryRecord

HitPointinterfaceSource ↗

A point in the coordinate space named by the function taking it.

interface HitPoint

HitTestOptionsinterfaceSource ↗

How precisely a hit resolves within a run.

Without a measurer the offset is INTERPOLATED across the span's advance, which is exact only for monospaced text — supply one for proportional fonts, or a click lands a character or two away from the glyph under the pointer.

interface HitTestOptions

HyperlinkFieldSpecinterfaceSource ↗

One parsed HYPERLINK instruction: the raw, unsanitized pieces.

target and anchor are verbatim from the instruction — the projector at the trust boundary decides what, if anything, they become in a DOM sink.

interface HyperlinkFieldSpec

InlineDrawingRecordinterfaceSource ↗

interface InlineDrawingRecord

KeyedRangeinterfaceSource ↗

A model range to highlight, and the key the caller knows it by.

interface KeyedRange

LayoutBoxinterfaceSource ↗

A rectangle in layout POINTS.

Points everywhere in this layer — twips convert at property-read boundaries and CSS pixels at paint. A box carrying either of those would eventually be added to one carrying the other.

interface LayoutBox

LayoutCacheStatsinterfaceSource ↗

Cache counters, for asserting that incremental layout is actually reusing work.

interface LayoutCacheStats

LayoutEnvironmentShapedMeasurerOptionsinterfaceSource ↗

Environment-bound production options that cannot drift from layout cache identity.

interface LayoutEnvironmentShapedMeasurerOptions

LayoutFontConfigurationinterfaceSource ↗

Structural font configuration shared by browser and server hosts.

interface LayoutFontConfiguration

LayoutFontSourceinterfaceSource ↗

Byte-backed face accepted by neutral shaping.

interface LayoutFontSource

LayoutFontSubstitutioninterfaceSource ↗

Explicit face substitution accepted by neutral shaping.

interface LayoutFontSubstitution

LayoutSchedulerinterfaceSource ↗

Coalesces commits into layout passes.

A keystroke is one commit but must not be one full layout pass, so changes accumulate into a scope and are laid out together. Every published layout is tagged with the revision it actually read, which is what makes a stale result detectable rather than merely late.

interface LayoutScheduler

LayoutSchedulerOptionsinterfaceSource ↗

How the scheduler produces layouts and when it publishes them.

interface LayoutSchedulerOptions

LayoutScopeinterfaceSource ↗

What a batch of commits can affect.

paragraphIds is the set the commits touched directly. What that set MEANS depends on impact: for a local impact it bounds the work, for a structural one it only says where the reflow starts.

interface LayoutScope

LayoutSessioninterfaceSource ↗

Carried-over state that makes layout incremental.

A caller creates one and hands the SAME object back each pass. It holds the previous pages, the per-block cache keys and the flow checkpoints a pass resumes from, so an edit low in a document re-lays only what follows it. A no-change pass returns the previous pages by identity.

interface LayoutSession

LayoutSessionStatsinterfaceSource ↗

What the last layout pass actually did — the observable evidence that incremental layout is working.

reusedPages and fullPasses are the ones that matter: a typing keystroke that rebuilds every page produces identical output and unusable performance, so the tests assert on these rather than on the rendered result.

interface LayoutSessionStats

LayoutShapingInstrumentationinterfaceSource ↗

Optional measurements for resource-budget tests and host diagnostics.

interface LayoutShapingInstrumentation

LayoutShapingOptionsinterfaceSource ↗

A fully resolved shaping bundle: fonts, shaper, and the environment they were admitted under. Produced by the editor lane's font configuration (createLayoutShaping) and consumed to build shaped measurers. Lived in the legacy metrics.ts until the legacy layout lane was deleted; the type is the surviving contract between the two lanes.

interface LayoutShapingOptions

LevelOverrideinterfaceSource ↗

One w:lvlOverride on a w:num: a restart value, a replacement level, or both.

How two lists share an abstract definition while numbering independently.

interface LevelOverride

LineRecordinterfaceSource ↗

One laid-out line: its geometry, its baseline, and the styled spans it renders.

The unit hit-testing and caret placement resolve against. Geometry comes from HERE, never from the DOM, which is what lets an empty paragraph still get a caret.

interface LineRecord

LineSegmentinterfaceSource ↗

The part of a line that belongs to ONE paragraph.

A line normally belongs to one paragraph outright, and then this is the whole of it — the same object every caller read before, so nothing about an ordinary document takes a new path. A resolved display mode merges paragraphs that a tracked decision merges, and the line carrying the join holds spans from two of them. Offsets there are ambiguous by themselves: both paragraphs start at zero, so an offset means nothing without the paragraph it counts in.

interface LineSegment

ListCounterAdvanceinterfaceSource ↗

The result of counting ONE list paragraph: the level that applied, the counter vector after it, and the marker text a reader sees.

Counters are a vector across all nine levels, not a single number, because a deeper level restarting resets the ones below it while leaving those above intact.

interface ListCounterAdvance

ListCounterStateinterfaceSource ↗

The running counters for one layout pass over one story.

Stateful and order-dependent by nature: a list number is a function of every numbered paragraph before it, which is why markers are computed during layout and cannot be read off a paragraph in isolation.

interface ListCounterState

ListMarkerRecordinterfaceSource ↗

A numbering marker as layout published it.

Geometry is in the same coordinate space as the fragment (page-content or cell-content relative). Paint positions from this box and MUST NOT remeasure the marker.

interface ListMarkerRecord

MaterializationInputinterfaceSource ↗

Which pages to build in detail.

A page left out keeps its size and position but no content, so the document's height and page count are unchanged and scrolling to it reveals it rather than reflowing everything below.

interface MaterializationInput

MoveCaretOptionsinterfaceSource ↗

Story-scoped stops are required when navigating inside an open header or footer.

interface MoveCaretOptions

NoteAreaRecordinterfaceSource ↗

Footnote / endnote area on one page: separator + stacked note stories.

placement records how the area was positioned. fallbackReason is set when the bounded reflow loop exhausted and layout kept the reference with its note on a later page (D12 named fallback).

interface NoteAreaRecord