@beyondwork/docx-react-component 1.0.79 → 1.0.80

package/package.json

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

@@ -1211,6 +1211,18 @@ export type SurfaceInlineSegment =
        * is enforced by `test/runtime/formatting/production-boundary.test.ts`.
        */
       revisionDisplay?: {
+        /**
+         * Identity of the attached revision. Render consumers emit
+         * `data-revision-id` and route sidebar scroll-to-revision off
+         * this field rather than re-deriving from the review store.
+         */
+        revisionId: string;
+        /**
+         * The revision's kind. Mirrors `RevisionRecord.kind` on the
+         * canonical document. Render consumers branch on this (e.g.
+         * widget-bracket placement in suggestions mode).
+         */
+        kind: "insertion" | "deletion" | "formatting" | "move" | "property-change";
         markupMode: "clean" | "simple" | "all";
         hidden?: boolean;
         strikethrough?: boolean;
@@ -2517,23 +2529,20 @@ export interface AddScopeResult {
   /**
    * 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.
+   * typed reason when the plant was refused (non-paragraph target,
+   * out-of-bounds, empty-document). Cross-paragraph ranges plant
+   * successfully as of 2026-04-24 — see the multi-paragraph-scopes
+   * slice. 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;

package/src/api/v3/ai/resolve.ts

@@ -1,13 +1,19 @@
 /**
  * @endStateApi v3 — `ai.resolve` family.
  *
- * Slice 3 of refactor/08 graduates `resolveReference` to
- * `live-with-adapter` for the FOUR DETERMINISTIC hint kinds: `scope-id`,
- * `semantic-path`, `offset`, and `range`. Offset / range resolution now
- * honors precise nested-kind ranges (fields, table rows, table cells)
- * via the scope-compiler's specificity tie-breaker — see
- * `docs/architecture/08-semantic-scope-compiler.md` §"Resolve-reference
- * precision" for the specificity table.
+ * Slice 3 of refactor/08 graduated `resolveReference` to
+ * `live-with-adapter`. Post-KI-P9 (2026-04-24) the reference union
+ * carries **three durable reference kinds**: `scope-id`, `semantic-path`,
+ * and `natural-language`. Positional queries (`offset` / `range`) were
+ * split into `queryScopeAtPosition(at)` / `queryScopeInRange(from, to)`
+ * one-shot APIs that return `ScopeHandle | null` directly — the
+ * type-system split prevents a positional hint from being cached or
+ * round-tripped as a reference across a mutation.
+ *
+ * Offset / range lookups still honor precise nested-kind ranges (fields,
+ * table rows, table cells) via the scope-compiler's specificity
+ * tie-breaker — see `docs/architecture/08-semantic-scope-compiler.md`
+ * §"Resolve-reference precision" for the specificity table.
  *
  * The `natural-language` hint remains **partial by design**. The live
  * path is a deterministic substring matcher over:

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

@@ -161,14 +161,11 @@ export type CreateScopeFromAnchorResult =
         | "from-negative"
         | "to-less-than-from"
         | "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. */
@@ -540,12 +537,6 @@ 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 }
             : {}),

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

@@ -16,6 +16,10 @@ import type { CanonicalDocumentEnvelope } from "../state/editor-state.ts";
  * knowing whether the scope was ever live. Every non-`"planted"`
  * status is now typed so callers can discriminate + surface
  * agent-actionable recovery hints.
