@beyondwork/docx-react-component 1.0.73 → 1.0.75

package/src/runtime/document-runtime.ts

@@ -171,7 +171,12 @@ import {
   seedMarkerBackedScopeIds,
   type OverlayStore,
 } from "./workflow/overlay-store.ts";
-import type { RuntimeOperationPlan, ScopeBundle } from "./scopes/semantic-scope-types.ts";
+import type {
+  RuntimeOperationPlan,
+  ScopeBundle,
+  SemanticScope,
+  SemanticScopeKind,
+} from "./scopes/semantic-scope-types.ts";
 import { createScopeCompilerService } from "./scopes/compiler-service.ts";
 import {
   createWorkflowCoordinator,
@@ -527,6 +532,42 @@ export interface DocumentRuntime {
    * handle (e.g. `getScope`).
    */
   compileScopeBundleById(scopeId: string, nowUtc: string): ScopeBundle | null;
+  /**
+   * KI-008 (2026-04-24) — batch enumeration primitive for L10
+   * `ui.scope.list(filter?)`. Returns the compiled `SemanticScope[]`
+   * through the existing `createScopeCompilerService` facade, applies
+   * the optional kind filter + limit over the result, and hands back a
+   * fresh array (callers may sort / splice freely without leaking
+   * into internal compiler state). L10 `src/api/v3/ui/**` can't import
+   * `src/runtime/scopes/**` per its purity guard; this handle method
+   * is the narrow seam through which `ui.scope.list` reaches
+   * enumeration. `ai.listScopes` delegates through the same primitive
+   * so both surfaces project the same identity set.
+   */
+  compileScopeList(filter?: {
+    readonly kind?: SemanticScopeKind;
+    readonly limit?: number;
+  }): readonly SemanticScope[];
+  /**
+   * KI-008 close (2026-04-24) — scopeId-keyed scope-card projection
+   * for L10 `ui.scope.card(scopeId)`. Delegates to
+   * `runtime.workflow.getAllScopeCardModels()` + filters to the
+   * matching scope. Returns `null` when the id doesn't project a
+   * card (not on overlay / no matching segment).
+   */
+  compileScopeCardById(
+    scopeId: string,
+  ): import("../api/public-types.ts").ScopeCardModel | null;
+  /**
+   * KI-008 close (2026-04-24) — scope-rail snapshot for L10
+   * `ui.scope.rail(options?)`. Wraps `getRailSegments(pageIndex)`
+   * (narrowed) or `getAllRailSegments()` (span) into a
+   * `ScopeRailSnapshot` envelope so the UI surface has a stable
+   * shape regardless of page filtering.
+   */
+  compileScopeRailSnapshot(options?: {
+    readonly pageIndex?: number;
+  }): import("../api/public-types.ts").ScopeRailSnapshot;
   /**
    * Debug projector support — readonly view of scope ids the runtime
    * considers marker-backed (present in both `collectScopeLocations(doc)`
@@ -837,6 +878,20 @@ export interface DocumentRuntime {
    * Safe to call at any frequency; identical ranges are a no-op.
    */
   setVisibleBlockRange(range: { start: number; end: number }): void;
+  /**
+   * Multi-interval variant of `setVisibleBlockRange`. The surface projection
+   * treats a block as real if its index falls in ANY of the supplied
+   * intervals. Use this when the editor's visible window and the caret's
+   * page are disjoint on a long document — emit the viewport + the caret's
+   * page as two ranges instead of one merged range so the gap between them
+   * stays virtualized (placeholder-culled) instead of being realized.
+   *
+   * The array is stored by reference; callers are responsible for passing
+   * non-overlapping intervals sorted ascending by `start`. An empty array
+   * is equivalent to passing a single full-document range (legacy
+   * "all-real" behavior). Identical ranges are a no-op.
+   */
+  setVisibleBlockRanges(ranges: readonly { start: number; end: number }[]): void;
   /**
    * Triggers a surface-only refresh that applies the latest visible block range
    * without running the full commit pipeline. Used by scroll handlers.
@@ -959,6 +1014,49 @@ interface HistoryState {
  * stale `items[].anchor` never reaches a consumer. The direct
  * `runtime.getReviewWorkSnapshot()` API does not use this cache.
  */
+/**
+ * Normalize incoming viewport intervals: drop degenerate ranges (end <= start),
+ * sort by `start`, merge overlapping / touching intervals. Returns a frozen
+ * array so callers can't mutate the cached state.
+ *
+ * The sort + merge is important: `refreshSurfaceOnly`'s idempotency key is
+ * a string serialization, so `[{0,5},{100,105}]` and `[{100,105},{0,5}]`
+ * must compare equal; likewise `[{0,5},{4,10}]` and `[{0,10}]` represent
+ * identical realization sets and should key identically.
+ */
+function normalizeViewportRanges(
+  ranges: readonly { start: number; end: number }[],
+): readonly { start: number; end: number }[] {
+  const cleaned = ranges
+    .filter((r) => Number.isFinite(r.start) && Number.isFinite(r.end) && r.end > r.start)
+    .map((r) => ({ start: r.start, end: r.end }));
+  if (cleaned.length === 0) return Object.freeze([]);
+  cleaned.sort((a, b) => a.start - b.start);
+  const merged: { start: number; end: number }[] = [cleaned[0]!];
+  for (let i = 1; i < cleaned.length; i += 1) {
+    const next = cleaned[i]!;
+    const last = merged[merged.length - 1]!;
+    // Mutation is safe: `last` is a fresh object from the `.map` step above,
+    // not aliased with any caller-provided input. The `Object.freeze` at the
+    // return site only runs after the merge loop finishes.
+    if (next.start <= last.end) {
+      if (next.end > last.end) last.end = next.end;
+    } else {
+      merged.push(next);
+    }
+  }
+  return Object.freeze(merged.map((r) => Object.freeze(r)));
+}
+
+/** Stable serialization of normalized viewport ranges for fingerprinting. */
+function serializeViewportRanges(
+  ranges: readonly { start: number; end: number }[] | null,
+): string {
+  if (ranges === null) return "null";
+  if (ranges.length === 0) return "empty";
+  return ranges.map((r) => `${r.start}:${r.end}`).join("|");
+}
+
 function computeWorkflowMarkupStructuralHash(
   wfMarkup: WorkflowMarkupSnapshot,
 ): string {
@@ -1215,19 +1313,14 @@ export function createDocumentRuntime(
     // so the facet forwards to the runtime method. Forward-reference pattern matches
     // `renderKernelRef` — see that example. See spec-review notes on commit 0b03bfa7.
     setVisibleBlockRange: (range) => {
-      if (
-        viewportBlockRange &&
-        viewportBlockRange.start === range.start &&
-        viewportBlockRange.end === range.end
-      ) {
-        return;
-      }
-      viewportBlockRange = { start: range.start, end: range.end };
-      perfCounters.increment("runtime.viewport.updates");
+      applyViewportRanges([range]);
+    },
+    setVisibleBlockRanges: (ranges) => {
+      applyViewportRanges(ranges);
     },
     requestViewportRefresh: () => {
       perfCounters.increment("runtime.viewport.refreshes");
-      refreshSurfaceOnly();
+      maybeRefreshSurfaceForViewport();
     },
   });
   // D1 — wire the layout-guard warning emitter so `return []` guard sites
@@ -1255,13 +1348,44 @@ export function createDocumentRuntime(
     renderKernel: () => renderKernelRef,
     getCanonicalDocument: () => state.document,
   });
-  // L7 Phase 2 — viewport block range for surface culling.
-  let viewportBlockRange: { start: number; end: number } | null = null;
+  // L7 Phase 2 — viewport block range(s) for surface culling. Multi-interval
+  // canonical state: a block is real if its index falls in ANY interval.
+  // Stored as a frozen, sorted, non-overlapping list so `applyViewportRanges`
+  // can identity-compare for fast no-ops; `null` = "all blocks real" (legacy).
+  let viewportBlockRanges: readonly { start: number; end: number }[] | null = null;
+  /** Serialized fingerprint of the active ranges — used as the idempotency key for `refreshSurfaceOnly`. */
+  let viewportRangesKey: string = serializeViewportRanges(null);
+
+  function applyViewportRanges(
+    incoming: readonly { start: number; end: number }[] | null,
+  ): void {
+    // Normalize: empty array / null both mean "no culling".
+    const normalized =
+      incoming == null || incoming.length === 0
+        ? null
+        : normalizeViewportRanges(incoming);
+    const nextKey = serializeViewportRanges(normalized);
+    if (nextKey === viewportRangesKey) return;
+    viewportBlockRanges = normalized;
+    viewportRangesKey = nextKey;
+    perfCounters.increment("runtime.viewport.updates");
+  }
 
   let cachedSurface:
     | {
         revisionToken: string;
         activeStoryKey: string;
+        /**
+         * Serialized viewport ranges at build time. A surface snapshot is
+         * only reusable for a subsequent `getCachedSurface` call if the
+         * runtime's current `viewportRangesKey` matches — otherwise the
+         * cached snapshot realizes a different set of blocks as real vs
+         * placeholder-culled than the current runtime state demands.
+         * Pre-refactor/11b this was a (revisionToken, activeStoryKey) key
+         * only, which was silently stale-prone when callers applied new
+         * viewport ranges without also calling `requestViewportRefresh()`.
+         */
+        viewportRangesKey: string;
         snapshot: RuntimeRenderSnapshot["surface"];
       }
     | undefined;
@@ -1423,13 +1547,14 @@ export function createDocumentRuntime(
     if (
       cachedSurface &&
       cachedSurface.revisionToken === state.revisionToken &&
-      cachedSurface.activeStoryKey === activeStoryKey
+      cachedSurface.activeStoryKey === activeStoryKey &&
+      cachedSurface.viewportRangesKey === viewportRangesKey
     ) {
       return cachedSurface.snapshot;
     }
 
     const snapshot = createEditorSurfaceSnapshot(document, state.selection, nextActiveStory, {
-      viewportBlockRange,
+      viewportBlockRanges,
       ...(effectiveMarkupModeProvider
         ? { getEffectiveMarkupMode: effectiveMarkupModeProvider }
         : {}),
@@ -1439,8 +1564,13 @@ export function createDocumentRuntime(
     cachedSurface = {
       revisionToken: state.revisionToken,
       activeStoryKey,
+      viewportRangesKey,
       snapshot,
     };
+    // Keep the scroll-path fingerprint in lockstep so a subsequent
+    // `maybeRefreshSurfaceForViewport` sees the freshly-built snapshot
+    // and short-circuits instead of paying a redundant projection.
+    cachedSurfaceFingerprint = `${state.revisionToken}|${activeStoryKey}|${viewportRangesKey}|${String(state.selection.anchor)}:${String(state.selection.head)}`;
     return snapshot;
   }
 
@@ -2241,10 +2371,28 @@ export function createDocumentRuntime(
   }
 
   /**
-   * L7 Phase 2 — surface-only refresh triggered by viewport scroll.
-   * Rebuilds only the surface facet (with the current viewportBlockRange) and
-   * splices it into cachedRenderSnapshot. Does NOT rebuild layout, comments,
-   * trackedChanges, or compatibility. Does NOT increment "refresh.all".
+   * Fingerprint over the inputs that the viewport-refresh fast-path knows
+   * about. Used to short-circuit {@link maybeRefreshSurfaceForViewport}
+   * when nothing that affects the scroll-driven projection has changed
+   * since the last build. Scroll handlers fire effectively-identical
+   * requests on every tick (IO coalescing, overscan nudges that don't
+   * flip any page's visible state); without this gate every tick would
+   * rebuild the surface + notify listeners + force PM `view.updateState()`.
+   *
+   * NOT suitable for callers that invalidate external projection inputs
+   * (markup-mode provider, etc.) because those inputs are read at
+   * projection time and are not captured in the fingerprint. Those callers
+   * use {@link refreshSurfaceOnly} directly (unconditional rebuild).
+   */
+  let cachedSurfaceFingerprint: string | null = null;
+
+  /**
+   * L7 Phase 2 — surface-only refresh. Rebuilds the surface facet (with
+   * the current viewportBlockRanges) and splices it into
+   * cachedRenderSnapshot. Does NOT rebuild layout, comments, trackedChanges,
+   * or compatibility. Does NOT increment "refresh.all". Callers that
+   * know an input outside the fingerprint changed (markup-mode provider,
+   * etc.) use this directly.
    */
   function refreshSurfaceOnly(): void {
     const newSurface = createEditorSurfaceSnapshot(
@@ -2252,12 +2400,13 @@ export function createDocumentRuntime(
       state.selection,
       activeStory,
       {
-        viewportBlockRange,
+        viewportBlockRanges,
         ...(effectiveMarkupModeProvider
           ? { getEffectiveMarkupMode: effectiveMarkupModeProvider }
           : {}),
       },
     );
+    cachedSurfaceFingerprint = `${state.revisionToken}|${storyTargetKey(activeStory)}|${viewportRangesKey}|${String(state.selection.anchor)}:${String(state.selection.head)}`;
     // Refresh the cache with the just-built snapshot so a subsequent
     // refreshRenderSnapshot (same revisionToken + activeStoryKey) hits cache.
     // Without this repopulate, the next non-mutation refresh wastes a second
@@ -2265,6 +2414,7 @@ export function createDocumentRuntime(
     cachedSurface = {
       revisionToken: state.revisionToken,
       activeStoryKey: storyTargetKey(activeStory),
+      viewportRangesKey,
       snapshot: newSurface,
     };
     cachedRenderSnapshot = {
@@ -2277,8 +2427,33 @@ export function createDocumentRuntime(
     }
   }
 
+  /**
+   * Viewport-refresh fast path — short-circuits when the tracked
+   * fingerprint matches, otherwise delegates to {@link refreshSurfaceOnly}.
+   * Used by `requestViewportRefresh` so steady-state scroll doesn't pay
+   * a full projection + listener fan-out on every tick.
+   *
+   * Safe because every external input that can change the projection
+   * output without ticking revisionToken / selection / viewportRanges /
+   * activeStory is wired to call `refreshSurfaceOnly` directly (see
+   * `setEffectiveMarkupModeProvider`, `invalidateForMarkupModeChange`).
+   */
+  function maybeRefreshSurfaceForViewport(): void {
+    const fingerprint = `${state.revisionToken}|${storyTargetKey(activeStory)}|${viewportRangesKey}|${String(state.selection.anchor)}:${String(state.selection.head)}`;
+    if (cachedSurfaceFingerprint === fingerprint && cachedSurface) {
+      return;
+    }
+    refreshSurfaceOnly();
+  }
+
   function invalidateDerivedRuntimeCaches(): void {
     cachedSurface = undefined;
+    // Keep the scroll-path fingerprint in lockstep with `cachedSurface`.
+    // Otherwise a post-commit `requestViewportRefresh` would compute a new
+    // fingerprint, see it differs from the stale pre-commit value, and
+    // rebuild + broadcast even when the freshly-hydrated `cachedSurface`
+    // already matches — wasted projection + listener fan-out.
+    cachedSurfaceFingerprint = null;
     cachedCompatibility = undefined;
     cachedComments = undefined;
     cachedTrackedChanges = undefined;
@@ -3289,6 +3464,31 @@ export function createDocumentRuntime(
     compileScopeBundleById(scopeId, nowUtc) {
       return createScopeCompilerService(runtime).compileBundleById(scopeId, nowUtc);
     },
+    compileScopeList(filter) {
+      const all = createScopeCompilerService(runtime).compileAllScopes();
+      const byKind = filter?.kind
+        ? all.filter((s) => s.kind === filter.kind)
+        : all.slice();
+      if (typeof filter?.limit === "number") {
+        return byKind.slice(0, filter.limit);
+      }
+      return byKind;
+    },
+    compileScopeCardById(scopeId) {
+      const cards = workflowCoordinator.getAllScopeCardModels();
+      return cards.find((card) => card.scopeId === scopeId) ?? null;
+    },
+    compileScopeRailSnapshot(options) {
+      const pageIndex = options?.pageIndex;
+      const segments =
+        typeof pageIndex === "number"
+          ? workflowCoordinator.getRailSegments(pageIndex)
+          : workflowCoordinator.getAllRailSegments();
+      return {
+        segments: Object.freeze([...segments]),
+        ...(typeof pageIndex === "number" ? { pageIndex } : {}),
+      };
+    },
     getMarkerBackedScopeIds() {
       return workflowCoordinator.getMarkerBackedScopeIds();
     },
@@ -4219,19 +4419,14 @@ export function createDocumentRuntime(
       perfCounters.reset();
     },
     setVisibleBlockRange(range) {
-      if (
-        viewportBlockRange &&
-        viewportBlockRange.start === range.start &&
-        viewportBlockRange.end === range.end
-      ) {
-        return;
-      }
-      viewportBlockRange = { start: range.start, end: range.end };
-      perfCounters.increment("runtime.viewport.updates");
+      applyViewportRanges([range]);
+    },
+    setVisibleBlockRanges(ranges) {
+      applyViewportRanges(ranges);
     },
     requestViewportRefresh() {
       perfCounters.increment("runtime.viewport.refreshes");
-      refreshSurfaceOnly();
+      maybeRefreshSurfaceForViewport();
     },
   };
 
@@ -5668,8 +5863,8 @@ function semanticallyEqualCommentThreads(
   if (prevAnchor.kind !== nextAnchor.kind) return false;
   if (prevAnchor.kind === "range" && nextAnchor.kind === "range") {
     return (
-      prevAnchor.range.from === nextAnchor.range.from &&
-      prevAnchor.range.to === nextAnchor.range.to
+      prevAnchor.from === nextAnchor.from &&
+      prevAnchor.to === nextAnchor.to
     );
   }
   if (prevAnchor.kind === "node" && nextAnchor.kind === "node") {
@@ -6038,8 +6233,8 @@ function toAnchorBounds(anchor: InternalEditorAnchorProjection): { from: number;
   switch (anchor.kind) {
     case "range":
       return {
-        from: Math.min(anchor.range.from, anchor.range.to),
-        to: Math.max(anchor.range.from, anchor.range.to),
+        from: Math.min(anchor.from, anchor.to),
+        to: Math.max(anchor.from, anchor.to),
       };
     case "node":
       return {
@@ -7212,12 +7407,12 @@ function remapProtectionSnapshot(
           "preserve-only: permission range could not be remapped after runtime edits",
       };
     }
-    if (mapped.range.from !== range.start || mapped.range.to !== range.end) {
+    if (mapped.from !== range.start || mapped.to !== range.end) {
       changed = true;
       return {
         ...range,
-        start: mapped.range.from,
-        end: mapped.range.to,
+        start: mapped.from,
+        end: mapped.to,
       };
     }
     return range;
@@ -7366,7 +7561,7 @@ function resolveClearHighlightRange(
   }
   const active = selection.activeRange;
   if (active.kind !== "range") return null;
-  return { from: active.range.from, to: active.range.to };
+  return { from: active.from, to: active.to };
 }
 
 function expandRangeToHighlightExtent(

package/src/runtime/formatting/formatting-context.ts

@@ -891,7 +891,7 @@ function buildRevisionRangeIndex(
     const anchor = revision.anchor;
     let range: { from: number; to: number } | undefined;
     if (anchor.kind === "range") {
-      range = { from: anchor.range.from, to: anchor.range.to };
+      range = { from: anchor.from, to: anchor.to };
     } else if (anchor.kind === "node") {
       range = { from: anchor.at, to: anchor.at };
     } else {

package/src/runtime/layout/inert-layout-facet.ts

@@ -68,6 +68,7 @@ export function createInertLayoutFacet(): WordReviewEditorLayoutFacet {
     getDirtyFieldFamilies: () => [],
     getFieldDirtinessReport: () => emptyReport,
     setVisibleBlockRange: () => undefined,
+    setVisibleBlockRanges: () => undefined,
     requestViewportRefresh: () => undefined,
     subscribe: (_listener: (event: LayoutFacetEvent) => void) => () => undefined,
   };

package/src/runtime/layout/layout-engine-version.ts

@@ -947,8 +947,16 @@
  *   all emit/honor framePr end-to-end. Cache envelopes from v54
  *   invalidate because any future document with a real body framePr
  *   paginates differently.
+ *
+ *  56 — perf(11b,07) `8d07de1b` multi-range viewport realization.
+ *   `WordReviewEditorLayoutFacet` gained `setVisibleBlockRanges` for
+ *   multi-range viewport realization (paired with coord-07 §2.9
+ *   `runtime.viewport.subscribe`). The contract widened but the
+ *   underlying layout algorithm is unchanged — persisted envelopes
+ *   remain shape-compatible. Bump is defensive so any consumer that
+ *   keyed on the facet contract refreshes the cache.
  */
-export const LAYOUT_ENGINE_VERSION = 55 as const;
+export const LAYOUT_ENGINE_VERSION = 56 as const;
 
 /**
  * Serialization schema version for the LayCache payload (the cache envelope

package/src/runtime/layout/public-facet.ts

@@ -580,6 +580,18 @@ export interface WordReviewEditorLayoutFacet {
    * identical ranges are a no-op inside the runtime.
    */
   setVisibleBlockRange(range: { start: number; end: number }): void;
+  /**
+   * Multi-interval variant of `setVisibleBlockRange`. Delegates to
+   * `DocumentRuntime.setVisibleBlockRanges`. Use when the editor's
+   * visible viewport and the caret's page are disjoint — emitting the
+   * two ranges separately keeps the gap between them virtualized
+   * instead of being realized as real blocks, which was the dominant
+   * scroll-cost regression on long documents (see the perf wiki
+   * "Viewport realization").
+   */
+  setVisibleBlockRanges(
+    ranges: readonly { start: number; end: number }[],
+  ): void;
   /**
    * Triggers a surface-only refresh applying the latest visible block range.
    * Delegates to `DocumentRuntime.requestViewportRefresh`.
@@ -625,6 +637,9 @@ export interface CreateLayoutFacetInput {
    * (e.g. tests, inert facet, standalone use) both methods are no-ops.
    */
   setVisibleBlockRange?: (range: { start: number; end: number }) => void;
+  setVisibleBlockRanges?: (
+    ranges: readonly { start: number; end: number }[],
+  ) => void;
   requestViewportRefresh?: () => void;
 }
 
@@ -1236,6 +1251,18 @@ export function createLayoutFacet(
       input.setVisibleBlockRange?.(range);
     },
 
+    setVisibleBlockRanges(ranges) {
+      // Prefer the multi-range delegate when the wiring supplies it;
+      // otherwise fall back to the scalar delegate with the first range so
+      // callers that only wire the legacy path still receive something
+      // actionable (degrades to pre-multi-range behavior).
+      if (input.setVisibleBlockRanges) {
+        input.setVisibleBlockRanges(ranges);
+      } else if (input.setVisibleBlockRange && ranges.length > 0) {
+        input.setVisibleBlockRange(ranges[0]!);
+      }
+    },
+
     requestViewportRefresh() {
       input.requestViewportRefresh?.();
     },

package/src/runtime/scopes/evidence.ts

@@ -38,7 +38,7 @@ import type {
 function anchorRange(anchor: CanonicalAnchor): ScopePositionRange | null {
   switch (anchor.kind) {
     case "range":
-      return { from: anchor.range.from, to: anchor.range.to };
+      return { from: anchor.from, to: anchor.to };
     case "node":
       return { from: anchor.at, to: anchor.at };
     case "detached":

package/src/runtime/scopes/review-bundle.ts

@@ -57,7 +57,7 @@ function anchorToRange(
 ): ScopePositionRange | null {
   switch (anchor.kind) {
     case "range":
-      return { from: anchor.range.from, to: anchor.range.to };
+      return { from: anchor.from, to: anchor.to };
     case "node":
       return { from: anchor.at, to: anchor.at };
     case "detached":

package/src/runtime/scopes/scope-range.ts

@@ -39,7 +39,7 @@ import type {
 function anchorToRange(anchor: CanonicalAnchor): ScopePositionRange | null {
   switch (anchor.kind) {
     case "range":
-      return { from: anchor.range.from, to: anchor.range.to };
+      return { from: anchor.from, to: anchor.to };
     case "node":
       return { from: anchor.at, to: anchor.at };
     case "detached":

package/src/runtime/selection/post-edit-validator.ts

@@ -64,8 +64,7 @@ export function validateSelectionAgainstDocument(
         head: collapsed,
         isCollapsed: true,
         activeRange: {
-          kind: "range",
-          range: { from: collapsed, to: collapsed },
+          kind: "range", from: collapsed, to: collapsed,
           assoc: {
             start: selection.activeRange.assoc,
             end: selection.activeRange.assoc,
@@ -84,7 +83,8 @@ export function validateSelectionAgainstDocument(
     return selection;
   }
 
-  const range = { from: Math.min(anchor, head), to: Math.max(anchor, head) };
+  const from = Math.min(anchor, head);
+  const to = Math.max(anchor, head);
   const assoc =
     selection.activeRange.kind === "range"
       ? selection.activeRange.assoc
@@ -94,7 +94,7 @@ export function validateSelectionAgainstDocument(
     anchor,
     head,
     isCollapsed: anchor === head,
-    activeRange: { kind: "range", range, assoc },
+    activeRange: { kind: "range", from, to, assoc },
   };
 }
 

package/src/runtime/surface-projection.ts

@@ -95,6 +95,29 @@ interface ParagraphAccumulator {
 }
 
 export interface SurfaceProjectionOptions {
+  /**
+   * Block-index intervals to render as real (non-placeholder). Blocks whose
+   * index falls in ANY interval are built as real `SurfaceBlockSnapshot`s;
+   * all others become size-preserving `placeholder-culled` opaque blocks.
+   *
+   * The canonical shape is an array of non-overlapping intervals (typically
+   * one for the visible viewport + overscan, and — when the caret is scrolled
+   * off-screen — a second one covering the caret's page so the selection
+   * block stays real without realizing the document-scale gap between the
+   * two). Callers still supplying the legacy scalar `viewportBlockRange` get
+   * wrapped into a single-element array internally.
+   *
+   * **Invariant (caller responsibility):** intervals must be sorted ascending
+   * by `start` and non-overlapping. The projection function itself only
+   * checks membership — it does not sort or merge — so an unsorted input
+   * produces a correct `isInViewport` answer but the snapshot's
+   * `viewportBlockRanges` field carries the unnormalized shape to downstream
+   * consumers (e.g. the surface-build-key serializer). Runtime callers
+   * route through `DocumentRuntime.applyViewportRanges` which normalizes;
+   * if you call `createEditorSurfaceSnapshot` directly, normalize first.
+   */
+  viewportBlockRanges?: readonly { start: number; end: number }[] | null;
+  /** @deprecated use `viewportBlockRanges`. Kept for back-compat; wrapped into a 1-element array when supplied alone. */
   viewportBlockRange?: { start: number; end: number } | null;
   /**
    * Active markup mode. When set together with the document's
@@ -146,7 +169,13 @@ export function createEditorSurfaceSnapshot(
   activeStory: EditorStoryTarget = { kind: "main" },
   options: SurfaceProjectionOptions = {},
 ): EditorSurfaceSnapshot {
-  const viewportBlockRange = options.viewportBlockRange ?? null;
+  const viewportBlockRanges: readonly { start: number; end: number }[] | null = (() => {
+    if (options.viewportBlockRanges != null) {
+      return options.viewportBlockRanges.length === 0 ? null : options.viewportBlockRanges;
+    }
+    if (options.viewportBlockRange != null) return [options.viewportBlockRange];
+    return null;
+  })();
   const root = normalizeDocumentRoot({
     type: "doc",
     children: [...getStoryBlocks(document, activeStory)],
@@ -199,8 +228,8 @@ export function createEditorSurfaceSnapshot(
 
   for (let index = 0; index < root.children.length; index += 1) {
     const isInViewport =
-      viewportBlockRange === null ||
-      (index >= viewportBlockRange.start && index < viewportBlockRange.end);
+      viewportBlockRanges === null ||
+      isIndexInAnyRange(index, viewportBlockRanges);
     // L7 Phase 2.9 — viewport bail on the style-cascade work. When the
     // block is outside the viewport, the surface block produced below is
     // immediately discarded in favor of a `placeholder-culled` entry (we
@@ -293,10 +322,25 @@ export function createEditorSurfaceSnapshot(
     blocks,
     lockedFragmentIds,
     secondaryStories,
-    viewportBlockRange,
+    viewportBlockRanges,
   };
 }
 
+/**
+ * True when `index` falls in any of the given half-open intervals. Linear
+ * scan because the typical caller passes 1 or 2 ranges; switching to binary
+ * search has no measurable payoff below ~8 ranges.
+ */
+function isIndexInAnyRange(
+  index: number,
+  ranges: readonly { start: number; end: number }[],
+): boolean {
+  for (const r of ranges) {
+    if (index >= r.start && index < r.end) return true;
+  }
+  return false;
+}
+
 function createSurfaceBlock(
   block: BlockNode,
   document: CanonicalDocumentEnvelope,