@beyondwork/docx-react-component 1.0.41 → 1.0.43

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

@@ -16,6 +16,8 @@ import * as React from "react";
 import type { OverlayCoordinateSpace } from "./chrome-overlay-projector";
 import type { ScopeRailSegment } from "../../runtime/layout";
 import type {
+  EditorRole,
+  EditorStoryTarget,
   ScopeIssueAction,
   TableStructureContextSnapshot,
   WordReviewEditorLayoutFacet,
@@ -23,6 +25,8 @@ import type {
 } from "../../api/public-types";
 import { TwScopeRailLayer } from "./tw-scope-rail-layer";
 import { TwScopeCardLayer } from "./tw-scope-card-layer";
+import { TwPageStackOverlayLayer } from "./tw-page-stack-overlay-layer";
+import { TwPageStackChromeLayer, type PmPortalView } from "../page-stack/tw-page-stack-chrome-layer";
 import { TwTableGripLayer } from "../chrome/tw-table-grip-layer";
 
 export interface TwChromeOverlayProps {
@@ -64,6 +68,26 @@ export interface TwChromeOverlayProps {
     issueId: string,
     action: ScopeIssueAction,
   ) => void;
+  /**
+   * R3 — scope card suggestion-group accept fired.  The owner relays
+   * to `ref.acceptSuggestionGroup(groupId)`.
+   */
+  onScopeCardAcceptSuggestionGroup?: (scopeId: string, groupId: string) => void;
+  /** R3 — suggestion-group reject. */
+  onScopeCardRejectSuggestionGroup?: (scopeId: string, groupId: string) => void;
+  /**
+   * K2 — scope card "Ask review agent" button fired.  The owner
+   * emits `agent-on-selection-requested` via WordReviewEditorEvent.
+   * Button is hidden when this handler is not supplied.
+   */
+  onScopeCardAskAgent?: (scopeId: string) => void;
+  /** P3 — active editor role; drives card visibility matrix. */
+  editorRole?: EditorRole;
+  /**
+   * P3 — scope-tag editor slot (workflow role only).  Renders between
+   * the card's mode row and issue row when present.
+   */
+  scopeCardScopeTagEditor?: React.ReactNode;
   /** Test id applied to the overlay root. */
   "data-testid"?: string;
   /** Optional extra children (e.g., future comment balloon layer). */
@@ -80,6 +104,54 @@ export interface TwChromeOverlayProps {
     twips: number,
     rule: "auto" | "atLeast" | "exact",
   ) => void;
+
+  // Page-stack overlay (P3.b) -------------------------------------------
+  /**
+   * Scroll root that hosts the PM surface + page-break widgets.  The page-
+   * stack overlay measures widget positions from this element to derive
+   * per-page Y-ranges.  When omitted, the page-stack overlay is skipped —
+   * consumers in canvas workspace mode or tests without a DOM can pass
+   * `null` to disable the overlay cleanly.
+   */
+  pageStackScrollRoot?: HTMLElement | null;
+  /**
+   * Render-frame revision tick — incremented by the workspace on
+   * `zoom_changed` / `render_frame_ready` / `incremental_relayout` events.
+   * Drives re-measurement of the page-stack overlay without triggering a
+   * full workspace re-render.
+   */
+  renderFrameRevision?: number;
+
+  // Page-stack chrome layer (P8.8) --------------------------------------
+  /**
+   * Current active story target — the page-stack chrome layer uses this
+   * to decide which per-page band (if any) should render in active-slot
+   * mode.  When omitted the chrome layer treats `{ kind: "main" }` as
+   * the active story, so no band is promoted.
+   */
+  activeStory?: EditorStoryTarget;
+  /**
+   * Fired when the user clicks a per-page header / footer band to
+   * promote it into the active editing surface.  Task 10 will route PM
+   * into the matching band via React portals; today the handler is a
+   * pass-through to `runtime.openStory`.
+   */
+  onOpenStory?: (target: EditorStoryTarget) => void;
+  /**
+   * P8.11 — PM surface DOM element (`.ProseMirror` div).  The chrome
+   * layer's portal mechanism reparents this element across the per-page
+   * band portal slots as `activeStory` changes.  When omitted the
+   * reparent step is skipped; the chrome layer still renders read-only
+   * bands but the active-slot promotion is inert.
+   */
+  pmSurfaceElement?: HTMLElement | null;
+  /**
+   * P8.11 — optional PM view handle with `hasFocus()` + `focus()`.  When
+   * supplied, the chrome layer re-focuses PM after a portal swap so
+   * mid-edit band clicks don't silently drop the caret.  Omitting the
+   * handle leaves focus-restore as a no-op — DOM reparent still runs.
+   */
+  pmView?: PmPortalView | null;
 }
 
 /**
@@ -100,11 +172,22 @@ export const TwChromeOverlay: React.FC<TwChromeOverlayProps> = ({
   onScopeCardClose,
   onScopeCardModeChange,
   onScopeCardIssueAction,
+  onScopeCardAcceptSuggestionGroup,
+  onScopeCardRejectSuggestionGroup,
+  onScopeCardAskAgent,
+  editorRole,
+  scopeCardScopeTagEditor,
   "data-testid": testId,
   children,
   tableContext,
   onSetColumnWidth,
   onSetRowHeight,
+  pageStackScrollRoot,
+  renderFrameRevision,
+  activeStory,
+  onOpenStory,
+  pmSurfaceElement,
+  pmView,
 }) => {
   return (
     <div
@@ -112,6 +195,24 @@ export const TwChromeOverlay: React.FC<TwChromeOverlayProps> = ({
       data-testid={testId ?? "chrome-overlay"}
       role="presentation"
     >
+      {pageStackScrollRoot !== undefined ? (
+        <TwPageStackOverlayLayer
+          facet={facet}
+          scrollRoot={pageStackScrollRoot}
+          renderFrameRevision={renderFrameRevision ?? 0}
+        />
+      ) : null}
+      {pageStackScrollRoot !== undefined ? (
+        <TwPageStackChromeLayer
+          facet={facet}
+          scrollRoot={pageStackScrollRoot}
+          renderFrameRevision={renderFrameRevision ?? 0}
+          activeStory={activeStory ?? { kind: "main" }}
+          onOpenStory={onOpenStory}
+          pmSurfaceElement={pmSurfaceElement}
+          pmView={pmView}
+        />
+      ) : null}
       <TwScopeRailLayer
         facet={facet}
         space={space}
@@ -125,6 +226,11 @@ export const TwChromeOverlay: React.FC<TwChromeOverlayProps> = ({
         onClose={onScopeCardClose ?? noop}
         onModeChange={onScopeCardModeChange ?? noopModeChange}
         onIssueAction={onScopeCardIssueAction ?? noopIssueAction}
+        onAcceptSuggestionGroup={onScopeCardAcceptSuggestionGroup}
+        onRejectSuggestionGroup={onScopeCardRejectSuggestionGroup}
+        onAskAgent={onScopeCardAskAgent}
+        editorRole={editorRole}
+        scopeTagEditor={scopeCardScopeTagEditor}
         space={space}
       />
       <TwTableGripLayer

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

@@ -0,0 +1,527 @@
+/**
+ * TwPageStackOverlayLayer — per-page paper-frame overlays for pages 2..N.
+ *
+ * Before this layer, a multi-page document rendered as ONE long page-shaped
+ * container with the `wre-page-chrome` shadow + border painted on the outer
+ * workspace `<div>`.  The inter-page widgets from
+ * `pm-page-break-decorations.ts` produced footer + canvas gap + header
+ * visuals between pages, but the outer shadow spanned the whole stack — so
+ * the user perceived one long paper, not N distinct papers.
+ *
+ * This layer composes over the PM surface inside the chrome overlay and
+ * paints an additional rounded-rectangle overlay behind each page's body
+ * region.  Page 1 keeps its shadow from the outer wrapper (the `wre-page-
+ * chrome` class); page 2..N get their own paper-frame overlay via this
+ * layer.  The overlays are purely decorative — `pointer-events: none`,
+ * `aria-hidden="true"`, z-index underneath the PM text — so they never
+ * interfere with selection, caret, or chrome interaction.
+ *
+ * Positioning strategy
+ * --------------------
+ *
+ * PM renders the body as a single continuous flow and the P3.a
+ * `pm-page-break-decorations` widgets mark every page boundary with
+ * `data-page-frame-end={prevPageId}` / `data-page-frame-start={nextPageId}`
+ * attributes.  This layer queries those markers from the overlay's owning
+ * scroll root, computes each page's Y-range in DOM coordinate space, and
+ * emits one `<div>` per page at that range.
+ *
+ * - Page 1 Y-range: from the scroll root top to the first
+ *   `data-page-frame-end="page-0"` widget's offsetTop.
+ * - Page K (2..N-1) Y-range: from the bottom of the previous boundary
+ *   widget (offsetTop + offsetHeight) to the top of the next boundary
+ *   widget (offsetTop).
+ * - Page N Y-range: from the last boundary widget's bottom to the scroll
+ *   root's bottom.
+ *
+ * Measurement is refreshed on:
+ * - mount (initial layout pass via `useLayoutEffect`)
+ * - `renderFrameRevision` tick (emitted by the layout facet after
+ *   incremental relayout, zoom changes, or render-frame diffs)
+ * - scroll root resize (via `ResizeObserver`)
+ * - PM body DOM mutations (via `MutationObserver` on the scroll root)
+ *
+ * The overlay is a runtime-owned projection — it never consults canonical
+ * state or the render kernel's emit beyond the page count; it reads the
+ * DOM once per render-frame revision and otherwise stays idle.
+ */
+
+import * as React from "react";
+import type { WordReviewEditorLayoutFacet } from "../../api/public-types";
+
+// ---------------------------------------------------------------------------
+// Measurement
+// ---------------------------------------------------------------------------
+
+export interface PageOverlayRect {
+  /** Canonical page id from `RuntimePageGraph.pageId`. */
+  pageId: string;
+  /** 0-based page index matching `facet.getPage(pageIndex)`. */
+  pageIndex: number;
+  /** Top Y in DOM coords relative to the scroll root. */
+  topPx: number;
+  /** Bottom Y in DOM coords relative to the scroll root. */
+  bottomPx: number;
+  /** Rendered height = bottomPx - topPx. */
+  heightPx: number;
+}
+
+/**
+ * Raw boundary measurement — one entry per `[data-page-frame-end]`
+ * widget.  Exported so DOM measurement helpers and tests can share a
+ * single shape.
+ */
+export interface PageBoundaryMeasurement {
+  prevPageId: string;
+  nextPageId: string;
+  /** Widget top edge = bottom of the previous page. */
+  topPx: number;
+  /** Widget bottom edge = top of the next page. */
+  bottomPx: number;
+}
+
+/**
+ * Pure helper: turn pre-measured page-boundary widget positions into
+ * one `PageOverlayRect` per page.  No DOM access — the caller supplies
+ * `widgets` and `scrollHeight` already expressed in whatever coordinate
+ * space the overlay consumer renders in.
+ *
+ * `pageCount` is the authoritative source of how many pages exist.
+ * Partial renders (PM hasn't committed every boundary widget yet) still
+ * produce a `pageCount`-long result: any tail page without its own
+ * `boundaryBefore` falls back to `topPx = 0` and any tail page without
+ * `boundaryAfter` falls back to `bottomPx = scrollHeight`.  Synthesized
+ * `page-N` ids keep React keys stable across partial→full renders.
+ *
+ * Exported for tests — unit tests drive this with inline widget data,
+ * no DOM fixture required.
+ */
+export function resolvePageOverlayRects(
+  input:
+    | {
+        /** Pre-measured widgets — origin-relative `topPx` / `bottomPx`. */
+        widgets: readonly PageBoundaryMeasurement[];
+        pageCount: number;
+        /** Total scroll-root height in the overlay's coordinate space. */
+        scrollHeight: number;
+      }
+    // Legacy two-arg path preserved for backward compat.  Walks
+    // offsetTop chain inside the scroll-root; used by harness code
+    // paths that never integrated a proper overlay ref.
+    | [
+        scrollRoot: Pick<HTMLElement, "clientHeight" | "querySelectorAll"> | null,
+        pageCount: number,
+      ],
+  legacyPageCount?: number,
+): readonly PageOverlayRect[] {
+  // Normalize arguments.  The two supported shapes:
+  //   1. Object: `{widgets, pageCount, scrollHeight}` — purely pure.
+  //   2. Positional: `(scrollRoot, pageCount)` — backward-compat; runs
+  //      `measureWidgetsViaOffsetChain` internally.  Kept so existing
+  //      tests pass without churn.
+  let widgets: readonly PageBoundaryMeasurement[];
+  let pageCount: number;
+  let scrollHeight: number;
+
+  if (Array.isArray(input)) {
+    const [scrollRoot, count] = input;
+    if (!scrollRoot || count <= 0) return [];
+    widgets = measureWidgetsViaOffsetChain(scrollRoot);
+    pageCount = count;
+    scrollHeight = scrollRoot.clientHeight;
+  } else if (
+    input !== null &&
+    typeof input === "object" &&
+    "widgets" in input
+  ) {
+    widgets = input.widgets;
+    pageCount = input.pageCount;
+    scrollHeight = input.scrollHeight;
+  } else if (input && legacyPageCount !== undefined) {
+    // (scrollRoot, pageCount) positional call.  `input` is the scroll
+    // root, `legacyPageCount` is the count.
+    const scrollRoot = input as unknown as Pick<
+      HTMLElement,
+      "clientHeight" | "querySelectorAll"
+    >;
+    if (legacyPageCount <= 0) return [];
+    widgets = measureWidgetsViaOffsetChain(scrollRoot);
+    pageCount = legacyPageCount;
+    scrollHeight = scrollRoot.clientHeight;
+  } else {
+    return [];
+  }
+
+  if (pageCount <= 0) return [];
+
+  // Sort boundaries by topPx so page order is stable even if the DOM
+  // emits widgets out-of-order (it doesn't today, but the cost is
+  // negligible).
+  const boundaries = [...widgets].sort((a, b) => a.topPx - b.topPx);
+
+  const rects: PageOverlayRect[] = [];
+  for (let pageIndex = 0; pageIndex < pageCount; pageIndex += 1) {
+    const boundaryBefore = pageIndex === 0 ? null : boundaries[pageIndex - 1];
+    const boundaryAfter =
+      pageIndex === pageCount - 1 ? null : boundaries[pageIndex];
+
+    let pageId: string | null = null;
+    if (boundaryBefore) pageId = boundaryBefore.nextPageId;
+    else if (boundaryAfter) pageId = boundaryAfter.prevPageId;
+    if (!pageId) pageId = `page-${pageIndex}`;
+
+    const topPx = boundaryBefore ? boundaryBefore.bottomPx : 0;
+    const bottomPx = boundaryAfter ? boundaryAfter.topPx : scrollHeight;
+
+    if (bottomPx <= topPx) continue;
+
+    rects.push({
+      pageId,
+      pageIndex,
+      topPx,
+      bottomPx,
+      heightPx: bottomPx - topPx,
+    });
+  }
+
+  return rects;
+}
+
+/**
+ * DOM measurement via `getBoundingClientRect()`.
+ *
+ * `originElement` defines the coordinate space the returned
+ * `topPx` / `bottomPx` values live in.  When the overlay consumer is a
+ * React component, `originElement` is typically the component's own
+ * root `<div>` (ref via `useRef`).  That keeps widget coordinates
+ * perfectly aligned with the overlay's own coordinate space regardless
+ * of how many positioned ancestors sit between the scroll root and
+ * the overlay — the problem P3.b's offset-chain walk silently
+ * produced wrong coordinates for.
+ *
+ * `queryRoot` is the DOM subtree to search for `[data-page-frame-end]`
+ * widgets.  It can be the same element as `originElement` or a broader
+ * ancestor.
+ */
+export function measureWidgetsViaBoundingRect(
+  queryRoot: Pick<HTMLElement, "querySelectorAll"> | null,
+  originElement: HTMLElement | null,
+): PageBoundaryMeasurement[] {
+  if (!queryRoot || !originElement) return [];
+  const originRect = originElement.getBoundingClientRect();
+  const widgets = Array.from(
+    queryRoot.querySelectorAll<HTMLElement>("[data-page-frame-end]"),
+  );
+  const out: PageBoundaryMeasurement[] = [];
+  for (const widget of widgets) {
+    const prevPageId = widget.getAttribute("data-page-frame-end");
+    const nextPageId = widget.getAttribute("data-page-frame-start");
+    if (!prevPageId || !nextPageId) continue;
+    const rect = widget.getBoundingClientRect();
+    out.push({
+      prevPageId,
+      nextPageId,
+      topPx: rect.top - originRect.top,
+      bottomPx: rect.bottom - originRect.top,
+    });
+  }
+  return out;
+}
+
+/**
+ * Legacy DOM measurement via the `offsetTop` / `offsetParent` chain.
+ * Returns offsets in scroll-root-relative coordinates.  Retained for
+ * the positional `resolvePageOverlayRects(scrollRoot, pageCount)` call
+ * signature that predates the `getBoundingClientRect()` path; new code
+ * should prefer `measureWidgetsViaBoundingRect(queryRoot, origin)` so
+ * widget coordinates align with the overlay's own rendering origin.
+ *
+ * The walk stops at `scrollRoot` (never-null parent is an escape
+ * hatch).  Nested positioned ancestors between the widget and the
+ * scroll root are summed correctly; the deprecation here is about
+ * "scroll root is often not the right origin", not about arithmetic.
+ */
+export function measureWidgetsViaOffsetChain(
+  scrollRoot: Pick<HTMLElement, "clientHeight" | "querySelectorAll">,
+): PageBoundaryMeasurement[] {
+  const widgets = Array.from(
+    scrollRoot.querySelectorAll<HTMLElement>("[data-page-frame-end]"),
+  );
+  const out: PageBoundaryMeasurement[] = [];
+  for (const widget of widgets) {
+    const prevPageId = widget.getAttribute("data-page-frame-end");
+    const nextPageId = widget.getAttribute("data-page-frame-start");
+    if (!prevPageId || !nextPageId) continue;
+    const topPx = resolveOffsetTop(widget, scrollRoot);
+    const bottomPx = topPx + resolveOffsetHeight(widget);
+    out.push({ prevPageId, nextPageId, topPx, bottomPx });
+  }
+  return out;
+}
+
+function resolveOffsetTop(
+  widget: HTMLElement,
+  scrollRoot: Pick<HTMLElement, "clientHeight">,
+): number {
+  // jsdom doesn't populate `offsetTop` from layout, but the property is
+  // still defined and defaults to 0.  Browsers set it relative to the
+  // offsetParent.  We walk up the offset chain until we reach the scroll
+  // root (or exit the document) so the result is scroll-root-relative.
+  let node: HTMLElement | null = widget;
+  let top = 0;
+  while (node) {
+    top += node.offsetTop ?? 0;
+    const parent = node.offsetParent as HTMLElement | null;
+    if (parent === scrollRoot || parent === null) break;
+    node = parent;
+  }
+  return top;
+}
+
+function resolveOffsetHeight(widget: HTMLElement): number {
+  return widget.offsetHeight ?? 0;
+}
+
+// ---------------------------------------------------------------------------
+// Component
+// ---------------------------------------------------------------------------
+
+export interface TwPageStackOverlayLayerProps {
+  /** Layout facet — source of the page count. */
+  facet: WordReviewEditorLayoutFacet;
+  /** Scroll root element whose page-boundary widgets drive measurement. */
+  scrollRoot: HTMLElement | null;
+  /**
+   * Revision tick incremented on `layout_recomputed`, `incremental_relayout`,
+   * `render_frame_ready`, or `zoom_changed`.  The layer re-measures every
+   * time this changes so the overlays stay aligned with content.
+   */
+  renderFrameRevision: number;
+  /** Optional test id applied to the overlay root. */
+  "data-testid"?: string;
+}
+
+/**
+ * The layer itself.  Renders one decorative `<div>` per page with the
+ * same card-shadow + rounded border treatment that `.wre-page-chrome`
+ * applies to the outer frame today.  Page 1's overlay sits flush with
+ * the outer frame (effectively redundant — the outer card is already
+ * visible); pages 2..N gain their own paper-frame treatment that the
+ * outer wrapper cannot draw on its own.
+ */
+export const TwPageStackOverlayLayer: React.FC<TwPageStackOverlayLayerProps> = ({
+  facet,
+  scrollRoot,
+  renderFrameRevision,
+  "data-testid": testId,
+}) => {
+  const [rects, setRects] = React.useState<readonly PageOverlayRect[]>([]);
+  // P3.d fix: the overlay root acts as the **measurement origin** so
+  // widget `topPx` / `bottomPx` are expressed in the exact coordinate
+  // space the overlay paints in.  Using `scrollRoot` as origin (P3.b
+  // default) silently produced wrong coordinates when the overlay
+  // rendered inside nested positioned ancestors (pm-body-wrapper inside
+  // frame-div inside content-inset inside scroll root).
+  const overlayRootRef = React.useRef<HTMLDivElement | null>(null);
+
+  // P14 hardening: coalesce refresh calls via requestAnimationFrame.
+  // Pre-P14 every ResizeObserver / MutationObserver / renderFrameRevision
+  // tick fired `refreshRects` synchronously — which does O(N)
+  // getBoundingClientRect calls (one per page-break widget plus the
+  // overlay-root rect), and every `getBoundingClientRect()` forces the
+  // browser to flush pending style + layout calculations.  For a
+  // 38-page CCEP doc that's 38 forced layouts per keystroke, multiplied
+  // by 2–3 refresh triggers per edit (layout_recomputed +
+  // incremental_relayout + MutationObserver + maybe page_count_changed)
+  // = ~150 forced layouts per keystroke.  The editor appeared to lock
+  // up during typing on large docs.
+  //
+  // rAF coalescing flips this so the worst case is **one measurement
+  // pass per frame** regardless of how many triggers fire.  The
+  // `rafHandleRef` protects against double-scheduling; clearing it on
+  // unmount prevents the callback from firing after the component
+  // tears down.
+  const rafHandleRef = React.useRef<number | null>(null);
+
+  const refreshRectsNow = React.useCallback(() => {
+    if (!scrollRoot) {
+      setRects([]);
+      return;
+    }
+    const origin = overlayRootRef.current;
+    const pageCount = facet.getPageCount();
+    if (origin) {
+      const widgets = measureWidgetsViaBoundingRect(scrollRoot, origin);
+      const originRect = origin.getBoundingClientRect();
+      setRects(
+        resolvePageOverlayRects({
+          widgets,
+          pageCount,
+          scrollHeight:
+            origin.clientHeight > 0 ? origin.clientHeight : originRect.height,
+        }),
+      );
+    } else {
+      setRects(resolvePageOverlayRects([scrollRoot, pageCount]));
+    }
+  }, [facet, scrollRoot]);
+
+  const refreshRects = React.useCallback(() => {
+    if (!scrollRoot) {
+      setRects([]);
+      return;
+    }
+    const runtime = scrollRoot.ownerDocument?.defaultView as
+      | (Window & {
+          requestAnimationFrame?: (cb: () => void) => number;
+          cancelAnimationFrame?: (handle: number) => void;
+        })
+      | null;
+    const raf = runtime?.requestAnimationFrame;
+    // SSR + older jsdom without rAF: fall back to immediate refresh.
+    if (!raf) {
+      refreshRectsNow();
+      return;
+    }
+    // Drop duplicate schedules inside the same frame — each subsequent
+    // refresh-request short-circuits while one is already pending.
+    if (rafHandleRef.current !== null) return;
+    rafHandleRef.current = raf(() => {
+      rafHandleRef.current = null;
+      refreshRectsNow();
+    });
+  }, [scrollRoot, refreshRectsNow]);
+
+  // P14: re-measure via the debounced scheduler so multiple
+  // `renderFrameRevision` bumps per edit (layout_recomputed +
+  // incremental_relayout + page_count_changed + page_field_dirtied)
+  // coalesce to one measurement pass per animation frame.  `useEffect`
+  // instead of `useLayoutEffect` — we don't need to block paint for
+  // this decorative overlay; a one-frame delay before page borders
+  // reposition is imperceptible.
+  React.useEffect(() => {
+    refreshRects();
+    return () => {
+      const runtime = scrollRoot?.ownerDocument?.defaultView as
+        | (Window & { cancelAnimationFrame?: (h: number) => void })
+        | null;
+      if (rafHandleRef.current !== null && runtime?.cancelAnimationFrame) {
+        runtime.cancelAnimationFrame(rafHandleRef.current);
+        rafHandleRef.current = null;
+      }
+    };
+  }, [refreshRects, renderFrameRevision, scrollRoot]);
+
+  // Observe scroll-root size changes so zoom, viewport resize, or font
+  // loading re-trigger measurement without a full app re-render.
+  React.useEffect(() => {
+    if (!scrollRoot) return;
+    const runtime = scrollRoot.ownerDocument?.defaultView as
+      | (Window & { ResizeObserver?: typeof ResizeObserver })
+      | null;
+    if (!runtime?.ResizeObserver) return;
+    const observer = new runtime.ResizeObserver(() => refreshRects());
+    observer.observe(scrollRoot);
+    return () => observer.disconnect();
+  }, [scrollRoot, refreshRects]);
+
+  // Observe DOM mutations so PM re-renders (page-break widgets added /
+  // removed on relayout) re-trigger measurement.  We filter to
+  // childList + subtree changes to avoid needless recomputation on
+  // style-only attribute churn.
+  //
+  // Hardening: ignore mutations whose targets live INSIDE the overlay
+  // root itself.  Without this filter, the `setRects` → React
+  // reconciliation → new/removed `<div>` children → MutationObserver
+  // cycle can fire recursively.  The filter breaks the cycle cleanly
+  // by ignoring every mutation that only touches overlay descendants.
+  //
+  // P14: the observer callback now routes through the debounced
+  // `refreshRects`, so a keystroke burst that fires the observer many
+  // times within one animation frame coalesces into one measurement
+  // pass instead of a per-mutation re-render storm.
+  React.useEffect(() => {
+    if (!scrollRoot) return;
+    const runtime = scrollRoot.ownerDocument?.defaultView as
+      | (Window & { MutationObserver?: typeof MutationObserver })
+      | null;
+    if (!runtime?.MutationObserver) return;
+    const observer = new runtime.MutationObserver((records) => {
+      const overlay = overlayRootRef.current;
+      if (overlay) {
+        const allSelf = records.every(
+          (r) => r.target instanceof Node && overlay.contains(r.target),
+        );
+        if (allSelf) return;
+      }
+      refreshRects();
+    });
+    // P14.e: subtree:false eliminates the per-keystroke characterData
+    // schedule.  Page boundaries only shift on childList changes — the
+    // page-frame widget `<div>` is added or removed when pagination
+    // emits a new page boundary.  characterData mutations (every
+    // keystroke!) used to fire the callback even though they never
+    // change widget positions; narrowing the scope removes that storm
+    // entirely without losing the page-add / page-remove signal that
+    // actually matters for the overlay's rect math.
+    observer.observe(scrollRoot, { childList: true, subtree: false });
+    return () => observer.disconnect();
+  }, [scrollRoot, refreshRects]);
+
+  // Always render the overlay root so the ref resolves on first paint.
+  // Without the root element we never get a `getBoundingClientRect()`
+  // call, which means the first measurement pass falls back to the
+  // offset-chain (wrong coords) and the user sees mis-aligned page
+  // frames until the next `renderFrameRevision` tick.  Keeping the
+  // root element present + empty is cheap (one `<div>`) and makes the
+  // ref resolve during the first layout-effect pass.
+  if (rects.length === 0) {
+    return (
+      <div
+        ref={overlayRootRef}
+        className="wre-page-stack-overlay pointer-events-none absolute inset-0 z-0"
+        aria-hidden="true"
+        data-testid={testId ?? "page-stack-overlay"}
+        data-page-count="0"
+      />
+    );
+  }
+
+  return (
+    <div
+      ref={overlayRootRef}
+      className="wre-page-stack-overlay pointer-events-none absolute inset-0 z-0"
+      aria-hidden="true"
+      data-testid={testId ?? "page-stack-overlay"}
+      data-page-count={rects.length}
+    >
+      {rects.map((rect) => (
+        <div
+          key={rect.pageId}
+          className="wre-page-stack-overlay-frame absolute"
+          data-page-index={rect.pageIndex}
+          data-page-id={rect.pageId}
+          style={{
+            top: `${rect.topPx}px`,
+            height: `${rect.heightPx}px`,
+            left: 0,
+            right: 0,
+            // The overlay paints decorative paper-edge treatment (border
+            // + soft shadow) around each page's vertical slice.  It sits
+            // ABOVE the PM surface in stacking order so we deliberately
+            // leave `backgroundColor` unset — a filled overlay would
+            // occlude PM text.  Border + box-shadow alone give the
+            // 'distinct paper' perception without covering content.
+            backgroundColor: "transparent",
+            border: "1px solid var(--color-page-border, rgba(148,163,184,0.2))",
+            borderRadius: "var(--radius-page, 4px)",
+            boxShadow:
+              "0 8px 24px -20px var(--color-page-shadow, rgba(15,23,42,0.38))",
+          }}
+        />
+      ))}
+    </div>
+  );
+};
+
+export default TwPageStackOverlayLayer;