@beyondwork/docx-react-component 1.0.86 → 1.0.87

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,7 +64,10 @@ 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 {
@@ -148,9 +152,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 +167,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 +282,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 +434,7 @@ 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 selectionToolbarFrameRef = useRef<number | null>(null);
   const lastSelectionToolbarMeasurementRef = useRef<{
     key: string | null;
@@ -653,10 +646,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 +765,7 @@ export const TwProseMirrorSurface = forwardRef<
   useEffect(() => {
     if (!props.dispatchRuntimeCommand || !sessionRef.current) {
       laneRef.current = null;
+      equivalentAckLedgerRef.current.clear();
       return;
     }
     // Wave 1 Slice E1/E2 — lane observability.
@@ -815,28 +810,27 @@ 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) => {
+        if (
+          ack.opId &&
+          ack.newRevisionToken &&
+          getTextCommandRefreshClass(ack) === "local-text-equivalent"
+        ) {
+          equivalentAckLedgerRef.current.set(ack.newRevisionToken, ack.opId);
+          return;
+        }
+        equivalentAckLedgerRef.current.clear();
       },
       onAdjustedAck: () => {
         // Adjusted path: allow the rebuild effect to run (it will call
         // view.updateState with the canonical snapshot).
-        equivalentAckKeyRef.current = null;
+        equivalentAckLedgerRef.current.clear();
       },
       onRejectedAck: () => {
-        equivalentAckKeyRef.current = null;
+        equivalentAckLedgerRef.current.clear();
       },
       onStructuralDivergence: () => {
-        equivalentAckKeyRef.current = null;
+        equivalentAckLedgerRef.current.clear();
       },
     });
   }, [props.dispatchRuntimeCommand, scopeTagRegistry]);
@@ -852,13 +846,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 +865,7 @@ export const TwProseMirrorSurface = forwardRef<
       positionMapRef.current = buildPositionMap(surface);
       documentBuildKeyRef.current = documentBuildKey;
       applyDecorationProps(viewRef.current, positionMapRef.current);
-      equivalentAckKeyRef.current = null;
+      equivalentAckLedgerRef.current.delete(snapshot.revisionToken);
       if (pendingTypingProbeRef.current) {
         finishPerfProbe(pendingTypingProbeRef.current);
         pendingTypingProbeRef.current = null;

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"
             >