@plannotator/ui 0.46.1 → 0.49.0

package/hooks/useCodeAnnotationDraft.ts

@@ -72,6 +72,8 @@ interface UseCodeAnnotationDraftOptions {
   autoViewSuppressed?: Set<string>;
   isApiMode: boolean;
   submitted: boolean;
+  /** Hosts with independent review-progress storage omit viewed state from drafts. */
+  persistViewedFiles?: boolean;
   /** Receives the unsent items found on a target the session switched onto
    *  in place (#1590), already filtered to ids the session neither holds nor
    *  deleted. The host adds them to its state; autosave then saves the merge.
@@ -125,12 +127,15 @@ export function useCodeAnnotationDraft({
   submitted,
   onDraftTargetMerge,
   targetLoadTimeoutMs = TARGET_LOAD_TIMEOUT_MS,
+  persistViewedFiles = true,
 }: UseCodeAnnotationDraftOptions): UseCodeAnnotationDraftResult {
   const [draftBanner, setDraftBanner] = useState<{ count: number; viewedCount: number; timeAgo: string } | null>(null);
   const draftDataRef = useRef<DraftData | null>(null);
   const timerRef = useRef<ReturnType<typeof setTimeout> | null>(null);
   const hasMountedRef = useRef(false);
   const draftGenerationRef = useRef(0);
+  const persistViewedRef = useRef(persistViewedFiles);
+  persistViewedRef.current = persistViewedFiles;
   // True once the user has actually had annotations this session. Used to decide
   // whether an empty state is a real "cleared everything" edit (persist it) vs a
   // fresh/unengaged session (leave the server alone). Keyed on annotations only —
@@ -186,6 +191,9 @@ export function useCodeAnnotationDraft({
         return data as DraftData | null;
       })
       .then((data: DraftData | null) => {
+        // Keep even a viewed-only draft while independent progress support is
+        // unresolved; a failed/unsupported load may need to offer it later.
+        draftDataRef.current = data;
         const generation = readDraftGeneration(data?.draftGeneration);
         if (generation !== null) {
           draftGenerationRef.current = Math.max(draftGenerationRef.current, generation);
@@ -193,7 +201,7 @@ export function useCodeAnnotationDraft({
         const annotationCount = (Array.isArray(data?.codeAnnotations) ? data.codeAnnotations.length : 0)
           + (Array.isArray(data?.descriptionAnnotations) ? data.descriptionAnnotations.length : 0)
           + (Array.isArray(data?.commentAnnotations) ? data.commentAnnotations.length : 0);
-        const viewedCount = Array.isArray(data?.viewedFiles) ? data.viewedFiles.length : 0;
+        const viewedCount = persistViewedRef.current && Array.isArray(data?.viewedFiles) ? data.viewedFiles.length : 0;
         if (annotationCount > 0 || viewedCount > 0) {
           draftDataRef.current = data;
           setDraftBanner({
@@ -209,6 +217,15 @@ export function useCodeAnnotationDraft({
       });
   }, [isApiMode]);
 
+  useEffect(() => {
+    const data = draftDataRef.current;
+    if (!data) return;
+    const count = (data.codeAnnotations?.length ?? 0)
+      + (data.descriptionAnnotations?.length ?? 0) + (data.commentAnnotations?.length ?? 0);
+    const viewedCount = persistViewedFiles ? data.viewedFiles?.length ?? 0 : 0;
+    setDraftBanner(count || viewedCount ? { count, viewedCount, timeAgo: formatTimeAgo(data.ts || 0) } : null);
+  }, [persistViewedFiles]);
+
   // Debounced auto-save on annotation/viewed changes
   useEffect(() => {
     if (!isApiMode || submitted) return;
@@ -223,7 +240,7 @@ export function useCodeAnnotationDraft({
     //     via `allAnnotations` and have their own lifecycle, separate from the draft.
     if (annotations.some((a) => !a.source) || descriptionAnnotations.length > 0 || commentAnnotations.length > 0) hasHadAnnotationsRef.current = true;
 
-    const isEmpty = annotations.length === 0 && descriptionAnnotations.length === 0 && commentAnnotations.length === 0 && viewedFiles.size === 0;
+    const isEmpty = annotations.length === 0 && descriptionAnnotations.length === 0 && commentAnnotations.length === 0 && (!persistViewedFiles || viewedFiles.size === 0);
     // Leave the server alone for an empty state until the user has actually had
     // annotations this session. This preserves an unrestored draft sitting on disk
     // at mount (the draft-recovery banner can still offer it).
@@ -259,8 +276,8 @@ export function useCodeAnnotationDraft({
         codeAnnotations: annotations,
         descriptionAnnotations,
         commentAnnotations,
-        viewedFiles: [...viewedFiles],
-        ...(autoViewSuppressed && autoViewSuppressed.size > 0
+        ...(persistViewedFiles ? { viewedFiles: [...viewedFiles] } : {}),
+        ...(persistViewedFiles && autoViewSuppressed && autoViewSuppressed.size > 0
           ? { autoViewSuppressed: [...autoViewSuppressed] }
           : {}),
         draftGeneration,
@@ -273,7 +290,7 @@ export function useCodeAnnotationDraft({
     return () => {
       if (timerRef.current) clearTimeout(timerRef.current);
     };
-  }, [annotations, descriptionAnnotations, commentAnnotations, viewedFiles, autoViewSuppressed, isApiMode, submitted, saveNudge]);
+  }, [annotations, descriptionAnnotations, commentAnnotations, viewedFiles, autoViewSuppressed, isApiMode, submitted, saveNudge, persistViewedFiles]);
 
   const restoreDraft = useCallback(() => {
     // Cancel any pending autosave so it can't fire with pre-restore state and
@@ -286,9 +303,9 @@ export function useCodeAnnotationDraft({
       annotations: data?.codeAnnotations ?? [],
       descriptionAnnotations: data?.descriptionAnnotations ?? [],
       commentAnnotations: data?.commentAnnotations ?? [],
-      viewedFiles: data?.viewedFiles ?? [],
-      autoViewSuppressed: data?.autoViewSuppressed ?? [],
       patchChanged: data?.patchChanged === true,
+      viewedFiles: persistViewedRef.current ? data?.viewedFiles ?? [] : [],
+      autoViewSuppressed: persistViewedRef.current ? data?.autoViewSuppressed ?? [] : [],
     };
   }, []);
 

package/hooks/useModelCatalogs.ts

@@ -3,6 +3,7 @@ import {
   CLAUDE_FALLBACK_MODELS,
   CODEX_FALLBACK_MODELS,
   type CatalogModel,
+  type ModelsSource,
 } from '@plannotator/core/model-catalog';
 import type { AgentCapabilities } from '../types';
 
@@ -26,8 +27,14 @@ export type CatalogEngine = 'claude' | 'codex';
 export interface ModelCatalog {
   models: CatalogModel[];
   settled: boolean;
+  /** Where the server says the list came from; absent when it did not say. */
+  modelsSource?: ModelsSource;
+  /** The installed CLI's version, when the server reports it. */
+  toolVersion?: string;
 }
 
