@beyondwork/docx-react-component 1.0.36 → 1.0.38

package/src/ui-tailwind/editor-surface/local-edit-session-state.ts

@@ -0,0 +1,100 @@
+import type { EditorState } from "prosemirror-state";
+
+/**
+ * LocalEditSessionState — internal to the mounted surface.
+ *
+ * Tracks the current canonical revision token, any predicted text ops that
+ * have been dispatched locally but not yet reconciled, and a pre-image per op
+ * so the lane can roll back on a `rejected` or `structural-divergence` ack.
+ *
+ * The lane owns all mutation of this state. No React state, no context, no
+ * event emission — purely a synchronous bookkeeping ledger.
+ */
+
+export interface PredictedPreImagePM {
+  /** Captured PM state BEFORE the predicted tx. Restored via view.updateState on rollback. */
+  preState: EditorState;
+}
+
+export type PredictedIntent =
+  | { kind: "text.insert"; text: string }
+  | { kind: "text.delete-backward" }
+  | { kind: "text.delete-forward" }
+  | { kind: "paragraph.split" }
+  | { kind: "text.insert-hard-break" };
+
+export interface PendingOp {
+  opId: string;
+  intent: PredictedIntent;
+  preImagePM: PredictedPreImagePM | null;
+  /** Runtime range the predicted tx targeted BEFORE application (selection bounds). */
+  fromRuntime: number;
+  toRuntime: number;
+  /** PM selection head after the predicted tx applied. */
+  predictedSelectionHead?: number;
+}
+
+export interface LocalEditSessionState {
+  getBaseRevisionToken(): string;
+  getPendingOps(): readonly PendingOp[];
+  appendPending(op: PendingOp): void;
+  advanceToRevision(ack: { opId: string; newRevisionToken: string }): void;
+  rollbackOp(opId: string): PendingOp | null;
+  clearAllPending(): PendingOp[];
+  hasPending(): boolean;
+  isPredicted(opId: string): boolean;
+  /**
+   * IME composition state. Set to true while the browser is composing an
+   * IME input sequence (between `compositionstart` and `compositionend`);
+   * the predicted lane must bail from `run()` when composing so IME and
+   * prediction do not fight over the same DOM range.
+   */
+  isComposing(): boolean;
+  setComposing(composing: boolean): void;
+}
+
+export interface CreateLocalEditSessionStateOptions {
+  baseRevisionToken: string;
+}
+
+export function createLocalEditSessionState(
+  options: CreateLocalEditSessionStateOptions,
+): LocalEditSessionState {
+  let baseRevisionToken = options.baseRevisionToken;
+  let composing = false;
+  const pendingOps: PendingOp[] = [];
+  const predictedIds = new Set<string>();
+
+  return {
+    getBaseRevisionToken: () => baseRevisionToken,
+    getPendingOps: () => pendingOps.slice(),
+    isComposing: () => composing,
+    setComposing: (value) => { composing = value; },
+    appendPending(op) {
+      pendingOps.push(op);
+      predictedIds.add(op.opId);
+    },
+    advanceToRevision({ opId, newRevisionToken }) {
+      const idx = pendingOps.findIndex((op) => op.opId === opId);
+      if (idx >= 0) {
+        pendingOps.splice(idx, 1);
+        predictedIds.delete(opId);
+      }
+      baseRevisionToken = newRevisionToken;
+    },
+    rollbackOp(opId) {
+      const idx = pendingOps.findIndex((op) => op.opId === opId);
+      if (idx < 0) return null;
+      const [op] = pendingOps.splice(idx, 1);
+      predictedIds.delete(opId);
+      return op;
+    },
+    clearAllPending() {
+      const all = pendingOps.splice(0, pendingOps.length);
+      predictedIds.clear();
+      return all;
+    },
+    hasPending: () => pendingOps.length > 0,
+    isPredicted: (opId) => predictedIds.has(opId),
+  };
+}

