@beyondwork/docx-react-component 1.0.48 → 1.0.49

package/src/ui/headless/selection-helpers.ts

@@ -1,31 +1,22 @@
 import type { SelectionSnapshot } from "../../api/public-types";
+import {
+  createPublicNodeAnchor,
+  createPublicRangeAnchor,
+} from "../../core/selection/anchor-conversion.ts";
 
 /**
  * Headless-UI-side `createSelectionSnapshot` that produces the **public**
- * `EditorAnchorProjection` shape (top-level `from`/`to`). The runtime-facing
- * twin at `src/core/state/editor-state.ts` produces the internal
- * `RangeAnchor` shape (`range: { from, to }`). The two are *not*
- * interchangeable — they serve different type contracts. See the
- * `EditorAnchorProjection` definitions in `src/api/public-types.ts` vs
- * `src/core/selection/mapping.ts`. Do not merge without first unifying
- * those two definitions.
+ * `EditorAnchorProjection` shape via the canonical
+ * `createPublicRangeAnchor` constructor. The runtime-facing twin at
+ * `src/core/state/editor-state.ts` produces the internal `RangeAnchor`
+ * shape (`range: { from, to }`) — the two are not interchangeable.
  */
 export function createSelectionSnapshot(anchor: number, head = anchor): SelectionSnapshot {
-  const from = Math.min(anchor, head);
-  const to = Math.max(anchor, head);
   return {
     anchor,
     head,
     isCollapsed: anchor === head,
-    activeRange: {
-      kind: "range",
-      from,
-      to,
-      assoc: {
-        start: -1,
-        end: 1,
-      },
-    },
+    activeRange: createPublicRangeAnchor(anchor, head),
   };
 }
 
@@ -34,11 +25,7 @@ export function createNodeSelectionSnapshot(at: number, assoc: -1 | 1 = 1): Sele
     anchor: at,
     head: at,
     isCollapsed: true,
-    activeRange: {
-      kind: "node",
-      at,
-      assoc,
-    },
+    activeRange: createPublicNodeAnchor(at, assoc),
   };
 }
 

package/src/ui/unsupported-previews-policy.ts

@@ -0,0 +1,23 @@
+/**
+ * I4 — Effective-visibility rule for preserve-only previews.
+ *
+ * Combines the harness-only opaque-token flag (from
+ * `__harnessDebugPorts`, read via `readHarnessDebugPortsFlag(..., "unsupportedObjectPreviews")`)
+ * with the public sibling `unsupportedPreviewsPolicy` prop (default
+ * `"never"`). The harness token remains unreachable from consumer
+ * apps (see `test/ui/unsupported-previews-invariant.test.ts`).
+ */
+export interface EffectiveShowUnsupportedPreviewsInput {
+  harnessShowUnsupportedPreviews: boolean;
+  unsupportedPreviewsPolicy: "never" | "review-only" | "always";
+  reviewMode: "editing" | "review";
+}
+
+export function computeEffectiveShowUnsupportedPreviews(
+  input: EffectiveShowUnsupportedPreviewsInput,
+): boolean {
+  if (input.harnessShowUnsupportedPreviews === true) return true;
+  if (input.unsupportedPreviewsPolicy === "always") return true;
+  if (input.unsupportedPreviewsPolicy === "review-only" && input.reviewMode === "review") return true;
+  return false;
+}

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

@@ -152,6 +152,14 @@ export interface TwChromeOverlayProps {
    * handle leaves focus-restore as a no-op — DOM reparent still runs.
    */
   pmView?: PmPortalView | null;
+  /**
+   * L7 Phase 2.8 — viewport cull for `TwPageStackChromeLayer`. Sequential
+   * page-index range (plus overscan) that should render full chrome
+   * bands; pages outside the range render empty frame wrappers only.
+   * When omitted, every page's chrome mounts (pre-Phase-2.8 behavior).
+   * See `useVisiblePageIndexRange` in `src/ui-tailwind/page-stack/use-visible-block-range.ts`.
+   */
+  visiblePageIndexRange?: { start: number; end: number } | null;
 }
 
 /**
@@ -188,6 +196,7 @@ export const TwChromeOverlay: React.FC<TwChromeOverlayProps> = ({
   onOpenStory,
   pmSurfaceElement,
   pmView,
+  visiblePageIndexRange,
 }) => {
   return (
     <div
@@ -211,6 +220,7 @@ export const TwChromeOverlay: React.FC<TwChromeOverlayProps> = ({
           onOpenStory={onOpenStory}
           pmSurfaceElement={pmSurfaceElement}
           pmView={pmView}
+          visiblePageIndexRange={visiblePageIndexRange ?? null}
         />
       ) : null}
       <TwScopeRailLayer

package/src/ui-tailwind/editor-surface/perf-probe.ts

@@ -5,6 +5,7 @@ export type PerfProbeKind =
   | "typing.divergence"
   | "selection"
   | "runtime.create"
+  | "loadSession.laycacheProbe"
   | "snapshot.surface"
   | "snapshot.compatibility"
   | "snapshot.navigation"

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>