@beyondwork/docx-react-component 1.0.67 → 1.0.70

package/src/runtime/surface-projection.ts

@@ -48,24 +48,27 @@ import {
   isBlockedImportFeatureKey,
 } from "../preservation/store.ts";
 import { getStoryBlocks } from "./story-targeting.ts";
-import {
-  createNumberingPrefixResolver,
-  type NumberingPrefixResult,
-  type NumberingPrefixResolver,
-} from "./numbering-prefix.ts";
 import {
   collectSectionContexts,
   findHeaderFooterDocumentEntry,
   resolveSectionVariants,
 } from "./story-context.ts";
-import { resolveTableStyleResolution } from "./table-style-resolver.ts";
+// L03 boundary: surface-projection owns PROJECTION, not formatting semantics.
+// Every formatting resolution goes through `FormattingContext` — the
+// production hot-path entry point for Layer 03. Scattered sub-resolver
+// calls are rejected by `scripts/ci-check-formatting-production-boundary.mjs`.
 import {
-  resolveEffectiveParagraphFormatting,
-  resolveEffectiveRunFormatting,
-  resolveNumberingMarkerRunFormatting,
-} from "./paragraph-style-resolver.ts";
-import { resolveHyperlinkRunFormatting } from "./hyperlink-color-resolver.ts";
-import { concretizeThemeColors, ThemeColorResolver } from "./theme-color-resolver.ts";
+  createFormattingContext,
+  type FormattingContext,
+  type NumberingResolution,
+} from "./formatting/formatting-context.ts";
+import { isSupportedNumberingFormat } from "./formatting/numbering/prefix.ts";
+import type { FormattingTelemetryEvent } from "./formatting/resolve-effective.ts";
+// The ThemeColorResolver type is still exposed to a handful of helper
+// callsites below (shading, cell fill) that accept a pre-built resolver.
+// Surface-projection no longer constructs one — it reads
+// `formattingContext.theme` instead.
+import type { ThemeColorResolver } from "./formatting/theme-color.ts";
 import type { CanonicalParagraphFormatting, CanonicalRunFormatting } from "../model/canonical-document.ts";
 
 const SAFE_CSS_HEX_COLOR_RE = /^#?(?:[0-9A-Fa-f]{3}|[0-9A-Fa-f]{4}|[0-9A-Fa-f]{6}|[0-9A-Fa-f]{8})$/;
