@beyondwork/docx-react-component 1.0.67 → 1.0.70

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

@@ -0,0 +1,157 @@
+/**
+ * Layer 03 — effective-formatting types.
+ *
+ * Output shapes of `resolveEffectiveFormatting`. Each type represents the
+ * post-cascade result for a given node kind — what the caller sees after
+ * the four-tier cascade + theme concretization + revision-display posture
+ * + (for paragraphs) resolved numbering have all been applied.
+ *
+ * Architecture reference: `docs/architecture/03-formatting-semantics.md`
+ * §"Entry point signature" + §"Contracts" F1–F6.
+ */
+
+import type {
+  CanonicalParagraphFormatting,
+  CanonicalRunFormatting,
+} from "../../model/canonical-document.ts";
+import type { ResolvedTableStyleResolution } from "./table-style-resolver.ts";
+
+/**
+ * Resolved paragraph formatting. Extends the canonical shape with:
+ *
+ *   - `numbering` — resolved numbering marker + geometry when the paragraph
+ *     has `paragraph.numbering?: { numberingInstanceId, level }`. Populated
+ *     by the entry's `"paragraph"` branch when a numbering context is
+ *     available (either `opts.numberingPrefixResolver` or a freshly built
+ *     one).
+ *   - `paragraphMarkRun` — the paragraph-mark rPr cascade, concretized
+ *     with theme colors when a `ThemeColorResolver` is threaded through
+ *     `opts.themeResolver`. Mirrors the canonical
+ *     `paragraphMarkRunProperties` field but carries post-cascade values
+ *     (bold/italic resolved, colorHex populated from theme slots, etc.).
+ *
+ * Extends rather than aliases `CanonicalParagraphFormatting` so callers
+ * can discriminate "post-cascade effective" from "raw canonical" at the
+ * type level — contract F1 is violated when render-path code consumes
+ * raw canonical values and re-does the cascade inline.
+ */
+export interface EffectiveParagraphFormatting extends CanonicalParagraphFormatting {
+  readonly numbering?: EffectiveNumbering;
+  readonly paragraphMarkRun?: EffectiveRunFormatting;
+}
+
+/**
+ * Resolved run formatting. Extends the canonical run shape with
+ * `revisionDisplay` — populated when `opts.revisionMarkupMode` is set
+ * AND the run has an attached revision (insertion/deletion/formatting/
+ * property-change/move).
+ *
+ * `colorHex` is post-concretization: theme slots have already been
+ * mapped through `ThemeColorResolver.resolveWordThemeColor` when a
+ * theme resolver is available. Raw `colorThemeSlot` / `colorThemeTint`
+ * / `colorThemeShade` fields are preserved for round-trip on export.
+ */
+export interface EffectiveRunFormatting extends CanonicalRunFormatting {
+  readonly revisionDisplay?: RevisionDisplayFlags;
+}
+
+export type EffectiveTableFormatting = ResolvedTableStyleResolution;
+
+/**
+ * Resolved numbering output for a paragraph with numbering context.
+ *
+ *   - `marker` — the formatted marker glyph (e.g. `"1."`, `"a)"`,
+ *     `"•"`). Produced by `NumberingPrefixResolver.resolve`.
+ *   - `level` — 0-indexed list depth (matches `<w:ilvl w:val>`).
+ *   - `markerRunFormatting` — rPr cascade for the marker glyph (ECMA-376
+ *     §17.9: docDefaults → paragraph-style chain → paragraph-mark rPr →
+ *     level rPr).
+ *   - `indentation` — merged indent + tab geometry from level def +
+ *     paragraph overrides. Consumers (layout, render) read this instead
+ *     of reading numbering level + paragraph indentation separately.
+ *   - `pictureBulletRef` — relationship id for picture-bullet glyph
+ *     when the numbering format is `"bullet"` with a pic mode.
+ */
+export interface EffectiveNumbering {
+  readonly marker?: string;
+  readonly level?: number;
+  readonly markerRunFormatting?: CanonicalRunFormatting;
+  readonly indentation?: {
+    readonly left?: number;
+    readonly hanging?: number;
+    readonly firstLine?: number;
+    readonly tab?: number;
+  };
+  readonly pictureBulletRef?: string;
+}
+
+/**
+ * Field-display output. `displayText` is the rendered string (e.g.
+ * `"1"` / `"3"` for PAGE, `"Heading 1"` for STYLEREF).
+ *
+ *   - `"resolved"` — text populated, safe to render.
+ *   - `"unresolved"` — field exists but resolution deferred (e.g. no
+ *     page graph yet; PAGE/NUMPAGES in prerender).
+ *   - `"unresolvable"` — permanent failure (e.g. REF to a missing
+ *     bookmark; STYLEREF to a non-existent style).
+ */
+export interface EffectiveFieldDisplay {
+  readonly displayText?: string;
+  readonly refreshStatus: "resolved" | "unresolved" | "unresolvable";
+}
+
+/**
+ * Revision-display posture flags applied per run. Owned by layer 03's
+ * `applyRevisionDisplay(run, revision, markupMode)`. Architecture
+ * reference: contract F6.
+ *
+ * `markupMode` echoes the input so consumers can branch without
+ * re-reading opts. Other flags are posture hints — consumers decide the
+ * visual vocabulary (CSS class, inline style, decoration).
+ */
+export interface RevisionDisplayFlags {
+  readonly markupMode: "clean" | "simple" | "all";
+  /** Hide the run entirely (e.g. open deletion in "clean" mode). */
+  readonly hidden?: boolean;
+  /** Render with strikethrough (deletion in "all" mode). */
+  readonly strikethrough?: boolean;
+  /** Render with insertion-underline (insertion in "all" mode). */
+  readonly insertionUnderline?: boolean;
+  /** Render de-emphasized (all revision kinds in "simple" mode). */
+  readonly deemphasize?: boolean;
+  /** Author color for change-bar / inline marker rendering. */
+  readonly authorColor?: string;
+}
+
+/**
+ * Discriminated union of per-node effective-formatting outputs. The
+ * entry dispatches by `nodeRef.kind` and returns the matching variant.
+ */
+export type EffectiveFormatting =
+  | {
+      readonly kind: "paragraph";
+      readonly paragraph: EffectiveParagraphFormatting;
+    }
+  | {
+      readonly kind: "run";
+      readonly run: EffectiveRunFormatting;
+    }
+  | {
+      readonly kind: "table";
+      readonly table: EffectiveTableFormatting;
+    }
+  | {
+      readonly kind: "table-cell";
+      readonly paragraph: EffectiveParagraphFormatting;
+      readonly run: EffectiveRunFormatting;
+    }
+  | {
+      readonly kind: "field";
+      readonly run: EffectiveRunFormatting;
+      readonly field: EffectiveFieldDisplay;
+    }
+  | {
+      readonly kind: "drawing-frame";
+      /** Resolved run-level formatting at the inline anchor. */
+      readonly run: EffectiveRunFormatting;
+    };

