@beyondwork/docx-react-component 1.0.78 → 1.0.80

package/src/runtime/formatting/revision-display.ts

@@ -44,16 +44,16 @@ export function applyRevisionDisplay(
   switch (markupMode) {
     case "clean": {
       if (revision.kind === "deletion" && revision.status === "open") {
-        return buildFlags(markupMode, authorColor, { hidden: true });
+        return buildFlags(revision, markupMode, authorColor, { hidden: true });
       }
-      return buildFlags(markupMode, authorColor);
+      return buildFlags(revision, markupMode, authorColor);
     }
 
     case "simple": {
       // Content visible, de-emphasized. No strikethrough / underline
       // markers — the consumer renders a muted style (opacity /
       // secondary color) uniformly.
-      return buildFlags(markupMode, authorColor, { deemphasize: true });
+      return buildFlags(revision, markupMode, authorColor, { deemphasize: true });
     }
 
     case "all": {
@@ -65,18 +65,18 @@ export function applyRevisionDisplay(
           // add the revision strikethrough flag — avoids double-struck
           // glyphs in render.
           if (run.strikethrough === true) {
-            return buildFlags(markupMode, authorColor);
+            return buildFlags(revision, markupMode, authorColor);
           }
-          return buildFlags(markupMode, authorColor, { strikethrough: true });
+          return buildFlags(revision, markupMode, authorColor, { strikethrough: true });
         }
         case "insertion": {
           // Mirror short-circuit for insertions. If the run already carries
           // a single-underline via direct formatting, skip the insertion
           // underline so the render doesn't over-paint.
           if (run.underline === "single") {
-            return buildFlags(markupMode, authorColor);
+            return buildFlags(revision, markupMode, authorColor);
           }
-          return buildFlags(markupMode, authorColor, { insertionUnderline: true });
+          return buildFlags(revision, markupMode, authorColor, { insertionUnderline: true });
         }
         case "formatting":
         case "property-change":
@@ -84,20 +84,26 @@ export function applyRevisionDisplay(
           // Paragraph-level markers (change-bar, move-from/to arrows) are
           // owned by the paragraph projection. For runs that carry these
           // revision kinds, fall through to the author-color-only posture.
-          return buildFlags(markupMode, authorColor);
+          return buildFlags(revision, markupMode, authorColor);
         }
       }
-      return buildFlags(markupMode, authorColor);
+      return buildFlags(revision, markupMode, authorColor);
     }
   }
 }
 
 function buildFlags(
+  revision: RevisionRecord,
   markupMode: RevisionMarkupMode,
   authorColor: string | undefined,
-  extras: Omit<RevisionDisplayFlags, "markupMode" | "authorColor"> = {},
+  extras: Omit<
+    RevisionDisplayFlags,
+    "revisionId" | "kind" | "markupMode" | "authorColor"
+  > = {},
 ): RevisionDisplayFlags {
   return {
+    revisionId: revision.changeId,
+    kind: revision.kind,
     markupMode,
     ...(authorColor !== undefined ? { authorColor } : {}),
     ...extras,

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/scopes/compile-scope-bundle.ts

@@ -18,7 +18,11 @@ import type {
   WorkflowOverlay,
 } from "./_scope-dependencies.ts";
 
-import { buildParagraphIndexMap, compileScope } from "./compile-scope.ts";
+import {
+  buildParagraphIndexMap,
+  buildSectionIndexByBlockIndex,
+  compileScope,
+} from "./compile-scope.ts";
 import type { EnumeratedScope } from "./enumerate-scopes.ts";
 import { enumerateScopes } from "./enumerate-scopes.ts";
 import { composeEvidence } from "./evidence.ts";
@@ -157,6 +161,10 @@ export function compileScopeBundleById(
     ...(fullDoc ? { document: fullDoc } : {}),
     ...(inputs.overlay !== undefined ? { overlay: inputs.overlay } : {}),
     paragraphIndexByBlockIndex: buildParagraphIndexMap(inputs.document),
+    // Thread the section-index map up-front so the `kind: "scope"` compile
+    // arm does not re-walk the document. Shared between dispatch + the
+    // `paragraph`/`heading`/`list-item` + `scope` kinds that read it.
+    sectionIndexByBlockIndex: buildSectionIndexByBlockIndex(inputs.document),
   });
   if (!compiled) return null;
   return compileScopeBundle(compiled, { ...inputs, scopes });

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

@@ -61,6 +61,7 @@ import { compileHeadingScope } from "./scope-kinds/heading.ts";
 import { compileListItemScope } from "./scope-kinds/list-item.ts";
 import { compileParagraphScope } from "./scope-kinds/paragraph.ts";
 import { compileRevisionScope } from "./scope-kinds/revision.ts";
+import { compileScopeKind } from "./scope-kinds/scope.ts";
 import { compileTableScope } from "./scope-kinds/table.ts";
 import { compileTableCellScope } from "./scope-kinds/table-cell.ts";
 import { compileTableRowScope } from "./scope-kinds/table-row.ts";
@@ -256,6 +257,21 @@ export function compileScope(
       return compileCommentThreadScope(entry);
     case "revision":
       return compileRevisionScope(entry);
+    case "scope": {
+      if (!options.document) return null;
+      let scopeSectionMap = options.sectionIndexByBlockIndex;
+      if (!scopeSectionMap) {
+        scopeSectionMap = buildSectionIndexByBlockIndex(options.document);
+      }
+      const scopeSectionIndex = scopeSectionMap.get(entry.startBlockIndex);
+      return compileScopeKind(entry, {
+        document: options.document,
+        ...(workflow ? { workflow } : {}),
+        ...(typeof scopeSectionIndex === "number"
+          ? { sectionIndex: scopeSectionIndex }
+          : {}),
+      });
+    }
     default:
       return null;
   }

package/src/runtime/scopes/enumerate-scopes.ts

@@ -121,11 +121,29 @@ export interface RevisionEnumeratedScope {
   readonly classifications: readonly string[];
 }
 
+/**
+ * Marker-backed scope whose start + end markers live in different
+ * top-level paragraphs. The reserved `"scope"` kind slot in the 13-kind
+ * taxonomy (`SemanticScopeKind`) exists to carry these cross-paragraph
+ * pairs without forcing them through the paragraph arm — the
+ * start-bearing paragraph continues to enumerate as `kind: "paragraph"`
+ * + `provenance: "derived"`, and this entry represents the pair as a
+ * whole.
+ */
+export interface ScopeEnumeratedScope {
+  readonly kind: "scope";
+  readonly handle: ScopeHandle;
+  readonly startBlockIndex: number;
+  readonly endBlockIndex: number;
+  readonly classifications: readonly string[];
+}
+
 /**
  * Discriminated by `kind`. Paragraph-bearing entries carry `paragraph`;
  * table-bearing entries carry the matching canonical node; field entries
  * carry the inline `FieldNode` + containing paragraph; review-store
- * entries carry the thread / revision record directly.
+ * entries carry the thread / revision record directly; multi-paragraph
+ * marker pairs carry the pair of block indices.
  */
 export type EnumeratedScope =
   | ParagraphLikeEnumeratedScope
@@ -134,7 +152,8 @@ export type EnumeratedScope =
   | TableCellEnumeratedScope
   | FieldEnumeratedScope
   | CommentThreadEnumeratedScope
-  | RevisionEnumeratedScope;
+  | RevisionEnumeratedScope
+  | ScopeEnumeratedScope;
 
 export interface EnumerateScopesInputs {
   readonly overlay?: WorkflowOverlay | null;
@@ -424,6 +443,57 @@ function enumerateRevisions(
   });
 }
 
