@beyondwork/docx-react-component 1.0.43 → 1.0.45

package/src/ui-tailwind/editor-surface/pm-page-break-decorations.ts

@@ -30,7 +30,12 @@ import { resolvePageFieldDisplayText } from "../../runtime/layout/resolve-page-f
 export const PAGE_CHROME_DEFAULTS = {
   headerBandPx: 32,
   footerBandPx: 32,
-  interGapPx: 24,
+  // L8 polish (2026-04-19): bumped from 24 → 48 so the workspace canvas
+  // between papers reads as a real break between discrete pages, not a
+  // seam inside one long paper.  Phase D's discrete paper cards will
+  // re-tune once overlay-owned gaps ship; until then the widget spacer
+  // carries the full gap height.
+  interGapPx: 48,
 } as const;
 
 export function totalPageBreakGapPx(
@@ -73,6 +78,15 @@ export interface PageBreakDecorationInput {
   headerPreviewByPageId?: ReadonlyMap<string, string>;
   /** Same shape for footers. */
   footerPreviewByPageId?: ReadonlyMap<string, string>;
+  /**
+   * L7 Phase 2 Task 2.2.4a — optional per-page block-index range so the
+   * viewport-tracking hook can translate page visibility into block indices
+   * without re-walking the surface blocks.  Keyed by pageIndex (0-based).
+   * When omitted, the chrome widgets are emitted without block-index
+   * attributes and the hook falls back to its ESTIMATED_BLOCKS_PER_PAGE
+   * heuristic.
+   */
+  blockIndexRangeByPageIndex?: ReadonlyMap<number, { first: number; last: number }>;
 }
 
 export function buildPageBreakDecorations(
@@ -88,6 +102,7 @@ export function buildPageBreakDecorations(
   const interGapPx = input.interGapPx ?? PAGE_CHROME_DEFAULTS.interGapPx;
 
   const decorations: Decoration[] = [];
+
   for (let i = 1; i < graph.pages.length; i += 1) {
     const prev = graph.pages[i - 1]!;
     const next = graph.pages[i]!;
@@ -106,6 +121,8 @@ export function buildPageBreakDecorations(
     const nextHeaderPreview =
       input.headerPreviewByPageId?.get(next.pageId) ?? "";
 
+    const nextBlockRange = input.blockIndexRangeByPageIndex?.get(next.pageIndex);
+
     decorations.push(
       Decoration.widget(
         pmOffset,
@@ -125,6 +142,8 @@ export function buildPageBreakDecorations(
             hasNextHeaderStory: Boolean(next.stories.header),
             prevFooterPreview,
             nextHeaderPreview,
+            nextPageFirstBlockIndex: nextBlockRange?.first ?? -1,
+            nextPageLastBlockIndex: nextBlockRange?.last ?? -1,
           }),
         {
           side: -1,
@@ -176,6 +195,16 @@ interface ChromeWidgetInput {
   hasNextHeaderStory: boolean;
   prevFooterPreview: string;
   nextHeaderPreview: string;
+  /**
+   * L7 Phase 2 Task 2.2.4a — inclusive first block index of the next page.
+   * -1 when block-index info was not supplied to the decoration builder.
+   */
+  nextPageFirstBlockIndex: number;
+  /**
+   * L7 Phase 2 Task 2.2.4a — inclusive last block index of the next page.
+   * -1 when block-index info was not supplied to the decoration builder.
+   */
+  nextPageLastBlockIndex: number;
 }
 
 // P14.c — cache the widget DOM by input identity.  PM rebuilds the
@@ -205,6 +234,8 @@ function widgetCacheKey(input: ChromeWidgetInput): string {
     input.hasNextHeaderStory ? "1" : "0",
     input.prevFooterPreview,
     input.nextHeaderPreview,
+    input.nextPageFirstBlockIndex,
+    input.nextPageLastBlockIndex,
   ].join("\x1f");
 }
 
@@ -238,14 +269,27 @@ function buildChromeWidgetDomUncached(input: ChromeWidgetInput): HTMLElement {
   root.setAttribute("data-posture", input.posture);
   root.setAttribute("data-prev-page-id", input.prevPageId);
   root.setAttribute("data-next-page-id", input.nextPageId);
-  root.setAttribute("data-prev-page-index", String(input.prevPageIndex));
-  root.setAttribute("data-next-page-index", String(input.nextPageIndex));
+  // NOTE: data-prev-page-index and data-next-page-index were removed — they had
+  // no reader after data-page-frame was added (Task 2.2.4a).  The page-id attrs
+  // above are still consumed by the chrome overlay (see line ~265 in this file).
   // P3.a: expose page-frame boundary markers so the page stack and tests
   // can enumerate pages without re-walking the render graph.  Each widget
   // ends page N (`prev`) and starts page N+1 (`next`); the outer workspace
   // frame still accounts for the boundaries at both ends of the document.
   root.setAttribute("data-page-frame-end", input.prevPageId);
   root.setAttribute("data-page-frame-start", input.nextPageId);
+  // L7 Phase 2 Task 2.2.4a — per-page markers for the viewport-tracking hook
+  // (`useVisibleBlockRange`).  Each boundary widget identifies the page that
+  // STARTS at this boundary (i.e. `nextPageIndex`).  The hook's
+  // IntersectionObserver picks these up via `[data-page-frame]` to compute the
+  // visible block range.  Block-index attributes are set only when the caller
+  // supplied a `blockIndexRangeByPageIndex` map (value ≥ 0); otherwise they
+  // are omitted so the hook's fallback estimate is used cleanly.
+  root.setAttribute("data-page-frame", String(input.nextPageIndex));
+  if (input.nextPageFirstBlockIndex >= 0) {
+    root.setAttribute("data-page-first-block-index", String(input.nextPageFirstBlockIndex));
+    root.setAttribute("data-page-last-block-index", String(input.nextPageLastBlockIndex));
+  }
   root.contentEditable = "false";
   root.setAttribute("aria-hidden", "false");
   root.style.display = "block";
@@ -286,175 +330,42 @@ function buildChromeWidgetDomUncached(input: ChromeWidgetInput): HTMLElement {
     return root;
   }
 
-  // PAGE-MODE chrome: footer band of prev + visible gap + header band of next.
+  // L8 Phase B (2026-04-19): the page-posture widget is a **transparent
+  // spacer**.  Inline band / gap / band chrome is retired — the real H/F
+  // bands are painted by `TwPageStackChromeLayer` as per-page overlays
+  // (P8.11).  The spacer keeps the same total height as the retired stack
+  // so `TwPageStackOverlayLayer.measureWidgetsViaBoundingRect` continues to
+  // produce the same page-overlay rect math; L8 Phase D will take over
+  // painting the gap and reduce this to 0.
+  //
+  // L8 polish (2026-04-19): the spacer carries a subtle, borderless
+  // page-count label centered in the inter-page gap so the workspace
+  // canvas reads as "two papers with a page number between them" — no
+  // pill, no border, just small muted text.
   root.style.height = `${
     input.footerBandPx + input.interGapPx + input.headerBandPx
   }px`;
   root.style.position = "relative";
-
-  const footer = buildBand({
-    kind: "footer",
-    pageId: input.prevPageId,
-    pageIndex: input.prevPageIndex,
-    pageLabel: input.prevPageLabel,
-    bandPx: input.footerBandPx,
-    position: "top",
-    hasStory: input.hasPrevFooterStory,
-    previewText: input.prevFooterPreview,
-  });
-  root.appendChild(footer);
-
-  // P3.a: the inter-page gap is now a visible canvas strip that reads as
-  // "the space between two papers", not a subtle gradient inside one white
-  // page.  The strip paints in the workspace canvas color (the same color
-  // the page frames float on in page mode), with subtle drop/rise shadows
-  // on either edge so the preceding footer reads as "bottom of page N's
-  // paper" and the following header reads as "top of page N+1's paper".
-  //
-  // The visual goal: bringing the user closer to a Word-native perception
-  // of distinct pages without requiring the PM editable tree to be split
-  // into per-page subtrees (that lands in P3.b).
-  const separator = document.createElement("div");
-  separator.className = "wre-page-chrome-separator";
-  separator.setAttribute("data-kind", "page-chrome-separator");
-  separator.style.position = "absolute";
-  separator.style.left = "0";
-  separator.style.right = "0";
-  separator.style.top = `${input.footerBandPx}px`;
-  separator.style.height = `${input.interGapPx}px`;
-  // Canvas color (same as the scroll root's bg-surface) so the strip reads
-  // as "gap between two papers".  Page mode and canvas mode both use the
-  // same token so the UX remains consistent at any chrome preset.
-  separator.style.backgroundColor = "var(--color-surface, #f1f5f9)";
-  // Inner shadows on top/bottom: the previous footer's bottom edge gains
-  // a subtle paper-edge shadow, and the next header's top edge likewise.
-  // Inset shadows let us avoid touching the footer / header DOM while
-  // keeping the shadows flush with the band borders.
-  separator.style.boxShadow = [
-    // Top edge — simulates the bottom shadow of page N's paper.
-    "inset 0 1px 0 rgba(15, 23, 42, 0.06)",
-    "inset 0 2px 3px -2px rgba(15, 23, 42, 0.12)",
-    // Bottom edge — simulates the top shadow of page N+1's paper.
-    "inset 0 -1px 0 rgba(15, 23, 42, 0.06)",
-    "inset 0 -2px 3px -2px rgba(15, 23, 42, 0.12)",
-  ].join(", ");
-  root.appendChild(separator);
-
-  const header = buildBand({
-    kind: "header",
-    pageId: input.nextPageId,
-    pageIndex: input.nextPageIndex,
-    pageLabel: input.nextPageLabel,
-    bandPx: input.headerBandPx,
-    position: "bottom",
-    topOffsetPx: input.footerBandPx + input.interGapPx,
-    hasStory: input.hasNextHeaderStory,
-    previewText: input.nextHeaderPreview,
-  });
-  root.appendChild(header);
-
-  return root;
-}
-
-function buildBand(input: {
-  kind: "header" | "footer";
-  pageId: string;
-  pageIndex: number;
-  pageLabel: string;
-  bandPx: number;
-  position: "top" | "bottom";
-  topOffsetPx?: number;
-  hasStory: boolean;
-  previewText: string;
-}): HTMLElement {
-  const band = document.createElement("div");
-  band.className = `wre-page-chrome-band wre-page-chrome-band-${input.kind}`;
-  band.setAttribute("data-band-kind", input.kind);
-  band.setAttribute("data-page-id", input.pageId);
-  band.setAttribute("data-page-index", String(input.pageIndex));
-  band.style.position = "absolute";
-  band.style.left = "0";
-  band.style.right = "0";
-  band.style.top = `${input.topOffsetPx ?? 0}px`;
-  band.style.height = `${input.bandPx}px`;
-  band.style.display = "flex";
-  band.style.alignItems = "center";
-  band.style.justifyContent = "space-between";
-  band.style.padding = "0 16px";
-  band.style.fontSize = "10px";
-  band.style.letterSpacing = "0.12em";
-  band.style.textTransform = "uppercase";
-  band.style.color = "var(--color-text-tertiary, #6b7280)";
-  band.style.backgroundColor =
-    "var(--color-surface-subtle, rgba(0,0,0,0.02))";
-  band.style.borderTop =
-    input.kind === "header"
-      ? "1px solid var(--color-border, rgba(0,0,0,0.08))"
-      : "none";
-  band.style.borderBottom =
-    input.kind === "footer"
-      ? "1px solid var(--color-border, rgba(0,0,0,0.08))"
-      : "none";
-  // Bands are interactive: double-click fires a custom event the shell
-  // forwards to `runtime.openStory()`.
-  band.style.pointerEvents = "auto";
-  band.style.cursor = input.hasStory ? "pointer" : "default";
-  band.title = input.hasStory
-    ? `Double-click to edit ${input.kind}`
-    : `No ${input.kind} defined for this page`;
+  root.style.pointerEvents = "none";
+  root.setAttribute("aria-hidden", "true");
 
   const label = document.createElement("span");
-  label.className = "wre-page-chrome-band-label";
-  if (input.previewText && input.previewText.trim().length > 0) {
-    // Show the live content (with PAGE/NUMPAGES resolved) rather than the
-    // static "Header" / "Footer" placeholder.  Band is compact so truncate
-    // at ~80 chars visually via CSS overflow; keep raw in textContent.
-    label.textContent = input.previewText;
-    label.style.textTransform = "none";
-    label.style.letterSpacing = "0";
-    label.style.fontSize = "11px";
-    label.style.color = "var(--color-text-secondary, #374151)";
-    label.style.overflow = "hidden";
-    label.style.textOverflow = "ellipsis";
-    label.style.whiteSpace = "nowrap";
-    label.style.maxWidth = "70%";
-  } else {
-    label.textContent = input.kind === "header" ? "Header" : "Footer";
-  }
-  band.appendChild(label);
-
-  const pageLabel = document.createElement("span");
-  pageLabel.className = "wre-page-chrome-band-page";
-  pageLabel.textContent = input.pageLabel;
-  band.appendChild(pageLabel);
+  label.className = "wre-page-chrome-gap-label";
+  label.setAttribute("data-kind", "page-gap-label");
+  label.textContent = input.nextPageLabel;
+  label.style.position = "absolute";
+  label.style.left = "50%";
+  label.style.top = "50%";
+  label.style.transform = "translate(-50%, -50%)";
+  label.style.fontSize = "10px";
+  label.style.letterSpacing = "0.12em";
+  label.style.textTransform = "uppercase";
+  label.style.color = "var(--color-tertiary, #6b7280)";
+  // Intentionally no background, no border, no padding — the label floats
+  // transparently in the workspace-canvas gap.
+  root.appendChild(label);
 
-  if (input.hasStory) {
-    band.addEventListener("dblclick", (event) => {
-      event.stopPropagation();
-      event.preventDefault();
-      const eventName =
-        input.kind === "header"
-          ? "wre-open-header-story-for-page"
-          : "wre-open-footer-story-for-page";
-      // Use the band's owning document's `CustomEvent` constructor so the
-      // event passes through jsdom's instance-of check.  In a real browser
-      // `band.ownerDocument.defaultView.CustomEvent` is the same as the
-      // global `CustomEvent`; in jsdom the two differ and the global one
-      // fails `dispatchEvent`'s internal Event-type convert step.
-      const view = band.ownerDocument?.defaultView as
-        | (Window & typeof globalThis)
-        | null;
-      const Ctor = view?.CustomEvent ?? CustomEvent;
-      band.dispatchEvent(
-        new Ctor(eventName, {
-          bubbles: true,
-          detail: { pageIndex: input.pageIndex, pageId: input.pageId },
-        }),
-      );
-    });
-  }
-
-  return band;
+  return root;
 }
 
 /**

package/src/ui-tailwind/editor-surface/pm-schema.ts

@@ -160,9 +160,26 @@ export const editorSchema = new Schema({
         bidi: { default: null },
         pageBreakBefore: { default: null },
         hiddenTextOnly: { default: null },
+        placeholderCulled: { default: null },
+        blockId: { default: null },
       },
       parseDOM: [{ tag: "p" }],
       toDOM(node) {
+        // Viewport-culled placeholder paragraph — cheap size-preserving leaf.
+        if (node.attrs.placeholderCulled) {
+          return [
+            "div",
+            {
+              "data-node-type": "paragraph-placeholder",
+              "data-placeholder-culled": "true",
+              "data-placeholder-size": String(node.nodeSize),
+              "data-placeholder-block-id": node.attrs.blockId ?? "",
+              style: "min-height: 20px; contain: strict;",
+              "aria-hidden": "true",
+            },
+            0,
+          ];
+        }
         const classes: string[] = ["leading-relaxed"];
         const styleId = node.attrs.styleId as string | null;
         const outlineLevel = node.attrs.outlineLevel as number | null;
@@ -893,6 +910,7 @@ export const editorSchema = new Schema({
         label: { default: "Locked" },
         detail: { default: "" },
         presentation: { default: "callout" },
+        placeholderSize: { default: null },
       },
       toDOM(node) {
         const fragmentId = node.attrs.fragmentId as string;

package/src/ui-tailwind/editor-surface/pm-state-from-snapshot.ts

@@ -700,6 +700,29 @@ function buildOpaqueBlock(
   block: Extract<SurfaceBlockSnapshot, { kind: "opaque_block" }>,
   showUnsupportedObjectPreviews: boolean,
 ): PMNode {
+  // Viewport-culled placeholder: emit a single paragraph with ZWSP text so
+  // PM position math matches the original block span.
+  // See docs/plans/lane-2-render-performance.md Task 2.2.3.
+  const placeholderSize = block.placeholderSize ?? null;
+  if (placeholderSize !== null) {
+    const targetSize = placeholderSize as number;
+    if (targetSize <= 2) {
+      // Edge case: bare empty paragraph claims exactly 2 positions.
+      return editorSchema.nodes.paragraph.create(
+        { blockId: block.blockId, placeholderCulled: true },
+        Fragment.empty,
+      );
+    }
+    // General case: one paragraph with (targetSize - 2) ZWSP chars so the
+    // total PM positions = 1 (open) + (targetSize - 2) (text) + 1 (close) = targetSize.
+    const filler = "\u200b".repeat(targetSize - 2);
+    return editorSchema.nodes.paragraph.create(
+      { blockId: block.blockId, placeholderCulled: true },
+      editorSchema.text(filler),
+    );
+  }
+
+  // Real (non-placeholder) opaque_block: existing behaviour unchanged.
   return editorSchema.nodes.opaque_block.create({
     fragmentId: block.fragmentId,
     warningId: block.warningId,

package/src/ui-tailwind/editor-surface/surface-build-keys.ts

@@ -23,6 +23,7 @@ export function createSurfaceDocumentBuildKey(input: {
   mediaPreviewKey: string;
   showUnsupportedObjectPreviews?: boolean;
 }): string {
+  const vp = input.surface?.viewportBlockRange ?? null;
   return JSON.stringify({
     surfaceIdentity:
       input.surface === undefined || input.surface === null
@@ -31,6 +32,7 @@ export function createSurfaceDocumentBuildKey(input: {
     activeStory: input.activeStory,
     mediaPreviewKey: input.mediaPreviewKey,
     showUnsupportedObjectPreviews: input.showUnsupportedObjectPreviews ?? false,
+    viewport: vp ? `${vp.start}:${vp.end}` : "full",
   });
 }
 

package/src/ui-tailwind/editor-surface/tw-prosemirror-surface.tsx

@@ -98,6 +98,7 @@ function buildPageBreakDecorationsFromProps(
     footerBandPx?: number;
     interGapPx?: number;
   } = {},
+  surfaceBlocks?: readonly import("../../api/public-types.ts").SurfaceBlockSnapshot[],
 ): ReturnType<typeof buildPageBreakDecorations> {
   if (!facet || !isMainStory) return [];
   if (typeof facet.getRenderFrame !== "function") return [];
@@ -133,6 +134,41 @@ function buildPageBreakDecorationsFromProps(
         })
       : undefined;
 
+  // L7 Phase 2 Task 2.2.4a — compute per-page block-index ranges from the
+  // render frame's page offsets + the surface blocks list.  Each block has a
+  // `from`/`to` offset; we find the first and last block whose offset range
+  // falls within each page's [startOffset, nextPage.startOffset) window.
+  // This map is passed into `buildPageBreakDecorations` so the chrome widgets
+  // carry `data-page-first-block-index` / `data-page-last-block-index`
+  // attributes needed by `useVisibleBlockRange`.
+  let blockIndexRangeByPageIndex: Map<number, { first: number; last: number }> | undefined;
+  if (surfaceBlocks && surfaceBlocks.length > 0 && frame.pages.length > 0) {
+    blockIndexRangeByPageIndex = new Map();
+    for (let pi = 0; pi < frame.pages.length; pi++) {
+      const page = frame.pages[pi]!;
+      if (page.page.isBlankFiller) continue;
+      const pageStart = page.page.startOffset;
+      const pageEnd =
+        pi + 1 < frame.pages.length
+          ? frame.pages[pi + 1]!.page.startOffset
+          : Infinity;
+      let first = -1;
+      let last = -1;
+      for (let bi = 0; bi < surfaceBlocks.length; bi++) {
+        const block = surfaceBlocks[bi]!;
+        const blockFrom = block.from;  // from is required on all SurfaceBlockSnapshot variants
+        // Block belongs to this page if its start falls within the page's offset window.
+        if (blockFrom >= pageStart && blockFrom < pageEnd) {
+          if (first === -1) first = bi;
+          last = bi;
+        }
+      }
+      if (first !== -1) {
+        blockIndexRangeByPageIndex.set(page.page.pageIndex, { first, last });
+      }
+    }
+  }
+
   return buildPageBreakDecorations({
     graph: fakeGraph as never,
     posture,
@@ -142,6 +178,7 @@ function buildPageBreakDecorationsFromProps(
     runtimeToPmOffset: (offset) => positionMap.runtimeToPm(offset),
     headerPreviewByPageId: previews?.headerPreviewByPageId,
     footerPreviewByPageId: previews?.footerPreviewByPageId,
+    blockIndexRangeByPageIndex,
   });
 }
 
@@ -512,6 +549,7 @@ export const TwProseMirrorSurface = forwardRef<
           footerBandPx: props.pageChromeFooterBandPx,
           interGapPx: props.pageChromeInterGapPx,
         },
+        snapshot.surface?.blocks,
       );
       const decorations = pageBreakDecos.length > 0
         ? DecorationSet.create(view.state.doc, [

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

@@ -0,0 +1,157 @@
+import * as React from "react";
+
+/**
+ * Fallback estimate of blocks per page. Used ONLY when no page markers
+ * are available (pre-observer window or a degenerate empty-pageMarkers
+ * input). Once the observer fires, actual per-page spans are read from
+ * `data-page-first-block-index` / `data-page-last-block-index` markers.
+ * Short (title-only) or very long (large-table) pages deviate from this,
+ * but the fallback is transient and only affects the initial render.
+ */
+const ESTIMATED_BLOCKS_PER_PAGE_FALLBACK = 50;
+
+/**
+ * Block-range hook — returns the range of surface block indices that should
+ * be rendered in PM as "real" (non-placeholder) blocks.
+ *
+ * Sources of truth:
+ * 1. IntersectionObserver on `[data-page-frame]` markers in the PM DOM.
+ * 2. Selection head block-index — always included (selection-guard).
+ * 3. Overscan — ±N pages around the visible set to avoid jank when scrolling.
+ *
+ * If the selection is far off-screen, the returned range spans both the
+ * visible window AND the selection's page (with the gap between filled in).
+ * Gap-filling is a deliberate correctness choice: position preservation does
+ * NOT require continuous viewport coverage, but continuous coverage simplifies
+ * the snapshot-projection step downstream.
+ */
+export interface VisibleBlockRangeInput {
+  pageMarkers: readonly HTMLElement[];
+  overscanPages: number;
+  selectionBlockIndex: number | null;
+  totalBlockCount: number;
+}
+
+export interface BlockRange {
+  start: number; // inclusive
+  end: number; // exclusive
+}
+
+function readBlockIndex(el: HTMLElement, attr: string): number | null {
+  const v = el.getAttribute(attr);
+  if (v === null) return null;
+  const n = Number(v);
+  return Number.isFinite(n) ? n : null;
+}
+
+export function useVisibleBlockRange(input: VisibleBlockRangeInput): BlockRange {
+  const { pageMarkers, overscanPages, selectionBlockIndex, totalBlockCount } = input;
+  const [visiblePages, setVisiblePages] = React.useState<Set<number>>(() => new Set());
+
+  React.useEffect(() => {
+    // Reset: marker set changed (e.g. document reload). Stale page indices
+    // from the previous observer would look up against new markers and miss,
+    // falling through to the `Infinity` fallback and producing a transient
+    // over-wide range. Clear them now so the new observer's first callback
+    // is the single source of truth.
+    setVisiblePages(new Set());
+
+    if (pageMarkers.length === 0) return;
+    const view = pageMarkers[0].ownerDocument?.defaultView;
+    if (!view?.IntersectionObserver) return;
+
+    const observer = new view.IntersectionObserver(
+      (entries) => {
+        setVisiblePages((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 (totalBlockCount <= 0) return { start: 0, end: 0 };
+    if (visiblePages.size === 0 && selectionBlockIndex === null) {
+      // No visibility signal yet — return initial-load window (first 2 × overscanPages worth).
+      const initialEnd = Math.min(totalBlockCount, (overscanPages * 2 + 1) * ESTIMATED_BLOCKS_PER_PAGE_FALLBACK);
+      return { start: 0, end: initialEnd };
+    }
+
+    // Expand visiblePages by ±overscanPages.
+    const expanded = new Set<number>();
+    for (const p of visiblePages) {
+      for (let d = -overscanPages; d <= overscanPages; d++) expanded.add(p + d);
+    }
+
+    // Translate page indices → block indices using marker attrs.
+    let minBlock = Infinity;
+    let maxBlock = -Infinity;
+    for (const marker of pageMarkers) {
+      const idx = readBlockIndex(marker, "data-page-frame");
+      if (idx === null || !expanded.has(idx)) continue;
+      const first = readBlockIndex(marker, "data-page-first-block-index");
+      const last = readBlockIndex(marker, "data-page-last-block-index");
+      if (first !== null) minBlock = Math.min(minBlock, first);
+      if (last !== null) maxBlock = Math.max(maxBlock, last + 1);
+    }
+    if (minBlock === Infinity) {
+      minBlock = 0;
+      maxBlock = Math.min(totalBlockCount, (overscanPages * 2 + 1) * ESTIMATED_BLOCKS_PER_PAGE_FALLBACK);
+    }
+
+    // Selection-guard: if selection is outside [minBlock, maxBlock), extend to cover
+    // the entire page that contains the selection.
+    if (selectionBlockIndex !== null) {
+      if (selectionBlockIndex < minBlock) {
+        // Find the page that contains selectionBlockIndex and extend to its start.
+        for (const marker of pageMarkers) {
+          const first = readBlockIndex(marker, "data-page-first-block-index");
+          const last = readBlockIndex(marker, "data-page-last-block-index");
+          if (first !== null && last !== null && selectionBlockIndex >= first && selectionBlockIndex <= last) {
+            if (first < minBlock) minBlock = first;
+            break;
+          }
+        }
+        // Fallback: just include the block itself.
+        if (selectionBlockIndex < minBlock) minBlock = selectionBlockIndex;
+      }
+      if (selectionBlockIndex >= maxBlock) {
+        // Find the page that contains selectionBlockIndex and extend to its end.
+        for (const marker of pageMarkers) {
+          const first = readBlockIndex(marker, "data-page-first-block-index");
+          const last = readBlockIndex(marker, "data-page-last-block-index");
+          if (first !== null && last !== null && selectionBlockIndex >= first && selectionBlockIndex <= last) {
+            if (last + 1 > maxBlock) maxBlock = last + 1;
+            break;
+          }
+        }
+        // Fallback: just include the block itself.
+        if (selectionBlockIndex >= maxBlock) maxBlock = selectionBlockIndex + 1;
+      }
+    }
+
+    // Clamp to doc bounds.
+    return {
+      start: Math.max(0, minBlock),
+      end: Math.min(totalBlockCount, maxBlock),
+    };
+  }, [visiblePages, selectionBlockIndex, pageMarkers, overscanPages, totalBlockCount]);
+}