@beyondwork/docx-react-component 1.0.66 → 1.0.69

package/src/runtime/{paragraph-style-resolver.ts → formatting/style-cascade.ts}

@@ -1,62 +1,44 @@
 /**
- * Resolve style chains for paragraph and character styles by walking the
- * `basedOn` reference, with cycle detection.
+ * Layer 03 — four-tier style cascade core.
  *
- * 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).
+ * Owns the primitive merge helpers (`mergeRun`, `mergeParagraph`) and the
+ * drivers that walk the `basedOn` chains to produce effective formatting:
  *
- * Tasks 9 and 10 extend this module with `resolveEffective*Formatting`
- * helpers that cascade the chain into a flat formatting record.
+ *   - `resolveEffectiveParagraphFormatting` — docDefaults → basedOn chain
+ *     (root-to-leaf) → direct
+ *   - `resolveEffectiveRunFormatting` — docDefaults.run → paragraph-style
+ *     chain rPr → character-style chain rPr → direct
+ *   - `resolveNumberingMarkerRunFormatting` — docDefaults.run →
+ *     paragraph-style chain → paragraph-mark rPr → level rPr
+ *   - `resolveTableCellTextFormatting` — docDefaults → table-style chain
+ *
+ * The chain walkers (`resolveParagraphStyleChain`, `resolveCharacterStyleChain`)
+ * remain in `./paragraph-style-resolver.ts` and are imported from there —
+ * they are not cascade drivers, they are tree-walkers.
+ *
+ * Contract: all drivers are pure functions on (input, catalog). They do not
+ * consult the document content, the theme, the numbering catalog, or any
+ * layout state. Theme concretization + numbering + field + revision-display
+ * posture layer on top in `./resolve-effective.ts`.
  */
 
 import type {
-  CanonicalFontTable,
   CanonicalParagraphFormatting,
   CanonicalRunFormatting,
-  CharacterStyleDefinition,
-  ParagraphStyleDefinition,
   StylesCatalog,
+  TableStyleConditionalRegion,
   TableStyleDefinition,
-} from "../model/canonical-document.ts";
+} from "../../model/canonical-document.ts";
+import {
+  resolveCharacterStyleChain,
+  resolveParagraphStyleChain,
+} from "./paragraph-style-resolver.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;
-}
+// ---------------------------------------------------------------------------
+// Merge primitives
+// ---------------------------------------------------------------------------
 
