@beyondwork/docx-react-component 1.0.85 → 1.0.87

package/src/ui-tailwind/editor-surface/pm-contextual-ui.ts

@@ -3,13 +3,47 @@ import { Plugin } from "prosemirror-state";
 export interface ContextualInteractionCallbacks {
   onCommentActivated?: (commentId: string) => void;
   onRevisionActivated?: (revisionId: string) => void;
+  onRevisionHovered?: (revisionId: string | null) => void;
+}
+
+function findRevisionId(target: EventTarget | null): string | null {
+  const element = target as HTMLElement | null;
+  return element?.closest?.("[data-revision-id]")?.getAttribute("data-revision-id") ?? null;
 }
 
 export function createContextualInteractionPlugin(
   callbacks: ContextualInteractionCallbacks,
 ): Plugin {
+  let hoveredRevisionId: string | null = null;
+
   return new Plugin({
     props: {
+      handleDOMEvents: {
+        mouseover(_view, event) {
+          const revisionId = findRevisionId(event.target);
+          if (!revisionId || revisionId === hoveredRevisionId) {
+            return false;
+          }
+          hoveredRevisionId = revisionId;
+          callbacks.onRevisionHovered?.(revisionId);
+          return false;
+        },
+        mouseout(_view, event) {
+          const revisionId = findRevisionId(event.target);
+          if (!revisionId) {
+            return false;
+          }
+          const relatedRevisionId = findRevisionId(event.relatedTarget);
+          if (relatedRevisionId === revisionId) {
+            return false;
+          }
+          if (hoveredRevisionId === revisionId) {
+            hoveredRevisionId = null;
+            callbacks.onRevisionHovered?.(null);
+          }
+          return false;
+        },
+      },
       handleClick(_view, _pos, event) {
         const target = event.target as HTMLElement | null;
         const commentId = target?.closest?.("[data-comment-id]")?.getAttribute("data-comment-id");

package/src/ui-tailwind/editor-surface/pm-decorations.ts

@@ -4,10 +4,12 @@ import type { CommentDecorationModel } from "../../ui/headless/comment-decoratio
 import { getCommentHighlightClass, type MarkupDisplay } from "../../ui/headless/comment-decoration-model";
 import type {
   RevisionDecorationModel,
+  RevisionDecorationEntry,
   RevisionDisplayFlags,
 } from "../../ui/headless/revision-decoration-model";
 import {
   buildClassFromRevisionDisplay,
+  getAuthorColor,
   getRevisionHighlightClass,
 } from "../../ui/headless/revision-decoration-model";
 import type {
@@ -46,6 +48,106 @@ type RailDecorationSpec = {
   attrs: Record<string, string>;
 };
 
+function sanitizeRevisionAuthorColor(raw: unknown): string | null {
+  if (typeof raw !== "string") return null;
+  const value = raw.trim();
+  if (/^var\(--color-chart-categorical-[1-8]\)$/.test(value)) return value;
+  return sanitizeHostCssColor(value);
+}
+
+function resolveRevisionAuthorColor(
+  rev: RevisionDecorationEntry,
+  display?: RevisionDisplayFlags,
+): string | undefined {
+  return sanitizeRevisionAuthorColor(display?.authorColor) ?? getAuthorColor(rev.authorId);
+}
+
+function buildRevisionAuthorStyle(
+  kind: RevisionDecorationEntry["kind"],
+  authorColor: string | undefined,
+): string | undefined {
+  if (!authorColor) return undefined;
+
+  const backgroundStrength =
+    kind === "deletion" ? "8%" : kind === "insertion" ? "10%" : "9%";
+  return [
+    `--wre-revision-author: ${authorColor}`,
+    "color: var(--wre-revision-author)",
+    `background-color: color-mix(in srgb, var(--wre-revision-author) ${backgroundStrength}, transparent)`,
+    `text-decoration-color: var(--wre-revision-author)`,
+    "text-decoration-thickness: 2px",
+    "text-underline-offset: 2px",
+    "box-decoration-break: clone",
+    "-webkit-box-decoration-break: clone",
+  ].join("; ");
+}
+
+function labelRevisionKind(kind: RevisionDecorationEntry["kind"]): string {
+  switch (kind) {
+    case "insertion":
+      return "Insertion";
+    case "deletion":
+      return "Deletion";
+    case "formatting":
+      return "Formatting change";
+    case "move":
+      return "Move";
+    case "property-change":
+      return "Property change";
+  }
+}
+
+function buildRevisionInlineAttrs(
+  rev: RevisionDecorationEntry,
+  className: string,
+  display?: RevisionDisplayFlags,
+): Record<string, string> {
+  const attrs: Record<string, string> = {
+    class: className,
+    "data-revision-id": rev.revisionId,
+    "data-revision-kind": rev.kind,
+  };
+  if (rev.authorId) {
+    attrs["data-revision-author-id"] = rev.authorId;
+    attrs.title = `${labelRevisionKind(rev.kind)} by ${rev.authorId}`;
+  }
+  if (rev.authorPaletteIndex !== undefined) {
+    attrs["data-revision-author-index"] = String(rev.authorPaletteIndex);
+  }
+
+  const style = buildRevisionAuthorStyle(
+    rev.kind,
+    resolveRevisionAuthorColor(rev, display),
+  );
+  if (style) {
+    attrs.style = style;
+  }
+  return attrs;
+}
+
+function buildRevisionBoundaryAttrs(
+  rev: RevisionDecorationEntry,
+  display?: RevisionDisplayFlags,
+): Record<string, string> {
+  const attrs: Record<string, string> = {
+    class: "text-insert font-semibold",
+    "data-revision-id": rev.revisionId,
+    "data-revision-kind": rev.kind,
+  };
+  if (rev.authorId) {
+    attrs["data-revision-author-id"] = rev.authorId;
+    attrs.title = `${labelRevisionKind(rev.kind)} by ${rev.authorId}`;
+  }
+  if (rev.authorPaletteIndex !== undefined) {
+    attrs["data-revision-author-index"] = String(rev.authorPaletteIndex);
+  }
+  const authorColor = resolveRevisionAuthorColor(rev, display);
+  if (authorColor) {
+    attrs.style = `color: ${authorColor}`;
+  }
+  return attrs;
+}
+
 /**
  * Validate and normalize a host-supplied CSS color before interpolating it
  * into an inline-style string.  Accepts only the narrow subset a
@@ -466,6 +568,7 @@ export function buildDecorations(
             Decoration.inline(cleanPmFrom, cleanPmTo, {
               class: "hidden",
               "data-revision-id": rev.revisionId,
+              "data-revision-kind": rev.kind,
             }),
           );
           revisionCount += 1;
@@ -480,17 +583,28 @@ export function buildDecorations(
       // Suggestions styling is always shown regardless of showTrackedChanges toggle.
       if (suggestionsEnabled) {
         if (rev.kind === "insertion") {
+          const insertionClass =
+            buildClassFromRevisionDisplay(revDisplayFlags) ||
+            getRevisionHighlightClass(revisionModel, rev.from, rev.to, "all");
           decorations.push(
-            Decoration.inline(pmFrom, pmTo, {
-              class: "text-insert",
-              "data-revision-id": rev.revisionId,
-            }),
+            Decoration.inline(
+              pmFrom,
+              pmTo,
+              buildRevisionInlineAttrs(rev, insertionClass, revDisplayFlags),
+            ),
           );
           decorations.push(
             Decoration.widget(pmFrom, () => {
               const el = document.createElement("span");
               el.textContent = "[";
-              el.className = "text-insert";
+              const attrs = buildRevisionBoundaryAttrs(rev, revDisplayFlags);
+              for (const [name, value] of Object.entries(attrs)) {
+                if (name === "class") {
+                  el.className = value;
+                } else {
+                  el.setAttribute(name, value);
+                }
+              }
               el.setAttribute("contenteditable", "false");
               return el;
             }, { side: -1, key: `${rev.revisionId}-open` }),
@@ -499,30 +613,41 @@ export function buildDecorations(
             Decoration.widget(pmTo, () => {
               const el = document.createElement("span");
               el.textContent = "]";
-              el.className = "text-insert";
+              const attrs = buildRevisionBoundaryAttrs(rev, revDisplayFlags);
+              for (const [name, value] of Object.entries(attrs)) {
+                if (name === "class") {
+                  el.className = value;
+                } else {
+                  el.setAttribute(name, value);
+                }
+              }
               el.setAttribute("contenteditable", "false");
               return el;
             }, { side: 1, key: `${rev.revisionId}-close` }),
           );
           revisionCount += 1;
         } else if (rev.kind === "deletion") {
+          const deletionClass =
+            buildClassFromRevisionDisplay(revDisplayFlags) ||
+            getRevisionHighlightClass(revisionModel, rev.from, rev.to, "all");
           decorations.push(
-            Decoration.inline(pmFrom, pmTo, {
-              class: "text-danger line-through decoration-danger/80 decoration-1",
-              "data-revision-id": rev.revisionId,
-            }),
+            Decoration.inline(
+              pmFrom,
+              pmTo,
+              buildRevisionInlineAttrs(rev, deletionClass, revDisplayFlags),
+            ),
           );
           revisionCount += 1;
         } else if (rev.kind === "property-change" || rev.kind === "formatting") {
           const propertyChangeClass =
             buildClassFromRevisionDisplay(revDisplayFlags) ||
-            "underline decoration-accent/70 decoration-dotted decoration-1 underline-offset-2";
+            "rounded-[2px] bg-accent-soft/70 px-[1px] underline decoration-accent/80 decoration-dotted decoration-2 underline-offset-2";
           decorations.push(
-            Decoration.inline(pmFrom, pmTo, {
-              class: propertyChangeClass,
-              "data-revision-id": rev.revisionId,
-              "data-revision-kind": rev.kind,
-            }),
+            Decoration.inline(
+              pmFrom,
+              pmTo,
+              buildRevisionInlineAttrs(rev, propertyChangeClass, revDisplayFlags),
+            ),
           );
           revisionCount += 1;
         }
@@ -547,10 +672,11 @@ export function buildDecorations(
       if (!cls) continue;
 
       decorations.push(
-        Decoration.inline(pmFrom, pmTo, {
-          class: cls,
-          "data-revision-id": rev.revisionId,
-        }),
+        Decoration.inline(
+          pmFrom,
+          pmTo,
+          buildRevisionInlineAttrs(rev, cls, displayFlags),
+        ),
       );
       revisionCount += 1;
     }

package/src/ui-tailwind/editor-surface/pm-position-map.ts

@@ -87,13 +87,19 @@ function walkBlocks(
         break;
       }
       case "opaque_block": {
+        const placeholderSize =
+          block.state === "placeholder-culled" &&
+          typeof block.placeholderSize === "number" &&
+          Number.isFinite(block.placeholderSize)
+            ? Math.max(1, block.placeholderSize)
+            : 1;
         entries.push({
           runtimeStart: block.from,
           pmStart: nextPmCursor,
           runtimeEnd: block.to,
-          pmEnd: nextPmCursor + 1,
+          pmEnd: nextPmCursor + placeholderSize,
         });
-        nextPmCursor += 1;
+        nextPmCursor += placeholderSize;
         break;
       }
       case "sdt_block": {

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-comment-sidebar.tsx

@@ -153,6 +153,7 @@ function CommentThreadCard(props: {
   }, [presentation]);
   const leadEntry = thread.entries[0];
   const isDraftThread = thread.status === "open" && thread.entryCount === 1 && isEmptyCommentBody(leadEntry?.body);
+  const isLinkedRevisionThread = thread.linkedRevisionId != null;
   const isOwnComment = props.currentUserId != null && leadEntry?.authorId === props.currentUserId;
   const canEdit = isOwnComment && thread.status === "open" && props.onEditBody != null;
   const hasNoBody = isEmptyCommentBody(leadEntry?.body);
@@ -205,6 +206,7 @@ function CommentThreadCard(props: {
             {formatCommentDate(thread.createdAt)}
           </span>
           <span className="flex-1" />
+          {isLinkedRevisionThread ? <StatusBadge label="tracked change" tone="revision" /> : null}
           {isDraftThread ? <StatusBadge label="draft" tone="draft" /> : null}
           {thread.status === "resolved" ? <StatusBadge label="resolved" tone="resolved" /> : null}
         </div>
@@ -222,7 +224,9 @@ function CommentThreadCard(props: {
             body={leadEntry?.body ?? ""}
             autoFocus={isActive && hasNoBody}
             onSave={(newBody) => props.onEditBody?.(thread.commentId, newBody)}
-            label={isDraftThread ? "New comment" : undefined}
+            label={isDraftThread
+              ? (isLinkedRevisionThread ? "Tracked change discussion" : "New comment")
+              : undefined}
           />
         ) : presentation ? (
           <CommentMarkdownRenderer
@@ -247,7 +251,7 @@ function CommentThreadCard(props: {
               props.onOpenComment?.(thread);
             }}
           >
-            New comment
+            {isLinkedRevisionThread ? "Tracked change discussion" : "New comment"}
           </p>
         ) : null}
 
@@ -494,11 +498,12 @@ function formatCommentDate(raw: string): string {
   }
 }
 
-function StatusBadge(props: { label: string; tone: "resolved" | "detached" | "draft" }) {
+function StatusBadge(props: { label: string; tone: "resolved" | "detached" | "draft" | "revision" }) {
   const styles: Record<string, string> = {
     resolved: "text-insert bg-insert-soft",
     detached: "text-comment bg-warning-soft",
     draft: "text-secondary bg-subtle",
+    revision: "text-accent bg-accent-soft",
   };
   return (
     <span

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

@@ -111,6 +111,7 @@ export interface TwReviewRailProps {
   onAddReply?: (commentId: string, body: string) => void;
   onEditBody?: (commentId: string, body: string) => void;
   onOpenRevision?: (revision: TrackedChangeEntrySnapshot) => void;
+  onReplyToRevision?: (revision: TrackedChangeEntrySnapshot) => void;
   onAcceptRevision?: (revisionId: string) => void;
   onRejectRevision?: (revisionId: string) => void;
   onAcceptAllChanges?: () => void;
@@ -285,6 +286,7 @@ export function TwReviewRail(props: TwReviewRailProps) {
                 markupDisplay={props.markupDisplay}
                 activeRevisionId={props.activeRevisionId}
                 onOpenRevision={props.onOpenRevision}
+                onReplyToRevision={props.onReplyToRevision}
                 onAcceptRevision={props.onAcceptRevision}
                 onRejectRevision={props.onRejectRevision}
                 onAcceptAllChanges={props.onAcceptAllChanges}