@plannotator/ui 0.37.0 → 0.38.0

package/components/Settings.tsx

@@ -3,6 +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 type { TokenHoverDelay } from '@plannotator/core/token-hover';
 import { configStore, useConfigValue, setReviewPanelView, setReviewDefaultDiffType, setReviewAutoViewed } from '../config';
 import { setWebMcpToolsEnabled, useWebMcpToolsEnabled } from '../webmcp/preference';
 import { loadDiffFont } from '../utils/diffFonts';
@@ -64,7 +65,7 @@ import { useAgents } from '../hooks/useAgents';
 import { KeyboardShortcuts } from './KeyboardShortcuts';
 import { type QuickLabel, getQuickLabels, saveQuickLabels, resetQuickLabels, DEFAULT_QUICK_LABELS, getLabelColors, LABEL_COLOR_MAP } from '../utils/quickLabels';
 import { ThemeTab } from './ThemeTab';
-import { isMac, modKey, altKey } from '../utils/platform';
+import { isMac, modKey, modKeyWord, altKey } from '../utils/platform';
 import { getAIProviderSettings, resolveAIProviderSelection } from '../utils/aiProvider';
 import { AISettingsTab } from './AISettingsTab';
 import { HooksTab } from './settings/HooksTab';
@@ -133,6 +134,23 @@ export const DIFF_STYLE_OPTIONS = [
   { value: 'split' as const, label: 'Split' },
   { value: 'unified' as const, label: 'Unified' },
 ];
