@plannotator/ui 0.45.1 → 0.46.0

package/hooks/useCodeAnnotationDraft.ts

@@ -10,6 +10,18 @@ import type { CodeAnnotation, Annotation, CommentAnnotation } from '../types';
 import { getDraftTransport } from './useAnnotationDraft';
 
 const DEBOUNCE_MS = 500;
+/** Bound on one read of a switched-onto target's draft (#1590). */
+export const TARGET_LOAD_TIMEOUT_MS = 5000;
+
+function withTimeout<T>(promise: Promise<T>, ms: number): Promise<T> {
+  return new Promise<T>((resolve, reject) => {
+    const timer = setTimeout(() => reject(new Error('draft load timed out')), ms);
+    promise.then(
+      (value) => { clearTimeout(timer); resolve(value); },
+      (error) => { clearTimeout(timer); reject(error); },
+    );
+  });
+}
 
 interface DraftData {
   codeAnnotations: CodeAnnotation[];
@@ -28,6 +40,12 @@ interface DraftData {
    */
   autoViewSuppressed?: string[];
   draftGeneration?: number;
+  /**
+   * Set by the review server (never by the client) when a PR draft is served
+   * through the PR's target key for a patch different from the one it was
+   * saved on (#1590). The host re-checks line comments' anchors on restore.
+   */
+  patchChanged?: boolean;
   ts: number;
 }
 
@@ -54,13 +72,47 @@ interface UseCodeAnnotationDraftOptions {
   autoViewSuppressed?: Set<string>;
   isApiMode: boolean;
   submitted: 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.
+   *  Called synchronously before autosave resumes. */
+  onDraftTargetMerge?: (items: CodeDraftMergeItems) => void;
+  /** Bound on one read of a switched-onto target's draft. Default
+   *  `TARGET_LOAD_TIMEOUT_MS`; exposed for tests. */
+  targetLoadTimeoutMs?: number;
+}
+
+/** Items auto-merged from a switched-onto target's draft. */
+export interface CodeDraftMergeItems {
+  annotations: CodeAnnotation[];
+  descriptionAnnotations: Annotation[];
+  commentAnnotations: CommentAnnotation[];
+  /** The server served the draft for a patch other than it was saved on. */
+  patchChanged: boolean;
+}
+
+/** Draft state a review server reports after an in-place target switch
+ *  (PR switch / PR diff-scope switch, #1590). */
+export interface CodeDraftTargetState {
+  found: boolean;
+  draftGeneration: number | null;
 }
 
 interface UseCodeAnnotationDraftResult {
   draftBanner: { count: number; viewedCount: number; timeAgo: string } | null;
-  restoreDraft: () => { annotations: CodeAnnotation[]; descriptionAnnotations: Annotation[]; commentAnnotations: CommentAnnotation[]; viewedFiles: string[]; autoViewSuppressed: string[] };
+  /** `patchChanged` is true when the server served the draft for a patch other
+   *  than the one it was saved on (the host re-checks line anchors). */
+  restoreDraft: () => { annotations: CodeAnnotation[]; descriptionAnnotations: Annotation[]; commentAnnotations: CommentAnnotation[]; viewedFiles: string[]; autoViewSuppressed: string[]; patchChanged: boolean };
   getDraftGeneration: () => number;
   dismissDraft: () => void;
+  /** Call with the server's `draftState` after an in-place target switch.
+   *  Raises the generation counter to the new target's floor (so saves are
+   *  not rejected against an old tombstone there) and, when that target holds
+   *  a draft, loads it and hands its new items to `onDraftTargetMerge`. Until
+   *  that one load settles (success, failure, or a newer switch) autosave does
+   *  not write under the new target, so the switch cannot overwrite a draft
+   *  it has not read yet; nothing else ever waits. */
+  adoptDraftTarget: (state: CodeDraftTargetState | undefined) => void;
 }
 
 export function useCodeAnnotationDraft({
@@ -71,6 +123,8 @@ export function useCodeAnnotationDraft({
   autoViewSuppressed,
   isApiMode,
   submitted,
+  onDraftTargetMerge,
+  targetLoadTimeoutMs = TARGET_LOAD_TIMEOUT_MS,
 }: UseCodeAnnotationDraftOptions): UseCodeAnnotationDraftResult {
   const [draftBanner, setDraftBanner] = useState<{ count: number; viewedCount: number; timeAgo: string } | null>(null);
   const draftDataRef = useRef<DraftData | null>(null);
@@ -82,6 +136,43 @@ export function useCodeAnnotationDraft({
   // fresh/unengaged session (leave the server alone). Keyed on annotations only —
   // see the autosave effect for why viewedFiles must not count.
   const hasHadAnnotationsRef = useRef(false);
+  // In-place switch bookkeeping (#1590). Every adoptDraftTarget call starts a
+  // new switch id; a load that resolves for an older id is ignored. While the
+  // current switch's draft load is in flight, autosave skips writing (it
+  // would overwrite a draft it has not merged yet) and remembers that it did,
+  // so settling — success, failure, or supersede — always resumes saving.
+  const switchSeqRef = useRef(0);
+  const awaitingTargetLoadRef = useRef(false);
+  const skippedWhileAwaitingRef = useRef(false);
+  // The switched-onto target's draft could not be read (both attempts failed
+  // or timed out). Autosave then does not write under that target — it would
+  // overwrite a draft nobody has seen — and instead retries the read on each
+  // save attempt; a successful read (or the next switch) clears it.
+  const targetUnreadableRef = useRef(false);
+  // Kicks a read of the current target's draft; set by adoptDraftTarget.
+  const retryTargetLoadRef = useRef<(() => void) | null>(null);
+  const [saveNudge, setSaveNudge] = useState(0);
+  const loadTimeoutRef = useRef(targetLoadTimeoutMs);
+  loadTimeoutRef.current = targetLoadTimeoutMs;
+  const onMergeRef = useRef(onDraftTargetMerge);
+  onMergeRef.current = onDraftTargetMerge;
+  const latestRef = useRef({ annotations, descriptionAnnotations, commentAnnotations });
+  latestRef.current = { annotations, descriptionAnnotations, commentAnnotations };
+  // Ids the reviewer removed during this session, so a later merge offer
+  // (switching back onto a target saved before the removal) never brings a
+  // deleted comment back. Re-adding an id (undo) clears it again.
+  const removedIdsRef = useRef(new Set<string>());
+  const seenIdsRef = useRef(new Set<string>());
+  {
+    const nowIds = new Set<string>([
+      ...annotations.map((a) => a.id),
+      ...descriptionAnnotations.map((a) => a.id),
+      ...commentAnnotations.map((a) => a.id),
+    ]);
+    for (const id of seenIdsRef.current) if (!nowIds.has(id)) removedIdsRef.current.add(id);
+    for (const id of nowIds) removedIdsRef.current.delete(id);
+    seenIdsRef.current = nowIds;
+  }
 
   // Load draft on mount
   useEffect(() => {
@@ -141,6 +232,17 @@ export function useCodeAnnotationDraft({
     if (timerRef.current) clearTimeout(timerRef.current);
 
     timerRef.current = setTimeout(() => {
+      // The switched-onto target's draft is still loading: writing now would
+      // overwrite it unread. Settling the load re-runs this effect.
+      if (awaitingTargetLoadRef.current) {
+        skippedWhileAwaitingRef.current = true;
+        return;
+      }
+      if (targetUnreadableRef.current) {
+        skippedWhileAwaitingRef.current = true;
+        retryTargetLoadRef.current?.();
+        return;
+      }
       const draftGeneration = draftGenerationRef.current + 1;
       draftGenerationRef.current = draftGeneration;
 
@@ -171,7 +273,7 @@ export function useCodeAnnotationDraft({
     return () => {
       if (timerRef.current) clearTimeout(timerRef.current);
     };
-  }, [annotations, descriptionAnnotations, commentAnnotations, viewedFiles, autoViewSuppressed, isApiMode, submitted]);
+  }, [annotations, descriptionAnnotations, commentAnnotations, viewedFiles, autoViewSuppressed, isApiMode, submitted, saveNudge]);
 
   const restoreDraft = useCallback(() => {
     // Cancel any pending autosave so it can't fire with pre-restore state and
@@ -186,6 +288,7 @@ export function useCodeAnnotationDraft({
       commentAnnotations: data?.commentAnnotations ?? [],
       viewedFiles: data?.viewedFiles ?? [],
       autoViewSuppressed: data?.autoViewSuppressed ?? [],
+      patchChanged: data?.patchChanged === true,
     };
   }, []);
 
@@ -202,5 +305,95 @@ export function useCodeAnnotationDraft({
     getDraftTransport().remove(deletedGeneration, { keepalive: false }).catch(() => {});
   }, []);
 
-  return { draftBanner, restoreDraft, getDraftGeneration, dismissDraft };
+  // Unmount supersedes any in-flight target read, so a retry never fires
+  // after the page (or a test host) is gone.
+  useEffect(() => () => { switchSeqRef.current += 1; }, []);
+
+  const adoptDraftTarget = useCallback((state: CodeDraftTargetState | undefined) => {
+    if (!isApiMode) return;
+    // Every switch starts clean: a previous switch's load (if still in
+    // flight) is superseded, an unreadable-target block is lifted, and any
+    // write either of them held back resumes (under the new target).
+    const seq = ++switchSeqRef.current;
+    const resumeHeldWrite = () => {
+      if (skippedWhileAwaitingRef.current) {
+        skippedWhileAwaitingRef.current = false;
+        setSaveNudge((n) => n + 1);
+      }
+    };
+    awaitingTargetLoadRef.current = false;
+    targetUnreadableRef.current = false;
+    retryTargetLoadRef.current = null;
+    if (!state) { resumeHeldWrite(); return; }
+    const floor = readDraftGeneration(state.draftGeneration);
+    if (floor !== null) draftGenerationRef.current = Math.max(draftGenerationRef.current, floor);
+    if (!state.found) { resumeHeldWrite(); return; }
+
+    const applyDraft = (data: unknown, generation: number | null) => {
+      if (generation !== null) draftGenerationRef.current = Math.max(draftGenerationRef.current, generation);
+      const draft = data as DraftData | null;
+      if (!draft) return;
+      const loadedGeneration = readDraftGeneration(draft.draftGeneration);
+      if (loadedGeneration !== null) draftGenerationRef.current = Math.max(draftGenerationRef.current, loadedGeneration);
+      // Only what the session neither holds nor deleted: the target may
+      // carry this session's own blob from before a switch away and back.
+      const current = latestRef.current;
+      const skip = new Set<string>([
+        ...current.annotations.map((a) => a.id),
+        ...current.descriptionAnnotations.map((a) => a.id),
+        ...current.commentAnnotations.map((a) => a.id),
+        ...removedIdsRef.current,
+      ]);
+      const fresh = <T extends { id: string }>(items: T[] | undefined) =>
+        (Array.isArray(items) ? items : []).filter((item) => !skip.has(item.id));
+      const items: CodeDraftMergeItems = {
+        annotations: fresh(draft.codeAnnotations),
+        descriptionAnnotations: fresh(draft.descriptionAnnotations),
+        commentAnnotations: fresh(draft.commentAnnotations),
+        patchChanged: draft.patchChanged === true,
+      };
+      if (items.annotations.length + items.descriptionAnnotations.length + items.commentAnnotations.length > 0) {
+        onMergeRef.current?.(items);
+      }
+    };
+
+    // One read = up to two attempts, each bounded by TARGET_LOAD_TIMEOUT_MS so
+    // a hung GET takes the failure path instead of pausing autosave.
+    const read = () => {
+      if (switchSeqRef.current !== seq || awaitingTargetLoadRef.current) return;
+      awaitingTargetLoadRef.current = true;
+      const attempt = (remaining: number): void => {
+        if (switchSeqRef.current !== seq) return; // superseded or unmounted
+        withTimeout(getDraftTransport().load(), loadTimeoutRef.current)
+          .then(({ data, generation }) => {
+            if (switchSeqRef.current !== seq) return; // a newer switch owns the keys now
+            // A debounced save armed before the read settled captured the
+            // pre-merge state; drop it and save again from the merged render.
+            if (timerRef.current) {
+              clearTimeout(timerRef.current);
+              timerRef.current = null;
+              skippedWhileAwaitingRef.current = true;
+            }
+            applyDraft(data, generation);
+            awaitingTargetLoadRef.current = false;
+            targetUnreadableRef.current = false;
+            resumeHeldWrite();
+          })
+          .catch(() => {
+            if (switchSeqRef.current !== seq) return;
+            if (remaining > 0) { attempt(remaining - 1); return; }
+            // Still unreadable: never overwrite it blind. Autosave keeps
+            // running for the session and retries this read on its next
+            // save attempt; the next switch lifts the block.
+            awaitingTargetLoadRef.current = false;
+            targetUnreadableRef.current = true;
+          });
+      };
+      attempt(1);
+    };
+    retryTargetLoadRef.current = read;
+    read();
+  }, [isApiMode]);
+
+  return { draftBanner, restoreDraft, getDraftGeneration, dismissDraft, adoptDraftTarget };
 }

package/hooks/useModelCatalogs.ts

@@ -0,0 +1,116 @@
+import { useCallback, useEffect, useMemo, useRef, useState } from 'react';
+import {
+  CLAUDE_FALLBACK_MODELS,
+  CODEX_FALLBACK_MODELS,
+  type CatalogModel,
+} from '@plannotator/core/model-catalog';
+import type { AgentCapabilities } from '../types';
+
+// Picker helpers, re-exported for launch surfaces outside @plannotator/ui.
+export { effortSelectOptions, modelSelectOptions } from '@plannotator/core/model-catalog';
+
+/**
+ * Claude / Codex model catalogs for the agent launchers (review, Code Tour,
+ * Guided Review) — the SAME lists Ask AI shows. Each is the Ask AI provider's
+ * discovered list, fetched through `/api/ai/capabilities?activate=<id>` (which
+ * runs the provider's server-cached discovery). Nothing is fetched until a
+ * surface asks for one engine with `useModelCatalogs(...).load(engine)`, and
+ * only when that engine is installed, so opening a launcher spawns only the
+ * selected CLI. While a fetch is in flight the static fallback is shown with
+ * `settled: false`, so callers never reconcile saved picks against a list that
+ * is merely loading; a failed fetch settles on the fallback and is retried the
+ * next time a surface asks.
+ */
+export type CatalogEngine = 'claude' | 'codex';
+
+export interface ModelCatalog {
+  models: CatalogModel[];
+  settled: boolean;
+}
+
+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;
+}
+
+const AI_PROVIDER_ID: Record<CatalogEngine, string> = {
+  claude: 'claude-agent-sdk',
+  codex: 'codex-sdk',
+};
+
+export const FALLBACK_MODELS: Record<CatalogEngine, CatalogModel[]> = {
+  claude: CLAUDE_FALLBACK_MODELS,
+  codex: CODEX_FALLBACK_MODELS,
+};
+
+const isCatalogEngine = (engine: unknown): engine is CatalogEngine => engine === 'claude' || engine === 'codex';
+
+// 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[]>>();
+
+export function loadModelCatalog(engine: CatalogEngine): Promise<CatalogModel[]> {
+  let load = loads.get(engine);
+  if (!load) {
+    const id = AI_PROVIDER_ID[engine];
+    const failed = () => {
+      loads.delete(engine);
+      return FALLBACK_MODELS[engine];
+    };
+    load = fetch(`/api/ai/capabilities?activate=${encodeURIComponent(id)}`)
+      .then((res) => (res.ok ? res.json() : null))
+      .then((data) => {
+        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();
+        // The server answers 200 with its static fallback when discovery
+        // 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[];
+      })
+      .catch(failed);
+    loads.set(engine, load);
+  }
+  return load;
+}
+
+/** Test seam: forget cached catalogs. */
+export function __resetModelCatalogsForTests(): void {
+  loads.clear();
+}
+
+export function useModelCatalogs(capabilities: AgentCapabilities | null): ModelCatalogs {
+  const available = (id: CatalogEngine) =>
+    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 mounted = useRef(true);
+  useEffect(() => {
+    mounted.current = true;
+    return () => {
+      mounted.current = false;
+    };
+  }, []);
+
+  const load = useCallback(
+    (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 }));
+      });
+    },
+    [claudeOn, codexOn],
+  );
+
+  return useMemo(
+    () => ({
+      claude: { models: loaded.claude ?? FALLBACK_MODELS.claude, settled: !!loaded.claude },
+      codex: { models: loaded.codex ?? FALLBACK_MODELS.codex, settled: !!loaded.codex },
+      load,
+    }),
+    [loaded, load],
+  );
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@plannotator/ui",
-  "version": "0.45.1",
+  "version": "0.46.0",
   "type": "module",
   "exports": {
     "./components/*": "./components/*.tsx",
@@ -76,7 +76,7 @@
     "@lezer/highlight": "^1.2.3",
     "@pierre/diffs": "1.3.6",
     "@plannotator/atomic-editor": "^0.8.0",
-    "@plannotator/core": "0.25.5",
+    "@plannotator/core": "0.25.6",
     "@plannotator/markdown-editor": "^0.4.0",
     "@plannotator/web-highlighter": "^0.8.1",
     "@tanstack/react-table": "^8.21.3",