@beyondwork/docx-react-component 1.0.39 → 1.0.40

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

@@ -0,0 +1,386 @@
+/**
+ * TwScopeCard — inline floating card shown above a scoped region when
+ * the user activates the rail stripe.  Displays scope label + mode
+ * selector + (when an `IssueMetadataValue` is attached via
+ * `ScopeCardModel.issue`) the R2 issue severity, owner, title, and
+ * resolve/waive/escalate actions.
+ *
+ * Per docs/plans/scope-card-overlay.md P1, the card never mutates
+ * runtime state directly — it fires `onModeChange` / `onIssueAction`
+ * callbacks that bubble up to `scope-mode-change-requested` /
+ * `scope-issue-action-requested` events on WordReviewEditorEvent.
+ *
+ * A11y contract:
+ *   - role="dialog", aria-modal="false" (not a hard-focus capture; the
+ *     editor surface remains interactive while the card is open)
+ *   - aria-labelledby points at the header id
+ *   - Escape closes; focus-trap wraps Tab / Shift-Tab
+ *   - An aria-live="polite" region announces the attached issue's
+ *     severity when the card opens with an issue
+ */
+
+import * as React from "react";
+import type {
+  IssueMetadataValue,
+  IssueOwner,
+  IssueSeverity,
+  ScopeCardModel,
+  ScopeIssueAction,
+  WorkflowScopeMode,
+} from "../../api/public-types";
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+export interface TwScopeCardProps {
+  model: ScopeCardModel;
+  onClose: () => void;
+  onModeChange: (mode: WorkflowScopeMode) => void;
+  onIssueAction: (action: ScopeIssueAction) => void;
+  /** Test id applied to the root node. */
+  "data-testid"?: string;
+}
+
+const MODE_OPTIONS: ReadonlyArray<{ mode: WorkflowScopeMode; label: string }> = [
+  { mode: "edit", label: "Edit" },
+  { mode: "suggest", label: "Suggest" },
+  { mode: "comment", label: "Comment" },
+  { mode: "view", label: "View" },
+];
+
+const SEVERITY_COLOR: Record<IssueSeverity, string> = {
+  low: "var(--color-secondary)",
+  medium: "var(--color-warning)",
+  high: "var(--color-warning)",
+  blocker: "var(--color-danger)",
+};
+
+const SEVERITY_LABEL: Record<IssueSeverity, string> = {
+  low: "Low",
+  medium: "Medium",
+  high: "High",
+  blocker: "Blocker",
+};
+
+const OWNER_LABEL: Record<IssueOwner, string> = {
+  procurement: "Procurement",
+  legal: "Legal",
+  risk: "Risk",
+  finance: "Finance",
+  sustainability: "Sustainability",
+};
+
+// ---------------------------------------------------------------------------
+// Component
+// ---------------------------------------------------------------------------
+
+export const TwScopeCard: React.FC<TwScopeCardProps> = ({
+  model,
+  onClose,
+  onModeChange,
+  onIssueAction,
+  "data-testid": testId,
+}) => {
+  const rootRef = React.useRef<HTMLDivElement | null>(null);
+  const headerId = React.useId();
+  const liveRegionId = React.useId();
+
+  // --- Focus management ----------------------------------------------------
+  React.useEffect(() => {
+    const root = rootRef.current;
+    if (!root) return undefined;
+    const first = getFocusable(root)[0];
+    first?.focus();
+    return undefined;
+  }, []);
+
+  // --- Escape + click-outside ---------------------------------------------
+  React.useEffect(() => {
+    const onKey = (event: KeyboardEvent) => {
+      if (event.key === "Escape") {
+        event.stopPropagation();
+        onClose();
+      }
+    };
+    const onPointerDown = (event: PointerEvent) => {
+      const root = rootRef.current;
+      if (!root) return;
+      if (event.target instanceof Node && root.contains(event.target)) return;
+      onClose();
+    };
+    window.addEventListener("keydown", onKey, true);
+    window.addEventListener("pointerdown", onPointerDown, true);
+    return () => {
+      window.removeEventListener("keydown", onKey, true);
+      window.removeEventListener("pointerdown", onPointerDown, true);
+    };
+  }, [onClose]);
+
+  // --- Focus trap ----------------------------------------------------------
+  const onKeyDown = (event: React.KeyboardEvent<HTMLDivElement>) => {
+    if (event.key !== "Tab") return;
+    const root = rootRef.current;
+    if (!root) return;
+    const focusables = getFocusable(root);
+    if (focusables.length === 0) return;
+    const first = focusables[0];
+    const last = focusables[focusables.length - 1];
+    const active = document.activeElement;
+    if (event.shiftKey) {
+      if (active === first || !root.contains(active)) {
+        event.preventDefault();
+        last.focus();
+      }
+    } else {
+      if (active === last) {
+        event.preventDefault();
+        first.focus();
+      }
+    }
+  };
+
+  const issue = model.issue;
+  const postureLabel = posturePresentationLabel(model.posture);
+
+  return (
+    <div
+      ref={rootRef}
+      className="wre-scope-card pointer-events-auto absolute flex w-80 max-w-[22rem] flex-col gap-2 rounded-lg border border-border bg-canvas p-3 text-sm shadow-[var(--shadow-float)]"
+      role="dialog"
+      aria-modal="false"
+      aria-labelledby={headerId}
+      data-testid={testId ?? "scope-card"}
+      data-scope-id={model.scopeId}
+      data-posture={model.posture}
+      onKeyDown={onKeyDown}
+    >
+      {/* Header --------------------------------------------------------- */}
+      <div className="flex items-center justify-between gap-2">
+        <div
+          id={headerId}
+          className="flex min-w-0 flex-1 items-center gap-2 text-xs font-medium text-primary"
+        >
+          <span
+            className={`wre-scope-rail-icon wre-scope-rail-icon-${posturePresentationIcon(model.posture)}`}
+            aria-hidden="true"
+            style={{ color: postureTokenColor(model.posture) }}
+          />
+          <span className="truncate uppercase tracking-[0.06em]">
+            {postureLabel}
+          </span>
+          {model.label ? (
+            <span className="truncate text-tertiary">· {model.label}</span>
+          ) : null}
+        </div>
+        <button
+          type="button"
+          aria-label="Close scope card"
+          className="flex h-6 w-6 items-center justify-center rounded-sm text-tertiary transition-colors hover:bg-surface hover:text-primary"
+          onClick={onClose}
+          data-testid="scope-card-close"
+        >
+          ×
+        </button>
+      </div>
+
+      {/* Mode row ------------------------------------------------------- */}
+      <div
+        role="group"
+        aria-label="Scope mode"
+        className="flex gap-1 rounded-md border border-border bg-surface p-0.5"
+      >
+        {MODE_OPTIONS.map(({ mode, label }) => {
+          const active = model.posture === mode;
+          return (
+            <button
+              key={mode}
+              type="button"
+              aria-pressed={active ? "true" : "false"}
+              className={`flex-1 rounded-sm px-2 py-1 text-xs font-medium transition-colors ${
+                active
+                  ? "bg-canvas text-primary shadow-sm"
+                  : "text-secondary hover:bg-canvas hover:text-primary"
+              }`}
+              onClick={() => onModeChange(mode)}
+              data-testid={`scope-card-mode-${mode}`}
+            >
+              {label}
+            </button>
+          );
+        })}
+      </div>
+
+      {/* Issue row (R2) ------------------------------------------------- */}
+      {issue ? <IssueRow issue={issue} onAction={onIssueAction} /> : null}
+
+      {/* A11y live region ---------------------------------------------- */}
+      <span
+        id={liveRegionId}
+        role="status"
+        aria-live="polite"
+        className="sr-only"
+      >
+        {issue
+          ? `${postureLabel} scope, ${SEVERITY_LABEL[issue.severity]} severity issue attached: ${issue.title}`
+          : `${postureLabel} scope opened`}
+      </span>
+    </div>
+  );
+};
+
+// ---------------------------------------------------------------------------
+// Issue row
+// ---------------------------------------------------------------------------
+
+const IssueRow: React.FC<{
+  issue: IssueMetadataValue;
+  onAction: (action: ScopeIssueAction) => void;
+}> = ({ issue, onAction }) => {
+  const canResolve = issue.checklistState === "open" || issue.checklistState === "acknowledged";
+  const canWaive = issue.checklistState !== "waived";
+  const canEscalate = issue.escalationState !== "requested";
+
+  return (
+    <div
+      className="flex flex-col gap-1.5 rounded-md bg-surface p-2"
+      data-testid="scope-card-issue"
+    >
+      <div className="flex items-center gap-1.5 text-[11px]">
+        <span
+          aria-hidden="true"
+          className="inline-block h-2 w-2 rounded-full"
+          style={{ background: SEVERITY_COLOR[issue.severity] }}
+        />
+        <span className="font-semibold text-primary">
+          {SEVERITY_LABEL[issue.severity]}
+        </span>
+        {issue.owner ? (
+          <span
+            className="rounded-sm border border-border px-1 py-0.5 text-[10px] font-medium uppercase tracking-[0.06em] text-secondary"
+            data-testid="scope-card-issue-owner"
+          >
+            {OWNER_LABEL[issue.owner]}
+          </span>
+        ) : null}
+      </div>
+      <div
+        className="text-xs font-medium leading-snug text-primary"
+        data-testid="scope-card-issue-title"
+      >
+        {issue.title}
+      </div>
+      {issue.summary ? (
+        <div className="text-[11px] leading-snug text-secondary">{issue.summary}</div>
+      ) : null}
+      <div className="flex gap-1">
+        <IssueActionButton
+          label="Resolve"
+          testId="scope-card-issue-resolve"
+          disabled={!canResolve}
+          onClick={() => onAction("resolve")}
+        />
+        <IssueActionButton
+          label="Waive"
+          testId="scope-card-issue-waive"
+          disabled={!canWaive}
+          onClick={() => onAction("waive")}
+        />
+        <IssueActionButton
+          label="Escalate"
+          testId="scope-card-issue-escalate"
+          disabled={!canEscalate}
+          onClick={() => onAction("escalate")}
+        />
+      </div>
+    </div>
+  );
+};
+
+const IssueActionButton: React.FC<{
+  label: string;
+  testId: string;
+  disabled: boolean;
+  onClick: () => void;
+}> = ({ label, testId, disabled, onClick }) => (
+  <button
+    type="button"
+    disabled={disabled}
+    className="flex-1 rounded-sm border border-border bg-canvas px-1.5 py-1 text-[11px] font-medium text-secondary transition-colors hover:bg-surface hover:text-primary disabled:cursor-not-allowed disabled:opacity-40"
+    onClick={onClick}
+    data-testid={testId}
+  >
+    {label}
+  </button>
+);
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+function getFocusable(root: HTMLElement): HTMLElement[] {
+  const selector =
+    'button:not([disabled]), a[href], [tabindex]:not([tabindex="-1"]), input:not([disabled]), select:not([disabled]), textarea:not([disabled])';
+  return Array.from(root.querySelectorAll<HTMLElement>(selector)).filter(
+    (el) => !el.hasAttribute("inert") && el.offsetParent !== null,
+  );
+}
+
+function posturePresentationLabel(posture: ScopeCardModel["posture"]): string {
+  switch (posture) {
+    case "edit":
+      return "Edit";
+    case "suggest":
+      return "Suggest";
+    case "comment":
+      return "Comment";
+    case "view":
+      return "View";
+    case "candidate":
+      return "Proposed";
+    case "preserve-only":
+    case "blocked-import":
+      return "Blocked";
+    default:
+      return "Scope";
+  }
+}
+
+function posturePresentationIcon(posture: ScopeCardModel["posture"]): string {
+  switch (posture) {
+    case "edit":
+      return "pencil";
+    case "suggest":
+      return "sparkles";
+    case "comment":
+      return "message";
+    case "view":
+      return "eye";
+    case "candidate":
+      return "flag";
+    case "preserve-only":
+    case "blocked-import":
+      return "lock";
+    default:
+      return "eye";
+  }
+}
+
+function postureTokenColor(posture: ScopeCardModel["posture"]): string {
+  switch (posture) {
+    case "edit":
+      return "var(--color-accent)";
+    case "suggest":
+    case "candidate":
+      return "var(--color-warning)";
+    case "comment":
+      return "var(--color-insert)";
+    case "preserve-only":
+    case "blocked-import":
+      return "var(--color-danger)";
+    default:
+      return "var(--color-secondary)";
+  }
+}
+
+export default TwScopeCard;

