@beyondwork/docx-react-component 1.0.66 → 1.0.69

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

@@ -48,6 +48,14 @@
 
 import * as React from "react";
 import type { WordReviewEditorLayoutFacet } from "../../api/public-types";
+import { incrementInvalidationCounter } from "../editor-surface/perf-probe";
+import {
+  resolvePageOverlayRectsFromGeometry as resolvePageOverlayRectsFromGeometryImpl,
+  type GeometryFacet,
+  type OverlayVisiblePageIndexRange,
+} from "../../runtime/geometry/index.ts";
+import type { ApiV3Ui } from "../../api/v3/ui";
+import { useUiApi } from "../ui-api-context";
 
 // ---------------------------------------------------------------------------
 // Measurement
@@ -394,6 +402,22 @@ function resolveOffsetHeight(widget: HTMLElement): number {
 export interface TwPageStackOverlayLayerProps {
   /** Layout facet — source of the page count. */
   facet: WordReviewEditorLayoutFacet;
+  /**
+   * Geometry facet — source of per-page rects when the render kernel has
+   * produced a frame (refactor/05 Slice 3b). When provided and
+   * `geometryFacet.getPage(0)` resolves, the overlay reads page rects
+   * directly from the kernel frame (tagged `space: "frame"`, which
+   * coincides with the overlay root's coordinate space — the overlay is
+   * a direct child of `wre-page-surface` at z-0 per v22 N1). This
+   * eliminates the overlay's G2 violation entirely for the warm path.
+   *
+   * When omitted, or when `getPage(0)` returns null (cold-open, before
+   * first render frame), the overlay falls back to the DOM-measurement
+   * path via `measureWidgetsViaBoundingRect` /
+   * `measureWidgetsViaOffsetChain` — preserved as the cold-open seam per
+   * architecture 05 Slice 3 exit criteria.
+   */
+  geometryFacet?: GeometryFacet;
   /** Scroll root element whose page-boundary widgets drive measurement. */
   scrollRoot: HTMLElement | null;
   /**
@@ -407,6 +431,76 @@ export interface TwPageStackOverlayLayerProps {
   "data-testid"?: string;
 }
 
+/**
+ * Slice 3b · Re-export of the pure geometry-projection helper that now
+ * lives in `src/runtime/geometry/overlay-rects.ts`. The `L05` layer
+ * owns the projection math; the overlay component re-exports from this
+ * module for back-compat with existing imports.
+ *
+ * Known coordinate-space caveat documented in
+ * `src/runtime/geometry/overlay-rects.ts` — the kernel's page-stacking
+ * gap (16 px) diverges from the DOM chrome's inter-page gap (48 px).
+ * Until Slice 3c reconciles them, production consumers should not pass
+ * a `geometryFacet` to this overlay — the DOM-measurement path remains
+ * the default.
+ */
+export const resolvePageOverlayRectsFromGeometry =
+  resolvePageOverlayRectsFromGeometryImpl;
+
+/**
+ * DS-C2 (designsystem.md §8.8.1 "Page / ruler / header-footer bands"
+ * row) — resolve per-page overlay rects via `ui.overlays.getAnchor` so
+ * the overlay's primary read seam is the public UI API, not the
+ * geometry facet directly. Returns `null` when `ui` cannot resolve the
+ * first page (cold-open or no controller bound); caller falls back to
+ * the geometry-facet / DOM paths below.
+ *
+ * `pageIds` is supplied by the caller when available (from the
+ * geometry facet's `getPage(i).pageId` metadata). When absent, the
+ * helper synthesizes `page-${index}` ids for the React `key=` slot —
+ * stable within a run, unstable across reloads. The L10 follow-up
+ * ticket on `ui.overlays` page-id enumeration (see
+ * `cross-layer-coord-10.md §1.7`) retires the synthesis path.
+ */
+export function resolvePageOverlayRectsFromUiApi(
+  ui: ApiV3Ui,
+  pageCount: number,
+  visiblePageIndexRange: VisiblePageIndexRange | null | undefined,
+  pageIds: readonly string[] | null,
+): readonly PageOverlayRect[] | null {
+  if (pageCount <= 0) return [];
+  const firstAnchor = ui.overlays.getAnchor({ kind: "page", value: 0 });
+  if (!firstAnchor) return null;
+  const start = visiblePageIndexRange?.start ?? 0;
+  const end = Math.min(
+    visiblePageIndexRange?.end ?? pageCount,
+    pageCount,
+  );
+  // Flicker-remediation 2026-04-22 (all-or-nothing policy): a single
+  // missing visible-page anchor returns null so the caller falls
+  // through to the geometry/DOM path instead of rendering a partial
+  // rect set. Under the prior "skip missing rows" policy a transiently-
+  // unresolved anchor during relayout would drop the paper background
+  // for pages 2..N while page 1 stayed painted — visibly gray bands
+  // between white papers. Atomic resolution forces consistency.
+  const rects: PageOverlayRect[] = [];
+  for (let i = start; i < end; i += 1) {
+    const rect =
+      i === 0 ? firstAnchor : ui.overlays.getAnchor({ kind: "page", value: i });
+    if (!rect) {
+      return null;
+    }
+    rects.push({
+      pageId: pageIds?.[i] ?? `page-${i}`,
+      pageIndex: i,
+      topPx: rect.topPx,
+      bottomPx: rect.topPx + rect.heightPx,
+      heightPx: rect.heightPx,
+    });
+  }
+  return rects;
+}
+
 /**
  * The layer itself.  Renders one decorative `<div>` per page with the
  * same card-shadow + rounded border treatment that `.wre-page-chrome`
@@ -417,12 +511,34 @@ export interface TwPageStackOverlayLayerProps {
  */
 export const TwPageStackOverlayLayer: React.FC<TwPageStackOverlayLayerProps> = ({
   facet,
+  geometryFacet,
   scrollRoot,
   renderFrameRevision,
   visiblePageIndexRange,
   "data-testid": testId,
 }) => {
-  const [rects, setRects] = React.useState<readonly PageOverlayRect[]>([]);
+  // DS-C2 — prefer `ui.overlays.getAnchor({ kind: "page", ... })` as
+  // the page-rect read seam when a `UiApiProvider` is mounted. Returns
+  // null here when headless / off-provider; the overlay then falls
+  // through to the existing geometry-facet / DOM paths.
+  const ui = useUiApi();
+  // Flicker-remediation 2026-04-22: compute initial rects synchronously
+  // from the geometry facet when the kernel is already warm, so the
+  // first paint has correct paper cards instead of an empty overlay
+  // that only populates after `useEffect` ticks. Cold-open paths where
+  // `geometryFacet` isn't passed / returns null still fall back to
+  // the empty initial state + the fallback paper rendered below.
+  const [rects, setRects] = React.useState<readonly PageOverlayRect[]>(() => {
+    if (!geometryFacet) return [];
+    const pageCount = facet.getPageCount();
+    if (pageCount <= 0) return [];
+    const warm = resolvePageOverlayRectsFromGeometry(
+      geometryFacet,
+      pageCount,
+      visiblePageIndexRange,
+    );
+    return warm ?? [];
+  });
   // 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
@@ -457,6 +573,61 @@ export const TwPageStackOverlayLayer: React.FC<TwPageStackOverlayLayerProps> = (
     }
     const origin = overlayRootRef.current;
     const pageCount = facet.getPageCount();
+
+    // DS-C2 — first try the UI API seam so presentation code does not
+    // reach into the geometry facet directly. Page-ids come from the
+    // geometry facet when the caller forwarded one; synthesized
+    // otherwise. When `ui.overlays.getAnchor` returns null for page 0
+    // the geometry-direct and DOM paths below still run.
+    //
+    // §4.10 telemetry (2026-04-23) — the all-or-nothing resolution
+    // policy above is correct but unprobed. `overlay.page.ui_api.hit`
+    // increments when the UI-API path resolves the full visible-range;
+    // `overlay.page.ui_api.fallthrough` increments when the path
+    // returns null and we continue to the geometry/DOM fallback. The
+    // ratio lets a future bench assert fall-through stays below a
+    // threshold during steady-state typing (follow-up work — bench
+    // setup for F01/F08 typing scenarios is a separate task).
+    if (ui) {
+      const pageIds: string[] | null = geometryFacet
+        ? Array.from({ length: pageCount }, (_, i) => {
+            const page = geometryFacet.getPage(i);
+            return page?.pageId ?? `page-${i}`;
+          })
+        : null;
+      const uiRects = resolvePageOverlayRectsFromUiApi(
+        ui,
+        pageCount,
+        visiblePageIndexRange,
+        pageIds,
+      );
+      if (uiRects !== null) {
+        incrementInvalidationCounter("overlay.page.ui_api.hit");
+        setRects(uiRects);
+        return;
+      }
+      incrementInvalidationCounter("overlay.page.ui_api.fallthrough");
+    } else {
+      incrementInvalidationCounter("overlay.page.ui_api.unavailable");
+    }
+
+    // Slice 3b: when the geometry facet resolves page 0 through the
+    // render kernel, read rects directly from the kernel frame — zero
+    // DOM measurement, zero forced layouts. The DOM path below remains
+    // for the cold-open window (first frame not yet emitted) and for
+    // wiring sites that haven't handed over a geometry facet.
+    if (geometryFacet) {
+      const geometryRects = resolvePageOverlayRectsFromGeometry(
+        geometryFacet,
+        pageCount,
+        visiblePageIndexRange,
+      );
+      if (geometryRects !== null) {
+        setRects(geometryRects);
+        return;
+      }
+    }
+
     if (origin) {
       const widgets = measureWidgetsViaBoundingRect(scrollRoot, origin, {
         pageCount,
@@ -486,7 +657,7 @@ export const TwPageStackOverlayLayer: React.FC<TwPageStackOverlayLayerProps> = (
         }),
       );
     }
-  }, [facet, scrollRoot, visiblePageIndexRange]);
+  }, [facet, geometryFacet, scrollRoot, ui, visiblePageIndexRange]);
 
   const refreshRects = React.useCallback(() => {
     if (!scrollRoot) {
@@ -597,6 +768,16 @@ export const TwPageStackOverlayLayer: React.FC<TwPageStackOverlayLayerProps> = (
   // 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.
+  //
+  // Flicker-remediation 2026-04-22: when rects are not yet available
+  // (cold-open; geometry facet has no kernel yet; DOM not measured),
+  // paint a full-area paper-color fallback card so the user sees a
+  // white page rather than the gray workspace canvas flashing through.
+  // The fallback uses the same paper chrome (bg / border / shadow /
+  // radius) as individual page cards, rendered as `inset-0` so it
+  // spans whatever region the scroll root currently occupies. When
+  // `rects` populates on the next refresh pass the fallback is
+  // replaced by N discrete cards.
   if (rects.length === 0) {
     return (
       <div
@@ -605,7 +786,20 @@ export const TwPageStackOverlayLayer: React.FC<TwPageStackOverlayLayerProps> = (
         aria-hidden="true"
         data-testid={testId ?? "page-stack-overlay"}
         data-page-count="0"
-      />
+        data-fallback-paper="true"
+      >
+        <div
+          className="wre-page-stack-overlay-frame wre-page-stack-overlay-frame--fallback absolute inset-0"
+          aria-hidden="true"
+          style={{
+            backgroundColor: "var(--color-page-bg, white)",
+            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>
     );
   }
 

package/src/ui-tailwind/chrome-overlay/tw-revision-margin-bar-layer.tsx

@@ -1,5 +1,5 @@
 import * as React from "react";
-import type { RenderBlockDecoration } from "../../runtime/render/render-frame-types";
+import type { RenderBlockDecoration } from "../../api/public-types.ts";
 import { AUTHOR_PALETTE } from "../../ui/headless/revision-decoration-model";
 
 const BAR_WIDTH_PX = 3;

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

@@ -24,21 +24,33 @@ import {
   type OverlayCoordinateSpace,
 } from "./chrome-overlay-projector";
 import { TwScopeCard } from "./tw-scope-card";
+import { useLocalSurfaceRequest } from "../chrome/local-surface-arbiter";
 import type {
   EditorRole,
   ScopeCardModel,
   ScopeIssueAction,
   WorkflowScopeMode,
 } from "../../api/public-types";
-import type { RenderFrameRect } from "../../runtime/render";
-import type { WordReviewEditorLayoutFacet } from "../../runtime/layout";
+import type { RenderFrameRect } from "../../api/public-types.ts";
+import type { WordReviewEditorLayoutFacet } from "../../api/public-types.ts";
+import type { WorkflowFacet } from "../../api/public-types.ts";
 
 // ---------------------------------------------------------------------------
 // Types
 // ---------------------------------------------------------------------------
 
 export interface TwScopeCardLayerProps {
+  /**
+   * Layout facet — still required for `getRenderFrame()` etc. Scope-
+   * card data now flows through `workflowFacet` per Layer-06 Slice 4.
+   */
   facet: WordReviewEditorLayoutFacet;
+  /**
+   * Workflow facet — canonical source of scope card models
+   * (`runtime.workflow.getAllScopeCardModels()`). `null` is treated as
+   * "no cards".
+   */
+  workflowFacet: WorkflowFacet | null;
   activeScopeId: string | null;
   onClose: () => void;
   onModeChange: (scopeId: string, mode: WorkflowScopeMode) => void;
@@ -77,6 +89,7 @@ const CARD_FALLBACK_TOP_PX = 16;
 
 export const TwScopeCardLayer: React.FC<TwScopeCardLayerProps> = ({
   facet,
+  workflowFacet,
   activeScopeId,
   onClose,
   onModeChange,
@@ -106,10 +119,7 @@ export const TwScopeCardLayer: React.FC<TwScopeCardLayerProps> = ({
   // The effective scope is the pinned one if it still resolves to a
   // model, else the active one.  When a pinned scope disappears
   // (e.g. the host cleared the overlay), drop the pin.
-  const models =
-    typeof facet.getAllScopeCardModels === "function"
-      ? facet.getAllScopeCardModels()
-      : [];
+  const models = workflowFacet?.getAllScopeCardModels() ?? [];
 
   const pinnedModel = pinnedScopeId
     ? models.find((m) => m.scopeId === pinnedScopeId) ?? null
@@ -128,10 +138,29 @@ export const TwScopeCardLayer: React.FC<TwScopeCardLayerProps> = ({
   }, [pinnedScopeId, models]);
 
   const effectiveScopeId = pinnedModel ? pinnedScopeId : activeScopeId;
+  const isPinnedEffective = pinnedScopeId !== null && pinnedScopeId === effectiveScopeId;
+
+  // Phase F.3 — request the scope-card slot from the shared arbiter.
+  // Pinned scope cards go into the orthogonal pinned slot so the rail
+  // (or a peer surface) can coexist; non-pinned scope cards take the
+  // single active slot at priority 7 and displace every lower peer.
+  // The hook MUST be called unconditionally — pass `null` when no
+  // scope is effective, which is a safe no-op.
+  const isArbiterActive = useLocalSurfaceRequest(
+    effectiveScopeId
+      ? {
+          kind: "scope-card",
+          id: effectiveScopeId,
+          pinned: isPinnedEffective,
+        }
+      : null,
+  );
+
   if (!effectiveScopeId) return null;
   const model: ScopeCardModel | undefined =
     pinnedModel ?? models.find((m) => m.scopeId === effectiveScopeId);
   if (!model) return null;
+  if (!isArbiterActive) return null;
 
   const projectorSpace: OverlayCoordinateSpace =
     space ?? { originLeftPx: 0, originTopPx: 0 };

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

@@ -17,17 +17,29 @@ import {
   projectRectToOverlay,
   type OverlayCoordinateSpace,
 } from "./chrome-overlay-projector";
-import type { RenderFrame, RenderFrameRect } from "../../runtime/render";
-import type { ScopeRailSegment, ScopeRailPosture } from "../../runtime/layout";
-import type { WordReviewEditorLayoutFacet } from "../../runtime/layout";
+import type { RenderFrame, RenderFrameRect } from "../../api/public-types.ts";
+import type { ScopeRailSegment, ScopeRailPosture } from "../../api/public-types.ts";
+import type { WorkflowFacet } from "../../api/public-types.ts";
+import type { GeometryFacet } from "../../api/public-types";
 
 // ---------------------------------------------------------------------------
 // Types
 // ---------------------------------------------------------------------------
 
 export interface TwScopeRailLayerProps {
-  /** Layout facet that provides segments + render frame. */
-  facet: WordReviewEditorLayoutFacet;
+  /**
+   * Geometry facet — used for `getRenderFrame()`. Migrated from
+   * `facet: WordReviewEditorLayoutFacet` in refactor/05 cross-lane-coord
+   * §8.4 pass. Rail-segment + scope-card data flows through
+   * `workflowFacet` per Layer-06 Slice 4's seam inversion.
+   */
+  geometryFacet: GeometryFacet;
+  /**
+   * Workflow facet — canonical source of scope rail segments + scope
+   * card models (`runtime.workflow.*`). Required for the layer to
+   * render anything; passing `null` makes the layer a no-op.
+   */
+  workflowFacet: WorkflowFacet | null;
   /** Overlay's coordinate space.  Defaults to the overlay's own origin. */
   space?: OverlayCoordinateSpace;
   /** Horizontal pad (px) the rail gutter occupies to the left of body. */
@@ -80,7 +92,8 @@ const LABEL_WIDTH_PX = 40;
 const STACK_OFFSET_PX = 6;
 
 export const TwScopeRailLayer: React.FC<TwScopeRailLayerProps> = ({
-  facet,
+  geometryFacet,
+  workflowFacet,
   space,
   railLaneWidthPx = DEFAULT_RAIL_LANE_PX,
   activeScopeId,
@@ -88,10 +101,8 @@ export const TwScopeRailLayer: React.FC<TwScopeRailLayerProps> = ({
   onSegmentClick,
   "data-testid": testId,
 }) => {
-  const frame = typeof facet.getRenderFrame === "function"
-    ? facet.getRenderFrame() ?? null
-    : null;
-  const segments = facet.getAllScopeRailSegments();
+  const frame = geometryFacet.getRenderFrame() ?? null;
+  const segments = workflowFacet?.getAllRailSegments() ?? [];
 
   if (!frame || segments.length === 0) {
     return null;
@@ -99,12 +110,9 @@ export const TwScopeRailLayer: React.FC<TwScopeRailLayerProps> = ({
 
   // P2: which scopes currently have a `source: "ai"` candidate
   // overlapping — drives the agent-pending shimmer class on their
-  // tints.  Reads from the facet's card-model projection so the
-  // shimmer logic lives in the runtime, not the overlay.
-  const cardModels =
-    typeof facet.getAllScopeCardModels === "function"
-      ? facet.getAllScopeCardModels()
-      : [];
+  // tints. Reads from the workflow facet's card-model projection so the
+  // shimmer logic lives in the Layer-06 runtime, not the overlay.
+  const cardModels = workflowFacet?.getAllScopeCardModels() ?? [];
   const agentPendingByScope = new Map<string, boolean>();
   for (const model of cardModels) {
     if (model.agentPending) {

package/src/ui-tailwind/chrome-overlay/tw-table-continuation-header.tsx

@@ -11,7 +11,7 @@
 
 import React from "react";
 import type { SurfaceTableRowSnapshot } from "../../api/public-types.ts";
-import type { WordReviewEditorLayoutFacet } from "../../runtime/layout/public-facet.ts";
+import type { WordReviewEditorLayoutFacet } from "../../api/public-types.ts";
 
 export interface TwTableContinuationHeaderProps {
   blockId: string;

package/src/ui-tailwind/debug/README.md

@@ -0,0 +1,57 @@
+# Phase Q — Debug UX (reserved)
+
+Target for the runtime-embedded debug UX consumed through `ui.debug.attach()`
+(layer 10, refactor/10 Slice 5). This directory is **reserved** — the Slice 5
+ship includes the UI API substrate (`src/api/v3/ui/debug.ts` +
+`UiController.attachDebug` hook), while the React presentation components +
+the public `debugMode` prop + the visibility invariant test are a **Phase Q
+follow-up** per `docs/plans/refactor/10-ui-api.md` Risk #3:
+
+> **Phase Q UX surface area.** `src/ui-tailwind/debug/**` is a new substantial
+> UI surface. *Mitigation:* ship substrate in M4 Slice 5; polish in follow-up.
+
+## Planned files (follow-up)
+
+| File | Purpose |
+|---|---|
+| `tw-debug-top-bar.tsx` | Minimal top bar when `debugMode: "top-bar"` — document hash, scope count, invalidation counter |
+| `tw-debug-overlay.tsx` | Full overlay when `debugMode: "full"` — renders `DebugInspectorSnapshot` sections |
+| `tw-debug-repl.tsx` | REPL with `api`, `runtime`, `debug` in scope; localStorage-persisted history |
+| `tw-debug-event-tail.tsx` | Tail of the last N events on active telemetry channels |
+| `keybindings.ts` | Cmd/Ctrl+Shift+D toggles top-bar ↔ full |
+
+## Planned prop (follow-up)
+
+Add `debugMode?: "off" | "top-bar" | "full"` to `WordReviewEditorProps`.
+**Default MUST be `"off"`** per CLAUDE.md Protected Invariants § "Phase Q
+placeholder" — this default has regressed multiple times in predecessor
+surfaces (`showUnsupportedObjectPreviews`, `unsupportedPreviewsPolicy`).
+
+## Planned test (follow-up)
+
+`test/ui/debug-mode-visibility-invariant.test.ts` — asserts:
+- `debugMode: "off"` → no debug UI renders
+- `debugMode: "top-bar"` → only the top bar renders
+- `debugMode: "full"` → overlay renders
+
+## How Slice 5 consumers wire today
+
+Until the Phase Q React components land, Slice 5 ships only the contract:
+
+```ts
+import { createUiApi } from "@beyondwork/docx-react-component/api/v3/ui";
+
+const ui = createUiApi(handle);
+ui.session.bind({
+  kind: "runtime-direct",
+  id: "my-mount",
+  attachDebug(session) {
+    // bind-side: wire runtime.debug.bus + getSnapshot to your debug surface
+    const off = runtime.debug.bus.on(/* ... */, (evt) => {/* render */});
+    return () => off();
+  },
+});
+const attachment = ui.debug.attach({ id: "s1", channels: ["api", "render"] });
+// later:
+attachment.detach();
+```

package/src/ui-tailwind/debug/index.ts

@@ -0,0 +1,3 @@
+export { TwDebugTopBar, type TwDebugTopBarProps } from "./tw-debug-top-bar.tsx";
+export { TwDebugOverlay, type TwDebugOverlayProps } from "./tw-debug-overlay.tsx";
+export { TwDebugPresentation, type TwDebugPresentationProps } from "./tw-debug-presentation.tsx";