@beyondwork/docx-react-component 1.0.43 → 1.0.45

package/src/runtime/edit-dispatch/list-aware-dispatch.ts

@@ -0,0 +1,125 @@
+import type {
+  EditorSessionState,
+  EditorStoryTarget,
+  RuntimeRenderSnapshot,
+  SelectionSnapshot as PublicSelectionSnapshot,
+  SurfaceBlockSnapshot,
+} from "../../api/public-types";
+import { type SelectionSnapshot as InternalSelectionSnapshot } from "../../core/state/editor-state.ts";
+import {
+  backspaceAtListStart,
+  indentListItems,
+  outdentListItems,
+  splitListParagraph,
+} from "../../core/commands/list-commands.ts";
+
+export type DispatchTextCommand =
+  | { type: "insert-text"; text: string }
+  | { type: "delete-backward" }
+  | { type: "delete-forward" }
+  | { type: "insert-tab" }
+  | { type: "outdent-tab" }
+  | { type: "insert-hard-break" }
+  | { type: "split-paragraph" };
+
+export interface ListAwareParagraphContext {
+  paragraphIndex: number;
+  paragraph: Extract<SurfaceBlockSnapshot, { kind: "paragraph" }>;
+  atParagraphStart: boolean;
+  isEmpty: boolean;
+}
+
+export interface StoryMutationContext {
+  timestamp: string;
+  activeStory: EditorStoryTarget;
+  persistedDocument: EditorSessionState["canonicalDocument"];
+  localDocument: EditorSessionState["canonicalDocument"];
+  localSnapshot: RuntimeRenderSnapshot;
+}
+
+export interface ListAwareMutationResult {
+  changed: boolean;
+  document: EditorSessionState["canonicalDocument"];
+  selection: InternalSelectionSnapshot;
+}
+
+export interface ListAwareDispatchDeps {
+  resolveActiveParagraphContext(
+    snapshot: Pick<RuntimeRenderSnapshot, "surface" | "selection">,
+  ): ListAwareParagraphContext | null;
+  toRuntimeSelectionSnapshot(selection: PublicSelectionSnapshot): InternalSelectionSnapshot;
+}
+
+export function applyListAwareTextCommand(
+  context: StoryMutationContext,
+  command: DispatchTextCommand,
+  deps: ListAwareDispatchDeps,
+): ListAwareMutationResult | null {
+  const paragraphContext = deps.resolveActiveParagraphContext(context.localSnapshot);
+  if (!paragraphContext?.paragraph.numbering) {
+    return null;
+  }
+
+  switch (command.type) {
+    case "insert-tab": {
+      const result = indentListItems(
+        context.localDocument,
+        [paragraphContext.paragraphIndex],
+        { timestamp: context.timestamp },
+      );
+      return createListMutationResult(result, context.localSnapshot.selection, deps);
+    }
+    case "outdent-tab": {
+      const result = outdentListItems(
+        context.localDocument,
+        [paragraphContext.paragraphIndex],
+        { timestamp: context.timestamp },
+      );
+      return createListMutationResult(result, context.localSnapshot.selection, deps);
+    }
+    case "delete-backward": {
+      if (!paragraphContext.atParagraphStart || !context.localSnapshot.selection.isCollapsed) {
+        return null;
+      }
+      const result = backspaceAtListStart(
+        context.localDocument,
+        paragraphContext.paragraphIndex,
+        { timestamp: context.timestamp },
+      );
+      return result.handled
+        ? createListMutationResult(result, context.localSnapshot.selection, deps)
+        : null;
+    }
+    case "split-paragraph": {
+      if (!context.localSnapshot.selection.isCollapsed || !paragraphContext.isEmpty) {
+        return null;
+      }
+      const result = splitListParagraph(
+        context.localDocument,
+        paragraphContext.paragraphIndex,
+        true,
+        { timestamp: context.timestamp },
+      );
+      return result.action === "split"
+        ? null
+        : createListMutationResult(result, context.localSnapshot.selection, deps);
+    }
+    default:
+      return null;
+  }
+}
+
+function createListMutationResult(
+  result: {
+    document: EditorSessionState["canonicalDocument"];
+    affectedParagraphIndexes: number[];
+  },
+  selection: RuntimeRenderSnapshot["selection"],
+  deps: ListAwareDispatchDeps,
+): ListAwareMutationResult {
+  return {
+    changed: result.affectedParagraphIndexes.length > 0,
+    document: result.document,
+    selection: deps.toRuntimeSelectionSnapshot(selection),
+  };
+}