+/**
+ * Pre-pass: for each paired marker across multiple paragraphs, return
+ * { scopeId, startBlockIndex, endBlockIndex }. Same-paragraph pairs are
+ * NOT returned here — they continue to enumerate through the paragraph
+ * arm as `kind: "paragraph"` + `provenance: "marker-backed"`. An
+ * unmatched marker (only start or only end in the doc) is skipped here;
+ * detachment reporting lives in `resolveScope`, not in enumeration.
+ */
+function locateMultiParagraphMarkerPairs(
+  root: DocumentRootNode,
+): Array<{ scopeId: string; startBlockIndex: number; endBlockIndex: number }> {
+  type Open = { scopeId: string; blockIndex: number };
+  const open = new Map<string, Open>();
+  const pairs: Array<{
+    scopeId: string;
+    startBlockIndex: number;
+    endBlockIndex: number;
+  }> = [];
+  for (let i = 0; i < root.children.length; i += 1) {
+    const block = root.children[i];
+    if (!block || block.type !== "paragraph") continue;
+    for (const child of block.children) {
+      if (child.type === "scope_marker_start") {
+        open.set(child.scopeId, { scopeId: child.scopeId, blockIndex: i });
+      } else if (child.type === "scope_marker_end") {
+        const opener = open.get(child.scopeId);
+        if (!opener) continue;
+        if (opener.blockIndex !== i) {
+          pairs.push({
+            scopeId: child.scopeId,
+            startBlockIndex: opener.blockIndex,
+            endBlockIndex: i,
+          });
+        }
+        open.delete(child.scopeId);
+      }
+    }
+  }
+  // Pairs are pushed in close-order by the walk above — for nested or
+  // partially-overlapping pairs the inner/earlier-closing pair appears
+  // first. Sort by startBlockIndex (break ties on scopeId) so downstream
+  // consumers see entries in document order, and S3 determinism is
+  // explicit in the sort rather than implicit in walk timing.
+  pairs.sort(
+    (a, b) =>
+      a.startBlockIndex - b.startBlockIndex ||
+      a.scopeId.localeCompare(b.scopeId),
+  );
+  return pairs;
+}
+
 export function enumerateScopes(
   document: Pick<CanonicalDocument, "content" | "docId" | "review"> | CanonicalDocumentEnvelope,
   inputs: EnumerateScopesInputs = {},
@@ -436,6 +506,10 @@ export function enumerateScopes(
   const documentId = (envelope.docId as unknown as string) ?? "";
   const classificationIndex = buildClassificationIndex(inputs.overlay);
   const knownOverlayScopeIds = new Set(classificationIndex.keys());
+  const multiParagraphPairs = locateMultiParagraphMarkerPairs(root);
+  const multiParagraphScopeIds = new Set(
+    multiParagraphPairs.map((p) => p.scopeId),
+  );
 
   const results: EnumeratedScope[] = [];
   for (let index = 0; index < root.children.length; index += 1) {
@@ -443,10 +517,19 @@ export function enumerateScopes(
     if (!block) continue;
 
     if (block.type === "paragraph") {
-      const markerScopeId = paragraphFirstMarkerStart(
+      const rawMarkerScopeId = paragraphFirstMarkerStart(
         block,
         knownOverlayScopeIds,
       );
+      // Multi-paragraph pairs are emitted below as kind: "scope" and
+      // must NOT also promote their start-bearing paragraph to
+      // marker-backed — the paragraph stays derived and the separate
+      // `scope` entry represents the pair as a whole.
+      const markerScopeId =
+        rawMarkerScopeId !== null &&
+        !multiParagraphScopeIds.has(rawMarkerScopeId)
+          ? rawMarkerScopeId
+          : null;
       const kind = detectParagraphKind(block);
       const semanticPath = buildParagraphSemanticPath(kind, index, block);
       const scopeId =
@@ -587,6 +670,36 @@ export function enumerateScopes(
     }
   }
 
+  // Cross-paragraph marker pairs — emit one `kind: "scope"` entry per
+  // pair, ordered by start-block index (preserving document order and
+  // S3 determinism across compiles).
+  for (const pair of multiParagraphPairs) {
+    const semanticPath = ["body", "scope", pair.scopeId];
+    const hint = stableRefHintForScopeId(pair.scopeId, inputs.overlay);
+    const stableRef: ScopeHandle["stableRef"] =
+      hint === "semantic-path"
+        ? { kind: "semantic-path", value: semanticPath.join("/") }
+        : { kind: "scope-id", value: pair.scopeId };
+    const handle: ScopeHandle = {
+      scopeId: pair.scopeId,
+      documentId,
+      storyTarget: MAIN_STORY,
+      semanticPath,
+      stableRef,
+      provenance: "marker-backed",
+      rangePrecision: "marker-backed",
+    };
+    const classifications =
+      classificationIndex.get(pair.scopeId) ?? Object.freeze<string[]>([]);
+    results.push({
+      kind: "scope",
+      handle,
+      startBlockIndex: pair.startBlockIndex,
+      endBlockIndex: pair.endBlockIndex,
+      classifications,
+    } satisfies ScopeEnumeratedScope);
+  }
+
   // Review-store scopes — threads + revisions — enumerate after document
   // walk so their block ordering in `results` stays stable (all block scopes
   // first, then review).

package/src/runtime/scopes/replaceability.ts

@@ -47,6 +47,22 @@ export function deriveReplaceability(
       reason: "marker-backed-preserves-anchor",
     };
   }
+  // Multi-paragraph marker-backed scopes — the `scope` kind slot. Replace
+  // semantics across multiple blocks are not yet compiler-backed; callers
+  // may read but should not full-replace until Task N of the
+  // multi-paragraph plan wires block-granular replacement.
+  if (kind === "scope") {
+    if (provenance === "marker-backed") {
+      return {
+        level: "preserve-only",
+        reason: "multi-paragraph-replace-not-implemented",
+      };
+    }
+    return {
+      level: "blocked",
+      reason: "scope-kind-requires-markers",
+    };
+  }
   switch (kind) {
     case "paragraph":
       return { level: "full", reason: "derived-default" };

package/src/runtime/scopes/replacement/apply.ts

@@ -199,10 +199,20 @@ export function applyScopeReplacement(
       resolvedScope.kind === "paragraph" ||
       resolvedScope.kind === "heading" ||
       resolvedScope.kind === "list-item";
+    // Multi-paragraph `scope` kind (Task 7 of the 2026-04-24 plan): the
+    // compiler has no replacement lowering for cross-paragraph marker
+    // spans yet. Replaceability already declares `preserve-only` with
+    // `reason: "multi-paragraph-replace-not-implemented"`; apply mirrors
+    // that reason into the refusal taxonomy suffix so consumers reading
+    // `blockers[0]` / `reason` see the actionable sub-reason directly
+    // (rather than the bare `compile-refused:scope`). Grammar matches
+    // §10 `compile-refused:<kind>:<sub-reason>` (74a45eaf, 2026-04-23).
     const blocker =
-      paragraphLike && proposed.operation !== "replace"
-        ? `compile-refused:${resolvedScope.kind}:operation-not-implemented:${proposed.operation}`
-        : `compile-refused:${resolvedScope.kind}`;
+      resolvedScope.kind === "scope"
+        ? "compile-refused:scope:multi-paragraph-replace-not-implemented"
+        : paragraphLike && proposed.operation !== "replace"
+          ? `compile-refused:${resolvedScope.kind}:operation-not-implemented:${proposed.operation}`
+          : `compile-refused:${resolvedScope.kind}`;
     const refused: ValidationResult = {
       safe: false,
       blockedReasons: Object.freeze([blocker]),

package/src/runtime/scopes/resolve-reference.ts

@@ -307,6 +307,11 @@ function extractNLHaystack(entry: EnumeratedScope): string {
     case "revision":
       return `${entry.revision.kind} ${entry.revision.authorId ?? ""}`
         .toLowerCase();
+    case "scope":
+      // Cross-paragraph marker pair — no inline text of its own;
+      // semantic-path matching (`body/scope/<id>`) covers it, and the
+      // per-paragraph entries inside the pair carry their own haystacks.
+      return "";
     default: {
       const _never: never = entry;
       void _never;

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

@@ -0,0 +1,87 @@
+/**
+ * Compile `kind: "scope"` entries — multi-paragraph marker-backed scopes.
+ *
+ * Aggregates the spanning paragraphs' text into `content.text` (joined by
+ * `\n`), projects a bounded formatting summary (no single paragraphStyleId
+ * is authoritative across multiple paragraphs; we surface none), and stays
+ * `partial: true` because layout + geometry projections are not yet
+ * compiler-backed for multi-block scopes.
+ *
+ * Replaceability is `"preserve-only"` for now — see
+ * `replaceability.ts::deriveReplaceability`.
+ *
+ * Determinism (S3): pure projection of (spanning paragraphs' text,
+ * classifications, provenance, sectionIndex). No ambient state.
+ */
+
+import type {
+  CanonicalDocument,
+  DocumentRootNode,
+  ParagraphNode,
+} from "../../../model/canonical-document.ts";
+import type { CanonicalDocumentEnvelope } from "../../../core/state/editor-state.ts";
+import type { ScopeEnumeratedScope } from "../enumerate-scopes.ts";
+import { deriveReplaceability } from "../replaceability.ts";
+import type {
+  SemanticScope,
+  SemanticScopeWorkflow,
+} from "../semantic-scope-types.ts";
+
+import { extractParagraphText, buildExcerpt } from "./_paragraph-text.ts";
+
+export interface CompileScopeKindOptions {
+  readonly document: CanonicalDocument | CanonicalDocumentEnvelope;
+  readonly workflow?: SemanticScopeWorkflow;
+  /**
+   * 0-based section index of the scope's **first** spanning block
+   * (matches paragraph-kind semantics; agents reading layout.sectionIndex
+   * for routing get the scope's home section).
+   */
+  readonly sectionIndex?: number;
+}
+
+export function compileScopeKind(
+  entry: ScopeEnumeratedScope,
+  options: CompileScopeKindOptions,
+): SemanticScope {
+  const envelope = options.document as CanonicalDocumentEnvelope;
+  const root: DocumentRootNode =
+    "content" in envelope
+      ? (envelope.content as DocumentRootNode)
+      : (options.document as unknown as DocumentRootNode);
+
+  const texts: string[] = [];
+  for (let i = entry.startBlockIndex; i <= entry.endBlockIndex; i += 1) {
+    const block = root.children[i];
+    if (!block || block.type !== "paragraph") continue;
+    texts.push(extractParagraphText(block as ParagraphNode));
+  }
+  const text = texts.join("\n");
+
+  return {
+    handle: entry.handle,
+    kind: "scope",
+    classifications: entry.classifications,
+    content: {
+      text,
+      excerpt: buildExcerpt(text),
+    },
+    formatting: {},
+    layout:
+      typeof options.sectionIndex === "number"
+        ? { sectionIndex: options.sectionIndex }
+        : {},
+    geometry: {},
+    workflow: options.workflow ?? { scopeIds: [], effectiveMode: "edit" },
+    replaceability: deriveReplaceability("scope", entry.handle.provenance),
+    audit: {
+      source: "runtime",
+      derivedFrom:
+        entry.classifications.length > 0
+          ? ["canonical", "workflow-overlay"]
+          : ["canonical"],
+      confidence: "medium",
+    },
+    partial: true,
+  };
+}

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

@@ -165,6 +165,17 @@ export function resolveScopeRange(
       return anchorToRange(entry.thread.anchor);
     case "revision":
       return anchorToRange(entry.revision.anchor);
+    case "scope": {
+      // Cross-paragraph marker pair. The marker-range lookup at the top
+      // of this function (stableRef.kind === "scope-id") normally wins
+      // first. This branch handles the case where the handle's stableRef
+      // was overridden to `semantic-path` via the `stableRefHint` seam —
+      // we fall back to spanning the start-block low to end-block high.
+      const startRange = positionMap.blocks.get(entry.startBlockIndex);
+      const endRange = positionMap.blocks.get(entry.endBlockIndex);
+      if (!startRange || !endRange) return null;
+      return { from: startRange.from, to: endRange.to };
+    }
     default: {
       const never: never = entry;
       void never;

package/src/runtime/workflow/coordinator.ts

@@ -791,19 +791,69 @@ 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,
+          // Cross-paragraph ranges now plant successfully (2026-04-24
+          // multi-paragraph-scopes slice) — that refusal variant is
+          // retired. Remaining failure reasons carry diagnostic fields:
+          ...(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