@beyondwork/docx-react-component 1.0.85 → 1.0.87

package/src/ui/WordReviewEditor.tsx

@@ -1062,7 +1062,6 @@ export const WordReviewEditor = forwardRef<WordReviewEditorRef, WordReviewEditor
     } = props;
 
     const [activeRailTab, setActiveRailTab] = useState<ReviewRailTab>("comments");
-    const [showTrackedChanges, setShowTrackedChanges] = useState(() => suggestionsEnabled);
     const [localMarkupDisplay, setLocalMarkupDisplay] =
       useState<WorkflowMarkupMode | null>(() => suggestionsEnabled ? "all" : null);
     const [activeRevisionId, setActiveRevisionId] = useState<string | undefined>();
@@ -1368,6 +1367,8 @@ export const WordReviewEditor = forwardRef<WordReviewEditorRef, WordReviewEditor
     const isPageWorkspace = viewState.workspaceMode === "page";
     const liveMarkupDisplay = localMarkupDisplay ??
       __resolveLiveMarkupDisplay(markupDisplay, isPageWorkspace);
+    const trackedChangesAuthoringEnabled = viewState.documentMode === "suggesting";
+    const showTrackedChanges = toWorkflowMarkupMode(liveMarkupDisplay) !== "clean";
     const documentNavigation = useRuntimeValue(
       runtime
         ? {
@@ -1510,16 +1511,15 @@ export const WordReviewEditor = forwardRef<WordReviewEditorRef, WordReviewEditor
     const setReviewMarkupMode = useCallback((mode: MarkupDisplay) => {
       const workflowMode = toWorkflowMarkupMode(mode);
       setLocalMarkupDisplay(workflowMode);
-      setShowTrackedChanges(workflowMode !== "clean");
       api.ui?.viewport.setLocalMarkupMode(workflowMode);
     }, [api]);
 
     const setTrackedChangesAuthoring = useCallback((enabled: boolean) => {
-      const workflowMode: WorkflowMarkupMode = enabled ? "all" : "clean";
-      setShowTrackedChanges(enabled);
-      setLocalMarkupDisplay(workflowMode);
       api.runtime.document.setMode(enabled ? "suggesting" : "editing");
-      api.ui?.viewport.setLocalMarkupMode(workflowMode);
+      if (enabled) {
+        setLocalMarkupDisplay("all");
+        api.ui?.viewport.setLocalMarkupMode("all");
+      }
     }, [api]);
 
     useEffect(() => {
@@ -1527,7 +1527,6 @@ export const WordReviewEditor = forwardRef<WordReviewEditorRef, WordReviewEditor
         setTrackedChangesAuthoring(true);
         return;
       }
-      setShowTrackedChanges(false);
       api.runtime.document.setMode("editing");
     }, [api, setTrackedChangesAuthoring, suggestionsEnabled]);
 
@@ -2467,13 +2466,15 @@ export const WordReviewEditor = forwardRef<WordReviewEditorRef, WordReviewEditor
 
     function addReviewComment(): string | null {
       try {
+        const currentSnapshot = activeRuntime.getRenderSnapshot();
         const { commentId } = activeRuntime.addComment({
-          anchor: resolveCommentCommandAnchor(snapshot),
+          anchor: resolveCommentCommandAnchor(currentSnapshot),
           body: "",
           authorId: currentUser.userId,
           snapToSafeBoundary: true,
         });
         activeRuntime.openComment(commentId);
+        setActiveReviewQueueItemId(`comment:${commentId}`);
         setActiveRailTab("comments");
         return commentId;
       } catch {
@@ -2814,11 +2815,49 @@ export const WordReviewEditor = forwardRef<WordReviewEditorRef, WordReviewEditor
     }, [
       activeRuntime,
       activeSelectionTool,
+      addReviewComment,
       currentUser.userId,
       dismissSelectionToolbar,
       focusDocumentSurface,
     ]);
 
+    const acceptActiveSuggestion = useCallback(() => {
+      if (activeSelectionTool?.kind !== "suggestion-review") {
+        return;
+      }
+      for (const changeId of activeSelectionTool.changeIds) {
+        activeRuntime.acceptChange(changeId);
+      }
+      dismissSelectionToolbar("chrome-action");
+    }, [activeRuntime, activeSelectionTool, dismissSelectionToolbar]);
+
+    const rejectActiveSuggestion = useCallback(() => {
+      if (activeSelectionTool?.kind !== "suggestion-review") {
+        return;
+      }
+      for (const changeId of activeSelectionTool.changeIds) {
+        activeRuntime.rejectChange(changeId);
+      }
+      dismissSelectionToolbar("chrome-action");
+    }, [activeRuntime, activeSelectionTool, dismissSelectionToolbar]);
+
+    const editActiveSuggestion = useCallback(() => {
+      if (activeSelectionTool?.kind !== "suggestion-review") {
+        return;
+      }
+      setSuppressedSuggestionRevisionId(activeSelectionTool.suggestionId);
+      const activeSuggestion = suggestionsSnapshot.suggestions.find(
+        (suggestion) => suggestion.suggestionId === activeSelectionTool.suggestionId,
+      );
+      if (activeSuggestion) {
+        applyRuntimeSelection(
+          activeRuntime,
+          createSelectionFromAnchor(activeSuggestion.anchor, activeSuggestion.storyTarget),
+        );
+      }
+      setSelectionToolbarFocusWithin(true);
+    }, [activeRuntime, activeSelectionTool, suggestionsSnapshot.suggestions]);
+
     const handleSelectionToolbarAnchorChange = useCallback(
       (nextAnchor: SelectionToolbarAnchor | null) => {
         setSelectionToolbarAnchor((current) =>
@@ -3209,6 +3248,19 @@ export const WordReviewEditor = forwardRef<WordReviewEditorRef, WordReviewEditor
         focusAnchor(revision.anchor, revision.storyTarget);
         setActiveRailTab("changes");
       },
+      onReplyToRevision: (revision: typeof snapshot.trackedChanges.revisions[number]) => {
+        const linkedThread = activeRuntime.ensureCommentThreadForChange(
+          revision.revisionId,
+          currentUser.userId,
+        );
+        if (!linkedThread?.commentId) {
+          return;
+        }
+        setActiveRevisionId(revision.revisionId);
+        focusAnchor(revision.anchor, revision.storyTarget);
+        activeRuntime.openComment(linkedThread.commentId);
+        setActiveRailTab("comments");
+      },
       onAcceptRevision: (revisionId: string) => {
         activeRuntime.acceptChange(revisionId);
         setActiveRailTab("changes");
@@ -3237,6 +3289,7 @@ export const WordReviewEditor = forwardRef<WordReviewEditorRef, WordReviewEditor
       onActiveRailTabChange: setActiveRailTab,
       onShowTrackedChangesChange: setTrackedChangesAuthoring,
       onReviewMarkupModeChange: setReviewMarkupMode,
+      onChromePinChange: (surface, pin) => activeRuntime.setChromePin(surface, pin),
       onToggleBold: () =>
         applyRuntimeFormattingOperation(activeRuntime, { type: "toggle", mark: "bold" }),
       onToggleItalic: () =>
@@ -3449,6 +3502,9 @@ export const WordReviewEditor = forwardRef<WordReviewEditorRef, WordReviewEditor
         onInsertPageBreak: commands.onInsertPageBreak,
         onInsertSectionBreak: (type) => commands.onInsertSectionBreak?.(type),
         onInsertTable: commands.onInsertTable,
+        onInsertImage: commands.onInsertImage
+          ? () => requestImageInsertFromPicker(commands.onInsertImage)
+          : undefined,
         onAddComment: commands.onAddComment,
         onFindRequested: onFindRequested
           ? () => onFindRequested({ selectionText: "", selectionRange: snapshot.selection })
@@ -3546,6 +3602,14 @@ export const WordReviewEditor = forwardRef<WordReviewEditorRef, WordReviewEditor
           setActiveRevisionId(revisionId);
           setActiveRailTab("changes");
         }}
+        onRevisionHovered={(revisionId) => {
+          if (!revisionId) {
+            return;
+          }
+          setActiveRevisionId(revisionId);
+          setActiveRailTab("changes");
+          onReviewSidebarTrackedChanges?.();
+        }}
       />
     );
 
@@ -3592,6 +3656,7 @@ export const WordReviewEditor = forwardRef<WordReviewEditorRef, WordReviewEditor
         activeRailTab={activeRailTab}
         activeCommentId={snapshot.comments.activeCommentId}
         activeRevisionId={activeRevisionId}
+        trackedChangesAuthoringEnabled={trackedChangesAuthoringEnabled}
         showTrackedChanges={showTrackedChanges}
         workflowScopeSnapshot={workflowScopeSnapshot}
         layoutFacet={activeRuntime.layout}
@@ -3626,35 +3691,13 @@ export const WordReviewEditor = forwardRef<WordReviewEditorRef, WordReviewEditor
         onAddCommentFromSelection={addSelectionToolbarComment}
         onAddCommentFromSuggestion={addSelectionToolbarComment}
         onAcceptSuggestion={activeSelectionTool?.kind === "suggestion-review"
-          ? () => {
-              for (const changeId of activeSelectionTool.changeIds) {
-                activeRuntime.acceptChange(changeId);
-              }
-              dismissSelectionToolbar("chrome-action");
-            }
+          ? acceptActiveSuggestion
           : undefined}
         onRejectSuggestion={activeSelectionTool?.kind === "suggestion-review"
-          ? () => {
-              for (const changeId of activeSelectionTool.changeIds) {
-                activeRuntime.rejectChange(changeId);
-              }
-              dismissSelectionToolbar("chrome-action");
-            }
+          ? rejectActiveSuggestion
           : undefined}
         onEditSuggestion={activeSelectionTool?.kind === "suggestion-review"
-          ? () => {
-              setSuppressedSuggestionRevisionId(activeSelectionTool.suggestionId);
-              const activeSuggestion = suggestionsSnapshot.suggestions.find(
-                (suggestion) => suggestion.suggestionId === activeSelectionTool.suggestionId,
-              );
-              if (activeSuggestion) {
-                applyRuntimeSelection(
-                  activeRuntime,
-                  createSelectionFromAnchor(activeSuggestion.anchor, activeSuggestion.storyTarget),
-                );
-              }
-              setSelectionToolbarFocusWithin(true);
-            }
+          ? editActiveSuggestion
           : undefined}
         onDismissSelectionToolbar={() => dismissSelectionToolbar("chrome-action")}
         onSelectionToolbarFocusCapture={handleSelectionToolbarFocusCapture}
@@ -4296,6 +4339,42 @@ function resolveCommentCommandAnchor(
     : selection.activeRange;
 }
 
+function requestImageInsertFromPicker(
+  onInsertImage: ((options: InsertImageOptions) => void) | undefined,
+): void {
+  const document = globalThis.document;
+  if (!onInsertImage || typeof document?.createElement !== "function" || !document.body) {
+    return;
+  }
+
+  const input = document.createElement("input");
+  input.type = "file";
+  input.accept = "image/png,image/jpeg,image/gif";
+  input.style.position = "fixed";
+  input.style.left = "-9999px";
+  input.style.top = "-9999px";
+  input.addEventListener("change", () => {
+    const file = input.files?.[0];
+    if (!file) {
+      input.remove();
+      return;
+    }
+    void file.arrayBuffer()
+      .then((buffer) => {
+        onInsertImage({
+          data: new Uint8Array(buffer),
+          mimeType: file.type || "image/png",
+          altText: file.name,
+        });
+      })
+      .finally(() => {
+        input.remove();
+      });
+  }, { once: true });
+  document.body.appendChild(input);
+  input.click();
+}
+
 function resolveCollapsedCommentRange(
   surface: RuntimeRenderSnapshot["surface"],
   selection: RuntimeRenderSnapshot["selection"],

package/src/ui/editor-command-bag.ts

@@ -1,6 +1,7 @@
 import { useMemo, useRef } from "react";
 
 import type {
+  ChromePinSurface,
   CommentSidebarThreadSnapshot,
   EditorStoryTarget,
   FormattingAlignment,
@@ -9,6 +10,7 @@ import type {
   SectionBreakType,
   SectionLayoutPatch,
   SectionPageNumberingPatch,
+  PinState,
   TrackedChangeEntrySnapshot,
   ZoomLevel,
   WorkspaceMode,
@@ -24,6 +26,7 @@ export interface EditorCommandBag {
   onActiveRailTabChange(value: ReviewRailTab): void;
   onShowTrackedChangesChange(show: boolean): void;
   onReviewMarkupModeChange?(mode: MarkupDisplay): void;
+  onChromePinChange?(surface: ChromePinSurface, pin: PinState | null): void;
   onUndo(): void;
   onRedo(): void;
   onSetParagraphStyle?(styleId: string): void;
@@ -85,6 +88,7 @@ export interface EditorCommandBag {
   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;

package/src/ui/editor-shell-view.tsx

@@ -55,6 +55,7 @@ export interface EditorShellViewProps {
   activeRailTab: ReviewRailTab;
   activeCommentId?: string;
   activeRevisionId?: string;
+  trackedChangesAuthoringEnabled?: boolean;
   showTrackedChanges: boolean;
   workflowScopeSnapshot?: WorkflowScopeSnapshot | null;
   /**

package/src/ui/editor-surface-controller.tsx

@@ -102,6 +102,7 @@ export interface EditorSurfaceControllerProps {
   }) => void;
   onCommentActivated?: (commentId: string) => void;
   onRevisionActivated?: (revisionId: string) => void;
+  onRevisionHovered?: (revisionId: string | null) => void;
   workflowScopes?: readonly WorkflowScope[];
   workflowCandidates?: readonly WorkflowCandidateRange[];
   workflowBlockedReasons?: readonly WorkflowBlockedCommandReason[];

package/src/ui/headless/revision-decoration-model.ts

@@ -204,18 +204,16 @@ export function buildClassFromRevisionDisplay(
 
   // Insertion underline (simple / all markup, insertion kind).
   if (display.insertionUnderline) {
-    // Matches the underline visual used in the review-store path for
-    // "simple-markup" insertions; keeps the two paths producing the
-    // same class bundle so a mid-flight migration does not produce a
-    // visual diff.
-    parts.push(
-      "underline decoration-insert/60 decoration-1 underline-offset-2 text-primary",
-    );
+    parts.push(display.markupMode === "all"
+      ? "rounded-[2px] bg-insert-soft/35 px-[1px] text-primary underline decoration-insert decoration-2 underline-offset-2"
+      : "rounded-[2px] px-[1px] text-primary underline decoration-insert decoration-2 underline-offset-2");
   }
 
   // Strikethrough (deletion kind, simple or all markup).
   if (display.strikethrough) {
-    parts.push("text-danger line-through decoration-danger/80 decoration-1");
+    parts.push(display.markupMode === "all"
+      ? "rounded-[2px] bg-delete-soft/35 px-[1px] text-danger line-through decoration-danger decoration-2"
+      : "text-danger line-through decoration-danger decoration-2");
   }
 
   // De-emphasize (e.g. inactive revision in all-markup; reviewer
@@ -234,7 +232,7 @@ export function buildClassFromRevisionDisplay(
     (display.kind === "formatting" || display.kind === "property-change")
   ) {
     parts.push(
-      "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",
     );
   }
 
@@ -277,18 +275,18 @@ export function getRevisionHighlightClass(
       return "";
     case "simple-markup":
       if (state.hasInsertions) {
-        return `underline decoration-insert/60 decoration-1 underline-offset-2 text-primary${activeRing}`;
+        return `rounded-[2px] px-[1px] text-primary underline decoration-insert decoration-2 underline-offset-2${activeRing}`;
       }
       if (state.hasDeletions) {
-        return `text-secondary line-through decoration-danger/70 decoration-1${activeRing}`;
+        return `text-danger line-through decoration-danger decoration-2${activeRing}`;
       }
       return activeRing;
     case "all-markup":
       if (state.hasInsertions) {
-        return `text-primary bg-insert-soft/80 ring-1 ring-insert/20${activeRing}`;
+        return `rounded-[2px] bg-insert-soft/35 px-[1px] text-primary underline decoration-insert decoration-2 underline-offset-2${activeRing}`;
       }
       if (state.hasDeletions) {
-        return `text-danger line-through decoration-danger/80 decoration-1 bg-delete-soft/70${activeRing}`;
+        return `rounded-[2px] bg-delete-soft/35 px-[1px] text-danger line-through decoration-danger decoration-2${activeRing}`;
       }
       return activeRing;
   }

package/src/ui-tailwind/chrome/editor-action-registry.ts

@@ -3,16 +3,17 @@
  * contextual actions exist, keyed by `TargetKind`.
  *
  * Consumed by three access routes so DESIGN-EDITOR.md §6.4 holds by
- * construction ("right-click cannot be richer than the floating surface;
- * cannot duplicate command trees"):
+ * construction for general editor actions:
  *
  *   1. Right-click context menu (via `build-context-menu-entries.ts`)
  *   2. Inline "More…" affordance on reduced floating toolbars (Phase D)
  *   3. Command palette groups (Phase C.δ)
  *
- * All three routes produce the same actions from this registry — they
- * cannot diverge.  This is the load-bearing decision that makes the
- * floating-menu demotion legal.
+ * All three routes produce the same general actions from this registry.
+ * Suggestion-specific review actions are intentionally absent for now:
+ * they require an exact revision/suggestion id payload, so they live on
+ * the floating suggestion card and Changes rail until the context-menu
+ * target resolver can supply that payload.
  *
  * Perf discipline: pure data + pure filter helpers.  No DOM reads, no
  * runtime calls, no observers.  Actions are dispatched through host-
@@ -106,10 +107,6 @@ export interface EditorActionHostCallbacks {
   readonly onPrintRequested?: () => void;
   readonly onGoToRequested?: () => void;
 
-  // Tracked-change operations (suggestion target)
-  readonly onAcceptSuggestion?: () => void;
-  readonly onRejectSuggestion?: () => void;
-
   // Comment operations (comment-anchor target)
   readonly onResolveComment?: () => void;
   readonly onReplyToComment?: () => void;
@@ -576,7 +573,7 @@ export const EDITOR_ACTION_REGISTRY: readonly EditorAction[] = [
   mkImportant({
     id: "insert-image",
     label: "Insert image…",
-    description: "Needs a host file picker before it can run.",
+    description: "Choose an image file and insert it at the caret.",
     group: "misc",
     targetKinds: [],
     callback: "onInsertImage",
@@ -636,22 +633,6 @@ export const EDITOR_ACTION_REGISTRY: readonly EditorAction[] = [
     callback: "onPrintRequested",
   }),
 
-  // -------- Suggestion / tracked change --------
-  mk({
-    id: "accept-suggestion",
-    label: "Accept suggestion",
-    group: "suggestion",
-    targetKinds: ["suggestion"],
-    callback: "onAcceptSuggestion",
-  }),
-  mk({
-    id: "reject-suggestion",
-    label: "Reject suggestion",
-    group: "suggestion",
-    targetKinds: ["suggestion"],
-    callback: "onRejectSuggestion",
-  }),
-
   // -------- Comment --------
   mk({
     id: "resolve-comment",

package/src/ui-tailwind/chrome/responsive-chrome.ts

@@ -17,11 +17,11 @@ export function isNarrowChromeViewport(viewportWidth?: number): boolean {
   return typeof viewportWidth === "number" && viewportWidth <= NARROW_CHROME_MAX_WIDTH;
 }
 
-export function getInitialReviewRailOpen(input: {
+export function getInitialReviewRailOpen(_input: {
   viewportWidth?: number;
   reviewRailAvailable: boolean;
 }): boolean {
-  return input.reviewRailAvailable && !isNarrowChromeViewport(input.viewportWidth);
+  return false;
 }
 
 export function resolveResponsiveChromeState(

package/src/ui-tailwind/chrome/tw-alert-banner.tsx

@@ -123,6 +123,7 @@ export function TwAlertBanner(
   // 3. Workflow blocked — host policy refuses a command, per reasons.
   if (workflowBlockedReasons.length > 0) {
     const firstReason = workflowBlockedReasons[0]!;
+    const hint = getWorkflowBlockedHint(firstReason);
     return renderBanner({
       severity: "warning",
       icon: (
@@ -131,6 +132,7 @@ export function TwAlertBanner(
       message: (
         <>
           {firstReason.message}
+          {hint ? <span className="opacity-80"> {hint}</span> : null}
           {workflowBlockedReasons.length > 1
             ? ` (+${workflowBlockedReasons.length - 1} more)`
             : ""}
@@ -161,3 +163,28 @@ export function TwAlertBanner(
 
   return null;
 }
+
+function getWorkflowBlockedHint(
+  reason: WorkflowBlockedCommandReason,
+): string | null {
+  switch (reason.code) {
+    case "suggesting_unsupported":
+      return "Switch to Edit for this command, or insert plain text.";
+    case "workflow_comment_only":
+      return "Add a comment, or use an editing scope.";
+    case "outside_workflow_scope":
+      return "Move into an editable workflow scope.";
+    case "workflow_view_only":
+    case "document_viewing_mode":
+    case "document_read_only":
+      return "Open an editable copy or request edit access.";
+    case "workflow_preserve_only":
+    case "workflow_blocked_import":
+    case "protected_range":
+    case "unsupported_surface":
+      return "Use detail for the safe path.";
+    case "workflow_round_locked":
+      return "Wait for the round to unlock or request approval.";
+  }
+  return null;
+}

package/src/ui-tailwind/chrome/tw-detach-handle.tsx

@@ -43,6 +43,10 @@ export function TwDetachHandle(props: TwDetachHandleProps): React.JSX.Element {
   const { surface, pin, onChange, label } = props;
   const isDetached = pin?.detached ?? false;
   const offset = pin?.offset ?? { x: 0, y: 0 };
+  const dragHandleTestId =
+    surface === "selectionTier" ? "selection-tool-drag-handle" : `${surface}-detach-drag-handle`;
+  const toggleTestId =
+    surface === "selectionTier" ? "selection-tool-attach-toggle" : `${surface}-detach-toggle`;
   const dragState = useRef<
     | {
         startX: number;
@@ -117,7 +121,7 @@ export function TwDetachHandle(props: TwDetachHandleProps): React.JSX.Element {
       <button
         type="button"
         aria-label={isDetached ? "Drag floating menu" : "Drag to float menu"}
-        data-testid={`${surface}-detach-drag-handle`}
+        data-testid={dragHandleTestId}
         className="inline-flex h-6 items-center justify-center rounded-md border border-transparent px-1.5 text-tertiary transition-colors hover:border-border/60 hover:bg-surface hover:text-primary"
         onMouseDown={beginDrag}
       >
@@ -133,7 +137,7 @@ export function TwDetachHandle(props: TwDetachHandleProps): React.JSX.Element {
         type="button"
         aria-label={isDetached ? "Dock menu" : "Float menu"}
         aria-pressed={isDetached}
-        data-testid={`${surface}-detach-toggle`}
+        data-testid={toggleTestId}
         className="inline-flex h-6 items-center rounded-md border border-border/60 px-2 text-[10px] font-medium text-secondary transition-colors hover:bg-surface hover:text-primary"
         onMouseDown={preserveEditorSelectionMouseDown}
         onClick={toggle}

package/src/ui-tailwind/editor-surface/fast-text-edit-lane.ts

@@ -1,7 +1,10 @@
 import type { Transaction } from "prosemirror-state";
 import type { EditorView } from "prosemirror-view";
 
-import type { TextCommandAck } from "../../api/public-types.ts";
+import type {
+  TextCommandAck,
+  TextCommandRefreshClass,
+} from "../../api/public-types.ts";
 import type {
   LocalEditSessionState,
   PendingOp,
@@ -78,7 +81,11 @@ export interface FastTextEditLaneOptions {
   /** Optional probe hooks for perf instrumentation. */
   probe?: {
     markPredicted(opId: string): void;
-    markReconciled(opId: string, kind: TextCommandAck["kind"]): void;
+    markReconciled(
+      opId: string,
+      kind: TextCommandAck["kind"],
+      refreshClass: TextCommandRefreshClass,
+    ): void;
   };
 }
 
@@ -96,6 +103,22 @@ function allocOpId(): string {
   return `op-${Date.now().toString(36)}-${nextOpIdCounter}`;
 }
 
+export function getTextCommandRefreshClass(
+  ack: TextCommandAck,
+): TextCommandRefreshClass {
+  if (ack.refreshClass) return ack.refreshClass;
+  switch (ack.kind) {
+    case "equivalent":
+      return "local-text-equivalent";
+    case "adjusted":
+      return "surface-only";
+    case "rejected":
+      return "blocked";
+    case "structural-divergence":
+      return "full-projection";
+  }
+}
+
 export function createFastTextEditLane(
   options: FastTextEditLaneOptions,
 ): FastTextEditLane {
@@ -136,9 +159,11 @@ export function createFastTextEditLane(
 
     if (options.shouldBailBeforePredict?.(intent, fromRuntime, toRuntime)) {
       const ack = options.dispatchRuntimeCommand(toRuntimeCommand(intent, opId));
+      const refreshClass = getTextCommandRefreshClass(ack);
       incrementInvalidationCounter(PREDICTED_LANE_COUNTERS.bailBeforePredict);
-      markLaneDebugReconciled(debugEntry, ack.kind, true);
-      options.probe?.markReconciled(opId, ack.kind);
+      incrementRefreshClassCounter(refreshClass);
+      markLaneDebugReconciled(debugEntry, ack.kind, refreshClass, true);
+      options.probe?.markReconciled(opId, ack.kind, refreshClass);
       switch (ack.kind) {
         case "equivalent":
           options.session.advanceToRevision({
@@ -184,8 +209,10 @@ export function createFastTextEditLane(
       op.predictedSelectionHead = view.state.selection.head;
 
       const ack = options.dispatchRuntimeCommand(toRuntimeCommand(intent, opId));
-      markLaneDebugReconciled(debugEntry, ack.kind, false);
-      options.probe?.markReconciled(opId, ack.kind);
+      const refreshClass = getTextCommandRefreshClass(ack);
+      markLaneDebugReconciled(debugEntry, ack.kind, refreshClass, false);
+      incrementRefreshClassCounter(refreshClass);
+      options.probe?.markReconciled(opId, ack.kind, refreshClass);
 
       switch (ack.kind) {
         case "equivalent":
@@ -284,6 +311,8 @@ interface LaneDebugEntry {
   toRuntime: number;
   /** Dispatch → reconcile observation. Filled by `markLaneDebugReconciled`. */
   ackKind?: TextCommandAck["kind"];
+  /** Narrow refresh tier derived from the runtime ack. */
+  refreshClass?: TextCommandRefreshClass;
   /** Wall-clock ms between `pushLaneDebug` and `markLaneDebugReconciled`. */
   reconcileMs?: number;
   /** Whether the lane short-circuited to dispatch-only (no predicted TX). */
@@ -336,10 +365,12 @@ function pushLaneDebug(
 function markLaneDebugReconciled(
   entry: LaneDebugEntry | null,
   ackKind: TextCommandAck["kind"],
+  refreshClass: TextCommandRefreshClass,
   bailed: boolean,
 ): void {
   if (!entry) return;
   entry.ackKind = ackKind;
+  entry.refreshClass = refreshClass;
   entry.bailed = bailed;
   const now =
     typeof performance !== "undefined" && typeof performance.now === "function"
@@ -348,6 +379,26 @@ function markLaneDebugReconciled(
   entry.reconcileMs = now - entry.startedAtMs;
 }
 
+function incrementRefreshClassCounter(refreshClass: TextCommandRefreshClass): void {
+  switch (refreshClass) {
+    case "selection-only":
+      incrementInvalidationCounter(PREDICTED_LANE_COUNTERS.refreshSelectionOnly);
+      return;
+    case "local-text-equivalent":
+      incrementInvalidationCounter(PREDICTED_LANE_COUNTERS.refreshLocalTextEquivalent);
+      return;
+    case "surface-only":
+      incrementInvalidationCounter(PREDICTED_LANE_COUNTERS.refreshSurfaceOnly);
+      return;
+    case "full-projection":
+      incrementInvalidationCounter(PREDICTED_LANE_COUNTERS.refreshFullProjection);
+      return;
+    case "blocked":
+      incrementInvalidationCounter(PREDICTED_LANE_COUNTERS.refreshBlocked);
+      return;
+  }
+}
+
 function buildTxCompat(
   view: EditorView,
   _intent: PredictedIntent,

package/src/ui-tailwind/editor-surface/page-slice-util.ts

@@ -13,3 +13,20 @@ export function sliceBlocksForPage(
     (b) => b.from < page.endOffset && b.to > page.startOffset,
   );
 }
+
+export function findBlockIndexRangeForPage(
+  blocks: readonly SurfaceBlockSnapshot[],
+  page: Pick<DocumentPageSnapshot, "startOffset" | "endOffset">,
+): { first: number; last: number } | null {
+  if (page.endOffset <= page.startOffset) return null;
+  let first = -1;
+  let last = -1;
+  for (let index = 0; index < blocks.length; index += 1) {
+    const block = blocks[index]!;
+    if (block.from < page.endOffset && block.to > page.startOffset) {
+      if (first === -1) first = index;
+      last = index;
+    }
+  }
+  return first === -1 ? null : { first, last };
+}

package/src/ui-tailwind/editor-surface/perf-probe.ts

@@ -41,6 +41,11 @@ export const PREDICTED_LANE_COUNTERS = {
   rollback: "predictions.rollback",
   structuralDivergence: "predictions.structuralDivergence",
   bailBeforePredict: "predictions.bailBeforePredict",
+  refreshSelectionOnly: "predictions.refresh.selectionOnly",
+  refreshLocalTextEquivalent: "predictions.refresh.localTextEquivalent",
+  refreshSurfaceOnly: "predictions.refresh.surfaceOnly",
+  refreshFullProjection: "predictions.refresh.fullProjection",
+  refreshBlocked: "predictions.refresh.blocked",
 } as const;
 
 export interface PerfProbeSample {