@beyondwork/docx-react-component 1.0.36 → 1.0.38

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,16 +299,50 @@ 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(),
           onRedo: () => callbacksRef.current?.onRedo(),
           onBlockedInput: (command, message) => callbacksRef.current?.onBlockedInput?.(command, message),
+          onCompositionChange: (composing) => {
+            sessionRef.current?.setComposing(composing);
+          },
         });
 
     return [
@@ -338,6 +400,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 +478,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 +629,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/index.ts

@@ -14,10 +14,31 @@ export { TwReviewRail, type TwReviewRailProps, type ReviewRailTab } from "./revi
 export { TwCommentSidebar } from "./review/tw-comment-sidebar";
 export { TwRevisionSidebar } from "./review/tw-revision-sidebar";
 export { TwHealthPanel } from "./review/tw-health-panel";
+export { TwWorkflowTab, type TwWorkflowTabProps } from "./review/tw-workflow-tab";
+export {
+  TwRailCard,
+  type TwRailCardProps,
+  type RailCardTone,
+  type RailCardAvatar,
+  type RailCardCounter,
+  type RailCardProgress,
+} from "./review/tw-rail-card";
+export {
+  TwReviewRailFooter,
+  type TwReviewRailFooterProps,
+} from "./review/tw-review-rail-footer";
 
 // Toolbar
 export { TwToolbar, type TwToolbarProps } from "./toolbar/tw-toolbar";
 export { TwToolbarIconButton } from "./toolbar/tw-toolbar-icon-button";
+export {
+  TwShellHeader,
+  type TwShellHeaderProps,
+  type ShellHeaderMode,
+  type ShellHeaderModeOption,
+  type ShellHeaderPrimaryAction,
+  type ShellHeaderIconAction,
+} from "./toolbar/tw-shell-header";
 export type { WorkspaceMode, ZoomLevel } from "../api/public-types";
 
 // Status
@@ -27,6 +48,18 @@ export { TwStatusBar } from "./status/tw-status-bar";
 export { TwAlertBanner } from "./chrome/tw-alert-banner";
 export { TwSelectionToolbar } from "./chrome/tw-selection-toolbar";
 
+// Chrome overlay plane (R3a — scope rail, workspace dock)
+export {
+  TwChromeOverlay,
+  type TwChromeOverlayProps,
+  TwScopeRailLayer,
+  type TwScopeRailLayerProps,
+  TwWorkspaceViewSwitcher,
+  type TwWorkspaceViewSwitcherProps,
+  type WorkspaceView,
+  type WorkspaceViewAction,
+} from "./chrome-overlay";
+
 // Session capabilities
 export {
   deriveCapabilities,

package/src/ui-tailwind/review/tw-comment-sidebar.tsx

@@ -93,10 +93,10 @@ function CommentThreadCard(props: {
       role="button"
       tabIndex={0}
       className={[
-        "cursor-pointer rounded-md bg-surface/90 px-3 py-2.5 transition-colors ring-1 ring-border/40",
+        "cursor-pointer rounded-lg bg-surface/90 px-3 py-2.5 transition-colors ring-1 ring-border/40",
         focusRingClass,
         isActive
-          ? "bg-accent-soft/40 ring-accent/25"
+          ? "bg-accent-soft/40 ring-accent/25 shadow-[var(--shadow-soft)]"
           : "hover:bg-surface",
         thread.status === "detached" ? "opacity-70" : "",
       ].join(" ")}

package/src/ui-tailwind/review/tw-rail-card.tsx

@@ -0,0 +1,150 @@
+import React, { type ReactNode } from "react";
+
+/**
+ * TwRailCard — shared editorial card primitive consumed by the runtime review
+ * rail tabs (Workflow, Comments, Changes).
+ *
+ * The card is tone-aware: the tone drives a 3px left edge rule, the eyebrow
+ * color, and the optional progress-bar fill via CSS custom properties declared
+ * in `src/ui-tailwind/theme/editor-theme.css` under `.wre-rail-card`.
+ *
+ * This primitive deliberately stays host-agnostic — no workflow, comment, or
+ * revision coupling.  Consumers pass display fields and an optional footer
+ * slot so the card can host accept/reject, reply composer, or resolve actions
+ * without the primitive owning any domain logic.
+ */
+
+export type RailCardTone =
+  | "neutral"
+  | "inReview"
+  | "blocked"
+  | "scheduled"
+  | "resolved";
+
+export interface RailCardAvatar {
+  initials: string;
+  color?: string;
+  alt?: string;
+}
+
+export interface RailCardProgress {
+  value: number;
+  total?: number;
+}
+
+export interface RailCardCounter {
+  label: string;
+  value: string;
+}
+
+export interface TwRailCardProps {
+  tone: RailCardTone;
+  eyebrow: string;
+  title: string;
+  detail?: string;
+  leadingIcon?: ReactNode;
+  avatars?: readonly RailCardAvatar[];
+  avatarOverflowCount?: number;
+  counter?: RailCardCounter;
+  progress?: RailCardProgress;
+  footer?: ReactNode;
+  onClick?: () => void;
+  onSelect?: () => void;
+  isActive?: boolean;
+  dataTestId?: string;
+}
+
+export function TwRailCard(props: TwRailCardProps) {
+  const {
+    tone,
+    eyebrow,
+    title,
+    detail,
+    leadingIcon,
+    avatars,
+    avatarOverflowCount,
+    counter,
+    progress,
+    footer,
+    onClick,
+    onSelect,
+    isActive,
+    dataTestId,
+  } = props;
+
+  const handleClick = onClick || onSelect;
+  const tag: "article" | "button" = handleClick ? "button" : "article";
+
+  const clamped = progress
+    ? Math.max(0, Math.min(1, progress.total && progress.total > 0 ? progress.value / progress.total : progress.value))
+    : 0;
+
+  const commonProps: Record<string, unknown> = {
+    className: "wre-rail-card block w-full text-left",
+    "data-tone": tone,
+    "data-active": isActive ? "true" : "false",
+    "data-testid": dataTestId,
+  };
+
+  if (handleClick) {
+    commonProps.onClick = handleClick;
+    commonProps.type = "button";
+  }
+
+  return React.createElement(
+    tag,
+    commonProps,
+    <>
+      {counter ? (
+        <span className="wre-rail-card__counter" aria-label={counter.label} title={counter.label}>
+          {counter.value}
+        </span>
+      ) : null}
+
+      <span className="wre-rail-card__eyebrow">
+        {leadingIcon ? <span aria-hidden="true">{leadingIcon}</span> : null}
+        {eyebrow}
+      </span>
+
+      <p className="wre-rail-card__title">{title}</p>
+
+      {detail ? <p className="wre-rail-card__detail">{detail}</p> : null}
+
+      {avatars && avatars.length > 0 ? (
+        <span className="wre-rail-card__avatars" aria-hidden={avatars.every((a) => !a.alt) ? "true" : undefined}>
+          {avatars.map((avatar, index) => (
+            <span
+              key={`${avatar.initials}-${index}`}
+              className="wre-rail-card__avatar"
+              style={avatar.color ? { background: avatar.color } : undefined}
+              title={avatar.alt}
+              aria-label={avatar.alt}
+            >
+              {avatar.initials}
+            </span>
+          ))}
+          {avatarOverflowCount && avatarOverflowCount > 0 ? (
+            <span className="wre-rail-card__avatar-counter">+{avatarOverflowCount}</span>
+          ) : null}
+        </span>
+      ) : null}
+
+      {footer ? <div className="wre-rail-card__footer">{footer}</div> : null}
+
+      {progress ? (
+        <span
+          className="wre-rail-card__progress"
+          role="progressbar"
+          aria-valuemin={0}
+          aria-valuemax={progress.total ?? 1}
+          aria-valuenow={progress.value}
+        >
+          <span
+            className="wre-rail-card__progress-fill"
+            style={{ width: `${Math.round(clamped * 100)}%` }}
+          />
+        </span>
+      ) : null}
+    </>,
+  );
+}

package/src/ui-tailwind/review/tw-review-rail-footer.tsx

@@ -0,0 +1,52 @@
+import React from "react";
+import { HelpCircle, Search } from "lucide-react";
+
+/**
+ * Thin pinned footer rendered at the bottom of the review rail.  The footer
+ * auto-hides when neither `onSearch` nor `helpHref` is supplied, so existing
+ * hosts that do not opt in see no change (progressive disclosure, DESIGN.md
+ * §5.4).
+ */
+export interface TwReviewRailFooterProps {
+  onSearch?: () => void;
+  helpHref?: string;
+  helpLabel?: string;
+  searchLabel?: string;
+}
+
+const focusRingClass =
+  "focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-accent focus-visible:ring-offset-1 focus-visible:ring-offset-canvas";
+
+export function TwReviewRailFooter(props: TwReviewRailFooterProps) {
+  const searchLabel = props.searchLabel ?? "SEARCH";
+  const helpLabel = props.helpLabel ?? "HELP";
+
+  if (!props.onSearch && !props.helpHref) {
+    return null;
+  }
+
+  return (
+    <footer className="flex h-10 shrink-0 items-center gap-2 border-t border-border/60 px-3">
+      {props.onSearch ? (
+        <button
+          type="button"
+          onClick={props.onSearch}
+          className={`inline-flex items-center gap-1.5 rounded-sm px-2 py-1 text-[10px] font-semibold uppercase tracking-[0.14em] text-tertiary transition-colors hover:text-secondary ${focusRingClass}`}
+        >
+          <Search aria-hidden="true" className="h-3 w-3" />
+          <span>{searchLabel}</span>
+        </button>
+      ) : null}
+
+      {props.helpHref ? (
+        <a
+          href={props.helpHref}
+          className={`inline-flex items-center gap-1.5 rounded-sm px-2 py-1 text-[10px] font-semibold uppercase tracking-[0.14em] text-tertiary transition-colors hover:text-secondary ${focusRingClass}`}
+        >
+          <HelpCircle aria-hidden="true" className="h-3 w-3" />
+          <span>{helpLabel}</span>
+        </a>
+      ) : null}
+    </footer>
+  );
+}