package/src/runtime/editor-surface/capabilities.ts

@@ -0,0 +1,411 @@
+/**
+ * Editor capability table — the single source of truth for every
+ * keyboard shortcut, context-menu action, and surface dispatch the
+ * mounted editor knows about.
+ *
+ * An `EditorCapability` classifies a binding into one of four kinds:
+ *   - `supported`      — the editor owns the mutation (runtime command
+ *                        or shell op).
+ *   - `host-delegated` — the editor recognizes the input but hands it
+ *                        off to the host via a typed callback prop.
+ *                        Host event name lives in `hostEvent`.
+ *   - `blocked`        — the editor explicitly rejects the input. The
+ *                        host sees a `command_blocked` event with the
+ *                        `blockReason.code` and `blockReason.message`.
+ *   - `passthrough`    — the editor does not intercept; the browser
+ *                        default behavior wins.
+ *
+ * This table is consumed by:
+ *   - `src/ui/runtime-shortcut-dispatch.ts` (I3 C.2) — each resolution
+ *     branch looks up by id rather than hard-coding block reasons.
+ *   - `docs/reference/editor-capabilities.md` (I3 C.4) — generated
+ *     from this table so the wiki + reference doc stay in sync.
+ *   - `src/ui/WordReviewEditor.tsx` (I3 C.3) — `host-delegated`
+ *     entries wire their `hostEvent` to the matching prop on
+ *     `WordReviewEditorProps`.
+ *
+ * C.1 (this file): enumerate every shortcut already present in
+ * `resolveShellShortcut` / `resolveSurfaceShortcut` / the PM
+ * Alt+Shift+arrow bindings. No behavior change — C.2 is the
+ * dispatcher refactor.
+ *
+ * Scope: keyboard shortcuts only in C.1. Context-menu capabilities
+ * land alongside the right-click hook (Phase F) in a later commit.
+ */
+
+export type CapabilityKind = "supported" | "host-delegated" | "blocked" | "passthrough";
+
+export type CapabilityCategory =
+  | "text-formatting"
+  | "paragraph-formatting"
+  | "navigation"
+  | "selection"
+  | "clipboard"
+  | "history"
+  | "tracked-changes"
+  | "comments"
+  | "structure"
+  | "system";
+
+export interface CapabilityShortcut {
+  /** Canonical Windows / Linux binding string (e.g. "Ctrl+B", "Shift+Tab"). */
+  winLinux: string;
+  /** Canonical Mac binding string (e.g. "Cmd+B", "Shift+Tab"). */
+  mac: string;
+}
+
+export interface CapabilityBlockReason {
+  code: string;
+  message: string;
+}
+
+export interface EditorCapability {
+  /** Stable symbolic identifier. Used for lookup + wire-format. */
+  id: string;
+  kind: CapabilityKind;
+  category: CapabilityCategory;
+  /** Human-readable description for docs + a11y help. */
+  label: string;
+  /** Present when the capability is keyboard-triggered. */
+  shortcut?: CapabilityShortcut;
+  /** For `host-delegated`: the `WordReviewEditorProps` callback name. */
+  hostEvent?: string;
+  /** For `blocked`: the reason returned in the `command_blocked` event. */
+  blockReason?: CapabilityBlockReason;
+}
+
+const UNSUPPORTED_SURFACE = "unsupported_surface";
+
+export const EDITOR_CAPABILITIES: readonly EditorCapability[] = [
+  // ---------------------------------------------------------------
+  // System — shell-level UX affordances
+  // ---------------------------------------------------------------
+  {
+    id: "shell.focus-region",
+    kind: "supported",
+    category: "system",
+    label: "Cycle focus between editor regions",
+    shortcut: { winLinux: "F6", mac: "F6" },
+  },
+  {
+    id: "shell.dismiss-selection-toolbar",
+    kind: "supported",
+    category: "system",
+    label: "Dismiss the selection toolbar",
+    shortcut: { winLinux: "Escape", mac: "Escape" },
+  },
+
+  // ---------------------------------------------------------------
+  // History
+  // ---------------------------------------------------------------
+  {
+    id: "history.undo",
+    kind: "supported",
+    category: "history",
+    label: "Undo",
+    shortcut: { winLinux: "Ctrl+Z", mac: "Cmd+Z" },
+  },
+  {
+    id: "history.redo",
+    kind: "supported",
+    category: "history",
+    label: "Redo",
+    shortcut: { winLinux: "Ctrl+Y", mac: "Cmd+Shift+Z" },
+  },
+
+  // ---------------------------------------------------------------
+  // Text formatting — shell-dispatched marks
+  // ---------------------------------------------------------------
+  {
+    id: "mark.toggle-bold",
+    kind: "supported",
+    category: "text-formatting",
+    label: "Toggle bold",
+    shortcut: { winLinux: "Ctrl+B", mac: "Cmd+B" },
+  },
+  {
+    id: "mark.toggle-italic",
+    kind: "supported",
+    category: "text-formatting",
+    label: "Toggle italic",
+    shortcut: { winLinux: "Ctrl+I", mac: "Cmd+I" },
+  },
+  {
+    id: "mark.toggle-underline",
+    kind: "supported",
+    category: "text-formatting",
+    label: "Toggle underline",
+    shortcut: { winLinux: "Ctrl+U", mac: "Cmd+U" },
+  },
+
+  // ---------------------------------------------------------------
+  // Comments
+  // ---------------------------------------------------------------
+  {
+    id: "comment.add",
+    kind: "supported",
+    category: "comments",
+    label: "Insert comment at selection",
+    shortcut: { winLinux: "Ctrl+Alt+M", mac: "Cmd+Option+A" },
+  },
+
+  // ---------------------------------------------------------------
+  // Paragraph-formatting — heading levels
+  // ---------------------------------------------------------------
+  {
+    id: "heading.set-level-1",
+    kind: "supported",
+    category: "paragraph-formatting",
+    label: "Apply Heading 1 style",
+    shortcut: { winLinux: "Ctrl+Alt+1", mac: "Cmd+Option+1" },
+  },
+  {
+    id: "heading.set-level-2",
+    kind: "supported",
+    category: "paragraph-formatting",
+    label: "Apply Heading 2 style",
+    shortcut: { winLinux: "Ctrl+Alt+2", mac: "Cmd+Option+2" },
+  },
+  {
+    id: "heading.set-level-3",
+    kind: "supported",
+    category: "paragraph-formatting",
+    label: "Apply Heading 3 style",
+    shortcut: { winLinux: "Ctrl+Alt+3", mac: "Cmd+Option+3" },
+  },
+
+  // ---------------------------------------------------------------
+  // Surface-dispatched text commands (PM-focus path)
+  // ---------------------------------------------------------------
+  {
+    id: "text.delete-backward",
+    kind: "supported",
+    category: "text-formatting",
+    label: "Delete character before the cursor",
+    shortcut: { winLinux: "Backspace", mac: "Backspace" },
+  },
+  {
+    id: "text.delete-forward",
+    kind: "supported",
+    category: "text-formatting",
+    label: "Delete character after the cursor",
+    shortcut: { winLinux: "Delete", mac: "Delete" },
+  },
+  {
+    id: "paragraph.split",
+    kind: "supported",
+    category: "structure",
+    label: "Split paragraph at cursor",
+    shortcut: { winLinux: "Enter", mac: "Enter" },
+  },
+  {
+    id: "text.insert-hard-break",
+    kind: "supported",
+    category: "structure",
+    label: "Insert hard line break",
+    shortcut: { winLinux: "Shift+Enter", mac: "Shift+Enter" },
+  },
+  {
+    id: "text.insert-tab",
+    kind: "supported",
+    category: "paragraph-formatting",
+    label: "Indent list item; in table, move to next cell; otherwise insert tab",
+    shortcut: { winLinux: "Tab", mac: "Tab" },
+  },
+  {
+    id: "text.outdent-tab",
+    kind: "supported",
+    category: "paragraph-formatting",
+    label: "Outdent list item or paragraph; in table, move to previous cell",
+    shortcut: { winLinux: "Shift+Tab", mac: "Shift+Tab" },
+  },
+  {
+    id: "list.indent",
+    kind: "supported",
+    category: "paragraph-formatting",
+    label: "Indent current list item (Word Alt+Shift binding)",
+    shortcut: { winLinux: "Alt+Shift+Right", mac: "Option+Shift+Right" },
+  },
+  {
+    id: "list.outdent",
+    kind: "supported",
+    category: "paragraph-formatting",
+    label: "Outdent current list item (Word Alt+Shift binding)",
+    shortcut: { winLinux: "Alt+Shift+Left", mac: "Option+Shift+Left" },
+  },
+  {
+    id: "table.navigate-cell",
+    kind: "supported",
+    category: "navigation",
+    label: "Move to next / previous table cell (Tab / Shift+Tab while inside a table)",
+    shortcut: { winLinux: "Tab", mac: "Tab" },
+  },
+
+  // ---------------------------------------------------------------
+  // Clipboard — force-plain-text shortcut
+  //
+  // Ctrl/Cmd+Shift+V resolves to `{kind: "none"}` at the shell layer
+  // and falls through to the browser's native paste flow, which PM's
+  // handlePaste routes through the same plain-text path as Ctrl/Cmd+V.
+  // Classified as `passthrough` here: we recognize the shortcut but
+  // don't intercept — the browser + PM surface handle it.
+  // ---------------------------------------------------------------
+  {
+    id: "clipboard.paste-plain-text",
+    kind: "passthrough",
+    category: "clipboard",
+    label: "Paste as plain text (today identical to Ctrl/Cmd+V — force-plain-text semantics land with Tier B rich paste)",
+    shortcut: { winLinux: "Ctrl+Shift+V", mac: "Cmd+Shift+V" },
+  },
+
+  // ---------------------------------------------------------------
+  // Host-delegated — browser-owned gestures
+  // ---------------------------------------------------------------
+  {
+    id: "shortcut.find",
+    kind: "host-delegated",
+    category: "navigation",
+    label: "Find in document",
+    shortcut: { winLinux: "Ctrl+F", mac: "Cmd+F" },
+    hostEvent: "onFindRequested",
+  },
+  {
+    id: "shortcut.print",
+    kind: "host-delegated",
+    category: "system",
+    label: "Print document",
+    shortcut: { winLinux: "Ctrl+P", mac: "Cmd+P" },
+    hostEvent: "onPrintRequested",
+  },
+  {
+    id: "shortcut.zoom-in",
+    kind: "host-delegated",
+    category: "system",
+    label: "Zoom in",
+    shortcut: { winLinux: "Ctrl+Plus", mac: "Cmd+Plus" },
+    hostEvent: "onZoomRequested",
+  },
+  {
+    id: "shortcut.zoom-out",
+    kind: "host-delegated",
+    category: "system",
+    label: "Zoom out",
+    shortcut: { winLinux: "Ctrl+Minus", mac: "Cmd+Minus" },
+    hostEvent: "onZoomRequested",
+  },
+  {
+    id: "shortcut.zoom-reset",
+    kind: "host-delegated",
+    category: "system",
+    label: "Reset zoom",
+    shortcut: { winLinux: "Ctrl+0", mac: "Cmd+0" },
+    hostEvent: "onZoomRequested",
+  },
+
+  // ---------------------------------------------------------------
+  // Blocked — Word shortcuts the mounted editor does not implement
+  // ---------------------------------------------------------------
+  {
+    id: "replaceText",
+    kind: "blocked",
+    category: "navigation",
+    label: "Find and replace",
+    shortcut: { winLinux: "Ctrl+H", mac: "Ctrl+H" },
+    blockReason: {
+      code: UNSUPPORTED_SURFACE,
+      message: "Replace shortcuts are not supported in the mounted editor yet.",
+    },
+  },
+  {
+    id: "goTo",
+    kind: "blocked",
+    category: "navigation",
+    label: "Go to",
+    shortcut: { winLinux: "Ctrl+G", mac: "Cmd+Option+G" },
+    blockReason: {
+      code: UNSUPPORTED_SURFACE,
+      message: "Go To shortcuts are not supported in the mounted editor yet.",
+    },
+  },
+  {
+    id: "toggleTrackChanges",
+    kind: "blocked",
+    category: "tracked-changes",
+    label: "Toggle track-changes authoring mode",
+    shortcut: { winLinux: "Ctrl+Shift+E", mac: "Cmd+Shift+E" },
+    blockReason: {
+      code: UNSUPPORTED_SURFACE,
+      message: "Track changes authoring shortcuts are not supported in the mounted editor.",
+    },
+  },
+  {
+    id: "checkSpelling",
+    kind: "blocked",
+    category: "system",
+    label: "Check spelling",
+    shortcut: { winLinux: "F7", mac: "F7" },
+    blockReason: {
+      code: UNSUPPORTED_SURFACE,
+      message: "Spelling shortcuts are not supported in the mounted editor.",
+    },
+  },
+  {
+    id: "openThesaurus",
+    kind: "blocked",
+    category: "system",
+    label: "Open thesaurus",
+    shortcut: { winLinux: "Shift+F7", mac: "Shift+F7" },
+    blockReason: {
+      code: UNSUPPORTED_SURFACE,
+      message: "Thesaurus shortcuts are not supported in the mounted editor.",
+    },
+  },
+  {
+    id: "extendSelection",
+    kind: "blocked",
+    category: "selection",
+    label: "Extend-selection mode",
+    shortcut: { winLinux: "F8", mac: "F8" },
+    blockReason: {
+      code: UNSUPPORTED_SURFACE,
+      message: "Extend-selection shortcuts are not supported in the mounted editor.",
+    },
+  },
+  {
+    id: "lastEdit",
+    kind: "blocked",
+    category: "navigation",
+    label: "Return to last edit",
+    shortcut: { winLinux: "Shift+F5", mac: "Shift+F5" },
+    blockReason: {
+      code: UNSUPPORTED_SURFACE,
+      message: "Last-edit shortcuts are not supported in the mounted editor.",
+    },
+  },
+];
+
+/**
+ * O(1) lookup by capability id. Derived from `EDITOR_CAPABILITIES`
+ * at module-load; freezes the map so accidental mutation throws.
+ */
+export const CAPABILITY_BY_ID: ReadonlyMap<string, EditorCapability> = (() => {
+  const map = new Map<string, EditorCapability>();
+  for (const cap of EDITOR_CAPABILITIES) {
+    map.set(cap.id, cap);
+  }
+  return map;
+})();
+
+/** Return every capability in the given category (preserves table order). */
+export function capabilitiesByCategory(
+  category: CapabilityCategory,
+): readonly EditorCapability[] {
+  return EDITOR_CAPABILITIES.filter((cap) => cap.category === category);
+}
+
+/** Return every capability with the given kind (preserves table order). */
+export function capabilitiesByKind(
+  kind: CapabilityKind,
+): readonly EditorCapability[] {
+  return EDITOR_CAPABILITIES.filter((cap) => cap.kind === kind);
+}

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

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

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