+/**
+ * The modifier gate is the platform's primary modifier: Cmd on macOS, Ctrl on
+ * Windows and Linux. Labeled through modKeyWord so the control names the key
+ * the reader actually has.
+ */
+export const TOKEN_HOVER_TRIGGER_OPTIONS = [
+  { value: 'hover' as const, label: 'On hover' },
+  { value: 'modifier' as const, label: `Hold ${modKeyWord}` },
+  { value: 'off' as const, label: 'Off' },
+];
+/** SegmentedControl keys on strings, so the ms values ride as their digits. */
+export type TokenHoverDelayOption = '150' | '300' | '700';
+export const TOKEN_HOVER_DELAY_OPTIONS = [
+  { value: '150' as const, label: 'Fast' },
+  { value: '300' as const, label: 'Default' },
+  { value: '700' as const, label: 'Relaxed' },
+];
 export const OVERFLOW_OPTIONS = [
   { value: 'scroll' as const, label: 'Scroll' },
   { value: 'wrap' as const, label: 'Wrap' },
@@ -157,6 +175,7 @@ const DEFAULT_DIFF_TYPE_OPTIONS = [
   // "All Changes" belongs to since-base (the flagship composite); uncommitted
   // reverts to its plain name so the two stay distinguishable side by side.
   { value: 'since-base' as const, label: 'All Changes (Recommended)', description: "Everything since your branch split from main — committed, uncommitted, and untracked" },
+  { value: 'local-vs-remote' as const, label: 'Local vs Remote Branch', description: "Your local branch and working tree compared with its last-fetched remote-tracking branch" },
   { value: 'uncommitted' as const, label: 'Uncommitted', description: "Everything you've changed since your last commit" },
   { value: 'unstaged' as const, label: 'Unstaged', description: "Only changes you haven't staged yet" },
   { value: 'staged' as const, label: 'Staged', description: "Only changes you've staged for commit" },
@@ -170,22 +189,27 @@ const AGENT_TERMINAL_SIDE_OPTIONS: { value: AnnotateAgentTerminalSide; label: st
   { value: 'hidden', label: 'Hidden' },
 ];
 
-function SegmentedControl<T extends string>({ options, value, onChange }: {
+function SegmentedControl<T extends string>({ options, value, onChange, disabled = false }: {
   options: { value: T; label: string }[];
   value: T;
   onChange: (v: T) => void;
+  /** Visible but inert, for a control whose axis does not apply right now. */
+  disabled?: boolean;
 }) {
   return (
-    <div className="flex items-center gap-1 bg-muted/50 rounded-lg p-0.5">
+    <div className={['flex items-center gap-1 bg-muted/50 rounded-lg p-0.5', disabled && 'opacity-50'].filter(Boolean).join(' ')}>
       {options.map((opt) => (
         <button
           key={opt.value}
+          {...(disabled ? { disabled: true } : {})}
           onClick={() => onChange(opt.value)}
-          className={`flex-1 px-3 py-1.5 text-xs rounded-md transition-colors ${
+          className={[
+            'flex-1 px-3 py-1.5 text-xs rounded-md transition-colors',
+            disabled && 'cursor-not-allowed',
             value === opt.value
               ? 'bg-background text-foreground shadow-sm font-medium'
-              : 'text-muted-foreground hover:text-foreground'
-          }`}
+              : 'text-muted-foreground hover:text-foreground',
+          ].filter(Boolean).join(' ')}
         >
           {opt.label}
         </button>
@@ -470,6 +494,8 @@ const ReviewDisplayTab: React.FC<{ isCompactTouchLayout?: boolean }> = ({ isComp
   const diffExpandUnchanged = useConfigValue('diffExpandUnchanged');
   const diffFontFamily = useConfigValue('diffFontFamily');
   const diffFontSize = useConfigValue('diffFontSize');
+  const tokenHoverTrigger = useConfigValue('tokenHoverTrigger');
+  const tokenHoverDelay = useConfigValue('tokenHoverDelay');
 
   // Load font for the preview swatch
   useEffect(() => {
@@ -493,6 +519,41 @@ const ReviewDisplayTab: React.FC<{ isCompactTouchLayout?: boolean }> = ({ isComp
 
       <div className="border-t border-border" />
 
+      {/* Hover cards (internally tokenHover*; the label is what changed, not
+          the ids). One trigger select rather than a toggle plus a mode: `Off`
+          is a value of the same question, so there is no unreachable
+          enabled-but-off state to reason about. The delay stays a separate
+          axis because "too eager" is a complaint neither the hold-modifier option
+          nor Off answers. */}
+      <div className="space-y-3">
+        <div>
+          <div className="text-sm font-medium">Hover cards</div>
+          <div className="text-xs text-muted-foreground">
+            Rest the pointer on a symbol in a diff to see where it is defined and who
+            references it. Needs ripgrep and a local checkout; nothing appears when the
+            search comes back empty. {modKeyWord}+click still opens the References panel either way.
+          </div>
+        </div>
+        <SegmentedControl
+          options={TOKEN_HOVER_TRIGGER_OPTIONS}
+          value={tokenHoverTrigger}
+          onChange={(v) => configStore.set('tokenHoverTrigger', v)}
+        />
+        <div className="space-y-2">
+          <div className="text-xs text-muted-foreground">
+            How long the pointer rests before a card is requested
+          </div>
+          <SegmentedControl
+            options={TOKEN_HOVER_DELAY_OPTIONS}
+            value={String(tokenHoverDelay) as TokenHoverDelayOption}
+            onChange={(v) => configStore.set('tokenHoverDelay', Number(v) as TokenHoverDelay)}
+            disabled={tokenHoverTrigger === 'off'}
+          />
+        </div>
+      </div>
+
+      <div className="border-t border-border" />
+
       {/* Font Family */}
       <div className="space-y-2">
         <div>

package/components/ToolbarButtons.tsx

@@ -14,7 +14,6 @@ interface FeedbackButtonProps {
   loadingLabel?: string;
   shortLoadingLabel?: string;
   title?: string;
-  muted?: boolean;
   labelBreakpoint?: ToolbarLabelBreakpoint;
 }
 
@@ -27,7 +26,6 @@ export const FeedbackButton: React.FC<FeedbackButtonProps> = ({
   loadingLabel = 'Sending...',
   shortLoadingLabel,
   title = 'Send Feedback',
-  muted = false,
   labelBreakpoint = 'md',
 }) => (
   <Button
@@ -37,7 +35,6 @@ export const FeedbackButton: React.FC<FeedbackButtonProps> = ({
     disabled={disabled}
     title={title}
     iconLeft={<Send className="size-3.5" />}
-    className={cn(muted && 'opacity-50 cursor-not-allowed')}
   >
     {shortLabel ? (
       <>
@@ -65,8 +62,10 @@ export interface ApproveButtonProps {
   mobileLabel?: string;
   mobileLoadingLabel?: string;
   title?: string;
+  /** Kept for plan mode (packages/editor AppHeader) — the softened "you have
+   *  annotations" treatment. The old platform-mode `muted` prop died with
+   *  PR6 (DecisionControl owns the self-approval mute now). */
   dimmed?: boolean;
-  muted?: boolean;
   labelBreakpoint?: ToolbarLabelBreakpoint;
 }
 
@@ -80,7 +79,6 @@ export const ApproveButton: React.FC<ApproveButtonProps> = ({
   mobileLoadingLabel = '...',
   title,
   dimmed = false,
-  muted = false,
   labelBreakpoint = 'md',
 }) => (
   <Button
@@ -91,9 +89,8 @@ export const ApproveButton: React.FC<ApproveButtonProps> = ({
     title={title}
     iconLeft={<Check className="size-3.5" />}
     className={cn(
-      muted && 'opacity-40 cursor-not-allowed bg-muted text-muted-foreground hover:bg-muted',
-      disabled && !muted && 'bg-muted text-muted-foreground hover:bg-muted',
-      dimmed && !muted && !disabled && 'bg-success/50 text-success-foreground/70 hover:bg-success hover:text-success-foreground',
+      disabled && 'bg-muted text-muted-foreground hover:bg-muted',
+      dimmed && !disabled && 'bg-success/50 text-success-foreground/70 hover:bg-success hover:text-success-foreground',
     )}
   >
     <span className={labelBreakpoint === 'lg' ? 'lg:hidden' : 'md:hidden'}>
@@ -111,6 +108,10 @@ interface ExitButtonProps {
   isLoading?: boolean;
   title?: string;
   labelBreakpoint?: ToolbarLabelBreakpoint;
+  /** `'ghost'` renders the icon-only ghost-X form that sits beside the
+   *  decision control. Default `'pill'` keeps every existing caller
+   *  byte-identical. */
+  appearance?: 'pill' | 'ghost';
 }
 
 export const ExitButton: React.FC<ExitButtonProps> = ({
@@ -119,7 +120,28 @@ export const ExitButton: React.FC<ExitButtonProps> = ({
   isLoading = false,
   title = 'Close session without sending feedback',
   labelBreakpoint = 'md',
-}) => (
+  appearance = 'pill',
+}) => appearance === 'ghost' ? (
+  <Button
+    variant="ghost"
+    size="xs"
+    onClick={onClick}
+    disabled={disabled || isLoading}
+    title={title}
+    aria-label={title}
+    // Maintainer ruling (post-demo): a bare X carries "close without
+    // sending" semantics an unlabeled icon should not carry alone — the
+    // word renders at every breakpoint.
+    className="px-2 text-muted-foreground gap-1.5"
+  >
+    {isLoading ? '…' : (
+      <>
+        <X className="size-3.5" aria-hidden="true" />
+        <span>Close</span>
+      </>
+    )}
+  </Button>
+) : (
   <Button
     variant="secondary"
     size="xs"

package/components/Viewer.tsx

@@ -1,3 +1,4 @@
+import { generateId } from '../utils/generateId';
 import React, { useRef, useState, useEffect, useMemo, forwardRef, useImperativeHandle, useCallback } from 'react';
 import { createPortal } from 'react-dom';
 import { AnnotationType, type Block, type Annotation, type EditorMode, type InputMethod, type ImageAttachment, type ActionsLabelMode } from '../types';
@@ -908,7 +909,10 @@ export const Viewer = forwardRef<ViewerHandle, ViewerProps>(({
 
     if (viewerCommentPopover.isGlobal) {
       const newAnnotation: Annotation = {
-        id: `global-${Date.now()}`,
+        // randomUUID, not Date.now(): two comments minted in the same
+        // millisecond (paste + submit, or a concurrent external write)
+        // would collide on a timestamp id.
+        id: generateId('global'),
         blockId: '',
         startOffset: 0,
         endOffset: 0,

package/components/blocks/AlertBlock.tsx

@@ -1,6 +1,8 @@
 import React from 'react';
 import type { AlertKind } from '../../types';
 import { renderProseBody } from './proseBody';
+import { InlineMarkdown } from '../InlineMarkdown';
+import { parseAlertTitleLine } from '../../utils/alertTitle';
 
 interface AlertBlockProps {
   blockId: string;
@@ -22,6 +24,25 @@ const TITLE: Record<AlertKind, string> = {
   important: 'Important',
 };
 
+/**
+ * Host seam: resolve a named icon from a title line's `<!-- icon: name -->`
+ * comment to a React node. Default: null for every name, so the alert keeps
+ * the type's own icon exactly as today. A host that ships an icon set (the
+ * package deliberately bundles none) registers a renderer once at startup.
+ * Returning null for an unknown name falls back to the type's icon.
+ */
+export type AlertIconRenderer = (name: string) => React.ReactNode | null;
+
+let alertIconRenderer: AlertIconRenderer | null = null;
+
+export function setAlertIconRenderer(renderer: AlertIconRenderer | null): void {
+  alertIconRenderer = renderer;
+}
+
+export function resetAlertIconRenderer(): void {
+  alertIconRenderer = null;
+}
+
 const Icon: React.FC<{ kind: AlertKind }> = ({ kind }) => {
   const common = { viewBox: '0 0 16 16', width: '16', height: '16', fill: 'currentColor', 'aria-hidden': true as const };
   switch (kind) {
@@ -41,6 +62,19 @@ const Icon: React.FC<{ kind: AlertKind }> = ({ kind }) => {
 export const AlertBlock: React.FC<AlertBlockProps> = ({
   blockId, kind, body, onOpenLinkedDoc, onOpenCodeFile, imageBaseDir, onImageClick, githubRepo, onNavigateAnchor,
 }) => {
+  const proseProps = { imageBaseDir, onImageClick, onOpenLinkedDoc, onOpenCodeFile, onNavigateAnchor, githubRepo };
+
+  // A bold-only first line (optionally led by one emoji, optionally trailed by
+  // an `<!-- icon: name -->` comment) is the alert's title and rides the icon
+  // row in place of the type word; the emoji, or a host-resolved named icon,
+  // takes the icon slot. See utils/alertTitle for the exact grammar. A body
+  // with no such line renders exactly as before.
+  const titleLine = parseAlertTitleLine(body);
+  const hostIcon = titleLine?.icon && alertIconRenderer ? alertIconRenderer(titleLine.icon) : null;
+  const icon = titleLine?.emoji
+    ? <span aria-hidden="true" className="alert-emoji text-base leading-none">{titleLine.emoji}</span>
+    : hostIcon ?? <Icon kind={kind} />;
+
   return (
     <div
       className={`alert alert-${kind} my-4 pl-4 pr-3 py-2 border-l-[3px]`}
@@ -48,11 +82,24 @@ export const AlertBlock: React.FC<AlertBlockProps> = ({
       data-block-type="alert"
       data-alert-kind={kind}
     >
-      <div className="alert-title flex items-center gap-2 font-semibold mb-1">
-        <Icon kind={kind} />
-        <span>{TITLE[kind]}</span>
+      <div
+        className="alert-title flex items-center gap-2 font-semibold mb-1"
+        aria-label={titleLine?.title ? `${TITLE[kind]}: ${titleLine.title}` : undefined}
+      >
+        {icon}
+        <span>
+          {titleLine?.title
+            ? <InlineMarkdown text={titleLine.title} {...proseProps} />
+            : TITLE[kind]}
+        </span>
       </div>
-      {renderProseBody({ body, imageBaseDir, onImageClick, onOpenLinkedDoc, onOpenCodeFile, onNavigateAnchor, githubRepo })}
+      {titleLine
+        ? (titleLine.rest.trim()
+            // Indent the body by the icon's width plus the row gap so it starts
+            // at the title's left edge (16px icon + 8px gap = pl-6).
+            ? <div className="alert-body pl-6">{renderProseBody({ body: titleLine.rest, ...proseProps })}</div>
+            : null)
+        : renderProseBody({ body, ...proseProps })}
     </div>
   );
 };

package/config/reviewView.ts

@@ -56,6 +56,7 @@ export function getPersistedReviewPanelView(): 'sections' | 'tree' | undefined {
 
 export type ReviewDefaultDiffType =
   | 'since-base'
+  | 'local-vs-remote'
   | 'uncommitted'
   | 'unstaged'
   | 'staged'

package/config/settings.ts

@@ -15,6 +15,13 @@ import {
 } from '@plannotator/core/agent-terminal';
 import type { DiffLineBgIntensity } from '@plannotator/core/config-types';
 import { isFaviconStyle, type FaviconStyle } from '@plannotator/core/favicon';
+import {
+  DEFAULT_TOKEN_HOVER_DELAY_MS,
+  isTokenHoverDelay,
+  resolveStoredTokenHoverTrigger,
+  type TokenHoverDelay,
+  type TokenHoverTrigger,
+} from '@plannotator/core/token-hover';
 import { storage } from '../utils/storage';
 import { generateIdentity } from '../utils/generateIdentity';
 import {
@@ -276,6 +283,44 @@ export const SETTINGS = {
     serverKey: undefined, fromServer: undefined, toServer: undefined,
   },
 
+  // Hovering a token in a code-review diff opens a card with what the search
+  // backend knows about that symbol. Cookie-only like the other review-chrome
+  // preferences: it is presentational, per-browser, and changes no review
+  // semantics — `off` simply means no listeners, no requests and no card.
+  //
+  // This one select REPLACED the original `tokenHoverCards` boolean rather
+  // than sitting beside it: a toggle plus a mode has an unreachable state
+  // (disabled + modifier) and asks one question with two controls. The legacy
+  // cookie is still read — on every load until the user touches this setting,
+  // since a migrating read returns a value and so never triggers the
+  // registry's default-seeding write — so an early adopter who turned cards
+  // off stays off. Resolution is pure and identical every time; see
+  // resolveStoredTokenHoverTrigger.
+  tokenHoverTrigger: {
+    defaultValue: 'hover' as TokenHoverTrigger,
+    fromCookie: () => resolveStoredTokenHoverTrigger(
+      storage.getItem('plannotator-token-hover-trigger'),
+      storage.getItem('plannotator-token-hover-cards'),
+    ),
+    toCookie: (value: TokenHoverTrigger) =>
+      storage.setItem('plannotator-token-hover-trigger', value),
+    serverKey: undefined, fromServer: undefined, toServer: undefined,
+  },
+
+  // How long the pointer rests on a symbol before a card is requested. Three
+  // fixed steps, not a slider: "too eager" is a real complaint that neither
+  // `modifier` nor `off` answers, but nobody can tell 340ms from 360ms.
+  tokenHoverDelay: {
+    defaultValue: DEFAULT_TOKEN_HOVER_DELAY_MS as TokenHoverDelay,
+    fromCookie: () => {
+      const parsed = Number(storage.getItem('plannotator-token-hover-delay'));
+      return isTokenHoverDelay(parsed) ? parsed : undefined;
+    },
+    toCookie: (value: TokenHoverDelay) =>
+      storage.setItem('plannotator-token-hover-delay', String(value)),
+    serverKey: undefined, fromServer: undefined, toServer: undefined,
+  },
+
   reviewShowStageControls: {
     defaultValue: true as boolean,
     fromCookie: () => {
@@ -288,18 +333,18 @@ export const SETTINGS = {
   },
 
   defaultDiffType: {
-    defaultValue: 'since-base' as 'since-base' | 'uncommitted' | 'unstaged' | 'staged' | 'merge-base' | 'all',
+    defaultValue: 'since-base' as 'since-base' | 'local-vs-remote' | 'uncommitted' | 'unstaged' | 'staged' | 'merge-base' | 'all',
     fromCookie: () => {
       const v = storage.getItem('plannotator-default-diff-type');
       if (v === 'branch') return 'merge-base' as const;
-      return v === 'since-base' || v === 'uncommitted' || v === 'unstaged' || v === 'staged' || v === 'merge-base' || v === 'all' ? v : undefined;
+      return v === 'since-base' || v === 'local-vs-remote' || v === 'uncommitted' || v === 'unstaged' || v === 'staged' || v === 'merge-base' || v === 'all' ? v : undefined;
     },
     toCookie: (v: string) => storage.setItem('plannotator-default-diff-type', v),
     serverKey: 'diffOptions',
     fromServer: (sc: Record<string, unknown>) => {
       const v = (sc.diffOptions as Record<string, unknown> | undefined)?.defaultDiffType;
       if (v === 'branch') return 'merge-base' as const;
-      return v === 'since-base' || v === 'uncommitted' || v === 'unstaged' || v === 'staged' || v === 'merge-base' || v === 'all' ? v : undefined;
+      return v === 'since-base' || v === 'local-vs-remote' || v === 'uncommitted' || v === 'unstaged' || v === 'staged' || v === 'merge-base' || v === 'all' ? v : undefined;
     },
     toServer: (v: string) => ({ diffOptions: { defaultDiffType: v } }),
   },

package/configure.ts

@@ -11,6 +11,7 @@ import { setSkillCatalogTransport, setSkillContentTransport, type SkillCatalogTr
 import { setWebMcpPolicy, type WebMcpPolicy } from './webmcp/policy';
 import { setMathRendererLoader, type MathRenderer, type MathRendererLoader } from './utils/math';
 import { setIdentityGenerator, type IdentityGenerator } from './utils/generateIdentity';
+import { setAlertIconRenderer, type AlertIconRenderer } from './components/blocks/AlertBlock';
 import { configStore } from './config';
 import type { ServerSyncFn } from './config/configStore';
 import type { ExternalAnnotationEvent, VaultNode } from './types';
@@ -38,6 +39,7 @@ export type {
   MathRenderer,
   MathRendererLoader,
   IdentityGenerator,
+  AlertIconRenderer,
 };
 
 type ExternalAnnotationBase = { id: string; source?: string };
@@ -85,6 +87,12 @@ export interface PlannotatorUIConfig {
    * dictionary by importing `@plannotator/ui/utils/identity-tater`.
    */
   identityGenerator?: IdentityGenerator;
+  /**
+   * Resolve a GitHub alert title line's `<!-- icon: name -->` to a React node.
+   * Default: null for every name, so alerts keep the type's own icon exactly as
+   * today; the package bundles no icon set. A host with one registers a renderer.
+   */
+  alertIconRenderer?: AlertIconRenderer;
   /** Re-hydrate settings from the installed (SYNCHRONOUS) storageBackend after install. */
   loadSettingsFromBackend?: boolean;
 }
@@ -105,6 +113,7 @@ export function configurePlannotatorUI(config: PlannotatorUIConfig): void {
   if (config.webmcp) setWebMcpPolicy(config.webmcp);
   if (config.mathRendererLoader) setMathRendererLoader(config.mathRendererLoader);
   if (config.identityGenerator) setIdentityGenerator(config.identityGenerator);
+  if (config.alertIconRenderer) setAlertIconRenderer(config.alertIconRenderer);
   // Re-hydrate AFTER storageBackend is installed (load-bearing order — gated last).
   if (config.loadSettingsFromBackend) configStore.loadFromBackend();
 }

package/hooks/useDismissablePopover.ts

@@ -0,0 +1,65 @@
+import { useEffect } from 'react';
+
+/**
+ * Outside-`pointerdown` + Escape dismissal for anchored popovers — the one
+ * shared effect behind DecisionControl, ActionMenu, and ApproveDropdown.
+ * (FloatingQuickLabelPicker deliberately keeps its own dismissal: it needs
+ * deferred capture-phase registration so the click that opens it cannot
+ * dismiss it, and its Escape shares a listener with the digit-select keys.)
+ *
+ * `dismissOnIframeFocus` is the explicit strategy for framed surfaces
+ * (raw-HTML srcdoc, live-app proxy): a click inside the iframe never produces
+ * a `pointerdown` in the parent document, but it does move focus into the
+ * frame, which fires `blur` on the parent window. The check runs on the next
+ * task because `document.activeElement` is not yet updated inside the blur
+ * handler.
+ */
+export function useDismissablePopover({
+  enabled,
+  ref,
+  onDismiss,
+  dismissOnIframeFocus,
+}: {
+  enabled: boolean;
+  ref: React.RefObject<HTMLElement | null>;
+  onDismiss: () => void;
+  dismissOnIframeFocus?: boolean;
+}) {
+  useEffect(() => {
+    if (!enabled) return;
+
+    const handlePointerDown = (event: PointerEvent) => {
+      const target = event.target as Node | null;
+      if (target && ref.current && ref.current.contains(target)) return;
+      onDismiss();
+    };
+
+    const handleKeyDown = (event: KeyboardEvent) => {
+      if (event.key !== 'Escape' || event.defaultPrevented) return;
+      // Fail closed: an Escape that dismisses the popover is consumed here
+      // (document bubbles before window), so the host apps' window-level
+      // Escape ladders never also act on it — one Escape, one rung.
+      event.preventDefault();
+      event.stopPropagation();
+      onDismiss();
+    };
+
+    let blurTimer: ReturnType<typeof setTimeout> | undefined;
+    const handleWindowBlur = () => {
+      blurTimer = setTimeout(() => {
+        if (document.activeElement?.tagName === 'IFRAME') onDismiss();
+      }, 0);
+    };
+
+    document.addEventListener('pointerdown', handlePointerDown);
+    document.addEventListener('keydown', handleKeyDown);
+    if (dismissOnIframeFocus) window.addEventListener('blur', handleWindowBlur);
+
+    return () => {
+      document.removeEventListener('pointerdown', handlePointerDown);
+      document.removeEventListener('keydown', handleKeyDown);
+      if (dismissOnIframeFocus) window.removeEventListener('blur', handleWindowBlur);
+      if (blurTimer !== undefined) clearTimeout(blurTimer);
+    };
+  }, [enabled, ref, onDismiss, dismissOnIframeFocus]);
+}

package/hooks/useVimDocumentFocus.ts

@@ -18,6 +18,12 @@ const BLOCKING_OVERLAY_SELECTOR = [
   // Vim from focusing the obscured document underneath those full-screen
   // overlays while they are brought onto the shared dialog primitive.
   '.fixed.inset-0',
+  // An open dismissable popover (ActionMenu, ApproveDropdown, DecisionControl)
+  // owns Escape through useDismissablePopover. Without this, the vim handler
+  // runs first (it registered earlier on document), preventDefaults while
+  // reclaiming focus, and the popover's own Escape handler then skips the
+  // defaultPrevented event — the menu never closes.
+  '[data-pn-dismissable-popover]',
 ].join(',');
 
 /** Inputs for restoring keyboard ownership to a Vim-enabled document. */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@plannotator/ui",
-  "version": "0.37.0",
+  "version": "0.38.0",
   "type": "module",
   "exports": {
     "./components/*": "./components/*.tsx",
@@ -54,57 +54,57 @@
     "!test-setup"
   ],
   "dependencies": {
-    "@base-ui/react": "^1.6.0",
+    "@base-ui/react": "^1.7.0",
     "@codemirror/autocomplete": "^6.20.3",
-    "@codemirror/commands": "^6.10.3",
+    "@codemirror/commands": "^6.11.0",
     "@codemirror/lang-javascript": "^6.2.5",
     "@codemirror/lang-json": "^6.0.2",
-    "@codemirror/lang-markdown": "^6.5.0",
+    "@codemirror/lang-markdown": "^6.5.2",
     "@codemirror/lang-python": "^6.2.1",
     "@codemirror/lang-yaml": "^6.1.3",
-    "@codemirror/language": "^6.12.3",
+    "@codemirror/language": "^6.12.4",
     "@codemirror/legacy-modes": "^6.5.3",
     "@codemirror/merge": "^6.12.2",
-    "@codemirror/search": "^6.7.0",
+    "@codemirror/search": "^6.7.2",
     "@codemirror/state": "^6.6.0",
-    "@codemirror/view": "^6.43.0",
-    "@fontsource-variable/geist-mono": "5.2.7",
-    "@fontsource-variable/inter": "^5.2.8",
+    "@codemirror/view": "^6.43.10",
+    "@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.2",
+    "@pierre/diffs": "1.3.6",
     "@plannotator/atomic-editor": "^0.8.0",
     "@plannotator/core": "0.25.1",
     "@plannotator/markdown-editor": "^0.4.0",
     "@plannotator/web-highlighter": "^0.8.1",
     "@tanstack/react-table": "^8.21.3",
-    "@viz-js/viz": "^3.25.0",
+    "@viz-js/viz": "^3.29.0",
     "class-variance-authority": "^0.7.1",
     "clsx": "^2.1.1",
     "diff": "^8.0.4",
-    "dompurify": "^3.3.3",
+    "dompurify": "^3.4.14",
     "katex": "^0.16.47",
-    "lucide-react": "^1.14.0",
+    "lucide-react": "^1.38.0",
     "marked": "^17.0.6",
-    "mermaid": "^11.12.2",
+    "mermaid": "^11.17.2",
     "motion": "^12.38.0",
     "perfect-freehand": "^1.2.2",
     "tailwind-merge": "^3.6.0",
     "unique-username-generator": "^1.5.1"
   },
   "peerDependencies": {
-    "react": "^19.2.3",
-    "react-dom": "^19.2.3",
+    "react": "^19.2.8",
+    "react-dom": "^19.2.8",
     "tailwindcss": "^4.1.18"
   },
   "devDependencies": {
-    "@happy-dom/global-registrator": "^20.10.1",
-    "@tailwindcss/vite": "^4.1.18",
+    "@happy-dom/global-registrator": "^20.12.0",
+    "@tailwindcss/vite": "^4.3.3",
     "@types/bun": "^1.2.0",
-    "@types/react": "^19.2.0",
-    "@types/react-dom": "^19.2.0",
-    "react": "^19.2.3",
-    "react-dom": "^19.2.3",
+    "@types/react": "^19.2.18",
+    "@types/react-dom": "^19.2.5",
+    "react": "^19.2.8",
+    "react-dom": "^19.2.8",
     "tailwindcss": "^4.1.18",
     "typescript": "~5.8.2",
     "vite": "^6.2.0"

package/shortcuts/decisionControl.shortcuts.ts

@@ -0,0 +1,31 @@
+import { defineShortcutScope } from './core';
+
+/**
+ * The header decision control's note composer (shortcuts root, not
+ * plan-review/ or code-review/: both apps mount the identical control with
+ * identical semantics).
+ *
+ * Documents ONLY the chords the control actually implements — bindings must
+ * match shipped behavior (`DecisionControl.tsx`). Enter is a newline in the
+ * note field and must never be documented as submit.
+ */
+export const decisionControlShortcuts = defineShortcutScope({
+  id: 'decision-control',
+  title: 'Decision control',
+  shortcuts: {
+    submitNote: {
+      description: 'Send the note with the decision you picked',
+      bindings: ['Mod+Enter'],
+      section: 'Actions',
+      hint: "Available while the decision control's note field is open. Enter inserts a newline.",
+      displayOrder: 12,
+    },
+    closeNote: {
+      description: 'Step back to the decision menu, keeping the note',
+      bindings: ['Escape'],
+      section: 'Actions',
+      hint: "Available while the decision control's note field is open.",
+      displayOrder: 14,
+    },
+  },
+});

package/shortcuts/index.ts

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