@beyondwork/docx-react-component 1.0.86 → 1.0.88

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

@@ -51,6 +51,7 @@ import {
 } from "./pm-command-bridge";
 import { buildDecorations } from "./pm-decorations";
 import { buildPageBreakDecorations } from "./pm-page-break-decorations";
+import { findBlockIndexRangeForPage } from "./page-slice-util.ts";
 import { DecorationSet } from "prosemirror-view";
 import type { WordReviewEditorLayoutFacet } from "../../api/public-types.ts";
 import { buildPagePreviewMaps } from "../../api/public-types";
@@ -63,11 +64,15 @@ import {
 } from "./perf-probe";
 import { buildPositionMap, type PositionMap } from "./pm-position-map";
 import { createLocalEditSessionState } from "./local-edit-session-state";
-import { createFastTextEditLane } from "./fast-text-edit-lane";
+import {
+  createFastTextEditLane,
+  getTextCommandRefreshClass,
+} from "./fast-text-edit-lane";
 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";
@@ -88,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
@@ -148,9 +171,12 @@ function buildPageBreakDecorationsFromProps(
       : undefined;
 
   // L7 Phase 2 Task 2.2.4a — compute per-page block-index ranges from the
-  // render frame's page offsets + the surface blocks list.  Each block has a
-  // `from`/`to` offset; we find the first and last block whose offset range
-  // falls within each page's [startOffset, nextPage.startOffset) window.
+  // render frame's page offsets + the surface blocks list. Each block has a
+  // `from`/`to` offset; a block belongs to every page whose offset window it
+  // overlaps. That matters for large tables/objects that can straddle a page
+  // boundary: matching only `block.from` would omit the active block from the
+  // page marker, cull it on the next viewport refresh, and remap the caret to
+  // the wrong PM position during snapshot replacement.
   // This map is passed into `buildPageBreakDecorations` so the chrome widgets
   // carry `data-page-first-block-index` / `data-page-last-block-index`
   // attributes needed by `useVisibleBlockRange`.
@@ -160,24 +186,9 @@ function buildPageBreakDecorationsFromProps(
     for (let pi = 0; pi < frame.pages.length; pi++) {
       const page = frame.pages[pi]!;
       if (page.page.isBlankFiller) continue;
-      const pageStart = page.page.startOffset;
-      const pageEnd =
-        pi + 1 < frame.pages.length
-          ? frame.pages[pi + 1]!.page.startOffset
-          : Infinity;
-      let first = -1;
-      let last = -1;
-      for (let bi = 0; bi < surfaceBlocks.length; bi++) {
-        const block = surfaceBlocks[bi]!;
-        const blockFrom = block.from;  // from is required on all SurfaceBlockSnapshot variants
-        // Block belongs to this page if its start falls within the page's offset window.
-        if (blockFrom >= pageStart && blockFrom < pageEnd) {
-          if (first === -1) first = bi;
-          last = bi;
-        }
-      }
-      if (first !== -1) {
-        blockIndexRangeByPageIndex.set(page.page.pageIndex, { first, last });
+      const range = findBlockIndexRangeForPage(surfaceBlocks, page.page);
+      if (range) {
+        blockIndexRangeByPageIndex.set(page.page.pageIndex, range);
       }
     }
   }
@@ -290,6 +301,7 @@ export interface TwProseMirrorSurfaceProps {
   }) => void;
   onCommentActivated?: (commentId: string) => void;
   onRevisionActivated?: (revisionId: string) => void;
+  onRevisionHovered?: (revisionId: string | null) => void;
   onSelectionToolbarAnchorChange?: (anchor: SelectionToolbarAnchor | null) => void;
   mediaPreviews?: Record<string, MediaPreviewDescriptor>;
   workflowScopes?: readonly WorkflowScope[];
@@ -441,7 +453,9 @@ export const TwProseMirrorSurface = forwardRef<
   const suppressSelectionEchoRef = useRef(false);
   const sessionRef = useRef<import("./local-edit-session-state").LocalEditSessionState | null>(null);
   const laneRef = useRef<import("./fast-text-edit-lane").FastTextEditLane | null>(null);
-  const equivalentAckKeyRef = useRef<string | 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;
@@ -653,10 +667,11 @@ export const TwProseMirrorSurface = forwardRef<
       createContextualInteractionPlugin({
         onCommentActivated: (commentId) => props.onCommentActivated?.(commentId),
         onRevisionActivated: (revisionId) => props.onRevisionActivated?.(revisionId),
+        onRevisionHovered: (revisionId) => props.onRevisionHovered?.(revisionId),
       }),
       createSearchPlugin(),
     ];