+type LoadedCatalog = Pick<ModelCatalog, 'models' | 'modelsSource' | 'toolVersion'>;
+
 export interface ModelCatalogs extends Record<CatalogEngine, ModelCatalog> {
   /** Fetch one engine's catalog (no-op for other engines or when not installed). */
   load: (engine: string | null | undefined) => void;
@@ -47,19 +54,19 @@ const isCatalogEngine = (engine: unknown): engine is CatalogEngine => engine ===
 
 // One request per engine per page: every launcher surface shares the answer.
 // A failed request is forgotten so the next load retries it.
-const loads = new Map<CatalogEngine, Promise<CatalogModel[]>>();
+const loads = new Map<CatalogEngine, Promise<LoadedCatalog>>();
 
-export function loadModelCatalog(engine: CatalogEngine): Promise<CatalogModel[]> {
+function loadCatalogEntry(engine: CatalogEngine): Promise<LoadedCatalog> {
   let load = loads.get(engine);
   if (!load) {
     const id = AI_PROVIDER_ID[engine];
-    const failed = () => {
+    const failed = (): LoadedCatalog => {
       loads.delete(engine);
-      return FALLBACK_MODELS[engine];
+      return { models: FALLBACK_MODELS[engine] };
     };
     load = fetch(`/api/ai/capabilities?activate=${encodeURIComponent(id)}`)
       .then((res) => (res.ok ? res.json() : null))
-      .then((data) => {
+      .then((data): LoadedCatalog => {
         const provider = data?.providers?.find((p: { id?: string; name?: string }) => p.id === id || p.name === id);
         const models = provider?.models;
         if (!Array.isArray(models) || models.length === 0) return failed();
@@ -67,7 +74,13 @@ export function loadModelCatalog(engine: CatalogEngine): Promise<CatalogModel[]>
         // failed; show it, but forget it so the next load retries (the
         // server's own cooldown bounds how often that spawns the CLI).
         if (provider.modelsSource === 'fallback') loads.delete(engine);
-        return models as CatalogModel[];
+        return {
+          models: models as CatalogModel[],
+          ...(provider.modelsSource === 'fallback' || provider.modelsSource === 'discovered'
+            ? { modelsSource: provider.modelsSource as ModelsSource }
+            : {}),
+          ...(typeof provider.toolVersion === 'string' && provider.toolVersion ? { toolVersion: provider.toolVersion } : {}),
+        };
       })
       .catch(failed);
     loads.set(engine, load);
@@ -75,6 +88,10 @@ export function loadModelCatalog(engine: CatalogEngine): Promise<CatalogModel[]>
   return load;
 }
 
+export function loadModelCatalog(engine: CatalogEngine): Promise<CatalogModel[]> {
+  return loadCatalogEntry(engine).then((entry) => entry.models);
+}
+
 /** Test seam: forget cached catalogs. */
 export function __resetModelCatalogsForTests(): void {
   loads.clear();
@@ -85,7 +102,7 @@ export function useModelCatalogs(capabilities: AgentCapabilities | null): ModelC
     capabilities?.providers.some((p) => p.id === id && p.available) ?? false;
   const claudeOn = available('claude');
   const codexOn = available('codex');
-  const [loaded, setLoaded] = useState<Partial<Record<CatalogEngine, CatalogModel[]>>>({});
+  const [loaded, setLoaded] = useState<Partial<Record<CatalogEngine, LoadedCatalog>>>({});
   const mounted = useRef(true);
   useEffect(() => {
     mounted.current = true;
@@ -98,8 +115,8 @@ export function useModelCatalogs(capabilities: AgentCapabilities | null): ModelC
     (engine: string | null | undefined) => {
       if (!isCatalogEngine(engine)) return;
       if (!(engine === 'claude' ? claudeOn : codexOn)) return;
-      void loadModelCatalog(engine).then((models) => {
-        if (mounted.current) setLoaded((prev) => (prev[engine] === models ? prev : { ...prev, [engine]: models }));
+      void loadCatalogEntry(engine).then((entry) => {
+        if (mounted.current) setLoaded((prev) => (prev[engine] === entry ? prev : { ...prev, [engine]: entry }));
       });
     },
     [claudeOn, codexOn],
@@ -107,8 +124,8 @@ export function useModelCatalogs(capabilities: AgentCapabilities | null): ModelC
 
   return useMemo(
     () => ({
-      claude: { models: loaded.claude ?? FALLBACK_MODELS.claude, settled: !!loaded.claude },
-      codex: { models: loaded.codex ?? FALLBACK_MODELS.codex, settled: !!loaded.codex },
+      claude: loaded.claude ? { ...loaded.claude, settled: true } : { models: FALLBACK_MODELS.claude, settled: false },
+      codex: loaded.codex ? { ...loaded.codex, settled: true } : { models: FALLBACK_MODELS.codex, settled: false },
       load,
     }),
     [loaded, load],

package/hooks/usePinpoint.ts

@@ -137,6 +137,10 @@ export function usePinpoint({
 
     const handleClick = (e: MouseEvent) => {
       const target = e.target as HTMLElement;
+      // A `:::question` card's form controls are the answer UI, never a pin
+      // target: a click on a radio, a checkbox or a text box answers.
+      const inQuestion = !!target.closest?.('fieldset.question-block');
+      if (inQuestion && target.closest('input, textarea, select')) return;
       const resolved = resolveSemanticTargetAtPoint(
         buildSemanticTargetGraph(container),
         target,
@@ -144,6 +148,12 @@ export function usePinpoint({
       );
       if (!resolved) return;
 
+      // Pinning a choice's text must not also pick the choice: the row is a
+      // <label>, which would forward this click to its radio or checkbox.
+      if (inQuestion && target.closest('[data-question-option]')) {
+        e.preventDefault();
+      }
+
       // Prevent link navigation in pinpoint mode
       const link = (target.closest('a') as HTMLAnchorElement | null);
       if (link && container.contains(link)) {

package/hooks/useScrollKeyRouting.ts

@@ -0,0 +1,157 @@
+import { useEffect } from 'react';
+import { hasBlockingOverlay } from './useVimDocumentFocus';
+import { isDocumentScrollViewport } from './useScrollViewport';
+
+/**
+ * Scroll keys with no browser target (#1647).
+ *
+ * The desktop editor scrolls inside an element (`<main>`), not the window. On
+ * load nothing is focused and the user has not clicked anywhere, so the
+ * browser's keyboard-scroll starting point is the root scroller, which cannot
+ * scroll: ArrowDown, PageDown and Space do nothing until the reader clicks into
+ * the document. The same dead state returns after the node the user last
+ * clicked is removed (a dismissed first-run dialog) or when that click landed
+ * on chrome with nothing scrollable above it (the header).
+ *
+ * This hook fills exactly that gap and nothing else. It never moves focus, so
+ * dialogs, popovers, screen readers and `:focus-visible` are untouched. It
+ * only acts when all of these hold:
+ *   - focus is neutral (body), so no control, input, editor or iframe owns
+ *     the key;
+ *   - no earlier listener consumed the key (`defaultPrevented`);
+ *   - no modifier except Shift+Space (page up), and not mid-composition;
+ *   - no dialog, modal overlay, popover, menu or listbox is open;
+ *   - the browser has no scroll target of its own: the last pointerdown is
+ *     absent, detached, or has no vertically scrollable ancestor. When it has
+ *     one (a click in the document, the annotations panel, the sidebar), the
+ *     native key scroll already works and is left alone.
+ */
+
+const LINE_STEP_PX = 40;
+/**
+ * Page step as Chromium and WebKit compute it: the larger of 87.5% of the
+ * viewport (kMinFractionToStepWhenPaging) and the viewport minus a 40px
+ * overlap (kMaxOverlapBetweenPages). On a normal window the overlap rule wins,
+ * so a routed PageDown matches the native one taken after a click.
+ */
+const PAGE_FRACTION = 0.875;
+const PAGE_OVERLAP_PX = 40;
+
+const OPEN_POPUP_SELECTOR = '[role="menu"], [role="listbox"]';
+
+export type ScrollKeyAction =
+  | { readonly kind: 'line'; readonly direction: 1 | -1 }
+  | { readonly kind: 'page'; readonly direction: 1 | -1 }
+  | { readonly kind: 'edge'; readonly edge: 'start' | 'end' };
+
+/** The keydown fields the mapping reads (pure, so it runs without a DOM). */
+export type ScrollKeyInput = Pick<
+  KeyboardEvent,
+  'key' | 'isComposing' | 'ctrlKey' | 'metaKey' | 'altKey' | 'shiftKey'
+>;
+
+/** Map a keydown to the scroll it asks for, or null when it is not a plain scroll key. */
+export function scrollKeyAction(event: ScrollKeyInput): ScrollKeyAction | null {
+  if (event.isComposing || event.ctrlKey || event.metaKey || event.altKey) return null;
+  const isSpace = event.key === ' ' || event.key === 'Spacebar';
+  if (isSpace) return { kind: 'page', direction: event.shiftKey ? -1 : 1 };
+  if (event.shiftKey) return null;
+  switch (event.key) {
+    case 'ArrowDown': return { kind: 'line', direction: 1 };
+    case 'ArrowUp': return { kind: 'line', direction: -1 };
+    case 'PageDown': return { kind: 'page', direction: 1 };
+    case 'PageUp': return { kind: 'page', direction: -1 };
+    case 'Home': return { kind: 'edge', edge: 'start' };
+    case 'End': return { kind: 'edge', edge: 'end' };
+    default: return null;
+  }
+}
+
+function canScrollVertically(element: Element): boolean {
+  if (!(element instanceof HTMLElement)) return false;
+  if (element.scrollHeight <= element.clientHeight) return false;
+  const overflowY = getComputedStyle(element).overflowY;
+  return overflowY === 'auto' || overflowY === 'scroll' || overflowY === 'overlay';
+}
+
+/**
+ * Whether the browser already has a keyboard-scroll target: the last clicked
+ * node is still in the page and sits inside a vertically scrollable element.
+ */
+export function browserHasScrollTarget(lastPointerTarget: Node | null): boolean {
+  if (!lastPointerTarget || !lastPointerTarget.isConnected) return false;
+  const root = lastPointerTarget.ownerDocument?.documentElement ?? null;
+  let node: Node | null = lastPointerTarget;
+  while (node && node !== root) {
+    if (node instanceof Element && canScrollVertically(node)) return true;
+    const parent: Node | null = node.parentNode;
+    node = parent instanceof ShadowRoot ? parent.host : parent;
+  }
+  return false;
+}
+
+function focusIsNeutral(event: KeyboardEvent): boolean {
+  const doc = document;
+  const active = doc.activeElement;
+  if (active !== null && active !== doc.body && active !== doc.documentElement) return false;
+  const origin = event.composedPath?.()[0] ?? event.target;
+  return origin === doc.body || origin === doc.documentElement || origin === doc || origin === window;
+}
+
+function prefersReducedMotion(): boolean {
+  return typeof window.matchMedia === 'function'
+    && window.matchMedia('(prefers-reduced-motion: reduce)').matches;
+}
+
+function applyScroll(viewport: HTMLElement, action: ScrollKeyAction): void {
+  if (action.kind === 'line') {
+    viewport.scrollBy({ top: action.direction * LINE_STEP_PX, behavior: 'auto' });
+    return;
+  }
+  const behavior: ScrollBehavior = prefersReducedMotion() ? 'auto' : 'smooth';
+  if (action.kind === 'edge') {
+    viewport.scrollTo({ top: action.edge === 'start' ? 0 : viewport.scrollHeight, behavior });
+    return;
+  }
+  const height = viewport.clientHeight;
+  const page = Math.max(1, Math.round(Math.max(height * PAGE_FRACTION, height - PAGE_OVERLAP_PX)));
+  viewport.scrollBy({ top: action.direction * page, behavior });
+}
+
+export interface UseScrollKeyRoutingOptions {
+  /** The element that scrolls the document. Page-scrolling viewports are ignored. */
+  readonly viewport: HTMLElement | null;
+  /** False where another owner has the keys (vim, iframe surfaces). */
+  readonly enabled: boolean;
+}
+
+/** Route unowned scroll keys to the document viewport. See the module comment. */
+export function useScrollKeyRouting({ viewport, enabled }: UseScrollKeyRoutingOptions): void {
+  useEffect(() => {
+    if (!enabled || !viewport || isDocumentScrollViewport(viewport)) return;
+
+    let lastPointerTarget: Node | null = null;
+    const handlePointerDown = (event: PointerEvent) => {
+      const origin = event.composedPath?.()[0] ?? event.target;
+      lastPointerTarget = origin instanceof Node ? origin : null;
+    };
+
+    const handleKeyDown = (event: KeyboardEvent) => {
+      if (event.defaultPrevented) return;
+      const action = scrollKeyAction(event);
+      if (!action) return;
+      if (!viewport.isConnected || !focusIsNeutral(event)) return;
+      if (hasBlockingOverlay() || document.querySelector(OPEN_POPUP_SELECTOR)) return;
+      if (browserHasScrollTarget(lastPointerTarget)) return;
+      event.preventDefault();
+      applyScroll(viewport, action);
+    };
+
+    window.addEventListener('pointerdown', handlePointerDown, true);
+    window.addEventListener('keydown', handleKeyDown);
+    return () => {
+      window.removeEventListener('pointerdown', handlePointerDown, true);
+      window.removeEventListener('keydown', handleKeyDown);
+    };
+  }, [enabled, viewport]);
+}

package/hooks/useUndoHistory.ts

@@ -13,6 +13,13 @@ export interface UndoHistoryApi<TAction> {
   readonly canUndo: boolean;
   readonly canRedo: boolean;
   record: (action: TAction) => void;
+  /**
+   * Coalesce into the newest undo entry: when it is still `expected` (the
+   * same object), replace it with `next`, or drop it when `next` is null.
+   * Returns false, changing nothing, when anything was recorded, undone or
+   * cleared since. Used to fold a typing burst into one entry.
+   */
+  replaceLast: (expected: TAction, next: TAction | null) => boolean;
   undo: () => boolean;
   redo: () => boolean;
   clear: () => void;
@@ -57,6 +64,16 @@ export function useUndoHistory<TAction>({
         const history = historyRef.current;
         history.state = recordUndoAction(history.state, action, optionsRef.current.capacity);
       },
+      replaceLast(expected, next) {
+        const history = historyRef.current;
+        const { past, future } = history.state;
+        if (past.length === 0 || past[past.length - 1] !== expected || future.length > 0) return false;
+        history.state = {
+          past: next === null ? past.slice(0, -1) : [...past.slice(0, -1), next],
+          future,
+        };
+        return true;
+      },
       undo() {
         const history = historyRef.current;
         const step = takeUndoAction(history.state);

package/hooks/useVimDocumentFocus.ts

@@ -38,7 +38,8 @@ function pageFocusIsNeutral(): boolean {
   return document.activeElement === document.body || document.activeElement === null;
 }
 
-function hasBlockingOverlay(): boolean {
+/** True while a dialog, modal overlay, or dismissable popover owns the page. */
+export function hasBlockingOverlay(): boolean {
   return document.querySelector(BLOCKING_OVERLAY_SELECTOR) !== null;
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@plannotator/ui",
-  "version": "0.46.1",
+  "version": "0.49.0",
   "type": "module",
   "exports": {
     "./components/*": "./components/*.tsx",
@@ -75,9 +75,9 @@
     "@lezer/common": "^1.5.2",
     "@lezer/highlight": "^1.2.3",
     "@pierre/diffs": "1.3.6",
-    "@plannotator/atomic-editor": "^0.8.0",
-    "@plannotator/core": "0.25.6",
-    "@plannotator/markdown-editor": "^0.4.0",
+    "@plannotator/atomic-editor": "^0.9.0",
+    "@plannotator/core": "0.25.9",
+    "@plannotator/markdown-editor": "^0.5.0",
     "@plannotator/web-highlighter": "^0.8.1",
     "@tanstack/react-table": "^8.21.3",
     "@viz-js/viz": "3.30.0",