@beyondwork/docx-react-component 1.0.78 → 1.0.79

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@beyondwork/docx-react-component",
   "publisher": "beyondwork",
-  "version": "1.0.78",
+  "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/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

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

@@ -569,6 +569,19 @@ export interface WordReviewEditorLayoutFacet {
    */
   getTableBodyYOffsetOnPage(blockId: string, pageIndex: number): number | null;
 
+  /**
+   * Viewport-cull height resolver — returns total rendered height (twips)
+   * for every block in the current page graph, computed as the sum of each
+   * fragment's `heightTwips` grouped by `blockId`. Consumers (the render
+   * surface builder in particular) use this to size `placeholder-culled`
+   * opaque stubs so the scrollable canvas does not change height when a
+   * block realizes during scroll.
+   *
+   * Returns an empty map on the inert facet or before the first successful
+   * pagination pass. Cached per `graph.revision`.
+   */
+  getBlockHeightsTwips(): ReadonlyMap<string, number>;
+
   // Fields ---------------------------------------------------------------
   getDirtyFieldFamilies(): readonly string[];
   getFieldDirtinessReport(): PublicFieldDirtinessReport;
@@ -707,6 +720,13 @@ export function createLayoutFacet(
     revision: number;
     blocks: readonly PublicRegionBlock[] | null;
   } = { revision: -1, blocks: null };
+  // Viewport-cull flicker fix — per-revision cache for getBlockHeightsTwips.
+  // One entry per blockId; value is the sum of that block's fragments'
+  // `heightTwips`. Busts on `graph.revision` change.
+  let blockHeightsCache: {
+    revision: number;
+    map: ReadonlyMap<string, number> | null;
+  } = { revision: -1, map: null };
 
   function resolveCanonicalDocument(): CanonicalDocumentEnvelope {
     if (input.canonicalDocument) {
@@ -1234,6 +1254,21 @@ export function createLayoutFacet(
       return null;
     },
 
+    getBlockHeightsTwips() {
+      const graph = currentGraph();
+      if (blockHeightsCache.revision === graph.revision && blockHeightsCache.map) {
+        return blockHeightsCache.map;
+      }
+      const map = new Map<string, number>();
+      for (const frag of graph.fragments) {
+        const prev = map.get(frag.blockId) ?? 0;
+        map.set(frag.blockId, prev + frag.heightTwips);
+      }
+      const frozen: ReadonlyMap<string, number> = map;
+      blockHeightsCache = { revision: graph.revision, map: frozen };
+      return frozen;
+    },
+
     getDirtyFieldFamilies() {
       return engine.getDirtyFieldFamilies();
     },

package/src/runtime/workflow/coordinator.ts

@@ -791,19 +791,72 @@ export function createWorkflowCoordinator(deps: CoordinatorDeps): WorkflowCoordi
       return { scopeId, anchor: params.anchor };
     }
 
-    const { document: nextDocument } = insertScopeMarkers(
-      deps.getDocument(),
-      { scopeId, from: anchor.from, to: anchor.to },
-    );
+    const plantResult = insertScopeMarkers(deps.getDocument(), {
+      scopeId,
+      from: anchor.from,
+      to: anchor.to,
+    });
 
-    if (nextDocument !== deps.getDocument()) {
-      deps.dispatch({
-        type: "document.replace",
-        document: nextDocument,
-        origin: { source: "api", at: clock() },
-      });
+    // Plant failed — pre-2026-04-24 this returned silently with a dead
+    // scopeId; callers later saw `scope-not-resolvable`. Now surface
+    // the typed failure on the AddScopeResult so consumers can detect
+    // the plant-failed path without a round-trip through
+    // resolveReference.
+    if (plantResult.status !== "planted") {
+      const callerAssoc: { readonly start: -1 | 1; readonly end: -1 | 1 } =
+        params.anchor.kind === "range"
+          ? params.anchor.assoc
+          : { start: -1, end: 1 };
+      // Return the caller's input range as an informational range
+      // anchor. The authoritative failure signal is `scopeId: ""` +
+      // `plantStatus.planted === false`. The detached-anchor shape has
+      // a fixed reason enum (`deleted|invalidatedByStructureChange|
+      // importAmbiguity`) that doesn't cover plant-refused, so we keep
+      // the range kind and let callers discriminate via plantStatus.
+      return {
+        scopeId: "",
+        anchor: {
+          kind: "range",
+          from: anchor.from,
+          to: anchor.to,
+          assoc: callerAssoc,
+        },
+        plantStatus: {
+          planted: false,
+          reason: plantResult.status,
+          ...(plantResult.status === "cross-paragraph-range"
+            ? {
+                fromBlockIndex: plantResult.fromBlockIndex,
+                toBlockIndex: plantResult.toBlockIndex,
+              }
+            : {}),
+          ...(plantResult.status === "non-paragraph-target"
+            ? {
+                blockIndex: plantResult.blockIndex,
+                blockKind: plantResult.blockKind,
+              }
+            : {}),
+          ...(plantResult.status === "range-out-of-bounds"
+            ? { storyLength: plantResult.storyLength }
+            : {}),
+          requestedFrom: plantResult.from,
+          requestedTo: plantResult.to,
+        },
+      };
+      // Intentionally NOT dispatching document.replace or workflow.set-overlay —
+      // a failed plant must not leave a half-registered scope. Prevents the
+      // pre-fix "overlay carries scopeId but canonical tree has no markers"
+      // state that produced `scope-not-resolvable` on every follow-up call.
     }
 
+    const nextDocument = plantResult.document;
+
+    deps.dispatch({
+      type: "document.replace",
+      document: nextDocument,
+      origin: { source: "api", at: clock() },
+    });
+
     // Coord-06 §13d — preserve the caller's assoc on the public anchor.
     // resolveScope re-derives the range from the inserted markers but emits
     // a hardcoded { start: -1, end: 1 }; without this override the caller's

package/src/runtime/workflow/scope-writer.ts

@@ -276,10 +276,19 @@ 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;
+      /** Cross-paragraph only — the two block indices the range straddled. */
+      readonly fromBlockIndex?: number;
+      readonly toBlockIndex?: number;
+      /** Non-paragraph target only — the offending block's index and kind. */
+      readonly blockIndex?: number;
+      readonly blockKind?: string;
       /**
        * Single-sentence, agent-actionable explanation. Tells the caller
        * what the failure was and the concrete next step — no guesswork
@@ -291,7 +300,9 @@ export type CreateScopeFromAnchorResult =
        * Short machine-routable next-step hint for thin consumers that
        * don't want to pattern-match on `reason`. Examples:
        *   "clamp-from-to-zero", "swap-from-and-to",
-       *   "clamp-to-to-storyLength-or-pick-a-different-range".
+       *   "clamp-to-to-storyLength-or-pick-a-different-range",
+       *   "narrow-to-single-paragraph",
+       *   "pick-a-paragraph-target".
        */
       readonly nextStep: string;
     };
@@ -420,5 +431,82 @@ export function createScopeFromAnchor(
     ...(scopeMetadataFields.length > 0 ? { scopeMetadataFields } : {}),
   });
 
+  // Pre-2026-04-24 the coordinator silently returned a minted scopeId
+  // even when insertScopeMarkers refused to plant (cross-paragraph
+  // range, non-paragraph target, out-of-bounds after the story-length
+  // check passed). Now the coordinator surfaces `plantStatus.planted:
+  // false`; translate each reason into the same `range-invalid` shape
+  // used by the bounds checks above so the caller gets one uniform
+  // discriminator to branch on.
+  if (result.plantStatus && result.plantStatus.planted === false) {
+    const ps = result.plantStatus;
+    if (ps.reason === "cross-paragraph-range") {
+      return {
+        status: "range-invalid",
+        reason: "cross-paragraph-range",
+        from,
+        to,
+        storyLength,
+        fromBlockIndex: ps.fromBlockIndex ?? -1,
+        toBlockIndex: ps.toBlockIndex ?? -1,
+        message:
+          `createScopeFromAnchor refused: range [${from}, ${to}] straddles ` +
+          `paragraphs ${ps.fromBlockIndex} and ${ps.toBlockIndex}. Marker-backed ` +
+          `scopes only plant inside a single paragraph today. Narrow the range to ` +
+          `land inside one paragraph, or create two separate scopes.`,
+        nextStep: "narrow-to-single-paragraph",
+      };
+    }
+    if (ps.reason === "non-paragraph-target") {
+      return {
+        status: "range-invalid",
+        reason: "non-paragraph-target",
+        from,
+        to,
+        storyLength,
+        blockIndex: ps.blockIndex ?? -1,
+        blockKind: ps.blockKind ?? "unknown",
+        message:
+          `createScopeFromAnchor refused: range [${from}, ${to}] targets a ` +
+          `${ps.blockKind ?? "non-paragraph"} block (index ${ps.blockIndex}). ` +
+          `Marker scopes only plant inside paragraphs today. Pick a paragraph ` +
+          `target, or use runtime.workflow.createScope({blockId}) for ` +
+          `whole-block scopes on the containing structure.`,
+        nextStep: "pick-a-paragraph-target",
+      };
+    }
+    if (ps.reason === "range-out-of-bounds") {
+      // Shouldn't happen — storyLength was checked above — but surface
+      // it as a first-class failure in case the underlying length math
+      // drifts from our bounds check.
+      return {
+        status: "range-invalid",
+        reason: "range-exceeds-story-length",
+        from,
+        to,
+        storyLength: ps.storyLength ?? storyLength,
+        message:
+          `createScopeFromAnchor refused: coordinator reports range [${from}, ${to}] ` +
+          `is out of bounds (storyLength=${ps.storyLength}). This is usually a ` +
+          `stale-offset bug (KI-P9) — re-derive positions from the current ` +
+          `document and retry.`,
+        nextStep: "clamp-to-to-storyLength-or-pick-a-different-range",
+      };
+    }
+    // empty-document — target has no canonical blocks.
+    return {
+      status: "range-invalid",
+      reason: "empty-document",
+      from,
+      to,
+      storyLength,
+      message:
+        `createScopeFromAnchor refused: the target document has no blocks; ` +
+        `cannot plant scope markers. Open or initialize a document before ` +
+        `creating sub-block scopes.`,
+      nextStep: "initialize-document-before-creating-scopes",
+    };
+  }
+
   return { status: "created", scopeId: result.scopeId, anchor: result.anchor };
 }

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