package/src/ui-tailwind/editor-surface/perf-probe.ts

@@ -1,5 +1,8 @@
 export type PerfProbeKind =
   | "typing"
+  | "typing.predicted"
+  | "typing.reconcile"
+  | "typing.divergence"
   | "selection"
   | "runtime.create"
   | "snapshot.surface"
@@ -10,7 +13,30 @@ export type PerfProbeKind =
   | "pm.mount"
   | "shell.render"
   | "workspace.chrome"
-  | "selection.sync";
+  | "selection.sync"
+  | "layout.incremental"
+  | "layout.full"
+  | "render.frame_build"
+  | "render.frame_diff"
+  | "render.decoration_resolve"
+  | "chrome.overlay_reposition"
+  | "chrome.hit_test"
+  | "rail.segment_project";
+
+/**
+ * Counter names the FastTextEditLane emits via `incrementInvalidationCounter`.
+ * Expose them as a const so integrators can read the shape without duplicating
+ * strings.
+ */
+export const PREDICTED_LANE_COUNTERS = {
+  applied: "predictions.applied",
+  equivalent: "predictions.equivalent",
+  adjusted: "predictions.adjusted",
+  rejected: "predictions.rejected",
+  rollback: "predictions.rollback",
+  structuralDivergence: "predictions.structuralDivergence",
+  bailBeforePredict: "predictions.bailBeforePredict",
+} as const;
 
 export interface PerfProbeSample {
   token: string;

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

@@ -26,6 +26,19 @@ export interface CommandBridgeCallbacks extends SelectionSyncCallbacks {
   onUndo: () => void;
   onRedo: () => void;
   onBlockedInput?: (command: "paste" | "drop", message: string) => void;
+  /**
+   * Optional. Fires on `compositionstart` (true) and `compositionend`
+   * (false). The surface forwards this to the predicted lane's session
+   * so the lane can bail from `run()` while IME is composing.
+   */
+  onCompositionChange?: (composing: boolean) => void;
+  /**
+   * Optional predicted-tx gate plugin. When provided, it replaces the
+   * default unconditional filter so the FastTextEditLane can apply
+   * registered predicted transactions locally before the canonical commit
+   * lands. When absent, the legacy "block all docChanged" behavior applies.
+   */
+  gate?: Plugin;
 }
 
 const bridgeKey = new PluginKey("command-bridge");
@@ -69,7 +82,7 @@ export function createCommandBridgePlugins(
 ): Plugin[] {
   let isComposing = false;
 
-  const filterPlugin = new Plugin({
+  const filterPlugin = callbacks.gate ?? new Plugin({
     key: bridgeKey,
     filterTransaction(tr) {
       if (!tr.docChanged) return true;
@@ -84,15 +97,20 @@ export function createCommandBridgePlugins(
     props: {
       handleDOMEvents: {
         blur() {
-          isComposing = false;
+          if (isComposing) {
+            isComposing = false;
+            callbacks.onCompositionChange?.(false);
+          }
           return false;
         },
         compositionstart() {
           isComposing = true;
+          callbacks.onCompositionChange?.(true);
           return false;
         },
         compositionend() {
           isComposing = false;
+          callbacks.onCompositionChange?.(false);
           return false;
         },
       },

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

@@ -223,6 +223,19 @@ function subtractInlineOverlaps(
   return segments.filter((segment) => segment.from < segment.to);
 }
 
+/**
+ * Rail decorations are now rendered on the `ChromeOverlay` plane via the
+ * `TwScopeRailLayer` consumer of `facet.getAllScopeRailSegments()`, not
+ * through PM Decoration.node.  This function keeps its signature so the
+ * call sites below continue to compile; it warms the range cache (which
+ * other PM decorations can still consume) but emits no node decoration.
+ *
+ * Per runtime-rendering-and-chrome-phase.md §5 the rail must live outside
+ * the PM NodeView tree so: (a) the user perceives it as chrome, not
+ * document content, (b) predicted transactions never flash rail visuals,
+ * and (c) the rail can extend into the page-margin gutter, which PM
+ * cannot paint through block decorations.
+ */
 function pushRailDecorations(
   decorations: Decoration[],
   doc: PMNode,
@@ -231,19 +244,11 @@ function pushRailDecorations(
   spec: RailDecorationSpec,
   rangeCache: Map<string, Array<{ from: number; to: number }>>,
 ): void {
+  void decorations;
+  void spec;
   const cacheKey = `${from}:${to}`;
-  const ranges = rangeCache.get(cacheKey) ?? collectRailRanges(doc, from, to);
   if (!rangeCache.has(cacheKey)) {
-    rangeCache.set(cacheKey, ranges);
-  }
-  for (const range of ranges) {
-    decorations.push(
-      Decoration.node(range.from, range.to, {
-        class: spec.className,
-        "data-workflow-rail": spec.railKind,
-        ...spec.attrs,
-      }),
-    );
+    rangeCache.set(cacheKey, collectRailRanges(doc, from, to));
   }
 }
 
@@ -261,19 +266,79 @@ export function buildDecorations(
   revisionModel: RevisionDecorationModel | undefined,
   markupDisplay: MarkupDisplay,
   showTrackedChanges = true,
-  suggestionsEnabled = false,
-  workflowScopes?: readonly WorkflowScope[],
-  activeStory: EditorStoryTarget = MAIN_STORY_TARGET,
-  workflowCandidates?: readonly WorkflowCandidateRange[],
-  workflowBlockedReasons?: readonly WorkflowBlockedCommandReason[],
-  workflowLockedZones?: readonly WorkflowLockedZone[],
-  activeWorkflowWorkItemId?: string | null,
-  activeWorkflowScopeIds?: readonly string[],
+  suggestionsEnabledOrWorkflowScopes: boolean | readonly WorkflowScope[] = false,
+  workflowScopesOrActiveStory?: readonly WorkflowScope[] | EditorStoryTarget,
+  activeStoryOrWorkflowCandidates: EditorStoryTarget | readonly WorkflowCandidateRange[] = MAIN_STORY_TARGET,
+  workflowCandidatesOrBlockedReasons?: readonly WorkflowCandidateRange[] | readonly WorkflowBlockedCommandReason[],
+  workflowBlockedReasonsOrLockedZones?: readonly WorkflowBlockedCommandReason[] | readonly WorkflowLockedZone[],
+  workflowLockedZonesOrActiveWorkItemId?: readonly WorkflowLockedZone[] | string | null,
+  activeWorkflowWorkItemIdOrScopeIds?: string | null | readonly string[],
+  activeWorkflowScopeIdsOrMetadata?: readonly string[] | readonly WorkflowMetadataMarkup[],
   workflowMetadata?: readonly WorkflowMetadataMarkup[],
 ): DecorationSet {
+  const isStoryTarget = (value: unknown): value is EditorStoryTarget =>
+    Boolean(value) &&
+    typeof value === "object" &&
+    "kind" in (value as Record<string, unknown>) &&
+    typeof (value as Record<string, unknown>).kind === "string";
+  const isStringArray = (value: unknown): value is readonly string[] =>
+    Array.isArray(value) && (value.length === 0 || typeof value[0] === "string");
+  const isWorkflowMetadataArray = (value: unknown): value is readonly WorkflowMetadataMarkup[] =>
+    Array.isArray(value) &&
+    value.length > 0 &&
+    typeof value[0] === "object" &&
+    value[0] !== null &&
+    "metadataId" in (value[0] as Record<string, unknown>);
+
+  const useLegacyShape =
+    typeof suggestionsEnabledOrWorkflowScopes !== "boolean" ||
+    isStoryTarget(workflowScopesOrActiveStory);
+  const suggestionsEnabled = useLegacyShape ? false : suggestionsEnabledOrWorkflowScopes;
+  const workflowScopes = useLegacyShape
+    ? (Array.isArray(suggestionsEnabledOrWorkflowScopes)
+      ? suggestionsEnabledOrWorkflowScopes
+      : undefined)
+    : (workflowScopesOrActiveStory as readonly WorkflowScope[] | undefined);
+  const activeStory = useLegacyShape
+    ? ((isStoryTarget(workflowScopesOrActiveStory)
+      ? workflowScopesOrActiveStory
+      : MAIN_STORY_TARGET) as EditorStoryTarget)
+    : ((activeStoryOrWorkflowCandidates as EditorStoryTarget | undefined) ?? MAIN_STORY_TARGET);
+  const workflowCandidates = useLegacyShape
+    ? (Array.isArray(activeStoryOrWorkflowCandidates)
+      ? activeStoryOrWorkflowCandidates as readonly WorkflowCandidateRange[]
+      : undefined)
+    : (workflowCandidatesOrBlockedReasons as readonly WorkflowCandidateRange[] | undefined);
+  const workflowBlockedReasons = useLegacyShape
+    ? (Array.isArray(workflowCandidatesOrBlockedReasons)
+      ? workflowCandidatesOrBlockedReasons as readonly WorkflowBlockedCommandReason[]
+      : undefined)
+    : (workflowBlockedReasonsOrLockedZones as readonly WorkflowBlockedCommandReason[] | undefined);
+  const workflowLockedZones = useLegacyShape
+    ? (Array.isArray(workflowBlockedReasonsOrLockedZones)
+      ? workflowBlockedReasonsOrLockedZones as readonly WorkflowLockedZone[]
+      : undefined)
+    : (workflowLockedZonesOrActiveWorkItemId as readonly WorkflowLockedZone[] | undefined);
+  const activeWorkflowWorkItemId = useLegacyShape
+    ? (typeof workflowLockedZonesOrActiveWorkItemId === "string" || workflowLockedZonesOrActiveWorkItemId === null
+      ? workflowLockedZonesOrActiveWorkItemId
+      : undefined)
+    : (activeWorkflowWorkItemIdOrScopeIds as string | null | undefined);
+  const activeWorkflowScopeIds = useLegacyShape
+    ? (isStringArray(activeWorkflowWorkItemIdOrScopeIds)
+      ? activeWorkflowWorkItemIdOrScopeIds as readonly string[]
+      : undefined)
+    : (activeWorkflowScopeIdsOrMetadata as readonly string[] | undefined);
+  const resolvedWorkflowMetadata = useLegacyShape
+    ? (isWorkflowMetadataArray(activeWorkflowScopeIdsOrMetadata)
+      ? activeWorkflowScopeIdsOrMetadata
+      : undefined)
+    : workflowMetadata;
+
   const decorations: Decoration[] = [];
   const railRangeCache = new Map<string, Array<{ from: number; to: number }>>();
   const activeScopeIds = new Set(activeWorkflowScopeIds ?? []);
+  const effectiveWorkflowScopes = workflowScopes ?? [];
   const lockedPmRanges = collectLockedPmRanges(workflowLockedZones, activeStory, positionMap);
 
   // Walk comment threads and create inline decorations
@@ -384,8 +449,8 @@ export function buildDecorations(
     }
   }
 
-  if (workflowScopes) {
-    for (const scope of workflowScopes) {
+  if (effectiveWorkflowScopes.length > 0) {
+    for (const scope of effectiveWorkflowScopes) {
       const scopeStoryTarget = scope.storyTarget ?? MAIN_STORY_TARGET;
       if (!storyTargetsEqual(scopeStoryTarget, activeStory)) continue;
       const pmRange = buildAnchorPmRange(scope.anchor, positionMap);
@@ -399,6 +464,11 @@ export function buildDecorations(
         );
 
       if (pmRange.allowInline && pmRange.from < pmRange.to) {
+        // Post-R3a: every workflow scope emits inline decorations with
+        // the scope-id attribution.  The flat block-tint + gutter rail
+        // render on the ChromeOverlay — PM keeps only inline class hooks
+        // so selection tools, accessibility, and host scripts can still
+        // resolve the active scope at a text offset.
         const visibleScopeSegments = subtractInlineOverlaps(
           { from: pmRange.from, to: pmRange.to },
           lockedPmRanges.filter((range) => range.to > pmRange.from && range.from < pmRange.to),
@@ -429,8 +499,8 @@ export function buildDecorations(
     }
   }
 
-  if (workflowMetadata) {
-    for (const metadata of workflowMetadata) {
+  if (resolvedWorkflowMetadata) {
+    for (const metadata of resolvedWorkflowMetadata) {
       const metadataStoryTarget = metadata.storyTarget ?? MAIN_STORY_TARGET;
       if (!storyTargetsEqual(metadataStoryTarget, activeStory)) continue;
       const pmRange = buildAnchorPmRange(metadata.anchor, positionMap);

package/src/ui-tailwind/editor-surface/predicted-position-map.ts

@@ -0,0 +1,78 @@
+import type { PositionMap } from "./pm-position-map.ts";
+import type { PendingOp } from "./local-edit-session-state.ts";
+
+/**
+ * PredictedPositionMap — layers pending predicted-op deltas on top of the
+ * canonical `PositionMap`.
+ *
+ * When there are no pending ops this passes through the canonical map
+ * unchanged. When predictions are outstanding, selection-sync and external
+ * runtime queries use this view to map runtime positions through the
+ * applied-but-not-yet-committed local edits.
+ *
+ * After a reconciled commit, the lane advances the session's base revision
+ * token and discards the corresponding predicted op; subsequent queries go
+ * through the new canonical map.
+ */
+export function createPredictedPositionMap(
+  canonical: PositionMap,
+  pendingOps: readonly PendingOp[],
+): PositionMap {
+  if (pendingOps.length === 0) return canonical;
+
+  function opsBefore(runtimePos: number): number {
+    let delta = 0;
+    for (const op of pendingOps) {
+      if (op.fromRuntime <= runtimePos) {
+        delta += opSizeDelta(op);
+      }
+    }
+    return delta;
+  }
+
+  return {
+    runtimeToPm(runtimePos) {
+      return canonical.runtimeToPm(runtimePos) + opsBefore(runtimePos);
+    },
+    pmToRuntime(pmPos) {
+      let adjusted = pmPos;
+      for (const op of pendingOps) {
+        const opPmStart = canonical.runtimeToPm(op.fromRuntime);
+        if (adjusted > opPmStart) {
+          adjusted -= opSizeDelta(op);
+        }
+      }
+      return canonical.pmToRuntime(Math.max(1, adjusted));
+    },
+    get pmDocSize() {
+      return canonical.pmDocSize + totalDelta(pendingOps);
+    },
+    get runtimeStorySize() {
+      return canonical.runtimeStorySize + totalDelta(pendingOps);
+    },
+  };
+}
+
+function totalDelta(pendingOps: readonly PendingOp[]): number {
+  let delta = 0;
+  for (const op of pendingOps) {
+    delta += opSizeDelta(op);
+  }
+  return delta;
+}
+
+function opSizeDelta(op: PendingOp): number {
+  switch (op.intent.kind) {
+    case "text.insert":
+      return op.intent.text.length;
+    case "text.delete-backward":
+    case "text.delete-forward":
+      return -(op.toRuntime - op.fromRuntime);
+    case "paragraph.split":
+      return 2;
+    case "text.insert-hard-break":
+      return 1;
+    default:
+      return 0;
+  }
+}

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);
+    },
+  });
+}