package/src/runtime/{hyperlink-color-resolver.ts → formatting/hyperlink-color.ts}

@@ -33,8 +33,8 @@
 import type {
   CanonicalRunFormatting,
   StylesCatalog,
-} from "../model/canonical-document.ts";
-import { ThemeColorResolver } from "./theme-color-resolver.ts";
+} from "../../model/canonical-document.ts";
+import { ThemeColorResolver } from "./theme-color.ts";
 import {
   resolveEffectiveRunFormatting,
   type RunResolveInput,

package/src/runtime/formatting/index.ts

@@ -0,0 +1,125 @@
+/**
+ * Layer 03 — Formatting Semantics.
+ *
+ * Canonical entry point is `resolveEffectiveFormatting`. Sub-resolvers
+ * (paragraph, table, theme-color, hyperlink-color, font-family) are
+ * re-exported here so consumers can migrate off the legacy
+ * `src/runtime/*-resolver.ts` paths; the legacy files remain as
+ * `@deprecated` shims until Slice 4.
+ */
+
+export {
+  resolveEffectiveFormatting,
+  type NodeRef,
+  type ResolveEffectiveFormattingOptions,
+} from "./resolve-effective.ts";
+
+// Production orchestrator — the real hot-path boundary. `resolveEffectiveFormatting`
+// above is a thin façade over this context for external/test callers that prefer
+// a `doc + nodeRef` API. Every in-repo production consumer goes through the
+// context directly for amortized per-document resolver construction.
+export {
+  createFormattingContext,
+  type FormattingContext,
+  type FormattingContextOptions,
+  type ProjectedRunMarks,
+  type ProjectedSurfaceMark,
+  type NumberingResolution,
+  type RunResolvedProperty,
+  type RunProvenance,
+} from "./formatting-context.ts";
+
+export type {
+  EffectiveFormatting,
+  EffectiveParagraphFormatting,
+  EffectiveRunFormatting,
+  EffectiveTableFormatting,
+  EffectiveNumbering,
+  EffectiveFieldDisplay,
+  RevisionDisplayFlags,
+} from "./formatting-types.ts";
+
+// ── Sub-resolvers ─────────────────────────────────────────────────────────
+export {
+  resolveParagraphStyleChain,
+  resolveCharacterStyleChain,
+  resolveEffectiveParagraphFormatting,
+  resolveEffectiveRunFormatting,
+  resolveNumberingMarkerRunFormatting,
+  resolveTableCellTextFormatting,
+  getNextStyleId,
+  type ParagraphResolveInput,
+  type RunResolveInput,
+  type MarkerResolveInput,
+} from "./paragraph-style-resolver.ts";
+
+export {
+  resolveTableStyleResolution,
+  type ResolvedTableCellStyle,
+  type ResolvedTableRowStyle,
+  type ResolvedTableLevelProperties,
+  type ResolvedTableStyleResolution,
+} from "./table-style-resolver.ts";
+
+export { resolveRunFontFamily } from "./font-resolution.ts";
+
+export {
+  applyThemeTintShade,
+  ThemeColorResolver,
+  concretizeThemeColors,
+  type DrawingMlColorMod,
+} from "./theme-color.ts";
+
+export { resolveHyperlinkRunFormatting } from "./hyperlink-color.ts";
+
+export { mergeRun, mergeParagraph } from "./style-cascade.ts";
+
+// ── Numbering (Slice 3) ───────────────────────────────────────────────────
+export {
+  createNumberingPrefixResolver,
+  formatCounter,
+  isSupportedNumberingFormat,
+  type NumberingPrefixResolver,
+  type NumberingPrefixResult,
+} from "./numbering/prefix.ts";
+
+export {
+  resolveNumberingDefinitionSet,
+  DEFAULT_NUMBERING_START_AT,
+  type ResolvedNumberingGeometry,
+  type ResolvedNumberingDefinitionSet,
+} from "./numbering/geometry.ts";
+
+// ── Fields (Slice 3) ──────────────────────────────────────────────────────
+export {
+  createFieldResolver,
+  type FieldResolver,
+  type FieldResolverInput,
+  type ResolvedField,
+  type DocumentContainerNode,
+} from "./field/resolver.ts";
+
+export { formatPageNumber } from "./field/page-number-format.ts";
+
+export { rebuildFieldRegistry } from "./field/registry.ts";
+
+// ── Debug projector (Slice 3) ─────────────────────────────────────────────
+export {
+  buildFormattingDebugEntry,
+  type FormattingDebugEntry,
+} from "./projector.ts";
+
+// ── Revision display (Slice 4) ────────────────────────────────────────────
+export {
+  applyRevisionDisplay,
+  type RevisionMarkupMode,
+} from "./revision-display.ts";
+
+// ── Telemetry bridge (Phase C3) ───────────────────────────────────────────
+export {
+  buildFormattingTelemetryBridge,
+  emitRevisionDisplayModeChanged,
+  type FormattingTelemetryBridgeOptions,
+} from "./telemetry-bridge.ts";
+
+export type { FormattingTelemetryEvent } from "./resolve-effective.ts";

package/src/runtime/{resolved-numbering-geometry.ts → formatting/numbering/geometry.ts}

@@ -8,7 +8,7 @@ import type {
   ParagraphNode,
   ParagraphSpacing,
   TabStop,
-} from "../model/canonical-document.ts";
+} from "../../../model/canonical-document.ts";
 
 export const DEFAULT_NUMBERING_START_AT = 1;
 

