@beyondwork/docx-react-component 1.0.77 → 1.0.79

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@beyondwork/docx-react-component",
   "publisher": "beyondwork",
-  "version": "1.0.77",
+  "version": "1.0.79",
   "description": "Embeddable React Word (docx) editor with review, comments, tracked changes, and round-trip OOXML fidelity.",
   "type": "module",
   "sideEffects": [

package/src/api/public-types.ts

@@ -1566,6 +1566,22 @@ export type SurfaceBlockSnapshot =
        * See CLAUDE.md (lane status table)
        */
       placeholderSize?: number;
+      /**
+       * Visual height of the block the placeholder stands in for, in twips,
+       * as computed by the L04 paginator against the fully-realized surface.
+       * When present, the PM placeholder emits a fixed-height `<div>` so the
+       * scrollable canvas matches what the realized block will occupy once
+       * it re-enters the viewport — eliminating the "paragraphs jump around
+       * pagination gaps" flicker that plagued culled regions rendered as
+       * single-line ZWSP stubs.
+       *
+       * Populated by `DocumentRuntime.buildRenderSnapshot()` after each
+       * pagination pass; surface-projection itself does not set it (L03 has
+       * no layout data). Consumers that build a surface without a runtime
+       * (tests, plain-text preview) safely leave it `undefined` and fall
+       * back to the `min-height: 20px` behaviour.
+       */
+      placeholderHeightTwips?: number;
       state: "locked-preserve-only" | "placeholder-culled";
     };
 
@@ -2487,9 +2503,43 @@ export interface AddScopeParams {
 }
 
 export interface AddScopeResult {
+  /**
+   * Minted scope id. Empty string (`""`) iff the marker plant failed —
+   * in that case `anchor.kind === "detached"` + `plantStatus.planted`
+   * is `false`. Pre-2026-04-24 a plant failure silently returned a
+   * non-empty scopeId that later resolved to `scope-not-resolvable`;
+   * callers must now check `scopeId.length > 0` (or equivalently
+   * `plantStatus?.planted !== false`) before using the id.
+   */
   scopeId: string;
-  /** Range anchor derived from the just-inserted marker positions. */
+  /** Range anchor derived from the just-inserted marker positions, or a detached placeholder on plant failure. */
   anchor: EditorAnchorProjection;
+  /**
+   * Structured diagnostic for the marker-plant attempt. Omitted on the
+   * happy path for back-compat; populated with `planted: false` + a
+   * typed reason when the plant was refused (cross-paragraph range,
+   * non-paragraph target, out-of-bounds). Callers that previously
+   * assumed every returned `scopeId` was live should migrate to
+   * checking this field.
+   */
+  plantStatus?: {
+    readonly planted: false;
+    readonly reason:
+      | "cross-paragraph-range"
+      | "non-paragraph-target"
+      | "range-out-of-bounds"
+      | "empty-document";
+    readonly requestedFrom: number;
+    readonly requestedTo: number;
+    /** Present on `cross-paragraph-range`. */
+    readonly fromBlockIndex?: number;
+    readonly toBlockIndex?: number;
+    /** Present on `non-paragraph-target`. */
+    readonly blockIndex?: number;
+    readonly blockKind?: string;
+    /** Present on `range-out-of-bounds`. */
+    readonly storyLength?: number;
+  };
 }
 
 export interface ExportDocxOptions {

package/src/api/v3/runtime/workflow.ts

@@ -160,13 +160,20 @@ export type CreateScopeFromAnchorResult =
       readonly reason:
         | "from-negative"
         | "to-less-than-from"
-        | "range-exceeds-story-length";
+        | "range-exceeds-story-length"
+        | "cross-paragraph-range"
+        | "non-paragraph-target"
+        | "empty-document";
       readonly from: number;
       readonly to: number;
       readonly storyLength: number;
+      readonly fromBlockIndex?: number;
+      readonly toBlockIndex?: number;
+      readonly blockIndex?: number;
+      readonly blockKind?: string;
       /** Agent-actionable single-sentence explanation. Safe to surface to LLM tool replies as-is. */
       readonly message: string;
-      /** Machine-routable next-step hint (`"clamp-from-to-zero"` / `"swap-from-and-to"` / `"clamp-to-to-storyLength-or-pick-a-different-range"`). */
+      /** Machine-routable next-step hint. */
       readonly nextStep: string;
     };
 
