@beyondwork/docx-react-component 1.0.36 → 1.0.38

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

@@ -0,0 +1,178 @@
+/**
+ * Scope rail layer — renders workflow scopes as a continuous zone with a
+ * gutter icon + label column OUTSIDE the document flow plus a flat block-
+ * level tint BEHIND the scoped paragraphs.
+ *
+ * Per runtime-rendering-and-chrome-phase.md §5, the rail is a projection
+ * over canonical workflow scopes; it never lives inside the PM NodeView
+ * tree.  Positions come from the render kernel's anchor index — not from
+ * DOM rect math — so the rail stays aligned across scroll, zoom, resize,
+ * and through predicted-text reconciliation.
+ */
+
+import * as React from "react";
+import {
+  inflateRect,
+  projectRectToOverlay,
+  unionRect,
+  type OverlayCoordinateSpace,
+} from "./chrome-overlay-projector";
+import type { RenderFrameRect } from "../../runtime/render";
+import type { ScopeRailSegment, ScopeRailPosture } from "../../runtime/layout";
+import type { WordReviewEditorLayoutFacet } from "../../runtime/layout";
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+export interface TwScopeRailLayerProps {
+  /** Layout facet that provides segments + anchor index. */
+  facet: WordReviewEditorLayoutFacet;
+  /** Overlay's coordinate space.  Defaults to the overlay's own origin. */
+  space?: OverlayCoordinateSpace;
+  /** Horizontal padding (px) the rail gutter occupies to the left of body. */
+  railLaneWidthPx?: number;
+  /** Optional click handler for a segment label (open-scope drawer, etc). */
+  onSegmentClick?: (segment: ScopeRailSegment) => void;
+  /** Scope id that should render with the `active` emphasis. */
+  activeScopeId?: string | null;
+  /** Test id applied to the layer root. */
+  "data-testid"?: string;
+}
+
+// ---------------------------------------------------------------------------
+// Posture → visual grammar
+// ---------------------------------------------------------------------------
+
+interface PostureStyle {
+  labelText: string;
+  icon: string; // lucide-style key; CSS ::before handles glyph in production
+  railToken: string;
+  tintToken: string;
+}
+
+const POSTURE_STYLES: Record<ScopeRailPosture, PostureStyle> = {
+  edit: { labelText: "EDIT", icon: "pencil", railToken: "accent", tintToken: "accent" },
+  suggest: { labelText: "SUGGEST", icon: "sparkles", railToken: "warning", tintToken: "warning" },
+  comment: { labelText: "COMMENT", icon: "message", railToken: "insert", tintToken: "insert" },
+  view: { labelText: "IN SCOPE", icon: "eye", railToken: "secondary", tintToken: "secondary" },
+  candidate: { labelText: "PROPOSED", icon: "flag", railToken: "warning", tintToken: "warning" },
+  "preserve-only": { labelText: "BLOCKED", icon: "lock", railToken: "danger", tintToken: "danger" },
+  "blocked-import": { labelText: "BLOCKED", icon: "lock", railToken: "danger", tintToken: "danger" },
+};
+
+// ---------------------------------------------------------------------------
+// Component
+// ---------------------------------------------------------------------------
+
+const DEFAULT_RAIL_LANE_PX = 120;
+const LABEL_WIDTH_PX = 92;
+
+export const TwScopeRailLayer: React.FC<TwScopeRailLayerProps> = ({
+  facet,
+  space,
+  railLaneWidthPx = DEFAULT_RAIL_LANE_PX,
+  onSegmentClick,
+  activeScopeId,
+  "data-testid": testId,
+}) => {
+  // Read the render frame once per paint cycle.  The facet.subscribe path
+  // already invalidates the caller's React state on layout changes, so we
+  // just read on render.
+  const frame = typeof facet.getRenderFrame === "function"
+    ? facet.getRenderFrame() ?? null
+    : null;
+  const segments = facet.getAllScopeRailSegments();
+
+  if (!frame || segments.length === 0) {
+    return null;
+  }
+
+  // Group segments by scopeId so multi-page scopes render one contiguous
+  // tint per page range.  (Per-page render happens below because each
+  // scope may span pages.)
+  const items = segments.map((segment) => {
+    const rect = resolveSegmentRect(facet, frame, segment);
+    if (!rect) return null;
+    const style = POSTURE_STYLES[segment.posture];
+    return { segment, rect, style };
+  }).filter((item): item is NonNullable<typeof item> => item !== null);
+
+  const projectorSpace: OverlayCoordinateSpace = space ?? { originLeftPx: 0, originTopPx: 0 };
+
+  return (
+    <div
+      className="wre-scope-rail-layer pointer-events-none absolute inset-0 z-20"
+      data-testid={testId ?? "scope-rail-layer"}
+      aria-hidden="false"
+      role="group"
+      aria-label="Workflow scope rail"
+    >
+      {items.map(({ segment, rect, style }) => {
+        const isActive = activeScopeId === segment.scopeId || segment.isActiveWorkItem;
+        const tintRect = inflateRect(rect, { leftPx: 4, rightPx: 4, topPx: 2, bottomPx: 2 });
+        const labelRect: RenderFrameRect = {
+          leftPx: rect.leftPx - railLaneWidthPx,
+          topPx: rect.topPx,
+          widthPx: LABEL_WIDTH_PX,
+          heightPx: Math.max(20, Math.min(rect.heightPx, 48)),
+        };
+
+        return (
+          <React.Fragment key={`${segment.scopeId}:${segment.pageIndex}:${segment.fromOffset}`}>
+            {/* Flat tint behind the scoped block region */}
+            <div
+              className={`wre-scope-rail-tint wre-scope-rail-tint-${style.tintToken} absolute ${
+                isActive ? "wre-scope-rail-tint-active" : ""
+              }`}
+              data-scope-id={segment.scopeId}
+              data-posture={segment.posture}
+              style={projectRectToOverlay(tintRect, projectorSpace)}
+            />
+            {/* Gutter label + icon outside the page frame */}
+            <button
+              type="button"
+              className={`wre-scope-rail-label wre-scope-rail-label-${style.railToken} pointer-events-auto absolute flex flex-col items-center justify-center gap-1 rounded-md text-[10px] font-semibold uppercase tracking-[0.08em] ${
+                isActive ? "wre-scope-rail-label-active" : ""
+              }`}
+              data-scope-id={segment.scopeId}
+              data-posture={segment.posture}
+              data-icon={style.icon}
+              aria-label={`${style.labelText}${segment.label ? `: ${segment.label}` : ""}`}
+              onClick={onSegmentClick ? () => onSegmentClick(segment) : undefined}
+              style={projectRectToOverlay(labelRect, projectorSpace)}
+            >
+              <span aria-hidden="true" className={`wre-scope-rail-icon wre-scope-rail-icon-${style.icon}`} />
+              <span className="wre-scope-rail-label-text">{style.labelText}</span>
+            </button>
+          </React.Fragment>
+        );
+      })}
+    </div>
+  );
+};
+
+// ---------------------------------------------------------------------------
+// Internals
+// ---------------------------------------------------------------------------
+
+function resolveSegmentRect(
+  facet: WordReviewEditorLayoutFacet,
+  _frame: { anchorIndex: { byRuntimeOffset: (offset: number) => RenderFrameRect | null } },
+  segment: ScopeRailSegment,
+): RenderFrameRect | null {
+  const fromRect = _frame.anchorIndex.byRuntimeOffset(segment.fromOffset);
+  const toRect = _frame.anchorIndex.byRuntimeOffset(Math.max(segment.fromOffset, segment.toOffset - 1));
+  const unioned = unionRect(fromRect, toRect);
+  if (unioned) return unioned;
+  // Fall back to the page rect so long scopes that can't resolve per-line
+  // still render a posture in the gutter.
+  const fallbackPage = facet.getPage(segment.pageIndex);
+  if (!fallbackPage) return null;
+  // Approximate: derive a rect from the page's body region by asking the
+  // render frame for the page rect.  Without a render kernel kernel this
+  // function returns null and the segment is skipped.
+  return null;
+}
+
+export default TwScopeRailLayer;