@@ -182,6 +182,35 @@ export interface LayoutEngineInstance {
    * glyphs, and the cached page graph keeps its stale page boundaries.
    */
   invalidateMeasurementCache(): void;
+
+  // ---- cache rehydration (L7 Phase 2.5) ---------------------------------
+  /**
+   * Seed the engine's cached graph from a prerendered `RuntimePageGraph`
+   * (read from IndexedDB or customXml). Subsequent `getPageGraph()` calls
+   * against the same `document` return the seeded graph directly —
+   * skipping `fullRebuild` and the pagination/measurement work that
+   * dominates cold-open on large docs.
+   *
+   * Both the graph and the source document must be seeded so the
+   * engine's internal cache-key (`content`, `styles`, `subParts`
+   * reference-equality tuple) compares equal on the next query. Passing
+   * only the graph leaves `cachedKey` null, the next query would run a
+   * full rebuild, and the seed would be discarded.
+   *
+   * Caller contract:
+   *   - The seeded graph must have been produced by the same
+   *     LAYOUT_ENGINE_VERSION as the current engine instance. Stale reads
+   *     are prevented by the cache-key scheme in
+   *     src/runtime/prerender/cache-key.ts (engine version is part of the
+   *     key), not by this method.
+   *   - The next runtime mutation triggers a normal invalidation path;
+   *     the seeded graph is treated as a fresh cache entry from the
+   *     engine's perspective.
+   */
+  seedCachedGraph(
+    graph: RuntimePageGraph,
+    document: CanonicalDocumentEnvelope,
+  ): void;
 }
 
 // ---------------------------------------------------------------------------