-  }, [props.awareness, props.onCommentActivated, props.onRevisionActivated]);
+  }, [props.awareness, props.onCommentActivated, props.onRevisionActivated, props.onRevisionHovered]);
 
   const applyDecorationProps = useCallback(
     (view: EditorView, positionMap: PositionMap): void => {
@@ -771,6 +786,8 @@ export const TwProseMirrorSurface = forwardRef<
   useEffect(() => {
     if (!props.dispatchRuntimeCommand || !sessionRef.current) {
       laneRef.current = null;
+      equivalentAckLedgerRef.current.clear();
+      pendingRebuildScrollAnchorRef.current = null;
       return;
     }
     // Wave 1 Slice E1/E2 — lane observability.
@@ -815,28 +832,34 @@ export const TwProseMirrorSurface = forwardRef<
           toRuntime,
         );
       },
-      onEquivalentAck: () => {
-        // INVARIANT: this marker is set only by onEquivalentAck, which the
-        // runtime invokes synchronously from dispatchRuntimeCommand. The
-        // rebuild effect's short-circuit (search for "Predicted-lane
-        // short-circuit" below) reads it during the same React render cycle
-        // that the predicted dispatch triggered. If the runtime ack ever
-        // becomes async (microtask, animation frame, network round-trip),
-        // this marker will be stale by the time the rebuild effect runs and
-        // the short-circuit must be replaced with a
-        // `pendingEquivalentAckOpIds: Set<string>` ledger keyed by opId.
-        equivalentAckKeyRef.current = documentBuildKeyRef.current;
+      onEquivalentAck: (ack) => {
+        pendingRebuildScrollAnchorRef.current = null;
+        if (
+          ack.opId &&
+          ack.newRevisionToken &&
+          getTextCommandRefreshClass(ack) === "local-text-equivalent"
+        ) {
+          equivalentAckLedgerRef.current.set(ack.newRevisionToken, ack.opId);
+          return;
+        }
+        equivalentAckLedgerRef.current.clear();
       },
-      onAdjustedAck: () => {
+      onAdjustedAck: (ack) => {
         // Adjusted path: allow the rebuild effect to run (it will call
         // view.updateState with the canonical snapshot).
-        equivalentAckKeyRef.current = null;
+        equivalentAckLedgerRef.current.clear();
+        pendingRebuildScrollAnchorRef.current =
+          getTextCommandRefreshClass(ack) === "surface-only"
+            ? "bounded-same-story"
+            : null;
       },
       onRejectedAck: () => {
-        equivalentAckKeyRef.current = null;
+        equivalentAckLedgerRef.current.clear();
+        pendingRebuildScrollAnchorRef.current = null;
       },
       onStructuralDivergence: () => {
-        equivalentAckKeyRef.current = null;
+        equivalentAckLedgerRef.current.clear();
+        pendingRebuildScrollAnchorRef.current = null;
       },
     });
   }, [props.dispatchRuntimeCommand, scopeTagRegistry]);
@@ -845,6 +868,7 @@ export const TwProseMirrorSurface = forwardRef<
     if (!mountRef.current || !surface) return;
 
     if (viewRef.current && documentBuildKeyRef.current === documentBuildKey) {
+      pendingRebuildScrollAnchorRef.current = null;
       return;
     }
 
@@ -852,13 +876,16 @@ export const TwProseMirrorSurface = forwardRef<
     // ack, the PM doc already matches the canonical snapshot. Update tracking
     // refs and decorations without rebuilding the PM state.
     //
