@plannotator/ui 0.53.0 → 0.54.0

package/hooks/useSharing.ts

@@ -9,7 +9,7 @@
  */
 
 import React, { useState, useEffect, useCallback, useMemo, useRef } from 'react';
-import { Annotation, type ImageAttachment } from '../types';
+import { Annotation, type DocumentRenderAs, type ImageAttachment } from '../types';
 import {
   type SharePayload,
   parseShareHash,
@@ -109,8 +109,10 @@ export function useSharing(
   resolveRawHtmlForShare?: () => Promise<string | null>,
   setRawHtml?: (h: string) => void,
   setShareHtml?: (h: string) => void,
-  setRenderAs?: (m: 'markdown' | 'html') => void,
+  setRenderAs?: (m: DocumentRenderAs) => void,
   contentRevision = 0,
+  /** Render kind of the shared document; `asciidoc` travels as `r: 'asciidoc'`. */
+  renderAs?: DocumentRenderAs,
 ): UseSharingResult {
   const [isSharedSession, setIsSharedSession] = useState(false);
   const [isLoadingShared, setIsLoadingShared] = useState(true);
@@ -136,6 +138,7 @@ export function useSharing(
     pasteApiUrl,
     rawHtml,
     contentRevision,
+    renderAs,
   ]);
   const latestShareRequestContextRef = useRef(shareRequestContext);
   latestShareRequestContextRef.current = shareRequestContext;
@@ -178,7 +181,7 @@ export function useSharing(
             setMarkdown('');
           } else {
             setMarkdown(payload.p);
-            setRenderAs?.('markdown');
+            setRenderAs?.(payload.r === 'asciidoc' ? 'asciidoc' : 'markdown');
             setRawHtml?.('');
             setShareHtml?.('');
           }
@@ -226,7 +229,7 @@ export function useSharing(
           setMarkdown('');
         } else {
           setMarkdown(payload.p);
-          setRenderAs?.('markdown');
+          setRenderAs?.(payload.r === 'asciidoc' ? 'asciidoc' : 'markdown');
           setRawHtml?.('');
           setShareHtml?.('');
         }
@@ -290,7 +293,7 @@ export function useSharing(
   const refreshShareUrl = useCallback(async () => {
     const requestContext = shareRequestContext;
     try {
-      const url = await generateShareUrl(markdown, annotations, globalAttachments, shareBaseUrl, rawHtml);
+      const url = await generateShareUrl(markdown, annotations, globalAttachments, shareBaseUrl, rawHtml, renderAs);
       if (latestShareRequestContextRef.current !== requestContext) return;
       setShareUrl(url ?? '');
       setShareUrlSize(url ? formatUrlSize(url) : '');
@@ -300,7 +303,7 @@ export function useSharing(
       setShareUrl('');
       setShareUrlSize('');
     }
-  }, [markdown, annotations, globalAttachments, shareBaseUrl, rawHtml, shareRequestContext]);
+  }, [markdown, annotations, globalAttachments, shareBaseUrl, rawHtml, renderAs, shareRequestContext]);
 
   // Auto-refresh share URL when dependencies change
   useEffect(() => {
@@ -372,6 +375,7 @@ export function useSharing(
         globalAttachments,
         { pasteApiUrl, shareBaseUrl },
         htmlForShare,
+        renderAs,
       );
 
       if (latestShareRequestContextRef.current !== requestContext) return null;
@@ -398,7 +402,7 @@ export function useSharing(
     } finally {
       if (latestShareRequestContextRef.current === requestContext) setIsGeneratingShortUrl(false);
     }
-  }, [markdown, annotations, globalAttachments, shareBaseUrl, pasteApiUrl, rawHtml, resolveRawHtmlForShare, shareRequestContext]);
+  }, [markdown, annotations, globalAttachments, shareBaseUrl, pasteApiUrl, rawHtml, resolveRawHtmlForShare, renderAs, shareRequestContext]);
 
   // Import annotations from a teammate's share URL (supports both hash-based and short /p/<id> URLs)
   const importFromShareUrl = useCallback(async (url: string): Promise<ImportResult> => {

package/hooks/useSkillReferenceAutocomplete.ts

@@ -59,14 +59,18 @@ export interface UseSkillReferenceAutocompleteResult {
  * active row and dismisses the menu when the user has engaged with it (a row
  * is active or a query was typed); on a bare-trigger menu with no engagement
  * it passes through, so Escape still closes the composer in one press.
+ * `bareEscapeDismisses` (default off) makes Escape close any open menu first,
+ * for a composer where Escape costs more than a press (the Inbox's compose
+ * dialog asks whether to keep a draft).
  */
 export function useSkillReferenceAutocomplete(options: {
   text: string;
   setText: (text: string) => void;
   textareaRef: React.RefObject<HTMLTextAreaElement | null>;
   enabled: boolean;
+  bareEscapeDismisses?: boolean;
 }): UseSkillReferenceAutocompleteResult {
-  const { text, setText, textareaRef, enabled } = options;
+  const { text, setText, textareaRef, enabled, bareEscapeDismisses = false } = options;
   // Seed from the memory cache only when the surface opted in — a disabled
   // composer must stay inert even after another surface warmed the catalog.
   const [catalog, setCatalog] = useState<SkillCatalogEntry[]>(() =>
@@ -205,7 +209,7 @@ export function useSkillReferenceAutocomplete(options: {
           // Only consume Escape when the user engaged with the menu (typed a
           // query or activated a row). A bare-trigger menu the user ignored
           // must not cost an extra Escape on the way to closing the composer.
-          if (boundedActive === null && trigger.query.length === 0) return false;
+          if (!bareEscapeDismisses && boundedActive === null && trigger.query.length === 0) return false;
           e.preventDefault();
           e.stopPropagation();
           setActiveIndex(null);
@@ -215,7 +219,7 @@ export function useSkillReferenceAutocomplete(options: {
           return false;
       }
     },
-    [boundedActive, items.length, open, select, trigger],
+    [bareEscapeDismisses, boundedActive, items.length, open, select, trigger],
   );
 
   const humanOnlyReferences = useMemo(

package/hooks/useThemePaletteHalves.ts

@@ -0,0 +1,37 @@
+import { useEffect, useState } from 'react';
+import { useTheme } from '../components/ThemeProvider';
+import { themesForHalf, type ThemeHalf, type ThemeInfo } from '../utils/themeRegistry';
+
+export interface ThemePaletteHalves {
+  /** Which half the picker assigns to. */
+  half: ThemeHalf;
+  setHalf: (half: ThemeHalf) => void;
+  /** The palette each half holds now. */
+  pair: Record<ThemeHalf, string>;
+  /** The palettes the current half can take, from the registry (so a new palette shows by itself). */
+  themes: ThemeInfo[];
+  nameOf: (id: string) => string;
+  /** Assign a palette to a half (ThemeProvider's setHalfTheme). */
+  choose: (half: ThemeHalf, id: string) => void;
+}
+
+/**
+ * The palette picker's state, without its layout: the half being assigned
+ * (it follows the mode on screen, so opening Settings in dark mode edits the
+ * dark half first), the pair, and the palettes that half can take. ThemeTab
+ * draws it for plan review, annotate and code review; the Inbox draws the
+ * same choices in its own Settings rows.
+ */
+export function useThemePaletteHalves(): ThemePaletteHalves {
+  const { lightTheme, darkTheme, setHalfTheme, availableThemes, preferredMode } = useTheme();
+  const [half, setHalf] = useState<ThemeHalf>(preferredMode);
+  useEffect(() => setHalf(preferredMode), [preferredMode]);
+  return {
+    half,
+    setHalf,
+    pair: { light: lightTheme, dark: darkTheme },
+    themes: themesForHalf(availableThemes, half),
+    nameOf: (id: string) => availableThemes.find(theme => theme.id === id)?.name ?? id,
+    choose: setHalfTheme,
+  };
+}

package/hooks/useUpdateCheck.ts

@@ -1,6 +1,6 @@
 import { useState, useCallback, useMemo } from 'react';
 import { getItem, setItem } from '../utils/storage';
-import type { UpdateAction, UpdateAdvert } from '../utils/updateNotice';
+import type { UpdateAction, UpdateAdvert, UpdateCheckFailingAdvert } from '../utils/updateNotice';
 
 declare const __APP_VERSION__: string;
 
@@ -21,6 +21,11 @@ export interface UpdateInfo {
   action?: UpdateAction;
   /** The command for this host, with the remembered install flags. */
   command?: string;
+  /**
+   * Checking for updates has failed for hours (no update known): the Options
+   * menu says so with `command`. `updateAvailable` is false then.
+   */
+  checkFailing?: { since: string; error: string };
   dismiss: () => void;
 }
 
@@ -35,13 +40,13 @@ function isDismissedVersion(latestVersion: string): boolean {
 /**
  * The Options menu's update state, from the server's advert (`updateAvailable`
  * on /api/plan and /api/diff). The browser never asks GitHub: the machine
- * checks once a day (packages/shared/update-check.ts) and the server passes
+ * checks every few minutes (packages/shared/update-check.ts) and the server passes
  * the answer on, or nothing when update checks are off, in a dev build, or on
  * a surface with no server.
  *
  * `?preview-update=0.29.0` still simulates an update, for screenshots.
  */
-export function useUpdateCheck(advert?: UpdateAdvert | null): UpdateInfo | null {
+export function useUpdateCheck(advert?: UpdateAdvert | null, failing?: UpdateCheckFailingAdvert | null): UpdateInfo | null {
   const preview = useMemo(() => {
     if (typeof window === 'undefined') return null;
     const version = new URLSearchParams(window.location.search).get('preview-update');
@@ -56,7 +61,20 @@ export function useUpdateCheck(advert?: UpdateAdvert | null): UpdateInfo | null
     setDismissedVersion(latestVersion);
   }, [latestVersion]);
 
-  if (!latestVersion) return null;
+  if (!latestVersion) {
+    if (!failing) return null;
+    const current = typeof __APP_VERSION__ !== 'undefined' ? __APP_VERSION__ : '0.0.0';
+    return {
+      currentVersion: current,
+      latestVersion: current,
+      updateAvailable: false,
+      dismissed: true,
+      releaseUrl: 'https://github.com/backnotprop/plannotator/releases',
+      command: failing.command,
+      checkFailing: { since: failing.since, error: failing.error },
+      dismiss,
+    };
+  }
   const currentVersion = advert?.current ?? (typeof __APP_VERSION__ !== 'undefined' ? __APP_VERSION__ : '0.0.0');
   return {
     currentVersion,

package/hooks/useUpdateToast.ts

@@ -21,7 +21,7 @@ function isTypingSomewhere(): boolean {
 
 /**
  * The review windows' "a new version is out" toast (design §4.5): from the
- * server's advert only, at most once per version and once every three days
+ * server's advert only, at most once per version and once a day
  * (claimUpdateToast), queued behind the first-run dialogs (`blocked`) and
  * never while a composer or dialog has focus. A blocked attempt is not
  * consumed: it looks again, and gives up for this load after two minutes.

package/hooks/useVimSelection.ts

@@ -317,8 +317,16 @@ export function useVimSelection({
     return next;
   }, [containerRef, setState]);
 
+  // Whether vim was on since the last reset. The disabled branch below resets
+  // only when vim actually goes from on to off: on a mount where vim was never
+  // on there is nothing to reset, and `window.getSelection()` in
+  // `clearSelectionWithin` forces a layout on every document open.
+  const wasEnabledRef = useRef(enabled);
+
   useEffect(() => {
     if (!enabled) {
+      if (!wasEnabledRef.current) return;
+      wasEnabledRef.current = false;
       setState(createInitialVimSelectionState());
       setFocused(false);
       setHelpOpen(false);
@@ -326,6 +334,7 @@ export function useVimSelection({
       clearSelectionWithin(containerRef.current);
       return;
     }
+    wasEnabledRef.current = true;
     if (!focused) return;
     if (restoringFocusRef.current) {
       restoringFocusRef.current = false;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@plannotator/ui",
-  "version": "0.53.0",
+  "version": "0.54.0",
   "license": "Apache-2.0",
   "type": "module",
   "exports": {
@@ -12,6 +12,7 @@
     "./components/ImageAnnotator": "./components/ImageAnnotator/index.tsx",
     "./components/html-viewer": "./components/html-viewer/index.ts",
     "./components/diagram": "./components/diagram/index.ts",
+    "./components/diagramLanguages": "./components/diagramLanguages.ts",
     "./components/diagram/*": "./components/diagram/*.tsx",
     "./components/html-viewer/bridge-script": "./components/html-viewer/bridge-script.ts",
     "./components/html-viewer/bridge-script.asset.js": "./components/html-viewer/bridge-script.asset.js",
@@ -57,42 +58,42 @@
     "!test-setup"
   ],
   "dependencies": {
-    "@base-ui/react": "^1.7.0",
+    "@base-ui/react": "^1.9.0",
     "@codemirror/autocomplete": "^6.20.3",
-    "@codemirror/commands": "^6.11.0",
+    "@codemirror/commands": "^6.11.1",
     "@codemirror/lang-javascript": "^6.2.5",
     "@codemirror/lang-json": "^6.0.2",
     "@codemirror/lang-markdown": "^6.5.2",
     "@codemirror/lang-python": "^6.2.1",
     "@codemirror/lang-yaml": "^6.1.3",
-    "@codemirror/language": "^6.12.4",
-    "@codemirror/legacy-modes": "^6.5.3",
+    "@codemirror/language": "^6.13.1",
+    "@codemirror/legacy-modes": "^6.5.5",
     "@codemirror/merge": "^6.12.2",
     "@codemirror/search": "^6.7.2",
-    "@codemirror/state": "^6.7.2",
-    "@codemirror/view": "^6.43.10",
+    "@codemirror/state": "^6.7.6",
+    "@codemirror/view": "^6.43.14",
     "@fontsource-variable/geist-mono": "5.3.0",
     "@fontsource-variable/inter": "^5.3.0",
-    "@lezer/common": "^1.5.2",
-    "@lezer/highlight": "^1.2.3",
-    "@pierre/diffs": "1.3.6",
+    "@lezer/common": "^1.5.3",
+    "@lezer/highlight": "^1.2.5",
+    "@pierre/diffs": "1.5.2",
     "@plannotator/atomic-editor": "^0.9.0",
-    "@plannotator/core": "0.25.13",
+    "@plannotator/core": "0.25.14",
     "@plannotator/markdown-editor": "^0.5.0",
     "@plannotator/web-highlighter": "^0.8.1",
     "@tanstack/react-table": "^8.21.3",
-    "@viz-js/viz": "3.30.0",
+    "@viz-js/viz": "3.31.0",
     "class-variance-authority": "^0.7.1",
     "clsx": "^2.1.1",
     "diff": "^8.0.4",
-    "dompurify": "^3.4.14",
-    "katex": "^0.16.47",
-    "lucide-react": "^1.38.0",
+    "dompurify": "^3.4.17",
+    "katex": "^0.18.11",
+    "lucide-react": "^1.59.0",
     "marked": "^17.0.6",
-    "mermaid": "12.0.0",
-    "motion": "^12.38.0",
+    "mermaid": "12.2.0",
+    "motion": "^14.4.0",
     "perfect-freehand": "^1.2.2",
-    "tailwind-merge": "^3.6.0",
+    "tailwind-merge": "^3.7.0",
     "unique-username-generator": "^1.5.1"
   },
   "peerDependencies": {
@@ -104,10 +105,10 @@
     "@happy-dom/global-registrator": "^20.12.0",
     "@tailwindcss/vite": "^4.3.3",
     "@types/bun": "^1.2.0",
-    "@types/react": "^19.2.18",
-    "@types/react-dom": "^19.2.5",
-    "react": "^19.2.8",
-    "react-dom": "^19.2.8",
+    "@types/react": "^19.3.0",
+    "@types/react-dom": "^19.3.0",
+    "react": "^19.3.1",
+    "react-dom": "^19.3.1",
     "tailwindcss": "^4.1.18",
     "typescript": "~5.8.2",
     "vite": "^6.2.0"

package/shortcuts/code-review/annotationToolbar.shortcuts.ts

@@ -8,6 +8,7 @@ export const reviewAnnotationToolbarShortcuts = defineShortcutScope({
     submitComment: {
       description: 'Submit comment',
       bindings: ['Mod+Enter'],
+      hint: 'With Settings → General → “Enter saves a comment” on, Enter saves too and Shift+Enter adds a new line.',
       section: 'Annotations',
       displayOrder: 10,
     },

package/shortcuts/code-review/explorer.shortcuts.ts

@@ -0,0 +1,82 @@
+import { defineShortcutScope } from '../core';
+import { createShortcutScopeHook } from '../runtime';
+
+/**
+ * Moving around the repository in code review (approved design record
+ * "review-explorer", step 3). VS Code's own default keys per system, so a
+ * reviewer's hands already know them. None of them takes a key code review
+ * used before; ⌘P / Ctrl+P is the browser's Print, replaced here in code
+ * review only.
+ */
+export const reviewExplorerShortcuts = defineShortcutScope({
+  id: 'review-explorer',
+  title: 'Go to',
+  shortcuts: {
+    goToFile: {
+      description: 'Go to File',
+      bindings: ['Mod+P'],
+      section: 'Go to',
+      hint: 'Fuzzy search over every file of the repository at the revision the diff reads. Changed files are marked and win ties; with nothing typed, the files you opened last.',
+      preventDefault: true,
+      displayOrder: 10,
+    },
+    goToDefinition: {
+      description: 'Go to Definition',
+      bindings: ['F12', 'Mod+F12'],
+      section: 'Go to',
+      hint: 'The symbol under the pointer (or the last one you clicked). One clear definition opens its file at the line; several open the references panel. Mod+F12 is for browsers that keep F12 for their developer tools. Needs the local checkout.',
+      preventDefault: true,
+      displayOrder: 20,
+    },
+    goToReferences: {
+      description: 'Go to References',
+      bindings: ['Shift+F12'],
+      section: 'Go to',
+      hint: 'Opens the references panel for the symbol under the pointer. A result opens its file at the line.',
+      preventDefault: true,
+      displayOrder: 30,
+    },
+    navigateBack: {
+      description: 'Go back',
+      bindings: ['Ctrl+-'],
+      platformBindings: {
+        mac: ['Ctrl+-'],
+        windows: ['Alt+ArrowLeft'],
+        linux: ['Ctrl+Alt+-'],
+      },
+      section: 'Go to',
+      hint: 'Back to where the last jump (Go to File, Go to Definition, a reference) started. Stays inside the review.',
+      preventDefault: true,
+      displayOrder: 40,
+    },
+    navigateForward: {
+      description: 'Go forward',
+      bindings: ['Ctrl+Shift+-'],
+      platformBindings: {
+        mac: ['Ctrl+Shift+-'],
+        windows: ['Alt+ArrowRight'],
+        linux: ['Ctrl+Shift+-'],
+      },
+      section: 'Go to',
+      displayOrder: 50,
+      preventDefault: true,
+    },
+    nextChange: {
+      description: 'Next change',
+      bindings: ['Alt+F5'],
+      section: 'Go to',
+      hint: 'The next run of changed lines in the open file; past the last one, the next file with changes.',
+      preventDefault: true,
+      displayOrder: 60,
+    },
+    previousChange: {
+      description: 'Previous change',
+      bindings: ['Shift+Alt+F5'],
+      section: 'Go to',
+      preventDefault: true,
+      displayOrder: 70,
+    },
+  },
+});
+
+export const useReviewExplorerShortcuts = createShortcutScopeHook(reviewExplorerShortcuts);

package/shortcuts/core.ts

@@ -1,11 +1,21 @@
-import { isMac } from '../utils/platform';
+import { isMac, isWindows } from '../utils/platform';
 
 export type ShortcutPlatform = 'mac' | 'non-mac' | 'cross-platform';
 
+/** The three desktop systems a binding can differ on (VS Code's split). */
+export type ShortcutOS = 'mac' | 'windows' | 'linux';
+
 export interface ShortcutDefinition {
   description: string;
   /** Alternative bindings for the same action, shown as “or” in the shortcuts UI. */
   bindings: string[];
+  /**
+   * Per-system bindings that replace `bindings` on that system (VS Code's
+   * defaults differ by OS, e.g. Back is ⌃- on macOS, Alt+← on Windows and
+   * Ctrl+Alt+- on Linux). `bindings` stays the fallback and what tools that
+   * know nothing of systems read.
+   */
+  platformBindings?: Partial<Record<ShortcutOS, string[]>>;
   section: string;
   hint?: string;
   preventDefault?: boolean;
@@ -41,6 +51,9 @@ export interface ShortcutSurface {
 
 const NAMED_TOKENS = new Set([
   'Mod',
+  // The physical Control key on every system (⌃ on macOS), unlike `Mod`,
+  // which is ⌘ on macOS. For VS Code's macOS bindings such as ⌃-.
+  'Ctrl',
   'Shift',
   'Alt',
   'Enter',
@@ -69,13 +82,15 @@ const NAMED_TOKENS = new Set([
   '}',
   '?',
   '$',
+  // Matched by its key code, so Shift (which turns it into `_`) still reads as it.
+  '-',
 ]);
 
 for (let n = 1; n <= 12; n += 1) {
   NAMED_TOKENS.add(`F${n}`);
 }
 
-const MODIFIER_TOKENS = new Set(['Mod', 'Shift', 'Alt']);
+const MODIFIER_TOKENS = new Set(['Mod', 'Ctrl', 'Shift', 'Alt']);
 const SHIFTED_LITERAL_TOKENS = new Set(['{', '}', '?', '$']);
 type ShortcutKeyEvent = Pick<
   KeyboardEvent,
@@ -184,7 +199,11 @@ export function validateShortcutRegistry(registry: ShortcutRegistry): string[] {
         errors.push(`Shortcut ${id} must define at least one binding.`);
       }
 
-      for (const binding of shortcut.bindings) {
+      const allBindings = [
+        ...shortcut.bindings,
+        ...Object.values(shortcut.platformBindings ?? {}).flat(),
+      ];
+      for (const binding of allBindings) {
         if (!binding.trim()) {
           errors.push(`Shortcut ${id} contains an empty binding.`);
           continue;
@@ -264,9 +283,36 @@ export function getShortcutPlatform(): Exclude<ShortcutPlatform, 'cross-platform
   return isMac ? 'mac' : 'non-mac';
 }
 
+export function getShortcutOS(): ShortcutOS {
+  return isMac ? 'mac' : isWindows ? 'windows' : 'linux';
+}
+
+/** The bindings that apply on a system: its own when it has some, else `bindings`. */
+export function resolveShortcutBindings(
+  shortcut: Pick<ShortcutDefinition, 'bindings' | 'platformBindings'>,
+  os: ShortcutOS = getShortcutOS(),
+): string[] {
+  return shortcut.platformBindings?.[os] ?? shortcut.bindings;
+}
+
+const OS_LABELS: Record<ShortcutOS, string> = { mac: 'macOS', windows: 'Windows', linux: 'Linux' };
+
+/**
+ * A shortcut's bindings as text for a reference that serves every system (the
+ * docs): `Cmd+P or Ctrl+P` style text, or one entry per system when they
+ * differ ("Ctrl+- (macOS) · Alt+ArrowLeft (Windows) · Ctrl+Alt+- (Linux)").
+ */
+export function formatShortcutDefinitionText(shortcut: Pick<ShortcutDefinition, 'bindings' | 'platformBindings'>): string {
+  if (!shortcut.platformBindings) return formatShortcutBindingsText(shortcut.bindings);
+  return (['mac', 'windows', 'linux'] as const)
+    .map((os) => `${formatShortcutBindingsText(resolveShortcutBindings(shortcut, os), os === 'mac' ? 'mac' : 'non-mac')} (${OS_LABELS[os]})`)
+    .join(' · ');
+}
+
 function formatKeycapToken(token: string, platform: Exclude<ShortcutPlatform, 'cross-platform'>): string {
   if (platform === 'mac') {
     if (token === 'Mod') return '⌘';
+    if (token === 'Ctrl') return '⌃';
     if (token === 'Alt') return '⌥';
     if (token === 'Shift') return '⇧';
     if (token === 'Enter') return '⏎';
@@ -293,6 +339,7 @@ function formatTextToken(token: string, platform: ShortcutPlatform): string {
     return platform === 'mac' ? 'Option' : 'Alt';
   }
 
+  if (token === 'Ctrl') return 'Ctrl';
   if (token === 'Escape') return 'Escape';
   if (token === 'hold') return 'hold';
   return token;
@@ -359,6 +406,10 @@ function matchesKeyToken(event: ShortcutKeyEvent, token: string): boolean {
     return event.key === ' ' || event.key === 'Spacebar' || event.code === 'Space';
   }
 
+  if (token === '-') {
+    return event.code === 'Minus' || event.key === '-' || event.key === '_';
+  }
+
   if (token === 'A-Z') {
     return /^[A-Z]$/.test(key);
   }
@@ -393,6 +444,7 @@ export function matchesShortcutBinding(event: ShortcutKeyEvent, binding: string)
   if (tokens.length === 0) return false;
 
   const requiresMod = tokens.includes('Mod');
+  const requiresCtrl = tokens.includes('Ctrl');
   const requiresShift = tokens.includes('Shift');
   const requiresAlt = tokens.includes('Alt');
   const keyTokens = tokens.filter(token => !MODIFIER_TOKENS.has(token));
@@ -403,7 +455,14 @@ export function matchesShortcutBinding(event: ShortcutKeyEvent, binding: string)
     || (!requiresShift && keyToken === 'A-Z' && event.shiftKey)
     || (!requiresShift && SHIFTED_LITERAL_TOKENS.has(keyToken) && event.key === keyToken);
 
-  if (requiresMod !== (event.metaKey || event.ctrlKey)) return false;
+  // `Mod` is ⌘ or Ctrl (as before); `Ctrl` is the physical Control key only.
+  if (requiresMod) {
+    if (!(event.metaKey || event.ctrlKey)) return false;
+  } else if (requiresCtrl) {
+    if (!event.ctrlKey || event.metaKey) return false;
+  } else if (event.metaKey || event.ctrlKey) {
+    return false;
+  }
   if (!shiftMatches) return false;
   if (requiresAlt !== event.altKey) return false;
 

package/shortcuts/index.ts

@@ -35,3 +35,4 @@ export { reviewAiShortcuts, useReviewAiShortcuts } from './code-review/ai.shortc
 export { reviewSuggestionModalShortcuts, useReviewSuggestionModalShortcuts } from './code-review/suggestionModal.shortcuts';
 export { reviewTourDialogShortcuts, useReviewTourDialogShortcuts } from './code-review/tourDialog.shortcuts';
 export { reviewMarkdownPreviewShortcuts, useReviewMarkdownPreviewShortcuts } from './code-review/markdownPreview.shortcuts';
+export { reviewExplorerShortcuts, useReviewExplorerShortcuts } from './code-review/explorer.shortcuts';

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

@@ -9,7 +9,7 @@ export const annotationPanelShortcuts = defineShortcutScope({
       description: 'Save annotation edit',
       bindings: ['Mod+Enter'],
       section: 'Annotations',
-      hint: 'Available while editing an annotation in the side panel.',
+      hint: 'Available while editing an annotation in the side panel. With Settings → General → “Enter saves a comment” on, Enter saves too.',
       displayOrder: 50,
     },
     cancelEdit: {

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

@@ -7,6 +7,7 @@ export const commentPopoverShortcuts = defineShortcutScope({
     submit: {
       description: 'Submit comment',
       bindings: ['Mod+Enter'],
+      hint: 'With Settings → General → “Enter saves a comment” on, Enter saves too and Shift+Enter adds a new line.',
       section: 'Annotations',
       displayOrder: 30,
     },