package/src/ui-tailwind/chrome-overlay/tw-scope-rail-layer.tsx

@@ -1,23 +1,23 @@
 /**
- * Scope rail layer — renders workflow scopes as a continuous zone with a
- * gutter icon + label column OUTSIDE the document flow plus a flat block-
- * level tint BEHIND the scoped paragraphs.
+ * Scope rail layer — renders workflow scopes as a thin color stripe in
+ * the reserved left-gutter lane plus a per-line flat tint behind the
+ * scoped text runs.
  *
- * Per runtime-rendering-and-chrome-phase.md §5, the rail is a projection
- * over canonical workflow scopes; it never lives inside the PM NodeView
- * tree.  Positions come from the render kernel's anchor index — not from
- * DOM rect math — so the rail stays aligned across scroll, zoom, resize,
- * and through predicted-text reconciliation.
+ * Per runtime-rendering-and-chrome-phase.md §5 and
+ * docs/plans/scope-card-overlay.md P0, the rail is a projection over
+ * canonical workflow scopes; it never lives inside the PM NodeView
+ * tree.  Positions come from the render kernel's per-line block data
+ * (walked directly from `RenderFrame.pages[].regions.body.blocks[]`)
+ * so multi-line scopes produce one tight tint per line rather than a
+ * fat bounding-box union.
  */
 
 import * as React from "react";
 import {
-  inflateRect,
   projectRectToOverlay,
-  unionRect,
   type OverlayCoordinateSpace,
 } from "./chrome-overlay-projector";