@@ -93,6 +96,48 @@ interface ParagraphAccumulator {
 
 export interface SurfaceProjectionOptions {
   viewportBlockRange?: { start: number; end: number } | null;
+  /**
+   * Active markup mode. When set together with the document's
+   * `review.revisions`, surface-projection tags each text segment whose
+   * offset falls inside a revision's anchor range with
+   * `segment.revisionDisplay` flags via `FormattingContext`.
+   *
+   * Architecture §F6: the layer applies the markup-mode decision (from
+   * UI / session capabilities); it does not decide it. When absent,
+   * segments carry no `revisionDisplay` field and the legacy decoration
+   * path continues to own rendering (back-compat during consumer
+   * migration).
+   */
+  revisionMarkupMode?: "clean" | "simple" | "all";
+  /**
+   * Live markup-mode callback. When set, wins over `revisionMarkupMode`
+   * on each projection pass — the composition site (L10
+   * `ui.viewport.getEffectiveMarkupMode()`) updates the rendered posture
+   * without re-parsing the document. Returning `undefined` means "no
+   * posture this pass". See `03-formatting-semantics.md` §F6.
+   */
+  getEffectiveMarkupMode?: () => "clean" | "simple" | "all" | undefined;
+  /**
+   * Author-id → color palette for revision-display posture. Consumed by
+   * `FormattingContext.resolveRunFromMarks({revision})` via the layer's
+   * `applyRevisionDisplay` function when the active revision carries an
+   * `authorId`.
+   */
+  authorColorPalette?: ReadonlyMap<string, string>;
+  /**
+   * Emit callback for L03 formatting telemetry. Bridges the numbering
+   * format-coverage gap (`formatting.numbering_format_unsupported`) onto
+   * the runtime telemetry bus when the document resolves a numbering
+   * level whose format is not in `SUPPORTED_NUMBERING_FORMATS` — the
+   * fallback path still renders `String(value)` so output is unchanged,
+   * but agents + the debug pane see the fidelity gap.
+   *
+   * Typically wired via `buildFormattingTelemetryBridge(handle.debug.bus)`
+   * in `src/runtime/formatting/telemetry-bridge.ts`. Surface-projection
+   * deduplicates emissions per `(numberingInstanceId, level, format)`
+   * tuple within a single projection pass.
+   */
+  emitFormattingTelemetry?: (event: FormattingTelemetryEvent) => void;
 }
 
 export function createEditorSurfaceSnapshot(
@@ -108,7 +153,25 @@ export function createEditorSurfaceSnapshot(
   });
   const blocks: SurfaceBlockSnapshot[] = [];
   const lockedFragmentIds: string[] = [];
-  const numberingPrefixResolver = createNumberingPrefixResolver(document.numbering);
+  // L03 boundary: construct one formatting context per projection pass.
+  // The context owns the theme resolver + numbering prefix counter +
+  // style catalog walks. Surface-projection delegates every formatting
+  // semantics question to it and keeps only projection concerns
+  // (id synthesis, viewport culling, chart/image metadata).
+  const formattingContext = createFormattingContext(document, {
+    ...(options.revisionMarkupMode ? { revisionMarkupMode: options.revisionMarkupMode } : {}),
+    ...(options.getEffectiveMarkupMode
+      ? { getEffectiveMarkupMode: options.getEffectiveMarkupMode }
+      : {}),
+    ...(options.authorColorPalette ? { authorColorPalette: options.authorColorPalette } : {}),
+  });
+  // L03 §F6: revision range index is owned by `FormattingContext`
+  // itself when `revisionMarkupMode` is set. Surface-projection calls
+  // `formattingContext.findRevisionAtRange(from, to)` per segment to
+  // look up the attached revision + passes it to
+  // `formattingContext.resolveRunFromMarks({revision})`. The layer
+  // applies the posture; surface-projection just carries the flags
+  // through to `segment.revisionDisplay`.
   // Open a chartModelStore build pass tagged with the document envelope.
   // Every `chart_preview` node populated during the pass records its id
   // in the pass's seen-set; `endBuildPass()` below evicts store entries
@@ -116,6 +179,14 @@ export function createEditorSurfaceSnapshot(
   // earlier builds (same owner, not seen this pass). Previously the
   // store grew unbounded across document loads — documented v1 gap.
   chartModelStore.beginBuildPass(document);
+  // Per-pass dedup set for L03 `formatting.numbering_format_unsupported`
+  // emissions. Keys are `"${numberingInstanceId}|${level}|${format}"`.
+  // Only populated when the caller wires `emitFormattingTelemetry` —
+  // otherwise zero cost.
+  const unsupportedNumberingFormatsSeen: Set<string> | null = options
+    .emitFormattingTelemetry
+    ? new Set<string>()
+    : null;
   let cursor = 0;
   const counters = {
     paragraph: 0,
@@ -143,7 +214,7 @@ export function createEditorSurfaceSnapshot(
       document,
       cursor,
       counters,
-      numberingPrefixResolver,
+      formattingContext,
       activeStory.kind !== "main",
       !isInViewport,
     );
@@ -178,7 +249,7 @@ export function createEditorSurfaceSnapshot(
     }
   }
 
-  const secondaryStories = createSecondaryStorySurfaces(document, numberingPrefixResolver);
+  const secondaryStories = createSecondaryStorySurfaces(document, formattingContext);
 
   // Close the chartModelStore build pass. Evicts entries from previous
   // documents + stale entries whose ids no longer appear in the current
@@ -186,6 +257,36 @@ export function createEditorSurfaceSnapshot(
   // chart_preview nodes).
   chartModelStore.endBuildPass();
 
+  // L03 Task A3 item 5 — emit `formatting.numbering_format_unsupported`
+  // once per unique `(numberingInstanceId, level, format)` tuple when
+  // the resolved format is outside `SUPPORTED_NUMBERING_FORMATS`. The
+  // rendered output is unchanged (fallback is `String(value)`); this
+  // signal exposes the fidelity gap to agents + the debug pane without
+  // changing behavior. Zero cost when the caller does not wire
+  // `emitFormattingTelemetry`.
+  if (
+    options.emitFormattingTelemetry !== undefined &&
+    unsupportedNumberingFormatsSeen !== null
+  ) {
+    for (const block of blocks) {
+      if (block.kind !== "paragraph") continue;
+      if (!block.resolvedNumbering || !block.numbering) continue;
+      const fmt = block.resolvedNumbering.format;
+      if (isSupportedNumberingFormat(fmt)) continue;
+      const key = `${block.numbering.numberingInstanceId}|${block.resolvedNumbering.level}|${fmt}`;
+      if (unsupportedNumberingFormatsSeen.has(key)) continue;
+      unsupportedNumberingFormatsSeen.add(key);
+      options.emitFormattingTelemetry({
+        type: "formatting.numbering_format_unsupported",
+        payload: {
+          format: fmt,
+          numberingInstanceId: block.numbering.numberingInstanceId,
+          level: block.resolvedNumbering.level,
+        },
+      });
+    }
+  }
+
   return {
     storySize: cursor,
     plainText: createPlainText(blocks),
@@ -208,7 +309,7 @@ function createSurfaceBlock(
     customXml: number;
     altChunk: number;
   },
-  numberingPrefixResolver: NumberingPrefixResolver,
+  formattingContext: FormattingContext,
   promoteSecondaryStoryTextBoxes: boolean,
   cullBuild: boolean = false,
 ): { block: SurfaceBlockSnapshot; lockedFragmentIds: string[]; nextCursor: number } {
@@ -249,7 +350,7 @@ function createSurfaceBlock(
       document,
       cursor,
       counters,
-      numberingPrefixResolver,
+      formattingContext,
       promoteSecondaryStoryTextBoxes,
       cullBuild,
     );
@@ -289,7 +390,7 @@ function createSurfaceBlock(
       document,
       cursor,
       counters,
-      numberingPrefixResolver,
+      formattingContext,
       promoteSecondaryStoryTextBoxes,
       cullBuild,
     );
@@ -382,7 +483,7 @@ function createSurfaceBlock(
     block,
     document,
     cursor,
-    numberingPrefixResolver,
+    formattingContext,
     promoteSecondaryStoryTextBoxes,
     cullBuild,
   );
@@ -401,7 +502,7 @@ function createTableBlock(
     customXml: number;
     altChunk: number;
   },
-  numberingPrefixResolver: NumberingPrefixResolver,
+  formattingContext: FormattingContext,
   promoteSecondaryStoryTextBoxes: boolean,
   cullBuild: boolean = false,
 ): { block: SurfaceBlockSnapshot; lockedFragmentIds: string[]; nextCursor: number } {
@@ -409,13 +510,11 @@ function createTableBlock(
   let innerCursor = cursor;
   const rows: SurfaceTableRowSnapshot[] = [];
   const rowSpans = computeTableRowSpans(table);
-  const resolvedTable = resolveTableStyleResolution(table, document.styles.tables);
-  // SOW gap G3 — build the theme color resolver once per table so every cell
-  // shading with `w:themeFill` can resolve the theme slot + tint/shade without
-  // reconstructing the resolver per cell.
-  const tableThemeResolver = document.subParts?.canonicalTheme
-    ? new ThemeColorResolver(document.subParts.canonicalTheme)
-    : undefined;
+  // L03 boundary: the table-style cascade + theme resolver come from the
+  // projection-pass-scoped formatting context so every block in the pass
+  // shares one cached theme resolver.
+  const resolvedTable = formattingContext.resolveTable(table);
+  const tableThemeResolver = formattingContext.theme;
 
   // SOW gap G5 — fold table-level borders into per-cell rendering. The CCEP
   // SOW form tables ship only `w:tblBorders` (single sz=4 on every side + insideH
@@ -449,7 +548,7 @@ function createTableBlock(
           document,
           innerCursor,
           counters,
-          numberingPrefixResolver,
+          formattingContext,
           promoteSecondaryStoryTextBoxes,
           cullBuild,
         );
@@ -841,7 +940,7 @@ function createSdtBlock(
     customXml: number;
     altChunk: number;
   },
-  numberingPrefixResolver: NumberingPrefixResolver,
+  formattingContext: FormattingContext,
   promoteSecondaryStoryTextBoxes: boolean,
   cullBuild: boolean = false,
 ): { block: SurfaceBlockSnapshot; lockedFragmentIds: string[]; nextCursor: number } {
@@ -855,7 +954,7 @@ function createSdtBlock(
       document,
       innerCursor,
       counters,
-      numberingPrefixResolver,
+      formattingContext,
       promoteSecondaryStoryTextBoxes,
       cullBuild,
     );
@@ -891,7 +990,7 @@ function createParagraphBlock(
   paragraph: ParagraphNode,
   document: CanonicalDocumentEnvelope,
   start: number,
-  numberingPrefixResolver: NumberingPrefixResolver,
+  formattingContext: FormattingContext,
   promoteSecondaryStoryTextBoxes: boolean,
   cullBuild: boolean = false,
 ): {
@@ -899,51 +998,40 @@ function createParagraphBlock(
   nextCursor: number;
   lockedFragmentIds: string[];
 } {
-  const themeResolver = document.subParts?.canonicalTheme
-    ? new ThemeColorResolver(document.subParts.canonicalTheme)
-    : undefined;
+  // L03 boundary: the formatting context owns the theme resolver +
+  // numbering counter + style-catalog walks. Surface-projection reads
+  // `formattingContext.theme` (constructed once per projection pass)
+  // and delegates every formatting semantics question to the context.
+  const themeResolver = formattingContext.theme;
   // L7 Phase 2.9 — viewport bail. When the paragraph is outside the
   // viewport, the returned block is discarded (the outer caller in
   // `createEditorSurfaceSnapshot` replaces it with a placeholder-culled
-  // entry and only consumes `nextCursor`). Skip the two style-catalog
-  // walks (`resolveEffectiveParagraphFormatting`,
-  // `resolveNumberingMarkerRunFormatting`) — their results are not read
-  // by the placeholder path. Segment-level work inside
-  // `appendInlineSegments` is suppressed symmetrically via the same
-  // `cullBuild` flag, preserving cursor arithmetic.
-  // Always resolve numbering so the counter advances for culled paragraphs too.
-  const effectiveNumbering = resolveEffectiveParagraphNumbering(document, paragraph);
-  const resolvedNumbering =
-    !cullBuild && effectiveNumbering
-      ? numberingPrefixResolver.resolveDetailed(effectiveNumbering, paragraph)
-      : effectiveNumbering
-        ? advanceNumberingCounterOnly(numberingPrefixResolver, effectiveNumbering)
-        : null;
-
-  // Task 11: compute cascaded paragraph formatting (expensive — styles-catalog walk).
-  const stylesCatalog = document.styles;
-  const directParagraphFormatting = cullBuild
-    ? undefined
-    : buildDirectParagraphFormattingFromNode(paragraph);
+  // entry and only consumes `nextCursor`). The context's numbering
+  // counter is always advanced so state stays correct for culled
+  // paragraphs; the paragraph cascade + marker rPr walks are skipped.
+  const effectiveNumbering = formattingContext.resolveEffectiveParagraphNumbering(paragraph);
+  let resolvedNumbering: NumberingResolution | null = null;
+  if (effectiveNumbering) {
+    if (!cullBuild) {
+      resolvedNumbering = formattingContext.resolveParagraphNumbering(paragraph);
+    } else {
+      // Counter-advance only for the culled path.
+      formattingContext.numbering.resolve(effectiveNumbering);
+    }
+  }
+
   const resolvedParagraphFormatting = cullBuild
     ? undefined
-    : resolveEffectiveParagraphFormatting(
-        { styleId: paragraph.styleId, direct: directParagraphFormatting },
-        stylesCatalog,
-      );
+    : formattingContext.resolveParagraphCascade(paragraph);
   const surfaceResolvedParagraphFormatting = resolvedParagraphFormatting
     ? resolveSurfaceParagraphFormatting(resolvedParagraphFormatting, themeResolver)
     : undefined;
 
-  // Task 11: compute cascaded marker run formatting (expensive).
   const markerRunProperties =
     !cullBuild && effectiveNumbering
-      ? resolveNumberingMarkerRunFormatting(
-          {
-            paragraphStyleId: paragraph.styleId,
-            levelRunProperties: resolvedNumbering?.markerRunProperties,
-          },
-          stylesCatalog,
+      ? formattingContext.resolveNumberingMarkerRunFormatting(
+          paragraph.styleId,
+          resolvedNumbering?.markerRunProperties,
         )
       : undefined;
 
@@ -1009,6 +1097,7 @@ function createParagraphBlock(
       undefined,
       cullBuild,
       themeResolver,
+      formattingContext,
     );
     cursor = result.nextCursor;
     lockedFragmentIds.push(...result.lockedFragmentIds);
@@ -1022,155 +1111,14 @@ function createParagraphBlock(
   };
 }
 
-function advanceNumberingCounterOnly(
-  resolver: NumberingPrefixResolver,
-  numbering: NonNullable<ParagraphNode["numbering"]>,
-): null {
-  resolver.resolve(numbering);
-  return null;
-}
-
-function resolveEffectiveParagraphNumbering(
-  document: CanonicalDocumentEnvelope,
-  paragraph: ParagraphNode,
-): ParagraphNode["numbering"] | undefined {
-  if (paragraph.numbering) {
-    return paragraph.numbering;
-  }
-  if (!paragraph.styleId) {
-    return undefined;
-  }
-
-  const paragraphStyles = document.styles?.paragraphs ?? {};
-  const styleChain = collectParagraphStyleChain(document, paragraph.styleId);
-  let styleNumbering:
-    | CanonicalDocumentEnvelope["styles"]["paragraphs"][string]["numbering"]
-    | 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(
-    document,
-    styleNumbering.numberingInstanceId,
-    styleChain,
-  );
-  return resolvedLevel !== undefined
-    ? {
-        numberingInstanceId: styleNumbering.numberingInstanceId,
-        level: resolvedLevel,
-      }
-    : undefined;
-}
-
-function collectParagraphStyleChain(
-  document: CanonicalDocumentEnvelope,
-  styleId: string,
-): string[] {
-  const paragraphStyles = document.styles?.paragraphs ?? {};
-  const chain: string[] = [];
-  const visited = new Set<string>();
-  let currentStyleId: string | undefined = styleId;
-
-  while (currentStyleId && !visited.has(currentStyleId)) {
-    visited.add(currentStyleId);
-    chain.push(currentStyleId);
-    currentStyleId = paragraphStyles[currentStyleId]?.basedOn;
-  }
-
-  return chain;
-}
-
-function resolveStyleLinkedNumberingLevel(
-  document: CanonicalDocumentEnvelope,
-  numberingInstanceId: string,
-  styleChain: readonly string[],
-): number | undefined {
-  const instance = document.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 = document.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 buildDirectRunFormattingFromMarks(
-  marks: SurfaceTextMark[] | undefined,
-  markAttrs: {
-    backgroundColor?: string;
-    charSpacing?: number;
-    kerning?: number;
-    textFill?: string;
-    fontFamily?: string;
-    fontSize?: number;
-    textColor?: string;
-  } | undefined,
-): CanonicalRunFormatting | undefined {
-  const direct: CanonicalRunFormatting = {};
-  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;
-  }
-  if (markAttrs) {
-    if (markAttrs.fontFamily) {
-      direct.fontFamily = markAttrs.fontFamily;
-      direct.fontFamilyAscii = markAttrs.fontFamily;
-    }
-    if (typeof markAttrs.fontSize === "number") {
-      // markAttrs.fontSize is already in half-points from cloneMarks
-      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;
-}
+// `advanceNumberingCounterOnly`, `resolveEffectiveParagraphNumbering`,
+// `collectParagraphStyleChain`, `resolveStyleLinkedNumberingLevel`, and
+// `buildDirectRunFormattingFromMarks` were removed from surface-projection
+// in the Layer-03 production-boundary migration. Their behavior now lives
+// on `FormattingContext` (`resolveEffectiveParagraphNumbering`,
+// `resolveParagraphNumbering`, `resolveRunFromMarks`, and the internal
+// `resolveStyleLinkedNumberingLevel` in `formatting-context.ts`). Surface-
+// projection owns projection concerns only.
 
 function appendInlineSegments(
   paragraph: ParagraphAccumulator,
@@ -1181,58 +1129,70 @@ function appendInlineSegments(
   hyperlinkHref?: string,
   cullBuild: boolean = false,
   themeResolver?: ThemeColorResolver,
+  formattingContext?: FormattingContext,
 ): { nextCursor: number; lockedFragmentIds: string[] } {
   switch (node.type) {
     case "text": {
       const cloned = node.marks ? cloneMarks(node.marks) : { marks: [] as SurfaceTextMark[] };
-      // L7 Phase 2.9 — skip the styles-catalog run-cascade walk when
-      // the block will be culled. `resolveEffectiveRunFormatting`
-      // dominates per-text-segment cost on style-heavy docs; the
-      // placeholder path does not read `resolvedRunFormatting`.
-      const directRunFormatting = cullBuild
-        ? undefined
-        : buildDirectRunFormattingFromMarks(
-            cloned.marks.length > 0 ? cloned.marks : undefined,
-            cloned.markAttrs,
-          );
-      // V7 — runs inside <w:hyperlink> go through the hyperlink color
-      // cascade (auto-applies the Hyperlink character style + resolves
-      // theme hlink slot with Word-default fallback). Non-hyperlink
-      // runs take the unchanged cascade path.
-      const runResolveInput = {
-        paragraphStyleId: paragraph.styleId,
-        characterStyleId: undefined,
-        direct: directRunFormatting,
-      };
-      // L2.c — non-hyperlink body text also gets theme-color concretization
-      // so paragraph styles declaring `<w:color w:themeColor="accent1"/>`
-      // render with their theme slot's hex instead of falling back to
-      // default black. Hyperlink branch already resolves theme via the
-      // Hyperlink-style cascade; only the non-hyperlink path was missing.
-      const resolvedRunFormatting = cullBuild
-        ? {}
-        : hyperlinkHref
-          ? resolveHyperlinkRunFormatting(
-              runResolveInput,
-              document.styles,
-              themeResolver,
-            )
-          : concretizeThemeColors(
-              resolveEffectiveRunFormatting(runResolveInput, document.styles),
-              themeResolver,
-            );
+      const segmentFrom = start;
+      const segmentTo = start + Array.from(node.text).length;
+      // L7 Phase 2.9 — skip the run-cascade walk when the block will be
+      // culled. The placeholder path does not read `resolvedRunFormatting`.
+      //
+      // L03 boundary: the run cascade + theme concretization + hyperlink
+      // four-tier fallback + F6 revision-display posture ALL flow through
+      // `formattingContext.resolveRunFromMarks`. Surface-projection hands
+      // the context the projected marks + the hyperlink-context flag +
+      // the attached revision (looked up via L03's per-context revision
+      // index); the context owns every cascade decision.
+      const attachedRevision =
+        !cullBuild && formattingContext
+          ? formattingContext.findRevisionAtRange(segmentFrom, segmentTo)
+          : undefined;
+      const resolvedRunFormatting =
+        cullBuild || !formattingContext
+          ? {}
+          : formattingContext.resolveRunFromMarks({
+              paragraphStyleId: paragraph.styleId,
+              marks: {
+                marks: cloned.marks.length > 0 ? cloned.marks : undefined,
+                markAttrs: cloned.markAttrs,
+              },
+              inHyperlink: hyperlinkHref !== undefined,
+              ...(attachedRevision ? { revision: attachedRevision } : {}),
+            });
+      // Pull the F6 revision-display flags off the resolved record so
+      // they ride the surface segment for render consumers. Research
+      // doc §F6: the surface is the single place that maps segment →
+      // revision; render reads `segment.revisionDisplay` directly.
+      const revisionDisplay =
+        (resolvedRunFormatting as { revisionDisplay?: unknown }).revisionDisplay;
+      // Strip `revisionDisplay` from the object that lands on
+      // `resolvedRunFormatting` — the snapshot surface carries it as a
+      // top-level segment field (`segment.revisionDisplay`), not as a
+      // sub-field of the cascade. This keeps legacy consumers of
+      // `resolvedRunFormatting` stable while exposing the flags at a
+      // discoverable site.
+      const resolvedRunFormattingWithoutRevisionDisplay:
+        Record<string, unknown> = { ...(resolvedRunFormatting as Record<string, unknown>) };
+      delete resolvedRunFormattingWithoutRevisionDisplay.revisionDisplay;
       paragraph.segments.push({
         segmentId: `${paragraph.blockId}-segment-${paragraph.segments.length}`,
         kind: "text",
-        from: start,
-        to: start + Array.from(node.text).length,
+        from: segmentFrom,
+        to: segmentTo,
         text: node.text,
         ...(cloned.marks.length > 0 ? { marks: cloned.marks } : {}),
         ...(cloned.markAttrs ? { markAttrs: cloned.markAttrs } : {}),
-        ...(Object.keys(resolvedRunFormatting).length > 0 ? { resolvedRunFormatting } : {}),
+        ...(Object.keys(resolvedRunFormattingWithoutRevisionDisplay).length > 0
+          ? { resolvedRunFormatting: resolvedRunFormattingWithoutRevisionDisplay as CanonicalRunFormatting }
+          : {}),
         ...(hyperlinkHref ? { hyperlinkHref } : {}),
+        ...(revisionDisplay
+          ? { revisionDisplay: revisionDisplay as Extract<SurfaceInlineSegment, { kind: "text" }>["revisionDisplay"] }
+          : {}),
       });
-      return { nextCursor: start + Array.from(node.text).length, lockedFragmentIds: [] };
+      return { nextCursor: segmentTo, lockedFragmentIds: [] };
     }
     case "tab":
       paragraph.segments.push({
@@ -1264,6 +1224,7 @@ function appendInlineSegments(
           node.href,
           cullBuild,
           themeResolver,
+          formattingContext,
         );
         cursor = result.nextCursor;
       }
@@ -1479,6 +1440,7 @@ function appendInlineSegments(
             refHyperlinkHref ?? hyperlinkHref,
             cullBuild,
             themeResolver,
+            formattingContext,
           );
           cursor = result.nextCursor;
           lockedIds.push(...result.lockedFragmentIds);
@@ -1844,7 +1806,7 @@ function createPlainText(
 
 function createSecondaryStorySurfaces(
   document: CanonicalDocumentEnvelope,
-  numberingPrefixResolver: NumberingPrefixResolver,
+  formattingContext: FormattingContext,
 ): SecondaryStorySurface[] {
   const surfaces: SecondaryStorySurface[] = [];
   const subParts = document.subParts;
@@ -1876,7 +1838,7 @@ function createSecondaryStorySurfaces(
           `Header · ${headerVariant.variant}`,
           header.blocks,
           document,
-          numberingPrefixResolver,
+          formattingContext,
         ),
       );
     }
@@ -1904,7 +1866,7 @@ function createSecondaryStorySurfaces(
           `Footer · ${footerVariant.variant}`,
           footer.blocks,
           document,
-          numberingPrefixResolver,
+          formattingContext,
         ),
       );
     }
@@ -1913,13 +1875,13 @@ function createSecondaryStorySurfaces(
   const footnotes = Object.values(subParts.footnoteCollection?.footnotes ?? {}).sort(compareNoteIds);
   for (const note of footnotes) {
     const target: EditorStoryTarget = { kind: "footnote", noteId: note.noteId };
-    surfaces.push(createStorySurface(target, `Footnote ${note.noteId}`, note.blocks, document, numberingPrefixResolver));
+    surfaces.push(createStorySurface(target, `Footnote ${note.noteId}`, note.blocks, document, formattingContext));
   }
 
   const endnotes = Object.values(subParts.footnoteCollection?.endnotes ?? {}).sort(compareNoteIds);
   for (const note of endnotes) {
     const target: EditorStoryTarget = { kind: "endnote", noteId: note.noteId };
-    surfaces.push(createStorySurface(target, `Endnote ${note.noteId}`, note.blocks, document, numberingPrefixResolver));
+    surfaces.push(createStorySurface(target, `Endnote ${note.noteId}`, note.blocks, document, formattingContext));
   }
 
   return surfaces;
@@ -1930,7 +1892,7 @@ function createStorySurface(
   label: string,
   blocks: readonly BlockNode[],
   document: CanonicalDocumentEnvelope,
-  numberingPrefixResolver: NumberingPrefixResolver,
+  formattingContext: FormattingContext,
 ): SecondaryStorySurface {
   const surfaceBlocks: SurfaceBlockSnapshot[] = [];
   let cursor = 0;
@@ -1949,7 +1911,7 @@ function createStorySurface(
       document,
       cursor,
       counters,
-      numberingPrefixResolver,
+      formattingContext,
       true,
     );
     surfaceBlocks.push(surfaceBlock.block);
@@ -2167,7 +2129,7 @@ function buildDirectParagraphFormattingFromNode(
 }
 
 function toSurfaceResolvedNumbering(
-  numbering: NumberingPrefixResult,
+  numbering: NumberingResolution,
 ): NonNullable<Extract<SurfaceBlockSnapshot, { kind: "paragraph" }>["resolvedNumbering"]> {
   return {
     level: numbering.level,
@@ -2508,3 +2470,11 @@ function createFloatingImageDetail(
 function hasMediaItem(media: MediaCatalog, mediaId: string): boolean {
   return mediaId in media.items;
 }
+
+// Revision range index was moved into `FormattingContext` itself in the
+// §A production-boundary pass. Surface-projection now calls
+// `formattingContext.findRevisionAtRange(from, to)` at each text segment
+// push-point and hands the attached revision to
+// `formattingContext.resolveRunFromMarks({revision})` (which invokes
+// `applyRevisionDisplay` per F6). The result flows onto
+// `segment.revisionDisplay` for render consumers.