@beyondwork/docx-react-component 1.0.66 → 1.0.69

package/src/runtime/formatting/formatting-context.ts

@@ -0,0 +1,903 @@
+/**
+ * Layer 03 — production formatting orchestrator (`FormattingContext`).
+ *
+ * The authoritative entry point for the hot path. One context is built per
+ * canonical-document projection pass (`surface-projection`, layout resolve
+ * pass, etc.); it internally owns the per-document resolvers that the
+ * layer previously forced every consumer to construct on their own:
+ *
+ *   - `ThemeColorResolver` (theme-color.ts)
+ *   - `NumberingPrefixResolver` (numbering/prefix.ts, stateful counters)
+ *   - the `StylesCatalog` for cascade walks
+ *   - the `FontTable` for ECMA-376 §17.3.2.26 font precedence
+ *   - the `FieldResolver` (when a page-graph is threaded in)
+ *
+ * Every method below is a production boundary call. The earlier
+ * `resolveEffectiveFormatting(doc, nodeRef)` API is a thin façade built on
+ * top of this context so tests + external callers exercise the same code
+ * path as the hot production path.
+ *
+ * Architecture contract F1: every consumer that needs effective formatting
+ * flows through this context (directly, or via
+ * `resolveEffectiveFormatting`). Scattered direct calls to sub-resolvers
+ * from non-Layer-03 code are rejected by
+ * `scripts/ci-check-formatting-layer-purity.mjs` (guards under
+ * `src/runtime/formatting/`) and by
+ * `scripts/ci-check-formatting-production-boundary.mjs` (guards the
+ * production consumers that migrated).
+ *
+ * Per F2, the context holds NO document state — it only caches the
+ * resolvers built from the input document. Caller is responsible for
+ * discarding the context when the document changes.
+ */
+
+import type {
+  CanonicalDocument,
+  CanonicalFontTable,
+  CanonicalParagraphFormatting,
+  CanonicalRunFormatting,
+  CanonicalTheme,
+  FieldRegistryEntry,
+  HyperlinkNode,
+  InlineNode,
+  ParagraphNode,
+  RevisionRecord,
+  TableNode,
+  TableStyleConditionalRegion,
+} from "../../model/canonical-document.ts";
+import type { FieldPageGraph, FieldResolver, ResolvedField } from "./field/resolver.ts";
+import { createFieldResolver } from "./field/resolver.ts";
+import { ThemeColorResolver, concretizeThemeColors } from "./theme-color.ts";
+import type { NumberingPrefixResolver, NumberingPrefixResult } from "./numbering/prefix.ts";
+import { createNumberingPrefixResolver } from "./numbering/prefix.ts";
+import {
+  resolveEffectiveParagraphFormatting,
+  resolveEffectiveRunFormatting,
+  resolveNumberingMarkerRunFormatting,
+  resolveTableCellTextFormatting,
+  type RunResolveInput,
+} from "./style-cascade.ts";
+import { resolveParagraphStyleChain } from "./paragraph-style-resolver.ts";
+import { resolveTableStyleResolution, type ResolvedTableStyleResolution } from "./table-style-resolver.ts";
+import { resolveHyperlinkRunFormatting } from "./hyperlink-color.ts";
+import { resolveRunFontFamily } from "./font-resolution.ts";
+import { applyRevisionDisplay } from "./revision-display.ts";
+import type {
+  EffectiveFieldDisplay,
+  EffectiveNumbering,
+  EffectiveParagraphFormatting,
+  EffectiveRunFormatting,
+} from "./formatting-types.ts";
+
+/**
+ * Direct-text-mark direct formatting. Mirrors (and replaces) the
+ * `buildDirectRunFormattingFromMarks` helper that previously lived
+ * inside `surface-projection.ts`. The production hot path passes
+ * projected marks + markAttrs in; `resolveEffectiveFormatting(doc,
+ * nodeRef)` callers use `resolveDirectRunFormattingAtSegment` on a
+ * canonical `TextNode` instead.
+ */
+/**
+ * Projected run marks — a string-literal union a size wider than the
+ * canonical direct-formatting projection. The extra marks (`superscript`,
+ * `subscript`, `emboss`, `imprint`, `shadow`) are preserved through the
+ * surface snapshot but have no direct-formatting projection into
+ * `CanonicalRunFormatting`; they flow through the surface marks array
+ * untouched. The context ignores them.
+ */
+export type ProjectedSurfaceMark =
+  | "bold"
+  | "italic"
+  | "underline"
+  | "strikethrough"
+  | "doubleStrikethrough"
+  | "superscript"
+  | "subscript"
+  | "vanish"
+  | "emboss"
+  | "imprint"
+  | "shadow"
+  | "smallCaps"
+  | "allCaps";
+
+export interface ProjectedRunMarks {
+  readonly marks?: ReadonlyArray<ProjectedSurfaceMark>;
+  readonly markAttrs?: {
+    readonly backgroundColor?: string;
+    readonly charSpacing?: number;
+    readonly kerning?: number;
+    readonly textFill?: string;
+    readonly fontFamily?: string;
+    readonly fontSize?: number;
+    readonly textColor?: string;
+  };
+}
+
+/**
+ * Numbering resolution result shape returned to the production consumer.
+ * Kept structurally compatible with the legacy `NumberingPrefixResult`
+ * from `./numbering/prefix.ts` so surface-projection can keep its
+ * downstream adapters unchanged.
+ */
+export type NumberingResolution = NumberingPrefixResult;
+
+/**
+ * Cascade-tier provenance for a run resolution. Research doc
+ * `ResolvedProperty { value, source, sourceId }` maps onto this shape:
+ * each populated field points at the tier that won, plus (for style
+ * tiers) the styleId whose rPr carried the winning value.
+ *
+ * `source: "direct"` ≥ `source: "characterStyle"` ≥
+ * `source: "style"` ≥ `source: "docDefaults"` — highest priority wins.
+ */
+export interface RunResolvedProperty<TValue = unknown> {
+  readonly value: TValue;
+  readonly source: "direct" | "characterStyle" | "style" | "docDefaults";
+  /** Winning styleId for `style` / `characterStyle` sources. */
+  readonly sourceId?: string;
+}
+
+export interface RunProvenance {
+  readonly run: EffectiveRunFormatting;
+  readonly properties: { readonly [K in keyof CanonicalRunFormatting]?: RunResolvedProperty };
+}
+
+export interface FormattingContextOptions {
+  readonly fontTable?: CanonicalFontTable;
+  /** Active markup mode. When set, per-run resolution attaches
+   *  `revisionDisplay` flags via `applyRevisionDisplay`. */
+  readonly revisionMarkupMode?: "clean" | "simple" | "all";
+  /**
+   * Live markup-mode callback. When set, it is consulted on every
+   * per-run resolve — composed L06 `workflow.getMarkupModePolicy()`
+   * (class-A document default) with L10 `ui.viewport.getEffectiveMarkupMode()`
+   * (class-C user preference) drive the active mode without the
+   * context being rebuilt. Precedence: callback result (if not
+   * `undefined`) wins over the static `revisionMarkupMode` field.
+   *
+   * The layer itself stays F6-neutral (applies posture, does not decide
+   * the mode — see `03-formatting-semantics.md` §F6). When the callback
+   * returns `undefined`, no posture is applied on that pass (same as
+   * the static field being unset).
+   */
+  readonly getEffectiveMarkupMode?: () =>
+    | "clean"
+    | "simple"
+    | "all"
+    | undefined;
+  /** Author-id → color palette for revision-display posture. */
+  readonly authorColorPalette?: ReadonlyMap<string, string>;
+  /**
+   * Page-graph reference for field resolution. When absent, the field
+   * resolver is not built and field dispatches return
+   * `refreshStatus: "unresolved"` with the registry's cached displayText.
+   */
+  readonly pageGraph?: FieldPageGraph;
+  /** Active page index for PAGE field resolution. Ignored when
+   *  `pageGraph` is absent. */
+  readonly activePageIndex?: number;
+  /**
+   * Optional pre-built bookmark map keyed on bookmark name. The field
+   * resolver needs it for REF / PAGEREF. The context accepts it so
+   * consumers that already compute bookmarks don't duplicate the work.
+   */
+  readonly bookmarkMap?: Map<string, { bookmarkId: string; paragraphIndex: number }>;
+  /** Per-paragraph cursor offsets used by REF/PAGEREF relative-position
+   *  resolution. */
+  readonly paragraphOffsets?: readonly number[];
+}
+
+export interface FormattingContext {
+  readonly doc: CanonicalDocument;
+  readonly theme: ThemeColorResolver | undefined;
+
+  /** Build (or reuse) the stateful numbering prefix resolver. */
+  readonly numbering: NumberingPrefixResolver;
+
+  /** Lazy field resolver; undefined until a page graph is threaded via opts. */
+  readonly field: FieldResolver | undefined;
+
+  /**
+   * Return the first open revision whose anchor range covers the
+   * half-open segment `[from, to)`, or `undefined` when no revision is
+   * attached. Pre-computed once per document from
+   * `doc.review.revisions`; consumers call this per segment to obtain
+   * the attached revision that `resolveRunFromMarks({ revision })` will
+   * use for F6 posture application.
+   *
+   * Accepted / rejected / detached revisions are ignored — F6's markup
+   * modes only change how *open* revisions render.
+   */
+  findRevisionAtRange(from: number, to: number): RevisionRecord | undefined;
+
+  /**
+   * Full paragraph cascade: docDefaults → style chain → direct. Returns
+   * the flat canonical shape for downstream consumers that want to read
+   * individual fields directly.
+   */
+  resolveParagraphCascade(para: ParagraphNode): CanonicalParagraphFormatting;
+
+  /**
+   * Per-paragraph "effective numbering" — inherits from
+   * `paragraph.numbering` or (when missing) walks the paragraph-style
+   * chain for a style-linked numbering reference. Mirrors the
+   * `resolveEffectiveParagraphNumbering` logic that previously lived in
+   * `surface-projection.ts` and moves it into L03 ownership.
+   */
+  resolveEffectiveParagraphNumbering(para: ParagraphNode): ParagraphNode["numbering"] | undefined;
+
+  /**
+   * Resolve the per-paragraph numbering prefix + geometry (marker,
+   * indent, tab) for rendering. Returns `null` when the paragraph has
+   * no numbering. Advances the stateful counter when `advance = true`
+   * (the default).
+   *
+   * For culled paragraphs on the viewport edge, callers pass
+   * `advance: true, emitGeometry: false` so the counter stays in sync
+   * without paying the geometry-projection cost.
+   */
+  resolveParagraphNumbering(
+    para: ParagraphNode,
+    options?: { advance?: boolean; emitGeometry?: boolean },
+  ): NumberingResolution | null;
+
+  /**
+   * Per-paragraph numbering-marker rPr cascade (ECMA-376 §17.9).
+   * Mirrors `resolveNumberingMarkerRunFormatting` with the layer's
+   * owned style catalog.
+   */
+  resolveNumberingMarkerRunFormatting(
+    paragraphStyleId: string | undefined,
+    levelRunProperties: CanonicalRunFormatting | undefined,
+  ): CanonicalRunFormatting;
+
+  /**
+   * Production hot-path run cascade. Accepts the surface-projected marks
+   * + markAttrs representation and does:
+   *   1. `buildDirectRunFormattingFromMarks` equivalent → direct rPr.
+   *   2. docDefaults → paragraph-style chain → character-style chain →
+   *      direct cascade.
+   *   3. Hyperlink-color cascade when the run is inside a `HyperlinkNode`.
+   *   4. Theme-color concretization via the layer-owned `ThemeColorResolver`.
+   *   5. Revision-display posture application when opts configured.
+   *
+   * The return value is `EffectiveRunFormatting` — the same type the
+   * entry-point `resolveEffectiveFormatting` produces; consumers should
+   * treat them as interchangeable. When revision posture is attached,
+   * `run.revisionDisplay` is populated.
+   */
+  resolveRunFromMarks(input: {
+    paragraphStyleId: string | undefined;
+    marks: ProjectedRunMarks | undefined;
+    inHyperlink: boolean;
+    characterStyleId?: string | undefined;
+    revision?: RevisionRecord;
+  }): EffectiveRunFormatting;
+
+  /**
+   * Pure canonical-inline-oriented run cascade. Used by the
+   * `resolveEffectiveFormatting(doc, nodeRef)` façade when callers pass
+   * a `TextNode` with canonical `marks` instead of the projected form.
+   */
+  resolveRunFromCanonicalInline(input: {
+    paragraphStyleId: string | undefined;
+    characterStyleId: string | undefined;
+    direct: CanonicalRunFormatting | undefined;
+    inHyperlink: boolean;
+    revision?: RevisionRecord;
+  }): EffectiveRunFormatting;
+
+  /**
+   * Table-style resolution; delegates to the pure resolver and exposes
+   * the same shape. Kept on the context so production consumers
+   * (surface-projection, layout public-facet) import from one place.
+   */
+  resolveTable(table: TableNode): ResolvedTableStyleResolution;
+
+  /**
+   * Cell-text cascade floor (docDefaults → table-style chain →
+   * optional conditional-region layering). Paragraph + run direct
+   * formatting from the cell's content layers on top via the normal
+   * paragraph/run cascades.
+   *
+   * When `activeRegions` is supplied (from `getActiveCellRegions()`
+   * via `resolveTable(table).rows[i].cells[j].activeConditionalRegions`)
+   * the cascade layers each region's `tblStylePr/pPr` + `rPr` after the
+   * basedOn-chain walk — fixes the L03 pre-A1 gap where banded tables
+   * and header rows received no region-level paragraph/run properties.
+   * Borders / shading / margins were already region-aware via
+   * `mergeStyleFormattingCell`; this brings text formatting to parity.
+   */
+  resolveTableCellFloor(
+    tableStyleId: string | undefined,
+    activeRegions?: readonly TableStyleConditionalRegion[],
+  ): { paragraph: CanonicalParagraphFormatting; run: CanonicalRunFormatting };
+
+  /** Resolve a registered field entry. Returns `undefined` when the
+   *  context has no page-graph (so the resolver was never built). */
+  resolveField(entry: FieldRegistryEntry): ResolvedField | undefined;
+
+  /** Resolve the effective font family for a run following
+   *  ECMA-376 §17.3.2.26 precedence + theme-minor fallback. */
+  resolveFontFamily(input: RunResolveInput, themeMinorFont?: string): string | undefined;
+
+  /** Build an `EffectiveParagraphFormatting` wrapper (cascade +
+   *  numbering + paragraphMarkRun) for the entry-point façade. */
+  resolveParagraph(para: ParagraphNode): EffectiveParagraphFormatting;
+
+  /**
+   * Layer-03 §C (provenance). Resolve the run cascade AND return a
+   * per-field source map — for each populated field, name the cascade
+   * tier that won the resolution: `"docDefaults"`, `"style"` (with the
+   * winning styleId), `"characterStyle"` (ditto), or `"direct"`.
+   *
+   * This powers agent explanations ("this bold came from the Heading 1
+   * style, not from direct formatting"). It is NOT called on the hot
+   * path — production consumers use `resolveRunFromCanonicalInline`
+   * which pays zero provenance cost.
+   *
+   * Research doc `ResolvedProperty { value, source, sourceId }` maps
+   * directly onto the return shape here.
+   */
+  resolveRunWithProvenance(input: {
+    paragraphStyleId: string | undefined;
+    characterStyleId: string | undefined;
+    direct: CanonicalRunFormatting | undefined;
+  }): RunProvenance;
+
+  /** Resolve an `EffectiveFieldDisplay` shape for an inline field. */
+  resolveFieldDisplay(
+    entry: FieldRegistryEntry | undefined,
+    cachedDisplayText: string | undefined,
+  ): EffectiveFieldDisplay;
+}
+
+// ---------------------------------------------------------------------------
+// Implementation
+// ---------------------------------------------------------------------------
+
+class FormattingContextImpl implements FormattingContext {
+  readonly doc: CanonicalDocument;
+  readonly theme: ThemeColorResolver | undefined;
+  readonly numbering: NumberingPrefixResolver;
+  readonly field: FieldResolver | undefined;
+  private readonly opts: FormattingContextOptions;
+  // F6 revision-range index. Built once per context lifetime (O(R)),
+  // consulted per segment (O(R) linear in the common case — the document
+  // has tens of open revisions, not thousands, so a sorted walk is fine).
+  // `null` when the caller did not configure revision markup, so the
+  // segment walk pays zero cost.
+  private readonly revisionIndex:
+    | ReadonlyArray<{ from: number; to: number; revision: RevisionRecord }>
+    | null;
+  // Paragraph-cascade memoization (D). Keyed by the weak `para` reference
+  // so cache frees automatically when the paragraph is GC'd. Hot-path
+  // surface-projection calls `resolveParagraphCascade` on the same
+  // paragraph via `resolveParagraph` + numbering resolve + marker-rPr;
+  // each of those re-walked the style catalog before.
+  private readonly paragraphCascadeCache: WeakMap<
+    ParagraphNode,
+    CanonicalParagraphFormatting
+  > = new WeakMap();
+
+  constructor(doc: CanonicalDocument, opts: FormattingContextOptions) {
+    this.doc = doc;
+    this.opts = opts;
+    const canonicalTheme: CanonicalTheme | undefined = doc.subParts?.canonicalTheme;
+    this.theme = canonicalTheme ? new ThemeColorResolver(canonicalTheme) : undefined;
+    this.numbering = createNumberingPrefixResolver(doc.numbering);
+    this.field =
+      opts.pageGraph !== undefined
+        ? createFieldResolver({
+            pageGraph: opts.pageGraph,
+            activePageIndex: opts.activePageIndex ?? 0,
+            bookmarkMap: opts.bookmarkMap ?? new Map(),
+            paragraphOffsets: opts.paragraphOffsets ?? [],
+            styles: doc.styles,
+            contentRoot: doc.content,
+          })
+        : undefined;
+    this.revisionIndex =
+      opts.revisionMarkupMode !== undefined ||
+      opts.getEffectiveMarkupMode !== undefined
+        ? buildRevisionRangeIndex(doc)
+        : null;
+  }
+
+  findRevisionAtRange(from: number, to: number): RevisionRecord | undefined {
+    const index = this.revisionIndex;
+    if (!index) return undefined;
+    for (const entry of index) {
+      if (entry.from > to) break;
+      if (entry.from <= from && entry.to >= to) return entry.revision;
+      if (entry.from <= from && entry.to > from) return entry.revision;
+    }
+    return undefined;
+  }
+
+  resolveParagraphCascade(para: ParagraphNode): CanonicalParagraphFormatting {
+    const cached = this.paragraphCascadeCache.get(para);
+    if (cached !== undefined) return cached;
+    const resolved = resolveEffectiveParagraphFormatting(
+      {
+        styleId: para.styleId,
+        direct: extractDirectParagraphFormatting(para),
+      },
+      this.doc.styles,
+    );
+    this.paragraphCascadeCache.set(para, resolved);
+    return resolved;
+  }
+
+  resolveEffectiveParagraphNumbering(
+    para: ParagraphNode,
+  ): ParagraphNode["numbering"] | undefined {
+    if (para.numbering) return para.numbering;
+    if (!para.styleId) return undefined;
+    const paragraphStyles = this.doc.styles?.paragraphs ?? {};
+    const styleChain = resolveParagraphStyleChain(para.styleId, this.doc.styles);
+    let styleNumbering: { numberingInstanceId: string; level?: number } | undefined;
+    for (const styleId of styleChain) {
+      const style = paragraphStyles[styleId];
+      if (style?.numbering) {
+        styleNumbering = style.numbering;
+        break;
+      }
+    }
+    if (!styleNumbering) return undefined;
+    if (styleNumbering.level !== undefined) {
+      return {
+        numberingInstanceId: styleNumbering.numberingInstanceId,
+        level: styleNumbering.level,
+      };
+    }
+    const resolvedLevel = resolveStyleLinkedNumberingLevel(
+      this.doc,
+      styleNumbering.numberingInstanceId,
+      styleChain,
+    );
+    return resolvedLevel !== undefined
+      ? {
+          numberingInstanceId: styleNumbering.numberingInstanceId,
+          level: resolvedLevel,
+        }
+      : undefined;
+  }
+
+  resolveParagraphNumbering(
+    para: ParagraphNode,
+    options: { advance?: boolean; emitGeometry?: boolean } = {},
+  ): NumberingResolution | null {
+    const advance = options.advance !== false;
+    const emitGeometry = options.emitGeometry !== false;
+    const effectiveNumbering = this.resolveEffectiveParagraphNumbering(para);
+    if (!effectiveNumbering) return null;
+    if (!emitGeometry) {
+      // Advance the counter but do not project geometry.
+      if (advance) this.numbering.resolve(effectiveNumbering);
+      return null;
+    }
+    if (!advance) {
+      // The underlying resolver is stateful and does not expose a
+      // "peek" primitive. When the caller needs the read without
+      // mutation, they must fork the context; for now, treat as a
+      // contract violation in a dev assertion.
+      // eslint-disable-next-line no-console -- dev-time only
+      console.warn("[formatting-context] resolveParagraphNumbering({advance:false}) is not supported; counter always advances");
+    }
+    return this.numbering.resolveDetailed(effectiveNumbering, para);
+  }
+
+  resolveNumberingMarkerRunFormatting(
+    paragraphStyleId: string | undefined,
+    levelRunProperties: CanonicalRunFormatting | undefined,
+  ): CanonicalRunFormatting {
+    return resolveNumberingMarkerRunFormatting(
+      { paragraphStyleId, levelRunProperties },
+      this.doc.styles,
+    );
+  }
+
+  resolveRunFromMarks(input: {
+    paragraphStyleId: string | undefined;
+    marks: ProjectedRunMarks | undefined;
+    inHyperlink: boolean;
+    characterStyleId?: string | undefined;
+    revision?: RevisionRecord;
+  }): EffectiveRunFormatting {
+    const direct = buildDirectRunFormattingFromProjected(input.marks);
+    return this.resolveRunCore({
+      paragraphStyleId: input.paragraphStyleId,
+      characterStyleId: input.characterStyleId,
+      direct,
+      inHyperlink: input.inHyperlink,
+      revision: input.revision,
+    });
+  }
+
+  resolveRunFromCanonicalInline(input: {
+    paragraphStyleId: string | undefined;
+    characterStyleId: string | undefined;
+    direct: CanonicalRunFormatting | undefined;
+    inHyperlink: boolean;
+    revision?: RevisionRecord;
+  }): EffectiveRunFormatting {
+    return this.resolveRunCore(input);
+  }
+
+  private resolveRunCore(input: {
+    paragraphStyleId: string | undefined;
+    characterStyleId: string | undefined;
+    direct: CanonicalRunFormatting | undefined;
+    inHyperlink: boolean;
+    revision?: RevisionRecord;
+  }): EffectiveRunFormatting {
+    const resolveInput: RunResolveInput = {
+      paragraphStyleId: input.paragraphStyleId,
+      characterStyleId: input.characterStyleId,
+      direct: input.direct,
+    };
+    const cascade = input.inHyperlink
+      ? resolveHyperlinkRunFormatting(resolveInput, this.doc.styles, this.theme)
+      : this.theme
+        ? concretizeThemeColors(
+            resolveEffectiveRunFormatting(resolveInput, this.doc.styles),
+            this.theme,
+          )
+        : resolveEffectiveRunFormatting(resolveInput, this.doc.styles);
+    const activeMarkupMode = this.resolveActiveMarkupMode();
+    if (activeMarkupMode !== undefined && input.revision !== undefined) {
+      const authorColor =
+        input.revision.authorId && this.opts.authorColorPalette
+          ? this.opts.authorColorPalette.get(input.revision.authorId)
+          : undefined;
+      const flags = applyRevisionDisplay(
+        cascade,
+        input.revision,
+        activeMarkupMode,
+        authorColor,
+      );
+      return { ...cascade, revisionDisplay: flags };
+    }
+    return cascade;
+  }
+
+  // Resolve the markup mode for the current per-run call. Callback
+  // wins when set; a callback that returns `undefined` means "no
+  // posture this pass" and does not fall back to the static field —
+  // that's how the composition site disables posture at runtime
+  // without rebuilding the context.
+  private resolveActiveMarkupMode():
+    | "clean"
+    | "simple"
+    | "all"
+    | undefined {
+    if (this.opts.getEffectiveMarkupMode !== undefined) {
+      return this.opts.getEffectiveMarkupMode();
+    }
+    return this.opts.revisionMarkupMode;
+  }
+
+  resolveTable(table: TableNode): ResolvedTableStyleResolution {
+    return resolveTableStyleResolution(table, this.doc.styles.tables);
+  }
+
+  resolveTableCellFloor(
+    tableStyleId: string | undefined,
+    activeRegions?: readonly TableStyleConditionalRegion[],
+  ): { paragraph: CanonicalParagraphFormatting; run: CanonicalRunFormatting } {
+    return resolveTableCellTextFormatting(
+      tableStyleId,
+      this.doc.styles,
+      activeRegions,
+    );
+  }
+
+  resolveField(entry: FieldRegistryEntry): ResolvedField | undefined {
+    if (!this.field) return undefined;
+    return this.field.resolve(entry);
+  }
+
+  resolveFontFamily(
+    input: RunResolveInput,
+    themeMinorFont?: string,
+  ): string | undefined {
+    return resolveRunFontFamily(
+      input,
+      this.doc.styles,
+      themeMinorFont,
+      this.opts.fontTable,
+      this.doc.subParts?.canonicalTheme?.fontScheme,
+    );
+  }
+
+  resolveParagraph(para: ParagraphNode): EffectiveParagraphFormatting {
+    const cascade = this.resolveParagraphCascade(para);
+    const numbering = buildEffectiveNumbering(
+      this.resolveParagraphNumbering(para, { advance: true }),
+    );
+    const paragraphMarkRun = cascade.paragraphMarkRunProperties && this.theme
+      ? (concretizeThemeColors(cascade.paragraphMarkRunProperties, this.theme) as EffectiveRunFormatting)
+      : (cascade.paragraphMarkRunProperties as EffectiveRunFormatting | undefined);
+    return {
+      ...cascade,
+      ...(numbering ? { numbering } : {}),
+      ...(paragraphMarkRun ? { paragraphMarkRun } : {}),
+    };
+  }
+
+  resolveRunWithProvenance(input: {
+    paragraphStyleId: string | undefined;
+    characterStyleId: string | undefined;
+    direct: CanonicalRunFormatting | undefined;
+  }): RunProvenance {
+    // Walk each tier in priority-ascending order, recording which tier
+    // last set each field. Highest-priority writer wins — same order
+    // as `resolveEffectiveRunFormatting` but with provenance tracked.
+    const properties: { [K in keyof CanonicalRunFormatting]?: RunResolvedProperty } = {};
+    const applyTier = (
+      tierRecord: CanonicalRunFormatting | undefined,
+      source: RunResolvedProperty["source"],
+      sourceId: string | undefined,
+    ): void => {
+      if (!tierRecord) return;
+      for (const key of Object.keys(tierRecord) as Array<keyof CanonicalRunFormatting>) {
+        const value = tierRecord[key];
+        if (value === undefined) continue;
+        properties[key] = {
+          value: value as unknown,
+          source,
+          ...(sourceId !== undefined ? { sourceId } : {}),
+        } as RunResolvedProperty;
+      }
+    };
+    const styles = this.doc.styles;
+    applyTier(styles.docDefaults?.run, "docDefaults", undefined);
+    if (input.paragraphStyleId) {
+      const chain = resolveParagraphStyleChain(input.paragraphStyleId, styles);
+      // Walk root-to-leaf so the most specific style wins.
+      for (let i = chain.length - 1; i >= 0; i -= 1) {
+        const styleId = chain[i]!;
+        applyTier(styles.paragraphs[styleId]?.runProperties, "style", styleId);
+      }
+    }
+    if (input.characterStyleId) {
+      // Character chain — lazy import to avoid cyclic dep.
+      const charStyles = styles.characters;
+      const visited = new Set<string>();
+      const chain: string[] = [];
+      let cursor: string | undefined = input.characterStyleId;
+      while (cursor && !visited.has(cursor)) {
+        visited.add(cursor);
+        if (charStyles[cursor]) chain.push(cursor);
+        cursor = charStyles[cursor]?.basedOn;
+      }
+      for (let i = chain.length - 1; i >= 0; i -= 1) {
+        const styleId = chain[i]!;
+        applyTier(charStyles[styleId]?.runProperties, "characterStyle", styleId);
+      }
+    }
+    applyTier(input.direct, "direct", undefined);
+    // Reconstruct the EffectiveRunFormatting from the winning values.
+    const run: EffectiveRunFormatting = {} as EffectiveRunFormatting;
+    for (const [key, prop] of Object.entries(properties) as Array<
+      [keyof CanonicalRunFormatting, RunResolvedProperty | undefined]
+    >) {
+      if (prop !== undefined) {
+        (run as Record<string, unknown>)[key] = prop.value;
+      }
+    }
+    // Theme concretization runs downstream of cascade — keep provenance
+    // stable ("style" or "direct" owns `colorTheme`; theme concretize
+    // populates `colorHex` which is still tied to the `colorTheme` tier).
+    if (this.theme) {
+      const concrete = concretizeThemeColors(run, this.theme);
+      if (concrete.colorHex && concrete.colorHex !== run.colorHex) {
+        (run as Record<string, unknown>).colorHex = concrete.colorHex;
+        properties.colorHex = {
+          value: concrete.colorHex,
+          source: properties.colorThemeSlot?.source ?? "style",
+          ...(properties.colorThemeSlot?.sourceId !== undefined
+            ? { sourceId: properties.colorThemeSlot.sourceId }
+            : {}),
+        };
+      }
+    }
+    return { run, properties };
+  }
+
+  resolveFieldDisplay(
+    entry: FieldRegistryEntry | undefined,
+    cachedDisplayText: string | undefined,
+  ): EffectiveFieldDisplay {
+    if (!entry) {
+      return cachedDisplayText
+        ? { refreshStatus: "unresolved", displayText: cachedDisplayText }
+        : { refreshStatus: "unresolved" };
+    }
+    const resolved = this.resolveField(entry);
+    if (!resolved) {
+      return {
+        refreshStatus: "unresolved",
+        ...(entry.displayText ? { displayText: entry.displayText } : {}),
+      };
+    }
+    const status: EffectiveFieldDisplay["refreshStatus"] =
+      resolved.refreshStatus === "current" || resolved.refreshStatus === "stale"
+        ? "resolved"
+        : resolved.refreshStatus === "unresolvable"
+          ? "unresolvable"
+          : "unresolved";
+    return {
+      refreshStatus: status,
+      ...(resolved.displayText !== undefined
+        ? { displayText: resolved.displayText }
+        : entry.displayText
+          ? { displayText: entry.displayText }
+          : {}),
+    };
+  }
+}
+
+export function createFormattingContext(
+  doc: CanonicalDocument,
+  opts: FormattingContextOptions = {},
+): FormattingContext {
+  return new FormattingContextImpl(doc, opts);
+}
+
+// ---------------------------------------------------------------------------
+// Private helpers
+// ---------------------------------------------------------------------------
+
+function buildDirectRunFormattingFromProjected(
+  projected: ProjectedRunMarks | undefined,
+): CanonicalRunFormatting | undefined {
+  if (!projected) return undefined;
+  const direct: CanonicalRunFormatting = {};
+  const marks = projected.marks;
+  if (marks) {
+    if (marks.includes("bold")) direct.bold = true;
+    if (marks.includes("italic")) direct.italic = true;
+    if (marks.includes("underline")) direct.underline = "single";
+    if (marks.includes("strikethrough")) direct.strikethrough = true;
+    if (marks.includes("doubleStrikethrough")) direct.doubleStrikethrough = true;
+    if (marks.includes("vanish")) direct.vanish = true;
+    if (marks.includes("allCaps")) direct.allCaps = true;
+    if (marks.includes("smallCaps")) direct.smallCaps = true;
+  }
+  const markAttrs = projected.markAttrs;
+  if (markAttrs) {
+    if (markAttrs.fontFamily) {
+      direct.fontFamily = markAttrs.fontFamily;
+      direct.fontFamilyAscii = markAttrs.fontFamily;
+    }
+    if (typeof markAttrs.fontSize === "number") {
+      direct.fontSizeHalfPoints = markAttrs.fontSize;
+    }
+    if (markAttrs.textColor) {
+      direct.colorHex = markAttrs.textColor.replace(/^#/, "");
+    }
+    if (markAttrs.backgroundColor) {
+      direct.highlight = markAttrs.backgroundColor;
+    }
+  }
+  return Object.keys(direct).length > 0 ? direct : undefined;
+}
+
+function extractDirectParagraphFormatting(
+  para: ParagraphNode,
+): CanonicalParagraphFormatting {
+  const direct: CanonicalParagraphFormatting = {};
+  if (para.alignment !== undefined) direct.alignment = para.alignment;
+  if (para.spacing !== undefined) direct.spacing = para.spacing;
+  if (para.contextualSpacing !== undefined) direct.contextualSpacing = para.contextualSpacing;
+  if (para.indentation !== undefined) direct.indentation = para.indentation;
+  if (para.tabStops !== undefined) direct.tabStops = para.tabStops;
+  if (para.keepNext !== undefined) direct.keepNext = para.keepNext;
+  if (para.keepLines !== undefined) direct.keepLines = para.keepLines;
+  if (para.outlineLevel !== undefined) direct.outlineLevel = para.outlineLevel;
+  if (para.pageBreakBefore !== undefined) direct.pageBreakBefore = para.pageBreakBefore;
+  if (para.widowControl !== undefined) direct.widowControl = para.widowControl;
+  if (para.borders !== undefined) direct.borders = para.borders;
+  if (para.shading !== undefined) direct.shading = para.shading;
+  if (para.bidi !== undefined) direct.bidi = para.bidi;
+  if (para.suppressLineNumbers !== undefined) direct.suppressLineNumbers = para.suppressLineNumbers;
+  return direct;
+}
+
+function resolveStyleLinkedNumberingLevel(
+  doc: CanonicalDocument,
+  numberingInstanceId: string,
+  styleChain: readonly string[],
+): number | undefined {
+  const instance = doc.numbering.instances[numberingInstanceId];
+  if (!instance) return undefined;
+
+  for (const styleId of styleChain) {
+    const overrideMatch = instance.overrides.find(
+      (override) => override.levelDefinition?.paragraphStyleId === styleId,
+    );
+    if (overrideMatch) return overrideMatch.level;
+  }
+
+  const abstractDefinition = doc.numbering.abstractDefinitions[instance.abstractNumberingId];
+  if (!abstractDefinition) return undefined;
+
+  for (const styleId of styleChain) {
+    const levelMatch = abstractDefinition.levels.find(
+      (levelDefinition) => levelDefinition.paragraphStyleId === styleId,
+    );
+    if (levelMatch) return levelMatch.level;
+  }
+  return undefined;
+}
+
+function buildEffectiveNumbering(
+  detail: NumberingResolution | null,
+): EffectiveNumbering | undefined {
+  if (!detail) return undefined;
+  const result: EffectiveNumbering = {
+    level: detail.level,
+    ...(detail.text !== null ? { marker: detail.text } : {}),
+    ...(detail.markerRunProperties
+      ? { markerRunFormatting: detail.markerRunProperties }
+      : {}),
+    ...(detail.geometry
+      ? {
+          indentation: {
+            ...(detail.geometry.indentation?.left !== undefined
+              ? { left: detail.geometry.indentation.left }
+              : {}),
+            ...(detail.geometry.indentation?.hanging !== undefined
+              ? { hanging: detail.geometry.indentation.hanging }
+              : {}),
+            ...(detail.geometry.indentation?.firstLine !== undefined
+              ? { firstLine: detail.geometry.indentation.firstLine }
+              : {}),
+            ...(detail.geometry.tabStops && detail.geometry.tabStops.length > 0
+              ? { tab: detail.geometry.tabStops[0]!.position }
+              : {}),
+          },
+        }
+      : {}),
+    ...(detail.picBulletMediaId
+      ? { pictureBulletRef: detail.picBulletMediaId }
+      : {}),
+  };
+  return result;
+}
+
+// Type-only re-export of HyperlinkNode so callers can type their walk.
+export type { HyperlinkNode, InlineNode };
+
+/**
+ * Build a sorted-by-`from` array of the document's OPEN revisions +
+ * their anchor ranges. Accepted / rejected / detached revisions are
+ * excluded because F6 markup modes ("clean" | "simple" | "all") only
+ * change how open revisions render. The array is immutable after
+ * construction; `FormattingContext.findRevisionAtRange` walks it per
+ * segment.
+ */
+function buildRevisionRangeIndex(
+  doc: CanonicalDocument,
+): ReadonlyArray<{ from: number; to: number; revision: RevisionRecord }> {
+  const records: { from: number; to: number; revision: RevisionRecord }[] = [];
+  const revisions = doc.review?.revisions;
+  if (!revisions) return records;
+  for (const revision of Object.values(revisions)) {
+    if (revision.status !== "open") continue;
+    const anchor = revision.anchor;
+    let range: { from: number; to: number } | undefined;
+    if (anchor.kind === "range") {
+      range = { from: anchor.range.from, to: anchor.range.to };
+    } else if (anchor.kind === "node") {
+      range = { from: anchor.at, to: anchor.at };
+    } else {
+      continue;
+    }
+    records.push({ from: range.from, to: range.to, revision });
+  }
+  records.sort((a, b) => a.from - b.from);
+  return records;
+}