package/src/ui-tailwind/chrome-overlay/tw-workspace-view-switcher.tsx

@@ -0,0 +1,95 @@
+/**
+ * TwWorkspaceViewSwitcher — floating dock that sits at the bottom of the
+ * chrome overlay.  Mirrors the "WORKFLOW VIEW" bottom bar in image copy.png.
+ *
+ * Per runtime-rendering-and-chrome-phase.md §6.3, the dock is a
+ * `DraggableFloat`-compatible surface that lives inside the `ChromeOverlay`
+ * plane.  Today it ships the preset selector + the canonical workflow
+ * actions (review / comment / approve) so consumers can wire them without
+ * waiting for the full DraggableFloat primitive.
+ */
+
+import * as React from "react";
+
+export type WorkspaceView = "draft" | "layout" | "review" | "workflow";
+
+export interface WorkspaceViewAction {
+  id: string;
+  label: string;
+  icon: string;
+  onClick?: () => void;
+  disabled?: boolean;
+}
+
+export interface TwWorkspaceViewSwitcherProps {
+  activeView: WorkspaceView;
+  onViewChange?: (view: WorkspaceView) => void;
+  actions?: readonly WorkspaceViewAction[];
+  "data-testid"?: string;
+}
+
+const DEFAULT_VIEW_ORDER: readonly WorkspaceView[] = [
+  "draft",
+  "layout",
+  "review",
+  "workflow",
+];
+
+const VIEW_LABELS: Record<WorkspaceView, string> = {
+  draft: "DRAFT",
+  layout: "LAYOUT",
+  review: "REVIEW",
+  workflow: "WORKFLOW VIEW",
+};
+
+export const TwWorkspaceViewSwitcher: React.FC<TwWorkspaceViewSwitcherProps> = ({
+  activeView,
+  onViewChange,
+  actions,
+  "data-testid": testId,
+}) => {
+  return (
+    <div
+      className="wre-workspace-dock pointer-events-auto absolute left-1/2 bottom-6 z-10 -translate-x-1/2 flex items-center gap-2 rounded-full border border-border/70 bg-canvas/95 px-4 py-2 shadow-lg backdrop-blur"
+      data-testid={testId ?? "workspace-view-switcher"}
+      role="toolbar"
+      aria-label="Workspace view"
+    >
+      {DEFAULT_VIEW_ORDER.map((view) => (
+        <button
+          key={view}
+          type="button"
+          className={`wre-workspace-dock-view-btn inline-flex items-center gap-1 rounded-full px-3 py-1 text-[11px] font-semibold uppercase tracking-[0.14em] ${
+            view === activeView
+              ? "wre-workspace-dock-view-btn-active bg-primary text-white"
+              : "text-secondary hover:text-primary"
+          }`}
+          aria-pressed={view === activeView}
+          onClick={onViewChange ? () => onViewChange(view) : undefined}
+          disabled={!onViewChange}
+        >
+          <span aria-hidden="true" className="wre-workspace-dock-icon h-3 w-3" />
+          {VIEW_LABELS[view]}
+        </button>
+      ))}
+      {actions && actions.length > 0 ? (
+        <div className="wre-workspace-dock-sep mx-1 h-5 w-px bg-border" />
+      ) : null}
+      {actions?.map((action) => (
+        <button
+          key={action.id}
+          type="button"
+          className="wre-workspace-dock-action inline-flex h-7 w-7 items-center justify-center rounded-full text-secondary hover:bg-surface hover:text-primary disabled:opacity-40"
+          aria-label={action.label}
+          disabled={action.disabled}
+          onClick={action.onClick}
+          data-action-id={action.id}
+        >
+          <span aria-hidden="true" className={`wre-workspace-dock-icon wre-workspace-dock-icon-${action.icon}`} />
+        </button>
+      ))}
+    </div>
+  );
+};
+
+export default TwWorkspaceViewSwitcher;

