@beyondwork/docx-react-component 1.0.66 → 1.0.69

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

@@ -42,33 +42,50 @@ export interface LayoutTabStop {
 
 /**
  * Average character width in twips per half-point of font size.
- * These are empirical values from measuring common document fonts.
- * Key insight: Word uses font metrics from the OS font table; we use
- * bounded approximations that are close enough for page composition.
+ *
+ * Calibrated 2026-04-23 against published OpenType font-metrics average
+ * advance widths (xAvgCharWidth / (unitsPerEm × 2)) rather than the
+ * pre-calibration "empirical" values that were systematically ~80%
+ * higher than real Word measurements. The pre-calibration values
+ * produced a 50-73% page overcount vs LibreOffice oracle baselines on
+ * CCEP contracts; trusted-oracle verification post truth-baseline's
+ * 2026-04-23 re-extraction confirmed the runtime-side miscalibration
+ * (cross-layer-coord-04.md §1.15 / §1.18).
+ *
+ * Unit: twips per half-point of font size. At an `effectiveSize` of 22
+ * (11-pt text), Calibri's factor of 5.0 yields 110 twips per character —
+ * which matches Calibri's published `xAvgCharWidth = 1037 / 2048 em`
+ * (~0.506 em = 5.57 pt = 111 twips at 11 pt). The same derivation gives
+ * the other values.
+ *
+ * The canvas backend does not consult this table — it measures real
+ * glyph widths via Canvas2D `measureText`. This table is only the
+ * empirical / SSR fallback used by the layout engine when a canvas
+ * context is unavailable.
  */
 const FONT_AVG_CHAR_WIDTH: Record<string, number> = {
-  // Proportional serif
-  "times new roman": 9.2,
-  "georgia": 10.0,
-  "garamond": 8.8,
-  "book antiqua": 9.6,
-  "palatino linotype": 9.8,
-  "cambria": 9.6,
-  // Proportional sans-serif
-  "arial": 10.4,
-  "calibri": 9.0,
-  "helvetica": 10.4,
-  "verdana": 12.0,
-  "tahoma": 10.6,
-  "segoe ui": 9.8,
-  "trebuchet ms": 10.2,
-  // Monospace
-  "courier new": 12.0,
-  "consolas": 11.0,
-  "lucida console": 12.0,
+  // Proportional serif (xAvgCharWidth ≈ 0.48-0.52 em for body text)
+  "times new roman": 5.1,
+  "georgia": 5.6,
+  "garamond": 4.9,
+  "book antiqua": 5.3,
+  "palatino linotype": 5.5,
+  "cambria": 5.3,
+  // Proportional sans-serif (xAvgCharWidth ≈ 0.50-0.60 em)
+  "arial": 5.8,
+  "calibri": 5.0,
+  "helvetica": 5.8,
+  "verdana": 6.7,
+  "tahoma": 5.9,
+  "segoe ui": 5.4,
+  "trebuchet ms": 5.6,
+  // Monospace (every glyph ≈ 0.60-0.67 em)
+  "courier new": 6.7,
+  "consolas": 6.1,
+  "lucida console": 6.7,
 };
 
-const DEFAULT_FONT_AVG_CHAR_WIDTH = 10.0; // reasonable fallback
+const DEFAULT_FONT_AVG_CHAR_WIDTH = 5.5; // reasonable fallback (between serif + sans proportional)
 const DEFAULT_FONT_SIZE_HALF_POINTS = 24; // 12pt
 const DEFAULT_LINE_HEIGHT_FACTOR = 1.15; // Word default for Calibri body
 const TWIPS_PER_POINT = 20;
@@ -277,15 +294,34 @@ function resolveIndentation(
 function resolveDominantFont(
   block: Extract<SurfaceBlockSnapshot, { kind: "paragraph" }>,
 ): { fontSizeHalfPoints: number; avgCharWidth: number; fontFamily: string | undefined } {
-  // Find the dominant font from the segments (most common or first text run)
+  // L03 → L04 contract: read formatting from the canonical L03 output
+  // (`segment.resolvedRunFormatting`) first; fall back to the surface
+  // projection intermediate (`segment.markAttrs`) only when the
+  // resolved value is absent (viewport-culled block).
+  //
+  // Architecture §C2: layout must consume formatting from L03, not
+  // re-derive it from a rendering intermediate. Research doc §"Where
+  // to combine layers for performance" permits layout to ride the
+  // surface snapshot for locality, but the authoritative values must
+  // come from L03.
   let fontFamily: string | undefined;
   let fontSizeHalfPoints: number | undefined;
   let maxTextLength = 0;
 
   for (const segment of block.segments) {
     if (segment.kind !== "text") continue;
-    const segFontFamily = segment.markAttrs?.fontFamily;
-    const segFontSize = segment.markAttrs?.fontSize;
+    const resolved = segment.resolvedRunFormatting;
+    // Prefer L03 resolved output over projected markAttrs. The cascade
+    // already layered docDefaults → paragraph style → character style →
+    // direct overrides; the markAttrs fallback only applies when the
+    // block was viewport-culled (resolvedRunFormatting absent).
+    const segFontFamily =
+      resolved?.fontFamilyAscii ??
+      resolved?.fontFamily ??
+      resolved?.fontFamilyHAnsi ??
+      segment.markAttrs?.fontFamily;
+    const segFontSize =
+      resolved?.fontSizeHalfPoints ?? segment.markAttrs?.fontSize;
     const textLength = segment.text.length;
 
     if (textLength > maxTextLength) {
@@ -457,3 +493,99 @@ export function resolveNumberingPrefixLength(
         : 0;
   return prefix.length + suffix;
 }
+
+/**
+ * Build a `Map<RunId, ResolvedRunFormatting>` for a paragraph block so
+ * the measurement provider's `measureLineFragments` call receives real
+ * per-run metrics instead of a placeholder empty map. Task 3 of
+ * refactor/04 post-closure (2026-04-23).
+ *
+ * Stable key convention: `${blockId}:${segmentId}`, matching the
+ * canvas backend's lookup (`measurement-backend-canvas.ts:156`).
+ *
+ * Source precedence per text segment:
+ *   1. `segment.resolvedRunFormatting` (L03 canonical cascade output)
+ *   2. `segment.markAttrs` + `segment.marks` (surface-projection intermediate)
+ *
+ * The shape emitted matches `ResolvedRunFormatting` from
+ * `resolved-formatting-document.ts` (structural compatibility — no
+ * import cycle). Canvas backend consumes `fontFamily`,
+ * `fontSizeHalfPoints`, `bold`, `italic`. The rest are populated
+ * best-effort for future consumers.
+ */
+export function buildRunFormattingMap(
+  block: Extract<SurfaceBlockSnapshot, { kind: "paragraph" }>,
+): Map<
+  string,
+  {
+    fontFamily?: string;
+    fontSizeHalfPoints?: number;
+    bold: boolean;
+    italic: boolean;
+    underline: boolean;
+    strikethrough: boolean;
+    color?: string;
+    highlight?: string;
+    verticalAlign: "baseline" | "superscript" | "subscript";
+  }
+> {
+  const runs = new Map<
+    string,
+    {
+      fontFamily?: string;
+      fontSizeHalfPoints?: number;
+      bold: boolean;
+      italic: boolean;
+      underline: boolean;
+      strikethrough: boolean;
+      color?: string;
+      highlight?: string;
+      verticalAlign: "baseline" | "superscript" | "subscript";
+    }
+  >();
+  for (const segment of block.segments) {
+    if (segment.kind !== "text") continue;
+    const resolved = segment.resolvedRunFormatting;
+    const markAttrs = segment.markAttrs ?? {};
+    const markSet = new Set(segment.marks ?? []);
+    const fontFamily =
+      resolved?.fontFamilyAscii ??
+      resolved?.fontFamily ??
+      resolved?.fontFamilyHAnsi ??
+      (typeof markAttrs.fontFamily === "string" ? markAttrs.fontFamily : undefined);
+    const fontSizeHalfPoints =
+      resolved?.fontSizeHalfPoints ??
+      (typeof markAttrs.fontSize === "number" ? markAttrs.fontSize : undefined);
+    const bold = resolved?.bold ?? markSet.has("bold");
+    const italic = resolved?.italic ?? markSet.has("italic");
+    const underline =
+      (resolved?.underline !== undefined && resolved.underline !== "none") ||
+      markSet.has("underline");
+    const strikethrough =
+      resolved?.strikethrough === true ||
+      markSet.has("strikethrough") ||
+      markSet.has("doubleStrikethrough");
+    const verticalAlign: "baseline" | "superscript" | "subscript" =
+      resolved?.verticalAlign === "superscript" || markSet.has("superscript")
+        ? "superscript"
+        : resolved?.verticalAlign === "subscript" || markSet.has("subscript")
+          ? "subscript"
+          : "baseline";
+    runs.set(`${block.blockId}:${segment.segmentId}`, {
+      ...(fontFamily ? { fontFamily } : {}),
+      ...(fontSizeHalfPoints !== undefined ? { fontSizeHalfPoints } : {}),
+      bold: Boolean(bold),
+      italic: Boolean(italic),
+      underline: Boolean(underline),
+      strikethrough: Boolean(strikethrough),
+      ...(typeof markAttrs.textColor === "string"
+        ? { color: markAttrs.textColor }
+        : {}),
+      ...(typeof markAttrs.backgroundColor === "string"
+        ? { highlight: markAttrs.backgroundColor }
+        : {}),
+      verticalAlign,
+    });
+  }
+  return runs;
+}

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

@@ -23,7 +23,7 @@ import type {
   SurfaceTableRowSnapshot,
 } from "../../api/public-types";
 import type { TableStyleConditionalRegion } from "../../model/canonical-document.ts";
-import type { ResolvedTableStyleResolution } from "../table-style-resolver.ts";
+import type { ResolvedTableStyleResolution } from "../formatting/table-style-resolver.ts";
 
 // ─── Public shapes ───────────────────────────────────────────────────────────
 

package/src/runtime/prerender/cache-envelope.ts

@@ -1,7 +1,12 @@
 import type { EditorSurfaceSnapshot } from "../../api/public-types";
 import type { CanonicalDocument } from "../../model/canonical-document.ts";
 import type { CompatibilityReport } from "../../core/state/editor-state.ts";
-import type { RuntimePageGraph } from "../layout/page-graph.ts";
+// Pass 2 (2026-04-22) — `RuntimePageGraph` relocated out of
+// `src/runtime/layout/` to `src/model/layout/runtime-page-graph-types.ts`
+// so this envelope (and the `tryReadLaycacheEnvelope` probe that
+// produces it) can be consumed from `src/session/**` without a
+// `src/runtime/**` transit. See `docs/plans/cross-layer-coord-04.md §1.12`.
+import type { RuntimePageGraph } from "../../model/layout/runtime-page-graph-types.ts";
 
 /**
  * L7 Phase 2.5 — prerender cache envelope shape.

package/src/runtime/prerender/prerender-document.ts

@@ -1,9 +1,8 @@
 import type { EditorSurfaceSnapshot } from "../../api/public-types";
 import { createSelectionSnapshot } from "../../core/state/editor-state.ts";
-import { loadDocxEditorSessionAsync } from "../../io/docx-session.ts";
-import { createLoadScheduler } from "../../io/load-scheduler.ts";
 import { readOpcPackage } from "../../io/opc/package-reader.ts";
 import { writeOpcPackage } from "../../io/opc/package-writer.ts";
+import { DocxSession } from "../../session/index.ts";
 import {
   LAYCACHE_SCHEMA_VERSION,
   LAYOUT_ENGINE_VERSION,
@@ -44,8 +43,8 @@ import { canonicalizeGraph } from "./graph-canonicalize.ts";
  *           but do not enter the envelope.
  *
  * Node-safety:
- *   - Uses `createLoadScheduler({ backendOverride: "sync" })` so the
- *     async loader runs without DOM scheduler.yield.
+ *   - Forwards `schedulerBackend: "sync"` to `DocxSession.open()` so
+ *     the async loader runs without DOM scheduler.yield.
  *   - Layout engine is constructed with
  *     `autoUpgradeToCanvasBackend: false` so the empirical measurement
  *     backend is used (no Canvas2D, no node-canvas).
@@ -118,26 +117,21 @@ export async function prerenderDocument(
   const bytes = toUint8Array(input);
   const fontFingerprint = options.fontFingerprint ?? resolveFontFingerprint();
 
-  const scheduler = createLoadScheduler({ backendOverride: "sync" });
-  let session;
-  try {
-    session = await loadDocxEditorSessionAsync({
-      documentId: PRERENDER_DOCUMENT_ID,
-      bytes,
-      editorBuild: "prerender",
-      scheduler,
-    });
-  } finally {
-    scheduler.dispose();
-  }
+  const openResult = await new DocxSession().open(bytes, {
+    documentId: PRERENDER_DOCUMENT_ID,
+    editorBuild: "prerender",
+    schedulerBackend: "sync",
+  });
 
-  if (session.fatalError) {
+  // Slice 5e-1 promoted `fatalError` onto `OpenResult`, so no legacy
+  // view lookup is needed on this path anymore.
+  if (openResult.fatalError) {
     throw new Error(
-      `prerenderDocument: failed to load input — ${session.fatalError.message ?? "fatal error"}`,
+      `prerenderDocument: failed to load input — ${openResult.fatalError.message ?? "fatal error"}`,
     );
   }
 
-  // Normalize session-birth timestamps. `loadDocxEditorSessionAsync` sets
+  // Normalize session-birth timestamps. `DocxSession.open()` sets
   // `createdAt`/`updatedAt` from `new Date().toISOString()`; without this
   // override, two sequential prerender calls on identical bytes would
   // produce different envelopes → different customXml bytes → determinism
@@ -146,8 +140,8 @@ export async function prerenderDocument(
   // eliminating the only remaining source of non-determinism.  The live
   // session's updatedAt is re-populated by runtime mutations anyway, so
   // the normalized value is irrelevant at runtime.
-  const envelope: typeof session.initialSessionState.canonicalDocument = {
-    ...session.initialSessionState.canonicalDocument,
+  const envelope: typeof openResult.canonicalDocument = {
+    ...openResult.canonicalDocument,
     createdAt: PRERENDER_NORMALIZED_TIMESTAMP,
     updatedAt: PRERENDER_NORMALIZED_TIMESTAMP,
   };
@@ -172,7 +166,8 @@ export async function prerenderDocument(
   });
 
   // Phase 2 Finale C3: pre-compute `compatibilityReport` so the warm Plan B
-  // short-circuit in `loadDocxEditorSessionAsync` can skip the live
+  // short-circuit inside `DocxSession.open()` (which still transits the
+  // legacy async loader) can skip the live
   // `buildCompatibilityReport` call (~60–100 ms on extra-large). The report
   // is a pure function of `canonicalDocument` + `generatedAt`; pinning
   // `generatedAt` to `CACHE_NORMALIZED_GENERATED_AT` keeps the envelope
@@ -196,7 +191,7 @@ export async function prerenderDocument(
 
   // Plan B B.5 — persistToCustomXml: inject the envelope into the docx's
   // workflow-payload part. Re-parses the OPC package from bytes (~17 ms on
-  // extra-large) because `LoadedDocxEditorSession` does not expose
+  // extra-large) because `DocxSession.open()` does not expose
   // `sourcePackage` publicly. Acceptable cost on the one-shot ingest path.
   let docWithCustomXml = bytes;
   let persistedToCustomXml = false;

package/src/runtime/render/decoration-resolver.ts

@@ -23,7 +23,7 @@ import type {
   RevisionDecorationModel,
   RevisionDecorationEntry,
 } from "../../ui/headless/revision-decoration-model.ts";
-import type { ScopeRailSegment } from "../workflow-rail-segments.ts";
+import type { ScopeRailSegment } from "../workflow/rail/types.ts";
 import type {
   DecorationIndex,
   RenderAnchorIndex,

package/src/runtime/render/render-frame-types.ts

@@ -244,6 +244,26 @@ export interface RenderAnchorIndex {
   byScopeId(scopeId: string): readonly RenderFrameRect[];
   byCommentId(commentId: string): RenderFrameRect | null;
   byRevisionId(revisionId: string): RenderFrameRect | null;
+  /**
+   * Locate an object's exact bounding rect given its object id.
+   *
+   * Object ids discriminate **the object itself** from **the block that
+   * contains it** — for inline images embedded in a paragraph,
+   * `byObjectId(imageId)` returns the image's own bbox, not the
+   * enclosing paragraph's rect. For block-level drawings (floating
+   * anchors resolved to a page slot) the rect matches the drawing's
+   * slot.
+   *
+   * Refactor/05 Slice 7c substrate: the kernel does not yet carry
+   * per-object metadata on anchor frames, so this method returns
+   * `null` today for every id except those that also happen to be
+   * block ids (preserving the Slice-5 `object-handles.ts` fallback).
+   * When the layout facet grows an object-specific index (`byObjectId`
+   * on the layout graph, Slice 7d follow-up), this method starts
+   * returning real object rects automatically — consumers that gate
+   * on `result !== null` pick up the upgrade without an API break.
+   */
+  byObjectId(objectId: string): RenderFrameRect | null;
 }
 
 // ---------------------------------------------------------------------------

package/src/runtime/render/render-kernel.ts

@@ -15,6 +15,7 @@
 
 import { MAIN_STORY_TARGET } from "../../core/selection/mapping.ts";
 import { recordPerfSample } from "../../ui-tailwind/editor-surface/perf-probe.ts";
+import { storyTargetKey } from "../story-targeting.ts";
 import type { EditorStoryTarget } from "../../api/public-types";
 import type {
   PublicBlockFragment,
@@ -25,7 +26,7 @@ import type {
 } from "../layout/public-facet.ts";
 import type { CommentDecorationModel } from "../../ui/headless/comment-decoration-model.ts";
 import type { RevisionDecorationModel } from "../../ui/headless/revision-decoration-model.ts";
-import type { ScopeRailSegment } from "../workflow-rail-segments.ts";
+import type { ScopeRailSegment } from "../workflow/rail/types.ts";
 import {
   resolveDecorationIndex,
   type LockedRangeInput,
@@ -719,7 +720,14 @@ function buildAnchorIndex(
   pxPerTwip = 1,
   decorationIndex: DecorationIndex = EMPTY_DECORATION_INDEX,
 ): RenderAnchorIndex {
+  // Main-document runtime offsets flow through `byRuntimeOffset` (body
+  // region). Header / footer / footnote stories have offsets LOCAL to
+  // their story — they can't share the `byRuntimeOffset` keyspace with
+  // the body without collisions. Refactor/05 Slice 7d indexes non-body
+  // blocks via `byRuntimeOffsetByStory`, a `storyTargetKey → offset →
+  // rect` map consulted when the caller passes a `story` argument.
   const byRuntimeOffset = new Map<number, RenderFrameRect>();
+  const byRuntimeOffsetByStory = new Map<string, Map<number, RenderFrameRect>>();
   const byFragmentId = new Map<string, RenderFrameRect>();
   const byBlockId = new Map<string, RenderFrameRect>();
   const byPageIndex = new Map<number, RenderFrameRect>();
@@ -730,28 +738,61 @@ function buildAnchorIndex(
   const tableColumnEdges = new Map<string, RenderFrameRect>();
   const tableRowEdges = new Map<string, RenderFrameRect>();
 
+  const recordBlock = (
+    block: import("./render-frame-types.ts").RenderBlock,
+    offsetMap: Map<number, RenderFrameRect>,
+  ): void => {
+    byFragmentId.set(block.fragment.fragmentId, block.frame);
+    byBlockId.set(block.fragment.blockId, block.frame);
+    offsetMap.set(block.fragment.from, block.frame);
+    for (const line of block.lines) {
+      for (const anchor of line.anchors) {
+        offsetMap.set(anchor.runtimeOffset, anchor.frame);
+      }
+    }
+    if (block.kind === "table" && block.tablePlan) {
+      recordTableAnchors(
+        block.fragment.blockId,
+        block.frame,
+        block.tablePlan,
+        pxPerTwip,
+        tableCellRects,
+        tableColumnEdges,
+        tableRowEdges,
+      );
+    }
+  };
+
+  const recordStoryRegion = (
+    region: import("./render-frame-types.ts").RenderStoryRegion,
+  ): void => {
+    const storyKey = storyTargetKey(region.storyTarget);
+    let storyMap = byRuntimeOffsetByStory.get(storyKey);
+    if (!storyMap) {
+      storyMap = new Map<number, RenderFrameRect>();
+      byRuntimeOffsetByStory.set(storyKey, storyMap);
+    }
+    for (const block of region.blocks) {
+      recordBlock(block, storyMap);
+    }
+  };
+
   for (const page of pages) {
     byPageIndex.set(page.page.pageIndex, page.frame);
+    // Body region feeds the shared `byRuntimeOffset` (main-story offsets).
     for (const block of page.regions.body.blocks) {
-      byFragmentId.set(block.fragment.fragmentId, block.frame);
-      byBlockId.set(block.fragment.blockId, block.frame);
-      byRuntimeOffset.set(block.fragment.from, block.frame);
-      for (const line of block.lines) {
-        for (const anchor of line.anchors) {
-          byRuntimeOffset.set(anchor.runtimeOffset, anchor.frame);
-        }
-      }
-      // P4d: derive per-table cell/edge rects from the attached plan.
-      if (block.kind === "table" && block.tablePlan) {
-        recordTableAnchors(
-          block.fragment.blockId,
-          block.frame,
-          block.tablePlan,
-          pxPerTwip,
-          tableCellRects,
-          tableColumnEdges,
-          tableRowEdges,
-        );
+      recordBlock(block, byRuntimeOffset);
+    }
+    // Refactor/05 Slice 7d: index non-body regions so header / footer /
+    // footnote chrome consumers can resolve `byFragmentId` /
+    // `byBlockId` / story-scoped `byRuntimeOffset` without falling
+    // back to body lookups. Each region's offsets are keyed on its
+    // own story (header offsets are header-local, etc.).
+    if (page.regions.header) recordStoryRegion(page.regions.header);
+    if (page.regions.footer) recordStoryRegion(page.regions.footer);
+    if (page.regions.footnotes) {
+      for (const footnote of page.regions.footnotes) {
+        recordStoryRegion(footnote);
       }
     }
   }
@@ -771,15 +812,22 @@ function buildAnchorIndex(
 
   const resolveByRuntimeOffset = (
     offset: number,
-    _story?: EditorStoryTarget,
+    story?: EditorStoryTarget,
   ): RenderFrameRect | null => {
-    void _story;
     const lookup = shiftForDeltas(offset);
-    const exact = byRuntimeOffset.get(lookup);
+    // Refactor/05 Slice 7d: pick the per-story offset map when the
+    // caller names a non-main story. Delta-shift is currently
+    // main-only — non-body stories don't receive predicted-dispatch
+    // deltas today, so the shift is a no-op for them.
+    const targetMap =
+      story && story.kind !== "main"
+        ? byRuntimeOffsetByStory.get(storyTargetKey(story)) ?? byRuntimeOffset
+        : byRuntimeOffset;
+    const exact = targetMap.get(lookup);
     if (exact) return exact;
     let best: RenderFrameRect | null = null;
     let bestDistance = Number.POSITIVE_INFINITY;
-    for (const [key, rect] of byRuntimeOffset) {
+    for (const [key, rect] of targetMap) {
       const distance = Math.abs(key - lookup);
       if (distance < bestDistance) {
         best = rect;
@@ -812,8 +860,16 @@ function buildAnchorIndex(
       // the anchor maps (see `shiftForDeltas` rationale above).
       const loShifted = shiftForDeltas(lo);
       const hiShifted = shiftForDeltas(hi);
+      // Refactor/05 Slice 7d: pick the per-story offset map when the
+      // selection lives in a non-main story (header / footer /
+      // footnote). Offsets are story-local so iterating the main map
+      // would never match.
+      const targetMap =
+        story && story.kind !== "main"
+          ? byRuntimeOffsetByStory.get(storyTargetKey(story)) ?? byRuntimeOffset
+          : byRuntimeOffset;
       let union: RenderFrameRect | null = null;
-      for (const [key, rect] of byRuntimeOffset) {
+      for (const [key, rect] of targetMap) {
         if (key < loShifted || key >= hiShifted) continue;
         union = unionRects(union, rect);
       }
@@ -855,6 +911,19 @@ function buildAnchorIndex(
       );
       return match?.frame ?? null;
     },
+    // Refactor/05 Slice 7c substrate: object-specific index. Falls back
+    // to `byBlockId` because the render kernel does not yet carry
+    // per-object metadata on anchor frames — the layout facet would
+    // need to emit `byObjectId` entries on the page graph. When that
+    // follow-up ships, populate a dedicated `byObjectIdMap` here and
+    // consult it before the `byBlockId` fallback. The fallback is
+    // correct for block-level drawings (whose object id equals their
+    // block id); it is `heuristic` for inline images (which share
+    // their block id with the enclosing paragraph). `object-handles.ts`
+    // tags those handles `precision: "heuristic"` accordingly.
+    byObjectId(objectId) {
+      return byBlockId.get(objectId) ?? null;
+    },
   };
 }