@beyondwork/docx-react-component 1.0.79 → 1.0.81

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/WordReviewEditor.tsx

@@ -186,6 +186,7 @@ import { EditorShellView } from "./editor-shell-view.tsx";
 import { TwDebugPresentation } from "../ui-tailwind/debug/index.ts";
 import { shellPasteFragmentParser as SHELL_PASTE_FRAGMENT_PARSER } from "../shell/paste-adapter.ts";
 import { EditorSurfaceController } from "./editor-surface-controller.tsx";
+import type { EditorActionHostCallbacks } from "../ui-tailwind/chrome/editor-action-registry";
 import type { TwWorkspaceChromeHostController } from "../ui-tailwind/chrome/tw-workspace-chrome-host";
 import {
   resolveChromePreset,
@@ -3306,6 +3307,63 @@ export const WordReviewEditor = forwardRef<WordReviewEditorRef, WordReviewEditor
       },
     });
 
+    const productEditorActionHost = useMemo<EditorActionHostCallbacks>(() => {
+      const runClipboardCommand = (command: "copy" | "cut") => {
+        try {
+          globalThis.document?.execCommand?.(command);
+        } catch {
+          // Browser-native clipboard commands are best-effort fallbacks.
+        }
+      };
+
+      const defaultHost: EditorActionHostCallbacks = {
+        onUndo: commands.onUndo,
+        onRedo: commands.onRedo,
+        onCut: () => runClipboardCommand("cut"),
+        onCopy: () => runClipboardCommand("copy"),
+        onPaste: () => {
+          const readText = globalThis.navigator?.clipboard?.readText;
+          if (typeof readText !== "function") return;
+          void readText.call(globalThis.navigator.clipboard)
+            .then((text: string) => {
+              if (!text) return;
+              dispatchTextCommand(
+                activeRuntime,
+                { type: "insert-text", text },
+                DISPATCH_CONTEXT,
+              );
+            })
+            .catch(() => {
+              // Clipboard permission failures should not break the menu.
+            });
+        },
+        onToggleBold: commands.onToggleBold,
+        onToggleItalic: commands.onToggleItalic,
+        onToggleUnderline: commands.onToggleUnderline,
+        onToggleStrikethrough: commands.onToggleStrikethrough,
+        onToggleBulletedList: commands.onToggleBulletedList,
+        onToggleNumberedList: commands.onToggleNumberedList,
+        onOutdent: commands.onOutdent,
+        onIndent: commands.onIndent,
+        onSetAlignment: (alignment) => commands.onSetAlignment?.(alignment),
+        onInsertTable: commands.onInsertTable,
+        onAddComment: commands.onAddComment,
+        onInsertRowAbove: commands.onAddRowBefore,
+        onInsertRowBelow: commands.onAddRowAfter,
+        onInsertColumnBefore: commands.onAddColumnBefore,
+        onInsertColumnAfter: commands.onAddColumnAfter,
+        onDeleteRow: commands.onDeleteRow,
+        onDeleteColumn: commands.onDeleteColumn,
+        onDeleteTable: commands.onDeleteTable,
+        onMergeCells: commands.onMergeCells,
+        onSplitCell: commands.onSplitCell,
+      };
+
+      return editorActionHost
+        ? { ...defaultHost, ...editorActionHost }
+        : defaultHost;
+    }, [activeRuntime, commands, editorActionHost]);
+
     const harnessShowUnsupportedPreviews = readHarnessDebugPortsFlag(__harnessDebugPorts, "unsupportedObjectPreviews");
     const effectiveShowUnsupportedPreviews = computeEffectiveShowUnsupportedPreviews({
       harnessShowUnsupportedPreviews,
@@ -3342,7 +3400,7 @@ export const WordReviewEditor = forwardRef<WordReviewEditorRef, WordReviewEditor
         activeWorkflowScopeIds={workflowScopeSnapshot?.activeWorkItem?.scopeIds ?? []}
         workflowMetadata={workflowMarkupSnapshot?.metadata}
         onSelectionToolbarAnchorChange={handleSelectionToolbarAnchorChange}
-        {...(editorActionHost ? { onContextMenuRequested: handleContextMenuRequested } : {})}
+        onContextMenuRequested={handleContextMenuRequested}
         {...editorCallbacks}
         dispatchRuntimeCommand={(command) =>
           activeRuntime.applyActiveStoryTextCommand(command as never)
@@ -3420,8 +3478,9 @@ export const WordReviewEditor = forwardRef<WordReviewEditorRef, WordReviewEditor
         interactionGuardSnapshot={interactionGuardSnapshot}
         chromePreset={effectiveChromePreset}
         chromeOptions={chromeOptions}
-        {...(editorActionHost ? { editorActionHost } : {})}
-        {...(editorActionHost ? { chromeControllerRef: teedChromeControllerRef } : {})}
+        density={density}
+        editorActionHost={productEditorActionHost}
+        chromeControllerRef={teedChromeControllerRef}
         {...(commandPaletteDisabled !== undefined
           ? { commandPaletteDisabled }
           : {})}

package/src/ui/editor-shell-view.tsx

@@ -83,6 +83,7 @@ export interface EditorShellViewProps {
   interactionGuardSnapshot?: InteractionGuardSnapshot;
   chromePreset?: WordReviewEditorChromePreset;
   chromeOptions?: Partial<WordReviewEditorChromeOptions>;
+  density?: "compact" | "standard" | "comfortable";
   editorActionHost?: import("../ui-tailwind/chrome/editor-action-registry.ts").EditorActionHostCallbacks;
   chromeControllerRef?: React.Ref<
     import("../ui-tailwind/chrome/tw-workspace-chrome-host.tsx").TwWorkspaceChromeHostController

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;