@beyondwork/docx-react-component 1.0.75 → 1.0.77

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

@@ -0,0 +1,230 @@
+/**
+ * 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;
+  /**
+   * When `true`, wrap the state swap in `capturePosition` /
+   * `restorePosition` so the scroll anchor block stays at the same
+   * viewport-Y across the replacement. Shipped **disabled by default**
+   * after the 2026-04-24 jump-to-top regression — re-enable under a
+   * diagnosed-safe codepath only.
+   */
+  preserveScrollAnchor?: boolean;
+  /**
+   * 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`, suppressing the
+ * selection-sync echo during the swap.
+ *
+ * Ordering invariant (regression-guarded by
+ * `preserve-position-ordering.test.ts`):
+ *
+ *   1. (optional) capture scroll anchor — gated on
+ *      `preserveScrollAnchor: true` and a live `geometryFacet`
+ *   2. suppressionRef.current = true
+ *   3. view.updateState(newState)      ← PM may fire selection events here
+ *   4. (optional) 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.
+ *
+ * **Scroll preservation is opt-in.** Shipped disabled by default
+ * after the 2026-04-24 jump-to-top regression report — enabling it
+ * requires evidence that the anchor math holds under the
+ * rebuild-effect's exact timing (PM DOM mid-mutation, observer-driven
+ * scrollTop resets, etc.). The capture/restore helpers are still
+ * exported + unit-tested for the eventual re-enable.
+ */
+export function replaceStatePreservingPosition(
+  options: ReplaceStateOptions,
+  newState: import("prosemirror-state").EditorState,
+): void {
+  const preserved = options.preserveScrollAnchor
+    ? capturePosition(options)
+    : null;
+  options.suppressionRef.current = true;
+  options.view.updateState(newState);
+  if (preserved) {
+    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);