@plannotator/ui 0.36.0 → 0.38.0

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/useAnnotationHighlighter.ts

@@ -196,6 +196,12 @@ const escapeAttrValue = (value: string): string => {
 const normalizeForRestoreCompare = (value: string): string =>
   value.replace(/\s+/g, ' ').trim();
 
+// web-highlighter 0.8.x accepts only class, ID, and tag exclusions.
+const ANNOTATION_EXCLUDED_SELECTOR = '.annotation-exclude';
+
+const isAnnotationExcludedTextNode = (node: Node): boolean =>
+  Boolean(node.parentElement?.closest(ANNOTATION_EXCLUDED_SELECTOR));
+
 const applyMathAnnotationClass = (
   element: HTMLElement,
   id: string,
@@ -361,21 +367,28 @@ export function useAnnotationHighlighter({
     const searchOnce = (needle: string): Range | null => {
       if (!needle || !containerRef.current) return null;
 
-      const rangeFromTextOffsets = (startIndex: number, endIndex: number): Range | null => {
-        const walker = document.createTreeWalker(
-          containerRef.current!,
-          NodeFilter.SHOW_TEXT,
-          null
-        );
+      const walker = document.createTreeWalker(
+        containerRef.current,
+        NodeFilter.SHOW_TEXT,
+        {
+          acceptNode: (node) => isAnnotationExcludedTextNode(node)
+            ? NodeFilter.FILTER_REJECT
+            : NodeFilter.FILTER_ACCEPT,
+        },
+      );
+      const textNodes: Text[] = [];
+      let currentNode: Text | null;
+      while ((currentNode = walker.nextNode() as Text | null)) {
+        textNodes.push(currentNode);
+      }
 
+      const rangeFromTextOffsets = (startIndex: number, endIndex: number): Range | null => {
         let charCount = 0;
         let startNode: Text | null = null;
         let startOffset = 0;
         let endNode: Text | null = null;
         let endOffset = 0;
-        let node: Text | null;
-
-        while ((node = walker.nextNode() as Text | null)) {
+        for (const node of textNodes) {
           const nodeLength = node.textContent?.length || 0;
 
           if (!startNode && charCount + nodeLength > startIndex) {
@@ -433,14 +446,7 @@ export function useAnnotationHighlighter({
         };
       };
 
-      const walker = document.createTreeWalker(
-        containerRef.current,
-        NodeFilter.SHOW_TEXT,
-        null
-      );
-
-      let node: Text | null;
-      while ((node = walker.nextNode() as Text | null)) {
+      for (const node of textNodes) {
         const text = node.textContent || '';
         const index = text.indexOf(needle);
         if (index !== -1) {
@@ -451,7 +457,7 @@ export function useAnnotationHighlighter({
         }
       }
 
-      const fullText = containerRef.current.textContent || '';
+      const fullText = textNodes.map((node) => node.textContent ?? '').join('');
       const searchIndex = fullText.indexOf(needle);
       if (searchIndex !== -1) {
         return rangeFromTextOffsets(searchIndex, searchIndex + needle.length);
@@ -840,7 +846,13 @@ export function useAnnotationHighlighter({
 
     const highlighter = new Highlighter({
       $root: containerRef.current,
-      exceptSelectors: ['.annotation-toolbar', 'button', '.math-annotatable', '.katex'],
+      exceptSelectors: [
+        '.annotation-toolbar',
+        'button',
+        '.math-annotatable',
+        '.katex',
+        ANNOTATION_EXCLUDED_SELECTOR,
+      ],
       wrapTag: 'mark',
       style: { className: 'annotation-highlight' },
     });

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.36.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';

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

@@ -7,6 +7,11 @@ import { createShortcutScopeHook } from '../runtime';
  * Focus mode is the keyboard entry point to the same view state the document
  * card's `Focus` control drives: both side panels collapse in one press and the
  * previous arrangement comes back on the next one.
+ *
+ * Edit mode is its sibling: the same chord the card's `Edit` / `Done` control
+ * drives, opening the markdown source editor in place and committing back to
+ * the viewer — the scroll position survives both directions, so a mid-document
+ * fix never costs a scroll to the top and back.
  */
 export const documentViewShortcuts = defineShortcutScope({
   id: 'document-view',
@@ -20,6 +25,14 @@ export const documentViewShortcuts = defineShortcutScope({
       displayOrder: 10,
       preventDefault: true,
     },
+    toggleEditMode: {
+      description: 'Toggle edit mode',
+      bindings: ['Mod+E'],
+      section: 'View',
+      hint: 'Opens the markdown source editor in place, keeping your scroll position; press again to commit your edits and return to annotating.',
+      displayOrder: 20,
+      preventDefault: true,
+    },
   },
 });