@beyondwork/docx-react-component 1.0.35 → 1.0.37

package/src/ui-tailwind/editor-surface/predicted-tag-preflight.ts

@@ -0,0 +1,63 @@
+import type {
+  EditorSurfaceSnapshot,
+  SurfaceBlockSnapshot,
+} from "../../api/public-types.ts";
+import type { ScopeTagRegistry } from "../../runtime/scope-tag-registry.ts";
+
+/**
+ * Pre-flight check the FastTextEditLane consults before applying a predicted
+ * transaction. Returns true when the proposed edit range intersects any tag
+ * whose registry behavior is `bailIfCrossed: true` — today, that is fields,
+ * SDTs, and opaque (preserve-only) blocks. Such edits would be rolled back by
+ * the runtime's workflow / structural-divergence checks anyway; bailing
+ * before predicting saves the predicted-then-restored PM churn.
+ *
+ * Phase 1 scope: top-level surface blocks (paragraph, opaque_block, sdt_block)
+ * plus inline field_ref segments inside paragraphs. Does NOT recurse into
+ * sdt_block.children (the block boundary already bails). Does NOT walk into
+ * `table` blocks or their cells (left to the runtime safety net).
+ *
+ * Boundary semantics: this uses strict-open intersection
+ * (`aFrom < bTo && aTo > bFrom`). A collapsed cursor sitting exactly at
+ * a tag boundary is NOT considered intersecting. This intentionally
+ * under-bails on boundary-touching cursors: an insert at the left edge
+ * of a field is a legal edit (the field shifts), so over-bailing would
+ * cost a predicted-tx optimization for no correctness benefit. The
+ * downside is that a delete-forward at the left edge or a delete-backward
+ * at the right edge of a bail-if-crossed tag will fall through to the
+ * runtime, which still rejects the edit — the lane pays one
+ * predicted-then-rolled-back PM cycle for those keystrokes. A future
+ * phase that takes the predicted intent's direction can tighten this.
+ */
+export function hasBailIfCrossedTagInRange(
+  surface: EditorSurfaceSnapshot,
+  registry: ScopeTagRegistry,
+  fromRuntime: number,
+  toRuntime: number,
+): boolean {
+  const opaqueBails = registry.get("opaque").bailIfCrossed;
+  const sdtBails = registry.get("sdt").bailIfCrossed;
+  const fieldBails = registry.get("field").bailIfCrossed;
+  for (const block of surface.blocks) {
+    if (!intersects(block.from, block.to, fromRuntime, toRuntime)) continue;
+    if (block.kind === "opaque_block" && opaqueBails) {
+      return true;
+    }
+    if (block.kind === "sdt_block" && sdtBails) {
+      return true;
+    }
+    if (block.kind === "paragraph" && fieldBails) {
+      for (const segment of block.segments) {
+        if (segment.kind !== "field_ref") continue;
+        if (intersects(segment.from, segment.to, fromRuntime, toRuntime)) {
+          return true;
+        }
+      }
+    }
+  }
+  return false;
+}
+
+function intersects(aFrom: number, aTo: number, bFrom: number, bTo: number): boolean {
+  return aFrom < bTo && aTo > bFrom;
+}

package/src/ui-tailwind/editor-surface/predicted-tx-gate.ts

@@ -0,0 +1,39 @@
+import { Plugin, PluginKey, type Transaction } from "prosemirror-state";
+
+/**
+ * Key used to stamp predicted PM transactions with their `opId`. The gate
+ * plugin reads this meta and allows a doc-changing transaction through only
+ * when the lane has registered the `opId`.
+ */
+export const PREDICTED_META_KEY = "bounded-local-first/predicted";
+
+export interface PredictedMeta {
+  opId: string;
+}
+
+export interface PredictedTxGateOptions {
+  /** The lane's `LocalEditSessionState.isPredicted(opId)` — consulted per tx. */
+  isPredicted(opId: string): boolean;
+}
+
+const gateKey = new PluginKey("predicted-tx-gate");
+
+/**
+ * PredictedTxGate — replaces the unconditional "block every `docChanged`"
+ * filter with one that lets through predicted transactions whose `opId` the
+ * lane has registered. Unregistered or unstamped doc-changing transactions
+ * are still blocked — the runtime remains the canonical mutation path.
+ *
+ * Selection-only transactions always pass.
+ */
+export function createPredictedTxGate(options: PredictedTxGateOptions): Plugin {
+  return new Plugin({
+    key: gateKey,
+    filterTransaction(tr: Transaction) {
+      if (!tr.docChanged) return true;
+      const meta = tr.getMeta(PREDICTED_META_KEY) as PredictedMeta | undefined;
+      if (!meta) return false;
+      return options.isPredicted(meta.opId);
+    },
+  });
+}