-    // INVARIANT: reads `equivalentAckKeyRef.current` set by `onEquivalentAck`
-    // above. Depends on the runtime ack being synchronous so the marker is
-    // already in place when this effect runs after the predicted dispatch.
-    // See the comment at `onEquivalentAck` for the async-ack migration path.
+    // INVARIANT: equivalent acks are tracked by revision token and op id, not
+    // by the previous build key. This keeps the short-circuit valid if the ack
+    // and render snapshot stop arriving in the same synchronous React pass.
+    const equivalentAckOpId =
+      sessionRef.current && !sessionRef.current.hasPending()
+        ? equivalentAckLedgerRef.current.get(snapshot.revisionToken)
+        : undefined;
     if (
       viewRef.current &&
-      equivalentAckKeyRef.current !== null &&
+      equivalentAckOpId !== undefined &&
       sessionRef.current &&
       !sessionRef.current.hasPending() &&
       sessionRef.current.getBaseRevisionToken() === snapshot.revisionToken
@@ -868,7 +895,9 @@ export const TwProseMirrorSurface = forwardRef<
       positionMapRef.current = buildPositionMap(surface);
       documentBuildKeyRef.current = documentBuildKey;
       applyDecorationProps(viewRef.current, positionMapRef.current);
-      equivalentAckKeyRef.current = null;
+      equivalentAckLedgerRef.current.delete(snapshot.revisionToken);
+      pendingRebuildScrollAnchorRef.current = null;
+      lastBuiltStoryRef.current = snapshot.activeStory;
       if (pendingTypingProbeRef.current) {
         finishPerfProbe(pendingTypingProbeRef.current);
         pendingTypingProbeRef.current = null;
@@ -924,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) {

package/src/ui-tailwind/page-stack/use-visible-block-range.ts

@@ -172,7 +172,7 @@ function resolveBlockRangeFromOffsetSpan(input: {
     const block = blocks[index];
     if (!block) continue;
     if (block.from >= endOffset) break;
-    if (block.from >= startOffset && block.from < endOffset) {
+    if (block.from < endOffset && block.to > startOffset) {
       if (first < 0) first = index;
       last = index;
     }

package/src/ui-tailwind/review/tw-revision-sidebar.tsx

@@ -4,6 +4,7 @@ import { Check, MessageSquare, X } from "lucide-react";
 import type { TrackedChangesSnapshot, TrackedChangeEntrySnapshot } from "../../api/public-types";
 import { selectVisibleRevisions } from "../../ui/shared/revision-filters";
 import type { MarkupDisplay } from "../../ui/headless/comment-decoration-model";
+import { getAuthorColor } from "../../ui/headless/revision-decoration-model";
 
 export interface TwRevisionSidebarProps {
   trackedChanges: TrackedChangesSnapshot;
@@ -37,6 +38,7 @@ export function TwRevisionSidebar(props: TwRevisionSidebarProps) {
 
   const [typeFilter, setTypeFilter] = React.useState<TypeFilter>("all");
   const [authorFilter, setAuthorFilter] = React.useState<string | null>(null);
+  const activeCardRef = React.useRef<HTMLDivElement | null>(null);
 
   // Derive distinct authors from all visible revisions
   const authors = React.useMemo(() => {
@@ -79,6 +81,11 @@ export function TwRevisionSidebar(props: TwRevisionSidebarProps) {
     }
   }, [filteredRevisions, typeFilter, authorFilter, props.onRejectAllChanges, props.onRejectRevision]);
 
+  React.useEffect(() => {
+    if (!activeRevisionId) return;
+    activeCardRef.current?.scrollIntoView({ block: "nearest" });
+  }, [activeRevisionId, filteredRevisions]);
+
   return (
     <div className="flex flex-col outline-none">
       {/* Stats header */}
@@ -119,17 +126,28 @@ export function TwRevisionSidebar(props: TwRevisionSidebarProps) {
           <div className="space-y-2">
             {filteredRevisions.map((rev) => {
               const isActive = activeRevisionId === rev.revisionId;
+              const authorColor = getAuthorColor(rev.authorId);
 
               return (
                 <div
                   key={rev.revisionId}
-                  className={`w-full text-left flex rounded-md bg-surface/90 transition-colors ring-1 ring-border ${isActive ? "bg-accent-soft/40 ring-accent/25" : "hover:bg-surface"}`}
+                  ref={(node) => {
+                    if (isActive) {
+                      activeCardRef.current = node;
+                    }
+                  }}
+                  className={`w-full text-left flex rounded-md bg-surface/90 transition-colors ring-1 ring-border ${isActive ? "bg-accent-soft/40 ring-accent/25 shadow-[var(--shadow-soft)]" : "hover:bg-surface"}`}
+                  style={
+                    authorColor && isActive
+                      ? { boxShadow: `0 0 0 1px ${authorColor}, var(--shadow-soft)` }
+                      : undefined
+                  }
                 >
                   <div className={`w-0.5 shrink-0 rounded-l-md ${
                     rev.kind === "insertion" ? "bg-insert"
                     : rev.kind === "deletion" ? "bg-danger"
                     : "bg-tertiary"
-                  }`} />
+                  }`} style={authorColor ? { backgroundColor: authorColor } : undefined} />
                   <div className="flex-1 min-w-0">
                     <button
                       type="button"
@@ -140,7 +158,18 @@ export function TwRevisionSidebar(props: TwRevisionSidebarProps) {
                         <span className="text-[11px] font-medium text-primary">{rev.anchorLabel}</span>
                         <RevisionBadge status={rev.status} actionability={rev.actionability} />
                       </div>
-                      <p className="mb-1 text-[10px] text-tertiary">{rev.authorId} · {rev.createdAt}</p>
+                      <p className="mb-1 flex items-center gap-1.5 text-[10px] text-tertiary">
+                        {authorColor ? (
+                          <span
+                            aria-hidden="true"
+                            className="h-2 w-2 rounded-full"
+                            style={{ backgroundColor: authorColor }}
+                          />
+                        ) : null}
+                        <span className="truncate">{rev.authorId}</span>
+                        <span aria-hidden="true">·</span>
+                        <span>{rev.createdAt}</span>
+                      </p>
                       {rev.excerpt ? (
                         <p className={`text-[11px] ${
                           rev.kind === "insertion" ? "text-insert"

package/src/ui-tailwind/review-workspace/use-review-rail-state.ts

@@ -21,7 +21,7 @@ export interface ReviewRailState {
  * Review-rail open/close state + the responsive transition effect.
  *
  * When the responsive signature flips (narrow↔wide, or
- * `reviewRailAvailable` changes), the rail resets to its default open
+ * `reviewRailAvailable` changes), the rail resets to its default closed
  * state per `getInitialReviewRailOpen`. A ref guards the effect so it
  * only fires on actual transitions, not every viewport resize.
  *

package/src/ui-tailwind/tw-review-workspace.tsx

@@ -181,6 +181,7 @@ export function TwReviewWorkspace(inputProps: TwReviewWorkspaceProps) {
   // in the render tree below.
   const { bodySlotRef, pmSurfaceElement } = usePmSurfaceCapture();
   const { scrollRootRef, pageStackScrollRoot } = useScrollRootCapture();
+  const lastHoveredRevisionIdRef = useRef<string | null>(null);
   const caps = props.capabilities;
   const isPageWorkspace = props.workspaceMode === "page";
   const markupDisplay = props.markupDisplay;
@@ -248,6 +249,22 @@ export function TwReviewWorkspace(inputProps: TwReviewWorkspaceProps) {
     reviewRailAvailable,
     viewportWidth,
   });
+  const handleDocumentMouseOver = useCallback(
+    (event: React.MouseEvent<HTMLDivElement>) => {
+      const element = event.target as HTMLElement | null;
+      const revisionId =
+        element?.closest?.("[data-revision-id]")?.getAttribute("data-revision-id") ?? null;
+      if (!revisionId || (revisionId === lastHoveredRevisionIdRef.current && reviewRailOpen)) {
+        return;
+      }
+      lastHoveredRevisionIdRef.current = revisionId;
+      if (reviewRailAvailable) {
+        setReviewRailOpen(true);
+        props.onActiveRailTabChange?.("changes");
+      }
+    },
+    [props.onActiveRailTabChange, reviewRailAvailable, reviewRailOpen, setReviewRailOpen],
+  );
   // Incremented on zoom_changed / render_frame_ready so the placement
   // useMemo below re-executes when the render kernel emits new rects.
   const renderFrameRevision = useLayoutFacetRenderSignal(props.layoutFacet);
@@ -928,6 +945,7 @@ export function TwReviewWorkspace(inputProps: TwReviewWorkspaceProps) {
           <div className="flex flex-1 flex-col min-w-0">
             <div
               ref={scrollRootRef}
+              onMouseOver={handleDocumentMouseOver}
               className="flex-1 overflow-y-auto bg-surface"
               data-wre-scroll-root="true"
             >