package/src/ui-tailwind/editor-surface/fast-text-edit-lane.ts

@@ -0,0 +1,337 @@
+import type { Transaction } from "prosemirror-state";
+import type { EditorView } from "prosemirror-view";
+
+import type { TextCommandAck } from "../../api/public-types.ts";
+import type {
+  LocalEditSessionState,
+  PendingOp,
+  PredictedIntent,
+  PredictedPreImagePM,
+} from "./local-edit-session-state.ts";
+import {
+  incrementInvalidationCounter,
+  PREDICTED_LANE_COUNTERS,
+} from "./perf-probe.ts";
+import type { PositionMap } from "./pm-position-map.ts";
+import { PREDICTED_META_KEY } from "./predicted-tx-gate.ts";
+
+/**
+ * Runtime-side text command the lane dispatches synchronously after applying
+ * a predicted PM transaction. The caller (React surface) wires this to
+ * `DocumentRuntime.applyActiveStoryTextCommand(command)` and returns the ack.
+ */
+export type LaneRuntimeCommand =
+  | {
+      type: "text.insert";
+      text: string;
+      origin: { opId: string; timestamp: number };
+    }
+  | {
+      type: "text.delete-backward";
+      origin: { opId: string; timestamp: number };
+    }
+  | {
+      type: "text.delete-forward";
+      origin: { opId: string; timestamp: number };
+    }
+  | {
+      type: "paragraph.split";
+      origin: { opId: string; timestamp: number };
+    }
+  | {
+      type: "text.insert-hard-break";
+      origin: { opId: string; timestamp: number };
+    };
+
+export interface FastTextEditLaneOptions {
+  session: LocalEditSessionState;
+  getView(): EditorView | null;
+  getPositionMap(): PositionMap | null;
+  /**
+   * Synchronously dispatch the canonical runtime command. The lane expects
+   * the returned ack to classify the outcome; if the runtime throws,
+   * implementations should return a `rejected` ack rather than propagating.
+   */
+  dispatchRuntimeCommand(command: LaneRuntimeCommand): TextCommandAck;
+  /**
+   * Optional. The lane toggles this around the predicted dispatch window so
+   * the surface's selection-sync plugin stays quiet while the PM doc is
+   * ahead of the canonical position map.
+   */
+  suppressSelectionSync?: (suppressed: boolean) => void;
+  /**
+   * Optional pre-flight check. When it returns true, the lane skips the
+   * predicted PM transaction and dispatches the canonical runtime command
+   * directly. Use this for tag families (field, sdt, opaque) where the
+   * runtime would reject or diverge anyway — bailing here avoids the
+   * predicted-then-restored PM churn.
+   */
+  shouldBailBeforePredict?(
+    intent: PredictedIntent,
+    fromRuntime: number,
+    toRuntime: number,
+  ): boolean;
+  onEquivalentAck(ack: TextCommandAck): void;
+  onAdjustedAck(ack: TextCommandAck): void;
+  onRejectedAck(ack: TextCommandAck): void;
+  onStructuralDivergence(ack: TextCommandAck): void;
+  /** Optional probe hooks for perf instrumentation. */
+  probe?: {
+    markPredicted(opId: string): void;
+    markReconciled(opId: string, kind: TextCommandAck["kind"]): void;
+  };
+}
+
+export interface FastTextEditLane {
+  onInsertText(text: string): void;
+  onDeleteBackward(): void;
+  onDeleteForward(): void;
+  onSplitParagraph(): void;
+  onInsertHardBreak(): void;
+}
+
+let nextOpIdCounter = 0;
+function allocOpId(): string {
+  nextOpIdCounter += 1;
+  return `op-${Date.now().toString(36)}-${nextOpIdCounter}`;
+}
+
+export function createFastTextEditLane(
+  options: FastTextEditLaneOptions,
+): FastTextEditLane {
+  function run(
+    intent: PredictedIntent,
+    buildTx: (tr: Transaction) => Transaction | null,
+  ): void {
+    // IME composition holds the DOM range; predicting through it would
+    // fight the browser's composition DOM mutations. The bridge's
+    // compositionstart/end handlers toggle this flag on the session.
+    if (options.session.isComposing()) return;
+    const view = options.getView();
+    const positionMap = options.getPositionMap();
+    if (!view || !positionMap) return;
+
+    const opId = allocOpId();
+    const before = view.state;
+    const fromPm = Math.min(before.selection.from, before.selection.to);
+    const toPm = Math.max(before.selection.from, before.selection.to);
+
+    const tr = buildTxCompat(view, intent, buildTx);
+    if (!tr) return;
+    tr.setMeta(PREDICTED_META_KEY, { opId });
+
+    const fromRuntime = positionMap.pmToRuntime(fromPm);
+    const toRuntime = positionMap.pmToRuntime(toPm);
+
+    pushLaneDebug({
+      opId,
+      intent: intent.kind,
+      pmFrom: fromPm,
+      pmTo: toPm,
+      pmDocSize: positionMap.pmDocSize,
+      runtimeStorySize: positionMap.runtimeStorySize,
+      fromRuntime,
+      toRuntime,
+    });
+
+    if (options.shouldBailBeforePredict?.(intent, fromRuntime, toRuntime)) {
+      const ack = options.dispatchRuntimeCommand(toRuntimeCommand(intent, opId));
+      incrementInvalidationCounter(PREDICTED_LANE_COUNTERS.bailBeforePredict);
+      options.probe?.markReconciled(opId, ack.kind);
+      switch (ack.kind) {
+        case "equivalent":
+          options.session.advanceToRevision({
+            opId,
+            newRevisionToken: ack.newRevisionToken,
+          });
+          options.onEquivalentAck(ack);
+          return;
+        case "adjusted":
+          options.session.advanceToRevision({
+            opId,
+            newRevisionToken: ack.newRevisionToken,
+          });
+          options.onAdjustedAck(ack);
+          return;
+        case "rejected":
+          options.onRejectedAck(ack);
+          return;
+        case "structural-divergence":
+          options.onStructuralDivergence(ack);
+          return;
+      }
+    }
+
+    const op: PendingOp = {
+      opId,
+      intent,
+      preImagePM: { preState: before },
+      fromRuntime,
+      toRuntime,
+    };
+
+    try {
+      options.session.appendPending(op);
+      incrementInvalidationCounter(PREDICTED_LANE_COUNTERS.applied);
+      options.probe?.markPredicted(opId);
+
+      // run() is invoked synchronously from PM input handlers and JavaScript is
+      // single-threaded, so reentrancy is impossible — a plain on/off toggle is
+      // correct here; no save/restore is needed.
+      options.suppressSelectionSync?.(true);
+      view.dispatch(tr);
+      op.predictedSelectionHead = view.state.selection.head;
+
+      const ack = options.dispatchRuntimeCommand(toRuntimeCommand(intent, opId));
+      options.probe?.markReconciled(opId, ack.kind);
+
+      switch (ack.kind) {
+        case "equivalent":
+          options.session.advanceToRevision({
+            opId,
+            newRevisionToken: ack.newRevisionToken,
+          });
+          incrementInvalidationCounter(PREDICTED_LANE_COUNTERS.equivalent);
+          options.onEquivalentAck(ack);
+          return;
+        case "adjusted":
+          options.session.advanceToRevision({
+            opId,
+            newRevisionToken: ack.newRevisionToken,
+          });
+          incrementInvalidationCounter(PREDICTED_LANE_COUNTERS.adjusted);
+          options.onAdjustedAck(ack);
+          return;
+        case "rejected": {
+          const removed = options.session.rollbackOp(opId);
+          if (removed?.preImagePM) {
+            restorePreImage(view, removed.preImagePM);
+          }
+          incrementInvalidationCounter(PREDICTED_LANE_COUNTERS.rejected);
+          incrementInvalidationCounter(PREDICTED_LANE_COUNTERS.rollback);
+          options.onRejectedAck(ack);
+          return;
+        }
+        case "structural-divergence": {
+          const all = options.session.clearAllPending();
+          for (let i = all.length - 1; i >= 0; i -= 1) {
+            const pre = all[i].preImagePM;
+            if (pre) restorePreImage(view, pre);
+          }
+          incrementInvalidationCounter(PREDICTED_LANE_COUNTERS.structuralDivergence);
+          incrementInvalidationCounter(PREDICTED_LANE_COUNTERS.rollback, all.length);
+          options.onStructuralDivergence(ack);
+          return;
+        }
+      }
+    } finally {
+      options.suppressSelectionSync?.(false);
+    }
+  }
+
+  function restorePreImage(view: EditorView, pre: PredictedPreImagePM): void {
+    // view.updateState bypasses the gate's filterTransaction entirely — it is
+    // the same path the React surface uses for full rebuilds. Safe here because
+    // we are restoring a state that already existed in this same view.
+    view.updateState(pre.preState);
+  }
+
+  return {
+    onInsertText(text) {
+      run({ kind: "text.insert", text }, (tr) => tr.insertText(text));
+    },
+    onDeleteBackward() {
+      run({ kind: "text.delete-backward" }, (tr) => {
+        if (!tr.selection.empty) return tr.deleteSelection();
+        const from = tr.selection.from;
+        if (from <= 1) return null;
+        return tr.delete(from - 1, from);
+      });
+    },
+    onDeleteForward() {
+      run({ kind: "text.delete-forward" }, (tr) => {
+        if (!tr.selection.empty) return tr.deleteSelection();
+        const to = tr.selection.to;
+        if (to >= tr.doc.content.size - 1) return null;
+        return tr.delete(to, to + 1);
+      });
+    },
+    onSplitParagraph() {
+      run({ kind: "paragraph.split" }, (tr) => tr.split(tr.selection.from));
+    },
+    onInsertHardBreak() {
+      run({ kind: "text.insert-hard-break" }, (tr) => {
+        const hardBreak = tr.doc.type.schema.nodes.hard_break;
+        if (!hardBreak) return null;
+        return tr.replaceSelectionWith(hardBreak.create(), true);
+      });
+    },
+  };
+}
+
+// ----- helpers -----
+
+interface LaneDebugEntry {
+  opId: string;
+  intent: PredictedIntent["kind"];
+  pmFrom: number;
+  pmTo: number;
+  pmDocSize: number;
+  runtimeStorySize: number;
+  fromRuntime: number;
+  toRuntime: number;
+}
+
+declare global {
+  interface Window {
+    __DOCX_LANE_DEBUG__?: LaneDebugEntry[];
+  }
+}
+
+/**
+ * Push a per-keystroke trace entry to a window-attached ring buffer when
+ * `window.__DOCX_LANE_DEBUG__` exists (initialized to an empty array). The
+ * buffer is capped at 200 entries; consumers can read it from the browser
+ * console to diagnose cursor position mismatches between PM and the runtime.
+ *
+ * To enable in the browser console:
+ *   window.__DOCX_LANE_DEBUG__ = [];
+ * Then type, then:
+ *   JSON.stringify(window.__DOCX_LANE_DEBUG__, null, 2)
+ */
+function pushLaneDebug(entry: LaneDebugEntry): void {
+  if (typeof window === "undefined") return;
+  const buffer = window.__DOCX_LANE_DEBUG__;
+  if (!Array.isArray(buffer)) return;
+  buffer.push(entry);
+  if (buffer.length > 200) {
+    buffer.splice(0, buffer.length - 200);
+  }
+}
+
+function buildTxCompat(
+  view: EditorView,
+  _intent: PredictedIntent,
+  buildTx: (tr: Transaction) => Transaction | null,
+): Transaction | null {
+  return buildTx(view.state.tr);
+}
+
+function toRuntimeCommand(
+  intent: PredictedIntent,
+  opId: string,
+): LaneRuntimeCommand {
+  const origin = { opId, timestamp: Date.now() };
+  switch (intent.kind) {
+    case "text.insert":
+      return { type: "text.insert", text: intent.text, origin };
+    case "text.delete-backward":
+      return { type: "text.delete-backward", origin };
+    case "text.delete-forward":
+      return { type: "text.delete-forward", origin };
+    case "paragraph.split":
+      return { type: "paragraph.split", origin };
+    case "text.insert-hard-break":
+      return { type: "text.insert-hard-break", origin };
+  }
+}