@beyondwork/docx-react-component 1.0.47 → 1.0.49

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

@@ -128,6 +128,23 @@ export interface TwPageStackChromeLayerProps {
    * DOM element; only the refocus step is skipped.
    */
   pmView?: PmPortalView | null;
+  /**
+   * L7 Phase 2.8 — optional viewport cull. When supplied, the chrome
+   * layer only mounts per-page header / footer / footnote bands for
+   * pages whose sequential index falls inside this range (with overscan
+   * already applied by the caller). Pages outside the range render a
+   * lightweight wrapper `div` carrying the `data-page-chrome-frame` +
+   * `data-page-index` attributes — every position read (portal-slot
+   * query, per-page measurement) continues to resolve deterministically,
+   * but the four child React subtrees (Header/Footer/Footnote bands)
+   * never mount, eliminating the measured 412 ms Layout + 229 ms
+   * Pre-paint cost on 138-pp extra-large CCEP per the rev5 Chrome trace.
+   *
+   * Omit the prop (or pass `null`) to render every page — current
+   * behavior, used on first mount before the IntersectionObserver has
+   * reported.
+   */
+  visiblePageIndexRange?: { start: number; end: number } | null;
   /** Optional test id applied to the layer root. */
   "data-testid"?: string;
 }
@@ -140,6 +157,7 @@ export const TwPageStackChromeLayer: React.FC<TwPageStackChromeLayerProps> = ({
   onOpenStory,
   pmSurfaceElement,
   pmView,
+  visiblePageIndexRange,
   "data-testid": testId,
 }) => {
   const [rects, setRects] = React.useState<readonly PageOverlayRect[]>([]);
@@ -352,6 +370,35 @@ export const TwPageStackChromeLayer: React.FC<TwPageStackChromeLayerProps> = ({
         const page = facet.getPage(pageIndex);
         if (!page) return null;
 
+        // L7 Phase 2.8 — viewport cull. Pages outside the visible range
+        // (plus overscan) render an empty frame wrapper: the
+        // `data-page-chrome-frame` + `data-page-index` attributes stay
+        // put so downstream DOM queries (portal-slot, test hooks) keep
+        // working, but the four heavy React subtrees below do not mount.
+        const frameHeightPxForCull = rect.bottomPx - rect.topPx;
+        if (
+          visiblePageIndexRange &&
+          (pageIndex < visiblePageIndexRange.start ||
+            pageIndex >= visiblePageIndexRange.end)
+        ) {
+          return (
+            <div
+              key={`page-chrome-${rect.pageId}`}
+              data-page-chrome-frame=""
+              data-page-index={pageIndex}
+              data-page-chrome-culled=""
+              style={{
+                position: "absolute",
+                top: `${rect.topPx}px`,
+                left: 0,
+                width: "100%",
+                height: `${frameHeightPxForCull}px`,
+                pointerEvents: "none",
+              }}
+            />
+          );
+        }
+
         const layout = page.layout;
         const headerStory = page.stories.header;
         const footerStory = page.stories.footer;

package/src/ui-tailwind/page-stack/use-visible-block-range.ts

@@ -37,6 +37,19 @@ export interface BlockRange {
   end: number; // exclusive
 }
 
+/**
+ * L7 Phase 2.8 — parallel result the chrome-overlay layers use to cull
+ * per-page React mounts. Expressed as sequential 0-based page indices
+ * (matching `facet.getPage(pageIndex)` + `pageMarkers.indexOf(marker)`),
+ * NOT the block indices stored on `data-page-frame`. `null` signals "no
+ * visibility signal yet — render every page" (initial-load fallback).
+ * Overscan is already applied to both sides.
+ */
+export interface VisiblePageIndexRange {
+  start: number; // inclusive
+  end: number; // exclusive
+}
+
 function readBlockIndex(el: HTMLElement, attr: string): number | null {
   const v = el.getAttribute(attr);
   if (v === null) return null;
@@ -155,3 +168,78 @@ export function useVisibleBlockRange(input: VisibleBlockRangeInput): BlockRange
     };
   }, [visiblePages, selectionBlockIndex, pageMarkers, overscanPages, totalBlockCount]);
 }