+ *
+ * Cross-paragraph ranges are first-class (planted) as of the
+ * 2026-04-24 multi-paragraph-scopes slice. The `cross-paragraph-range`
+ * failure variant no longer exists — markers now span paragraphs.
  */
 export type InsertScopeMarkersResult =
   | {
@@ -25,14 +29,6 @@ export type InsertScopeMarkersResult =
       /** 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;
@@ -60,13 +56,17 @@ export type InsertScopeMarkersResult =
  * pair of `scope_marker_start` / `scope_marker_end` inline nodes got
  * inserted at `[from, to]`.
  *
+ * Same-paragraph ranges insert both markers into the single owning
+ * paragraph. Cross-paragraph ranges place the start marker inside the
+ * paragraph containing `from` and the end marker inside the paragraph
+ * containing `to`; intermediate top-level blocks (paragraphs, tables,
+ * section breaks) are passed through unmodified and fall inside the
+ * scope by document order.
+ *
  * 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-target` — either `from` or `to` lands inside a
  *     non-paragraph block (table / SDT / section_break). Marker
- *     scopes only plant inside paragraphs today.
+ *     scopes only plant inside paragraphs.
  *   - `range-out-of-bounds` — `to` exceeds the main story length.
  *   - `empty-document` — the document has no root / no children.
  *
@@ -82,10 +82,10 @@ export function insertScopeMarkers(
     to: number;
   },
 ): InsertScopeMarkersResult {
-  const { scopeId, from, to } = params;
+  const { scopeId } = params;
   const root = document.content as DocumentRootNode;
-  const normalizedFrom = Math.min(from, to);
-  const normalizedTo = Math.max(from, to);
+  const normalizedFrom = Math.min(params.from, params.to);
+  const normalizedTo = Math.max(params.from, params.to);
 
   if (!root || root.type !== "doc" || root.children.length === 0) {
     return {
@@ -96,9 +96,15 @@ export function insertScopeMarkers(
     };
   }
 
-  // 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.
+  // Pre-pass — locate which block each of `from` and `to` resolves to,
+  // compute story length, and build per-paragraph slot envelopes.
+  // **Invariant:** the cursor arithmetic here MUST match
+  // `src/runtime/scopes/position-map.ts::computeBlockPositions`
+  // (same `inlineLength`, same `+1` per-block boundary). Layer 04
+  // cannot change one walker without the other or cross-paragraph
+  // marker insertion silently drifts vs. enumerated scope ranges.
+  type ParaSlot = { index: number; from: number; to: number };
+  const paraSlots: ParaSlot[] = [];
   let cursor = 0;
   let fromBlockIndex = -1;
   let fromBlockKind: string | null = null;
@@ -115,15 +121,24 @@ export function insertScopeMarkers(
         (total, child) => total + inlineLength(child as InlineNode),
         0,
       );
+      paraSlots.push({ index: i, from: blockFrom, to: blockFrom + blockLength });
     } else {
       blockLength = 1;
     }
     const blockTo = blockFrom + blockLength;
-    if (fromBlockIndex === -1 && normalizedFrom >= blockFrom && normalizedFrom <= blockTo) {
+    if (
+      fromBlockIndex === -1 &&
+      normalizedFrom >= blockFrom &&
+      normalizedFrom <= blockTo
+    ) {
       fromBlockIndex = i;
       fromBlockKind = block.type;
     }
-    if (toBlockIndex === -1 && normalizedTo >= blockFrom && normalizedTo <= blockTo) {
+    if (
+      toBlockIndex === -1 &&
+      normalizedTo >= blockFrom &&
+      normalizedTo <= blockTo
+    ) {
       toBlockIndex = i;
       toBlockKind = block.type;
     }
@@ -150,62 +165,81 @@ export function insertScopeMarkers(
       storyLength,
     };
   }
-  if (fromBlockIndex !== toBlockIndex) {
+  if (fromBlockKind !== "paragraph" || toBlockKind !== "paragraph") {
+    // Either endpoint lands on a non-paragraph top-level block
+    // (table / section_break / sdt). Report the first non-paragraph
+    // offender for diagnostic clarity.
+    const nonParaIndex =
+      fromBlockKind !== "paragraph" ? fromBlockIndex : toBlockIndex;
+    const nonParaKind =
+      fromBlockKind !== "paragraph" ? fromBlockKind : toBlockKind;
     return {
-      status: "cross-paragraph-range",
+      status: "non-paragraph-target",
       scopeId,
       from: normalizedFrom,
       to: normalizedTo,
-      fromBlockIndex,
-      toBlockIndex,
+      blockIndex: nonParaIndex,
+      blockKind: nonParaKind ?? "unknown",
     };
   }
-  if (fromBlockKind !== "paragraph") {
+
+  const startSlot = paraSlots.find((s) => s.index === fromBlockIndex)!;
+  const endSlot = paraSlots.find((s) => s.index === toBlockIndex)!;
+
+  // Same-paragraph fast path: inject both markers into one paragraph.
+  // Preserves all existing single-paragraph behaviour byte-for-byte
+  // (regression pin [C9]).
+  if (startSlot.index === endSlot.index) {
+    const newChildren = injectMarkersIntoInlineList(
+      (root.children[startSlot.index] as ParagraphNode).children as InlineNode[],
+      scopeId,
+      normalizedFrom - startSlot.from,
+      normalizedTo - startSlot.from,
+      "both",
+    );
+    const children = root.children.map((block, i) =>
+      i === startSlot.index
+        ? ({ ...block, children: newChildren } as ParagraphNode)
+        : block,
+    );
     return {
-      status: "non-paragraph-target",
+      status: "planted",
+      document: { ...document, content: { ...root, children } },
       scopeId,
-      from: normalizedFrom,
-      to: normalizedTo,
-      blockIndex: fromBlockIndex,
-      blockKind: fromBlockKind ?? "unknown",
+      plantedRange: { from: normalizedFrom, to: normalizedTo },
     };
   }
 
-  // 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;
+  // Cross-paragraph path — start marker goes in the start-bearing
+  // paragraph; end marker goes in the end-bearing paragraph;
+  // intermediate blocks pass through unchanged.
+  const children = root.children.map((block, i) => {
+    if (i === startSlot.index) {
+      const newChildren = injectMarkersIntoInlineList(
+        (block as ParagraphNode).children as InlineNode[],
+        scopeId,
+        normalizedFrom - startSlot.from,
+        Number.POSITIVE_INFINITY,
+        "start-only",
+      );
+      return { ...block, children: newChildren } as ParagraphNode;
     }
-    const paragraphFrom = cursor;
-    const paragraph = block as ParagraphNode;
-    const startOffset = normalizedFrom - paragraphFrom;
-    const endOffset = normalizedTo - paragraphFrom;
-    const newChildren = injectMarkersIntoInlineList(
-      paragraph.children as InlineNode[],
-      scopeId,
-      startOffset,
-      endOffset,
-    );
-    return { ...paragraph, children: newChildren };
+    if (i === endSlot.index) {
+      const newChildren = injectMarkersIntoInlineList(
+        (block as ParagraphNode).children as InlineNode[],
+        scopeId,
+        Number.NEGATIVE_INFINITY,
+        normalizedTo - endSlot.from,
+        "end-only",
+      );
+      return { ...block, children: newChildren } as ParagraphNode;
+    }
+    return block;
   });
 
   return {
     status: "planted",
-    document: {
-      ...document,
-      content: { ...root, children },
-    },
+    document: { ...document, content: { ...root, children } },
     scopeId,
     plantedRange: { from: normalizedFrom, to: normalizedTo },
   };
@@ -273,28 +307,28 @@ function injectMarkersIntoInlineList(
   scopeId: string,
   startOffset: number,
   endOffset: number,
+  mode: "both" | "start-only" | "end-only",
 ): InlineNode[] {
-  const start: ScopeMarkerStartNode = {
-    type: "scope_marker_start",
-    scopeId,
-  };
-  const end: ScopeMarkerEndNode = {
-    type: "scope_marker_end",
-    scopeId,
-  };
+  const start: ScopeMarkerStartNode = { type: "scope_marker_start", scopeId };
+  const end: ScopeMarkerEndNode = { type: "scope_marker_end", scopeId };
+
+  const needStart = mode === "both" || mode === "start-only";
+  const needEnd = mode === "both" || mode === "end-only";
 
   const output: InlineNode[] = [];
   let cursor = 0;
-  let startEmitted = false;
-  let endEmitted = false;
+  let startEmitted = !needStart;
+  let endEmitted = !needEnd;
 
   for (const node of inlines) {
     const length = inlineLength(node);
     const nodeStart = cursor;
     const nodeEnd = cursor + length;
 
-    const startInside = !startEmitted && startOffset >= nodeStart && startOffset <= nodeEnd;
-    const endInside = !endEmitted && endOffset >= nodeStart && endOffset <= nodeEnd;
+    const startInside =
+      needStart && !startEmitted && startOffset >= nodeStart && startOffset <= nodeEnd;
+    const endInside =
+      needEnd && !endEmitted && endOffset >= nodeStart && endOffset <= nodeEnd;
 
     if (!startInside && !endInside) {
       output.push(node);
@@ -302,10 +336,7 @@ function injectMarkersIntoInlineList(
       continue;
     }
 
-    // Currently only text nodes support splitting for an internal cut.
     if (node.type !== "text") {
-      // For non-text nodes, markers land at the node boundary closest to the
-      // target offset — avoids mid-atom splits which would corrupt the node.
       if (startInside && !startEmitted && startOffset <= nodeStart) {
         output.push(start);
         startEmitted = true;
@@ -330,11 +361,7 @@ function injectMarkersIntoInlineList(
     const text = node.text;
     const chars = Array.from(text);
     const marks = node.marks;
-    const pieces: {
-      cut: number;
-      emit: "start" | "end";
-    }[] = [];
-
+    const pieces: { cut: number; emit: "start" | "end" }[] = [];
     if (startInside) pieces.push({ cut: startOffset - nodeStart, emit: "start" });
     if (endInside) pieces.push({ cut: endOffset - nodeStart, emit: "end" });
     pieces.sort((a, b) => a.cut - b.cut || (a.emit === "start" ? -1 : 1));
@@ -370,12 +397,11 @@ function injectMarkersIntoInlineList(
     cursor = nodeEnd;
   }
 
-  // Append markers that were at the very end of the paragraph.
-  if (!startEmitted) {
+  if (needStart && !startEmitted) {
     output.push(start);
     startEmitted = true;
   }
-  if (!endEmitted) {
+  if (needEnd && !endEmitted) {
     output.push(end);
     endEmitted = true;
   }

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

@@ -110,6 +110,22 @@ export interface EffectiveFieldDisplay {
  * visual vocabulary (CSS class, inline style, decoration).
  */
 export interface RevisionDisplayFlags {
+  /**
+   * The attached revision's id. Enables render consumers to emit
+   * `data-revision-id` + route sidebar scroll-to-revision off the
+   * authoritative L03 flags rather than re-deriving from the review-store
+   * side channel. Present whenever `input.revision !== undefined` drove
+   * flag emission.
+   */
+  readonly revisionId: string;
+  /**
+   * The revision's kind. Mirrors `RevisionRecord.kind` from the canonical
+   * document (`src/model/canonical-document.ts`). Render consumers use
+   * this to branch on insertion/deletion/move/property-change variants
+   * (e.g. widget-bracket placement in suggestions mode) without reading
+   * the review store.
+   */
+  readonly kind: "insertion" | "deletion" | "formatting" | "move" | "property-change";
   readonly markupMode: "clean" | "simple" | "all";
   /** Hide the run entirely (e.g. open deletion in "clean" mode). */
   readonly hidden?: boolean;

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/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

@@ -824,12 +824,9 @@ export function createWorkflowCoordinator(deps: CoordinatorDeps): WorkflowCoordi
         plantStatus: {
           planted: false,
           reason: plantResult.status,
-          ...(plantResult.status === "cross-paragraph-range"
-            ? {
-                fromBlockIndex: plantResult.fromBlockIndex,
-                toBlockIndex: plantResult.toBlockIndex,
-              }
-            : {}),
+          // 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,

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

@@ -277,15 +277,11 @@ export type CreateScopeFromAnchorResult =
         | "from-negative"
         | "to-less-than-from"
         | "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;
@@ -301,7 +297,6 @@ export type CreateScopeFromAnchorResult =
        * 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",
-       *   "narrow-to-single-paragraph",
        *   "pick-a-paragraph-target".
        */
       readonly nextStep: string;
@@ -432,31 +427,15 @@ export function createScopeFromAnchor(
   });
 
   // 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
+  // even when insertScopeMarkers refused to plant (non-paragraph
+  // target, out-of-bounds after the story-length check passed).
+  // Cross-paragraph ranges now plant successfully (2026-04-24
+  // multi-paragraph-scopes slice), so that refusal variant is retired.
+  // Remaining reasons translate 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",

package/src/ui/headless/revision-decoration-model.ts

@@ -155,6 +155,16 @@ export function getRevisionRangeState(
  * by `test/runtime/formatting/production-boundary.test.ts`.
  */
 export interface RevisionDisplayFlags {
+  /**
+   * Identity of the attached revision. Mirrors
+   * `SurfaceInlineSegment.revisionDisplay.revisionId`.
+   */
+  revisionId: string;
+  /**
+   * Mirrors `RevisionRecord.kind`. Consumers branch on insertion /
+   * deletion variants without reading the review store.
+   */
+  kind: "insertion" | "deletion" | "formatting" | "move" | "property-change";
   markupMode: "clean" | "simple" | "all";
   hidden?: boolean;
   strikethrough?: boolean;

package/src/ui-tailwind/theme/editor-theme.css

@@ -1075,7 +1075,16 @@
 }
 
 .wre-page-band:hover {
-  background-color: color-mix(in srgb, var(--color-bg-muted) 80%, var(--color-surface));
+  /*
+   * N3 audit (2026-04-24): the prior `color-mix(bg-muted 80%, surface 20%)`
+   * blended two near-adjacent tokens — in dark mode (#17211C vs #182420)
+   * the result moved ≤2 RGB units from the base, leaving no visible
+   * hover affordance. `--color-bg-hover` is the token the design system
+   * already dedicates to this signal (light #EAF6EF vs muted #F7FAF8;
+   * dark #21342A vs muted #17211C) and resolves the dark-mode legibility
+   * gap without regressing light-mode subtlety.
+   */
+  background-color: var(--color-bg-hover);
 }
 
 .wre-page-band[data-active="true"] {