@@ -199,6 +199,17 @@ export const editorSchema = new Schema({
         pageBreakBefore: { default: null },
         hiddenTextOnly: { default: null },
         placeholderCulled: { default: null },
+        /**
+         * Rendered height (in twips) of the block that this placeholder
+         * stands in for, supplied by `DocumentRuntime` from L04's page
+         * graph. When present on a `placeholderCulled` paragraph, `toDOM`
+         * emits a fixed-height `<div>` (`${twips/20}pt`) instead of the
+         * `min-height: 20px` fallback, eliminating the scroll-path
+         * "paragraphs jump around pagination gaps" flicker that occurred
+         * when blocks realized at real heights larger than one line.
+         * Null / undefined preserves the pre-existing 20 px minimum.
+         */
+        placeholderHeightTwips: { default: null },
         blockId: { default: null },
         /**
          * `<w:framePr>` projection from `SurfaceBlockFragment.frameProperties`
@@ -214,6 +225,11 @@ export const editorSchema = new Schema({
       toDOM(node) {
         // Viewport-culled placeholder paragraph — cheap size-preserving leaf.
         if (node.attrs.placeholderCulled) {
+          const heightTwips = node.attrs.placeholderHeightTwips as number | null;
+          const heightStyle =
+            typeof heightTwips === "number" && heightTwips > 0
+              ? `height: ${heightTwips / 20}pt`
+              : "min-height: 20px";
           return [
             "div",
             {
@@ -221,7 +237,10 @@ export const editorSchema = new Schema({
               "data-placeholder-culled": "true",
               "data-placeholder-size": String(node.nodeSize),
               "data-placeholder-block-id": node.attrs.blockId ?? "",
-              style: "min-height: 20px; contain: strict;",
+              ...(typeof heightTwips === "number" && heightTwips > 0
+                ? { "data-placeholder-height-twips": String(heightTwips) }
+                : {}),
+              style: `${heightStyle}; contain: strict;`,
               "aria-hidden": "true",
             },
             0,

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

@@ -867,10 +867,25 @@ function buildOpaqueBlock(
   const placeholderSize = block.placeholderSize ?? null;
   if (placeholderSize !== null) {
     const targetSize = placeholderSize as number;
+    // Flicker fix — when DocumentRuntime has enriched the placeholder with
+    // the block's known rendered height (from L04's page graph), thread it
+    // onto the paragraph node so `pm-schema.ts::toDOM` emits a fixed
+    // `height` style matching the real block. Without this, the placeholder
+    // renders at `min-height: 20px` and inflates to its real height when
+    // the block realizes on scroll, dragging content below the scroll
+    // pointer ("paragraphs jump around pagination gaps").
+    const placeholderHeightTwips = block.placeholderHeightTwips ?? null;
+    const placeholderAttrs: Record<string, unknown> = {
+      blockId: block.blockId,
+      placeholderCulled: true,
+    };
+    if (placeholderHeightTwips !== null) {
+      placeholderAttrs.placeholderHeightTwips = placeholderHeightTwips;
+    }
     if (targetSize <= 2) {
       // Edge case: bare empty paragraph claims exactly 2 positions.
       return editorSchema.nodes.paragraph.create(
-        { blockId: block.blockId, placeholderCulled: true },
+        placeholderAttrs,
         Fragment.empty,
       );
     }
@@ -878,7 +893,7 @@ function buildOpaqueBlock(
     // 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 },
+      placeholderAttrs,
       editorSchema.text(filler),
     );
   }