@plannotator/ui 0.34.0 → 0.35.0

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/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 ?? [],
     };
   }, []);
 

package/hooks/useHtmlRefresh.ts

@@ -1,15 +1,22 @@
 import { useCallback, useLayoutEffect, useRef, useState } from 'react';
 
+/**
+ * A successful snapshot. `Extra` lets a host carry document metadata read
+ * alongside the bytes (Plannotator: the root document's version diff) through
+ * to `onSnapshot`; the hook never reads anything but `rawHtml`.
+ */
+export type HtmlRefreshOkSnapshot<Extra extends object = object> = { status: 'ok'; rawHtml: string } & Extra;
+
 /** What a host's `fetchSnapshot` resolves to. */
-export type HtmlRefreshSnapshot =
-  | { status: 'ok'; rawHtml: string }
+export type HtmlRefreshSnapshot<Extra extends object = object> =
+  | HtmlRefreshOkSnapshot<Extra>
   | { status: 'missing' }
   | { status: 'unavailable' };
 
 /** The outcome of one `refresh()` call, for host notifications (toasts). */
 export type HtmlRefreshResult = 'refreshed' | 'missing' | 'unavailable';
 
-export interface UseHtmlRefreshOptions {
+export interface UseHtmlRefreshOptions<Extra extends object = object> {
   /** Whether refresh is offered at all. Default true. */
   enabled?: boolean;
   /**
@@ -22,9 +29,11 @@ export interface UseHtmlRefreshOptions {
   documentKey?: string | null;
   /** Fetch the current bytes of the document. Called with `documentKey`.
    *  A rejection is treated as `{ status: 'unavailable' }`. */
-  fetchSnapshot: (documentKey: string | null) => Promise<HtmlRefreshSnapshot>;
-  /** Apply the refreshed bytes (the host owns the viewer's `rawHtml`). */
-  onSnapshot: (rawHtml: string) => void;
+  fetchSnapshot: (documentKey: string | null) => Promise<HtmlRefreshSnapshot<Extra>>;
+  /** Apply the refreshed bytes (the host owns the viewer's `rawHtml`). The
+   *  whole successful snapshot is the second argument, for hosts whose
+   *  `fetchSnapshot` reads metadata alongside the bytes. */
+  onSnapshot: (rawHtml: string, snapshot: HtmlRefreshOkSnapshot<Extra>) => void;
   /**
    * Once per refresh: the ids the remounted viewer could not re-anchor,
    * possibly empty. Wire the viewer's `onUnanchoredChange` to the returned
@@ -57,14 +66,14 @@ export interface UseHtmlRefreshReturn {
  * restore acknowledgement is armed per reload generation and consumed by
  * the first viewer report for that generation.
  */
-export function useHtmlRefresh({
+export function useHtmlRefresh<Extra extends object = object>({
   enabled = true,
   documentKey,
   fetchSnapshot,
   onSnapshot,
   onUnanchored,
   onResult,
-}: UseHtmlRefreshOptions): UseHtmlRefreshReturn {
+}: UseHtmlRefreshOptions<Extra>): UseHtmlRefreshReturn {
   const [isRefreshing, setIsRefreshing] = useState(false);
   const [reloadGeneration, setReloadGeneration] = useState(0);
   const keyed = documentKey !== undefined;
@@ -98,7 +107,7 @@ export function useHtmlRefresh({
       // A rejecting fetch is an unavailable snapshot: the host hears it
       // through onResult like any other outcome, never as an unhandled
       // rejection out of refresh().
-      let result: HtmlRefreshSnapshot;
+      let result: HtmlRefreshSnapshot<Extra>;
       try {
         result = await fetchSnapshot(requestKey);
       } catch {
@@ -111,7 +120,7 @@ export function useHtmlRefresh({
         return;
       }
 
-      onSnapshot(result.rawHtml);
+      onSnapshot(result.rawHtml, result);
       const nextGeneration = reloadGenerationRef.current + 1;
       reloadGenerationRef.current = nextGeneration;
       // Armed until the remounted viewer's bridge reports its restore. The

package/hooks/useSharing.ts

@@ -76,6 +76,12 @@ interface UseSharingResult {
   clearShareLoadError: () => void;
 }
 
+type ShortShareUrlLifecycle =
+  | { readonly _tag: 'none' }
+  | { readonly _tag: 'incoming-hydration' }
+  | { readonly _tag: 'generating'; readonly requestContext: object }
+  | { readonly _tag: 'associated'; readonly requestContext: object }
+  | { readonly _tag: 'failed'; readonly requestContext: object };
 
 // Share payloads are base64url-encoded deflate output: charset [A-Za-z0-9_-],
 // realistically >=30 chars, and virtually always mixed-case because deflate
@@ -133,6 +139,7 @@ export function useSharing(
   ]);
   const latestShareRequestContextRef = useRef(shareRequestContext);
   latestShareRequestContextRef.current = shareRequestContext;
+  const shortShareUrlLifecycleRef = useRef<ShortShareUrlLifecycle>({ _tag: 'none' });
 
   const clearPendingSharedAnnotations = useCallback(() => {
     setPendingSharedAnnotations(null);
@@ -148,6 +155,11 @@ export function useSharing(
       const pathMatch = window.location.pathname.match(/^\/p\/([A-Za-z0-9]{6,16})$/);
       if (pathMatch) {
         const pasteId = pathMatch[1];
+        // Capture before the async fetch. Concurrent loads (including the
+        // development Strict Mode replay) can complete after an earlier load
+        // removes /p/<id> from history; every completion must preserve the
+        // original short URL.
+        const incomingShortUrl = window.location.href;
 
         // Extract key and optional paste origin from fragment: #key=<k>&paste=<base64url>
         const fragment = window.location.hash.slice(1);
@@ -180,7 +192,8 @@ export function useSharing(
 
           setPendingSharedAnnotations(restoredAnnotations);
           setIsSharedSession(true);
-          setShortShareUrl(window.location.href);
+          shortShareUrlLifecycleRef.current = { _tag: 'incoming-hydration' };
+          setShortShareUrl(incomingShortUrl);
           onSharedLoad?.();
 
           // Remove the /p/<id> path from browser history so a refresh doesn't
@@ -294,17 +307,43 @@ export function useSharing(
     refreshShareUrl();
   }, [refreshShareUrl]);
 
-  // Clear stale short URL when content changes (does NOT auto-regenerate —
-  // the user must explicitly click "Create short link" again).
-  // Skip on shared session load — the incoming short URL must survive.
-  const isSharedRef = useRef(false);
+  // An incoming short URL becomes associated with the fully hydrated share
+  // context on its first committed render. From then on it follows the same
+  // lifecycle as a locally generated URL: any shareable-content change makes
+  // the immutable paste stale, so discard the URL without auto-uploading a
+  // replacement. Markdown users can still use the fresh hash URL; creating a
+  // new short link remains an explicit action.
   useEffect(() => {
-    if (isSharedSession) { isSharedRef.current = true; return; }
-    if (isSharedRef.current) { isSharedRef.current = false; return; }
+    const lifecycle = shortShareUrlLifecycleRef.current;
+    if (lifecycle._tag === 'incoming-hydration') {
+      if (!shortShareUrl) return;
+      // Hydration writes fresh annotation and attachment arrays, so this first
+      // committed request context represents the loaded snapshot. If those
+      // setters ever preserve identity, replace this consume-on-next-effect
+      // handoff with an explicit post-hydration signal.
+      shortShareUrlLifecycleRef.current = {
+        _tag: 'associated',
+        requestContext: shareRequestContext,
+      };
+      return;
+    }
+    if (
+      (
+        lifecycle._tag === 'generating'
+        || lifecycle._tag === 'associated'
+        || lifecycle._tag === 'failed'
+      )
+      && lifecycle.requestContext === shareRequestContext
+    ) {
+      return;
+    }
+    if (lifecycle._tag === 'none' && !shortShareUrl) return;
+
+    shortShareUrlLifecycleRef.current = { _tag: 'none' };
     setIsGeneratingShortUrl(false);
     setShortShareUrl('');
     setShortUrlError('');
-  }, [markdown, annotations, globalAttachments, rawHtml, isSharedSession, contentRevision]);
+  }, [shareRequestContext, shortShareUrl]);
 
   /**
    * Generate a short URL via the paste service.
@@ -318,6 +357,10 @@ export function useSharing(
     setIsGeneratingShortUrl(true);
     setShortUrlError('');
     const requestContext = shareRequestContext;
+    shortShareUrlLifecycleRef.current = {
+      _tag: 'generating',
+      requestContext,
+    };
 
     try {
       const htmlForShare = rawHtml
@@ -334,15 +377,21 @@ export function useSharing(
       if (latestShareRequestContextRef.current !== requestContext) return null;
 
       if (result) {
+        shortShareUrlLifecycleRef.current = {
+          _tag: 'associated',
+          requestContext,
+        };
         setShortShareUrl(result.shortUrl);
         return result.shortUrl;
       } else {
+        shortShareUrlLifecycleRef.current = { _tag: 'failed', requestContext };
         setShortShareUrl('');
         setShortUrlError('Short URL service unavailable');
         return null;
       }
     } catch (e) {
       if (latestShareRequestContextRef.current !== requestContext) return null;
+      shortShareUrlLifecycleRef.current = { _tag: 'failed', requestContext };
       setShortShareUrl('');
       setShortUrlError(e instanceof Error ? e.message : 'Failed to generate short URL');
       return null;

package/hooks/useUndoHistory.ts

@@ -0,0 +1,83 @@
+import { useRef } from 'react';
+import {
+  createUndoHistoryState,
+  recordUndoAction,
+  takeRedoAction,
+  takeUndoAction,
+  type HistoryDirection,
+  type UndoHistoryState,
+} from '../utils/undoHistory';
+
+/** Imperative bounded history API used by surface-specific command adapters. */
+export interface UndoHistoryApi<TAction> {
+  readonly canUndo: boolean;
+  readonly canRedo: boolean;
+  record: (action: TAction) => void;
+  undo: () => boolean;
+  redo: () => boolean;
+  clear: () => void;
+}
+
+interface UndoHistoryOptions<TAction> {
+  context: string;
+  apply: (action: TAction, direction: HistoryDirection) => void;
+  capacity?: number;
+}
+
+/**
+ * Keep one bounded stack for the active surface context while replaying
+ * actions through the latest adapter callbacks. A context change starts a
+ * fresh baseline synchronously, before any shortcut can reach the new view.
+ */
+export function useUndoHistory<TAction>({
+  context,
+  apply,
+  capacity = 50,
+}: UndoHistoryOptions<TAction>): UndoHistoryApi<TAction> {
+  const optionsRef = useRef({ apply, capacity });
+  optionsRef.current = { apply, capacity };
+  const historyRef = useRef<{
+    context: string;
+    state: UndoHistoryState<TAction>;
+  }>({ context, state: createUndoHistoryState<TAction>() });
+  if (historyRef.current.context !== context) {
+    historyRef.current = { context, state: createUndoHistoryState<TAction>() };
+  }
+  const apiRef = useRef<UndoHistoryApi<TAction> | null>(null);
+
+  if (!apiRef.current) {
+    apiRef.current = {
+      get canUndo() {
+        return historyRef.current.state.past.length > 0;
+      },
+      get canRedo() {
+        return historyRef.current.state.future.length > 0;
+      },
+      record(action) {
+        const history = historyRef.current;
+        history.state = recordUndoAction(history.state, action, optionsRef.current.capacity);
+      },
+      undo() {
+        const history = historyRef.current;
+        const step = takeUndoAction(history.state);
+        if (step.action === null) return false;
+        history.state = step.state;
+        optionsRef.current.apply(step.action, 'undo');
+        return true;
+      },
+      redo() {
+        const history = historyRef.current;
+        const step = takeRedoAction(history.state, optionsRef.current.capacity);
+        if (step.action === null) return false;
+        history.state = step.state;
+        optionsRef.current.apply(step.action, 'redo');
+        return true;
+      },
+      clear() {
+        historyRef.current.state = createUndoHistoryState<TAction>();
+      },
+    };
+  }
+
+  return apiRef.current;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@plannotator/ui",
-  "version": "0.34.0",
+  "version": "0.35.0",
   "type": "module",
   "exports": {
     "./components/*": "./components/*.tsx",
@@ -74,7 +74,7 @@
     "@lezer/highlight": "^1.2.3",
     "@pierre/diffs": "1.3.2",
     "@plannotator/atomic-editor": "^0.8.0",
-    "@plannotator/core": "0.25.0",
+    "@plannotator/core": "workspace:*",
     "@plannotator/markdown-editor": "^0.4.0",
     "@plannotator/web-highlighter": "^0.8.1",
     "@tanstack/react-table": "^8.21.3",

package/shortcuts/history.shortcuts.ts

@@ -0,0 +1,25 @@
+import { defineShortcutScope } from './core';
+import { createShortcutScopeHook } from './runtime';
+
+export const historyShortcuts = defineShortcutScope({
+  id: 'history',
+  title: 'History',
+  shortcuts: {
+    undo: {
+      description: 'Undo annotation change',
+      bindings: ['Mod+Z'],
+      section: 'History',
+      preventDefault: true,
+      displayOrder: 10,
+    },
+    redo: {
+      description: 'Redo annotation change',
+      bindings: ['Mod+Shift+Z', 'Mod+Y'],
+      section: 'History',
+      preventDefault: true,
+      displayOrder: 20,
+    },
+  },
+});
+
+export const useHistoryShortcuts = createShortcutScopeHook(historyShortcuts);

package/shortcuts/index.ts

@@ -1,5 +1,6 @@
 export * from './core';
 export * from './runtime';
+export { historyShortcuts, useHistoryShortcuts } from './history.shortcuts';
 
 // plan-review scopes
 export { annotationModeShortcuts, useAnnotationModeShortcuts } from './plan-review/annotationMode.shortcuts';

package/shortcuts/plan-review/imageAnnotator.shortcuts.ts

@@ -27,14 +27,23 @@ export const imageAnnotatorShortcuts = defineShortcutScope({
       description: 'Undo',
       bindings: ['Mod+Z'],
       section: 'Image Annotator',
+      preventDefault: true,
       displayOrder: 40,
     },
+    redo: {
+      description: 'Redo',
+      bindings: ['Mod+Shift+Z', 'Mod+Y'],
+      section: 'Image Annotator',
+      preventDefault: true,
+      displayOrder: 50,
+    },
     save: {
       description: 'Save and close annotator',
       bindings: ['Enter', 'Escape'],
       section: 'Image Annotator',
+      preventDefault: true,
       hint: 'When the image name field is focused, Escape blurs it first and Enter confirms the name; both close the annotator otherwise.',
-      displayOrder: 50,
+      displayOrder: 60,
     },
   },
 });