@beyondwork/docx-react-component 1.0.66 → 1.0.69

package/src/runtime/layout/layout-engine-version.ts

@@ -221,8 +221,457 @@
  *       `resolved-formatting-document`, and `resolved-formatting-state`.
  *       Persisted prerender/layout caches must invalidate so geometry derived
  *       under v23 is never reused against the merged layout pipeline.
+ *  25 — Debug-infra D1 public-facet widening. `src/runtime/layout/public-facet.ts`
+ *       adds module-level `setActiveLayoutWarningEmitter` setter + private
+ *       `emitLayoutGuardWarning` helper, with call-site probes at the 10
+ *       silent-success `return []` guards (powers D1 stage-token lineage
+ *       for the `warning` telemetry channel). `src/runtime/layout/index.ts`
+ *       re-exports `setActiveLayoutWarningEmitter`. No pixel-geometry
+ *       change; the facet interface widened (new exported function), so
+ *       persisted envelopes from v24 should invalidate cleanly.
+ *  26 — Layer-03 Phase D (formatting-semantics refactor, earned bump).
+ *       `src/runtime/layout/table-render-plan.ts` +
+ *       `src/runtime/layout/public-facet.ts` flipped their imports from
+ *       the legacy `src/runtime/table-style-resolver.ts` to the canonical
+ *       `src/runtime/formatting/table-style-resolver.ts`. The 9 legacy
+ *       shim files at `src/runtime/*-resolver.ts` + friends were deleted.
+ *       No pixel-geometry change; cache envelopes from v25 invalidate
+ *       because the layout-engine import graph materially changed shape.
+ *       NOTE on prior unearned bumps: Layer-03 Slices 2 + 3 had previously
+ *       assigned 24 → 25 → 26 as "defensive" versions while the refactor
+ *       was under way; on code review those bumps were found to be
+ *       unearned and Phase A1 reverted to 24. With upstream having since
+ *       re-claimed 25 for debug-infra D1, this earned Layer-03 bump
+ *       lands at 26.
+ *  27 — Refactor/05 Slice 1: reserve `src/runtime/geometry/**` as its own
+ *       layer. New modules `geometry-types.ts`, `geometry-facet.ts` (thin
+ *       proxy over the existing layout facet + render kernel), `viewport.ts`
+ *       (stubbed), `invalidation.ts` (cache-key helper), and barrel
+ *       `index.ts`. The layout-engine-version CI guard's WATCHED_PREFIXES
+ *       now includes `src/runtime/geometry/` so future slices must bump
+ *       this constant when they touch the tree. The companion guard
+ *       `scripts/ci-check-geometry-no-dom-authority.mjs` ships alongside
+ *       (enforces G2 — DOM-origin reads forbidden outside `viewport.ts`).
+ *       No behavior change: the geometry facet delegates to the layout
+ *       facet's existing `hitTest` / `getAnchorRects`, and caret / envelope
+ *       / handle methods return null / empty stubs pending Slices 4–5.
+ *       Cache envelopes from v26 invalidate because the runtime's exported
+ *       module set changed (new `src/runtime/geometry/index.ts` barrel)
+ *       even though pixel geometry did not.
+ *  28 — Refactor/05 Slice 2a: move `resolveHitTest`, `hitTestRegion`,
+ *       `containsPoint`, and `resolveAnchorRects` from
+ *       `src/runtime/layout/public-facet.ts` into
+ *       `src/runtime/geometry/hit-test.ts` and
+ *       `src/runtime/geometry/project-anchors.ts`. Layout facet imports
+ *       from the new locations; its `hitTest` / `getAnchorRects` methods
+ *       remain wrapping those calls (deprecation + deletion lands in
+ *       Slice 6). `createGeometryFacet` gains an optional `renderKernel`
+ *       getter — when supplied, geometry resolves directly against the
+ *       kernel's current frame, bypassing the layout-facet proxy. New
+ *       CI guard `scripts/ci-check-no-layout-geometry-leak.mjs` rejects
+ *       DOM-origin reads inside `src/runtime/layout/**` +
+ *       `src/runtime/render/**` (dual of the geometry-no-dom-authority
+ *       guard). No pixel-geometry change; cache envelopes from v27
+ *       invalidate because the runtime's module exports and the layout
+ *       facet's internal dependency set changed.
+ *  29 — Refactor/05 Slice 2b: move `collectLineBoxesForRegion`,
+ *       `resolveRegionEntry`, `EMPTY_LINE_BOXES`, and the
+ *       `RuntimeLineBoxAlias` type from `public-facet.ts` into
+ *       `src/runtime/geometry/project-fragments.ts`; move
+ *       `collectScopeRailSegmentsForQuery` into
+ *       `src/runtime/geometry/project-anchors.ts` (with D1 warning probe
+ *       ported alongside). Layout facet imports from the new locations.
+ *       `GeometryFacet` gains `getBlockRects` (new impl — walks the render
+ *       frame, tags rects `space: "frame"`; required by Slice 5's
+ *       `v3 runtime.geometry.getBlockRects` live promotion), `getLineBoxes`,
+ *       `getScopeRailSegments`, and `getAllScopeRailSegments` methods —
+ *       the line-box and rail-segment methods delegate to the layout
+ *       facet's orchestration for now and flip to direct engine/graph
+ *       access during Slice 6. No pixel-geometry change; cache envelopes
+ *       from v28 invalidate because the layout facet's internal import
+ *       set changed again.
+ *  30 — Refactor/05 Slice 3a: real `src/runtime/geometry/viewport.ts`
+ *       implementation. `createViewportFromRoot({ root, pxPerTwip })`
+ *       attaches passive scroll + ResizeObserver listeners to the editor
+ *       root and rAF-coalesces fanouts — consumers subscribe via
+ *       `geometryFacet.subscribeViewport`. The Slice-1 stub
+ *       `createViewport()` is preserved for tests and unwired call sites.
+ *       `RootViewportHandle.setPxPerTwip` propagates zoom changes
+ *       synchronously so chrome overlays re-project without waiting for a
+ *       scroll event. Architecture 05 contract G2 exception is honored:
+ *       only `scrollLeft` / `scrollTop` are read here, and only from
+ *       inside `viewport.ts` (enforced by
+ *       `scripts/ci-check-geometry-no-dom-authority.mjs`).
+ *
+ *       `GeometryFacet` gains `getPage(target)` and `getBlock(blockId)` —
+ *       the substrate Slice 3b (overlay + scroll-anchor rewire) consumes
+ *       in place of DOM reads. Implementations are thin projections over
+ *       `frame.pages` / `frame.pages[*].regions.*.blocks`, tagged
+ *       `space: "frame"` per G5.
+ *
+ *       No pixel-geometry change; cache envelopes from v29 invalidate
+ *       because the facet surface widened (new `getPage` / `getBlock`
+ *       methods + `createViewportFromRoot` export) even though pixel
+ *       output is unchanged.
+ *  31 — Refactor/05 Slice 3b: rewire chrome consumers off DOM authority.
+ *       `src/ui-tailwind/chrome-overlay/tw-page-stack-overlay-layer.tsx`
+ *       gains an optional `geometryFacet` prop; when wired (and
+ *       `getPage(0)` resolves through the kernel), the overlay reads
+ *       page rects directly from the render frame via the new exported
+ *       helper `resolvePageOverlayRectsFromGeometry` — zero DOM reads,
+ *       zero forced layouts. The DOM-measurement path
+ *       (`measureWidgetsViaBoundingRect` / `ViaOffsetChain`) is kept as
+ *       the cold-open fallback per architecture 05 Slice 3 exit
+ *       criteria.
+ *
+ *       `src/ui-tailwind/editor-surface/scroll-anchor.ts` —
+ *       `findScrollAnchor` + `restoreScrollAnchor` gain an optional
+ *       `{ geometryFacet, prepaintFallback }` options arg. When wired,
+ *       block positions are computed from the kernel's frame coordinates
+ *       (`geometryFacet.getBlock(blockId).rects[0]`); the DOM path runs
+ *       only on cold-open or when `prepaintFallback: true` is
+ *       explicitly requested.
+ *
+ *       `scripts/ci-check-geometry-no-dom-authority.mjs` extends
+ *       `SCOPED_FILES` + `ALLOWED_FILES` to both chrome files so
+ *       additions to them are tracked; Slice 6 narrows `ALLOWED_FILES`
+ *       back to `viewport.ts` only.
+ *
+ *       No pixel-geometry change — the geometry-path rects are
+ *       byte-identical to the kernel frame rects they project from, and
+ *       the DOM fallback path is unchanged. Cache envelopes from v30
+ *       invalidate because the overlay and scroll-anchor public
+ *       signatures widened.
+ *  32 — Refactor/05 Slice-3 cleanup: relocate
+ *       `resolvePageOverlayRectsFromGeometry` from the overlay's `.tsx`
+ *       into `src/runtime/geometry/overlay-rects.ts` so the projection
+ *       math lives inside L05. Adds a classifier rule for
+ *       `test/runtime/geometry/` in `scripts/test-bundles.mjs` (previously
+ *       the bundle was empty because tests fell through the catch-all).
+ *       No behavior change; the overlay component re-exports the moved
+ *       symbol under its original name. Cache envelopes from v31
+ *       invalidate because the geometry layer's export surface widened
+ *       (new `overlay-rects.ts` module + new barrel export).
+ *  33 — Refactor/05 Slice 4: caret geometry as a first-class operation.
+ *       `src/runtime/geometry/caret-geometry.ts` ships
+ *       `resolveCaretGeometry(frame, offset, story?)` and
+ *       `resolveSelectionRects(frame, range)`. `GeometryFacet.getCaret`
+ *       and `getSelectionRects` replace their Slice-1 null/[] stubs
+ *       with real implementations routed through `frame.anchorIndex`
+ *       (the working substrate for offset-to-rect projection even when
+ *       per-line `RenderLine` anchors aren't populated).
+ *
+ *       Known Slice-4 caveats (documented in `caret-geometry.ts`):
+ *       `direction` is always `"ltr"` until run-level writing-direction
+ *       metadata arrives in a later slice; `getSelectionRects`
+ *       non-collapsed range returns the kernel's union rect (single
+ *       entry) until per-line anchors land and enable one-rect-per-line
+ *       enumeration. `baseline` is approximated at 0.8× height via the
+ *       cap-height heuristic.
+ *
+ *       No pixel-geometry change — caret rects are byte-identical to
+ *       the anchor index's projections, just reshaped into
+ *       `CaretGeometry`. Cache envelopes from v32 invalidate because
+ *       the geometry facet surface widened.
+ *  34 — Refactor/05 Slice 5: replacement envelope + object handles as
+ *       first-class operations.
+ *       `src/runtime/geometry/replacement-envelope.ts` ships
+ *       `resolveReplacementEnvelope(frame, scope, story?)` →
+ *       `EnvelopeBundle | null`. Range scopes produce `confidence:
+ *       "exact"`; detached scopes project the `lastKnownRange` with
+ *       `confidence: "detached"`. `scopeRects` routes through the
+ *       Slice-4 `resolveSelectionRects` helper so the envelope upgrades
+ *       to one-rect-per-line automatically when per-run anchors land.
+ *       `src/runtime/geometry/object-handles.ts` ships
+ *       `resolveObjectHandles(frame, objectId)` producing 9 zero-size
+ *       handle points (4 corners + 4 edge midpoints + 1 rotate anchor
+ *       20 px above the top-center) projected from the block bbox via
+ *       `frame.anchorIndex.byBlockId`.
+ *       `GeometryFacet` adds a `getCanonicalDocument?` input used by
+ *       `getReplacementEnvelope(scopeId)` to resolve scopes through
+ *       `src/runtime/workflow/scope-resolver.ts::resolveScope`. `getObjectHandles`
+ *       routes directly through the kernel frame.
+ *       v3 promotion: `src/api/v3/runtime/geometry.ts::getBlockRectsMetadata`
+ *       flips from `mock` to `live-with-adapter`; adapter wraps
+ *       `layout.getAnchorRects({kind:'block-id', value})` into
+ *       `BlockRectEntry.rects[]`. Mock shape retained as the headless
+ *       fallback.
+ *       No pixel-geometry change — envelope and handle rects are
+ *       byte-identical projections of existing anchor-index outputs.
+ *       Cache envelopes from v33 invalidate because the geometry facet
+ *       surface widened again (new `getCanonicalDocument` input + new
+ *       export `ReplacementScope`).
+ *  35 — Refactor/05 Slice 6 (layer closure): `GeometryDebugEntry` +
+ *       `buildGeometryDebugEntry` ship at
+ *       `src/runtime/geometry/projector.ts`, mirroring
+ *       `src/runtime/formatting/projector.ts`. The entry is wired into
+ *       `DebugInspectorSnapshot.geometry` as an optional field gated by
+ *       the `layout` telemetry channel (consumers must call
+ *       `bus.isEnabled("layout")` before materializing).
+ *       Plan frontmatter flips `status: PROPOSED → CLOSED` with
+ *       explicitly-documented deferred follow-ups (consumer flip +
+ *       gap reconciliation, wrapper deletion, CI-guard tightening,
+ *       `geometry.projected` emit, per-run anchors, v3 promotions).
+ *       Wiki pages `rendering-pipeline.md` + `selection-and-cursor.md`
+ *       bump `lastCuratedCommit` and gain closure status notes.
+ *       Closure evidence artifact lands at
+ *       `docs/reference/layer-05-geometry-projection-evidence-2026-04-22.{md,json}`.
+ *       No pixel-geometry change; cache envelopes from v34 invalidate
+ *       because a new debug-snapshot optional field is now part of the
+ *       runtime's exported shape.
+ *  36 — Layer-03 production-boundary pass §B. `resolved-formatting-state.ts
+ *       ::resolveDominantFont` now reads from `segment.resolvedRunFormatting`
+ *       (canonical L03 output) first, with `segment.markAttrs` fallback only
+ *       for viewport-culled blocks where the resolved output is absent.
+ *       Before: layout reconstructed dominant font from the surface
+ *       projection intermediate (`markAttrs`), bypassing the L03 cascade.
+ *       After: L04 measurement-path reads authoritative L03 output, matching
+ *       architecture §C2 ("formatting, layout, and geometry are separate
+ *       layers"). Pixel-identical on documents whose markAttrs agreed with
+ *       the cascade; fixes cases where the cascade carried a
+ *       character-style-chain font (`Heading 1` → `Cambria`) but markAttrs
+ *       lacked the override — line-height + avg-char-width now inherit the
+ *       cascade-resolved font. Cache envelopes from v35 invalidate because
+ *       dominant-font inputs to line-height + widow/keep-next measurement
+ *       changed shape.
+ *  37 — Refactor/04 Slice 3: activate the reserved `layout` telemetry
+ *       channel. `createLayoutEngine({ telemetryBus })` forwards the
+ *       granular `page_count_changed` / `page_field_dirtied` /
+ *       `layout_committed` events to the bus and additionally emits
+ *       `layout.recompute.completed` at the end of `fullRebuild` /
+ *       `incrementalRelayout` with `{ layoutEngineVersion, reasonKind,
+ *       scope, pageCountBefore, pageCountAfter, durationMs }`. Adds a
+ *       `LayoutDebugEntry` projector + `DebugInspectorSnapshot.layoutDebug`
+ *       section, both gated on `bus.isEnabled("layout")` — complementing
+ *       the `geometry?` section that v35 already gates on the same
+ *       channel. Zero cost when the channel is off (bitmap short-circuit
+ *       on every emit, `recomputeStart` sample skipped on the cold
+ *       path). No behavior change to pagination itself. Cache envelopes
+ *       from v36 invalidate because the `createLayoutEngine` options
+ *       shape widened (new optional `telemetryBus`) and a new optional
+ *       debug-snapshot field is now part of the runtime's exported
+ *       shape.
+ *  38 — Refactor/04 Slice 4. Multi-column `nextColumn` + column-aware
+ *       fragment routing. Pagination now tracks a per-block column
+ *       placement (`columnByBlockIdByPageIndex`) when the section layout
+ *       has `columns > 1`. `RuntimeBlockFragment.columnIndex` carries
+ *       that placement onto every fragment; `buildRegions` partitions
+ *       fragment ids into `RuntimePageRegions.columns[i].fragmentIds`
+ *       rather than leaving the per-column lists empty. Behavioral
+ *       changes: block-level `<w:br w:type="column"/>` inside a multi-
+ *       column section now routes subsequent fragments into the
+ *       advanced column region; column overflow pushes a new page that
+ *       inherits the section's column layout with the active column
+ *       reset to 0; single-column sections continue to route every
+ *       fragment to `regions.body` and leave `regions.columns`
+ *       undefined (F01 + 10 single-column CCEP regression preserved).
+ *       Section-level `<w:type w:val="nextColumn"/>` still degrades to
+ *       `continuous`-style page merging — cross-section column-state
+ *       carry is explicit follow-up work (tracked on react-refactor).
+ *       Cache envelopes from v37 invalidate because the per-page
+ *       fragment routing under multi-column layouts changes; single-
+ *       column envelopes remain shape-compatible but the version bump
+ *       ensures consumers re-derive regions rather than trust a stale
+ *       empty `columns[*].fragmentIds`.
+ *  39 — Refactor/05 Slice 6 wrapper-deletion pass (2026-04-22). Deletes
+ *       `hitTest` + `getAnchorRects` from `WordReviewEditorLayoutFacet`
+ *       interface + impl + inert stub. Geometry consumers now read through
+ *       `runtime.geometry.hitTest` / `.getAnchorRects`. The geometry-facet's
+ *       own layout-facet fallback paths were also deleted; unwired facet
+ *       returns null / [] directly. Persisted LayCache envelopes from v38
+ *       invalidate because the facet's interface shape changed.
+ *  40 — Refactor/06 Slice 4C rail-seam inversion (2026-04-22). The
+ *       layout facet's `getScopeRailSegments` / `getAllScopeRailSegments`
+ *       / `getAllScopeCardModels` methods are removed; rail + scope-
+ *       card composition is now Layer-06-owned via
+ *       `runtime.workflow.*`. The `getWorkflowRailInput` /
+ *       `getWorkflowMarkupMetadata` / `getSuggestionsSnapshot` config
+ *       hooks on `CreateLayoutFacetInput` are removed since the facet
+ *       no longer consumes workflow state. Geometry-facet's
+ *       `getScopeRailSegments` / `getAllScopeRailSegments` proxies are
+ *       removed. No pixel-geometry change, but the public layout
+ *       surface shape changed, so cache envelopes from v39 invalidate.
+ */
+/*
+ * v40 (2026-04-22) — refactor/04 post-Slice-4 cross-section column
+ *   carry. Section-level `<w:type w:val="nextColumn"/>` between two
+ *   matching multi-column sections now advances column state across
+ *   the boundary: section N is seeded with `startColumnIndex =
+ *   prevEndColumn + 1` when prev ended with room; otherwise a new
+ *   page pushes with column index 0 (matching Word's behavior).
+ *   Single-column sections still degrade to `continuous` (F01 + CCEP
+ *   regression preserved). Mismatched column counts degrade to
+ *   `nextPage`. New optional `startColumnIndex` parameter on
+ *   `paginateSectionBlocksWithSplits`; new
+ *   `endColumnByGlobalPageIndex` tracking in
+ *   `paginateAllSectionsWithSplits` feeds the decision. Persisted
+ *   LayCache envelopes from v39 invalidate because documents with
+ *   cross-section multi-column content paginate differently under
+ *   v40 (blocks that previously landed at `columnIndex: 0` after a
+ *   `nextColumn` section break now land at `columnIndex: 1+`).
+ *   Single-column documents are pagination-identical to v39.
+ */
+/*
+ * v41 (2026-04-22) — refactor/05 cross-lane-coord pass. Adds
+ *   `getRenderFrame` + `getRenderZoom` to `GeometryFacet` (passthrough
+ *   to the render kernel) so UI chrome consumers can flip their reads
+ *   off the layout-facet's now-@deprecated `getRenderFrame` /
+ *   `getRenderZoom` methods without losing access to the underlying
+ *   kernel primitives. Per Layer 04's cross-layer-coord §1.1 ask:
+ *   those two methods are the last remaining geometry-shaped
+ *   accessors on the layout facet; they exit once UI consumers flip.
+ *   Shape change on `GeometryFacet` invalidates persisted v40 cache
+ *   envelopes via the top-level version discriminator.
+ */
+/*
+ * v42 (2026-04-22) — refactor/05 cross-lane-coord §8.4–§8.6 completion.
+ *   Deletes `getRenderFrame` + `getRenderZoom` from the layout facet
+ *   interface + impl + inert stub. Consumers (5 UI chrome files + 4
+ *   tests) were migrated in the same pass to read through
+ *   `runtime.geometry.getRenderFrame` / `.getRenderZoom`. Per L04's
+ *   cross-layer-coord §1.1, the layout facet now exposes layout-only
+ *   reads — no more geometry-shaped accessors. Cache envelopes from
+ *   v41 invalidate via the top-level version discriminator.
+ */
+/*
+ * v43 (2026-04-22) — refactor/04 post-closure Task 4: endnote reservation
+ *   bug fix. `estimateFootnoteReservation` in `paginated-layout-engine.ts`
+ *   now skips `noteKind === "endnote"` during per-page reservation math,
+ *   matching the pre-existing skip in `snapshotNoteAllocations` (the
+ *   emission path). Prior behavior inflated `reservedNoteHeight` with
+ *   endnote body estimates on every page that referenced an endnote,
+ *   squeezing body content onto additional pages even though endnotes
+ *   flow to the document-end endnote area (P8.2, `getDocumentEndnoteBlocks`).
+ *   Footnote behavior is unchanged. Cache envelopes from v42 invalidate
+ *   because documents containing endnotes paginate differently under v43
+ *   (fewer body pages when endnote bodies are large); footnote-only and
+ *   note-free documents are pagination-identical to v42.
+ */
+/*
+ * v44 (2026-04-22) — refactor/04 cross-layer-coord §1.12 Pass 2. Pure
+ *   type relocation: `RuntimePageGraph`, `RuntimePageNode`, and
+ *   `BuildPageGraphInput` move from `src/runtime/layout/page-graph.ts`
+ *   into `src/model/layout/runtime-page-graph-types.ts`, along with
+ *   their dependencies (`PageLayoutSnapshot`, `EditorStoryTarget`,
+ *   `DocumentPageSnapshot`, `ResolvedPageStories`,
+ *   `ResolvedDocumentSection` — the first three re-exported from
+ *   `src/api/public-types.ts`, the latter two from their prior runtime
+ *   homes, for consumer-import stability). `src/runtime/prerender/
+ *   cache-envelope.ts` now imports `RuntimePageGraph` from model
+ *   rather than runtime — cutting Layer 01's session→runtime transit
+ *   through `CacheEnvelope` (L01 coord §1 primary ask). Graph
+ *   construction (`buildPageGraph`, `spliceGraph`, `graphRevision`)
+ *   stays in `src/runtime/layout/page-graph.ts`. Zero behavior change;
+ *   cache envelopes from v43 invalidate because the layout-engine
+ *   import graph materially changed shape (page-graph.ts's type
+ *   declarations are now re-exports from model).
+ */
+/*
+ * v47 (2026-04-23) — refactor/04 coord §1.15 / §1.18 — `FONT_AVG_CHAR_WIDTH`
+ *   calibration against OpenType xAvgCharWidth. Pre-calibration values
+ *   (Calibri 9.0 twips/half-point, TNR 9.2, etc.) were ~80% higher than
+ *   published font metrics, producing a 50-73% runtime page overcount
+ *   vs LibreOffice on CCEP contracts. Post truth-baseline's 2026-04-23
+ *   oracle re-extraction (bundle 34d860831fe32b38) the miscalibration
+ *   was isolated to the empirical measurement backend; the canvas
+ *   backend measures real glyph widths via Canvas2D and is unaffected.
+ *
+ *   New values are derived from each font's published xAvgCharWidth
+ *   (OpenType OS/2 table) expressed as em-fraction × twips-per-em at
+ *   the given font size. For Calibri: xAvgCharWidth = 1037/2048 em ≈
+ *   0.506em → at 11pt (22 half-points) = 5.57pt = 111 twips per char,
+ *   matching the new factor of 5.0 × 22 = 110. The remaining 16 fonts
+ *   in the table were recalibrated on the same basis.
+ *
+ *   Impact on the 5 CCEP docs with re-extracted oracles:
+ *     aps-short-form-supply-of-services    39 → 25   pages (−3.8% vs oracle 26)
+ *     aps-supply-of-services                45 → 29   pages (+11.5% vs oracle 26)
+ *     eu-global-consultancy-services        61 → 40   pages (+5.3%  vs oracle 38)
+ *     eu-global-supply-of-services          41 → 27   pages (+12.5% vs oracle 24)
+ *     eu-tactical-sourcing-team-agreement    7 →  5   pages (−16.7% vs oracle  6)
+ *
+ *   Baseline was 50-73% overcount across the four large docs; post-
+ *   calibration deltas are −16.7% to +12.5%. 2/5 docs now within ±10%
+ *   of oracle; residual over/under is attributable to secondary
+ *   factors (widow/orphan, keep-with-next, minor per-font refinement).
+ *
+ *   New `test/runtime/layout/ccep-multi-doc-parity-probe.test.ts`
+ *   loads oracle page counts from the trusted-oracle dumps at
+ *   `services/debug/scripts/.reports/diagnose-oracle-raw-*.json` at
+ *   read time — the probe is single-source-of-truth: no oracle page
+ *   counts are hardcoded anywhere in the runtime or the probe.
+ *
+ *   Two factor-encoding unit tests in
+ *   `test/runtime/layout/paginated-layout-engine.test.ts` were
+ *   updated to the new expected values; one `pagination-state.test.ts`
+ *   test was narrowed to its structural-invariant assertion (the
+ *   column-definitions survive) rather than the measurement-specific
+ *   page-count/offset values it had encoded. Cache envelopes from v46
+ *   invalidate because pagination output changes for every document
+ *   whose dominant font has a corrected factor (which is effectively
+ *   all documents — the `DEFAULT_FONT_AVG_CHAR_WIDTH` fallback also
+ *   shifted 10.0 → 5.5).
+ */
+/*
+ * v46 (2026-04-23) — refactor/04 post-closure Task 5: compat-input
+ *   ledger + projector exposure. New module
+ *   `src/runtime/layout/compat-input-ledger.ts` exports
+ *   `resolveLayoutCompatInputs(settings)` → typed `LayoutCompatInputs`
+ *   snapshot covering seven named compat fields (compatibilityMode,
+ *   doNotExpandShiftReturn, useWord97LineBreakRules, useFELayout,
+ *   doNotUseHTMLParagraphAutoSpacing,
+ *   overrideTableStyleFontSizeAndJustification,
+ *   differentiateMultirowTableHeaders) plus passthrough buckets for
+ *   every unknown `<w:compatSetting>` / `<w:compat>` boolean flag.
+ *   `src/runtime/layout/projector.ts::buildLayoutDebugEntry` gains an
+ *   optional `settings` input; when supplied, the entry's new
+ *   `compatInputs` field surfaces the resolved ledger.
+ *   `src/runtime/debug/build-debug-inspector-snapshot.ts` threads
+ *   `document.subParts.settings` into the projector. LayoutDebugEntry
+ *   `schemaVersion` bumps 1 → 2. Zero pagination behavior change —
+ *   the ledger is pure diagnostic wiring today; future behavioral
+ *   branches that gate on a compat flag now have a canonical access
+ *   point instead of ad-hoc `settings.compatFlags?.[...]` reads.
+ *   Cache envelopes from v45 invalidate because the layout module
+ *   export surface widened (new `compat-input-ledger.ts` module + new
+ *   optional projector field).
+ */
+/*
+ * v45 (2026-04-23) — refactor/04 post-closure Task 3: measurement
+ *   provider becomes authoritative. Three changes land under
+ *   `src/runtime/layout/**`:
+ *
+ *   1. `paginated-layout-engine.ts` threads a real
+ *      `Map<RunId, ResolvedRunFormatting>` into both
+ *      `measureLineFragments` call sites via the new
+ *      `buildRunFormattingMap(block)` helper in
+ *      `resolved-formatting-state.ts`. The empirical backend still
+ *      ignores `runs` (paragraph-level metrics suffice — same
+ *      numerical output), but the canvas backend now reads
+ *      `runs.get("${blockId}:${segmentId}")` for per-run font
+ *      metrics so paragraphs with mixed inline fonts / sizes /
+ *      weights produce accurate canvas-measured line counts.
+ *   2. `measurement-backend-empirical.ts` + `measurement-backend-
+ *      canvas.ts` `measureLineFragments` now delegate image-segment
+ *      line-displacement to their own `measureInlineObject` method
+ *      instead of inlining `display === "floating" ? 2 : 1`. Zero
+ *      numerical change; the provider method is now live inside
+ *      each backend, so future work can specialize displacement
+ *      math (e.g., canvas-backend ceil(heightTwips/lineHeight))
+ *      without touching the line-fragments inner loop.
+ *   3. `layout-measurement-provider.ts` docstring clarifies that
+ *      `measureTableBlock` is a coarse standalone helper and
+ *      production table measurement goes through
+ *      `src/runtime/layout/table-row-split.ts::measureTableRowHeights`
+ *      (which already threads this provider through for per-cell
+ *      paragraph measurement).
+ *
+ *   Persisted envelopes from v44 invalidate because the runs-map
+ *   input to canvas `measureLineFragments` and the backend
+ *   dispatch topology changed shape. Empirical-backend numerical
+ *   output is identical.
  */
-export const LAYOUT_ENGINE_VERSION = 24 as const;
+export const LAYOUT_ENGINE_VERSION = 47 as const;
 
 /**
  * Serialization schema version for the LayCache payload (the cache envelope

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

@@ -0,0 +1,60 @@
+/**
+ * Layer 04 — `LayoutFacet` type surface.
+ *
+ * Per `docs/architecture/04-layout-semantics.md` and refactor plan Slice 2,
+ * `LayoutFacet` is the refactor-era structural name for the semantic layout
+ * surface consumers type against. The factory lives at
+ * `createLayoutFacet` in `./public-facet.ts`; the interface itself continues
+ * to be declared there as `WordReviewEditorLayoutFacet` — the long-standing
+ * public-API name — and `LayoutFacet` is a type alias.
+ *
+ * Why alias rather than relocate:
+ * - `WordReviewEditorLayoutFacet` is part of the package's public type
+ *   surface and is imported by 49 sites plus the consumer-facing public-API
+ *   reference. Relocating the declaration would churn all of them with no
+ *   behavioral gain.
+ * - Declaring `LayoutFacet` as an alias at a stable import path gives
+ *   consumers (runtime API, stateless services, debug inspectors, tests)
+ *   a single short name to depend on during the refactor, independent of
+ *   the public type that continues to anchor the public API.
+ *
+ * Consumers imported `WordReviewEditorLayoutFacet` from `./public-facet.ts`
+ * before Slice 2; they may switch to `LayoutFacet` from
+ * `./layout-facet-types.ts` at their own cadence. Both names resolve to
+ * the identical interface and remain assignment-compatible in both
+ * directions.
+ *
+ * Associated read-model types referenced in facet signatures are
+ * re-exported here so consumers can pull the whole type surface from one
+ * module.
+ */
+
+export type {
+  // Facet surface --------------------------------------------------------
+  WordReviewEditorLayoutFacet as LayoutFacet,
+  WordReviewEditorLayoutFacet,
+
+  // Read-model types ----------------------------------------------------
+  PublicPageNode,
+  PublicPageRegions,
+  PublicPageRegion,
+  PublicRegionBlock,
+  PublicRegionKind,
+  PublicBlockFragment,
+  PublicLineBox,
+  PublicNoteAllocation,
+  PublicPageAnchor,
+  PublicPageSpan,
+  PublicSectionNode,
+  PublicResolvedPageStories,
+  PublicResolvedParagraphFormatting,
+  PublicResolvedRunFormatting,
+  PublicBlockMeasurement,
+  PublicMeasurementFidelity,
+  PublicFieldDirtinessReport,
+
+  // Events + invalidation ----------------------------------------------
+  LayoutFacetEvent,
+  LayoutFacetInvalidationReason,
+  RenderZoomSummary,
+} from "./public-facet.ts";

package/src/runtime/layout/layout-measurement-provider.ts

@@ -74,6 +74,19 @@ export interface MeasuredTableBlock {
   rowHeights: number[];
 }
 
+/**
+ * Task 3 (2026-04-23) note on `measureTableBlock`: the production
+ * table-measurement path is `src/runtime/layout/table-row-split.ts
+ * ::measureTableRowHeights`, which threads this provider through for
+ * per-cell paragraph measurement and integrates with `findTableRowSplit`
+ * for pagination. `measureTableBlock` on this contract remains a
+ * coarse standalone helper (used when a table's height is needed
+ * without row-split context). Both empirical and canvas backends
+ * implement it with the same lightweight estimation; consumers that
+ * need accurate per-cell measurement should call `measureTableRowHeights`
+ * directly.
+ */
+
 export interface LayoutMeasurementProvider {
   readonly fidelity: MeasurementFidelity;
   /**

package/src/runtime/layout/measurement-backend-canvas.ts

@@ -214,11 +214,23 @@ export function createCanvasBackend(
           currentLineWidth = 0;
           currentCapacity = subsequentLineWidth;
           break;
-        case "image":
-          lineCount += segment.display === "floating" ? 2 : 1;
+        case "image": {
+          // Route through this backend's own `measureInlineObject` so
+          // the provider contract is live inside the canvas backend
+          // (Task 3, 2026-04-23). Intrinsic dimensions are not carried
+          // on the surface segment here; backends that later want
+          // glyph-height-aware displacement can resolve from the
+          // segment's `anchor.extent` at the caller.
+          const measured = measureInlineObject({
+            widthTwips: 0,
+            heightTwips: 0,
+            display: segment.display === "floating" ? "floating" : "inline",
+          });
+          lineCount += Math.max(1, measured.displacedLineCount);
           currentLineWidth = 0;
           currentCapacity = subsequentLineWidth;
           break;
+        }
         case "note_ref":
         case "opaque_inline":
           // Treat as a single narrow character.

package/src/runtime/layout/measurement-backend-empirical.ts

@@ -31,24 +31,37 @@ const TABLE_ROW_PADDING_TWIPS = 120;
 
 export function createEmpiricalBackend(): LayoutMeasurementProvider {
   const fidelity: MeasurementFidelity = "empirical";
-  return {
+  // `measureLineFragments` dispatches through the backend object's own
+  // `measureInlineObject` method at call time (not via closure capture)
+  // so consumers can swap the inline measurement strategy after
+  // construction — Task 3 (2026-04-23) routed image segments through
+  // the provider contract instead of hardcoded displacement math.
+  const backend: LayoutMeasurementProvider = {
     get fidelity() {
       return fidelity;
     },
     whenReady() {
       return Promise.resolve();
     },
-    measureLineFragments,
+    measureLineFragments(input) {
+      return measureLineFragments(input, (objectInput) =>
+        backend.measureInlineObject(objectInput),
+      );
+    },
     measureInlineObject,
     measureTableBlock,
     invalidateCache() {
       /* no cache in empirical mode */
     },
   };
+  return backend;
 }
 
 function measureLineFragments(
   input: MeasureLineFragmentsInput,
+  inlineObjectMeasurer: (
+    objectInput: MeasureInlineObjectInput,
+  ) => MeasuredInlineObject,
 ): MeasuredLineFragments {
   const { block, formatting, columnWidth } = input;
   const firstLineWidth = resolveTextWidth(formatting, columnWidth, true);
@@ -93,11 +106,17 @@ function measureLineFragments(
         currentLineChars = 0;
         currentLineCapacity = subsequentLineCapacity;
         break;
-      case "image":
-        lineCount += segment.display === "floating" ? 2 : 1;
+      case "image": {
+        const measured = inlineObjectMeasurer({
+          widthTwips: 0,
+          heightTwips: 0,
+          display: segment.display === "floating" ? "floating" : "inline",
+        });
+        lineCount += Math.max(1, measured.displacedLineCount);
         currentLineChars = 0;
         currentLineCapacity = subsequentLineCapacity;
         break;
+      }
       case "note_ref":
         currentLineChars += 1;
         if (currentLineChars > currentLineCapacity) {