@beyondwork/docx-react-component 1.0.35 → 1.0.37

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

@@ -0,0 +1,333 @@
+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 {
+    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 };
+  }
+}

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

@@ -0,0 +1,89 @@
+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;
+}
+
+export interface CreateLocalEditSessionStateOptions {
+  baseRevisionToken: string;
+}
+
+export function createLocalEditSessionState(
+  options: CreateLocalEditSessionStateOptions,
+): LocalEditSessionState {
+  let baseRevisionToken = options.baseRevisionToken;
+  const pendingOps: PendingOp[] = [];
+  const predictedIds = new Set<string>();
+
+  return {
+    getBaseRevisionToken: () => baseRevisionToken,
+    getPendingOps: () => pendingOps.slice(),
+    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,24 @@ export type PerfProbeKind =
   | "pm.mount"
   | "shell.render"
   | "workspace.chrome"
-  | "selection.sync";
+  | "selection.sync"
+  | "layout.incremental"
+  | "layout.full";
+
+/**
+ * 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,13 @@ export interface CommandBridgeCallbacks extends SelectionSyncCallbacks {
   onUndo: () => void;
   onRedo: () => void;
   onBlockedInput?: (command: "paste" | "drop", message: string) => 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 +76,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;

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

@@ -261,19 +261,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 +444,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);
@@ -398,7 +458,7 @@ export function buildDecorations(
           activeScopeIds.has(scope.scopeId)
         );
 
-      if (pmRange.allowInline && pmRange.from < pmRange.to) {
+      if (isSelectionZone && pmRange.allowInline && pmRange.from < pmRange.to) {
         const visibleScopeSegments = subtractInlineOverlaps(
           { from: pmRange.from, to: pmRange.to },
           lockedPmRanges.filter((range) => range.to > pmRange.from && range.from < pmRange.to),
@@ -429,8 +489,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;
+  }
+}