@plannotator/ui 0.34.0 → 0.35.0

package/HANDOFF.md

@@ -195,6 +195,7 @@ We deliberately did **not** restructure the exports map in this PR (move-don't-r
 | `components/MarkdownDiff` | Theme-bridging wrapper over `@plannotator/markdown-editor`'s frozen two-revision diff. Same shim pattern as `components/MarkdownEditor` (ThemeProvider bridge, `extensions` passthrough, grid card chrome); never editable. See "Frozen markdown diff (0.28.0)". |
 | `components/CommentPopover` | Anchor capture + comment entry. Ask-AI UI renders only if you pass `onAskAI`. |
 | `components/AnnotationPanel` | Renders from your annotation state; no fetches of its own. |
+| `components/AnnotationToolstrip` | The annotation mode toolstrip (Select / Pinpoint / Markup / Comment / Redline / Label). **Pass `showHelpLink={false}` in a host** — the default help modal embeds Plannotator's own YouTube walkthroughs. `hideQuickLabel` omits only the Label button (`StickyHeaderLane` forwards it, so the pinned scroll header matches); it hides the control, it does **not** clamp the mode — keep host mode state out of `'quickLabel'` (including preferences restored through `utils/editorMode`, which accepts it from storage) or text selection silently opens the quick-label picker with no visible cause. `hideInputMethodSwitch` likewise omits the pinpoint/drag switch. *(Blessed in 0.35.0.)* |
 | `components/ThemeProvider` | Color-mode context. |
 | `theme-modes` (`THEME_MODES`, `Mode`) | The supported Light/Dark/System catalog and mode type. `Mode` also remains exported from `components/ThemeProvider` for compatibility with existing consumers. |
 | `components/ImageThumbnail` / `getImageSrc` | Routes through `imageSrcResolver`. |

package/README.md

@@ -129,6 +129,14 @@ The srcdoc then carries one classic `<script src>` in the exact place the inline
 - **`@plannotator/ui/shortcuts`**: the declarative keyboard-shortcut engine (`defineShortcutScope`, `useShortcutScope`) and the per-surface scopes, including `useHtmlAnnotateShortcuts` for the Mod+Shift+A Annotate/Interact chord on HTML surfaces. Pure React plus `utils/platform`; no backend.
 - **`@plannotator/ui/utils/inputMethod`**: `getInputMethod(surface)` / `saveInputMethod(method, surface)` / `refreshInputMethodStamp(method)`, the per-surface pinpoint-or-drag preference with its TTL, persisted through the `storageBackend` seam.
 
+#### Toolstrip host props (0.35.0)
+
+`components/AnnotationToolstrip` is supported host surface: the annotation mode toolstrip with per-tool opt-outs, all defaulting to today's rendering.
+
+- **`hideQuickLabel`** omits the Quick Label tool. `StickyHeaderLane` forwards it, so the pinned scroll header stays consistent. It hides the button only — it does not clamp the mode, so keep host mode state out of `'quickLabel'` (including preferences restored through `utils/editorMode`).
+- **`showHelpLink={false}`** for hosts: the default help modal embeds Plannotator's own video walkthroughs.
+- **`hideInputMethodSwitch`** omits the pinpoint/drag input-method switch.
+
 ### WebMCP provider (`@plannotator/ui/webmcp`; 0.32.0)
 
 The engine that lets a browser-integrated agent (Chrome/Edge WebMCP, `document.modelContext`) call in-page tools on a document surface. Feature-detected once; a browser without the API sees no registration, no DOM, no network, no timers. Seam: `configurePlannotatorUI({ webmcp: { enabled, namePrefix } })`, default enabled with the `plannotator.` prefix; pass `enabled: false` to keep a host page tool-free, or your own prefix to namespace the tools beside your own. There is deliberately no confirmation seam: the catalog is read-and-comment only (no approve / submit / close tools), and the agent may only edit or remove comments stamped `source: "browser-agent"`.

package/components/AnnotationPanel.tsx

@@ -7,6 +7,7 @@ import { useIsMobile } from '../hooks/useIsMobile';
 import { OverlayScrollArea } from './OverlayScrollArea';
 import { Button } from './ui/button';
 import { cn } from '../lib/utils';
+import { resolveReplyParents, resolveThreadRootTimestamps } from '@plannotator/core/annotation-threads';
 
 // Card type-word colors. Deletion uses `destructive` (reliably red on every
 // theme, matching the in-document .deletion highlight). Comment uses the
@@ -40,50 +41,47 @@ const TrashCardIcon = () => (
 
 /**
  * Order annotations so every reply follows its parent (replies among
- * themselves stay in creation order). A reply whose parent is absent renders
- * as a top-level card. Without any `inReplyTo` the input order is returned
- * unchanged, so annotations without replies render exactly as before.
+ * themselves stay in creation order). The threading rule is the shared one
+ * (resolveReplyParents, also what the export applies): a reply whose parent
+ * is absent, a self-reference, and every member of an `inReplyTo` cycle
+ * render as top-level cards in input order, so nothing is ever dropped.
+ * Without any `inReplyTo` the input order is returned unchanged, so
+ * annotations without replies render exactly as before.
  */
 export function threadReplies(sorted: Annotation[]): Array<{ annotation: Annotation; isReply: boolean }> {
   if (!sorted.some((a) => a.inReplyTo)) return sorted.map((annotation) => ({ annotation, isReply: false }));
-  const ids = new Set(sorted.map((a) => a.id));
+  const parents = resolveReplyParents(sorted);
   const byParent = new Map<string, Annotation[]>();
   for (const a of sorted) {
-    if (a.inReplyTo && ids.has(a.inReplyTo) && a.inReplyTo !== a.id) {
-      const list = byParent.get(a.inReplyTo) ?? [];
-      list.push(a);
-      byParent.set(a.inReplyTo, list);
-    }
+    const parent = parents.get(a.id);
+    if (!parent) continue;
+    const list = byParent.get(parent) ?? [];
+    list.push(a);
+    byParent.set(parent, list);
   }
+  // Depth-first, iteratively: a 5,000-deep chain must not recurse 5,000
+  // frames deep. The stack holds each node's replies in reverse so they pop
+  // in creation order.
   const out: Array<{ annotation: Annotation; isReply: boolean }> = [];
-  const emitted = new Set<string>();
-  const emit = (a: Annotation, isReply: boolean) => {
-    if (emitted.has(a.id)) return;
-    emitted.add(a.id);
-    out.push({ annotation: a, isReply });
-    for (const reply of byParent.get(a.id) ?? []) emit(reply, true);
+  const stack: Array<{ annotation: Annotation; isReply: boolean }> = [];
+  const pushReplies = (a: Annotation) => {
+    const replies = byParent.get(a.id);
+    if (!replies) return;
+    for (let i = replies.length - 1; i >= 0; i--) stack.push({ annotation: replies[i], isReply: true });
   };
   for (const a of sorted) {
-    if (a.inReplyTo && ids.has(a.inReplyTo) && a.inReplyTo !== a.id) continue;
-    emit(a, false);
+    if (parents.get(a.id)) continue;
+    out.push({ annotation: a, isReply: false });
+    pushReplies(a);
+    while (stack.length > 0) {
+      const next = stack.pop()!;
+      out.push(next);
+      pushReplies(next.annotation);
+    }
   }
-  for (const a of sorted) emit(a, false);
   return out;
 }
 
-/** Timeline position of an annotation: its own time, or its thread root's for replies. */
-function threadTs(annotation: Annotation, all: Annotation[]): number {
-  let current = annotation;
-  const seen = new Set<string>();
-  while (current.inReplyTo && !seen.has(current.id)) {
-    seen.add(current.id);
-    const parent = all.find((a) => a.id === current.inReplyTo);
-    if (!parent) break;
-    current = parent;
-  }
-  return current.createdA;
-}
-
 interface DirectEditsPanelItem {
   id: string;
   title?: string;
@@ -178,13 +176,16 @@ export const AnnotationPanel: React.FC<PanelProps> = ({
   // sit right after its parent (and the parent's earlier replies) at the
   // parent's timeline position. With no replies the order is untouched.
   const threadedAnnotations = threadReplies(sortedAnnotations);
+  // Thread timestamps are resolved once per render, linearly (shared helper),
+  // and the comparator only reads the map: resolving each chain inside the
+  // comparator with a linear parent lookup was O(n^2 log n) and froze the
+  // tab on a few thousand threaded comments.
+  const threadRootTs = resolveThreadRootTimestamps(sortedAnnotations);
   const timelineEntries = [
-    ...threadedAnnotations.map(({ annotation, isReply }) => ({ kind: 'plan' as const, ts: annotation.createdA, annotation, isReply })),
-    ...sortedCodeAnnotations.map(annotation => ({ kind: 'code' as const, ts: annotation.createdAt, annotation, isReply: false })),
+    ...threadedAnnotations.map(({ annotation, isReply }) => ({ kind: 'plan' as const, ts: annotation.createdA, threadTs: threadRootTs.get(annotation.id) ?? annotation.createdA, annotation, isReply })),
+    ...sortedCodeAnnotations.map(annotation => ({ kind: 'code' as const, ts: annotation.createdAt, threadTs: annotation.createdAt, annotation, isReply: false })),
   ].sort((a, b) => {
-    const ta = a.kind === 'plan' ? threadTs(a.annotation, sortedAnnotations) : a.ts;
-    const tb = b.kind === 'plan' ? threadTs(b.annotation, sortedAnnotations) : b.ts;
-    if (ta !== tb) return ta - tb;
+    if (a.threadTs !== b.threadTs) return a.threadTs - b.threadTs;
     return a.ts - b.ts;
   });
   const totalCount = annotations.length + codeAnnotations.length + (editorAnnotations?.length ?? 0);

package/components/AnnotationToolstrip.tsx

@@ -2,7 +2,8 @@ import React, { useState, useRef, useLayoutEffect, useEffect } from 'react';
 import type { EditorMode, InputMethod } from '../types';
 import { TaterSpritePullup } from './TaterSpritePullup';
 
-interface AnnotationToolstripProps {
+/** Props for the shared annotation input and action mode toolstrip. */
+export interface AnnotationToolstripProps {
   inputMethod: InputMethod;
   onInputMethodChange: (method: InputMethod) => void;
   mode: EditorMode;
@@ -30,8 +31,14 @@ interface AnnotationToolstripProps {
    * pinpoint-only, so the switch would be a dead control there.
    */
   hideInputMethodSwitch?: boolean;
+  /**
+   * Omit only the Quick Label action. Defaults to false so existing consumers
+   * retain the complete action-mode group.
+   */
+  hideQuickLabel?: boolean;
 }
 
+/** Render the shared input-method and annotation-mode controls. */
 export const AnnotationToolstrip: React.FC<AnnotationToolstripProps> = ({
   inputMethod,
   onInputMethodChange,
@@ -42,6 +49,7 @@ export const AnnotationToolstrip: React.FC<AnnotationToolstripProps> = ({
   showHelpLink = true,
   iconOnly = false,
   hideInputMethodSwitch = false,
+  hideQuickLabel = false,
 }) => {
   const [showHelp, setShowHelp] = useState(false);
   const [helpTab, setHelpTab] = useState<'selection' | 'plannotator'>('selection');
@@ -142,20 +150,22 @@ export const AnnotationToolstrip: React.FC<AnnotationToolstripProps> = ({
               </svg>
             }
           />
-          <ToolstripButton
-            active={mode === 'quickLabel'}
-            onClick={() => onModeChange('quickLabel')}
-            label="Label"
-            color="warning"
-            mounted={mounted}
-            compact={compact}
-            iconOnly={iconOnly}
-            icon={
-              <svg className="w-3.5 h-3.5 shrink-0" fill="none" viewBox="0 0 24 24" stroke="currentColor" strokeWidth={2}>
-                <path strokeLinecap="round" strokeLinejoin="round" d="M13 10V3L4 14h7v7l9-11h-7z" />
-              </svg>
-            }
-          />
+          {!hideQuickLabel && (
+            <ToolstripButton
+              active={mode === 'quickLabel'}
+              onClick={() => onModeChange('quickLabel')}
+              label="Label"
+              color="warning"
+              mounted={mounted}
+              compact={compact}
+              iconOnly={iconOnly}
+              icon={
+                <svg className="w-3.5 h-3.5 shrink-0" fill="none" viewBox="0 0 24 24" stroke="currentColor" strokeWidth={2}>
+                  <path strokeLinecap="round" strokeLinejoin="round" d="M13 10V3L4 14h7v7l9-11h-7z" />
+                </svg>
+              }
+            />
+          )}
         </div>
 
         {/* Help */}

package/components/GraphvizBlock.tsx

@@ -2,6 +2,7 @@ import React, { useRef, useState, useEffect, useCallback } from 'react';
 import { createPortal } from 'react-dom';
 import type { Viz } from '@viz-js/viz';
 import type { Block } from '../types';
+import { createRuntimeRetryEpoch } from '../utils/runtimeRetry';
 
 interface ViewBox {
   x: number;
@@ -60,6 +61,9 @@ export function __setVizLoaderForTests(
 
 const wait = (ms: number) => new Promise<void>((resolve) => setTimeout(resolve, ms));
 
+/** One Retry re-attempts every block whose engine import failed (see utils/runtimeRetry). */
+const vizRetryEpoch = createRuntimeRetryEpoch();
+
 function parseViewBox(svgEl: SVGSVGElement): ViewBox | null {
   const raw = svgEl.getAttribute('viewBox');
   if (!raw) return null;
@@ -153,6 +157,16 @@ export const GraphvizBlock: 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 engine import; a healthy block or a dot syntax
+  // error is left alone.
+  const runtimeUnavailableRef = useRef(runtimeUnavailable);
+  runtimeUnavailableRef.current = runtimeUnavailable;
+  useEffect(() => vizRetryEpoch.subscribe(() => {
+    if (!runtimeUnavailableRef.current) return;
+    setError(null);
+    setRetryToken((token) => token + 1);
+  }), []);
 
   const zoomLevelRef = useRef(1);
   const isDraggingRef = useRef(false);
@@ -431,10 +445,7 @@ export const GraphvizBlock: React.FC<{ block: Block }> = ({ block }) => {
           {runtimeUnavailable && (
             <button
               type="button"
-              onClick={() => {
-                setError(null);
-                setRetryToken((token) => token + 1);
-              }}
+              onClick={() => vizRetryEpoch.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/HtmlSurfaceControls.tsx

@@ -55,9 +55,10 @@ export interface HtmlSurfaceControlsProps {
   onToggleArmed?: () => void;
   /** Whether the floating tools over the page are hidden (eye-off). */
   toolsHidden?: boolean;
-  /** Flip the tools. The eye (and the refresh beside it) render only when provided. */
+  /** Flip the tools. The eye renders only when provided. */
   onToggleTools?: () => void;
-  /** Whether a refresh is offered for this document. */
+  /** Whether a refresh is offered for this document. The refresh renders
+   *  whenever this is true and `onRefresh` is passed, with or without the eye. */
   canRefresh?: boolean;
   onRefresh?: () => void;
   isRefreshing?: boolean;
@@ -80,15 +81,21 @@ export function HtmlSurfaceControls({
   if (compact) return null;
   const text = { ...DEFAULT_HTML_SURFACE_CONTROL_LABELS, ...labels };
   const penLabel = armed ? labels?.annotateLabel : labels?.interactLabel;
+  const showRefresh = canRefresh && !!onRefresh;
   return (
     <>
-      {/* Show/hide tools: removes ALL floating chrome (sidebar tongue tabs +
+      {/* The refresh and the eye share one group, left of the pen. Each
+          renders on its own terms: the refresh whenever it is offered
+          (canRefresh + onRefresh), the eye whenever onToggleTools is passed,
+          so a host without the tools toggle still gets its refresh.
+
+          Show/hide tools: removes ALL floating chrome (sidebar tongue tabs +
           the comment/attachments cluster) from the DOM, leaving nothing over
-          the page. Sits left of the pen; this button is the only way back,
-          so it never hides itself. Eye = tools visible, eye-off = hidden. */}
-      {onToggleTools && (
+          the page. This button is the only way back, so it never hides
+          itself. Eye = tools visible, eye-off = hidden. */}
+      {(showRefresh || onToggleTools) && (
         <div className="ml-1 flex items-center gap-0.5">
-          {canRefresh && onRefresh && (
+          {showRefresh && (
             <button
               type="button"
               data-html-refresh
@@ -117,6 +124,7 @@ export function HtmlSurfaceControls({
               <span className="hidden sm:inline">{isRefreshing ? text.refreshing : text.refresh}</span>
             </button>
           )}
+          {onToggleTools && (
           <button
             type="button"
             data-html-tools-toggle
@@ -137,6 +145,7 @@ export function HtmlSurfaceControls({
             )}
             <span className="sr-only">{toolsHidden ? text.showTools : text.hideTools}</span>
           </button>
+          )}
         </div>
       )}
 

package/components/ImageAnnotator/Toolbar.tsx

@@ -7,10 +7,12 @@ interface ToolbarProps {
   color: string;
   strokeSize: number;
   canUndo: boolean;
+  canRedo?: boolean;
   onToolChange: (tool: Tool) => void;
   onColorChange: (color: string) => void;
   onStrokeSizeChange: (size: number) => void;
   onUndo: () => void;
+  onRedo?: () => void;
   onClear: () => void;
   onSave: () => void;
 }
@@ -44,6 +46,13 @@ const UndoIcon = () => (
   </svg>
 );
 
+const RedoIcon = () => (
+  <svg className="w-4 h-4" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth={2}>
+    <path d="M21 7v6h-6" />
+    <path d="M3 17a9 9 0 019-9 9 9 0 016 2.3L21 13" />
+  </svg>
+);
+
 const ClearIcon = () => (
   <svg className="w-4 h-4" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth={2}>
     <path strokeLinecap="round" strokeLinejoin="round" d="M6 18L18 6M6 6l12 12" />
@@ -81,10 +90,12 @@ export const Toolbar: React.FC<ToolbarProps> = ({
   color,
   strokeSize,
   canUndo,
+  canRedo = false,
   onToolChange,
   onColorChange,
   onStrokeSizeChange,
   onUndo,
+  onRedo,
   onClear,
   onSave,
 }) => {
@@ -192,6 +203,22 @@ export const Toolbar: React.FC<ToolbarProps> = ({
         <UndoIcon />
       </button>
 
+      {onRedo && (
+        <button
+          type="button"
+          onClick={onRedo}
+          disabled={!canRedo}
+          title="Redo (Cmd+Shift+Z)"
+          className={`p-1.5 rounded transition-colors ${
+            canRedo
+              ? 'hover:bg-muted text-muted-foreground hover:text-foreground'
+              : 'text-muted-foreground/30 cursor-not-allowed'
+          }`}
+        >
+          <RedoIcon />
+        </button>
+      )}
+
       {/* Clear all */}
       <button
         type="button"

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

@@ -11,6 +11,10 @@ import {
 } 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 };
@@ -135,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);
@@ -459,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;