@beyondwork/docx-react-component 1.0.75 → 1.0.76

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@beyondwork/docx-react-component",
   "publisher": "beyondwork",
-  "version": "1.0.75",
+  "version": "1.0.76",
   "description": "Embeddable React Word (docx) editor with review, comments, tracked changes, and round-trip OOXML fidelity.",
   "type": "module",
   "sideEffects": [

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

@@ -123,7 +123,7 @@ export function createFastTextEditLane(
     const fromRuntime = positionMap.pmToRuntime(fromPm);
     const toRuntime = positionMap.pmToRuntime(toPm);
 
-    pushLaneDebug({
+    const debugEntry = pushLaneDebug({
       opId,
       intent: intent.kind,
       pmFrom: fromPm,
@@ -137,6 +137,7 @@ export function createFastTextEditLane(
     if (options.shouldBailBeforePredict?.(intent, fromRuntime, toRuntime)) {
       const ack = options.dispatchRuntimeCommand(toRuntimeCommand(intent, opId));
       incrementInvalidationCounter(PREDICTED_LANE_COUNTERS.bailBeforePredict);
+      markLaneDebugReconciled(debugEntry, ack.kind, true);
       options.probe?.markReconciled(opId, ack.kind);
       switch (ack.kind) {
         case "equivalent":
@@ -183,6 +184,7 @@ export function createFastTextEditLane(
       op.predictedSelectionHead = view.state.selection.head;
 
       const ack = options.dispatchRuntimeCommand(toRuntimeCommand(intent, opId));
+      markLaneDebugReconciled(debugEntry, ack.kind, false);
       options.probe?.markReconciled(opId, ack.kind);
 
       switch (ack.kind) {
@@ -280,6 +282,14 @@ interface LaneDebugEntry {
   runtimeStorySize: number;
   fromRuntime: number;
   toRuntime: number;
+  /** Dispatch → reconcile observation. Filled by `markLaneDebugReconciled`. */
+  ackKind?: TextCommandAck["kind"];
+  /** Wall-clock ms between `pushLaneDebug` and `markLaneDebugReconciled`. */
+  reconcileMs?: number;
+  /** Whether the lane short-circuited to dispatch-only (no predicted TX). */
+  bailed?: boolean;
+  /** Wall-clock timestamp at push time — used to compute reconcileMs. */
+  startedAtMs: number;
 }
 
 declare global {
@@ -294,19 +304,48 @@ declare global {
  * buffer is capped at 200 entries; consumers can read it from the browser
  * console to diagnose cursor position mismatches between PM and the runtime.
  *
+ * Returns the pushed entry (or `null` when the buffer isn't enabled) so
+ * the caller can mutate it in place with ack-kind + reconcile timing
+ * via `markLaneDebugReconciled` once the runtime dispatch returns.
+ *
  * 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;
+function pushLaneDebug(
+  entry: Omit<LaneDebugEntry, "startedAtMs">,
+): LaneDebugEntry | null {
+  if (typeof window === "undefined") return null;
   const buffer = window.__DOCX_LANE_DEBUG__;
-  if (!Array.isArray(buffer)) return;
-  buffer.push(entry);
+  if (!Array.isArray(buffer)) return null;
+  const full: LaneDebugEntry = {
+    ...entry,
+    startedAtMs:
+      typeof performance !== "undefined" && typeof performance.now === "function"
+        ? performance.now()
+        : Date.now(),
+  };
+  buffer.push(full);
   if (buffer.length > 200) {
     buffer.splice(0, buffer.length - 200);
   }
+  return full;
+}
+
+function markLaneDebugReconciled(
+  entry: LaneDebugEntry | null,
+  ackKind: TextCommandAck["kind"],
+  bailed: boolean,
+): void {
+  if (!entry) return;
+  entry.ackKind = ackKind;
+  entry.bailed = bailed;
+  const now =
+    typeof performance !== "undefined" && typeof performance.now === "function"
+      ? performance.now()
+      : Date.now();
+  entry.reconcileMs = now - entry.startedAtMs;
 }
 
 function buildTxCompat(

package/src/ui-tailwind/editor-surface/preserve-position.ts

@@ -0,0 +1,211 @@
+/**
+ * Snapshot-replacement position-preservation funnel.
+ *
+ * `view.updateState()` replaces the PM document wholesale after an
+ * `adjusted` / `rejected` / `structural-divergence` ack, after a
+ * progressive-surface swap, or after any structural edit that falls off
+ * the predicted-lane short-circuit. Between the capture and restore
+ * points, the scroll container's `scrollTop` may end up pointing at a
+ * different document position because blocks above the viewport changed
+ * height. This helper wraps a replacement `fn` so the anchor block
+ * stays at the same viewport-Y before and after.
+ *
+ * The helper builds on `findScrollAnchor` / `restoreScrollAnchor`
+ * (scroll-anchor.ts) — those already honor the
+ * `geometry:allow-dom-fallback` discipline: geometry facet first, DOM
+ * `getBoundingClientRect` only when the facet can't resolve. The helper
+ * inherits that discipline so the per-keystroke path never measures DOM
+ * (performance invariant 7); DOM reads fire only on the cold-open
+ * branch before the render kernel's first frame.
+ *
+ * Focus preservation: `EditorView.updateState` already preserves DOM
+ * focus on the view's root when the prior state was focused. This helper
+ * does not force focus back — it only captures `hadFocus` for
+ * observability so tests can assert focus invariants externally.
+ */
+
+import type { EditorView } from "prosemirror-view";
+
+import type { GeometryFacet } from "../../api/public-types.ts";
+import {
+  findScrollAnchor,
+  restoreScrollAnchor,
+  type ScrollAnchor,
+} from "./scroll-anchor.ts";
+
+/**
+ * Scroll-container discovery selector — matches the shell's scroll root
+ * marker. Kept in sync with the selector used by
+ * `tw-prosemirror-surface.tsx` selection-toolbar anchoring and
+ * `tw-review-workspace.tsx` mode-toggle anchoring.
+ */
+const SCROLL_ROOT_SELECTOR = "[data-wre-scroll-root='true']";
+
+export interface PreservePositionOptions {
+  /** The PM view whose state is about to be replaced. */
+  view: EditorView;
+  /**
+   * Geometry facet from the runtime. When supplied, capture + restore
+   * read block rects from the render kernel instead of the DOM (warm
+   * path — no layout thrashing).
+   */
+  geometryFacet?: GeometryFacet;
+  /**
+   * Explicit scroll-container override. Defaults to
+   * `view.dom.closest("[data-wre-scroll-root='true']")`. Tests pass an
+   * element directly to avoid the DOM lookup.
+   */
+  scrollRoot?: HTMLElement | null;
+}
+
+export interface PreservedPosition {
+  scrollRoot: HTMLElement | null;
+  anchor: ScrollAnchor | null;
+  /** `scrollRoot.scrollTop` at capture time. Retained for regression-test assertions. */
+  scrollTop: number;
+  /** Whether the view held DOM focus at capture time. Observability only. */
+  hadFocus: boolean;
+}
+
+/**
+ * Capture the scroll-anchor state of the view's scroll container.
+ *
+ * Returns a record with `anchor: null` when no `[data-block-id]`
+ * descendants exist (typical for empty docs or pre-mount), which makes
+ * the paired `restorePosition` call a graceful no-op.
+ */
+export function capturePosition(
+  options: PreservePositionOptions,
+): PreservedPosition {
+  const scrollRoot = resolveScrollRoot(options);
+  const anchor = findScrollAnchor(scrollRoot, {
+    geometryFacet: options.geometryFacet,
+  });
+  return {
+    scrollRoot,
+    anchor,
+    scrollTop: scrollRoot ? scrollRoot.scrollTop : 0,
+    hadFocus: options.view.hasFocus(),
+  };
+}
+
+/**
+ * Restore the scroll container's position so the anchor block sits at
+ * the same viewport-Y it had at capture time.
+ *
+ * Graceful no-op when the scroll root is gone, when no anchor was
+ * captured, or when the anchor's block no longer exists in the new
+ * document (e.g. the block was deleted by the replacement). The
+ * scroll-anchor helpers in scroll-anchor.ts handle each of these cases
+ * internally.
+ */
+export function restorePosition(
+  captured: PreservedPosition,
+  options: PreservePositionOptions,
+): void {
+  if (!captured.scrollRoot || !captured.anchor) return;
+  restoreScrollAnchor(captured.scrollRoot, captured.anchor, {
+    geometryFacet: options.geometryFacet,
+  });
+}
+
+/**
+ * Execute `fn` with position preservation. Captures the scroll-anchor
+ * before `fn` runs, invokes `fn` synchronously, then restores the
+ * anchor so the user's viewport lands on the same block.
+ *
+ * Returns `fn`'s return value so callers can thread state through
+ * without a wrapping closure.
+ *
+ * Intentionally synchronous — async variants would require a
+ * two-step microtask dance we don't need today. When a caller needs a
+ * deferred restore (e.g. to wait for a second paint), use
+ * `capturePosition` / `restorePosition` directly and schedule the
+ * restore via `requestAnimationFrame` like `tw-review-workspace.tsx`
+ * does for the mode toggle.
+ */
+export function preservePosition<T>(
+  options: PreservePositionOptions,
+  fn: () => T,
+): T {
+  const captured = capturePosition(options);
+  const result = fn();
+  restorePosition(captured, options);
+  return result;
+}
+
+function resolveScrollRoot(
+  options: PreservePositionOptions,
+): HTMLElement | null {
+  if (options.scrollRoot !== undefined) return options.scrollRoot;
+  const dom = options.view.dom;
+  if (!(dom instanceof HTMLElement)) return null;
+  return dom.closest<HTMLElement>(SCROLL_ROOT_SELECTOR);
+}
+
+/**
+ * Mutable ref shape for the echo-suppression flag. Kept minimal so
+ * callers can pass a `useRef` object or a stub in tests without
+ * importing React types here.
+ */
+export interface EchoSuppressionRef {
+  current: boolean;
+}
+
+export interface ReplaceStateOptions extends PreservePositionOptions {
+  /**
+   * Ref whose `.current` is read by the selection-sync plugin. The
+   * helper sets it to `true` before the replacement and releases it to
+   * `false` inside a microtask that runs AFTER the state swap — the
+   * ordering invariant tested by
+   * `preserve-position-ordering.test.ts`.
+   */
+  suppressionRef: EchoSuppressionRef;
+  /**
+   * Microtask scheduler. Defaults to the global `queueMicrotask`.
+   * Tests override it to capture the release callback.
+   */
+  scheduleMicrotask?: (callback: () => void) => void;
+}
+
+/**
+ * Replace the view's state with `newState` while preserving the user's
+ * scroll position AND suppressing the selection-sync echo that would
+ * otherwise fire when PM dispatches its internal selection-change
+ * notifications during the swap.
+ *
+ * Ordering invariant (regression-guarded):
+ *
+ *   1. capture scroll anchor
+ *   2. suppressionRef.current = true
+ *   3. view.updateState(newState)      ← PM may fire selection events here
+ *   4. restore scroll anchor
+ *   5. queueMicrotask(() => suppressionRef.current = false)
+ *
+ * The microtask release guarantees the flag is still `true` for any
+ * synchronous selection-change handler that fires during (3), and
+ * false by the time any subsequent user-initiated selection change
+ * reaches the selection-sync plugin.
+ *
+ * Using `queueMicrotask` rather than `setTimeout(..., 0)` /
+ * `requestAnimationFrame` is deliberate — a later scheduler would
+ * leave the flag stuck true across a macrotask boundary, causing
+ * legitimate post-swap selection changes to be swallowed.
+ */
+export function replaceStatePreservingPosition(
+  options: ReplaceStateOptions,
+  newState: import("prosemirror-state").EditorState,
+): void {
+  const preserved = capturePosition(options);
+  options.suppressionRef.current = true;
+  options.view.updateState(newState);
+  restorePosition(preserved, options);
+  const release = () => {
+    options.suppressionRef.current = false;
+  };
+  if (options.scheduleMicrotask) {
+    options.scheduleMicrotask(release);
+  } else {
+    queueMicrotask(release);
+  }
+}

package/src/ui-tailwind/editor-surface/scroll-anchor.ts

@@ -143,11 +143,14 @@ export function restoreScrollAnchor(
     const geometry = options.geometryFacet.getBlock(anchor.blockId);
     if (geometry && geometry.rects.length > 0) {
       const rect = geometry.rects[0]!;
-      // We want, post-restore, the frame-local y of the block's top to
-      // land at `scrollTop + offsetWithinBlock`-below-viewport-top.
-      // Equivalently, set scrollTop so that the block's top is
-      // `offsetWithinBlock` above it.
-      root.scrollTop = rect.topPx - anchor.offsetWithinBlock;
+      // `offsetWithinBlock = viewportTopFramePx - blockTop` at capture
+      // time (see `findScrollAnchor` above), i.e. how far INTO the
+      // block the viewport top sat. To land the viewport at the same
+      // relative point inside the block in the new frame:
+      //   newScrollTop = newBlockTop + offsetWithinBlock.
+      // Matches the DOM-path formula below (round-trip verified by
+      // `test/ui/mode-toggle-scroll-anchor.test.ts`).
+      root.scrollTop = rect.topPx + anchor.offsetWithinBlock;
       return;
     }
     // No block match through facet; fall through to DOM path.

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

@@ -65,6 +65,7 @@ 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 { replaceStatePreservingPosition } from "./preserve-position";
 import {
   createScopeTagRegistry,
   type ScopeTagRegistry,
@@ -772,11 +773,35 @@ export const TwProseMirrorSurface = forwardRef<
       laneRef.current = null;
       return;
     }
+    // Wave 1 Slice E1/E2 — lane observability.
+    //
+    // `typing.reconcile` measures the dispatch → ack window per keystroke
+    // (predicted path). `typing.divergence` fires on the
+    // structural-divergence ack kind (the rollback-all path). Both probe
+    // kinds are declared in `PerfProbeKind` and were previously
+    // unemitted — wiring them here closes the instrumentation gap so
+    // lane quality regressions show up in the standard perf summary.
+    const pendingReconcileTokens = new Map<string, string | null>();
     laneRef.current = createFastTextEditLane({
       session: sessionRef.current,
       getView: () => viewRef.current,
       getPositionMap: () => positionMapRef.current,
       dispatchRuntimeCommand: props.dispatchRuntimeCommand,
+      probe: {
+        markPredicted(opId: string) {
+          pendingReconcileTokens.set(opId, startPerfProbe("typing.reconcile"));
+        },
+        markReconciled(opId: string, kind) {
+          const token = pendingReconcileTokens.get(opId);
+          if (token !== undefined) {
+            finishPerfProbe(token);
+            pendingReconcileTokens.delete(opId);
+          }
+          if (kind === "structural-divergence") {
+            recordPerfSample("typing.divergence");
+          }
+        },
+      },
       suppressSelectionSync: (suppressed) => {
         suppressSelectionEchoRef.current = suppressed;
       },
@@ -891,11 +916,30 @@ export const TwProseMirrorSurface = forwardRef<
       viewRef.current = view;
       recordPerfSample("pm.mount");
     } else {
-      suppressSelectionEchoRef.current = true;
-      viewRef.current.updateState(state);
-      queueMicrotask(() => {
-        suppressSelectionEchoRef.current = false;
-      });
+      // Wave 1 Slice C · the single funnel for snapshot replacement.
+      //
+      // `replaceStatePreservingPosition` encapsulates two invariants:
+      //   1. Scroll position preservation — capture the anchor block
+      //      before `view.updateState`, restore scroll after, so the
+      //      user's viewport doesn't jump when blocks above change
+      //      height (invariant 7: geometry-facet warm path, no DOM
+      //      measurement on the hot path).
+      //   2. Echo-suppression ordering — `suppressSelectionEchoRef` is
+      //      set to `true` BEFORE the state swap and released in a
+      //      microtask AFTER, so PM's internal selection-change events
+      //      during the swap are swallowed by the selection-sync
+      //      plugin.
+      //
+      // Ordering is regression-guarded by
+      // `test/ui-tailwind/editor-surface/preserve-position-ordering.test.ts`.
+      replaceStatePreservingPosition(
+        {
+          view: viewRef.current,
+          geometryFacet: props.geometryFacet,
+          suppressionRef: suppressSelectionEchoRef,
+        },
+        state,
+      );
     }
     documentBuildKeyRef.current = documentBuildKey;
     applyDecorationProps(viewRef.current, positionMap);