-import type { RenderFrameRect } from "../../runtime/render";
+import type { RenderFrame, RenderFrameRect } from "../../runtime/render";
 import type { ScopeRailSegment, ScopeRailPosture } from "../../runtime/layout";
 import type { WordReviewEditorLayoutFacet } from "../../runtime/layout";
 
@@ -26,16 +26,25 @@ import type { WordReviewEditorLayoutFacet } from "../../runtime/layout";
 // ---------------------------------------------------------------------------
 
 export interface TwScopeRailLayerProps {
-  /** Layout facet that provides segments + anchor index. */
+  /** Layout facet that provides segments + render frame. */
   facet: WordReviewEditorLayoutFacet;
   /** Overlay's coordinate space.  Defaults to the overlay's own origin. */
   space?: OverlayCoordinateSpace;
-  /** Horizontal padding (px) the rail gutter occupies to the left of body. */
+  /** Horizontal pad (px) the rail gutter occupies to the left of body. */
   railLaneWidthPx?: number;
-  /** Optional click handler for a segment label (open-scope drawer, etc). */
-  onSegmentClick?: (segment: ScopeRailSegment) => void;
   /** Scope id that should render with the `active` emphasis. */
   activeScopeId?: string | null;
+  /**
+   * Fires when the user clicks the rail stripe — opens the scope card.
+   * P0 wires this directly; P1 replaces with card-layer-aware routing.
+   */
+  onStripeClick?: (segment: ScopeRailSegment) => void;
+  /**
+   * Legacy click handler kept for existing consumers.  Called alongside
+   * `onStripeClick` so host apps that subscribed to the pre-stripe API
+   * continue to receive clicks.
+   */
+  onSegmentClick?: (segment: ScopeRailSegment) => void;
   /** Test id applied to the layer root. */
   "data-testid"?: string;
 }
