@beyondwork/docx-react-component 1.0.80 → 1.0.82

package/src/ui-tailwind/chrome-overlay/tw-chrome-overlay.tsx

@@ -251,6 +251,7 @@ export const TwChromeOverlay: React.FC<TwChromeOverlayProps> = ({
       {pageStackScrollRoot !== undefined ? (
         <TwPageStackChromeLayer
           facet={facet}
+          geometryFacet={geometryFacet}
           scrollRoot={pageStackScrollRoot}
           renderFrameRevision={renderFrameRevision ?? 0}
           activeStory={activeStory ?? { kind: "main" }}

package/src/ui-tailwind/chrome-overlay/tw-page-stack-overlay-layer.tsx

@@ -94,6 +94,99 @@ export interface VisiblePageIndexRange {
   end: number;
 }
 
+function pageOverlayRectsEqual(
+  a: readonly PageOverlayRect[],
+  b: readonly PageOverlayRect[],
+): boolean {
+  if (a === b) return true;
+  if (a.length !== b.length) return false;
+  for (let i = 0; i < a.length; i += 1) {
+    const left = a[i]!;
+    const right = b[i]!;
+    if (
+      left.pageId !== right.pageId ||
+      left.pageIndex !== right.pageIndex ||
+      left.topPx !== right.topPx ||
+      left.bottomPx !== right.bottomPx ||
+      left.heightPx !== right.heightPx
+    ) {
+      return false;
+    }
+  }
+  return true;
+}
+
+function pageOverlayLastBottom(rects: readonly PageOverlayRect[]): number {
+  let bottom = 0;
+  for (const rect of rects) {
+    if (rect.bottomPx > bottom) bottom = rect.bottomPx;
+  }
+  return bottom;
+}
+
+/**
+ * Page mode currently keeps the editable ProseMirror body as one natural DOM
+ * flow and paints page cards behind it. Layout geometry gives us the intended
+ * page frames, but browser-rendered PM content can exceed the final geometry
+ * frame (wide tables, fallback font metrics, or deliberately-degraded
+ * over-tall blocks). The decorative paper must follow that visible flow so
+ * text never appears directly on the workspace canvas.
+ */
+export function extendFinalPageOverlayRectToFlowHeight(
+  rects: readonly PageOverlayRect[],
+  flowHeightPx: number,
+): readonly PageOverlayRect[] {
+  if (rects.length === 0 || !Number.isFinite(flowHeightPx)) return rects;
+  const last = rects[rects.length - 1]!;
+  if (flowHeightPx <= last.bottomPx + 1) return rects;
+  return [
+    ...rects.slice(0, -1),
+    {
+      ...last,
+      bottomPx: flowHeightPx,
+      heightPx: Math.max(0, flowHeightPx - last.topPx),
+    },
+  ];
+}
+
+export function extendPageOverlayRectsAcrossTableBoundaryGaps(
+  rects: readonly PageOverlayRect[],
+  tableBoundaryIndices: readonly number[],
+): readonly PageOverlayRect[] {
+  if (rects.length === 0 || tableBoundaryIndices.length === 0) return rects;
+  const tableBoundaries = new Set(tableBoundaryIndices);
+  const byPageIndex = new Map<number, PageOverlayRect>();
+  for (const rect of rects) {
+    byPageIndex.set(rect.pageIndex, rect);
+  }
+
+  let changed = false;
+  const bridged = rects.map((rect) => {
+    if (!tableBoundaries.has(rect.pageIndex)) return rect;
+    const next = byPageIndex.get(rect.pageIndex + 1);
+    if (!next || next.topPx <= rect.bottomPx + 1) return rect;
+    changed = true;
+    return {
+      ...rect,
+      bottomPx: next.topPx,
+      heightPx: Math.max(0, next.topPx - rect.topPx),
+    };
+  });
+  return changed ? bridged : rects;
+}
+
+function mergePageOverlayRectsByPageIndex(
+  baseRects: readonly PageOverlayRect[],
+  flowRects: readonly PageOverlayRect[],
+): readonly PageOverlayRect[] {
+  if (baseRects.length === 0 || flowRects.length === 0) return baseRects;
+  const flowByIndex = new Map<number, PageOverlayRect>();
+  for (const rect of flowRects) {
+    flowByIndex.set(rect.pageIndex, rect);
+  }
+  return baseRects.map((rect) => flowByIndex.get(rect.pageIndex) ?? rect);
+}
+
 function normalizeVisiblePageIndexRange(
   range: VisiblePageIndexRange | null | undefined,
   pageCount: number,
@@ -126,6 +219,26 @@ function parsePageBoundaryIndex(prevPageId: string): number | undefined {
   return Number.parseInt(match[1] ?? "", 10);
 }
 
+function collectTableEmbeddedBoundaryIndices(
+  queryRoot: Pick<HTMLElement, "querySelectorAll"> | null,
+): number[] {
+  if (!queryRoot) return [];
+  const indices: number[] = [];
+  const widgets = Array.from(
+    queryRoot.querySelectorAll<HTMLElement>("[data-page-frame-end]"),
+  );
+  for (const widget of widgets) {
+    const prevPageId = widget.getAttribute("data-page-frame-end");
+    if (!prevPageId) continue;
+    const boundaryIndex = parsePageBoundaryIndex(prevPageId);
+    if (boundaryIndex === undefined) continue;
+    if (widget.closest("[data-pm-table-root='true'], table")) {
+      indices.push(boundaryIndex);
+    }
+  }
+  return indices;
+}
+
 /**
  * Pure helper: turn pre-measured page-boundary widget positions into
  * one `PageOverlayRect` per page.  No DOM access — the caller supplies
@@ -407,6 +520,39 @@ function resolveOffsetHeight(widget: HTMLElement): number {
   return widget.offsetHeight ?? 0;
 }
 
+function readElementFlowHeight(
+  element: HTMLElement | null,
+  options: { includeScrollHeight?: boolean } = {},
+): number {
+  if (!element) return 0;
+  let height = 0;
+  // geometry:allow-dom-fallback
+  height = Math.max(height, element.clientHeight || 0);
+  if (options.includeScrollHeight !== false) {
+    // geometry:allow-dom-fallback
+    height = Math.max(height, element.scrollHeight || 0);
+  }
+  if (height <= 0) {
+    // geometry:allow-dom-fallback
+    const rect = element.getBoundingClientRect();
+    height = Math.max(height, rect.height || 0);
+  }
+  return height;
+}
+
+function readOverlayFlowHeight(origin: HTMLElement | null): number {
+  if (!origin) return 0;
+  const parent = origin.parentElement instanceof HTMLElement
+    ? origin.parentElement
+    : null;
+  const parentHeight = readElementFlowHeight(parent);
+  if (parentHeight > 0) return parentHeight;
+  // Fallback only: do not read origin.scrollHeight here. The overlay's own
+  // absolutely-positioned paper cards can otherwise preserve a stale extended
+  // height after editable content shrinks.
+  return readElementFlowHeight(origin, { includeScrollHeight: false });
+}
+
 // ---------------------------------------------------------------------------
 // Component
 // ---------------------------------------------------------------------------
@@ -438,6 +584,10 @@ export interface TwPageStackOverlayLayerProps {
    * time this changes so the overlays stay aligned with content.
    */
   renderFrameRevision: number;
+  /**
+   * Kept for call-site compatibility. Paper-card backgrounds intentionally
+   * render every page; viewport culling belongs to heavier chrome layers.
+   */
   visiblePageIndexRange?: VisiblePageIndexRange | null;
   /** Optional test id applied to the overlay root. */
   "data-testid"?: string;
@@ -524,7 +674,6 @@ export const TwPageStackOverlayLayer: React.FC<TwPageStackOverlayLayerProps> = (
   geometryFacet,
   scrollRoot,
   renderFrameRevision,
-  visiblePageIndexRange,
   "data-testid": testId,
 }) => {
   // DS-C2 — prefer `ui.overlays.getAnchor({ kind: "page", ... })` as
@@ -542,12 +691,21 @@ export const TwPageStackOverlayLayer: React.FC<TwPageStackOverlayLayerProps> = (
     if (!geometryFacet) return [];
     const pageCount = facet.getPageCount();
     if (pageCount <= 0) return [];
+    // Paper-card backgrounds are cheap and must stay ahead of scroll. Heavy
+    // header/footer/footnote chrome still consumes `visiblePageIndexRange`;
+    // this decorative white-paper layer renders every card so fast scrolls
+    // never expose the gray canvas while the page window catches up.
     const warm = resolvePageOverlayRectsFromGeometry(
       geometryFacet,
       pageCount,
-      visiblePageIndexRange,
+      null,
     );
-    return warm ?? [];
+    return warm
+      ? extendPageOverlayRectsAcrossTableBoundaryGaps(
+          warm,
+          collectTableEmbeddedBoundaryIndices(scrollRoot),
+        )
+      : [];
   });
   // P3.d fix: the overlay root acts as the **measurement origin** so
   // widget `topPx` / `bottomPx` are expressed in the exact coordinate
@@ -576,12 +734,60 @@ export const TwPageStackOverlayLayer: React.FC<TwPageStackOverlayLayerProps> = (
   // tears down.
   const rafHandleRef = React.useRef<number | null>(null);
 
+  const setRectsIfChanged = React.useCallback(
+    (next: readonly PageOverlayRect[]) => {
+      setRects((prev) => (pageOverlayRectsEqual(prev, next) ? prev : next));
+    },
+    [],
+  );
+
+  const reconcilePaperRectsWithFlow = React.useCallback(
+    (
+      baseRects: readonly PageOverlayRect[],
+      pageCount: number,
+    ): readonly PageOverlayRect[] => {
+      if (baseRects.length === 0 || pageCount <= 0) return baseRects;
+      const origin = overlayRootRef.current;
+      const flowHeight = readOverlayFlowHeight(origin);
+      const bridgedBase = extendPageOverlayRectsAcrossTableBoundaryGaps(
+        baseRects,
+        collectTableEmbeddedBoundaryIndices(scrollRoot),
+      );
+      if (flowHeight <= 0) return bridgedBase;
+
+      const extendedBase = extendFinalPageOverlayRectToFlowHeight(
+        bridgedBase,
+        flowHeight,
+      );
+      if (!origin || !scrollRoot) return extendedBase;
+
+      // The common warm path has geometry and DOM flow in agreement. Avoid the
+      // full boundary-widget scan unless the PM flow is visibly taller than the
+      // geometry stack. When it is taller, the paper-card layer must follow the
+      // in-flow boundaries so content remains on paper instead of canvas.
+      if (flowHeight <= pageOverlayLastBottom(bridgedBase) + 1) {
+        return extendedBase;
+      }
+
+      const widgets = measureWidgetsViaBoundingRect(scrollRoot, origin, {
+        pageCount,
+        visiblePageIndexRange: null,
+      });
+      if (widgets.length === 0) return extendedBase;
+
+      const flowRects = resolvePageOverlayRects({
+        widgets,
+        pageCount,
+        scrollHeight: flowHeight,
+        visiblePageIndexRange: null,
+      });
+      const merged = mergePageOverlayRectsByPageIndex(extendedBase, flowRects);
+      return extendFinalPageOverlayRectToFlowHeight(merged, flowHeight);
+    },
+    [scrollRoot],
+  );
+
   const refreshRectsNow = React.useCallback(() => {
-    if (!scrollRoot) {
-      setRects([]);
-      return;
-    }
-    const origin = overlayRootRef.current;
     const pageCount = facet.getPageCount();
 
     // DS-C2 — first try the UI API seam so presentation code does not
@@ -608,12 +814,12 @@ export const TwPageStackOverlayLayer: React.FC<TwPageStackOverlayLayerProps> = (
       const uiRects = resolvePageOverlayRectsFromUiApi(
         ui,
         pageCount,
-        visiblePageIndexRange,
+        null,
         pageIds,
       );
       if (uiRects !== null) {
         incrementInvalidationCounter("overlay.page.ui_api.hit");
-        setRects(uiRects);
+        setRectsIfChanged(reconcilePaperRectsWithFlow(uiRects, pageCount));
         return;
       }
       incrementInvalidationCounter("overlay.page.ui_api.fallthrough");
@@ -630,54 +836,65 @@ export const TwPageStackOverlayLayer: React.FC<TwPageStackOverlayLayerProps> = (
       const geometryRects = resolvePageOverlayRectsFromGeometry(
         geometryFacet,
         pageCount,
-        visiblePageIndexRange,
+        null,
       );
       if (geometryRects !== null) {
-        setRects(geometryRects);
+        setRectsIfChanged(reconcilePaperRectsWithFlow(geometryRects, pageCount));
         return;
       }
     }
 
+    if (!scrollRoot) {
+      setRectsIfChanged([]);
+      return;
+    }
+    const origin = overlayRootRef.current;
+
     // Cold-open / pre-paint DOM fallback — warm path early-returned
     // above via `geometryFacet` or the UI-API resolver. Lines below
     // fire only before the first render frame.
     if (origin) {
       const widgets = measureWidgetsViaBoundingRect(scrollRoot, origin, {
         pageCount,
-        visiblePageIndexRange,
+        visiblePageIndexRange: null,
       });
       // geometry:allow-dom-fallback
       const originRect = origin.getBoundingClientRect();
-      setRects(
-        resolvePageOverlayRects({
-          widgets,
-          pageCount,
-          scrollHeight:
-            // geometry:allow-dom-fallback
-            origin.clientHeight > 0 ? origin.clientHeight : originRect.height,
-          visiblePageIndexRange,
-        }),
-      );
+      const domRects = resolvePageOverlayRects({
+        widgets,
+        pageCount,
+        scrollHeight:
+          // geometry:allow-dom-fallback
+          origin.clientHeight > 0 ? origin.clientHeight : originRect.height,
+        visiblePageIndexRange: null,
+      });
+      setRectsIfChanged(reconcilePaperRectsWithFlow(domRects, pageCount));
     } else {
       const widgets = measureWidgetsViaOffsetChain(scrollRoot, {
         pageCount,
-        visiblePageIndexRange,
+        visiblePageIndexRange: null,
       });
-      setRects(
-        resolvePageOverlayRects({
-          widgets,
-          pageCount,
-          // geometry:allow-dom-fallback
-          scrollHeight: scrollRoot.clientHeight,
-          visiblePageIndexRange,
-        }),
-      );
+      const domRects = resolvePageOverlayRects({
+        widgets,
+        pageCount,
+        // geometry:allow-dom-fallback
+        scrollHeight: scrollRoot.clientHeight,
+        visiblePageIndexRange: null,
+      });
+      setRectsIfChanged(reconcilePaperRectsWithFlow(domRects, pageCount));
     }
-  }, [facet, geometryFacet, scrollRoot, ui, visiblePageIndexRange]);
+  }, [
+    facet,
+    geometryFacet,
+    reconcilePaperRectsWithFlow,
+    scrollRoot,
+    setRectsIfChanged,
+    ui,
+  ]);
 
   const refreshRects = React.useCallback(() => {
     if (!scrollRoot) {
-      setRects([]);
+      refreshRectsNow();
       return;
     }
     const runtime = scrollRoot.ownerDocument?.defaultView as
@@ -724,6 +941,7 @@ export const TwPageStackOverlayLayer: React.FC<TwPageStackOverlayLayerProps> = (
   // Observe scroll-root size changes so zoom, viewport resize, or font
   // loading re-trigger measurement without a full app re-render.
   React.useEffect(() => {
+    if (geometryFacet) return;
     if (!scrollRoot) return;
     const runtime = scrollRoot.ownerDocument?.defaultView as
       | (Window & { ResizeObserver?: typeof ResizeObserver })
@@ -732,7 +950,7 @@ export const TwPageStackOverlayLayer: React.FC<TwPageStackOverlayLayerProps> = (
     const observer = new runtime.ResizeObserver(() => refreshRects());
     observer.observe(scrollRoot);
     return () => observer.disconnect();
-  }, [scrollRoot, refreshRects]);
+  }, [geometryFacet, scrollRoot, refreshRects]);
 
   // Observe DOM mutations so PM re-renders (page-break widgets added /
   // removed on relayout) re-trigger measurement.  We filter to
@@ -750,6 +968,7 @@ export const TwPageStackOverlayLayer: React.FC<TwPageStackOverlayLayerProps> = (
   // times within one animation frame coalesces into one measurement
   // pass instead of a per-mutation re-render storm.
   React.useEffect(() => {
+    if (geometryFacet) return;
     if (!scrollRoot) return;
     const runtime = scrollRoot.ownerDocument?.defaultView as
       | (Window & { MutationObserver?: typeof MutationObserver })
@@ -775,7 +994,7 @@ export const TwPageStackOverlayLayer: React.FC<TwPageStackOverlayLayerProps> = (
     // actually matters for the overlay's rect math.
     observer.observe(scrollRoot, { childList: true, subtree: false });
     return () => observer.disconnect();
-  }, [scrollRoot, refreshRects]);
+  }, [geometryFacet, scrollRoot, refreshRects]);
 
   // Always render the overlay root so the ref resolves on first paint.
   // Without the root element we never get a `getBoundingClientRect()`

package/src/ui-tailwind/editor-surface/pm-schema.ts

@@ -279,6 +279,28 @@ export const editorSchema = new Schema({
         const indentHanging = node.attrs.indentHanging as number | null;
         if (indentHanging) styles.push(`text-indent: -${indentHanging / 20}pt`);
         else if (indentFirstLine) styles.push(`text-indent: ${indentFirstLine / 20}pt`);
+        // Numbering marker-lane outdent (coord-04 §1.21 — "legal numbering
+        // touches the left margin / clips into page chrome"). Word/LO model:
+        // a numbered paragraph occupies `[markerLane.start, textColumn.right]`;
+        // the marker lane lives at `[textStart - hanging, textStart]`. When
+        // `hanging > indentLeft` the marker starts at negative x relative to
+        // the paragraph's content-frame origin — a legitimate Word scenario
+        // (w:ind w:left="360" w:hanging="720"). The marker span's
+        // `margin-left: -markerWidth` (emitted below) depends on the
+        // paragraph's content box actually reaching that far left; without
+        // this outdent the marker slides off the page frame and clips into
+        // surrounding chrome. `margin-left` expands the paragraph's content
+        // box leftward while keeping `padding-left` (body-text alignment)
+        // untouched.
+        const numberingMarkerStartTwips = node.attrs.numberingMarkerStart as
+          | number
+          | null;
+        if (
+          typeof numberingMarkerStartTwips === "number" &&
+          numberingMarkerStartTwips < 0
+        ) {
+          styles.push(`margin-left: ${numberingMarkerStartTwips / 20}pt`);
+        }
         const shadingColor = safeHexColor(node.attrs.shadingFill as string | null);
         if (shadingColor) styles.push(`background-color: ${shadingColor}`);
         // Paragraph borders. Reads the PublicBorderSpec shape
@@ -378,6 +400,27 @@ export const editorSchema = new Schema({
         if (contextualSpacingAfter) {
           attrs["data-contextual-spacing-after"] = "true";
         }
+        // Numbering geometry debug visibility (coord-04 §1.21 Deliverable D):
+        // expose the resolved marker lane on the paragraph element so parity
+        // investigators can inspect truth-vs-render without re-deriving the
+        // geometry. Values are twips; consumers convert at read time.
+        if (typeof numberingMarkerStartTwips === "number") {
+          attrs["data-numbering-marker-start-twips"] = String(numberingMarkerStartTwips);
+        }
+        const _numberingMarkerWidthTwips = node.attrs.numberingMarkerWidth as
+          | number
+          | null;
+        if (
+          typeof _numberingMarkerWidthTwips === "number" &&
+          _numberingMarkerWidthTwips > 0
+        ) {
+          attrs["data-numbering-marker-width-twips"] = String(
+            _numberingMarkerWidthTwips,
+          );
+        }
+        if (typeof indentLeft === "number") {
+          attrs["data-numbering-body-start-twips"] = String(indentLeft);
+        }
         if (styles.length > 0) attrs.style = styles.join("; ");
         const numberingPrefix = node.attrs.numberingPrefix as string | null;
         const numberingLevel = node.attrs.numberingLevel as number | null;
@@ -453,6 +496,17 @@ export const editorSchema = new Schema({
           if (hasResolvedMarkerWidth) {
             // P13.a: emit marker geometry in pt (twips/20 == pt) so it
             // self-scales under CSS `zoom` and matches Word's intent.
+            //
+            // Marker-lane contract (coord-04 §1.21 — Word/LO model):
+            // the marker occupies `[markerStart, markerStart + markerWidth]`
+            // where `markerStart = textStart - hanging`. The negative
+            // `margin-left` pulls the marker leftward by its own width into
+            // the paragraph's padding zone (`textStart - markerWidth`, since
+            // `padding-left = textStart`). When `markerStart < 0` the
+            // paragraph itself carries a compensating negative `margin-left`
+            // (emitted above at the paragraph-style branch) so its content
+            // box reaches far enough left to hold the marker without
+            // clipping into page chrome.
             const markerWidthPt = Math.max(1, numberingMarkerWidth / 20);
             prefixStyles.push(
               `width: ${markerWidthPt}pt`,
@@ -462,7 +516,6 @@ export const editorSchema = new Schema({
               `margin-right: 0`,
               `overflow: visible`,
             );
-            void numberingMarkerStart; // consumed via paragraph padding-left geometry
           } else {
             prefixStyles.push(
               `min-width: ${fallbackMinWidth}ch`,

package/src/ui-tailwind/editor-surface/tw-page-block-view.helpers.ts

@@ -205,6 +205,25 @@ export function buildParagraphStyle(
   if (indentHanging) style.textIndent = `-${indentHanging / 20}pt`;
   else if (indentFirstLine) style.textIndent = `${indentFirstLine / 20}pt`;
 
+  // Numbering marker-lane outdent (coord-04 §1.21 — "legal numbering
+  // touches the left margin / clips into page chrome"). Word/LO model:
+  // a numbered paragraph occupies `[markerLane.start, textColumn.right]`;
+  // the marker lane lives at `[textStart - hanging, textStart]`. When
+  // `hanging > indentLeft` the marker starts at negative x relative to
+  // the paragraph's content-frame origin — legitimate Word (e.g.
+  // w:ind w:left="360" w:hanging="720"). The marker span's
+  // `margin-left: -markerWidth` (emitted by `buildMarkerStyle`)
+  // depends on the paragraph's content box reaching that far left;
+  // without this outdent the marker slides off the page frame and
+  // clips into surrounding chrome. `margin-left` expands the
+  // paragraph's content box leftward while keeping body-text
+  // alignment (via `padding-left`) untouched. Mirrors the PM branch
+  // in `pm-schema.ts::paragraph.toDOM`.
+  const markerLaneStart = block.resolvedNumbering?.geometry.markerLane?.start;
+  if (typeof markerLaneStart === "number" && markerLaneStart < 0) {
+    style.marginLeft = `${markerLaneStart / 20}pt`;
+  }
+
   // Shading
   const shadingFill = block.shading?.fill;
   const shadingColor = safeHexColor(shadingFill);
@@ -341,6 +360,17 @@ export function buildMarkerStyle(
   const hasResolvedMarkerWidth = typeof markerWidth === "number" && markerWidth > 0;
   if (hasResolvedMarkerWidth) {
     // P13.a: emit marker geometry in pt so it self-scales under CSS `zoom`.
+    //
+    // Marker-lane contract (coord-04 §1.21 — Word/LO model): marker occupies
+    // `[markerStart, markerStart + markerWidth]` where
+    // `markerStart = textStart - hanging`. The negative `margin-left` pulls
+    // the marker leftward by its own width into the paragraph's padding
+    // zone. When `markerStart < 0` the paragraph carries a compensating
+    // negative `margin-left` via `buildParagraphStyle`, so the content box
+    // reaches far enough left to hold the marker without clipping into
+    // page chrome. `markerStart` is therefore consumed via the paragraph
+    // geometry — the marker span itself stays at `-markerWidth` relative
+    // to the paragraph's (now-outdented) content-box left.
     const markerWidthPt = Math.max(1, markerWidth! / 20);
     style.width = `${markerWidthPt}pt`;
     style.minWidth = `${markerWidthPt}pt`;
@@ -348,7 +378,7 @@ export function buildMarkerStyle(
     style.marginLeft = `-${markerWidthPt}pt`;
     style.marginRight = 0;
     style.overflow = "visible";
-    void markerStart; // consumed via paragraph padding-left geometry
+    void markerStart;
   } else {
     const fallbackMinWidth = Math.min(Math.max(prefix.length + 1, 4), 14);
     const fallbackMarginRight =

package/src/ui-tailwind/editor-surface/tw-page-block-view.tsx

@@ -126,6 +126,9 @@ function ParagraphBlock({
     "data-heading-level"?: string;
     "data-numbered"?: string;
     "data-contextual-spacing"?: string;
+    "data-numbering-marker-start-twips"?: string;
+    "data-numbering-marker-width-twips"?: string;
+    "data-numbering-body-start-twips"?: string;
   } = {
     className: classes.join(" "),
     style: Object.keys(pStyle).length > 0 ? pStyle : undefined,
@@ -140,6 +143,18 @@ function ParagraphBlock({
   if (block.contextualSpacing) {
     attrs["data-contextual-spacing"] = "true";
   }
+  // Numbering geometry debug visibility (coord-04 §1.21 Deliverable D):
+  // mirror the PM path so parity investigators can read the resolved
+  // marker lane directly off the DOM on both page 1 (PM) and pages 2+
+  // (static) renders. Values are twips.
+  const debugMarkerLane = block.resolvedNumbering?.geometry?.markerLane;
+  if (debugMarkerLane) {
+    attrs["data-numbering-marker-start-twips"] = String(debugMarkerLane.start);
+    if (debugMarkerLane.width > 0) {
+      attrs["data-numbering-marker-width-twips"] = String(debugMarkerLane.width);
+    }
+    attrs["data-numbering-body-start-twips"] = String(debugMarkerLane.textStart);
+  }
   if (block.bidi) {
     attrs.dir = "rtl";
   }

package/src/ui-tailwind/page-stack/tw-floating-image-layer.tsx

@@ -11,6 +11,7 @@ import type {
 import { preserveEditorSelectionMouseDown } from "../../ui/headless/preserve-editor-selection.ts";
 import {
   measureWidgetsViaBoundingRect,
+  resolvePageOverlayRectsFromGeometry,
   resolvePageOverlayRects,
   type PageOverlayRect,
   type VisiblePageIndexRange,
@@ -60,6 +61,19 @@ export const TwFloatingImageLayer: React.FC<TwFloatingImageLayerProps> = ({
   const [pageRects, setPageRects] = React.useState<readonly PageOverlayRect[]>([]);
 
   const refreshPageRectsNow = React.useCallback(() => {
+    const pageCount = facet.getPageCount();
+    if (geometryFacet) {
+      const geometryRects = resolvePageOverlayRectsFromGeometry(
+        geometryFacet,
+        pageCount,
+        visiblePageIndexRange,
+      );
+      if (geometryRects !== null) {
+        setPageRects(geometryRects);
+        return;
+      }
+    }
+
     if (!scrollRoot) {
       setPageRects([]);
       return;
@@ -69,7 +83,6 @@ export const TwFloatingImageLayer: React.FC<TwFloatingImageLayerProps> = ({
       setPageRects([]);
       return;
     }
-    const pageCount = facet.getPageCount();
     const widgets = measureWidgetsViaBoundingRect(scrollRoot, origin, {
       pageCount,
       visiblePageIndexRange,
@@ -84,11 +97,11 @@ export const TwFloatingImageLayer: React.FC<TwFloatingImageLayerProps> = ({
         visiblePageIndexRange,
       }),
     );
-  }, [facet, scrollRoot, visiblePageIndexRange]);
+  }, [facet, geometryFacet, scrollRoot, visiblePageIndexRange]);
 
   const refreshPageRects = React.useCallback(() => {
     if (!scrollRoot) {
-      setPageRects([]);
+      refreshPageRectsNow();
       return;
     }
     const runtime = scrollRoot.ownerDocument?.defaultView as
@@ -125,6 +138,9 @@ export const TwFloatingImageLayer: React.FC<TwFloatingImageLayerProps> = ({
   }, [refreshPageRects, renderFrameRevision, scrollRoot]);
 
   React.useEffect(() => {
+    if (geometryFacet) {
+      return;
+    }
     if (!scrollRoot) {
       return;
     }
@@ -137,9 +153,12 @@ export const TwFloatingImageLayer: React.FC<TwFloatingImageLayerProps> = ({
     const observer = new runtime.ResizeObserver(() => refreshPageRects());
     observer.observe(scrollRoot);
     return () => observer.disconnect();
-  }, [refreshPageRects, scrollRoot]);
+  }, [geometryFacet, refreshPageRects, scrollRoot]);
 
   React.useEffect(() => {
+    if (geometryFacet) {
+      return;
+    }
     if (!scrollRoot) {
       return;
     }
@@ -163,7 +182,7 @@ export const TwFloatingImageLayer: React.FC<TwFloatingImageLayerProps> = ({
     });
     observer.observe(scrollRoot, { childList: true, subtree: false });
     return () => observer.disconnect();
-  }, [refreshPageRects, scrollRoot]);
+  }, [geometryFacet, refreshPageRects, scrollRoot]);
 
   const items = React.useMemo(() => {
     const pxPerTwip = geometryFacet?.getRenderZoom()?.pxPerTwip;