@plannotator/ui 0.33.0 → 0.35.0

package/components/ImageAnnotator/index.tsx

@@ -2,8 +2,16 @@ import React, { useState, useCallback, useEffect, useRef } from 'react';
 import { Canvas } from './Canvas';
 import { Toolbar } from './Toolbar';
 import { renderStroke } from './utils';
-import type { Point, AnnotatorState } from './types';
-import { DEFAULT_STATE } from './types';
+import type { Point } from './types';
+import { useImageAnnotatorShortcuts } from '../../shortcuts';
+import {
+  DEFAULT_STROKE_HISTORY_STATE,
+  clearStrokeHistory,
+  recordStroke,
+  redoStroke,
+  undoStroke,
+  type StrokeHistoryState,
+} from './strokeHistory';
 
 interface ImageAnnotatorProps {
   imageSrc: string;
@@ -21,7 +29,7 @@ export const ImageAnnotator: React.FC<ImageAnnotatorProps> = ({
   onClose,
   initialName = '',
 }) => {
-  const [state, setState] = useState<AnnotatorState>(DEFAULT_STATE);
+  const [state, setState] = useState<StrokeHistoryState>(DEFAULT_STROKE_HISTORY_STATE);
   const [saving, setSaving] = useState(false);
   const [name, setName] = useState(initialName);
   const imageRef = useRef<HTMLImageElement | null>(null);
@@ -30,51 +38,11 @@ export const ImageAnnotator: React.FC<ImageAnnotatorProps> = ({
   // Reset state when dialog opens
   useEffect(() => {
     if (isOpen) {
-      setState(DEFAULT_STATE);
+      setState(DEFAULT_STROKE_HISTORY_STATE);
       setName(initialName);
     }
   }, [isOpen, initialName]);
 
-  // Keyboard shortcuts
-  useEffect(() => {
-    if (!isOpen) return;
-
-    const handleKeyDown = (e: KeyboardEvent) => {
-      // Don't intercept when typing in the name input
-      const target = e.target as HTMLElement;
-      if (target.tagName === 'INPUT') {
-        if (e.key === 'Escape') {
-          // Blur and let the next Escape close
-          target.blur();
-          e.preventDefault();
-        }
-        return;
-      }
-
-      // Escape or Enter to accept
-      if (e.key === 'Escape' || e.key === 'Enter') {
-        e.preventDefault();
-        handleAccept();
-        return;
-      }
-
-      // Cmd+Z to undo
-      if ((e.metaKey || e.ctrlKey) && e.key === 'z') {
-        e.preventDefault();
-        handleUndo();
-        return;
-      }
-
-      // 1/2/3 to switch tools
-      if (e.key === '1') setState(s => ({ ...s, tool: 'pen' }));
-      if (e.key === '2') setState(s => ({ ...s, tool: 'arrow' }));
-      if (e.key === '3') setState(s => ({ ...s, tool: 'circle' }));
-    };
-
-    window.addEventListener('keydown', handleKeyDown);
-    return () => window.removeEventListener('keydown', handleKeyDown);
-  }, [isOpen, state.strokes]);
-
   const handleStrokeStart = useCallback((point: Point) => {
     const id = crypto.randomUUID();
     setState(s => ({
@@ -107,27 +75,20 @@ export const ImageAnnotator: React.FC<ImageAnnotatorProps> = ({
       if (!s.currentStroke || s.currentStroke.points.length < 2) {
         return { ...s, currentStroke: null };
       }
-      return {
-        ...s,
-        strokes: [...s.strokes, s.currentStroke],
-        currentStroke: null,
-      };
+      return recordStroke(s, s.currentStroke);
     });
   }, []);
 
   const handleUndo = useCallback(() => {
-    setState(s => ({
-      ...s,
-      strokes: s.strokes.slice(0, -1),
-    }));
+    setState(undoStroke);
+  }, []);
+
+  const handleRedo = useCallback(() => {
+    setState(redoStroke);
   }, []);
 
   const handleClear = useCallback(() => {
-    setState(s => ({
-      ...s,
-      strokes: [],
-      currentStroke: null,
-    }));
+    setState(clearStrokeHistory);
   }, []);
 
   const handleImageLoad = useCallback((img: HTMLImageElement) => {
@@ -159,7 +120,8 @@ export const ImageAnnotator: React.FC<ImageAnnotatorProps> = ({
 
       // Composite image + drawings
       const canvas = document.createElement('canvas');
-      const ctx = canvas.getContext('2d')!;
+      const ctx = canvas.getContext('2d');
+      if (!ctx) throw new Error('Canvas 2D context is unavailable');
 
       canvas.width = img.naturalWidth;
       canvas.height = img.naturalHeight;
@@ -190,6 +152,29 @@ export const ImageAnnotator: React.FC<ImageAnnotatorProps> = ({
     }
   };
 
+  const keyboardTargetIsInput = (event: KeyboardEvent): boolean =>
+    event.composedPath()[0] instanceof HTMLInputElement;
+
+  useImageAnnotatorShortcuts({
+    handlers: {
+      penTool: { when: (event) => isOpen && !saving && !keyboardTargetIsInput(event), handle: () => setState((current) => ({ ...current, tool: 'pen' })) },
+      arrowTool: { when: (event) => isOpen && !saving && !keyboardTargetIsInput(event), handle: () => setState((current) => ({ ...current, tool: 'arrow' })) },
+      circleTool: { when: (event) => isOpen && !saving && !keyboardTargetIsInput(event), handle: () => setState((current) => ({ ...current, tool: 'circle' })) },
+      undo: {
+        when: (event) => isOpen && !saving && !keyboardTargetIsInput(event) && state.strokes.length > 0,
+        handle: handleUndo,
+      },
+      redo: {
+        when: (event) => isOpen && !saving && !keyboardTargetIsInput(event) && state.futureStrokes.length > 0,
+        handle: handleRedo,
+      },
+      save: {
+        when: (event) => isOpen && !saving && !keyboardTargetIsInput(event),
+        handle: () => { void handleAccept(); },
+      },
+    },
+  });
+
   const handleBackdropClick = (e: React.MouseEvent) => {
     if (e.target === e.currentTarget) {
       handleAccept();
@@ -212,10 +197,12 @@ export const ImageAnnotator: React.FC<ImageAnnotatorProps> = ({
           color={state.color}
           strokeSize={state.strokeSize}
           canUndo={state.strokes.length > 0}
+          canRedo={state.futureStrokes.length > 0}
           onToolChange={(tool) => setState(s => ({ ...s, tool }))}
           onColorChange={(color) => setState(s => ({ ...s, color }))}
           onStrokeSizeChange={(strokeSize) => setState(s => ({ ...s, strokeSize }))}
           onUndo={handleUndo}
+          onRedo={handleRedo}
           onClear={handleClear}
           onSave={handleAccept}
         />
@@ -242,6 +229,11 @@ export const ImageAnnotator: React.FC<ImageAnnotatorProps> = ({
               value={name}
               onChange={(e) => setName(e.target.value)}
               onKeyDown={(e) => {
+                if (e.key === 'Escape') {
+                  e.preventDefault();
+                  e.currentTarget.blur();
+                  return;
+                }
                 if (e.key === 'Enter' && !e.nativeEvent.isComposing) {
                   e.preventDefault();
                   handleAccept();

package/components/ImageAnnotator/strokeHistory.ts

@@ -0,0 +1,58 @@
+import { DEFAULT_STATE, type AnnotatorState, type Stroke } from './types';
+
+/** Internal image-annotator state that adds redo without widening the published state contract. */
+export interface StrokeHistoryState extends AnnotatorState {
+  /** Strokes removed by undo, newest redo candidate last. */
+  futureStrokes: Stroke[];
+}
+
+/** Initial state for the image annotator's internal stroke history. */
+export const DEFAULT_STROKE_HISTORY_STATE: StrokeHistoryState = {
+  ...DEFAULT_STATE,
+  futureStrokes: [],
+};
+
+/** Commit a completed stroke and invalidate the abandoned redo branch. */
+export function recordStroke(state: StrokeHistoryState, stroke: Stroke): StrokeHistoryState {
+  return {
+    ...state,
+    strokes: [...state.strokes, stroke],
+    futureStrokes: [],
+    currentStroke: null,
+  };
+}
+
+/** Move the latest visible stroke to the redo stack. */
+export function undoStroke(state: StrokeHistoryState): StrokeHistoryState {
+  const stroke = state.strokes.at(-1);
+  if (!stroke) return state;
+  return {
+    ...state,
+    strokes: state.strokes.slice(0, -1),
+    futureStrokes: [...state.futureStrokes, stroke],
+    currentStroke: null,
+  };
+}
+
+/** Restore the latest stroke removed by undo. */
+export function redoStroke(state: StrokeHistoryState): StrokeHistoryState {
+  const stroke = state.futureStrokes.at(-1);
+  if (!stroke) return state;
+  return {
+    ...state,
+    strokes: [...state.strokes, stroke],
+    futureStrokes: state.futureStrokes.slice(0, -1),
+    currentStroke: null,
+  };
+}
+
+/** Clear the canvas and invalidate both stroke branches. */
+export function clearStrokeHistory(state: StrokeHistoryState): StrokeHistoryState {
+  if (state.strokes.length === 0 && state.futureStrokes.length === 0 && state.currentStroke === null) return state;
+  return {
+    ...state,
+    strokes: [],
+    futureStrokes: [],
+    currentStroke: null,
+  };
+}

package/components/MermaidBlock.tsx

@@ -9,6 +9,12 @@ import {
   loadMermaidRuntime,
   __setMermaidRuntimeLoaderForTests,
 } from '../utils/mermaid';
+import { loadMathRenderer } from '../utils/math';
+import { hasMermaidMath } from '../utils/mermaid-math-slot';
+import { createRuntimeRetryEpoch } from '../utils/runtimeRetry';
+
+/** One Retry re-attempts every block whose runtime import failed (see utils/runtimeRetry). */
+const mermaidRetryEpoch = createRuntimeRetryEpoch();
 
 // Re-exported: the config pin test and the lazy-retry test import them from here.
 export { MERMAID_CONFIG, __setMermaidRuntimeLoaderForTests };
@@ -133,6 +139,16 @@ const MermaidBlockImpl: React.FC<{ block: Block }> = ({ block }) => {
   const [retryToken, setRetryToken] = useState(0);
   const [showSource, setShowSource] = useState(false);
   const [isExpanded, setIsExpanded] = useState(false);
+  // A sibling's Retry re-attempts this block too, but only while its own
+  // failure was the shared runtime import; a healthy block or a diagram
+  // syntax error is left alone.
+  const runtimeUnavailableRef = useRef(runtimeUnavailable);
+  runtimeUnavailableRef.current = runtimeUnavailable;
+  useEffect(() => mermaidRetryEpoch.subscribe(() => {
+    if (!runtimeUnavailableRef.current) return;
+    setError(null);
+    setRetryToken((token) => token + 1);
+  }), []);
 
   // All zoom/pan state as refs to avoid re-renders
   const zoomLevelRef = useRef(1);
@@ -208,6 +224,20 @@ const MermaidBlockImpl: React.FC<{ block: Block }> = ({ block }) => {
         return;
       }
       try {
+        // A `$$` label makes Mermaid render KaTeX. On a host that redirects
+        // Mermaid's `katex` import to `utils/mermaid-math-slot` the label is
+        // typeset through the math slot, which must be filled by then: warm
+        // it with the registered loader first. A filled slot (Plannotator's
+        // eager entry) resolves at once; a load failure is left to the
+        // render, whose error panel names it with the source.
+        if (hasMermaidMath(block.content)) {
+          try {
+            await loadMathRenderer();
+          } catch {
+            // Reported by the render below.
+          }
+          if (cancelled) return;
+        }
         const id = `mermaid-${block.id}`;
         const { svg: renderedSvg } = await mermaid.render(id, block.content);
         if (!cancelled) {
@@ -443,10 +473,7 @@ const MermaidBlockImpl: React.FC<{ block: Block }> = ({ block }) => {
           {runtimeUnavailable && (
             <button
               type="button"
-              onClick={() => {
-                setError(null);
-                setRetryToken((token) => token + 1);
-              }}
+              onClick={() => mermaidRetryEpoch.bump()}
               className="ml-auto rounded-md border border-destructive/30 px-2 py-0.5 text-xs text-destructive hover:bg-destructive/10"
               title="Retry loading the diagram renderer"
             >

package/components/PlanHeaderMenu.tsx

@@ -40,7 +40,7 @@ interface PlanHeaderMenuProps {
 }
 
 export interface CompactPlanAction {
-  id: 'exit' | 'feedback' | 'approve' | 'copy' | 'done' | 'edit' | 'tools' | 'annotate' | 'annotations' | 'ai' | 'review';
+  id: 'exit' | 'feedback' | 'approve' | 'copy' | 'done' | 'edit' | 'tools' | 'annotate' | 'refresh' | 'annotations' | 'ai' | 'review';
   label: string;
   subtitle?: string;
   onSelect: () => void;

package/components/Settings.tsx

@@ -3,7 +3,7 @@ import { createPortal } from 'react-dom';
 import type { AnnotateAgentTerminalSide } from '@plannotator/core/agent-terminal';
 import type { Origin } from '@plannotator/core/agents';
 import type { DiffLineBgIntensity } from '@plannotator/core/config-types';
-import { configStore, useConfigValue, setReviewPanelView, setReviewDefaultDiffType } from '../config';
+import { configStore, useConfigValue, setReviewPanelView, setReviewDefaultDiffType, setReviewAutoViewed } from '../config';
 import { setWebMcpToolsEnabled, useWebMcpToolsEnabled } from '../webmcp/preference';
 import { loadDiffFont } from '../utils/diffFonts';
 import { TaterSpritePullup } from './TaterSpritePullup';
@@ -375,8 +375,23 @@ function ReviewAnalysisTab() {
 const GitTab: React.FC<{ sinceBaseUnavailable?: boolean }> = ({ sinceBaseUnavailable }) => {
   const defaultDiffType = useConfigValue('defaultDiffType');
   const reviewPanelView = useConfigValue('reviewPanelView');
+  const reviewAutoViewed = useConfigValue('reviewAutoViewed');
   return (
     <div className="space-y-5">
+      <div className="space-y-2">
+        <div className="text-xs font-semibold uppercase tracking-wider text-muted-foreground">
+          Viewed files
+        </div>
+        {/* Never write `reviewAutoViewed` directly — setReviewAutoViewed also
+            consumes the first-time notice, since an explicit toggle is proof
+            the reviewer already found the switch. */}
+        <ToggleSwitch
+          checked={reviewAutoViewed}
+          onChange={(v) => setReviewAutoViewed(v)}
+          label="Auto-mark viewed"
+          description="Mark a file viewed when you scroll past it or move on to another file. Files you un-view stay un-viewed, and files that change on refresh become un-viewed."
+        />
+      </div>
       <div className="space-y-2">
         <div>
           <div className="text-sm font-medium">Default review view</div>

package/components/StickyHeaderLane.tsx

@@ -65,6 +65,8 @@ interface StickyHeaderLaneProps {
   mode: EditorMode;
   onModeChange: (mode: EditorMode) => void;
   taterMode?: boolean;
+  /** Omit the Quick Label tool in the compact toolstrip (mirrors AnnotationToolstripProps.hideQuickLabel). */
+  hideQuickLabel?: boolean;
 
   // Badge state
   repoInfo?: { display: string; branch?: string } | null;
@@ -95,6 +97,7 @@ export const StickyHeaderLane: React.FC<StickyHeaderLaneProps> = ({
   mode,
   onModeChange,
   taterMode,
+  hideQuickLabel,
   repoInfo,
   planDiffStats,
   isPlanDiffActive,
@@ -252,6 +255,7 @@ export const StickyHeaderLane: React.FC<StickyHeaderLaneProps> = ({
               mode={mode}
               onModeChange={onModeChange}
               taterMode={taterMode}
+              hideQuickLabel={hideQuickLabel}
               compact
               iconOnly={isNarrow || isToolstripIconOnly}
             />

package/components/html-viewer/HtmlViewer.tsx

@@ -281,9 +281,19 @@ export interface HtmlViewerProps {
   bridgeReadyTimeoutMs?: number;
   /** The bridge could not be established on the `bridgeScriptUrl` path (no
    *  ready within the timeout, or a protocol version mismatch). The surface
-   *  shows its own banner as well; this lets the host react (telemetry, a
-   *  retry affordance). Never called on the inline path. */
+   *  shows its own banner as well unless `bridgeErrorDisplay` is `'none'`;
+   *  this lets the host react (telemetry, a retry affordance). Never called
+   *  on the inline path. */
   onBridgeUnavailable?: (info: BridgeUnavailableInfo) => void;
+  /**
+   * Who renders the bridge-failure strip on the `bridgeScriptUrl` path.
+   * `'banner'` (default): the package renders its `[data-bridge-error]`
+   * strip over the frame, as in 0.33.0. `'none'`: no strip is rendered and
+   * the host owns the display through `onBridgeUnavailable`, which fires
+   * exactly as before (and a version mismatch still logs its one console
+   * warning). Meaningless on the inline path, which never shows a strip.
+   */
+  bridgeErrorDisplay?: "banner" | "none";
 }
 
 /**
@@ -329,6 +339,7 @@ export const HtmlViewer = forwardRef<ViewerHandle, HtmlViewerProps>(
       bridgeScriptUrl,
       bridgeReadyTimeoutMs = DEFAULT_BRIDGE_READY_TIMEOUT_MS,
       onBridgeUnavailable,
+      bridgeErrorDisplay = "banner",
     },
     ref,
   ) => {
@@ -1061,8 +1072,10 @@ export const HtmlViewer = forwardRef<ViewerHandle, HtmlViewerProps>(
             {/* bridgeScriptUrl path only: the bridge did not come up (no
                 ready within the timeout, or a stale asset's version). Floated
                 over the top of the iframe so it never changes the layout the
-                page renders in; the page itself stays visible. */}
-            {bridgeError && !bridgeErrorDismissed && (
+                page renders in; the page itself stays visible. A host that
+                renders its own notice from onBridgeUnavailable passes
+                bridgeErrorDisplay="none" and no strip is rendered at all. */}
+            {bridgeError && !bridgeErrorDismissed && bridgeErrorDisplay !== "none" && (
               <div
                 role="alert"
                 data-print-hide

package/components/html-viewer/useHtmlAnnotation.ts

@@ -55,12 +55,12 @@ function nextHtmlAnnId(): string {
   return `html-ann-${Date.now().toString(36)}-${(htmlAnnSeq++).toString(36)}`;
 }
 
-/** Ids minted by this module for locally created annotations (create-mark).
- * Module-scoped like the sequence above: a host that swaps a local id for
- * its own server id keeps the local mark until it removes it, and the
- * unanchored union needs to recognise such ids whichever viewer instance
- * minted them. Bounded: only ids from this page load, one entry per create. */
-const mintedHtmlAnnIds = new Set<string>();
+// Ids minted for locally created annotations (create-mark) live per hook
+// instance (mintedIdsRef below), not per module: the unanchored union only
+// consults them against the bridge of the instance that minted them (a
+// remounted viewer restores from the host's list and never reports an id it
+// was not asked for), and a module-wide set leaked every id ever minted into
+// unrelated later instances of a long-lived host page.
 
 function htmlCommentDraftKey(
   text: string,
@@ -463,6 +463,15 @@ export function useHtmlAnnotation({
   enabledRef.current = enabled;
   const modeRef = useRef(mode);
   modeRef.current = mode;
+  // Ids this instance minted (see the module comment above nextHtmlAnnId);
+  // released on unmount so nothing outlives the viewer that created it.
+  const mintedIdsRef = useRef<Set<string>>(new Set());
+  useEffect(() => {
+    const minted = mintedIdsRef.current;
+    return () => {
+      minted.clear();
+    };
+  }, []);
   // Mirror toolbar visibility into a ref so the (stable) message handler can gate
   // type-to-comment on "the markup toolbar is showing", like AnnotationToolbar does.
   const toolbarStateRef = useRef(toolbarState);
@@ -805,7 +814,7 @@ export function useHtmlAnnotation({
       if (!text || type !== AnnotationType.DELETION) return;
 
       const id = nextHtmlAnnId();
-      mintedHtmlAnnIds.add(id);
+      mintedIdsRef.current.add(id);
       post({ type: `${PREFIX}create-mark`, id, annotationType: "deletion" });
       onAddRef.current?.({
         id,
@@ -864,7 +873,7 @@ export function useHtmlAnnotation({
           : undefined;
 
       const id = nextHtmlAnnId();
-      mintedHtmlAnnIds.add(id);
+      mintedIdsRef.current.add(id);
       post({ type: `${PREFIX}create-mark`, id, annotationType: "comment" });
       onAddRef.current?.({
         id,
@@ -910,7 +919,7 @@ export function useHtmlAnnotation({
         : undefined;
 
     const id = nextHtmlAnnId();
-    mintedHtmlAnnIds.add(id);
+    mintedIdsRef.current.add(id);
     post({ type: `${PREFIX}create-mark`, id, annotationType: "comment" });
     onAddRef.current?.({
       id,
@@ -970,7 +979,7 @@ export function useHtmlAnnotation({
       const text = pendingTextRef.current;
       if (!text) return;
       const id = nextHtmlAnnId();
-      mintedHtmlAnnIds.add(id);
+      mintedIdsRef.current.add(id);
       post({ type: `${PREFIX}create-mark`, id, annotationType: "comment" });
       onAddRef.current?.({
         id,
@@ -1067,6 +1076,6 @@ export function useHtmlAnnotation({
     removeDraftTarget,
     flashDraftTarget,
     composerFocusToken,
-    createdAnnotationIds: mintedHtmlAnnIds,
+    createdAnnotationIds: mintedIdsRef.current,
   };
 }

package/config/index.ts

@@ -5,5 +5,8 @@ export {
   setReviewPanelView,
   setReviewDefaultDiffType,
   getPersistedReviewPanelView,
+  setReviewAutoViewed,
+  needsAutoViewedNotice,
+  markAutoViewedNoticeSeen,
   type ReviewDefaultDiffType,
 } from './reviewView';

package/config/reviewView.ts

@@ -1,5 +1,6 @@
 import { configStore } from './configStore';
 import { SETTINGS } from './settings';
+import { storage } from '../utils/storage';
 
 /**
  * The ONLY writers for the coupled setting pair (reviewPanelView,
@@ -73,3 +74,39 @@ export function setReviewDefaultDiffType(
     store.set('reviewPanelViewLastUsed', 'tree');
   }
 }
+
+
+/**
+ * One-time gate for the auto-mark-viewed notice — the toast that fires the
+ * FIRST time auto-view actually marks a file, i.e. the moment the feature
+ * demonstrates itself. Cookie-based, mirroring the other review first-run
+ * gates, so it survives the random port each session runs on. Versioned so a
+ * meaningful revision can re-show it.
+ *
+ * It lives beside the setting rather than in the review app because BOTH
+ * writers of the setting (Settings > Git here, and the file-list gear in the
+ * review app) must consume the gate: someone who found the switch has
+ * demonstrably discovered the feature and must never be told about it.
+ */
+const AUTO_VIEWED_NOTICE_SEEN_KEY = 'plannotator-auto-viewed-notice-seen';
+const AUTO_VIEWED_NOTICE_VERSION = '1';
+
+export function needsAutoViewedNotice(): boolean {
+  return storage.getItem(AUTO_VIEWED_NOTICE_SEEN_KEY) !== AUTO_VIEWED_NOTICE_VERSION;
+}
+
+export function markAutoViewedNoticeSeen(): void {
+  storage.setItem(AUTO_VIEWED_NOTICE_SEEN_KEY, AUTO_VIEWED_NOTICE_VERSION);
+}
+
+/**
+ * The only writer of `reviewAutoViewed` outside the notice's own "Turn off"
+ * action. Stamps the notice gate: an explicit toggle is proof of discovery.
+ */
+export function setReviewAutoViewed(
+  value: boolean,
+  store: PanelViewConfigStore = configStore,
+): void {
+  markAutoViewedNoticeSeen();
+  store.set('reviewAutoViewed', value);
+}

package/config/settings.ts

@@ -261,6 +261,21 @@ export const SETTINGS = {
     serverKey: undefined, fromServer: undefined, toServer: undefined,
   },
 
+  // Mark a file viewed when the reviewer scrolls past it or moves on to
+  // another file. Cookie-only like the other review-chrome preferences: it
+  // shapes how the local file list checks itself off and changes no review
+  // semantics (viewed gates nothing on submit).
+  reviewAutoViewed: {
+    defaultValue: true as boolean,
+    fromCookie: () => {
+      const value = storage.getItem('plannotator-review-auto-viewed');
+      return value === 'true' ? true : value === 'false' ? false : undefined;
+    },
+    toCookie: (value: boolean) =>
+      storage.setItem('plannotator-review-auto-viewed', String(value)),
+    serverKey: undefined, fromServer: undefined, toServer: undefined,
+  },
+
   reviewShowStageControls: {
     defaultValue: true as boolean,
     fromCookie: () => {

package/hooks/useCodeAnnotationDraft.ts

@@ -16,6 +16,17 @@ interface DraftData {
   descriptionAnnotations?: Annotation[];
   commentAnnotations?: CommentAnnotation[];
   viewedFiles?: string[];
+  /**
+   * Files the reviewer manually un-viewed, which auto-mark-viewed must never
+   * re-check (the "come back to this" contract). Additive and optional: a
+   * draft written before this field restores fine, and a draft carrying it is
+   * ignored gracefully by an older build.
+   *
+   * Deliberately absent from `isEmpty` and from the engagement signal — a
+   * session whose only state is suppression is still an empty draft and is
+   * still cleared, keeping #948's clear-everything semantics untouched.
+   */
+  autoViewSuppressed?: string[];
   draftGeneration?: number;
   ts: number;
 }
@@ -40,13 +51,14 @@ interface UseCodeAnnotationDraftOptions {
   descriptionAnnotations?: Annotation[];
   commentAnnotations?: CommentAnnotation[];
   viewedFiles: Set<string>;
+  autoViewSuppressed?: Set<string>;
   isApiMode: boolean;
   submitted: boolean;
 }
 
 interface UseCodeAnnotationDraftResult {
   draftBanner: { count: number; viewedCount: number; timeAgo: string } | null;
-  restoreDraft: () => { annotations: CodeAnnotation[]; descriptionAnnotations: Annotation[]; commentAnnotations: CommentAnnotation[]; viewedFiles: string[] };
+  restoreDraft: () => { annotations: CodeAnnotation[]; descriptionAnnotations: Annotation[]; commentAnnotations: CommentAnnotation[]; viewedFiles: string[]; autoViewSuppressed: string[] };
   getDraftGeneration: () => number;
   dismissDraft: () => void;
 }
@@ -56,6 +68,7 @@ export function useCodeAnnotationDraft({
   descriptionAnnotations = [],
   commentAnnotations = [],
   viewedFiles,
+  autoViewSuppressed,
   isApiMode,
   submitted,
 }: UseCodeAnnotationDraftOptions): UseCodeAnnotationDraftResult {
@@ -145,6 +158,9 @@ export function useCodeAnnotationDraft({
         descriptionAnnotations,
         commentAnnotations,
         viewedFiles: [...viewedFiles],
+        ...(autoViewSuppressed && autoViewSuppressed.size > 0
+          ? { autoViewSuppressed: [...autoViewSuppressed] }
+          : {}),
         draftGeneration,
         ts: Date.now(),
       };
@@ -155,7 +171,7 @@ export function useCodeAnnotationDraft({
     return () => {
       if (timerRef.current) clearTimeout(timerRef.current);
     };
-  }, [annotations, descriptionAnnotations, commentAnnotations, viewedFiles, isApiMode, submitted]);
+  }, [annotations, descriptionAnnotations, commentAnnotations, viewedFiles, autoViewSuppressed, isApiMode, submitted]);
 
   const restoreDraft = useCallback(() => {
     // Cancel any pending autosave so it can't fire with pre-restore state and
@@ -169,6 +185,7 @@ export function useCodeAnnotationDraft({
       descriptionAnnotations: data?.descriptionAnnotations ?? [],
       commentAnnotations: data?.commentAnnotations ?? [],
       viewedFiles: data?.viewedFiles ?? [],
+      autoViewSuppressed: data?.autoViewSuppressed ?? [],
     };
   }, []);