package/src/runtime/{numbering-prefix.ts → formatting/numbering/prefix.ts}

@@ -3,12 +3,12 @@ import type {
   NumberingCatalog,
   NumberingLevelDefinition,
   ParagraphNode,
-} from "../model/canonical-document.ts";
+} from "../../../model/canonical-document.ts";
 import {
   DEFAULT_NUMBERING_START_AT,
   resolveNumberingDefinitionSet,
   type ResolvedNumberingGeometry,
-} from "./resolved-numbering-geometry.ts";
+} from "./geometry.ts";
 
 interface NumberingSequenceState {
   counters: Array<number | undefined>;
@@ -221,7 +221,43 @@ function renderLevelText(
   return rendered.trim().length > 0 ? rendered : null;
 }
 
-function formatCounter(value: number, format: string): string {
+/**
+ * Formats the runtime has dedicated implementations for. Anything outside
+ * this set falls through to `decimal` — documented dishonestly-silent
+ * behavior pending ECMA-376 §17.9.7 full coverage. L03 audit
+ * (2026-04-22) tracks this as Task-5. When a format NOT in this set
+ * is requested, we still return `String(value)` so user-visible
+ * rendering doesn't collapse, but consumers should treat unknown
+ * formats as a fidelity gap.
+ */
+const SUPPORTED_NUMBERING_FORMATS = new Set<string>([
+  "decimal",
+  "decimalZero",
+  "upperLetter",
+  "lowerLetter",
+  "upperRoman",
+  "lowerRoman",
+  "hex",
+  "ordinal",
+  "cardinalText",
+  "ordinalText",
+  "chicago",
+  "bullet",
+  "none",
+]);
+
+export function isSupportedNumberingFormat(format: string): boolean {
+  return SUPPORTED_NUMBERING_FORMATS.has(format);
+}
+
+/**
+ * Internal helper exported for targeted testing. Consumers should drive
+ * the full `createNumberingPrefixResolver(catalog).resolveParagraph(...)`
+ * path in production code — this raw entry exists so parity tests can
+ * assert format-by-format behavior without constructing a full
+ * `NumberingCatalog`.
+ */
+export function formatCounter(value: number, format: string): string {
   switch (format) {
     case "decimal":
       return String(value);
@@ -235,13 +271,60 @@ function formatCounter(value: number, format: string): string {
       return toRoman(value).toUpperCase();
     case "lowerRoman":
       return toRoman(value).toLowerCase();
+    case "hex":
+      // ECMA-376 §17.9.7: hexadecimal numbering. Uppercase matches
+      // Word's rendered output on round-tripped documents.
+      return value >= 0 ? value.toString(16).toUpperCase() : String(value);
+    case "ordinal":
+      // ECMA-376 §17.9.7: English ordinal suffix. 11/12/13 are the
+      // special cases that take "th" regardless of last digit.
+      return toOrdinal(value);
+    case "cardinalText":
+      // ECMA-376 §17.9.7: English cardinal-word numbering. Coverage is
+      // 1–999; values outside fall through to decimal (String(value)).
+      return toCardinalText(value);
+    case "ordinalText":
+      // ECMA-376 §17.9.7: English ordinal-word numbering.
+      return toOrdinalText(value);
+    case "chicago":
+      // ECMA-376 §17.9.7: Chicago-manual-style symbol cycle. *, †, ‡,
+      // §, ‖, ¶, then each doubles for the 7–12 pass, triples for
+      // 13–18, and so on.
+      return toChicago(value);
+    case "bullet":
+      // ECMA-376 §17.9.7: bullet numbering — level.text carries the
+      // literal glyph (or picture-bullet reference). `%1` placeholders
+      // must interpolate to "" so the glyph is the only visible
+      // output; matches the `none` behavior.
+      return "";
     case "none":
       return "";
     default:
+      // Unsupported format — fall through to decimal for visible output.
+      // Callers that care about fidelity should gate on
+      // `isSupportedNumberingFormat(format)` first.
       return String(value);
   }
 }
 
+function toOrdinal(value: number): string {
+  if (value <= 0) return String(value);
+  const lastTwo = value % 100;
+  const lastOne = value % 10;
+  // Teens: 11th, 12th, 13th (not 11st/12nd/13rd).
+  if (lastTwo >= 11 && lastTwo <= 13) return `${value}th`;
+  switch (lastOne) {
+    case 1:
+      return `${value}st`;
+    case 2:
+      return `${value}nd`;
+    case 3:
+      return `${value}rd`;
+    default:
+      return `${value}th`;
+  }
+}
+
 function toAlphabetic(value: number): string {
   if (value <= 0) {
     return String(value);
@@ -288,3 +371,87 @@ function toRoman(value: number): string {
   }
   return result;
 }
+
+// ---------------------------------------------------------------------------
+// ECMA-376 §17.9.7 English number-word helpers (cardinalText / ordinalText).
+// Coverage is 1–999; values outside the supported range fall through to
+// `String(value)` so rendered output is never empty. Callers that care
+// about fidelity beyond 999 should gate on the value range before invoking
+// these formats.
+// ---------------------------------------------------------------------------
+
+const ONES_CARDINAL = [
+  "", "one", "two", "three", "four", "five", "six", "seven", "eight", "nine",
+  "ten", "eleven", "twelve", "thirteen", "fourteen", "fifteen", "sixteen",
+  "seventeen", "eighteen", "nineteen",
+] as const;
+
+const TENS_CARDINAL = [
+  "", "", "twenty", "thirty", "forty", "fifty", "sixty", "seventy", "eighty",
+  "ninety",
+] as const;
+
+function toCardinalText(value: number): string {
+  if (!Number.isInteger(value) || value < 1 || value > 999) return String(value);
+  return cardinalBelowThousand(value);
+}
+
+function cardinalBelowThousand(value: number): string {
+  if (value < 20) return ONES_CARDINAL[value]!;
+  if (value < 100) {
+    const tens = Math.floor(value / 10);
+    const rest = value % 10;
+    return rest === 0
+      ? TENS_CARDINAL[tens]!
+      : `${TENS_CARDINAL[tens]}-${ONES_CARDINAL[rest]}`;
+  }
+  const hundreds = Math.floor(value / 100);
+  const rest = value % 100;
+  const base = `${ONES_CARDINAL[hundreds]} hundred`;
+  if (rest === 0) return base;
+  return `${base} ${cardinalBelowThousand(rest)}`;
+}
+
+// Standalone ordinal-word map for ones 1–19 where the ordinal differs from
+// the cardinal (e.g. "one" → "first", not "oneth").
+const ONES_ORDINAL = [
+  "", "first", "second", "third", "fourth", "fifth", "sixth", "seventh",
+  "eighth", "ninth", "tenth", "eleventh", "twelfth", "thirteenth",
+  "fourteenth", "fifteenth", "sixteenth", "seventeenth", "eighteenth",
+  "nineteenth",
+] as const;
+
+// Tens endings (20 → "twentieth", 30 → "thirtieth", …). Standalone decades
+// swap their trailing `y` for `ieth`.
+const TENS_ORDINAL = [
+  "", "", "twentieth", "thirtieth", "fortieth", "fiftieth", "sixtieth",
+  "seventieth", "eightieth", "ninetieth",
+] as const;
+
+function toOrdinalText(value: number): string {
+  if (!Number.isInteger(value) || value < 1 || value > 999) return String(value);
+  if (value < 20) return ONES_ORDINAL[value]!;
+  if (value < 100) {
+    const tens = Math.floor(value / 10);
+    const rest = value % 10;
+    return rest === 0
+      ? TENS_ORDINAL[tens]!
+      : `${TENS_CARDINAL[tens]}-${ONES_ORDINAL[rest]}`;
+  }
+  const hundreds = Math.floor(value / 100);
+  const rest = value % 100;
+  if (rest === 0) return `${ONES_CARDINAL[hundreds]} hundredth`;
+  return `${ONES_CARDINAL[hundreds]} hundred ${toOrdinalText(rest)}`;
+}
+
+// ECMA-376 §17.9.7 chicago cycle. 6-symbol sequence; each pass through the
+// cycle repeats the symbol once more. Value 1 → "*", 6 → "¶", 7 → "**",
+// 12 → "¶¶", 13 → "***", etc. Non-positive values fall through to decimal.
+const CHICAGO_GLYPHS = ["*", "†", "‡", "§", "‖", "¶"] as const;
+
+function toChicago(value: number): string {
+  if (!Number.isInteger(value) || value < 1) return String(value);
+  const index = (value - 1) % CHICAGO_GLYPHS.length;
+  const repeat = Math.floor((value - 1) / CHICAGO_GLYPHS.length) + 1;
+  return CHICAGO_GLYPHS[index]!.repeat(repeat);
+}

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

@@ -0,0 +1,92 @@
+/**
+ * Paragraph + character style chain walkers.
+ *
+ * Owns ONLY the `basedOn`-chain traversal functions
+ * (`resolveParagraphStyleChain`, `resolveCharacterStyleChain`) and the small
+ * utility `getNextStyleId`. The four-tier cascade drivers
+ * (`resolveEffective*Formatting`, `resolveNumberingMarkerRunFormatting`,
+ * `resolveTableCellTextFormatting`) and the merge primitives live in
+ * `./style-cascade.ts`; they are re-exported here for back-compat with
+ * consumers migrating off the legacy import path.
+ *
+ * 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).
+ */
+
+import type {
+  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;
+}
+
+/**
+ * Return the `w:next` style ID for `styleId` — the paragraph style Word
+ * applies after pressing Enter at the end of a paragraph of this style.
+ */
+export function getNextStyleId(
+  styleId: string,
+  catalog: StylesCatalog | undefined,
+): string | undefined {
+  return catalog?.paragraphs[styleId]?.nextStyle;
+}
+
+// ---------------------------------------------------------------------------
+// Back-compat re-exports
+//
+// The cascade drivers + merge primitives moved to `./style-cascade.ts` in
+// Phase B1 of the layer-03 refactor (completes the Slice-2 "four-tier
+// cascade core extract" plan row). Re-exported here so consumers that
+// import from `paragraph-style-resolver.ts` continue to compile during
+// the Phase-D consumer migration.
+// ---------------------------------------------------------------------------
+
+export {
+  resolveEffectiveParagraphFormatting,
+  resolveEffectiveRunFormatting,
+  resolveNumberingMarkerRunFormatting,
+  resolveTableCellTextFormatting,
+  mergeParagraph,
+  mergeRun,
+  type ParagraphResolveInput,
+  type RunResolveInput,
+  type MarkerResolveInput,
+} from "./style-cascade.ts";
+
+export { resolveRunFontFamily } from "./font-resolution.ts";

package/src/runtime/formatting/projector.ts

@@ -0,0 +1,75 @@
+/**
+ * Layer 03 — formatting debug projector.
+ *
+ * Produces a `FormattingDebugEntry` for the debug-inspector snapshot when
+ * the `formatting` telemetry channel is on. Architecture reference:
+ * docs/architecture/03-formatting-semantics.md §"Projector and oracle surfaces".
+ *
+ * The projector is strict about cost: when the `formatting` channel is
+ * off, consumers must not call `buildFormattingDebugEntry`. The channel
+ * toggle lives on the telemetry bus; callers gate the call through
+ * `bus.isEnabled("formatting")` before paying the summary cost.
+ *
+ * Slice 3 lands the minimum-viable summary: catalog population, cascade
+ * cache-hit counters, and a probability-gated sample of the last N
+ * resolutions. Slice 4 extends it with revision-display posture counts.
+ */
+
+import type { CanonicalDocument } from "../../model/canonical-document.ts";
+
+export interface FormattingCatalogSummary {
+  readonly paragraphStyles: number;
+  readonly characterStyles: number;
+  readonly tableStyles: number;
+  readonly numberingInstances: number;
+  readonly numberingAbstracts: number;
+  readonly hasTheme: boolean;
+  readonly hasFontTable: boolean;
+}
+
+export interface FormattingResolutionSample {
+  readonly t: number;
+  readonly kind:
+    | "paragraph"
+    | "run"
+    | "table"
+    | "table-cell"
+    | "field"
+    | "drawing-frame";
+  readonly blockId: string;
+  readonly resolvedStyleChainDepth?: number;
+}
+
+export interface FormattingDebugEntry {
+  readonly schemaVersion: 1;
+  readonly catalog: FormattingCatalogSummary;
+  readonly revisionMarkupMode?: "clean" | "simple" | "all";
+  readonly recentSamples: readonly FormattingResolutionSample[];
+}
+
+export interface BuildFormattingDebugEntryInputs {
+  readonly doc: CanonicalDocument;
+  readonly revisionMarkupMode?: "clean" | "simple" | "all";
+  readonly recentSamples?: readonly FormattingResolutionSample[];
+}
+
+export function buildFormattingDebugEntry(
+  inputs: BuildFormattingDebugEntryInputs,
+): FormattingDebugEntry {
+  const { doc, revisionMarkupMode, recentSamples } = inputs;
+  const catalog: FormattingCatalogSummary = {
+    paragraphStyles: Object.keys(doc.styles.paragraphs ?? {}).length,
+    characterStyles: Object.keys(doc.styles.characters ?? {}).length,
+    tableStyles: Object.keys(doc.styles.tables ?? {}).length,
+    numberingInstances: Object.keys(doc.numbering?.instances ?? {}).length,
+    numberingAbstracts: Object.keys(doc.numbering?.abstractDefinitions ?? {}).length,
+    hasTheme: Boolean(doc.subParts?.canonicalTheme),
+    hasFontTable: Boolean(doc.fontTable),
+  };
+  return {
+    schemaVersion: 1,
+    catalog,
+    revisionMarkupMode,
+    recentSamples: recentSamples ?? [],
+  };
+}