@@ -46,7 +55,7 @@ export interface TwScopeRailLayerProps {
 
 interface PostureStyle {
   labelText: string;
-  icon: string; // lucide-style key; CSS ::before handles glyph in production
+  icon: string;
   railToken: string;
   tintToken: string;
 }
@@ -65,20 +74,19 @@ const POSTURE_STYLES: Record<ScopeRailPosture, PostureStyle> = {
 // Component
 // ---------------------------------------------------------------------------
 
-const DEFAULT_RAIL_LANE_PX = 120;
-const LABEL_WIDTH_PX = 92;
+const DEFAULT_RAIL_LANE_PX = 44;
+const STRIPE_WIDTH_PX = 4;
+const LABEL_WIDTH_PX = 40;
 
 export const TwScopeRailLayer: React.FC<TwScopeRailLayerProps> = ({
   facet,
   space,
   railLaneWidthPx = DEFAULT_RAIL_LANE_PX,
-  onSegmentClick,
   activeScopeId,
+  onStripeClick,
+  onSegmentClick,
   "data-testid": testId,
 }) => {
-  // Read the render frame once per paint cycle.  The facet.subscribe path
-  // already invalidates the caller's React state on layout changes, so we
-  // just read on render.
   const frame = typeof facet.getRenderFrame === "function"
     ? facet.getRenderFrame() ?? null
     : null;
@@ -88,16 +96,6 @@ export const TwScopeRailLayer: React.FC<TwScopeRailLayerProps> = ({
     return null;
   }
 
-  // Group segments by scopeId so multi-page scopes render one contiguous
-  // tint per page range.  (Per-page render happens below because each
-  // scope may span pages.)
-  const items = segments.map((segment) => {
-    const rect = resolveSegmentRect(facet, frame, segment);
-    if (!rect) return null;
-    const style = POSTURE_STYLES[segment.posture];
-    return { segment, rect, style };
-  }).filter((item): item is NonNullable<typeof item> => item !== null);
-
   const projectorSpace: OverlayCoordinateSpace = space ?? { originLeftPx: 0, originTopPx: 0 };
 
   return (
@@ -108,43 +106,86 @@ export const TwScopeRailLayer: React.FC<TwScopeRailLayerProps> = ({
       role="group"
       aria-label="Workflow scope rail"
     >
-      {items.map(({ segment, rect, style }) => {
-        const isActive = activeScopeId === segment.scopeId || segment.isActiveWorkItem;
-        const tintRect = inflateRect(rect, { leftPx: 4, rightPx: 4, topPx: 2, bottomPx: 2 });
+      {segments.map((segment) => {
+        const style = POSTURE_STYLES[segment.posture];
+        const lineRects = collectLineRectsForSegment(frame, segment);
+        if (lineRects.length === 0) return null;
+
+        const isActive =
+          activeScopeId === segment.scopeId || segment.isActiveWorkItem;
+
+        // Stripe + label span the vertical range of the scope's lines;
+        // they live in the gutter lane to the left of the first line.
+        const firstLine = lineRects[0];
+        const lastLine = lineRects[lineRects.length - 1];
+        const stripeTopPx = firstLine.topPx;
+        const stripeHeightPx =
+          lastLine.topPx + lastLine.heightPx - firstLine.topPx;
+        const stripeRect: RenderFrameRect = {
+          leftPx: firstLine.leftPx - railLaneWidthPx + (railLaneWidthPx - STRIPE_WIDTH_PX) / 2,
+          topPx: stripeTopPx,
+          widthPx: STRIPE_WIDTH_PX,
+          heightPx: Math.max(stripeHeightPx, 14),
+        };
         const labelRect: RenderFrameRect = {
-          leftPx: rect.leftPx - railLaneWidthPx,
-          topPx: rect.topPx,
+          leftPx: firstLine.leftPx - railLaneWidthPx,
+          topPx: stripeTopPx,
           widthPx: LABEL_WIDTH_PX,
-          heightPx: Math.max(20, Math.min(rect.heightPx, 48)),
+          heightPx: 20,
+        };
+
+        const handleActivate = () => {
+          onStripeClick?.(segment);
+          onSegmentClick?.(segment);
+        };
+        const handleStripeKey = (event: React.KeyboardEvent<HTMLButtonElement>) => {
+          if (event.key === "Enter" || event.key === " ") {
+            event.preventDefault();
+            handleActivate();
+          }
         };
 
         return (
           <React.Fragment key={`${segment.scopeId}:${segment.pageIndex}:${segment.fromOffset}`}>
-            {/* Flat tint behind the scoped block region */}
-            <div
-              className={`wre-scope-rail-tint wre-scope-rail-tint-${style.tintToken} absolute ${
-                isActive ? "wre-scope-rail-tint-active" : ""
-              }`}
-              data-scope-id={segment.scopeId}
-              data-posture={segment.posture}
-              style={projectRectToOverlay(tintRect, projectorSpace)}
-            />
-            {/* Gutter label + icon outside the page frame */}
+            {/* Per-line tint behind the scoped text runs. */}
+            {lineRects.map((lineRect, index) => (
+              <div
+                key={`tint:${index}`}
+                className={`wre-scope-rail-tint wre-scope-rail-tint-${style.tintToken} ${
+                  isActive ? "wre-scope-rail-tint-active" : ""
+                }`}
+                data-scope-id={segment.scopeId}
+                data-posture={segment.posture}
+                data-line-index={index}
+                style={projectRectToOverlay(lineRect, projectorSpace)}
+              />
+            ))}
+            {/* Rail stripe in the gutter. */}
             <button
               type="button"
-              className={`wre-scope-rail-label wre-scope-rail-label-${style.railToken} pointer-events-auto absolute flex flex-col items-center justify-center gap-1 rounded-md text-[10px] font-semibold uppercase tracking-[0.08em] ${
-                isActive ? "wre-scope-rail-label-active" : ""
+              className={`wre-scope-rail-stripe wre-scope-rail-label-${style.railToken} ${
+                isActive ? "wre-scope-rail-stripe-active" : ""
               }`}
               data-scope-id={segment.scopeId}
               data-posture={segment.posture}
-              data-icon={style.icon}
+              data-testid="scope-rail-stripe"
               aria-label={`${style.labelText}${segment.label ? `: ${segment.label}` : ""}`}
-              onClick={onSegmentClick ? () => onSegmentClick(segment) : undefined}
+              aria-expanded={isActive ? "true" : "false"}
+              onClick={handleActivate}
+              onKeyDown={handleStripeKey}
+              style={projectRectToOverlay(stripeRect, projectorSpace)}
+            />
+            {/* Label pill — revealed on stripe hover via CSS. */}
+            <div
+              className={`wre-scope-rail-label wre-scope-rail-label-${style.railToken}`}
+              data-scope-id={segment.scopeId}
+              data-posture={segment.posture}
+              aria-hidden="true"
               style={projectRectToOverlay(labelRect, projectorSpace)}
             >
               <span aria-hidden="true" className={`wre-scope-rail-icon wre-scope-rail-icon-${style.icon}`} />
               <span className="wre-scope-rail-label-text">{style.labelText}</span>
-            </button>
+            </div>
           </React.Fragment>
         );
       })}
@@ -156,23 +197,53 @@ export const TwScopeRailLayer: React.FC<TwScopeRailLayerProps> = ({
 // Internals
 // ---------------------------------------------------------------------------
 
-function resolveSegmentRect(
-  facet: WordReviewEditorLayoutFacet,
-  _frame: { anchorIndex: { byRuntimeOffset: (offset: number) => RenderFrameRect | null } },
+/**
+ * Walk the render frame and collect one rect per line whose owning
+ * fragment overlaps the segment's offset range.  Line frames come from
+ * the kernel's per-line projection, which clamps widthPx to the line's
+ * text-actual width via `Math.min(regionFrame.widthPx, box.widthTwips
+ * * pxPerTwip)`.  Multi-line scopes therefore produce one tight tint
+ * per line instead of a single bounding-box union.
+ *
+ * Exported for unit testing — not part of the public API.
+ */
+export function collectLineRectsForSegment(
+  frame: RenderFrame,
   segment: ScopeRailSegment,
-): RenderFrameRect | null {
-  const fromRect = _frame.anchorIndex.byRuntimeOffset(segment.fromOffset);
-  const toRect = _frame.anchorIndex.byRuntimeOffset(Math.max(segment.fromOffset, segment.toOffset - 1));
-  const unioned = unionRect(fromRect, toRect);
-  if (unioned) return unioned;
-  // Fall back to the page rect so long scopes that can't resolve per-line
-  // still render a posture in the gutter.
-  const fallbackPage = facet.getPage(segment.pageIndex);
-  if (!fallbackPage) return null;
-  // Approximate: derive a rect from the page's body region by asking the
-  // render frame for the page rect.  Without a render kernel kernel this
-  // function returns null and the segment is skipped.
-  return null;
+): RenderFrameRect[] {
+  const rects: RenderFrameRect[] = [];
+  const lo = segment.fromOffset;
+  const hi = segment.toOffset;
+  if (lo >= hi) return rects;
+
+  const page = frame.pages[segment.pageIndex];
+  if (!page) {
+    // Fall back to scanning every page — protects against pageIndex
+    // drift during an in-flight layout update.
+    for (const p of frame.pages) {
+      pushRectsFromPage(rects, p, lo, hi);
+    }
+    return rects;
+  }
+  pushRectsFromPage(rects, page, lo, hi);
+  return rects;
+}
+
+function pushRectsFromPage(
+  sink: RenderFrameRect[],
+  page: RenderFrame["pages"][number],
+  lo: number,
+  hi: number,
+): void {
+  for (const block of page.regions.body.blocks) {
+    const from = block.fragment.from;
+    const to = block.fragment.to;
+    if (to <= lo || from >= hi) continue;
+    // Block overlaps the segment — emit one tint per line.
+    for (const line of block.lines) {
+      sink.push(line.frame);
+    }
+  }
 }
 
 export default TwScopeRailLayer;