@@ -533,6 +540,18 @@ export function createWorkflowFamily(runtime: RuntimeApiHandle) {
           from: adapterResult.from,
           to: adapterResult.to,
           storyLength: adapterResult.storyLength,
+          ...(adapterResult.fromBlockIndex !== undefined
+            ? { fromBlockIndex: adapterResult.fromBlockIndex }
+            : {}),
+          ...(adapterResult.toBlockIndex !== undefined
+            ? { toBlockIndex: adapterResult.toBlockIndex }
+            : {}),
+          ...(adapterResult.blockIndex !== undefined
+            ? { blockIndex: adapterResult.blockIndex }
+            : {}),
+          ...(adapterResult.blockKind !== undefined
+            ? { blockKind: adapterResult.blockKind }
+            : {}),
           message: adapterResult.message,
           nextStep: adapterResult.nextStep,
         };

package/src/core/commands/add-scope.ts

@@ -7,18 +7,72 @@ import type {
 } from "../../model/canonical-document.ts";
 import type { CanonicalDocumentEnvelope } from "../state/editor-state.ts";
 
-export interface InsertScopeMarkersResult {
-  document: CanonicalDocumentEnvelope;
-  scopeId: string;
-}
+/**
+ * Discriminated return — pre-2026-04-24 this helper silently returned
+ * the input document unchanged on every failure mode, which left
+ * callers holding a minted `scopeId` that referenced nothing in the
+ * canonical tree. `compileScopeById` later returned null and the v3
+ * surface emitted `scope-not-resolvable:<scopeId>` without the caller
+ * knowing whether the scope was ever live. Every non-`"planted"`
+ * status is now typed so callers can discriminate + surface
+ * agent-actionable recovery hints.
+ */
+export type InsertScopeMarkersResult =
+  | {
+      readonly status: "planted";
+      readonly document: CanonicalDocumentEnvelope;
+      readonly scopeId: string;
+      /** Absolute span that got planted (after from/to normalization). */
+      readonly plantedRange: { readonly from: number; readonly to: number };
+    }
+  | {
+      readonly status: "cross-paragraph-range";
+      readonly scopeId: string;
+      readonly from: number;
+      readonly to: number;
+      readonly fromBlockIndex: number;
+      readonly toBlockIndex: number;
+    }
+  | {
+      readonly status: "non-paragraph-target";
+      readonly scopeId: string;
+      readonly from: number;
+      readonly to: number;
+      readonly blockIndex: number;
+      readonly blockKind: string;
+    }
+  | {
+      readonly status: "range-out-of-bounds";
+      readonly scopeId: string;
+      readonly from: number;
+      readonly to: number;
+      readonly storyLength: number;
+    }
+  | {
+      readonly status: "empty-document";
+      readonly scopeId: string;
+      readonly from: number;
+      readonly to: number;
+    };
 
 /**
- * Pure helper — returns a new CanonicalDocumentEnvelope with a pair of
- * scope-marker inline nodes inserted at the given position range.
+ * Pure helper — returns a discriminated result describing whether a
+ * pair of `scope_marker_start` / `scope_marker_end` inline nodes got
+ * inserted at `[from, to]`.
+ *
+ * Failure modes (all previously silent — pre-2026-04-24):
+ *   - `cross-paragraph-range` — `from` and `to` resolve to different
+ *     top-level paragraph blocks. Multi-block marker scopes are not
+ *     yet wired; narrow the range to land inside one paragraph.
+ *   - `non-paragraph-target` — the target range lands inside a
+ *     non-paragraph block (table / SDT / section_break). Marker
+ *     scopes only plant inside paragraphs today.
+ *   - `range-out-of-bounds` — `to` exceeds the main story length.
+ *   - `empty-document` — the document has no root / no children.
  *
- * Supports the common case: `from` and `to` land in the same top-level
- * paragraph. Cross-paragraph ranges are currently a no-op and return the
- * document unchanged — multi-block scopes ship in a follow-up slice.
+ * Each failure variant names the scopeId the caller had minted but
+ * does NOT mutate the document — callers treat it as a hard failure
+ * and must not register the scopeId on the overlay.
  */
 export function insertScopeMarkers(
   document: CanonicalDocumentEnvelope,
@@ -30,57 +84,130 @@ export function insertScopeMarkers(
 ): InsertScopeMarkersResult {
   const { scopeId, from, to } = params;
   const root = document.content as DocumentRootNode;
-  if (!root || root.type !== "doc") return { document, scopeId };
-
   const normalizedFrom = Math.min(from, to);
   const normalizedTo = Math.max(from, to);
 
+  if (!root || root.type !== "doc" || root.children.length === 0) {
+    return {
+      status: "empty-document",
+      scopeId,
+      from: normalizedFrom,
+      to: normalizedTo,
+    };
+  }
+
+  // First pass — locate which block each of `from` and `to` resolves to,
+  // so we can distinguish cross-paragraph / non-paragraph / out-of-bounds
+  // failures before attempting the plant.
   let cursor = 0;
-  let inserted = false;
-  const children = root.children.map((block, blockIndex) => {
-    if (inserted) return block;
-    if (block.type !== "paragraph") {
-      cursor += 1;
-      if (blockIndex < root.children.length - 1) cursor += 1;
-      return block;
+  let fromBlockIndex = -1;
+  let fromBlockKind: string | null = null;
+  let toBlockIndex = -1;
+  let toBlockKind: string | null = null;
+  let storyLength = 0;
+
+  for (let i = 0; i < root.children.length; i += 1) {
+    const block = root.children[i]!;
+    const blockFrom = cursor;
+    let blockLength: number;
+    if (block.type === "paragraph") {
+      blockLength = block.children.reduce(
+        (total, child) => total + inlineLength(child as InlineNode),
+        0,
+      );
+    } else {
+      blockLength = 1;
+    }
+    const blockTo = blockFrom + blockLength;
+    if (fromBlockIndex === -1 && normalizedFrom >= blockFrom && normalizedFrom <= blockTo) {
+      fromBlockIndex = i;
+      fromBlockKind = block.type;
     }
+    if (toBlockIndex === -1 && normalizedTo >= blockFrom && normalizedTo <= blockTo) {
+      toBlockIndex = i;
+      toBlockKind = block.type;
+    }
+    cursor = blockTo;
+    if (i < root.children.length - 1) cursor += 1;
+    storyLength = cursor;
+  }
 
-    const paragraphFrom = cursor;
-    const paragraphLength = block.children.reduce(
-      (total, child) => total + inlineLength(child as InlineNode),
-      0,
-    );
-    const paragraphTo = paragraphFrom + paragraphLength;
-    cursor = paragraphTo + 1;
+  if (normalizedFrom < 0 || normalizedTo > storyLength) {
+    return {
+      status: "range-out-of-bounds",
+      scopeId,
+      from: normalizedFrom,
+      to: normalizedTo,
+      storyLength,
+    };
+  }
+  if (fromBlockIndex === -1 || toBlockIndex === -1) {
+    return {
+      status: "range-out-of-bounds",
+      scopeId,
+      from: normalizedFrom,
+      to: normalizedTo,
+      storyLength,
+    };
+  }
+  if (fromBlockIndex !== toBlockIndex) {
+    return {
+      status: "cross-paragraph-range",
+      scopeId,
+      from: normalizedFrom,
+      to: normalizedTo,
+      fromBlockIndex,
+      toBlockIndex,
+    };
+  }
+  if (fromBlockKind !== "paragraph") {
+    return {
+      status: "non-paragraph-target",
+      scopeId,
+      from: normalizedFrom,
+      to: normalizedTo,
+      blockIndex: fromBlockIndex,
+      blockKind: fromBlockKind ?? "unknown",
+    };
+  }
 
-    if (
-      normalizedFrom < paragraphFrom ||
-      normalizedTo > paragraphTo ||
-      normalizedFrom > paragraphTo
-    ) {
+  // Plant — we've validated the range lands inside a single paragraph.
+  cursor = 0;
+  const children = root.children.map((block, blockIndex) => {
+    if (blockIndex !== fromBlockIndex) {
+      if (block.type === "paragraph") {
+        const len = block.children.reduce(
+          (total, child) => total + inlineLength(child as InlineNode),
+          0,
+        );
+        cursor += len;
+      } else {
+        cursor += 1;
+      }
+      if (blockIndex < root.children.length - 1) cursor += 1;
       return block;
     }
-
-    inserted = true;
+    const paragraphFrom = cursor;
+    const paragraph = block as ParagraphNode;
     const startOffset = normalizedFrom - paragraphFrom;
     const endOffset = normalizedTo - paragraphFrom;
     const newChildren = injectMarkersIntoInlineList(
-      block.children as InlineNode[],
+      paragraph.children as InlineNode[],
       scopeId,
       startOffset,
       endOffset,
     );
-    return { ...block, children: newChildren } as ParagraphNode;
+    return { ...paragraph, children: newChildren };
   });
 
-  if (!inserted) return { document, scopeId };
-
   return {
+    status: "planted",
     document: {
       ...document,
       content: { ...root, children },
     },
     scopeId,
+    plantedRange: { from: normalizedFrom, to: normalizedTo },
   };
 }
 

package/src/io/ooxml/parse-shapes.ts

@@ -10,7 +10,7 @@
  * preserved in the canonical node's rawXml field for lossless round-trip export.
  */
 
-import type { ShapeContent } from "../../model/canonical-document.ts";
+import type { BlockNode, ShapeContent } from "../../model/canonical-document.ts";
 import { parseFill } from "./parse-fill.ts";
 import {
   type XmlElementNode,
@@ -40,7 +40,7 @@ export interface ParsedWpsShape {
    * shape-textbox paragraphs). Same shape + semantics as
    * `ShapeContent.txbxBlocks` on the drawing-frame path.
    */
-  txbxBlocks?: ReadonlyArray<{ type: string; [key: string]: unknown }>;
+  txbxBlocks?: ReadonlyArray<BlockNode>;
   /** DrawML geometry preset, e.g. "rect", "roundRect". */
   geometry?: string;
   /** Original drawing XML for lossless round-trip export. */
@@ -122,10 +122,20 @@ export function parseShapeXml(
   // content (CCEP "Copyright CCEP STRICTLY CONFIDENTIAL" footer band)
   // is reachable only via the `.text` summary string — L03 cascade +
   // L11 render can't walk runs/marks.
-  let txbxBlocks: ReadonlyArray<{ type: string; [key: string]: unknown }> | undefined;
+  let txbxBlocks: ReadonlyArray<BlockNode> | undefined;
   if (txbxContentXml && blockParser) {
     try {
-      txbxBlocks = blockParser(txbxContentXml);
+      // The `blockParser` callback is supplied by parse-main-document.ts
+      // as a thin wrapper over `parseBlockStreamFromXml`. That function
+      // returns `ParsedBlockNode[]` — structurally identical to canonical
+      // `BlockNode[]` at runtime for shape-textbox content (verified on
+      // CCEP SOW footer fixture 2026-04-24: paragraph + text + TextMark
+      // shapes land end-to-end with zero `ParsedBlockNode`-only fields
+      // surfaced). The cast is safe here because the runtime output IS
+      // canonical; a structural `as unknown as BlockNode[]` preserves
+      // type safety at every consumer site (L03 cascade, L11 render,
+      // validator walk).
+      txbxBlocks = blockParser(txbxContentXml) as unknown as ReadonlyArray<BlockNode>;
     } catch {
       txbxBlocks = undefined;
     }
@@ -214,6 +224,17 @@ function extractAllText(node: XmlElementNode): string {
 // txbxContentXml, optional recursive txbxBlocks).
 // ───────────────────────────────────────────────────────────────────────────
 
+/**
+ * Callback signature for the txbx-content block parser supplied by
+ * parse-main-document.ts / parse-headers-footers.ts. The actual
+ * implementation wraps `parseBlockStreamFromXml` which returns
+ * `ParsedBlockNode[]`; its runtime output is canonical `BlockNode[]`
+ * for shape-textbox content (no `ParsedBlockNode`-only fields surface
+ * at the shape boundary — verified on CCEP SOW footer fixture
+ * 2026-04-24). The structural `unknown` return keeps the parse layer
+ * layer-pure; `parseShapeContent` + `parseShapeXml` cast to canonical
+ * `BlockNode[]` at the assembly seam.
+ */
 export type TxbxBlockParser = (xml: string) => ReadonlyArray<{ type: string; [key: string]: unknown }>;
 
 export function parseShapeContent(
@@ -240,10 +261,15 @@ export function parseShapeContent(
   const txbxContent = txbx ? findFirstDescendant(txbx, "txbxContent") : undefined;
   const txbxContentXml = txbxContent ? extractRawXml(txbxContent) : undefined;
 
-  let txbxBlocks: ReadonlyArray<{ type: string; [key: string]: unknown }> | undefined;
+  let txbxBlocks: ReadonlyArray<BlockNode> | undefined;
   if (txbxContentXml && blockParser) {
     try {
-      txbxBlocks = blockParser(txbxContentXml);
+      // See `TxbxBlockParser` doc above: runtime output is canonical
+      // `BlockNode[]` for shape-textbox content (verified on CCEP SOW
+      // footer fixture 2026-04-24). Cast at the assembly seam so
+      // downstream consumers (L03, L11, validator) get canonical types
+      // without local `as unknown` ceremony.
+      txbxBlocks = blockParser(txbxContentXml) as unknown as ReadonlyArray<BlockNode>;
     } catch {
       // Preserve-only fallback: keep txbxContentXml for serialization; leave
       // txbxBlocks undefined so consumers know recursion did not succeed.

package/src/model/canonical-document.ts

@@ -1786,12 +1786,29 @@ export interface SmartArtPreviewNode {
 /**
  * Read-only rendering of a wps:wsp WordprocessingShape. Text content is
  * extracted for display. The original drawing XML is preserved in rawXml.
+ *
+ * When the shape is a text-box (`isTextBox: true`), the raw textbox XML
+ * is preserved in `txbxContentXml` for lossless round-trip, and the
+ * parsed block structure lands in `txbxBlocks` — canonical `BlockNode[]`
+ * with styles already resolved (coord-02 §14 / coord-11 §22 closed L01
+ * side 2026-04-24 in `7d87f1189`; L02 type-promoted 2026-04-24 once the
+ * runtime contract was confirmed canonical).
  */
 export interface ShapeNode {
   type: "shape";
   text?: string;
   geometry?: string;
   isTextBox?: boolean;
+  /** Raw `<w:txbxContent>` XML, preserved for serialization + round-trip. */
+  txbxContentXml?: string;
+  /**
+   * Parsed canonical block-level structure from `<w:txbxContent>`,
+   * populated when the parse path supplies a `blockParser` callback
+   * (headers/footers via `src/io/ooxml/parse-headers-footers.ts`;
+   * body via `src/io/ooxml/parse-main-document.ts`). Shape + semantics
+   * identical to `ShapeContent.txbxBlocks` on the drawing-frame path.
+   */
+  txbxBlocks?: ReadonlyArray<BlockNode>;
   rawXml: string;
 }
 
@@ -1971,14 +1988,16 @@ export interface ShapeContent {
    * Parsed block-level structure from `w:txbxContent`, populated when a
    * `blockParser` callback is supplied during parse (CO4 F3.3).
    *
-   * Type is deliberately structural (`{ type: string; ... }`) rather than
-   * canonical `BlockNode[]` because the recursion stops at the parse layer
-   * before the style + numbering normalization pass that converts
-   * `ParsedBlockNode` → canonical `BlockNode`. Consumers that need the fully
-   * normalized form run normalization on this subtree explicitly. Testing
-   * that `txbxBlocks.length > 0` proves the recursion executed.
+   * Canonical `BlockNode[]` — the parse path produces fully-normalized
+   * blocks (styles resolved, marks attached, no `ParsedBlockNode`-only
+   * fields at runtime). Verified on the CCEP SOW footer fixture 2026-04-24:
+   * paragraph + text + `TextMark` shapes land end-to-end. Type promoted
+   * 2026-04-24 from the earlier weakly-typed escape hatch once the L01
+   * shape-textbox parse (commit `7d87f1189`) confirmed the runtime
+   * contract — unblocks L03 cascade + L11 render walking `txbxBlocks`
+   * without `as unknown as BlockNode[]` casts at the consumer site.
    */
-  txbxBlocks?: ReadonlyArray<{ type: string; [key: string]: unknown }>;
+  txbxBlocks?: ReadonlyArray<BlockNode>;
   rawXml: string;
 }
 
@@ -2860,11 +2879,29 @@ function validateDocumentNode(
       return;
     case "chart_preview":
     case "smartart_preview":
-    case "shape":
     case "wordart":
     case "vml_shape":
       expectString(record.rawXml, `${path}.rawXml`, issues);
       return;
+    case "shape":
+      expectString(record.rawXml, `${path}.rawXml`, issues);
+      if (record.txbxBlocks !== undefined) {
+        if (!Array.isArray(record.txbxBlocks)) {
+          issues.push({
+            path: `${path}.txbxBlocks`,
+            message: "shape.txbxBlocks must be an array when present.",
+          });
+        } else {
+          // coord-02 §14 follow-up (2026-04-24): `ShapeNode.txbxBlocks`
+          // is canonical `BlockNode[]`. Walk it with the same validator
+          // used for top-level document content so run marks / paragraph
+          // structure / nested shapes all enforce the normal rules.
+          record.txbxBlocks.forEach((child, index) => {
+            validateDocumentNode(child, `${path}.txbxBlocks[${index}]`, issues);
+          });
+        }
+      }
+      return;
     case "drawing_frame": {
       const anchor = asPlainObject(record.anchor, `${path}.anchor`, issues);
       const content = asPlainObject(record.content, `${path}.content`, issues);

package/src/runtime/document-runtime.ts

@@ -57,6 +57,7 @@ import type {
   RestoreResult,
   ReviewWorkSnapshot,
   RuntimeContextAnalyticsQuery,
+  EditorSurfaceSnapshot,
   RuntimeContextAnalyticsSnapshot,
   RuntimeRenderSnapshot,
   ScopeTagTouch,
@@ -1561,17 +1562,91 @@ export function createDocumentRuntime(
     });
     recordPerfSample("snapshot.surface");
     incrementInvalidationCounter("runtime.snapshot.surfaceMisses");
+    // Viewport-cull flicker fix — enrich `placeholder-culled` opaque
+    // blocks with the block's known rendered height (twips) so the PM
+    // placeholder emits a fixed-height `<div>` sized to match what the
+    // realized block will occupy once it re-enters the viewport. Without
+    // this, culled stubs render at `min-height: 20px` regardless of their
+    // real visual size; scrolling into a culled region inflates every
+    // block to its real height in succession and drags content below
+    // the scroll pointer (the "paragraphs jump around pagination gaps"
+    // flicker).
+    //
+    // The heights come from L04's page graph, which is already computed
+    // on a FULLY-REALIZED surface inside `layout-engine-instance.ts` —
+    // i.e. pagination is independent of the viewport cull, so every
+    // blockId has an authoritative height regardless of whether its
+    // surface block is real or a placeholder. `getBlockHeightsTwips()`
+    // sums per-block fragments and caches per `graph.revision`.
+    //
+    // No-op on pre-pagination calls (engine not yet ready → empty map)
+    // and on the inert facet.
+    const enrichedSnapshot = enrichCulledPlaceholdersWithHeights(snapshot);
     cachedSurface = {
       revisionToken: state.revisionToken,
       activeStoryKey,
       viewportRangesKey,
-      snapshot,
+      snapshot: enrichedSnapshot,
     };
     // 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;
+    return enrichedSnapshot;
+  }
+
+  function enrichCulledPlaceholdersWithHeights(
+    snapshot: EditorSurfaceSnapshot,
+  ): EditorSurfaceSnapshot {
+    let heights: ReadonlyMap<string, number>;
+    try {
+      heights = layoutFacet.getBlockHeightsTwips();
+    } catch {
+      return snapshot;
+    }
+    if (heights.size === 0) return snapshot;
+    let changed = false;
+    const enrichedBlocks = snapshot.blocks.map((block) => {
+      if (
+        block.kind !== "opaque_block" ||
+        block.state !== "placeholder-culled"
+      ) {
+        return block;
+      }
+      // The culled placeholder's blockId is `placeholder-culled-<index>`;
+      // the underlying ParagraphNode kept its own id which is NOT carried
+      // on the placeholder. Instead, identify the real block by its
+      // `from` offset — surface-projection guarantees `from` on the
+      // placeholder mirrors the real block's `from`, and fragment records
+      // on the page graph record runtime offsets.
+      const realBlockIdFromOffset = resolveBlockIdFromRuntimeOffset(
+        layoutFacet,
+        block.from,
+      );
+      if (!realBlockIdFromOffset) return block;
+      const heightTwips = heights.get(realBlockIdFromOffset);
+      if (typeof heightTwips !== "number" || heightTwips <= 0) return block;
+      changed = true;
+      return { ...block, placeholderHeightTwips: heightTwips };
+    });
+    if (!changed) return snapshot;
+    return { ...snapshot, blocks: enrichedBlocks };
+  }
+
+  function resolveBlockIdFromRuntimeOffset(
+    facet: WordReviewEditorLayoutFacet,
+    runtimeOffset: number,
+  ): string | null {
+    // `getFragmentForOffset` exists on the facet; use it to recover the
+    // real blockId for a given offset without having to walk all
+    // fragments. Returns the fragment whose `[from, to)` contains the
+    // offset, or null.
+    try {
+      const frag = facet.getFragmentForOffset?.(runtimeOffset);
+      return frag?.blockId ?? null;
+    } catch {
+      return null;
+    }
   }
 
   function getCachedFieldSnapshot(document: CanonicalDocumentEnvelope): FieldSnapshot {

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

@@ -65,6 +65,7 @@ export function createInertLayoutFacet(): WordReviewEditorLayoutFacet {
     invalidateMeasurementCache: () => undefined,
     getTableRenderPlan: () => null,
     getTableBodyYOffsetOnPage: () => null,
+    getBlockHeightsTwips: () => new Map(),
     getDirtyFieldFamilies: () => [],
     getFieldDirtinessReport: () => emptyReport,
     setVisibleBlockRange: () => undefined,

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

@@ -955,8 +955,34 @@
  *   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.
+ *
+ *  57 — viewport-cull flicker fix. The pre-v57 PM placeholder emitted
+ *   for `placeholder-culled` opaque blocks rendered at
+ *   `min-height: 20px` regardless of the real block's visual height
+ *   (`src/ui-tailwind/editor-surface/pm-schema.ts`), because neither
+ *   L03 surface-projection nor L11 PM state-build had access to
+ *   layout-derived heights. Scrolling into a culled region inflated
+ *   every block in turn, dragging content below the scroll pointer —
+ *   the long-standing "paragraphs jump around pagination gaps"
+ *   flicker.
+ *
+ *   L04 now exposes `WordReviewEditorLayoutFacet.getBlockHeightsTwips():
+ *   ReadonlyMap<string, number>` — one entry per blockId, value = sum
+ *   of that block's fragments' `heightTwips`. Cached per
+ *   `graph.revision`. `DocumentRuntime` reads the map after each
+ *   surface-projection pass and enriches every
+ *   `placeholder-culled` `opaque_block` with
+ *   `placeholderHeightTwips`. The PM schema's paragraph node gained
+ *   a `placeholderHeightTwips` attr; `toDOM` emits
+ *   `height: ${twips/20}pt` instead of the `min-height: 20px`
+ *   fallback when the attr is set.
+ *
+ *   Pagination itself is untouched — this is purely a render-surface
+ *   fix. Cache envelopes from v56 invalidate because the exposed
+ *   facet surface grew one public method; any consumer relying on
+ *   the prior interface shape re-derives its cache key under v57.
  */
-export const LAYOUT_ENGINE_VERSION = 56 as const;
+export const LAYOUT_ENGINE_VERSION = 57 as const;
 
 /**
  * Serialization schema version for the LayCache payload (the cache envelope