@beyondwork/docx-react-component 1.0.78 → 1.0.80

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

@@ -276,10 +276,15 @@ export type CreateScopeFromAnchorResult =
       readonly reason:
         | "from-negative"
         | "to-less-than-from"
-        | "range-exceeds-story-length";
+        | "range-exceeds-story-length"
+        | "non-paragraph-target"
+        | "empty-document";
       readonly from: number;
       readonly to: number;
       readonly storyLength: number;
+      /** Non-paragraph target only — the offending block's index and kind. */
+      readonly blockIndex?: number;
+      readonly blockKind?: string;
       /**
        * Single-sentence, agent-actionable explanation. Tells the caller
        * what the failure was and the concrete next step — no guesswork
@@ -291,7 +296,8 @@ export type CreateScopeFromAnchorResult =
        * Short machine-routable next-step hint for thin consumers that
        * don't want to pattern-match on `reason`. Examples:
        *   "clamp-from-to-zero", "swap-from-and-to",
-       *   "clamp-to-to-storyLength-or-pick-a-different-range".
+       *   "clamp-to-to-storyLength-or-pick-a-different-range",
+       *   "pick-a-paragraph-target".
        */
       readonly nextStep: string;
     };
@@ -420,5 +426,66 @@ export function createScopeFromAnchor(
     ...(scopeMetadataFields.length > 0 ? { scopeMetadataFields } : {}),
   });
 
+  // Pre-2026-04-24 the coordinator silently returned a minted scopeId
+  // 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 === "non-paragraph-target") {
+      return {
+        status: "range-invalid",
+        reason: "non-paragraph-target",
+        from,
+        to,
+        storyLength,
+        blockIndex: ps.blockIndex ?? -1,
+        blockKind: ps.blockKind ?? "unknown",
+        message:
+          `createScopeFromAnchor refused: range [${from}, ${to}] targets a ` +
+          `${ps.blockKind ?? "non-paragraph"} block (index ${ps.blockIndex}). ` +
+          `Marker scopes only plant inside paragraphs today. Pick a paragraph ` +
+          `target, or use runtime.workflow.createScope({blockId}) for ` +
+          `whole-block scopes on the containing structure.`,
+        nextStep: "pick-a-paragraph-target",
+      };
+    }
+    if (ps.reason === "range-out-of-bounds") {
+      // Shouldn't happen — storyLength was checked above — but surface
+      // it as a first-class failure in case the underlying length math
+      // drifts from our bounds check.
+      return {
+        status: "range-invalid",
+        reason: "range-exceeds-story-length",
+        from,
+        to,
+        storyLength: ps.storyLength ?? storyLength,
+        message:
+          `createScopeFromAnchor refused: coordinator reports range [${from}, ${to}] ` +
+          `is out of bounds (storyLength=${ps.storyLength}). This is usually a ` +
+          `stale-offset bug (KI-P9) — re-derive positions from the current ` +
+          `document and retry.`,
+        nextStep: "clamp-to-to-storyLength-or-pick-a-different-range",
+      };
+    }
+    // empty-document — target has no canonical blocks.
+    return {
+      status: "range-invalid",
+      reason: "empty-document",
+      from,
+      to,
+      storyLength,
+      message:
+        `createScopeFromAnchor refused: the target document has no blocks; ` +
+        `cannot plant scope markers. Open or initialize a document before ` +
+        `creating sub-block scopes.`,
+      nextStep: "initialize-document-before-creating-scopes",
+    };
+  }
+
   return { status: "created", scopeId: result.scopeId, anchor: result.anchor };
 }

package/src/ui/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/editor-surface/pm-schema.ts

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

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

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

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"] {