@beyondwork/docx-react-component 1.0.38 → 1.0.39

package/src/runtime/layout/public-facet.ts

@@ -42,6 +42,7 @@ import type {
   LayoutEngineInstance,
   LayoutEngineQueryInput,
 } from "./layout-engine-instance.ts";
+import type { LayoutMeasurementProvider } from "./layout-measurement-provider.ts";
 import type { PageFragmentMapper } from "./page-fragment-mapper.ts";
 import {
   PAGE_FORMAT_CATALOG,
@@ -64,6 +65,7 @@ import { MAIN_STORY_TARGET } from "../../core/selection/mapping.ts";
 import { createSelectionSnapshot } from "../../core/state/editor-state.ts";
 import { resolveTableStyleResolution } from "../table-style-resolver.ts";
 import { buildTableRenderPlan } from "./table-render-plan.ts";
+import { recordPerfSample } from "../../ui-tailwind/editor-surface/perf-probe.ts";
 import type {
   SurfaceBlockSnapshot,
 } from "../../api/public-types";
@@ -396,6 +398,28 @@ export interface WordReviewEditorLayoutFacet {
   getMeasurement(blockId: string): PublicBlockMeasurement | null;
   getMeasurementFidelity(): PublicMeasurementFidelity;
   whenMeasurementReady(): Promise<void>;
+  swapMeasurementProvider(provider: LayoutMeasurementProvider): void;
+
+  // Table render plan (P3e consumed by the render kernel, P4) ------------
+  /**
+   * 0-based page index where the first fragment of `blockId` lands, or
+   * `null` when the block has no fragments in the current page graph.
+   * Used by the tables facet to determine which page to request plans for
+   * without needing PM document offsets.
+   */
+  getFirstPageIndexForBlock(blockId: string): number | null;
+  /**
+   * Build a `TableRenderPlan` for a table block on a given page. Returns
+   * `null` when the blockId does not resolve to a table in the current
+   * surface. The plan carries columnsTwips, bandClasses, verticalMerges,
+   * repeatedHeaderRows, and columnResizeHandles so chrome can render
+   * band-aware cell styling and place column-resize grips without
+   * walking canonical state.
+   */
+  getTableRenderPlan(
+    blockId: string,
+    pageIndex: number,
+  ): import("./table-render-plan.ts").TableRenderPlan | null;
 
   // Table render plan (P3e consumed by the render kernel, P4) ------------
   /**
@@ -659,8 +683,11 @@ export function createLayoutFacet(
     hitTest(pointInRoot) {
       const kernel = input.renderKernel?.();
       if (!kernel) return null;
+      const t0 = typeof performance !== "undefined" ? performance.now() : 0;
       const frame = kernel.getRenderFrame();
-      return resolveHitTest(frame, pointInRoot);
+      const result = resolveHitTest(frame, pointInRoot);
+      if (t0 > 0) recordPerfSample("chrome.hit_test", performance.now() - t0);
+      return result;
     },
 
     getAnchorRects(query) {
@@ -736,6 +763,18 @@ export function createLayoutFacet(
       return engine.whenMeasurementReady();
     },
 
+    getFirstPageIndexForBlock(blockId) {
+      const graph = currentGraph();
+      const fragment = graph.fragments.find((f) => f.blockId === blockId);
+      if (!fragment) return null;
+      const page = graph.pages.find((p) => p.pageId === fragment.pageId);
+      return page?.pageIndex ?? null;
+    },
+
+    swapMeasurementProvider(provider) {
+      engine.swapMeasurementProvider(provider);
+    },
+
     getTableRenderPlan(blockId, pageIndex) {
       const graph = currentGraph();
       const fragment = graph.fragments.find((f) => f.blockId === blockId);

package/src/runtime/layout/resolve-page-fields.ts

@@ -0,0 +1,70 @@
+/**
+ * Resolve `PAGE` and `NUMPAGES` field values per page.
+ *
+ * These two field families (now in `SupportedFieldFamily`) compute differently
+ * from `REF` / `PAGEREF` because the resolved value depends on the *owning
+ * page* of each header/footer instance, not on a single document-level
+ * computation.  A header part is shared across many pages; the same PAGE
+ * field must render "1" on page 1, "2" on page 2, and so on.
+ *
+ * The resolver is a pure function over the page graph — no DOM, no side
+ * effects.  Consumers (per-page header/footer bands) call
+ * `resolvePageFieldDisplayText` at render time to substitute the cached
+ * preserve-only text that currently sits inside the paragraph inline atom.
+ */
+
+import type { RuntimePageGraph, RuntimePageNode } from "./page-graph.ts";
+import type { SupportedFieldFamily } from "../../model/canonical-document.ts";
+
+export interface PageFieldContext {
+  /** The page this header/footer copy renders on. */
+  page: RuntimePageNode;
+  /** The graph the page belongs to (for NUMPAGES resolution). */
+  graph: RuntimePageGraph;
+}
+
+/**
+ * Resolve the display text for a PAGE / NUMPAGES field on a specific page.
+ *
+ * Returns the original cached `displayText` for unsupported families so the
+ * caller can use this as a single resolution helper.
+ */
+export function resolvePageFieldDisplayText(
+  family: SupportedFieldFamily | string,
+  cachedDisplayText: string,
+  context: PageFieldContext,
+): string {
+  switch (family) {
+    case "PAGE":
+      return String(context.page.stories.displayPageNumber);
+    case "NUMPAGES":
+      // Blank fillers (evenPage/oddPage section breaks) don't count toward
+      // NUMPAGES — the graph already excludes them from contentPageCount.
+      return String(context.graph.contentPageCount);
+    default:
+      return cachedDisplayText;
+  }
+}
+
+/**
+ * Build a lookup keyed by pageId → (fieldFamily → resolvedText).  Useful when
+ * a renderer wants to bulk-resolve every page's fields before emitting DOM.
+ * Absent keys mean no override; the cached field text should be used.
+ */
+export function buildPageFieldResolutionTable(
+  graph: RuntimePageGraph,
+  families: ReadonlySet<string> = new Set(["PAGE", "NUMPAGES"]),
+): Map<string, Map<string, string>> {
+  const result = new Map<string, Map<string, string>>();
+  for (const page of graph.pages) {
+    const perPage = new Map<string, string>();
+    for (const family of families) {
+      perPage.set(
+        family,
+        resolvePageFieldDisplayText(family, "", { page, graph }),
+      );
+    }
+    result.set(page.pageId, perPage);
+  }
+  return result;
+}

package/src/runtime/layout/resolve-page-previews.ts

@@ -0,0 +1,185 @@
+/**
+ * Flatten header/footer sub-part blocks to short text previews with PAGE /
+ * NUMPAGES fields resolved for the owning page.  Used by the in-flow page
+ * chrome widgets so the bands show live content ("Page 3 of 5") rather
+ * than a static "Header" / "Footer" placeholder.
+ *
+ * This is a **preview**, not a full renderer — we flatten to plain text
+ * and cap the length.  A per-page band is ~32 px tall; anything more
+ * elaborate belongs to the full editing path, which is entered by double-
+ * clicking the band.
+ */
+
+import type {
+  BlockNode,
+  HeaderDocument,
+  FooterDocument,
+  InlineNode,
+} from "../../model/canonical-document.ts";
+import type {
+  RuntimePageGraph,
+  RuntimePageNode,
+} from "./page-graph.ts";
+import { resolvePageFieldDisplayText } from "./resolve-page-fields.ts";
+
+const MAX_PREVIEW_CHARS = 140;
+
+export interface PagePreviewMaps {
+  /** pageId → short text preview of the resolved header story (if any). */
+  headerPreviewByPageId: Map<string, string>;
+  /** pageId → short text preview of the resolved footer story (if any). */
+  footerPreviewByPageId: Map<string, string>;
+}
+
+export function buildPagePreviewMaps(
+  graph: RuntimePageGraph,
+  subParts: {
+    headers?: ReadonlyArray<HeaderDocument>;
+    footers?: ReadonlyArray<FooterDocument>;
+  },
+): PagePreviewMaps {
+  const headerPreviewByPageId = new Map<string, string>();
+  const footerPreviewByPageId = new Map<string, string>();
+
+  for (const page of graph.pages) {
+    if (page.isBlankFiller) continue;
+    const headerStory = page.stories.header;
+    if (headerStory && headerStory.kind === "header") {
+      const source = findSubPart(subParts.headers, headerStory.relationshipId);
+      if (source) {
+        headerPreviewByPageId.set(
+          page.pageId,
+          flattenBlocksToPreview(source.blocks, page, graph),
+        );
+      }
+    }
+    const footerStory = page.stories.footer;
+    if (footerStory && footerStory.kind === "footer") {
+      const source = findSubPart(subParts.footers, footerStory.relationshipId);
+      if (source) {
+        footerPreviewByPageId.set(
+          page.pageId,
+          flattenBlocksToPreview(source.blocks, page, graph),
+        );
+      }
+    }
+  }
+
+  return { headerPreviewByPageId, footerPreviewByPageId };
+}
+
+function findSubPart<T extends HeaderDocument | FooterDocument>(
+  parts: ReadonlyArray<T> | undefined,
+  relationshipId: string,
+): T | undefined {
+  if (!parts) return undefined;
+  return parts.find((p) => p.relationshipId === relationshipId);
+}
+
+function flattenBlocksToPreview(
+  blocks: ReadonlyArray<BlockNode>,
+  page: RuntimePageNode,
+  graph: RuntimePageGraph,
+): string {
+  const parts: string[] = [];
+  for (const block of blocks) {
+    collectBlockText(block, page, graph, parts);
+    if (joinPreview(parts).length >= MAX_PREVIEW_CHARS) break;
+  }
+  return truncate(joinPreview(parts));
+}
+
+function collectBlockText(
+  block: BlockNode,
+  page: RuntimePageNode,
+  graph: RuntimePageGraph,
+  out: string[],
+): void {
+  switch (block.type) {
+    case "paragraph":
+      for (const child of block.children) {
+        collectInlineText(child, page, graph, out);
+      }
+      break;
+    case "table":
+      for (const row of block.rows) {
+        for (const cell of row.cells) {
+          for (const childBlock of cell.children) {
+            collectBlockText(childBlock, page, graph, out);
+          }
+        }
+      }
+      break;
+    case "sdt":
+      for (const child of block.children) {
+        collectBlockText(child, page, graph, out);
+      }
+      break;
+    // opaque_block / section_break / custom_xml / alt_chunk — no preview text.
+    default:
+      break;
+  }
+}
+
+function collectInlineText(
+  inline: InlineNode,
+  page: RuntimePageNode,
+  graph: RuntimePageGraph,
+  out: string[],
+): void {
+  switch (inline.type) {
+    case "text":
+      out.push(inline.text);
+      break;
+    case "tab":
+      out.push(" ");
+      break;
+    case "hard_break":
+      out.push(" ");
+      break;
+    case "field": {
+      const family = inline.fieldFamily ?? classifyFieldInstructionLocal(inline.instruction);
+      const cached = flattenInline(inline.children);
+      if (family === "PAGE" || family === "NUMPAGES") {
+        out.push(
+          resolvePageFieldDisplayText(family, cached, { page, graph }),
+        );
+      } else {
+        out.push(cached);
+      }
+      break;
+    }
+    case "hyperlink":
+      for (const child of inline.children) {
+        collectInlineText(child, page, graph, out);
+      }
+      break;
+    // bookmark_start/end, opaque_inline, note_ref etc — skip.
+    default:
+      break;
+  }
+}
+
+function flattenInline(inlines: ReadonlyArray<InlineNode> | undefined): string {
+  if (!inlines) return "";
+  let buf = "";
+  for (const inline of inlines) {
+    if (inline.type === "text") buf += inline.text;
+    else if (inline.type === "hard_break" || inline.type === "tab") buf += " ";
+  }
+  return buf;
+}
+
+function classifyFieldInstructionLocal(instr: string): string {
+  const match = /^\s*(\w+)/.exec(instr);
+  return match ? match[1]!.toUpperCase() : "UNKNOWN";
+}
+
+function joinPreview(parts: readonly string[]): string {
+  return parts.join("").replace(/\s+/g, " ").trim();
+}
+
+function truncate(s: string): string {
+  if (s.length <= MAX_PREVIEW_CHARS) return s;
+  return s.slice(0, MAX_PREVIEW_CHARS - 1).trimEnd() + "…";
+}

package/src/runtime/layout/resolved-formatting-state.ts

@@ -151,11 +151,11 @@ export function resolveBlockFormatting(
     fontSizeHalfPoints: fontInfo.fontSizeHalfPoints,
     averageCharWidthTwips: fontInfo.avgCharWidth,
     tabStops: resolveTabStops(block),
-    keepNext: Boolean(block.keepNext),
-    keepLines: Boolean(block.keepLines),
-    pageBreakBefore: Boolean(block.pageBreakBefore),
-    widowControl: block.widowControl !== false, // default true in Word
-    contextualSpacing: Boolean(block.contextualSpacing),
+    keepNext: Boolean(block.keepNext ?? block.resolvedParagraphFormatting?.keepNext),
+    keepLines: Boolean(block.keepLines ?? block.resolvedParagraphFormatting?.keepLines),
+    pageBreakBefore: Boolean(block.pageBreakBefore ?? block.resolvedParagraphFormatting?.pageBreakBefore),
+    widowControl: (block.widowControl ?? block.resolvedParagraphFormatting?.widowControl) !== false, // default true in Word
+    contextualSpacing: Boolean(block.contextualSpacing ?? block.resolvedParagraphFormatting?.contextualSpacing),
   };
 }
 
@@ -166,9 +166,10 @@ export function resolveBlockFormatting(
 function resolveSpacing(
   block: Extract<SurfaceBlockSnapshot, { kind: "paragraph" }>,
 ): ParagraphSpacing {
-  // Numbering geometry spacing overrides direct paragraph spacing
+  // Priority: numbering geometry > direct paragraph > style cascade
   const numbering = block.resolvedNumbering?.geometry.spacing;
   const direct = block.spacing;
+  const cascade = block.resolvedParagraphFormatting?.spacing;
 
   const normalizeLineRule = (
     rule: string | undefined,
@@ -177,21 +178,15 @@ function resolveSpacing(
     return undefined;
   };
 
-  if (numbering) {
+  if (numbering || direct || cascade) {
     return {
-      before: numbering.before ?? direct?.before,
-      after: numbering.after ?? direct?.after,
-      line: numbering.line ?? direct?.line,
-      lineRule: normalizeLineRule(numbering.lineRule) ?? normalizeLineRule(direct?.lineRule),
-    };
-  }
-
-  if (direct) {
-    return {
-      before: direct.before,
-      after: direct.after,
-      line: direct.line,
-      lineRule: normalizeLineRule(direct.lineRule),
+      before: numbering?.before ?? direct?.before ?? cascade?.before,
+      after: numbering?.after ?? direct?.after ?? cascade?.after,
+      line: numbering?.line ?? direct?.line ?? cascade?.line,
+      lineRule:
+        normalizeLineRule(numbering?.lineRule) ??
+        normalizeLineRule(direct?.lineRule) ??
+        normalizeLineRule(cascade?.lineRule),
     };
   }
 
@@ -228,16 +223,25 @@ function resolveIndentation(
     };
   }
 
-  const ind = block.indentation;
-  if (!ind) {
+  const direct = block.indentation;
+  const cascade = block.resolvedParagraphFormatting?.indentation;
+
+  if (!direct && !cascade) {
     return { left: 0, right: 0, firstLine: 0, hanging: 0 };
   }
 
   return {
-    left: ind.left ?? 0,
-    right: ind.right ?? 0,
-    firstLine: ind.firstLine ?? 0,
-    hanging: ind.hanging ?? (typeof ind.firstLine === "number" && ind.firstLine < 0 ? Math.abs(ind.firstLine) : 0),
+    left: direct?.left ?? cascade?.left ?? 0,
+    right: direct?.right ?? cascade?.right ?? 0,
+    firstLine: direct?.firstLine ?? cascade?.firstLine ?? 0,
+    hanging:
+      direct?.hanging ??
+      cascade?.hanging ??
+      (typeof direct?.firstLine === "number" && direct.firstLine < 0
+        ? Math.abs(direct.firstLine)
+        : typeof cascade?.firstLine === "number" && cascade.firstLine < 0
+          ? Math.abs(cascade.firstLine)
+          : 0),
   };
 }
 

package/src/runtime/layout/table-render-plan.ts

@@ -101,6 +101,13 @@ export interface BuildTableRenderPlanInput {
   /** If `columnsTwips` was scaled to the canvas width, pass the scale
    *  factor here; otherwise leave undefined. */
   columnsTwipsScale?: number;
+  /**
+   * R3: true when this plan is for a continuation page of a multi-page
+   * table (i.e. a page other than the one the table first appears on).
+   * When true, header rows from the source table are emitted in
+   * `repeatedHeaderRows` so the consumer can prepend them on render.
+   */
+  isContinuationPage?: boolean;
 }
 
 export function buildTableRenderPlan(
@@ -112,7 +119,20 @@ export function buildTableRenderPlan(
 
   const bandClasses = buildBandClasses(block.rows, resolved);
   const verticalMerges = collectVerticalMerges(block.rows);
-  const repeatedHeaderRows: RepeatedHeaderRowRef[] = [];
+  // R3: header rows are repeated on every continuation page.  When the
+  // render-plan builder is invoked for a page with `isContinuationPage`,
+  // every row with `isHeader === true` gets an entry in repeatedHeaderRows.
+  // First-page plans (or tables that fit on a single page) return an empty
+  // array.  `virtualFragmentId` is deterministic so consumers can key off it.
+  const repeatedHeaderRows: RepeatedHeaderRowRef[] = input.isContinuationPage
+    ? block.rows
+        .map((row, rowIndex) => ({ row, rowIndex }))
+        .filter(({ row }) => row.isHeader === true)
+        .map(({ rowIndex }) => ({
+          sourceRowIndex: rowIndex,
+          virtualFragmentId: `fragment-${blockId}-vheader-p${pageIndex}-r${rowIndex}`,
+        }))
+    : [];
   const columnResizeHandles = buildColumnResizeHandles(columnsTwips, tableHeightTwips);
 
   return {

package/src/runtime/numbering-prefix.ts

@@ -1,4 +1,5 @@
 import type {
+  CanonicalRunFormatting,
   NumberingCatalog,
   NumberingLevelDefinition,
   ParagraphNode,
@@ -23,6 +24,7 @@ export interface NumberingPrefixResult {
   paragraphStyleId?: string;
   isLegalNumbering?: boolean;
   geometry: ResolvedNumberingGeometry;
+  markerRunProperties?: CanonicalRunFormatting;
 }
 
 export interface NumberingPrefixResolver {
@@ -90,6 +92,9 @@ export function createNumberingPrefixResolver(
         ? { paragraphStyleId: resolved.effectiveLevel.paragraphStyleId }
         : {}),
       ...(resolved.effectiveLevel.isLegalNumbering ? { isLegalNumbering: true } : {}),
+      ...(resolved.geometry.markerRunProperties
+        ? { markerRunProperties: resolved.geometry.markerRunProperties }
+        : {}),
       geometry: resolved.geometry,
     };
   }

package/src/runtime/paragraph-style-resolver.ts

@@ -0,0 +1,194 @@
+/**
+ * Resolve style chains for paragraph and character styles by walking the
+ * `basedOn` reference, with cycle detection.
+ *
+ * Returned chains are leaf-first (most-specific style at index 0, root at the
+ * end). Cycles break at the first re-encounter. Dangling `basedOn` references
+ * stop the walk silently (the leaf is still returned).
+ *
+ * Tasks 9 and 10 extend this module with `resolveEffective*Formatting`
+ * helpers that cascade the chain into a flat formatting record.
+ */
+
+import type {
+  CanonicalParagraphFormatting,
+  CanonicalRunFormatting,
+  CharacterStyleDefinition,
+  ParagraphStyleDefinition,
+  StylesCatalog,
+} from "../model/canonical-document.ts";
+
+export function resolveParagraphStyleChain(
+  styleId: string,
+  catalog: StylesCatalog | undefined,
+): string[] {
+  const chain: string[] = [];
+  if (!catalog) return chain;
+  const visited = new Set<string>();
+  let current: string | undefined = styleId;
+  while (current && !visited.has(current)) {
+    visited.add(current);
+    const def: ParagraphStyleDefinition | undefined = catalog.paragraphs[current];
+    if (!def) break;
+    chain.push(current);
+    current = def.basedOn;
+  }
+  return chain;
+}
+
+export function resolveCharacterStyleChain(
+  styleId: string,
+  catalog: StylesCatalog | undefined,
+): string[] {
+  const chain: string[] = [];
+  if (!catalog) return chain;
+  const visited = new Set<string>();
+  let current: string | undefined = styleId;
+  while (current && !visited.has(current)) {
+    visited.add(current);
+    const def: CharacterStyleDefinition | undefined = catalog.characters[current];
+    if (!def) break;
+    chain.push(current);
+    current = def.basedOn;
+  }
+  return chain;
+}
+
+function mergeRun(
+  base: CanonicalRunFormatting | undefined,
+  over: CanonicalRunFormatting | undefined,
+): CanonicalRunFormatting | undefined {
+  if (!base && !over) return undefined;
+  return { ...(base ?? {}), ...(over ?? {}) };
+}
+
+function mergeParagraph(
+  base: CanonicalParagraphFormatting | undefined,
+  over: CanonicalParagraphFormatting | undefined,
+): CanonicalParagraphFormatting | undefined {
+  if (!base && !over) return undefined;
+  const merged: CanonicalParagraphFormatting = { ...(base ?? {}), ...(over ?? {}) };
+  if (base?.spacing || over?.spacing) {
+    merged.spacing = { ...(base?.spacing ?? {}), ...(over?.spacing ?? {}) };
+  }
+  if (base?.indentation || over?.indentation) {
+    merged.indentation = { ...(base?.indentation ?? {}), ...(over?.indentation ?? {}) };
+  }
+  if (base?.borders || over?.borders) {
+    merged.borders = { ...(base?.borders ?? {}), ...(over?.borders ?? {}) };
+  }
+  if (base?.shading || over?.shading) {
+    merged.shading = { ...(base?.shading ?? {}), ...(over?.shading ?? {}) };
+  }
+  if (base?.paragraphMarkRunProperties || over?.paragraphMarkRunProperties) {
+    merged.paragraphMarkRunProperties = mergeRun(
+      base?.paragraphMarkRunProperties,
+      over?.paragraphMarkRunProperties,
+    );
+  }
+  return merged;
+}
+
+export interface ParagraphResolveInput {
+  styleId: string | undefined;
+  direct: CanonicalParagraphFormatting | undefined;
+}
+
+/**
+ * Resolve paragraph formatting cascade: docDefaults.paragraph → basedOn chain
+ * (root-to-leaf) → direct. Returns `{}` when nothing is present.
+ */
+export function resolveEffectiveParagraphFormatting(
+  input: ParagraphResolveInput,
+  catalog: StylesCatalog | undefined,
+): CanonicalParagraphFormatting {
+  let acc: CanonicalParagraphFormatting | undefined = catalog?.docDefaults?.paragraph;
+  if (catalog && input.styleId) {
+    const chain = resolveParagraphStyleChain(input.styleId, catalog);
+    // Walk root-to-leaf (most-general first) so the most-specific style wins
+    for (let i = chain.length - 1; i >= 0; i -= 1) {
+      const styleId = chain[i]!;
+      acc = mergeParagraph(acc, catalog.paragraphs[styleId]?.paragraphProperties);
+    }
+  }
+  acc = mergeParagraph(acc, input.direct);
+  return acc ?? {};
+}
+
+export interface RunResolveInput {
+  paragraphStyleId: string | undefined;
+  characterStyleId: string | undefined;
+  direct: CanonicalRunFormatting | undefined;
+}
+
+/**
+ * Resolve run formatting cascade: docDefaults.run → paragraph-style-chain rPr
+ * (root-to-leaf) → character-style-chain (root-to-leaf) → direct. Returns
+ * `{}` when nothing is present.
+ */
+export function resolveEffectiveRunFormatting(
+  input: RunResolveInput,
+  catalog: StylesCatalog | undefined,
+): CanonicalRunFormatting {
+  let acc: CanonicalRunFormatting | undefined = catalog?.docDefaults?.run;
+  if (catalog && input.paragraphStyleId) {
+    const chain = resolveParagraphStyleChain(input.paragraphStyleId, catalog);
+    for (let i = chain.length - 1; i >= 0; i -= 1) {
+      const styleId = chain[i]!;
+      acc = mergeRun(acc, catalog.paragraphs[styleId]?.runProperties);
+    }
+  }
+  if (catalog && input.characterStyleId) {
+    const chain = resolveCharacterStyleChain(input.characterStyleId, catalog);
+    for (let i = chain.length - 1; i >= 0; i -= 1) {
+      const styleId = chain[i]!;
+      acc = mergeRun(acc, catalog.characters[styleId]?.runProperties);
+    }
+  }
+  acc = mergeRun(acc, input.direct);
+  return acc ?? {};
+}
+
+export interface MarkerResolveInput {
+  paragraphStyleId: string | undefined;
+  levelRunProperties: CanonicalRunFormatting | undefined;
+}
+
+/**
+ * Resolve the numbering marker's character formatting — the rPr that styles
+ * the number/bullet glyph itself (bold, color, font, size, etc.).
+ *
+ * Cascade order (lowest to highest priority):
+ *   1. `docDefaults.run` — Word's baseline run formatting.
+ *   2. Paragraph style chain's `runProperties` — walked root-to-leaf; the
+ *      numbered paragraph's styleId contributes each ancestor's rPr.
+ *   3. The leaf paragraph style's `paragraphProperties.paragraphMarkRunProperties`
+ *      — Word stores the paragraph-mark rPr separately from the body rPr,
+ *      and the mark's formatting is what the numbering marker inherits from.
+ *   4. `levelRunProperties` — `<w:lvl><w:rPr>` on the numbering level. Per
+ *      ECMA-376, this is the most specific formatting for the marker and
+ *      overrides the paragraph's run formatting entirely for the marker.
+ */
+export function resolveNumberingMarkerRunFormatting(
+  input: MarkerResolveInput,
+  catalog: StylesCatalog | undefined,
+): CanonicalRunFormatting {
+  // Start with docDefaults baseline
+  let acc: CanonicalRunFormatting | undefined = catalog?.docDefaults?.run;
+
+  // Walk the paragraph style chain's rPr (root-to-leaf, most-specific wins)
+  if (catalog && input.paragraphStyleId) {
+    const chain = resolveParagraphStyleChain(input.paragraphStyleId, catalog);
+    for (let i = chain.length - 1; i >= 0; i -= 1) {
+      const styleId = chain[i]!;
+      acc = mergeRun(acc, catalog.paragraphs[styleId]?.runProperties);
+    }
+    // Leaf paragraph style's paragraph-mark rPr layers on top of the chain
+    const leaf = catalog.paragraphs[input.paragraphStyleId];
+    acc = mergeRun(acc, leaf?.paragraphProperties?.paragraphMarkRunProperties);
+  }
+
+  // Level rPr has the final say (per ECMA-376 17.9)
+  acc = mergeRun(acc, input.levelRunProperties);
+  return acc ?? {};
+}