-function mergeRun(
+export function mergeRun(
   base: CanonicalRunFormatting | undefined,
   over: CanonicalRunFormatting | undefined,
 ): CanonicalRunFormatting | undefined {
@@ -64,7 +46,7 @@ function mergeRun(
   return { ...(base ?? {}), ...(over ?? {}) };
 }
 
-function mergeParagraph(
+export function mergeParagraph(
   base: CanonicalParagraphFormatting | undefined,
   over: CanonicalParagraphFormatting | undefined,
 ): CanonicalParagraphFormatting | undefined {
@@ -91,13 +73,32 @@ function mergeParagraph(
   return merged;
 }
 
+// ---------------------------------------------------------------------------
+// Driver inputs
+// ---------------------------------------------------------------------------
+
 export interface ParagraphResolveInput {
   styleId: string | undefined;
   direct: CanonicalParagraphFormatting | undefined;
 }
 
+export interface RunResolveInput {
+  paragraphStyleId: string | undefined;
+  characterStyleId: string | undefined;
+  direct: CanonicalRunFormatting | undefined;
+}
+
+export interface MarkerResolveInput {
+  paragraphStyleId: string | undefined;
+  levelRunProperties: CanonicalRunFormatting | undefined;
+}
+
+// ---------------------------------------------------------------------------
+// Drivers
+// ---------------------------------------------------------------------------
+
 /**
- * Resolve paragraph formatting cascade: docDefaults.paragraph → basedOn chain
+ * Paragraph formatting cascade: docDefaults.paragraph → basedOn chain
  * (root-to-leaf) → direct. Returns `{}` when nothing is present.
  */
 export function resolveEffectiveParagraphFormatting(
@@ -107,7 +108,7 @@ export function resolveEffectiveParagraphFormatting(
   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
+    // 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);
@@ -117,14 +118,8 @@ export function resolveEffectiveParagraphFormatting(
   return acc ?? {};
 }
 
-export interface RunResolveInput {
-  paragraphStyleId: string | undefined;
-  characterStyleId: string | undefined;
-  direct: CanonicalRunFormatting | undefined;
-}
-
 /**
- * Resolve run formatting cascade: docDefaults.run → paragraph-style-chain rPr
+ * Run formatting cascade: docDefaults.run → paragraph-style-chain rPr
  * (root-to-leaf) → character-style-chain (root-to-leaf) → direct. Returns
  * `{}` when nothing is present.
  */
@@ -151,102 +146,35 @@ export function resolveEffectiveRunFormatting(
   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.).
+ * Numbering marker rPr cascade (ECMA-376 §17.9).
  *
- * 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.
+ * Order (lowest → highest priority):
+ *   1. `docDefaults.run`
+ *   2. Paragraph style chain `runProperties` — root-to-leaf
+ *   3. Leaf paragraph style's `paragraphProperties.paragraphMarkRunProperties`
+ *      (Word stores the mark rPr separately from body rPr; the marker
+ *      inherits from the mark).
+ *   4. `levelRunProperties` (`<w:lvl><w:rPr>`) — final word.
  */
 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 ?? {};
 }
 
-/**
- * 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.
- * Used by Lane 1's suggest-paragraph-split command.
- */
-export function getNextStyleId(
-  styleId: string,
-  catalog: StylesCatalog | undefined,
-): string | undefined {
-  return catalog?.paragraphs[styleId]?.nextStyle;
-}
-
-/**
- * Resolve the effective font family name for a run.
- *
- * Walks the ECMA-376 §17.3.2.26 precedence for `<w:rFonts>`: `ascii` →
- * `hAnsi` → `eastAsia` → `cs`. When none of those resolve on the direct
- * run formatting, layers the paragraph/character style cascade for the
- * same four fields, then falls back to the caller-supplied
- * `themeMinorFont` (ECMA-376 default for body text).
- *
- * `fontTable`, when supplied, is consulted only for presence — an entry
- * whose `w:name` does not appear in `fontTable.fonts` is still returned
- * as-is (Word behavior: substitute at render time, not at model resolve).
- * Lane 3a's measurement backend owns the substitution decision.
- *
- * Returns undefined only when no source in the cascade supplies a family
- * name (rare — production docs always hit docDefaults or the theme).
- */
-export function resolveRunFontFamily(
-  input: RunResolveInput,
-  catalog: StylesCatalog | undefined,
-  themeMinorFont: string | undefined,
-  fontTable?: CanonicalFontTable | undefined,
-): string | undefined {
-  // `fontTable` is currently unused inside this resolver; the ECMA-376
-  // rFonts precedence does not require consulting the package's fontTable
-  // to pick a name. It is reserved so Lane 3a's measurement backend can
-  // layer substitution (e.g. pick a monospace fallback when the resolved
-  // name has `pitch === "fixed"`) by threading the same table through.
-  void fontTable;
-  const resolved = resolveEffectiveRunFormatting(input, catalog);
-  const name =
-    resolved.fontFamilyAscii ??
-    resolved.fontFamilyHAnsi ??
-    resolved.fontFamilyEastAsia ??
-    resolved.fontFamilyCs ??
-    resolved.fontFamily ??
-    themeMinorFont;
-  return name;
-}
-
 function resolveTableStyleChain(
   styleId: string,
   catalog: StylesCatalog | undefined,
@@ -273,26 +201,41 @@ function resolveTableStyleChain(
  *   1. `catalog.docDefaults.paragraph` / `.run`
  *   2. Table style's `basedOn` chain, walked root-to-leaf, projecting each
  *      style's `formatting.paragraphProperties` / `.runProperties`.
+ *   3. When `activeRegions` is supplied — the `conditionalFormatting[region]`
+ *      pPr / rPr for each active region, applied in the caller's region
+ *      order (typically `getActiveCellRegions()` output: row bands →
+ *      column bands → first/last row → first/last column → corner cells).
+ *      Higher regions in the list win over lower — consistent with
+ *      ECMA-376 §17.7.6 region-precedence semantics and matches how
+ *      `mergeStyleFormattingCell` already layers cell-level properties.
  *
- * Conditional-region pPr/rPr (`<w:tblStylePr w:type="...">`) is intentionally
- * NOT layered here — callers that need region-aware cell-text cascade must
- * extend this once the conditional region parser captures pPr/rPr (Lane 3a
- * follow-up). Per-paragraph and per-run formatting from the cell's content
- * is layered by `resolveEffectiveParagraphFormatting` /
- * `resolveEffectiveRunFormatting`; this function only returns the floor.
+ * Callers that have no region information (e.g. a non-contextual lookup)
+ * omit `activeRegions` and receive the basedOn-chain floor only. Per-paragraph
+ * and per-run formatting from the cell's content is layered on top by the
+ * paragraph + run cascade drivers; this function returns the pre-direct
+ * table-style floor.
  */
 export function resolveTableCellTextFormatting(
   tableStyleId: string | undefined,
   catalog: StylesCatalog | undefined,
+  activeRegions?: readonly TableStyleConditionalRegion[],
 ): { paragraph: CanonicalParagraphFormatting; run: CanonicalRunFormatting } {
   let paragraph: CanonicalParagraphFormatting | undefined = catalog?.docDefaults?.paragraph;
   let run: CanonicalRunFormatting | undefined = catalog?.docDefaults?.run;
   if (catalog && tableStyleId) {
     const chain = resolveTableStyleChain(tableStyleId, catalog);
     for (let i = chain.length - 1; i >= 0; i -= 1) {
-      const formatting = chain[i]!.formatting;
-      paragraph = mergeParagraph(paragraph, formatting?.paragraphProperties);
-      run = mergeRun(run, formatting?.runProperties);
+      const def = chain[i]!;
+      paragraph = mergeParagraph(paragraph, def.formatting?.paragraphProperties);
+      run = mergeRun(run, def.formatting?.runProperties);
+      if (activeRegions && activeRegions.length > 0 && def.conditionalFormatting) {
+        for (const region of activeRegions) {
+          const regionFormatting = def.conditionalFormatting[region];
+          if (!regionFormatting) continue;
+          paragraph = mergeParagraph(paragraph, regionFormatting.paragraphProperties);
+          run = mergeRun(run, regionFormatting.runProperties);
+        }
+      }
     }
   }
   return { paragraph: paragraph ?? {}, run: run ?? {} };

package/src/runtime/{table-style-resolver.ts → formatting/table-style-resolver.ts}

@@ -10,7 +10,7 @@ import type {
   TableStyleDefinition,
   TableStyleFormatting,
   TableWidth,
-} from "../model/canonical-document.ts";
+} from "../../model/canonical-document.ts";
 
 export interface ResolvedTableCellStyle {
   width?: TableWidth;

package/src/runtime/formatting/telemetry-bridge.ts

@@ -0,0 +1,106 @@
+/**
+ * Layer 03 — formatting-telemetry bridge.
+ *
+ * Consumers (surface-projection, document-runtime, field resolver) pass a
+ * `ResolveEffectiveFormattingOptions.emitFormattingTelemetry` callback
+ * that bridges entry events onto the runtime `TelemetryBus`. This helper
+ * builds that callback with:
+ *
+ *   - Probability gating for `formatting.resolution_sampled` (default
+ *     rate `0.01` — 1% of resolutions).
+ *   - Unfiltered pass-through for `formatting.cache.invalidated` and
+ *     `formatting.revision_display.mode_changed` (low-frequency signals).
+ *   - Bus-level `isEnabled("formatting")` short-circuit so the callback
+ *     returns immediately when the channel is off, preserving the
+ *     "zero cost when off" contract.
+ *
+ * The bridge lives in the formatting layer so it can stay colocated with
+ * the telemetry event type. The telemetry bus `TelemetryBus` is imported
+ * by type only; there is no value dependency on layer 02's debug
+ * infrastructure at runtime.
+ *
+ * Performance: each call is a channel-enabled check (O(1)) + an optional
+ * Math.random for sampled events. `bus.emitLazy` is used for sampled
+ * events so the payload factory runs only on hit.
+ */
+
+import type { TelemetryBus } from "../debug/telemetry-bus.ts";
+import { shouldEmitSample } from "../debug/probability-sampler.ts";
+import type { FormattingTelemetryEvent } from "./resolve-effective.ts";
+
+export interface FormattingTelemetryBridgeOptions {
+  /** Probability gate for `formatting.resolution_sampled` events.
+   *  Default `0.01` (1%). Set to 0 to disable sample emission entirely. */
+  readonly resolutionSampleRate?: number;
+}
+
+const DEFAULT_RESOLUTION_SAMPLE_RATE = 0.01;
+
+/**
+ * Build an `emitFormattingTelemetry` callback suitable for passing to
+ * `resolveEffectiveFormatting({ ..., emitFormattingTelemetry })`. Wraps
+ * the runtime telemetry bus with probability-gated sampling for the
+ * high-frequency event.
+ */
+export function buildFormattingTelemetryBridge(
+  bus: TelemetryBus,
+  options: FormattingTelemetryBridgeOptions = {},
+): (event: FormattingTelemetryEvent) => void {
+  const sampleRate = options.resolutionSampleRate ?? DEFAULT_RESOLUTION_SAMPLE_RATE;
+
+  return function emit(event: FormattingTelemetryEvent): void {
+    if (!bus.isEnabled("formatting")) return;
+
+    switch (event.type) {
+      case "formatting.resolution_sampled": {
+        if (!shouldEmitSample(sampleRate)) return;
+        bus.emit({
+          channel: "formatting",
+          type: event.type,
+          t: 0,
+          payload: event.payload,
+        });
+        return;
+      }
+      case "formatting.cache.invalidated": {
+        bus.emit({
+          channel: "formatting",
+          type: event.type,
+          t: 0,
+          payload: event.payload,
+        });
+        return;
+      }
+      case "formatting.numbering_format_unsupported": {
+        // Low-frequency fidelity-gap signal (dedup happens at the emit
+        // site — see surface-projection). No sampling; every hit matters.
+        bus.emit({
+          channel: "formatting",
+          type: event.type,
+          t: 0,
+          payload: event.payload,
+        });
+        return;
+      }
+    }
+  };
+}
+
+/**
+ * Narrow helper for emitting the revision-display mode-change event.
+ * Consumers (render-kernel, surface-projection) call this directly when
+ * the active markup mode toggles — it's a state-change event, not per
+ * resolution.
+ */
+export function emitRevisionDisplayModeChanged(
+  bus: TelemetryBus,
+  mode: "clean" | "simple" | "all",
+): void {
+  if (!bus.isEnabled("formatting")) return;
+  bus.emit({
+    channel: "formatting",
+    type: "formatting.revision_display.mode_changed",
+    t: 0,
+    payload: { mode },
+  });
+}

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

@@ -24,9 +24,8 @@
  * reference byte-for-byte.
  */
 
-import type { CanonicalRunFormatting, CanonicalTheme, ClrSchemeMappingSlot, ResolvedTheme } from "../model/canonical-document.ts";
-import { resolveThemeColor } from "../io/ooxml/parse-theme.ts";
-import { GRADIENT_STOP_UNITS } from "./units.ts";
+import type { CanonicalRunFormatting, CanonicalTheme, ClrSchemeMappingSlot } from "../../model/canonical-document.ts";
+import { GRADIENT_STOP_UNITS } from "../units.ts";
 
 /**
  * DrawingML color modifier (ECMA-376 §20.1.2.3.x).
@@ -98,33 +97,6 @@ export class ThemeColorResolver {
   }
 }
 
-/**
- * Collapse `<w:color>`-style theme-slot + tint + shade references into a
- * single resolved hex colour. §17-only byte-form path; does NOT apply
- * `w:clrSchemeMapping` remap.
- *
- * @deprecated Use `ThemeColorResolver.resolveWordThemeColor` instead —
- * it honours clrSchemeMapping. This free function is retained only for
- * its targeted unit tests (`test/io/theme-color-tint-shade.test.ts`) and
- * will be removed once those migrate to the class.
- */
-export function resolveThemeColorHex(
-  rPr: Pick<
-    CanonicalRunFormatting,
-    "colorHex" | "colorThemeSlot" | "colorThemeTint" | "colorThemeShade"
-  >,
-  theme: ResolvedTheme | undefined,
-): string | undefined {
-  if (rPr.colorHex === "auto") return "auto";
-  if (rPr.colorHex) return rPr.colorHex;
-  if (!rPr.colorThemeSlot) return undefined;
-
-  const baseHex = resolveThemeColor(theme, rPr.colorThemeSlot);
-  if (!baseHex) return undefined;
-
-  return applyThemeTintShade(baseHex, rPr.colorThemeTint, rPr.colorThemeShade);
-}
-
 /**
  * Post-process a cascade of run formatting to concretize any
  * theme-color-only reference into a paintable `colorHex`.

package/src/runtime/geometry/caret-geometry.ts

@@ -0,0 +1,164 @@
+/**
+ * Layer 05 — Caret + selection-rect geometry.
+ *
+ * Pure projections against a `RenderFrame`:
+ *
+ *   - `resolveCaretGeometry(frame, offset, story?)` → `CaretGeometry | null`
+ *     Returns the caret position + line height + baseline + writing
+ *     direction at `offset`, projected to frame-local pixels.
+ *   - `resolveSelectionRects(frame, { from, to, story? })`
+ *     Returns one `GeometryRect` per line the selection covers when
+ *     per-line data is available, or the kernel's union selection rect
+ *     otherwise. Empty range collapses to a zero-width caret rect;
+ *     off-document ranges return `[]`.
+ *
+ * Slice-4 substrate notes:
+ *
+ *   - The primary source is `frame.anchorIndex` — the render kernel's
+ *     anchor lookup is populated for every layout-produced offset even
+ *     when per-line `RenderLine[]` arrays are empty (which they are for
+ *     synthetic docs with no measurement provider). `byRuntimeOffset`
+ *     returns a rect shaped like "the line at that offset", which gives
+ *     the caret its correct top + height. When per-line anchors DO
+ *     populate (Slice 5 with richer line projection), selection-rect
+ *     enumeration upgrades to one-rect-per-line automatically.
+ *   - **RTL + bidi** is reserved. `direction` is always `"ltr"` in this
+ *     slice because the render kernel does not yet expose run-level
+ *     writing-direction metadata. The `CaretGeometry.direction` field
+ *     is stable so a future slice can fill in RTL without a consumer-
+ *     visible API change.
+ *   - **Empty blocks** snap to the block's left edge at the full line
+ *     height — the Word-compatible behavior. `byRuntimeOffset` on an
+ *     offset inside an empty paragraph returns the paragraph's rect;
+ *     the caret lives at that rect's leftPx.
+ */
+
+import type { EditorStoryTarget } from "../../api/public-types";
+import type {
+  RenderFrame,
+  RenderFrameRect,
+} from "../render/index.ts";
+import type {
+  CaretGeometry,
+  GeometryRect,
+} from "./geometry-types.ts";
+
+/**
+ * Resolve the caret for `offset`, or `null` if the offset falls outside
+ * the frame's resolvable range. Slice 4 routes through
+ * `frame.anchorIndex.byRuntimeOffset`; Slice 5 tightens x-position
+ * within a line once per-run anchors land.
+ */
+export function resolveCaretGeometry(
+  frame: RenderFrame | null,
+  offset: number,
+  story?: EditorStoryTarget,
+): CaretGeometry | null {
+  if (!frame) return null;
+  if (!Number.isFinite(offset)) return null;
+
+  const anchorRect = frame.anchorIndex.byRuntimeOffset(offset, story);
+  if (!anchorRect) return null;
+
+  const rect: GeometryRect = {
+    leftPx: anchorRect.leftPx,
+    topPx: anchorRect.topPx,
+    widthPx: 0,
+    heightPx: anchorRect.heightPx,
+    space: "frame",
+  };
+
+  // Slice 7b (2026-04-22): `direction` is hardcoded "ltr" and
+  // `baseline` uses a 0.8 * height heuristic. Both are substrate
+  // placeholders pending the render-kernel's per-run anchor work
+  // (refactor/05 Slice 7, Task 2). Tag the coarsest precision so
+  // consumers can gate bidi-sensitive work.
+  return {
+    rect,
+    baseline: resolveBaselinePx(anchorRect),
+    height: anchorRect.heightPx,
+    direction: "ltr", // reserved for a future bidi-aware slice.
+    precision: "heuristic",
+  };
+}
+
+/**
+ * Resolve `GeometryRect[]` for a selection range. Slice 4 produces:
+ *   - an empty list when either endpoint can't be resolved
+ *   - a single zero-width caret rect when `from === to`
+ *   - a single union rect otherwise (via `frame.anchorIndex.bySelection`)
+ *
+ * When the kernel's per-line anchor projection matures (Slice 5+), this
+ * function flips to emitting one rect per line. The single-rect fallback
+ * keeps chrome surfaces that currently call `getAnchorRects({ kind:
+ * "runtime-offset", … })[0]` in sync with the new selection API.
+ */
+export function resolveSelectionRects(
+  frame: RenderFrame | null,
+  range: {
+    from: number;
+    to: number;
+    story?: EditorStoryTarget;
+  },
+): readonly GeometryRect[] {
+  if (!frame) return [];
+  const { from, to } = range;
+  if (!Number.isFinite(from) || !Number.isFinite(to)) return [];
+  const lo = Math.min(from, to);
+  const hi = Math.max(from, to);
+
+  if (lo === hi) {
+    const caret = resolveCaretGeometry(frame, lo, range.story);
+    if (!caret) return [];
+    // Caret rect for a collapsed range is an exact anchor-index read —
+    // the placeholder-grade metadata on `CaretGeometry` (direction,
+    // baseline) applies to the caret as a whole, not to the rect's
+    // position. Return the rect untagged so callers that iterate
+    // `getSelectionRects(...)` and expect pixel-exact carets see the
+    // expected `"exact"` default.
+    return [caret.rect];
+  }
+
+  const union = frame.anchorIndex.bySelection(lo, hi, range.story);
+  if (!union) return [];
+  // Slice 7b (2026-04-22): the substrate returns ONE union rect for any
+  // non-collapsed range. That rect is geometrically correct at the
+  // block level but loses per-line detail — tag it `within-tolerance`
+  // so callers can gate per-line chrome work. When the render kernel
+  // ships per-run anchors (refactor/05 Slice 7 Task 2), this site
+  // upgrades to multiple `"exact"` rects automatically.
+  return [toGeometryRect(union, "within-tolerance")];
+}
+
+// ---------------------------------------------------------------------------
+// Internals
+// ---------------------------------------------------------------------------
+
+function toGeometryRect(
+  rect: RenderFrameRect,
+  precision?: GeometryRect["precision"],
+): GeometryRect {
+  const out: GeometryRect = {
+    leftPx: rect.leftPx,
+    topPx: rect.topPx,
+    widthPx: rect.widthPx,
+    heightPx: rect.heightPx,
+    space: "frame",
+  };
+  if (precision !== undefined) {
+    out.precision = precision;
+  }
+  return out;
+}
+
+/**
+ * Approximate the baseline offset within a line rect. The render frame
+ * does not yet carry per-anchor baseline metadata, so Slice 4 uses a
+ * fixed 0.8× ratio — the typical cap-height heuristic for Latin scripts.
+ * A later slice replaces this with the per-line `baselineTwips` once
+ * per-line anchors are populated.
+ */
+function resolveBaselinePx(rect: RenderFrameRect): number {
+  if (rect.heightPx <= 0) return 0;
+  return rect.heightPx * 0.8;
+}