@beyondwork/docx-react-component 1.0.41 → 1.0.43

package/src/ui-tailwind/chrome-overlay/tw-scope-rail-layer.tsx

@@ -77,6 +77,7 @@ const POSTURE_STYLES: Record<ScopeRailPosture, PostureStyle> = {
 const DEFAULT_RAIL_LANE_PX = 44;
 const STRIPE_WIDTH_PX = 4;
 const LABEL_WIDTH_PX = 40;
+const STACK_OFFSET_PX = 6;
 
 export const TwScopeRailLayer: React.FC<TwScopeRailLayerProps> = ({
   facet,
@@ -96,6 +97,27 @@ export const TwScopeRailLayer: React.FC<TwScopeRailLayerProps> = ({
     return null;
   }
 
+  // P2: which scopes currently have a `source: "ai"` candidate
+  // overlapping — drives the agent-pending shimmer class on their
+  // tints.  Reads from the facet's card-model projection so the
+  // shimmer logic lives in the runtime, not the overlay.
+  const cardModels =
+    typeof facet.getAllScopeCardModels === "function"
+      ? facet.getAllScopeCardModels()
+      : [];
+  const agentPendingByScope = new Map<string, boolean>();
+  for (const model of cardModels) {
+    if (model.agentPending) {
+      agentPendingByScope.set(model.scopeId, true);
+    }
+  }
+
+  // P3c: stack offsets for overlapping scopes.  Two scopes whose
+  // offset ranges intersect on the same page render as stacked
+  // stripes in the gutter; the inner stripe shifts STACK_OFFSET_PX
+  // further right per overlap count so all are clickable.
+  const stackIndexByScope = computeStackIndices(segments);
+
   const projectorSpace: OverlayCoordinateSpace = space ?? { originLeftPx: 0, originTopPx: 0 };
 
   return (
@@ -121,14 +143,20 @@ export const TwScopeRailLayer: React.FC<TwScopeRailLayerProps> = ({
         const stripeTopPx = firstLine.topPx;
         const stripeHeightPx =
           lastLine.topPx + lastLine.heightPx - firstLine.topPx;
+        const stackIndex = stackIndexByScope.get(segment.scopeId) ?? 0;
+        const stackOffset = stackIndex * STACK_OFFSET_PX;
         const stripeRect: RenderFrameRect = {
-          leftPx: firstLine.leftPx - railLaneWidthPx + (railLaneWidthPx - STRIPE_WIDTH_PX) / 2,
+          leftPx:
+            firstLine.leftPx
+              - railLaneWidthPx
+              + (railLaneWidthPx - STRIPE_WIDTH_PX) / 2
+              + stackOffset,
           topPx: stripeTopPx,
           widthPx: STRIPE_WIDTH_PX,
           heightPx: Math.max(stripeHeightPx, 14),
         };
         const labelRect: RenderFrameRect = {
-          leftPx: firstLine.leftPx - railLaneWidthPx,
+          leftPx: firstLine.leftPx - railLaneWidthPx + stackOffset,
           topPx: stripeTopPx,
           widthPx: LABEL_WIDTH_PX,
           heightPx: 20,
@@ -148,18 +176,28 @@ export const TwScopeRailLayer: React.FC<TwScopeRailLayerProps> = ({
         return (
           <React.Fragment key={`${segment.scopeId}:${segment.pageIndex}:${segment.fromOffset}`}>
             {/* Per-line tint behind the scoped text runs. */}
-            {lineRects.map((lineRect, index) => (
-              <div
-                key={`tint:${index}`}
-                className={`wre-scope-rail-tint wre-scope-rail-tint-${style.tintToken} ${
-                  isActive ? "wre-scope-rail-tint-active" : ""
-                }`}
-                data-scope-id={segment.scopeId}
-                data-posture={segment.posture}
-                data-line-index={index}
-                style={projectRectToOverlay(lineRect, projectorSpace)}
-              />
-            ))}
+            {lineRects.map((lineRect, index) => {
+              const agentPending = agentPendingByScope.get(segment.scopeId) === true;
+              const tintClassList = [
+                "wre-scope-rail-tint",
+                `wre-scope-rail-tint-${style.tintToken}`,
+              ];
+              if (isActive) tintClassList.push("wre-scope-rail-tint-active");
+              if (agentPending) {
+                tintClassList.push("wre-scope-rail-tint-agent-pending");
+              }
+              return (
+                <div
+                  key={`tint:${index}`}
+                  className={tintClassList.join(" ")}
+                  data-scope-id={segment.scopeId}
+                  data-posture={segment.posture}
+                  data-line-index={index}
+                  data-agent-pending={agentPending ? "true" : undefined}
+                  style={projectRectToOverlay(lineRect, projectorSpace)}
+                />
+              );
+            })}
             {/* Rail stripe in the gutter. */}
             <button
               type="button"
@@ -168,6 +206,7 @@ export const TwScopeRailLayer: React.FC<TwScopeRailLayerProps> = ({
               }`}
               data-scope-id={segment.scopeId}
               data-posture={segment.posture}
+              data-stack-index={stackIndex}
               data-testid="scope-rail-stripe"
               aria-label={`${style.labelText}${segment.label ? `: ${segment.label}` : ""}`}
               aria-expanded={isActive ? "true" : "false"}
@@ -246,4 +285,44 @@ function pushRectsFromPage(
   }
 }
 
+/**
+ * P3c: Compute a stack index per scope so overlapping scopes render
+ * as offset stripes in the gutter instead of stacking on top of each
+ * other.  For each scope's first segment, count earlier-document-
+ * order scopes whose offset range intersects on the same page — that
+ * count is the stack index (0 = outer / earliest, 1 = next, etc).
+ *
+ * Exported for unit testing.
+ */
+export function computeStackIndices(
+  segments: readonly ScopeRailSegment[],
+): Map<string, number> {
+  const firstSegmentByScope = new Map<string, ScopeRailSegment>();
+  const scopeOrder: string[] = [];
+  for (const segment of segments) {
+    if (!firstSegmentByScope.has(segment.scopeId)) {
+      firstSegmentByScope.set(segment.scopeId, segment);
+      scopeOrder.push(segment.scopeId);
+    }
+  }
+
+  const result = new Map<string, number>();
+  for (let i = 0; i < scopeOrder.length; i += 1) {
+    const scopeId = scopeOrder[i];
+    const seg = firstSegmentByScope.get(scopeId);
+    if (!seg) continue;
+    let overlapCount = 0;
+    for (let j = 0; j < i; j += 1) {
+      const other = firstSegmentByScope.get(scopeOrder[j]);
+      if (!other) continue;
+      if (other.pageIndex !== seg.pageIndex) continue;
+      if (other.toOffset > seg.fromOffset && other.fromOffset < seg.toOffset) {
+        overlapCount += 1;
+      }
+    }
+    result.set(scopeId, overlapCount);
+  }
+  return result;
+}
+
 export default TwScopeRailLayer;

package/src/ui-tailwind/editor-surface/paste-plain-text.ts

@@ -0,0 +1,72 @@
+/**
+ * Extract a sequence of callback operations from a plain-text clipboard
+ * payload. Used by the `pm-command-bridge` handlePaste / handleDrop
+ * hooks to turn a pasted string into calls to `onInsertText` /
+ * `onSplitParagraph` / `onInsertHardBreak` — the same runtime-owned
+ * callbacks typing already uses.
+ *
+ * Separator convention:
+ *   - LF (`\n`), CRLF (`\r\n`), CR (`\r`) → paragraph split
+ *     ({ kind: "split" }).
+ *   - U+000B (vertical tab) → hard break ({ kind: "hard_break" }).
+ *     Word's plain-text clipboard represents shift-enter line breaks
+ *     as vertical-tab; preserving them keeps paragraph-internal line
+ *     structure.
+ *   - Tab (U+0009) stays inside the current text segment. The
+ *     runtime's `onInsertText` decides whether it is rendered as a
+ *     tab-stop or swallowed.
+ *
+ * Consecutive separators produce multiple splits in sequence (empty
+ * paragraphs). Leading / trailing separators are emitted verbatim so
+ * the caller can decide whether to coalesce into a trailing blank.
+ *
+ * Pure function: no DOM, no React, no ProseMirror state.
+ *
+ * Source plan: `docs/plans/editor-paste-drop.md` §Phase 1.
+ */
+
+export type PastePlainSegment =
+  | { kind: "text"; value: string }
+  | { kind: "split" }
+  | { kind: "hard_break" };
+
+export function extractPlainTextSegments(input: string): PastePlainSegment[] {
+  if (input.length === 0) return [];
+
+  const segments: PastePlainSegment[] = [];
+  let buffer = "";
+
+  const flush = (): void => {
+    if (buffer.length > 0) {
+      segments.push({ kind: "text", value: buffer });
+      buffer = "";
+    }
+  };
+
+  for (let i = 0; i < input.length; i += 1) {
+    const ch = input[i];
+
+    if (ch === "\r") {
+      flush();
+      segments.push({ kind: "split" });
+      // Collapse CRLF into one split — advance past the LF.
+      if (input[i + 1] === "\n") i += 1;
+      continue;
+    }
+    if (ch === "\n") {
+      flush();
+      segments.push({ kind: "split" });
+      continue;
+    }
+    if (ch === "\u000B") {
+      flush();
+      segments.push({ kind: "hard_break" });
+      continue;
+    }
+
+    buffer += ch;
+  }
+
+  flush();
+  return segments;
+}

package/src/ui-tailwind/editor-surface/pm-command-bridge.ts

@@ -7,8 +7,62 @@ import {
   createSelectionSnapshot,
 } from "../../ui/headless/selection-helpers";
 import { resolveSurfaceShortcut } from "../../ui/runtime-shortcut-dispatch";
+import {
+  extractPlainTextSegments,
+  type PastePlainSegment,
+} from "./paste-plain-text";
 import type { PositionMap } from "./pm-position-map";
 
+/**
+ * Callback subset used by paste / drop dispatch. Exported so tests can
+ * record dispatch order without constructing the full
+ * `CommandBridgeCallbacks` surface.
+ */
+export interface PasteDispatchCallbacks {
+  onInsertText: (text: string) => void;
+  onSplitParagraph: () => void;
+  onInsertHardBreak: () => void;
+}
+
+/**
+ * Dispatch an ordered list of plain-text segments to the runtime-owned
+ * callbacks. Empty text segments are skipped. Pure with respect to the
+ * callbacks — no global state, no PM mutation.
+ */
+export function applyPasteSegmentsToCallbacks(
+  segments: readonly PastePlainSegment[],
+  callbacks: PasteDispatchCallbacks,
+): void {
+  for (const seg of segments) {
+    switch (seg.kind) {
+      case "text":
+        if (seg.value.length > 0) callbacks.onInsertText(seg.value);
+        break;
+      case "split":
+        callbacks.onSplitParagraph();
+        break;
+      case "hard_break":
+        callbacks.onInsertHardBreak();
+        break;
+    }
+  }
+}
+
+/**
+ * Sum the character length across every `text` segment. Used by the
+ * paste / drop handlers to populate the `charCount` field of the
+ * public `paste_applied` event.
+ */
+export function totalTextCharCount(
+  segments: readonly PastePlainSegment[],
+): number {
+  let total = 0;
+  for (const seg of segments) {
+    if (seg.kind === "text") total += seg.value.length;
+  }
+  return total;
+}
+
 export interface SelectionSyncCallbacks {
   onSelectionChange: (selection: SelectionSnapshot) => void;
   getPositionMap: () => PositionMap | null;
@@ -28,6 +82,17 @@ export interface CommandBridgeCallbacks extends SelectionSyncCallbacks {
   onUndo: () => void;
   onRedo: () => void;
   onBlockedInput?: (command: "paste" | "drop", message: string) => void;
+  /**
+   * Optional. Fires after a plain-text paste or drop successfully
+   * dispatches through the runtime callbacks. `source` distinguishes
+   * paste from drop. Rich paste (HTML, Office clipboard) still fires
+   * `onBlockedInput`, not this callback.
+   */
+  onPasteApplied?: (meta: {
+    segmentCount: number;
+    charCount: number;
+    source: "paste" | "drop";
+  }) => void;
   /**
    * Optional. Fires on `compositionstart` (true) and `compositionend`
    * (false). The surface forwards this to the predicted lane's session
@@ -130,16 +195,61 @@ export function createCommandBridgePlugins(
         return true; // Block PM from processing
       },
 
-      // Block paste (rich paste is not safe, plain paste via text.insert is TODO)
-      handlePaste() {
-        callbacks.onBlockedInput?.("paste", "Paste is not supported in the mounted editor yet.");
-        return true; // Block
+      // Plain-text paste: extract text/plain from the clipboard and
+      // dispatch through the runtime-owned callbacks that typing uses.
+      // Rich paste (HTML, Office clipboard) stays blocked — hosts that
+      // listen for onBlockedInput still get notified when a non-plain-
+      // text payload arrives. See docs/plans/editor-paste-drop.md.
+      handlePaste(_view, event) {
+        if (isComposing) return true;
+        const clipboard = event.clipboardData;
+        if (!clipboard) {
+          callbacks.onBlockedInput?.("paste", "Clipboard data was not available.");
+          return true;
+        }
+        const plain = clipboard.getData("text/plain");
+        if (!plain) {
+          callbacks.onBlockedInput?.(
+            "paste",
+            "Non-plain-text paste is not supported yet.",
+          );
+          return true;
+        }
+        const segments = extractPlainTextSegments(plain);
+        applyPasteSegmentsToCallbacks(segments, callbacks);
+        callbacks.onPasteApplied?.({
+          segmentCount: segments.length,
+          charCount: totalTextCharCount(segments),
+          source: "paste",
+        });
+        return true;
       },
 
-      // Block drop
-      handleDrop() {
-        callbacks.onBlockedInput?.("drop", "Drag and drop is not supported in the mounted editor.");
-        return true; // Block
+      // Plain-text drop: symmetric path — extract text/plain from the
+      // DataTransfer and dispatch through the same callbacks paste uses.
+      handleDrop(_view, event) {
+        if (isComposing) return true;
+        const dt = (event as DragEvent).dataTransfer;
+        if (!dt) {
+          callbacks.onBlockedInput?.("drop", "Drop data was not available.");
+          return true;
+        }
+        const plain = dt.getData("text/plain");
+        if (!plain) {
+          callbacks.onBlockedInput?.(
+            "drop",
+            "Non-plain-text drop is not supported yet.",
+          );
+          return true;
+        }
+        const segments = extractPlainTextSegments(plain);
+        applyPasteSegmentsToCallbacks(segments, callbacks);
+        callbacks.onPasteApplied?.({
+          segmentCount: segments.length,
+          charCount: totalTextCharCount(segments),
+          source: "drop",
+        });
+        return true;
       },
     },
   });

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

@@ -23,6 +23,39 @@ type RailDecorationSpec = {
   attrs: Record<string, string>;
 };
 
+/**
+ * Validate and normalize a host-supplied CSS color before interpolating it
+ * into an inline-style string.  Accepts only the narrow subset a
+ * host-issued metadata color would legitimately use:
+ *   - `#rgb`, `#rrggbb`, `#rrggbbaa` hex literals
+ *   - `rgb(...)` / `rgba(...)` with numeric/percent/alpha args, no nested
+ *     comments or closing-paren escape tricks
+ *   - named colors drawn from a short whitelist
+ * Any semicolon, brace, or parenthesis outside the matched shape is
+ * rejected.  Returns `null` when the input is unsafe; callers must drop
+ * the style attribute entirely in that case.
+ */
+export function sanitizeHostCssColor(raw: unknown): string | null {
+  if (typeof raw !== "string") return null;
+  const value = raw.trim();
+  if (value.length === 0 || value.length > 64) return null;
+  // Hex: #rgb / #rrggbb / #rrggbbaa
+  if (/^#[0-9a-fA-F]{3}$|^#[0-9a-fA-F]{6}$|^#[0-9a-fA-F]{8}$/.test(value)) {
+    return value;
+  }
+  // rgb()/rgba() with digits, dots, percent, commas and a single space.
+  if (/^rgba?\(\s*\d+(\.\d+)?%?(\s*,\s*\d+(\.\d+)?%?){2,3}\s*\)$/.test(value)) {
+    return value;
+  }
+  // Named colors — short whitelist that covers every host-chip use.
+  const named = new Set([
+    "black", "white", "red", "green", "blue", "yellow", "orange",
+    "purple", "pink", "brown", "gray", "grey", "transparent",
+  ]);
+  if (named.has(value.toLowerCase())) return value.toLowerCase();
+  return null;
+}
+
 function isSelectionZoneScope(scope: WorkflowScope): boolean {
   return (
     scope.scopeId.startsWith("scope-lab-") ||
@@ -511,10 +544,11 @@ export function buildDecorations(
       const pmRange = buildAnchorPmRange(metadata.anchor, positionMap);
       if (!pmRange || !pmRange.allowInline || pmRange.from >= pmRange.to) continue;
 
+      const safeColor = sanitizeHostCssColor(metadata.color);
       decorations.push(
         Decoration.inline(pmRange.from, pmRange.to, {
           class: getWorkflowMetadataInlineClass(),
-          ...(metadata.color ? { style: `--wre-workflow-metadata-color: ${metadata.color};` } : {}),
+          ...(safeColor ? { style: `--wre-workflow-metadata-color: ${safeColor};` } : {}),
           "data-workflow-entry-id": metadata.entryId,
           "data-workflow-metadata-id": metadata.metadataId,
         }),

package/src/ui-tailwind/editor-surface/pm-page-break-decorations.ts

@@ -178,7 +178,60 @@ interface ChromeWidgetInput {
   nextHeaderPreview: string;
 }
 
+// P14.c — cache the widget DOM by input identity.  PM rebuilds the
+// page-break decorations on every commit (37 widgets per 38-page doc);
+// each widget's DOM is ~10 elements.  When the page IDs, labels, and
+// preview text haven't changed (the common case during typing inside
+// one page), returning the cached DOM lets PM's decoration
+// reconciliation skip the remount entirely.  Bounded LRU at 256 entries
+// so a long session with significant content churn doesn't grow without
+// bound.
+const widgetDomCache = new Map<string, HTMLElement>();
+const WIDGET_DOM_CACHE_LIMIT = 256;
+
+function widgetCacheKey(input: ChromeWidgetInput): string {
+  return [
+    input.posture,
+    input.prevPageId,
+    input.nextPageId,
+    input.prevPageIndex,
+    input.nextPageIndex,
+    input.headerBandPx,
+    input.footerBandPx,
+    input.interGapPx,
+    input.prevPageLabel,
+    input.nextPageLabel,
+    input.hasPrevFooterStory ? "1" : "0",
+    input.hasNextHeaderStory ? "1" : "0",
+    input.prevFooterPreview,
+    input.nextHeaderPreview,
+  ].join("\x1f");
+}
+
 function buildChromeWidgetDom(input: ChromeWidgetInput): HTMLElement {
+  const key = widgetCacheKey(input);
+  const cached = widgetDomCache.get(key);
+  if (cached) {
+    // Touch LRU recency by re-inserting.
+    widgetDomCache.delete(key);
+    widgetDomCache.set(key, cached);
+    return cached;
+  }
+  const built = buildChromeWidgetDomUncached(input);
+  widgetDomCache.set(key, built);
+  if (widgetDomCache.size > WIDGET_DOM_CACHE_LIMIT) {
+    const oldest = widgetDomCache.keys().next().value;
+    if (oldest !== undefined) widgetDomCache.delete(oldest);
+  }
+  return built;
+}
+
+/** Test-only export — clears the cache between assertions. */
+export function __resetPageBreakWidgetCache(): void {
+  widgetDomCache.clear();
+}
+
+function buildChromeWidgetDomUncached(input: ChromeWidgetInput): HTMLElement {
   const root = document.createElement("div");
   root.className = "wre-page-chrome-widget";
   root.setAttribute("data-kind", "page-chrome-widget");
@@ -187,6 +240,12 @@ function buildChromeWidgetDom(input: ChromeWidgetInput): HTMLElement {
   root.setAttribute("data-next-page-id", input.nextPageId);
   root.setAttribute("data-prev-page-index", String(input.prevPageIndex));
   root.setAttribute("data-next-page-index", String(input.nextPageIndex));
+  // P3.a: expose page-frame boundary markers so the page stack and tests
+  // can enumerate pages without re-walking the render graph.  Each widget
+  // ends page N (`prev`) and starts page N+1 (`next`); the outer workspace
+  // frame still accounts for the boundaries at both ends of the document.
+  root.setAttribute("data-page-frame-end", input.prevPageId);
+  root.setAttribute("data-page-frame-start", input.nextPageId);
   root.contentEditable = "false";
   root.setAttribute("aria-hidden", "false");
   root.style.display = "block";
@@ -245,16 +304,40 @@ function buildChromeWidgetDom(input: ChromeWidgetInput): HTMLElement {
   });
   root.appendChild(footer);
 
+  // P3.a: the inter-page gap is now a visible canvas strip that reads as
+  // "the space between two papers", not a subtle gradient inside one white
+  // page.  The strip paints in the workspace canvas color (the same color
+  // the page frames float on in page mode), with subtle drop/rise shadows
+  // on either edge so the preceding footer reads as "bottom of page N's
+  // paper" and the following header reads as "top of page N+1's paper".
+  //
+  // The visual goal: bringing the user closer to a Word-native perception
+  // of distinct pages without requiring the PM editable tree to be split
+  // into per-page subtrees (that lands in P3.b).
   const separator = document.createElement("div");
   separator.className = "wre-page-chrome-separator";
+  separator.setAttribute("data-kind", "page-chrome-separator");
   separator.style.position = "absolute";
   separator.style.left = "0";
   separator.style.right = "0";
   separator.style.top = `${input.footerBandPx}px`;
   separator.style.height = `${input.interGapPx}px`;
-  // Background: two subtle page-edge shadows mimicking real paper gap.
-  separator.style.background =
-    "linear-gradient(to bottom, rgba(0,0,0,0.045), rgba(0,0,0,0) 40%, rgba(0,0,0,0) 60%, rgba(0,0,0,0.035))";
+  // Canvas color (same as the scroll root's bg-surface) so the strip reads
+  // as "gap between two papers".  Page mode and canvas mode both use the
+  // same token so the UX remains consistent at any chrome preset.
+  separator.style.backgroundColor = "var(--color-surface, #f1f5f9)";
+  // Inner shadows on top/bottom: the previous footer's bottom edge gains
+  // a subtle paper-edge shadow, and the next header's top edge likewise.
+  // Inset shadows let us avoid touching the footer / header DOM while
+  // keeping the shadows flush with the band borders.
+  separator.style.boxShadow = [
+    // Top edge — simulates the bottom shadow of page N's paper.
+    "inset 0 1px 0 rgba(15, 23, 42, 0.06)",
+    "inset 0 2px 3px -2px rgba(15, 23, 42, 0.12)",
+    // Bottom edge — simulates the top shadow of page N+1's paper.
+    "inset 0 -1px 0 rgba(15, 23, 42, 0.06)",
+    "inset 0 -2px 3px -2px rgba(15, 23, 42, 0.12)",
+  ].join(", ");
   root.appendChild(separator);
 
   const header = buildBand({