@@ -737,6 +766,23 @@ export function createLayoutEngine(
       cachedFormatting = null;
       cachedMapper = null;
     },
+
+    /**
+     * L7 Phase 2.5 — seed the cached graph from a prerender envelope.
+     * Populates both `cachedGraph` and `cachedKey` (keyed on the provided
+     * document's identity-equal slots) so the next getPageGraph query
+     * returns the seeded graph directly. Any subsequent mutation
+     * invalidates normally through the existing path.
+     */
+    seedCachedGraph(graph: RuntimePageGraph, document: CanonicalDocumentEnvelope) {
+      cachedGraph = graph;
+      cachedKey = {
+        content: document.content,
+        styles: document.styles,
+        subParts: document.subParts,
+      };
+      previousPageCount = graph.contentPageCount;
+    },
   };
 }
 

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

@@ -0,0 +1,41 @@
+/**
+ * Layout engine version marker — bump when **any** file under
+ * `src/runtime/layout/**` or `src/runtime/render/**` changes, or when
+ * the page-break widget DOM shape under `src/ui-tailwind/editor-surface/`
+ * changes in a way that affects cached render-frame diffs or persisted
+ * layout caches.
+ *
+ * Enforcement: `scripts/ci-check-layout-engine-version.mjs` inspects the
+ * PR diff; if any file in the watched trees is touched without this
+ * constant being co-touched, CI fails.  See CLAUDE.md → *Performance
+ * Invariants* for the full contract.
+ *
+ * Persisted caches should key their stored snapshots on this version so a
+ * bump automatically invalidates stale entries — no corruption path
+ * exists because the version is the cache's top-level discriminator.
+ *
+ * History:
+ *   1 — initial materialization (L8 Phase B).
+ *   2 — L8 Phase B retired the page-posture widget's inline band-gap-band
+ *       DOM in favor of a transparent spacer.  Widget DOM shape changed;
+ *       cached render frames from version 1 are incompatible.
+ *   3 — L7 Phase 2.5 Plan A. Adds `seedCachedGraph(graph, document)` to
+ *       `LayoutEngineInstance` so prerender-cache consumers can seed the
+ *       internal cachedGraph + cachedKey without triggering fullRebuild.
+ *       Does not change geometry — but the public interface changed, so
+ *       persisted envelopes MUST re-derive their cacheKey under 3.
+ */
+export const LAYOUT_ENGINE_VERSION = 3 as const;
+
+/**
+ * Serialization schema version for the LayCache payload (the cache envelope
+ * stored in IndexedDB, and — post Plan B — the customXml editor-state
+ * namespace). Bump independently of LAYOUT_ENGINE_VERSION when the
+ * envelope shape changes but the layout engine itself has not.
+ *
+ * History:
+ *   1 — initial envelope shape: { schemaVersion, engineVersion,
+ *       fontFingerprint, structuralHash, graph, surface }. Ships with
+ *       L7 Phase 2.5 Plan A.
+ */
+export const LAYCACHE_SCHEMA_VERSION = 1 as const;

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