package/src/ui-tailwind/editor-surface/tw-prosemirror-surface.tsx

@@ -52,7 +52,12 @@ import {
   recordPerfSample,
   startPerfProbe,
 } from "./perf-probe";
-import type { PositionMap } from "./pm-position-map";
+import { buildPositionMap, type PositionMap } from "./pm-position-map";
+import { createLocalEditSessionState } from "./local-edit-session-state";
+import { createFastTextEditLane } from "./fast-text-edit-lane";
+import { createPredictedTxGate } from "./predicted-tx-gate";
+import { createScopeTagRegistry } from "../../runtime/scope-tag-registry";
+import { hasBailIfCrossedTagInRange } from "./predicted-tag-preflight";
 import {
   clearSearch as clearSearchPlugin,
   createSearchPlugin,
@@ -111,6 +116,15 @@ export interface TwProseMirrorSurfaceProps {
   activeWorkflowWorkItemId?: string | null;
   activeWorkflowScopeIds?: readonly string[];
   workflowMetadata?: readonly WorkflowMetadataMarkup[];
+  /**
+   * Synchronous dispatcher for predicted-lane runtime commands. When provided,
+   * the surface routes text input through `FastTextEditLane` for immediate
+   * local PM feel; when absent, it falls back to the legacy callback-based
+   * round-trip that calls `runtime.applyActiveStoryTextCommand` externally.
+   */
+  dispatchRuntimeCommand?: (
+    command: import("./fast-text-edit-lane").LaneRuntimeCommand,
+  ) => import("../../api/public-types").TextCommandAck;
 }
 
 export interface TwProseMirrorSurfaceRef {
@@ -157,6 +171,9 @@ export const TwProseMirrorSurface = forwardRef<
   const documentBuildKeyRef = useRef<string | null>(null);
   const decorationBuildKeyRef = useRef<string | null>(null);
   const suppressSelectionEchoRef = useRef(false);
+  const sessionRef = useRef<import("./local-edit-session-state").LocalEditSessionState | null>(null);
+  const laneRef = useRef<import("./fast-text-edit-lane").FastTextEditLane | null>(null);
+  const equivalentAckKeyRef = useRef<string | null>(null);
   const selectionToolbarFrameRef = useRef<number | null>(null);
   const lastSelectionToolbarMeasurementRef = useRef<{
     key: string | null;
@@ -165,6 +182,13 @@ export const TwProseMirrorSurface = forwardRef<
     key: null,
     anchor: null,
   });
+  const snapshotRef = useRef(snapshot);
+  snapshotRef.current = snapshot;
+
+  const scopeTagRegistry = useMemo(
+    () => createScopeTagRegistry(),
+    [],
+  );
 
   // Keep callbacks ref up to date (avoids stale closures in PM plugins)
   callbacksRef.current = {
@@ -263,6 +287,10 @@ export const TwProseMirrorSurface = forwardRef<
         callbacksRef.current?.isSelectionSyncSuppressed?.() ?? false,
     };
 
+    const gate = createPredictedTxGate({
+      isPredicted: (opId) => sessionRef.current?.isPredicted(opId) ?? false,
+    });
+
     const corePlugins = props.ydoc
       ? createCollabPlugins({
           ydoc: props.ydoc,
@@ -271,11 +299,42 @@ export const TwProseMirrorSurface = forwardRef<
         })
       : createCommandBridgePlugins({
           ...selectionCallbacks,
-          onInsertText: (text) => callbacksRef.current?.onInsertText(text),
-          onDeleteBackward: () => callbacksRef.current?.onDeleteBackward(),
-          onDeleteForward: () => callbacksRef.current?.onDeleteForward(),
-          onSplitParagraph: () => callbacksRef.current?.onSplitParagraph(),
-          onInsertHardBreak: () => callbacksRef.current?.onInsertHardBreak(),
+          gate,
+          onInsertText: (text) => {
+            if (laneRef.current) {
+              laneRef.current.onInsertText(text);
+            } else {
+              callbacksRef.current?.onInsertText(text);
+            }
+          },
+          onDeleteBackward: () => {
+            if (laneRef.current) {
+              laneRef.current.onDeleteBackward();
+            } else {
+              callbacksRef.current?.onDeleteBackward();
+            }
+          },
+          onDeleteForward: () => {
+            if (laneRef.current) {
+              laneRef.current.onDeleteForward();
+            } else {
+              callbacksRef.current?.onDeleteForward();
+            }
+          },
+          onSplitParagraph: () => {
+            if (laneRef.current) {
+              laneRef.current.onSplitParagraph();
+            } else {
+              callbacksRef.current?.onSplitParagraph();
+            }
+          },
+          onInsertHardBreak: () => {
+            if (laneRef.current) {
+              laneRef.current.onInsertHardBreak();
+            } else {
+              callbacksRef.current?.onInsertHardBreak();
+            }
+          },
           onInsertTab: () => callbacksRef.current?.onInsertTab(),
           onOutdentTab: () => callbacksRef.current?.onOutdentTab?.(),
           onUndo: () => callbacksRef.current?.onUndo(),
@@ -338,6 +397,72 @@ export const TwProseMirrorSurface = forwardRef<
     ],
   );
 
+  // Create the local edit session once per mount. The session is scoped to the
+  // view lifetime; the rebuild effect seeds the base revision token below.
+  useEffect(() => {
+    sessionRef.current = createLocalEditSessionState({
+      baseRevisionToken: snapshot.revisionToken,
+    });
+    return () => {
+      sessionRef.current = null;
+      laneRef.current = null;
+    };
+    // Intentionally empty deps: session is scoped to the view lifetime.
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, []);
+
+  // Build the FastTextEditLane whenever `dispatchRuntimeCommand` changes.
+  // The lane is consulted via `laneRef.current` inside PM plugin callbacks,
+  // so the plugins memo does not need to depend on this effect.
+  useEffect(() => {
+    if (!props.dispatchRuntimeCommand || !sessionRef.current) {
+      laneRef.current = null;
+      return;
+    }
+    laneRef.current = createFastTextEditLane({
+      session: sessionRef.current,
+      getView: () => viewRef.current,
+      getPositionMap: () => positionMapRef.current,
+      dispatchRuntimeCommand: props.dispatchRuntimeCommand,
+      suppressSelectionSync: (suppressed) => {
+        suppressSelectionEchoRef.current = suppressed;
+      },
+      shouldBailBeforePredict: (_intent, fromRuntime, toRuntime) => {
+        const surface = snapshotRef.current.surface;
+        if (!surface) return false;
+        return hasBailIfCrossedTagInRange(
+          surface,
+          scopeTagRegistry,
+          fromRuntime,
+          toRuntime,
+        );
+      },
+      onEquivalentAck: () => {
+        // INVARIANT: this marker is set only by onEquivalentAck, which the
+        // runtime invokes synchronously from dispatchRuntimeCommand. The
+        // rebuild effect's short-circuit (search for "Predicted-lane
+        // short-circuit" below) reads it during the same React render cycle
+        // that the predicted dispatch triggered. If the runtime ack ever
+        // becomes async (microtask, animation frame, network round-trip),
+        // this marker will be stale by the time the rebuild effect runs and
+        // the short-circuit must be replaced with a
+        // `pendingEquivalentAckOpIds: Set<string>` ledger keyed by opId.
+        equivalentAckKeyRef.current = documentBuildKeyRef.current;
+      },
+      onAdjustedAck: () => {
+        // Adjusted path: allow the rebuild effect to run (it will call
+        // view.updateState with the canonical snapshot).
+        equivalentAckKeyRef.current = null;
+      },
+      onRejectedAck: () => {
+        equivalentAckKeyRef.current = null;
+      },
+      onStructuralDivergence: () => {
+        equivalentAckKeyRef.current = null;
+      },
+    });
+  }, [props.dispatchRuntimeCommand, scopeTagRegistry]);
+
   useEffect(() => {
     if (!mountRef.current || !surface) return;
 
@@ -350,6 +475,34 @@ export const TwProseMirrorSurface = forwardRef<
       return;
     }
 
+    // Predicted-lane short-circuit: if the lane just confirmed an equivalent
+    // ack, the PM doc already matches the canonical snapshot. Update tracking
+    // refs and decorations without rebuilding the PM state.
+    //
+    // INVARIANT: reads `equivalentAckKeyRef.current` set by `onEquivalentAck`
+    // above. Depends on the runtime ack being synchronous so the marker is
+    // already in place when this effect runs after the predicted dispatch.
+    // See the comment at `onEquivalentAck` for the async-ack migration path.
+    if (
+      viewRef.current &&
+      equivalentAckKeyRef.current !== null &&
+      sessionRef.current &&
+      !sessionRef.current.hasPending() &&
+      sessionRef.current.getBaseRevisionToken() === snapshot.revisionToken
+    ) {
+      // Rebuild the position map so runtime↔PM translations track the new
+      // canonical surface shape. The PM document itself is already correct.
+      positionMapRef.current = buildPositionMap(surface);
+      documentBuildKeyRef.current = documentBuildKey;
+      applyDecorationProps(viewRef.current, positionMapRef.current);
+      equivalentAckKeyRef.current = null;
+      if (pendingTypingProbeRef.current) {
+        finishPerfProbe(pendingTypingProbeRef.current);
+        pendingTypingProbeRef.current = null;
+      }
+      return;
+    }
+
     const { state, positionMap } = createPMStateFromSnapshot(
       surface,
       snapshot.selection,
@@ -473,6 +626,20 @@ export const TwProseMirrorSurface = forwardRef<
       return;
     }
 
+    // Skip the dispatch when PM is blurred. `view.dispatch(setSelection)`
+    // synchronizes the DOM selection, and on a blurred contenteditable some
+    // browsers pull DOM focus back to the editor as a side effect — which
+    // would steal focus from any toolbar button or other chrome the user
+    // just clicked. PM's state.selection is allowed to diverge from the
+    // runtime's selection while PM is blurred; the natural focus flow
+    // (click → onFocus → activeRuntime.focus() → snapshot update → this
+    // effect fires again with view.hasFocus() === true) resyncs them when
+    // PM regains focus, and the next canonical rebuild also re-derives PM
+    // selection from the snapshot.
+    if (!view.hasFocus()) {
+      return;
+    }
+
     suppressSelectionEchoRef.current = true;
     view.dispatch(view.state.tr.setSelection(nextSelection));
     recordPerfSample("selection.sync");

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

@@ -332,23 +332,40 @@
 
 .prosemirror-surface .ProseMirror .wre-workflow-rail {
   position: relative;
-  padding-left: 0.875rem;
-  border-radius: 0.25rem;
+  isolation: isolate;
+  overflow: visible;
 }
 
 .prosemirror-surface .ProseMirror .wre-workflow-rail::before {
   content: "";
   position: absolute;
-  left: 0;
-  top: 0.2rem;
-  bottom: 0.2rem;
-  width: 0.3rem;
+  left: -0.85rem;
+  top: 0;
+  bottom: 0;
+  width: 0.22rem;
   border-radius: 999px;
   background: var(--wre-workflow-rail-color, var(--color-border-strong));
+  z-index: 1;
+}
+
+.prosemirror-surface .ProseMirror .wre-workflow-rail::after {
+  content: "";
+  position: absolute;
+  left: -0.35rem;
+  right: -0.25rem;
+  top: -0.2rem;
+  bottom: -0.2rem;
+  border-radius: 0.45rem;
+  background: var(--wre-workflow-overlay-fill, transparent);
+  box-shadow:
+    inset 0 0 0 1px var(--wre-workflow-overlay-stroke, transparent),
+    0 8px 22px -22px color-mix(in srgb, var(--wre-workflow-rail-color, var(--color-border-strong)) 28%, transparent);
+  pointer-events: none;
+  z-index: -1;
 }
 
 .prosemirror-surface .ProseMirror .wre-workflow-rail-active::before {
-  width: 0.3125rem;
+  width: 0.26rem;
   opacity: 1;
   box-shadow: 0 0 0 1px color-mix(in oklab, var(--wre-workflow-rail-color, var(--color-border-strong)) 30%, transparent);
 }
@@ -366,27 +383,32 @@
 
 .prosemirror-surface .ProseMirror .wre-workflow-rail-edit {
   --wre-workflow-rail-color: var(--color-accent);
-  background: color-mix(in srgb, var(--color-accent) 7%, transparent);
+  --wre-workflow-overlay-fill: color-mix(in srgb, var(--color-accent) 9%, transparent);
+  --wre-workflow-overlay-stroke: color-mix(in srgb, var(--color-accent) 16%, transparent);
 }
 
 .prosemirror-surface .ProseMirror .wre-workflow-rail-suggest {
   --wre-workflow-rail-color: var(--color-warning);
-  background: color-mix(in srgb, var(--color-warning) 8%, transparent);
+  --wre-workflow-overlay-fill: color-mix(in srgb, var(--color-warning) 10%, transparent);
+  --wre-workflow-overlay-stroke: color-mix(in srgb, var(--color-warning) 17%, transparent);
 }
 
 .prosemirror-surface .ProseMirror .wre-workflow-rail-comment {
   --wre-workflow-rail-color: var(--color-insert);
-  background: color-mix(in srgb, var(--color-insert) 7%, transparent);
+  --wre-workflow-overlay-fill: color-mix(in srgb, var(--color-insert) 9%, transparent);
+  --wre-workflow-overlay-stroke: color-mix(in srgb, var(--color-insert) 16%, transparent);
 }
 
 .prosemirror-surface .ProseMirror .wre-workflow-rail-view {
   --wre-workflow-rail-color: var(--color-secondary);
-  background: color-mix(in srgb, var(--color-secondary) 6%, transparent);
+  --wre-workflow-overlay-fill: color-mix(in srgb, var(--color-secondary) 7%, transparent);
+  --wre-workflow-overlay-stroke: color-mix(in srgb, var(--color-secondary) 12%, transparent);
 }
 
 .prosemirror-surface .ProseMirror .wre-workflow-rail-candidate {
   --wre-workflow-rail-color: var(--color-warning);
-  background: color-mix(in srgb, var(--color-warning) 4%, transparent);
+  --wre-workflow-overlay-fill: color-mix(in srgb, var(--color-warning) 5%, transparent);
+  --wre-workflow-overlay-stroke: color-mix(in srgb, var(--color-warning) 14%, transparent);
 }
 
 .prosemirror-surface .ProseMirror .wre-workflow-rail-candidate::before {
@@ -402,7 +424,8 @@
 
 .prosemirror-surface .ProseMirror .wre-workflow-rail-preserve-only {
   --wre-workflow-rail-color: var(--color-danger);
-  background: color-mix(in srgb, var(--color-danger) 5%, transparent);
+  --wre-workflow-overlay-fill: color-mix(in srgb, var(--color-danger) 7%, transparent);
+  --wre-workflow-overlay-stroke: color-mix(in srgb, var(--color-danger) 16%, transparent);
 }
 
 .prosemirror-surface .ProseMirror .wre-workflow-rail-preserve-only::before {
@@ -411,7 +434,8 @@
 
 .prosemirror-surface .ProseMirror .wre-workflow-rail-blocked-import {
   --wre-workflow-rail-color: var(--color-danger);
-  background: color-mix(in srgb, var(--color-danger) 8%, transparent);
+  --wre-workflow-overlay-fill: color-mix(in srgb, var(--color-danger) 10%, transparent);
+  --wre-workflow-overlay-stroke: color-mix(in srgb, var(--color-danger) 20%, transparent);
 }
 
 .prosemirror-surface .ProseMirror .wre-workflow-rail-blocked-import::before {
@@ -431,6 +455,8 @@
 
 .prosemirror-surface .ProseMirror .wre-workflow-rail-selection-zone {
   background: transparent;
+  --wre-workflow-overlay-fill: transparent;
+  --wre-workflow-overlay-stroke: transparent;
 }
 
 .prosemirror-surface .ProseMirror .wre-workflow-rail-selection-zone::before {

package/src/ui-tailwind/toolbar/tw-toolbar-icon-button.tsx

@@ -26,7 +26,7 @@ export function TwToolbarIconButton(props: TwToolbarIconButtonProps) {
           onMouseDown={preserveEditorSelectionMouseDown}
           onClick={props.onClick}
           className={[
-            "inline-flex h-7 w-7 items-center justify-center rounded-lg border border-transparent transition-colors outline-none",
+            "inline-flex h-6 w-6 items-center justify-center rounded-md border border-transparent transition-colors outline-none",
             "disabled:opacity-30 disabled:cursor-not-allowed",
             props.emphasis
               ? "text-accent hover:border-border/60 hover:bg-surface"
@@ -36,7 +36,7 @@ export function TwToolbarIconButton(props: TwToolbarIconButtonProps) {
             focusRingClass,
           ].join(" ")}
         >
-          <props.icon className="h-4 w-4" />
+          <props.icon className="h-3.5 w-3.5" />
         </button>
       </Tooltip.Trigger>
       <Tooltip.Portal>