@plannotator/ui 0.34.0 → 0.35.1

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`. |
@@ -674,11 +675,11 @@ Additive only, but required: `@plannotator/ui` 0.32.0 imports the new `@plannota
 
 ## Publishing & versioning
 
-- The current pair is `@plannotator/ui` `0.34.0` on `@plannotator/core` `0.25.0`. **No lockstep again**: nothing under `packages/core` changed since the 0.32.0 pair, so core is not republished and ui 0.34.0 pins the already published core 0.25.0 (only the ui tarball is built and published). 0.34.0 carries the 0.33.0 adoption feedback: the Mermaid KaTeX redirect target `utils/mermaid-math-slot`, `HtmlViewer` `bridgeErrorDisplay`, the anchored bridge-script alias, and `resetMathRenderer` keeping the registered loader (with `setMathRendererLoader(null)` and `getMathRendererLoader`). 0.33.0 carried the bridge-script asset (`bridge-script.asset.js`, `bridge-script.lite`, both generated by `prepack`), the `utils/math-default-loader` split, and `HANDOFF.md` inside the tarball so the README's section references resolve for a consumer.
-- Recent pairs, for the consumer's install matrix: ui 0.31.0 on core 0.24.0 (lockstep), ui 0.32.0 on core 0.25.0 (lockstep, `html-anchor`), ui 0.33.0 and ui 0.34.0 on core 0.25.0 (ui only, core unchanged).
-- When a pair IS lockstep, **publish `core` first**: ui 0.32.0 imports the new `@plannotator/core/html-anchor` subpath, which no earlier published core (0.24.0 and before) has, just as ui 0.29.0 needed core 0.23.0 for `@plannotator/core/annotatable`. The ui→core dependency resolves exactly at pack time, from the lockfile: after a version bump, run `bun install` so `bun.lock` carries the new workspace versions, or `bun pm pack` will still stamp the previous core version into ui's tarball (the 0.31.0 lesson).
+- The current pair is `@plannotator/ui` `0.35.1` on `@plannotator/core` `0.25.0`. **No lockstep again**: nothing under `packages/core` changed, so core is not republished. UI 0.35.1 is the packaging correction for 0.35.0: the source and packed UI manifests now pin core 0.25.0 exactly, so external pnpm consumers do not receive the unpublished `workspace:*` protocol. It otherwise carries the same `hideQuickLabel` toolstrip seam as 0.35.0.
+- Recent pairs, for the consumer's install matrix: ui 0.31.0 on core 0.24.0 (lockstep), ui 0.32.0 on core 0.25.0 (lockstep, `html-anchor`), and ui 0.33.0 through ui 0.35.1 on core 0.25.0 (ui only, core unchanged). Do not consume ui 0.35.0 externally; its published manifest contains `workspace:*`.
+- When both packages change, **publish `core` first**: ui 0.32.0 imports the `@plannotator/core/html-anchor` subpath, which no earlier published core (0.24.0 and before) has, just as ui 0.29.0 needed core 0.23.0 for `@plannotator/core/annotatable`. Bump core, update UI's exact core dependency to the same new version, and run `bun install` so `bun.lock` records the new workspace versions before packing either package.
 - The HTML annotation seams also changed the guides.show viewer **stylesheet** (five utility rules from `HtmlSurfaceControls`; the viewer JS is unchanged), so `packages/core/guide-viewer-manifest.ts` now pins a CSS hash that exists on guides.show only after the deploy workflow has published this build's `/v1/` assets. A guide exported from this build before that deploy would pin a stylesheet the host does not serve yet: **deploy guides.show before any release that ships this manifest.**
-- They depend on each other via `workspace:*`. At publish time that must resolve to the **exact** version in the tarball, so publish with a tool that does that resolution (the repo's existing flow uses `bun pm pack` to build the tarball, then `npm publish *.tgz --access public`). Publish **`core` first, then `ui`**.
+- UI declares the already published core version exactly in its source manifest. Do not replace it with `workspace:*`: direct publication can preserve that protocol and make the package impossible to install outside this repository. Bun links the local core workspace whenever its version matches the exact dependency. Before publishing, run `bun run --cwd packages/ui smoke:package`; it checks the source and packed manifests, required tarball subpaths, local Bun linking, and a real pnpm install in an external temporary consumer. When both packages change, publish **`core` first, then `ui`**.
 - **`--provenance` only works from a supported CI environment (GitHub Actions OIDC)** — a local publish fails with `Automatic provenance generation not supported for provider: null`. Until a CI publish job exists for these two packages, local publishes drop the flag. Publishing under `--tag next` first lets the consumer preflight before `npm dist-tag add <pkg>@<version> latest` promotes it.
 - `styles.css` is built by the `prepack` script (`bun run build:css`) so the published tarball always carries fresh precompiled CSS; since 0.33.0 `prepack` also runs `build:bridge-assets`, which generates the gitignored `bridge-script.asset.js` and `bridge-script.lite.ts` beside their source. Both are in `files`, so a tarball built without `prepack` (a hand-rolled `npm pack --ignore-scripts`) would ship export subpaths that resolve to nothing; always build with `bun pm pack`.
 - There is **no CI publish job for these two packages yet** — first publish is manual from `main` after merge. (Wiring a CI publish job is a follow-up.)

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"`.
@@ -162,9 +170,9 @@ npm install @plannotator/ui @plannotator/core
 ## Packages & publishing
 
 - `@plannotator/core` — pure utils + types, zero deps, browser-safe (CI enforces no `node:` imports). Published.
-- `@plannotator/ui` — React components/hooks + theme + `configure()`. Depends on `@plannotator/core` (exact-version lockstep). Published.
+- `@plannotator/ui` — React components/hooks + theme + `configure()`. Depends on an exact published `@plannotator/core` version. Published.
 - `@plannotator/shared`, `@plannotator/ai` — stay private to the monorepo; `shared` re-exports `core`'s modules via shims so Plannotator's internals are untouched.
-- Versioned together (currently `@plannotator/ui` 0.34.0 on `@plannotator/core` 0.25.0). `core` is bumped only when something under `packages/core` changed, so `ui` can advance alone: 0.33.0 and 0.34.0 are such releases, published on the already available core 0.25.0. When both change, publish `core` then `ui`: build each tarball with **`bun pm pack`** (resolves `workspace:*` to the exact version at pack time, from `bun.lock`, so run `bun install` after a bump), then **`npm publish *.tgz --provenance --access public`**, the repo's existing flow (`--provenance` needs CI OIDC; local publishes drop it, see HANDOFF.md "Publishing & versioning").
+- Currently `@plannotator/ui` 0.35.1 depends exactly on `@plannotator/core` 0.25.0. `core` is bumped only when something under `packages/core` changes, so `ui` can advance alone. Keep the published core version exact in `packages/ui/package.json`; do not use a `workspace:` protocol there, because a directly published manifest must remain installable outside this monorepo. Bun still links the matching local workspace during development. When both packages change, publish `core` first, then build and publish the UI tarball. See HANDOFF.md "Publishing & versioning" for the verification command.
 
 ## The one rule
 

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,
+  };
+}