@@ -564,6 +564,19 @@ export interface WordReviewEditorLayoutFacet {
   getDirtyFieldFamilies(): readonly string[];
   getFieldDirtinessReport(): PublicFieldDirtinessReport;
 
+  // Viewport culling (L7 Phase 2) ----------------------------------------
+  /**
+   * Notifies the runtime that the visible block range changed.  Delegates to
+   * `DocumentRuntime.setVisibleBlockRange`.  Safe to call at any frequency;
+   * identical ranges are a no-op inside the runtime.
+   */
+  setVisibleBlockRange(range: { start: number; end: number }): void;
+  /**
+   * Triggers a surface-only refresh applying the latest visible block range.
+   * Delegates to `DocumentRuntime.requestViewportRefresh`.
+   */
+  requestViewportRefresh(): void;
+
   // Events ---------------------------------------------------------------
   subscribe(listener: (event: LayoutFacetEvent) => void): () => void;
 }
@@ -614,6 +627,14 @@ export interface CreateLayoutFacetInput {
     | readonly import("../../api/public-types.ts").WorkflowMetadataMarkup[]
     | null
     | undefined;
+  /**
+   * L7 Phase 2 — optional viewport culling hooks wired from the owning
+   * `DocumentRuntime`.  When supplied, `facet.setVisibleBlockRange` /
+   * `facet.requestViewportRefresh` delegate directly to these; when omitted
+   * (e.g. tests, inert facet, standalone use) both methods are no-ops.
+   */
+  setVisibleBlockRange?: (range: { start: number; end: number }) => void;
+  requestViewportRefresh?: () => void;
   /**
    * R3 — optional suggestions snapshot accessor.  Used by
    * `getAllScopeCardModels` to attach `SuggestionGroup` entries whose
@@ -1231,6 +1252,15 @@ export function createLayoutFacet(
       };
     },
 
+    // L7 Phase 2 — viewport culling delegates
+    setVisibleBlockRange(range) {
+      input.setVisibleBlockRange?.(range);
+    },
+
+    requestViewportRefresh() {
+      input.requestViewportRefresh?.();
+    },
+
     subscribe(listener) {
       listeners.add(listener);
       return () => {