@beyondwork/docx-react-component 1.0.87 → 1.0.88

package/package.json

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

package/src/runtime/document-runtime.ts

@@ -124,6 +124,7 @@ import {
   MAIN_STORY_TARGET,
   storyTargetsEqual,
   type EditorAnchorProjection as InternalEditorAnchorProjection,
+  type TransactionMapping,
 } from "../core/selection/mapping.ts";
 import {
   toInternalAnchorProjection,
@@ -1174,6 +1175,8 @@ export function createDocumentRuntime(
   // to a single microtask-deferred emit. Declared early because emit() (which
   // checks this flag) runs during construction.
   let analyticsEmitScheduled = false;
+  let analyticsEmitScheduleMode: "none" | "microtask" | "idle" = "none";
+  let deferNextContextAnalyticsEmit = false;
 
   // V6c — heading fingerprint for TOC auto-invalidation. Compared in notify();
   // a mismatch schedules a microtask refresh of TOC fields.
@@ -1380,6 +1383,8 @@ export function createDocumentRuntime(
   let viewportBlockRanges: readonly { start: number; end: number }[] | null = null;
   /** Serialized fingerprint of the active ranges — used as the idempotency key for `refreshSurfaceOnly`. */
   let viewportRangesKey: string = serializeViewportRanges(null);
+  const EDITING_CORRIDOR_BLOCK_RADIUS = 8;
+  const EDITING_CORRIDOR_MIN_BLOCKS = 24;
 
   function applyViewportRanges(
     incoming: readonly { start: number; end: number }[] | null,
@@ -1567,19 +1572,35 @@ export function createDocumentRuntime(
   function getCachedSurface(
     document: CanonicalDocumentEnvelope,
     nextActiveStory: EditorStoryTarget,
+    options: {
+      viewportBlockRangesOverride?: readonly { start: number; end: number }[] | null;
+      enrichCulledPlaceholders?: boolean;
+    } = {},
   ): RuntimeRenderSnapshot["surface"] {
     const activeStoryKey = storyTargetKey(nextActiveStory);
+    const surfaceViewportRanges =
+      "viewportBlockRangesOverride" in options
+        ? options.viewportBlockRangesOverride ?? null
+        : viewportBlockRanges;
+    const surfaceViewportRangesKey =
+      "viewportBlockRangesOverride" in options
+        ? serializeViewportRanges(surfaceViewportRanges)
+        : viewportRangesKey;
+    const surfaceCacheKey =
+      options.enrichCulledPlaceholders === false
+        ? `${surfaceViewportRangesKey}|raw-placeholders`
+        : surfaceViewportRangesKey;
     if (
       cachedSurface &&
       cachedSurface.revisionToken === state.revisionToken &&
       cachedSurface.activeStoryKey === activeStoryKey &&
-      cachedSurface.viewportRangesKey === viewportRangesKey
+      cachedSurface.viewportRangesKey === surfaceCacheKey
     ) {
       return cachedSurface.snapshot;
     }
 
     const snapshot = createEditorSurfaceSnapshot(document, state.selection, nextActiveStory, {
-      viewportBlockRanges,
+      viewportBlockRanges: surfaceViewportRanges,
       ...(effectiveMarkupModeProvider
         ? { getEffectiveMarkupMode: effectiveMarkupModeProvider }
         : {}),
@@ -1605,20 +1626,57 @@ export function createDocumentRuntime(
     //
     // No-op on pre-pagination calls (engine not yet ready → empty map)
     // and on the inert facet.
-    const enrichedSnapshot = enrichCulledPlaceholdersWithHeights(snapshot);
+    const enrichedSnapshot =
+      options.enrichCulledPlaceholders === false
+        ? snapshot
+        : enrichCulledPlaceholdersWithHeights(snapshot);
     cachedSurface = {
       revisionToken: state.revisionToken,
       activeStoryKey,
-      viewportRangesKey,
+      viewportRangesKey: surfaceCacheKey,
       snapshot: enrichedSnapshot,
     };
     // Keep the scroll-path fingerprint in lockstep so a subsequent
     // `maybeRefreshSurfaceForViewport` sees the freshly-built snapshot
     // and short-circuits instead of paying a redundant projection.
-    cachedSurfaceFingerprint = `${state.revisionToken}|${activeStoryKey}|${viewportRangesKey}|${String(state.selection.anchor)}:${String(state.selection.head)}`;
+    cachedSurfaceFingerprint = `${state.revisionToken}|${activeStoryKey}|${surfaceCacheKey}|${String(state.selection.anchor)}:${String(state.selection.head)}`;
     return enrichedSnapshot;
   }
 
+  function getLocalTextCommitViewportRanges(
+    previousSurface: RuntimeRenderSnapshot["surface"] | undefined,
+  ): readonly { start: number; end: number }[] | null {
+    if (!previousSurface || previousSurface.blocks.length < EDITING_CORRIDOR_MIN_BLOCKS) {
+      return viewportBlockRanges;
+    }
+    const caretBlockIndex = findSurfaceBlockIndexForSelection(previousSurface, state.selection);
+    if (caretBlockIndex === -1) {
+      return viewportBlockRanges;
+    }
+    const corridor = {
+      start: Math.max(0, caretBlockIndex - EDITING_CORRIDOR_BLOCK_RADIUS),
+      end: Math.min(previousSurface.blocks.length, caretBlockIndex + EDITING_CORRIDOR_BLOCK_RADIUS + 1),
+    };
+    return normalizeViewportRanges([...(viewportBlockRanges ?? []), corridor]);
+  }
+
+  function findSurfaceBlockIndexForSelection(
+    surface: RuntimeRenderSnapshot["surface"],
+    selection: EditorState["selection"],
+  ): number {
+    if (!surface) return -1;
+    const from = Math.min(selection.anchor, selection.head);
+    const to = Math.max(selection.anchor, selection.head);
+    for (let index = 0; index < surface.blocks.length; index += 1) {
+      const block = surface.blocks[index];
+      if (!block) continue;
+      if (to >= block.from && from <= block.to) {
+        return index;
+      }
+    }
+    return -1;
+  }
+
   function enrichCulledPlaceholdersWithHeights(
     snapshot: EditorSurfaceSnapshot,
   ): EditorSurfaceSnapshot {
@@ -2469,6 +2527,57 @@ export function createDocumentRuntime(
     return snapshot;
   }
 
+  function refreshLocalTextCommitSnapshot(
+    surface: RuntimeRenderSnapshot["surface"],
+    mapping: TransactionMapping,
+  ): RuntimeRenderSnapshot {
+    perfCounters.increment("refresh.localTextEquivalent");
+    return {
+      ...cachedRenderSnapshot,
+      documentId: state.documentId,
+      sessionId: state.sessionId,
+      sourceLabel: state.sourceLabel,
+      revisionToken: state.revisionToken,
+      isReady: state.phase === "ready",
+      isDirty: state.isDirty,
+      readOnly: state.readOnly,
+      documentMode: viewState.documentMode,
+      selection: toPublicSelectionSnapshot(state.selection, activeStory),
+      activeStory,
+      documentStats: updateDocumentStatsForLocalTextCommit(
+        cachedRenderSnapshot.documentStats,
+        mapping,
+      ),
+      warnings: cachedRenderSnapshot.warnings,
+      fatalError: state.fatalError ? toPublicError(state.fatalError) : undefined,
+      commandState: {
+        canUndo: history.past.length > 0,
+        canRedo: history.future.length > 0,
+        readOnly: state.readOnly,
+      },
+      surface,
+      protectionSnapshot,
+      grabbedObjectId: grabState.objectId,
+    };
+  }
+
+  function updateDocumentStatsForLocalTextCommit(
+    previousStats: RuntimeRenderSnapshot["documentStats"],
+    mapping: TransactionMapping,
+  ): RuntimeRenderSnapshot["documentStats"] {
+    if (!previousStats) {
+      return toPublicDocumentStats(state);
+    }
+    let delta = 0;
+    for (const step of mapping.steps) {
+      delta += step.insertSize - Math.max(0, step.to - step.from);
+    }
+    return {
+      ...previousStats,
+      storyLength: Math.max(0, previousStats.storyLength + delta),
+    };
+  }
+
   /**
    * Fingerprint over the inputs that the viewport-refresh fast-path knows
    * about. Used to short-circuit {@link maybeRefreshSurfaceForViewport}
@@ -4892,14 +5001,52 @@ export function createDocumentRuntime(
       history.future = [];
     }
 
-    applyTransactionToState(transaction);
+    applyTransactionToState(transaction, { allowLocalTextFastPath: true });
   }
 
   function commitRemote(transaction: EditorTransaction): void {
     applyTransactionToState(transaction);
   }
 
-  function applyTransactionToState(transaction: EditorTransaction): void {
+  function shouldUseLocalTextCommitSnapshot(
+    previous: EditorState,
+    next: EditorState,
+    transaction: EditorTransaction,
+    effects: EditorTransaction["effects"],
+  ): boolean {
+    if (activeStory.kind !== "main") return false;
+    if (!transaction.markDirty || transaction.mapping.steps.length === 0) {
+      return false;
+    }
+    if (transaction.mapping.metadata?.invalidatesStructures) {
+      return false;
+    }
+    if (previous.document.subParts !== next.document.subParts) {
+      return false;
+    }
+    if (effects.warningsAdded.length > 0 || effects.warningsCleared.length > 0) {
+      return false;
+    }
+    if ((effects.transientWarnings?.length ?? 0) > 0) {
+      return false;
+    }
+    return (
+      !effects.commentAdded &&
+      !effects.commentResolved &&
+      !effects.commentReopened &&
+      !effects.commentReplyAdded &&
+      !effects.commentBodyEdited &&
+      !effects.changeAccepted &&
+      !effects.changeRejected &&
+      !effects.revisionAuthored &&
+      !effects.commandBlocked
+    );
+  }
+
+  function applyTransactionToState(
+    transaction: EditorTransaction,
+    options: { allowLocalTextFastPath?: boolean } = {},
+  ): void {
     // Pure-no-op short-circuit: when a reducer skipped without emitting any
     // observable effect AND the selection is identical, skip finalizeState
     // / invalidate / refresh / notify entirely. This keeps hot paths (e.g.
@@ -4941,7 +5088,9 @@ export function createDocumentRuntime(
     const previous = state;
 
     const tApply0 = performance.now();
+    const tProtection0 = performance.now();
     protectionSnapshot = remapProtectionSnapshot(protectionSnapshot, transaction.mapping);
+    perfCounters.increment("commit.protectionRemap.us", Math.round((performance.now() - tProtection0) * 1000));
     const tFinalize0 = performance.now();
     state = finalizeState(transaction.nextState, transaction.markDirty, clock());
     perfCounters.increment("commit.finalizeState.us", Math.round((performance.now() - tFinalize0) * 1000));
@@ -4949,8 +5098,10 @@ export function createDocumentRuntime(
     // Re-sync marker-backed scope IDs against the new document; the
     // store handles set computation + telemetry. `replaceOverlay(current, doc)`
     // is idempotent on state and re-derives the marker-backed set.
+    const tOverlay0 = performance.now();
     overlayStore.replaceOverlay(overlayStore.getOverlay(), state.document);
     const detachedWorkflowScopeWarnings = syncDetachedWorkflowScopeWarningsInState();
+    perfCounters.increment("commit.overlaySync.us", Math.round((performance.now() - tOverlay0) * 1000));
 
     const tInvalidate0 = performance.now();
     if (transaction.markDirty && transaction.mapping.steps.length > 0) {
@@ -4974,12 +5125,37 @@ export function createDocumentRuntime(
     }
     perfCounters.increment("commit.invalidate.us", Math.round((performance.now() - tInvalidate0) * 1000));
 
+    const notifyEffects: EditorTransaction["effects"] = {
+      ...transaction.effects,
+      warningsAdded: [
+        ...transaction.effects.warningsAdded,
+        ...detachedWorkflowScopeWarnings.added,
+      ],
+      warningsCleared: [
+        ...transaction.effects.warningsCleared,
+        ...detachedWorkflowScopeWarnings.cleared,
+      ],
+    };
+
+    const tClassify0 = performance.now();
+    const useLocalTextCommitSnapshot =
+      options.allowLocalTextFastPath === true &&
+      shouldUseLocalTextCommitSnapshot(
+        previous,
+        state,
+        transaction,
+        notifyEffects,
+      );
+    perfCounters.increment("commit.refreshClassify.us", Math.round((performance.now() - tClassify0) * 1000));
+
     // I5: validate post-mutation selection against the new document bound.
     // First call to getCachedSurface() here computes the post-mutation surface
     // snapshot (cache miss — revisionToken just changed in finalizeState).
-    // refreshRenderSnapshot's internal call below hits the cache and reuses it.
-    // Net cost: identical to pre-I5 — one surface walk per commit, just shifted
-    // a few lines earlier so the validator can read storySize.
+    // For local text commits, this is an editing-corridor surface (current
+    // block plus a small halo) so the immediate typing path keeps visible
+    // truth hot without rebuilding offscreen table/comment markup. Structural,
+    // review, and warning commits still use the full current viewport surface
+    // and fall back to refreshRenderSnapshot().
     //
     // Wired ONLY at this chokepoint. The other 12 `cachedRenderSnapshot =
     // refreshRenderSnapshot()` sites in this file are intentionally skipped:
@@ -4999,7 +5175,13 @@ export function createDocumentRuntime(
     // The return type of getCachedSurface is `RuntimeRenderSnapshot["surface"]`
     // which is optional in the public API for shape-only reasons — the helper
     // itself always returns a defined snapshot.
-    const surfaceForValidation = getCachedSurface(state.document, activeStory)!;
+    const tValidation0 = performance.now();
+    const surfaceForValidation = useLocalTextCommitSnapshot
+      ? getCachedSurface(state.document, activeStory, {
+          viewportBlockRangesOverride: getLocalTextCommitViewportRanges(cachedRenderSnapshot.surface),
+          enrichCulledPlaceholders: false,
+        })!
+      : getCachedSurface(state.document, activeStory)!;
     const validationOptions = state.selection.activeRange.kind === "node"
       ? {
           isValidNodeTarget: createSurfaceNodeSelectionProbe(surfaceForValidation),
@@ -5015,26 +5197,24 @@ export function createDocumentRuntime(
       state = { ...state, selection: validatedSelection };
       storySelections.set(storyTargetKey(activeStory), state.selection);
     }
+    perfCounters.increment("commit.selectionValidation.us", Math.round((performance.now() - tValidation0) * 1000));
 
     const tRefresh0 = performance.now();
-    cachedRenderSnapshot = refreshRenderSnapshot();
+    cachedRenderSnapshot = useLocalTextCommitSnapshot
+      ? refreshLocalTextCommitSnapshot(surfaceForValidation, transaction.mapping)
+      : refreshRenderSnapshot();
     perfCounters.increment("commit.refresh.us", Math.round((performance.now() - tRefresh0) * 1000));
 
     const tNotify0 = performance.now();
-    notify(previous, state, {
-      ...transaction,
-      effects: {
-        ...transaction.effects,
-        warningsAdded: [
-          ...transaction.effects.warningsAdded,
-          ...detachedWorkflowScopeWarnings.added,
-        ],
-        warningsCleared: [
-          ...transaction.effects.warningsCleared,
-          ...detachedWorkflowScopeWarnings.cleared,
-        ],
-      },
-    });
+    deferNextContextAnalyticsEmit = useLocalTextCommitSnapshot;
+    try {
+      notify(previous, state, {
+        ...transaction,
+        effects: notifyEffects,
+      });
+    } finally {
+      deferNextContextAnalyticsEmit = false;
+    }
     perfCounters.increment("commit.notify.us", Math.round((performance.now() - tNotify0) * 1000));
     perfCounters.increment("commit.total.us", Math.round((performance.now() - tApply0) * 1000));
     emitStageToken(telemetryBus, "commit", "commit.apply.complete", {
@@ -5608,23 +5788,58 @@ export function createDocumentRuntime(
   // synchronous call stack — one per commit. (Flag declared above near
   // perfCounters so it is initialized before construction-time emits run.)
   function scheduleContextAnalyticsEmit(): void {
+    const shouldDefer = deferNextContextAnalyticsEmit;
+    deferNextContextAnalyticsEmit = false;
     if (analyticsEmitScheduled) {
+      if (shouldDefer && analyticsEmitScheduleMode === "microtask") {
+        analyticsEmitScheduleMode = "idle";
+        perfCounters.increment("emit.contextAnalytics.deferred");
+        return;
+      }
       perfCounters.increment("emit.contextAnalytics.coalesced");
       return;
     }
     analyticsEmitScheduled = true;
-    queueMicrotask(() => {
+    analyticsEmitScheduleMode = shouldDefer ? "idle" : "microtask";
+    const run = () => {
       // Reset BEFORE the emit so any synchronous re-entrant emits triggered
       // by listener callbacks schedule a fresh second microtask (no lost
       // updates). Reversing this order would drop bursts originating in
       // listeners.
       analyticsEmitScheduled = false;
+      analyticsEmitScheduleMode = "none";
       const t = performance.now();
       emitContextAnalyticsChanged();
       perfCounters.increment("emit.contextAnalytics.us", Math.round((performance.now() - t) * 1000));
+    };
+    if (shouldDefer) {
+      perfCounters.increment("emit.contextAnalytics.deferred");
+      scheduleIdleContextAnalytics(run);
+      return;
+    }
+    queueMicrotask(() => {
+      if (analyticsEmitScheduleMode === "idle") {
+        scheduleIdleContextAnalytics(run);
+        return;
+      }
+      run();
     });
   }
 
+  function scheduleIdleContextAnalytics(callback: () => void): void {
+    const requestIdle = (globalThis as {
+      requestIdleCallback?: (
+        cb: () => void,
+        options?: { timeout?: number },
+      ) => number;
+    }).requestIdleCallback;
+    if (typeof requestIdle === "function") {
+      requestIdle(callback, { timeout: 250 });
+      return;
+    }
+    setTimeout(callback, 0);
+  }
+
   // V6c — TOC auto-refresh scheduler. Mirrors scheduleContextAnalyticsEmit's
   // microtask-coalesce shape. Bursts of heading edits within one synchronous
   // call stack collapse to a single rebuild + a single toc_auto_refreshed

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

@@ -29,7 +29,7 @@ import type { EditorView } from "prosemirror-view";
 import type { GeometryFacet } from "../../api/public-types.ts";
 import {
   findScrollAnchor,
-  restoreScrollAnchor,
+  resolveScrollTopForAnchor,
   type ScrollAnchor,
 } from "./scroll-anchor.ts";
 
@@ -56,6 +56,13 @@ export interface PreservePositionOptions {
    * element directly to avoid the DOM lookup.
    */
   scrollRoot?: HTMLElement | null;
+  /**
+   * Optional safety bound for edit-path restores. When set, restores whose
+   * target differs from the captured `scrollTop` by more than this many CSS
+   * pixels are refused. This keeps scroll preservation narrow for typing
+   * rebuilds while still allowing small same-story geometry shifts.
+   */
+  maxScrollDeltaPx?: number;
 }
 
 export interface PreservedPosition {
@@ -102,11 +109,29 @@ export function capturePosition(
 export function restorePosition(
   captured: PreservedPosition,
   options: PreservePositionOptions,
-): void {
-  if (!captured.scrollRoot || !captured.anchor) return;
-  restoreScrollAnchor(captured.scrollRoot, captured.anchor, {
-    geometryFacet: options.geometryFacet,
-  });
+): boolean {
+  if (!captured.scrollRoot || !captured.anchor) return false;
+  const targetScrollTop = resolveScrollTopForAnchor(
+    captured.scrollRoot,
+    captured.anchor,
+    {
+      geometryFacet: options.geometryFacet,
+    },
+  );
+  if (targetScrollTop === null || !Number.isFinite(targetScrollTop)) {
+    return false;
+  }
+  if (targetScrollTop < 0) {
+    return false;
+  }
+  if (
+    options.maxScrollDeltaPx !== undefined &&
+    Math.abs(targetScrollTop - captured.scrollTop) > options.maxScrollDeltaPx
+  ) {
+    return false;
+  }
+  captured.scrollRoot.scrollTop = targetScrollTop;
+  return true;
 }
 
 /**

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

@@ -137,7 +137,23 @@ export function restoreScrollAnchor(
   anchor: ScrollAnchor | null,
   options?: FindScrollAnchorOptions,
 ): void {
-  if (!root || !anchor) return;
+  const targetScrollTop = resolveScrollTopForAnchor(root, anchor, options);
+  if (root && targetScrollTop !== null) {
+    root.scrollTop = targetScrollTop;
+  }
+}
+
+/**
+ * Resolve the `scrollTop` that would restore `anchor` without mutating the
+ * scroll container. Used by the edit-path preservation guard so it can reject
+ * unsafe restores before writing scroll state.
+ */
+export function resolveScrollTopForAnchor(
+  root: HTMLElement | null,
+  anchor: ScrollAnchor | null,
+  options?: FindScrollAnchorOptions,
+): number | null {
+  if (!root || !anchor) return null;
 
   if (options?.geometryFacet && !options.prepaintFallback) {
     const geometry = options.geometryFacet.getBlock(anchor.blockId);
@@ -150,15 +166,14 @@ export function restoreScrollAnchor(
       //   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;
+      return rect.topPx + anchor.offsetWithinBlock;
     }
     // No block match through facet; fall through to DOM path.
   }
 
   const selector = `[data-block-id="${cssEscape(anchor.blockId)}"]`;
   const block = root.querySelector<HTMLElement>(selector);
-  if (!block) return;
+  if (!block) return null;
   // Cold-open / pre-paint DOM fallback — same rationale as
   // findScrollAnchor's fallback above.
   // geometry:allow-dom-fallback
@@ -171,7 +186,7 @@ export function restoreScrollAnchor(
   // capture time).  Scrolling by `delta` shifts rects by `-delta`, so
   // solve for delta: delta = blockRect.top - rootRect.top + offsetWithinBlock.
   const delta = blockRect.top - rootRect.top + anchor.offsetWithinBlock;
-  root.scrollTop = root.scrollTop + delta;
+  return root.scrollTop + delta;
 }
 
 /**

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

@@ -72,6 +72,7 @@ import { createPredictedTxGate } from "./predicted-tx-gate";
 import { replaceStatePreservingPosition } from "./preserve-position";
 import {
   createScopeTagRegistry,
+  storyTargetsEqual,
   type ScopeTagRegistry,
 } from "../../api/public-types";
 import { hasBailIfCrossedTagInRange } from "./predicted-tag-preflight";
@@ -92,6 +93,24 @@ import { chartNodeViews } from "./chart-node-view.tsx";
 import type { SelectionToolbarAnchor } from "../../ui/headless/selection-toolbar-model";
 import type { MediaPreviewDescriptor } from "./pm-state-from-snapshot";
 
+type RebuildScrollAnchorPolicy = "bounded-same-story";
+
+const BOUNDED_TYPING_SCROLL_RESTORE_MAX_DELTA_PX = 256;
+
+export function shouldPreserveScrollAnchorForRebuild(options: {
+  policy: RebuildScrollAnchorPolicy | null;
+  view: Pick<EditorView, "hasFocus"> | null;
+  geometryFacet?: import("../../runtime/geometry/index.ts").GeometryFacet;
+  previousStory: EditorStoryTarget | null;
+  nextStory: EditorStoryTarget;
+}): boolean {
+  if (options.policy !== "bounded-same-story") return false;
+  if (!options.view?.hasFocus()) return false;
+  if (!options.geometryFacet) return false;
+  if (!options.previousStory) return false;
+  return storyTargetsEqual(options.previousStory, options.nextStory);
+}
+
 /**
  * Build page-break widget decorations from the layout facet's current page
  * graph. Returns `[]` when the facet is unavailable, the active story is
@@ -435,6 +454,8 @@ export const TwProseMirrorSurface = forwardRef<
   const sessionRef = useRef<import("./local-edit-session-state").LocalEditSessionState | null>(null);
   const laneRef = useRef<import("./fast-text-edit-lane").FastTextEditLane | null>(null);
   const equivalentAckLedgerRef = useRef<Map<string, string>>(new Map());
+  const pendingRebuildScrollAnchorRef = useRef<RebuildScrollAnchorPolicy | null>(null);
+  const lastBuiltStoryRef = useRef<EditorStoryTarget | null>(null);
   const selectionToolbarFrameRef = useRef<number | null>(null);
   const lastSelectionToolbarMeasurementRef = useRef<{
     key: string | null;
@@ -766,6 +787,7 @@ export const TwProseMirrorSurface = forwardRef<
     if (!props.dispatchRuntimeCommand || !sessionRef.current) {
       laneRef.current = null;
       equivalentAckLedgerRef.current.clear();
+      pendingRebuildScrollAnchorRef.current = null;
       return;
     }
     // Wave 1 Slice E1/E2 — lane observability.
@@ -811,6 +833,7 @@ export const TwProseMirrorSurface = forwardRef<
         );
       },
       onEquivalentAck: (ack) => {
+        pendingRebuildScrollAnchorRef.current = null;
         if (
           ack.opId &&
           ack.newRevisionToken &&
@@ -821,16 +844,22 @@ export const TwProseMirrorSurface = forwardRef<
         }
         equivalentAckLedgerRef.current.clear();
       },
-      onAdjustedAck: () => {
+      onAdjustedAck: (ack) => {
         // Adjusted path: allow the rebuild effect to run (it will call
         // view.updateState with the canonical snapshot).
         equivalentAckLedgerRef.current.clear();
+        pendingRebuildScrollAnchorRef.current =
+          getTextCommandRefreshClass(ack) === "surface-only"
+            ? "bounded-same-story"
+            : null;
       },
       onRejectedAck: () => {
         equivalentAckLedgerRef.current.clear();
+        pendingRebuildScrollAnchorRef.current = null;
       },
       onStructuralDivergence: () => {
         equivalentAckLedgerRef.current.clear();
+        pendingRebuildScrollAnchorRef.current = null;
       },
     });
   }, [props.dispatchRuntimeCommand, scopeTagRegistry]);
@@ -839,6 +868,7 @@ export const TwProseMirrorSurface = forwardRef<
     if (!mountRef.current || !surface) return;
 
     if (viewRef.current && documentBuildKeyRef.current === documentBuildKey) {
+      pendingRebuildScrollAnchorRef.current = null;
       return;
     }
 
@@ -866,6 +896,8 @@ export const TwProseMirrorSurface = forwardRef<
       documentBuildKeyRef.current = documentBuildKey;
       applyDecorationProps(viewRef.current, positionMapRef.current);
       equivalentAckLedgerRef.current.delete(snapshot.revisionToken);
+      pendingRebuildScrollAnchorRef.current = null;
+      lastBuiltStoryRef.current = snapshot.activeStory;
       if (pendingTypingProbeRef.current) {
         finishPerfProbe(pendingTypingProbeRef.current);
         pendingTypingProbeRef.current = null;
@@ -921,24 +953,37 @@ export const TwProseMirrorSurface = forwardRef<
       // AFTER, so PM's internal selection-change events during the
       // swap are swallowed by the selection-sync plugin.
       //
-      // Scroll-anchor preservation (`preserveScrollAnchor: true`) is
-      // currently OFF by default after the 2026-04-24 jump-to-top
-      // regression report (see hotfix commit). Re-enable under a
-      // diagnosed-safe codepath only; the capture/restore helpers
-      // remain tested and ready.
+      // Scroll-anchor preservation is narrowly re-enabled only when a
+      // predicted edit receives a `surface-only` adjusted ack and the
+      // replacement stays in the same focused story with a live geometry
+      // facet. `maxScrollDeltaPx` is the guardrail: if the anchor target
+      // would move by more than the small local-edit budget, the helper
+      // refuses the restore and leaves the browser/runtime position alone.
       //
       // Ordering invariant is regression-guarded by
       // `test/ui-tailwind/editor-surface/preserve-position-ordering.test.ts`.
+      const scrollAnchorPolicy = pendingRebuildScrollAnchorRef.current;
+      pendingRebuildScrollAnchorRef.current = null;
+      const preserveScrollAnchor = shouldPreserveScrollAnchorForRebuild({
+        policy: scrollAnchorPolicy,
+        view: viewRef.current,
+        geometryFacet: props.geometryFacet,
+        previousStory: lastBuiltStoryRef.current,
+        nextStory: snapshot.activeStory,
+      });
       replaceStatePreservingPosition(
         {
           view: viewRef.current,
           geometryFacet: props.geometryFacet,
           suppressionRef: suppressSelectionEchoRef,
+          preserveScrollAnchor,
+          maxScrollDeltaPx: BOUNDED_TYPING_SCROLL_RESTORE_MAX_DELTA_PX,
         },
         state,
       );
     }
     documentBuildKeyRef.current = documentBuildKey;
+    lastBuiltStoryRef.current = snapshot.activeStory;
     applyDecorationProps(viewRef.current, positionMap);
 
     if (activeSearchRef.current) {