+
+/**
+ * L7 Phase 2.8 — sibling hook returning the visible sequential page index
+ * range for chrome-overlay viewport culling. Reuses the same
+ * IntersectionObserver wiring as `useVisibleBlockRange` but translates the
+ * visible-set of `data-page-frame` first-block-indices into SEQUENTIAL
+ * page indices via the order of `pageMarkers`. Returns `null` while the
+ * observer hasn't reported yet (fresh mount) — callers treat that as
+ * "render every page" and fall through to the current non-culled path.
+ *
+ * Overscan is applied on both sides so a single rapid scroll does not
+ * unmount chrome that is about to be revisible.
+ */
+export function useVisiblePageIndexRange(input: {
+  pageMarkers: readonly HTMLElement[];
+  overscanPages: number;
+}): VisiblePageIndexRange | null {
+  const { pageMarkers, overscanPages } = input;
+  const [visiblePageFirstBlockIndices, setVisiblePageFirstBlockIndices] =
+    React.useState<Set<number>>(() => new Set());
+
+  React.useEffect(() => {
+    setVisiblePageFirstBlockIndices(new Set());
+    if (pageMarkers.length === 0) return;
+    const view = pageMarkers[0].ownerDocument?.defaultView;
+    if (!view?.IntersectionObserver) return;
+
+    const observer = new view.IntersectionObserver(
+      (entries) => {
+        setVisiblePageFirstBlockIndices((prev) => {
+          const next = new Set(prev);
+          let changed = false;
+          for (const entry of entries) {
+            const idx = readBlockIndex(entry.target as HTMLElement, "data-page-frame");
+            if (idx === null) continue;
+            const was = next.has(idx);
+            if (entry.isIntersecting && !was) {
+              next.add(idx);
+              changed = true;
+            } else if (!entry.isIntersecting && was) {
+              next.delete(idx);
+              changed = true;
+            }
+          }
+          return changed ? next : prev;
+        });
+      },
+      { root: null, rootMargin: "0px", threshold: 0 },
+    );
+
+    for (const marker of pageMarkers) observer.observe(marker);
+    return () => observer.disconnect();
+  }, [pageMarkers]);
+
+  return React.useMemo(() => {
+    if (pageMarkers.length === 0) return null;
+    if (visiblePageFirstBlockIndices.size === 0) return null;
+
+    let minSeq = Infinity;
+    let maxSeq = -Infinity;
+    pageMarkers.forEach((marker, seqIndex) => {
+      const firstBlockIdx = readBlockIndex(marker, "data-page-frame");
+      if (firstBlockIdx === null) return;
+      if (!visiblePageFirstBlockIndices.has(firstBlockIdx)) return;
+      if (seqIndex < minSeq) minSeq = seqIndex;
+      if (seqIndex > maxSeq) maxSeq = seqIndex;
+    });
+    if (minSeq === Infinity) return null;
+
+    return {
+      start: Math.max(0, minSeq - overscanPages),
+      end: Math.min(pageMarkers.length, maxSeq + overscanPages + 1),
+    };
+  }, [visiblePageFirstBlockIndices, pageMarkers, overscanPages]);
+}

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

@@ -52,7 +52,10 @@ import {
   incrementInvalidationCounter,
   recordPerfSample,
 } from "./editor-surface/perf-probe.ts";
-import { useVisibleBlockRange } from "./page-stack/use-visible-block-range.ts";
+import {
+  useVisibleBlockRange,
+  useVisiblePageIndexRange,
+} from "./page-stack/use-visible-block-range.ts";
 import { sliceBlocksForPage } from "./editor-surface/page-slice-util.ts";
 import { TwPageBlockView } from "./editor-surface/tw-page-block-view.tsx";
 import { computeLineMarkersIfEnabled } from "./page-chrome-model.ts";
@@ -982,6 +985,17 @@ export function TwReviewWorkspace(inputProps: TwReviewWorkspaceProps) {
     totalBlockCount: snapshot.surface?.blocks.length ?? 0,
   });
 
+  // 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,
+  });
+
   // Push the visible range into the layout facet (which delegates to the
   // runtime's viewport-culling machinery).  Depend on `[start, end]` values
   // (not the range object) so identity-preserving updates are a no-op.
@@ -1649,6 +1663,7 @@ export function TwReviewWorkspace(inputProps: TwReviewWorkspaceProps) {
                             activeStory={snapshot.activeStory}
                             onOpenStory={props.onOpenStory}
                             pmSurfaceElement={pmSurfaceElement}
+                            visiblePageIndexRange={visiblePageIndexRange}
                           />
                         ) : null}
                       </div>