@beyondwork/docx-react-component 1.0.81 → 1.0.82

package/src/ui-tailwind/review-workspace/use-page-markers.ts

@@ -1,16 +1,24 @@
 import { useEffect, useMemo, useState } from "react";
 
-import type { RuntimeRenderSnapshot } from "../../api/public-types.ts";
+import type { GeometryFacet, RuntimeRenderSnapshot } from "../../api/public-types.ts";
 import {
+  resolveVisibleBlockRangesFromPageOffsets,
+  resolveVisibleBlockRangesFromPageRange,
+  resolveVisiblePageIndexRangeFromViewport,
   useVisibleBlockRange,
   useVisibleBlockRanges,
   useVisiblePageIndexRange,
+  type VisiblePageIndexRange,
 } from "../page-stack/use-visible-block-range.ts";
 
 export interface UsePageMarkersOptions {
   pageStackScrollRoot: HTMLElement | null;
   snapshot: RuntimeRenderSnapshot;
   layoutFacet?: import("../../runtime/layout/index.ts").WordReviewEditorLayoutFacet;
+  geometryFacet?: GeometryFacet;
+  renderFrameRevision?: number;
+  /** CSS zoom applied to the document surface; scroll pixels are normalized by this. */
+  viewportScale?: number;
 }
 
 export interface PageMarkersResult {
@@ -27,6 +35,151 @@ export interface PageMarkersResult {
   visiblePageIndexRange: ReturnType<typeof useVisiblePageIndexRange>;
 }
 
+function pageRangeEqual(
+  a: VisiblePageIndexRange | null,
+  b: VisiblePageIndexRange | null,
+): boolean {
+  if (a === b) return true;
+  if (!a || !b) return false;
+  return a.start === b.start && a.end === b.end;
+}
+
+function readMarkerSignature(el: HTMLElement): string {
+  return [
+    el.getAttribute("data-page-frame") ?? "",
+    el.getAttribute("data-page-first-block-index") ?? "",
+    el.getAttribute("data-page-last-block-index") ?? "",
+  ].join(":");
+}
+
+function isSyntheticPageZeroMarker(el: HTMLElement): boolean {
+  return !el.isConnected && el.getAttribute("data-page-frame") === "0";
+}
+
+function pageMarkersEqual(
+  a: readonly HTMLElement[],
+  b: readonly HTMLElement[],
+): 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 === right) continue;
+    if (
+      isSyntheticPageZeroMarker(left) &&
+      isSyntheticPageZeroMarker(right) &&
+      readMarkerSignature(left) === readMarkerSignature(right)
+    ) {
+      continue;
+    }
+    return false;
+  }
+  return true;
+}
+
+function useGeometryVisiblePageIndexRange(input: {
+  scrollRoot: HTMLElement | null;
+  geometryFacet?: GeometryFacet;
+  layoutFacet?: import("../../runtime/layout/index.ts").WordReviewEditorLayoutFacet;
+  pageMarkerCount: number;
+  overscanPages: number;
+  renderFrameRevision?: number;
+  viewportScale?: number;
+}): VisiblePageIndexRange | null {
+  const {
+    scrollRoot,
+    geometryFacet,
+    layoutFacet,
+    pageMarkerCount,
+    overscanPages,
+    renderFrameRevision,
+    viewportScale,
+  } = input;
+  const [range, setRange] = useState<VisiblePageIndexRange | null>(null);
+
+  useEffect(() => {
+    if (!scrollRoot || !geometryFacet) {
+      setRange((prev) => (prev === null ? prev : null));
+      return undefined;
+    }
+
+    const runtime = scrollRoot.ownerDocument?.defaultView as
+      | (Window & {
+          requestAnimationFrame?: (cb: () => void) => number;
+          cancelAnimationFrame?: (handle: number) => void;
+          ResizeObserver?: typeof ResizeObserver;
+        })
+      | null;
+    let rafHandle: number | null = null;
+    let disposed = false;
+
+    const publish = () => {
+      if (disposed) return;
+      const pageCount = layoutFacet?.getPageCount() ?? pageMarkerCount;
+      const scale =
+        typeof viewportScale === "number" &&
+        Number.isFinite(viewportScale) &&
+        viewportScale > 0
+          ? viewportScale
+          : 1;
+      const next = resolveVisiblePageIndexRangeFromViewport({
+        pageCount,
+        viewportTopPx: scrollRoot.scrollTop / scale,
+        viewportHeightPx: scrollRoot.clientHeight / scale,
+        overscanPages,
+        getPageFrame: (pageIndex) => {
+          const page = geometryFacet.getPage(pageIndex);
+          return page ? page.frame : null;
+        },
+      });
+      setRange((prev) => (pageRangeEqual(prev, next) ? prev : next));
+    };
+
+    const schedule = () => {
+      if (disposed || rafHandle !== null) return;
+      const raf = runtime?.requestAnimationFrame;
+      if (!raf) {
+        publish();
+        return;
+      }
+      rafHandle = raf.call(runtime, () => {
+        rafHandle = null;
+        publish();
+      });
+    };
+
+    publish();
+    scrollRoot.addEventListener("scroll", schedule, { passive: true });
+
+    const ResizeObserverCtor = runtime?.ResizeObserver;
+    const resizeObserver = ResizeObserverCtor
+      ? new ResizeObserverCtor(schedule)
+      : null;
+    resizeObserver?.observe(scrollRoot);
+
+    return () => {
+      disposed = true;
+      scrollRoot.removeEventListener("scroll", schedule);
+      resizeObserver?.disconnect();
+      if (rafHandle !== null && runtime?.cancelAnimationFrame) {
+        runtime.cancelAnimationFrame(rafHandle);
+        rafHandle = null;
+      }
+    };
+  }, [
+    geometryFacet,
+    layoutFacet,
+    overscanPages,
+    pageMarkerCount,
+    renderFrameRevision,
+    scrollRoot,
+    viewportScale,
+  ]);
+
+  return range;
+}
+
 /**
  * L7 Phase 2 Task 2.2.4a — viewport-scroll wiring.
  *
@@ -46,17 +199,29 @@ export interface PageMarkersResult {
  * `data-page-frame="N+1"`, so page 0 has no widget before it.
  */
 export function usePageMarkers(options: UsePageMarkersOptions): PageMarkersResult {
-  const { pageStackScrollRoot, snapshot, layoutFacet } = options;
+  const {
+    pageStackScrollRoot,
+    snapshot,
+    layoutFacet,
+    geometryFacet,
+    renderFrameRevision,
+    viewportScale,
+  } = options;
+  const overscanPages = 2;
 
   const [pageMarkers, setPageMarkers] = useState<readonly HTMLElement[]>([]);
 
   useEffect(() => {
     const root = pageStackScrollRoot;
     if (!root) {
-      setPageMarkers([]);
+      setPageMarkers((prev) => (prev.length === 0 ? prev : []));
       return undefined;
     }
-    const refresh = () => {
+    const view = root.ownerDocument?.defaultView;
+    let rafHandle: number | null = null;
+    let disposed = false;
+
+    const collectMarkers = (): readonly HTMLElement[] => {
       const found = Array.from(root.querySelectorAll<HTMLElement>("[data-page-frame]"));
       const hasPage0 = found.some(
         (el) => el.getAttribute("data-page-frame") === "0",
@@ -76,17 +241,42 @@ export function usePageMarkers(options: UsePageMarkersOptions): PageMarkersResul
         synth.setAttribute("data-page-frame", "0");
         synth.setAttribute("data-page-first-block-index", "0");
         synth.setAttribute("data-page-last-block-index", String(Math.max(0, page0Last)));
-        setPageMarkers([synth, ...found]);
-      } else {
-        setPageMarkers(found);
+        return [synth, ...found];
       }
+      return found;
     };
-    refresh();
-    const view = root.ownerDocument?.defaultView;
+
+    const publish = () => {
+      if (disposed) return;
+      const next = collectMarkers();
+      setPageMarkers((prev) => (pageMarkersEqual(prev, next) ? prev : next));
+    };
+
+    const schedulePublish = () => {
+      if (disposed || rafHandle !== null) return;
+      const raf = view?.requestAnimationFrame;
+      if (!raf) {
+        publish();
+        return;
+      }
+      rafHandle = raf.call(view, () => {
+        rafHandle = null;
+        publish();
+      });
+    };
+
+    publish();
     if (!view?.MutationObserver) return undefined;
-    const mo = new view.MutationObserver(refresh);
+    const mo = new view.MutationObserver(schedulePublish);
     mo.observe(root, { childList: true, subtree: true });
-    return () => mo.disconnect();
+    return () => {
+      disposed = true;
+      mo.disconnect();
+      if (rafHandle !== null && view.cancelAnimationFrame) {
+        view.cancelAnimationFrame(rafHandle);
+        rafHandle = null;
+      }
+    };
     // Re-run when the scroll root changes OR when a new snapshot lands
     // (which may have a different page count and new widgets in the PM DOM).
     // NOTE: snapshot.surface is intentionally excluded — its reference changes on
@@ -108,13 +298,83 @@ export function usePageMarkers(options: UsePageMarkersOptions): PageMarkersResul
     return null;
   }, [snapshot.selection, snapshot.surface]);
 
-  const visibleBlockRanges = useVisibleBlockRanges({
+  const markerVisibleBlockRanges = useVisibleBlockRanges({
     pageMarkers,
-    overscanPages: 2,
+    overscanPages,
     selectionBlockIndex,
     totalBlockCount: snapshot.surface?.blocks.length ?? 0,
   });
 
+  // Marker IO is retained as the cold-open/degraded path, but the warm editor
+  // path derives the page window from render-kernel geometry plus viewport
+  // scroll. Boundary widgets only exist in the inter-page gaps; using them as
+  // primary visibility sentinels makes culling disappear while the user is in
+  // the middle of a page.
+  const markerVisiblePageIndexRange = useVisiblePageIndexRange({
+    pageMarkers,
+    overscanPages,
+  });
+  const geometryVisiblePageIndexRange = useGeometryVisiblePageIndexRange({
+    scrollRoot: pageStackScrollRoot,
+    geometryFacet,
+    layoutFacet,
+    pageMarkerCount: pageMarkers.length,
+    overscanPages,
+    renderFrameRevision,
+    viewportScale,
+  });
+  const visiblePageIndexRange =
+    geometryVisiblePageIndexRange ?? markerVisiblePageIndexRange;
+
+  const visibleBlockRangesFromPageOffsets = useMemo(
+    () =>
+      visiblePageIndexRange && layoutFacet
+        ? resolveVisibleBlockRangesFromPageOffsets({
+            blocks: snapshot.surface?.blocks ?? [],
+            pageCount: layoutFacet.getPageCount(),
+            visiblePageIndexRange,
+            selectionBlockIndex,
+            totalBlockCount: snapshot.surface?.blocks.length ?? 0,
+            getPageOffsets: (pageIndex) => {
+              const page = layoutFacet.getPage(pageIndex);
+              return page
+                ? { startOffset: page.startOffset, endOffset: page.endOffset }
+                : null;
+            },
+          })
+        : null,
+    [
+      layoutFacet,
+      selectionBlockIndex,
+      snapshot.surface?.blocks,
+      snapshot.surface?.blocks.length,
+      visiblePageIndexRange,
+    ],
+  );
+
+  const visibleBlockRangesFromPageRange = useMemo(
+    () =>
+      visiblePageIndexRange
+        ? resolveVisibleBlockRangesFromPageRange({
+            pageMarkers,
+            visiblePageIndexRange,
+            selectionBlockIndex,
+            totalBlockCount: snapshot.surface?.blocks.length ?? 0,
+          })
+        : null,
+    [
+      pageMarkers,
+      selectionBlockIndex,
+      snapshot.surface?.blocks.length,
+      visiblePageIndexRange,
+    ],
+  );
+
+  const visibleBlockRanges =
+    visibleBlockRangesFromPageOffsets ??
+    visibleBlockRangesFromPageRange ??
+    markerVisibleBlockRanges;
+
   // Bounding hull of the disjoint ranges for the back-compat `visibleBlockRange`
   // result field + for the effect's dep key (below).
   const visibleBlockRange = useMemo(() => {
@@ -128,17 +388,6 @@ export function usePageMarkers(options: UsePageMarkersOptions): PageMarkersResul
     return { start, end };
   }, [visibleBlockRanges]);
 
-  // L7 Phase 2.8 — viewport cull for `TwPageStackChromeLayer`. Returns
-  // `null` while the IntersectionObserver hasn't reported yet; the chrome
-  // layer treats null as "render every page" so first paint is
-  // unaffected. Once the observer fires, the chrome layer only mounts
-  // bands for pages inside `[start, end)` plus overscan, eliminating the
-  // measured 412 ms Layout + 229 ms Pre-paint cost on 138-pp extra-large.
-  const visiblePageIndexRange = useVisiblePageIndexRange({
-    pageMarkers,
-    overscanPages: 2,
-  });
-
   // Stable fingerprint of the current disjoint-range set; used as the effect
   // dep so identity-preserving recomputes (same intervals, new memo array
   // reference) don't re-fire the viewport refresh.

package/src/ui-tailwind/theme/editor-theme.css

@@ -83,12 +83,10 @@
    * The outer `.wre-page-chrome` wrapper paints this; the inner paper
    * frame paints the white `--color-page-bg` on top.
    *
-   * L8 polish (2026-04-19): darkened from #e7e5e4 → #d4d1cc so the canvas
-   * reads as a distinctly different surface from the white paper (the
-   * earlier tone was close enough that the paper edges blurred against
-   * the canvas on high-brightness screens).
+   * Editor-experience pass (2026-04-23): keep the canvas quiet so paper
+   * edges come from the card border + shadow, not a high-contrast gray field.
    */
-  --color-workspace-canvas: #d4d1cc;
+  --color-workspace-canvas: #f7f8fa;
 
   /*
    * ─── Radius tokens (balanced 10 / 8 / 4 / 2) ───

package/src/ui-tailwind/tw-review-workspace.tsx

@@ -366,6 +366,9 @@ export function TwReviewWorkspace(inputProps: TwReviewWorkspaceProps) {
     pageStackScrollRoot,
     snapshot,
     layoutFacet: props.layoutFacet,
+    geometryFacet: props.geometryFacet,
+    renderFrameRevision,
+    viewportScale: zoomScale,
   });
 
   const { dismissSelectionToolbar, runWithSelectionToolbarDismiss } =