@plannotator/ui 0.22.0

package/hooks/useArchive.ts

@@ -0,0 +1,171 @@
+/**
+ * Archive Hook
+ *
+ * Manages state and handlers for the archive browser — both standalone
+ * archive mode and in-session browsing via the sidebar tab.
+ */
+
+import { useState, useRef, useMemo, useCallback } from "react";
+import type { ArchivedPlan } from "@plannotator/core/storage-types";
+import type { UseLinkedDocReturn } from "./useLinkedDoc";
+import type { ViewerHandle } from "../components/Viewer";
+import type { Annotation } from "../types";
+import { getPlanSaveSettings } from "../utils/planSave";
+
+export interface UseArchiveOptions {
+  markdown: string;
+  viewerRef: React.RefObject<ViewerHandle | null>;
+  linkedDocHook: UseLinkedDocReturn;
+  setMarkdown: (md: string) => void;
+  setAnnotations: (anns: Annotation[]) => void;
+  setSelectedAnnotationId: (id: string | null) => void;
+  setSubmitted: (s: "approved" | "denied" | null) => void;
+}
+
+export interface UseArchiveReturn {
+  /** Whether running in standalone archive mode */
+  archiveMode: boolean;
+  /** List of archived plans */
+  plans: ArchivedPlan[];
+  /** Currently selected archive filename */
+  selectedFile: string | null;
+  /** Whether the plan list is loading */
+  isLoading: boolean;
+  /** Info about the currently selected archive plan */
+  currentInfo: { status: ArchivedPlan["status"]; timestamp: string; title: string } | null;
+  /** Initialize archive state from /api/plan response */
+  init: (plans: ArchivedPlan[]) => void;
+  /** Select an archive plan to view */
+  select: (filename: string) => Promise<void>;
+  /** Lazy-fetch the plan list (for in-session mode) */
+  fetchPlans: () => Promise<void>;
+  /** Close the archive browser */
+  done: () => Promise<void>;
+  /** Copy plan content to clipboard (strips annotations) */
+  copy: () => void;
+  /** Clear the selected file (used by linked doc back) */
+  clearSelection: () => void;
+}
+
+export function useArchive(options: UseArchiveOptions): UseArchiveReturn {
+  const {
+    markdown,
+    viewerRef,
+    linkedDocHook,
+    setMarkdown,
+    setAnnotations,
+    setSelectedAnnotationId,
+    setSubmitted,
+  } = options;
+
+  const [archiveMode, setArchiveMode] = useState(false);
+  const [plans, setPlans] = useState<ArchivedPlan[]>([]);
+  const [selectedFile, setSelectedFile] = useState<string | null>(null);
+  const [isLoading, setIsLoading] = useState(false);
+  const hasFetched = useRef(false);
+
+  const customPath = useMemo(() => getPlanSaveSettings().customPath || undefined, []);
+
+  const currentInfo = useMemo(() => {
+    if (!selectedFile) return null;
+    const plan = plans.find(p => p.filename === selectedFile);
+    return plan ? { status: plan.status, timestamp: plan.timestamp, title: plan.title } : null;
+  }, [selectedFile, plans]);
+
+  const init = useCallback((archivePlans: ArchivedPlan[]) => {
+    setArchiveMode(true);
+    setPlans(archivePlans);
+    if (archivePlans.length > 0) {
+      setSelectedFile(archivePlans[0].filename);
+    }
+  }, []);
+
+  const select = useCallback(async (filename: string) => {
+    try {
+      const params = new URLSearchParams({ filename });
+      if (customPath) params.set("customPath", customPath);
+      const res = await fetch(`/api/archive/plan?${params}`);
+      if (!res.ok) return;
+      const data = await res.json() as { markdown: string; filepath: string };
+
+      if (archiveMode) {
+        // Standalone: direct swap
+        viewerRef.current?.clearAllHighlights();
+        setMarkdown(data.markdown);
+        setAnnotations([]);
+        setSelectedAnnotationId(null);
+        setSelectedFile(filename);
+      } else {
+        // In-session: use linked doc overlay
+        const buildUrl = (f: string) => {
+          const p = new URLSearchParams({ filename: f });
+          if (customPath) p.set("customPath", customPath);
+          return `/api/archive/plan?${p}`;
+        };
+        linkedDocHook.open(filename, buildUrl, "archive");
+        setSelectedFile(filename);
+      }
+    } catch { /* ignore */ }
+  }, [archiveMode, customPath, viewerRef, setMarkdown, setAnnotations, setSelectedAnnotationId, linkedDocHook]);
+
+  const fetchPlans = useCallback(async () => {
+    if (hasFetched.current || isLoading) return;
+    hasFetched.current = true;
+    setIsLoading(true);
+    try {
+      const params = new URLSearchParams();
+      if (customPath) params.set("customPath", customPath);
+      const qs = params.toString();
+      const res = await fetch(`/api/archive/plans${qs ? `?${qs}` : ""}`);
+      if (!res.ok) return;
+      const data = await res.json() as { plans: ArchivedPlan[] };
+      setPlans(data.plans);
+      // In standalone archive mode, auto-select and load the first plan
+      // so the viewer reflects the customPath results, not stale server data
+      if (archiveMode && data.plans.length > 0) {
+        const first = data.plans[0].filename;
+        setSelectedFile(first);
+        const fetchParams = new URLSearchParams({ filename: first });
+        if (customPath) fetchParams.set("customPath", customPath);
+        const planRes = await fetch(`/api/archive/plan?${fetchParams}`);
+        if (planRes.ok) {
+          const planData = await planRes.json() as { markdown: string };
+          setMarkdown(planData.markdown);
+        }
+      }
+    } catch {
+      hasFetched.current = false;
+    } finally {
+      setIsLoading(false);
+    }
+  }, [archiveMode, customPath, isLoading, setMarkdown]);
+
+  const done = useCallback(async () => {
+    try {
+      await fetch("/api/done", { method: "POST" });
+      setSubmitted("approved");
+    } catch { /* ignore */ }
+  }, [setSubmitted]);
+
+  const copy = useCallback(() => {
+    navigator.clipboard.writeText(markdown);
+  }, [markdown]);
+
+  const clearSelection = useCallback(() => {
+    setSelectedFile(null);
+  }, []);
+
+  return {
+    archiveMode,
+    plans,
+    selectedFile,
+    isLoading,
+    currentInfo,
+    init,
+    select,
+    fetchPlans,
+    done,
+    copy,
+    clearSelection,
+  };
+}

package/hooks/useAutoClose.ts

@@ -0,0 +1,104 @@
+import { useState, useEffect, useCallback } from 'react';
+import { getAutoCloseDelay, setAutoCloseDelay } from '../utils/storage';
+
+/**
+ * Phases of the auto-close lifecycle after a form submission.
+ *
+ * - idle:        nothing submitted yet
+ * - counting:    countdown is ticking (seconds remaining in `remaining`)
+ * - prompt:      auto-close is disabled; offer the user a checkbox to opt in
+ * - closed:      window.close() succeeded (terminal state)
+ * - closeFailed: window.close() was blocked by the browser
+ */
+type AutoClosePhase =
+  | { phase: 'idle' }
+  | { phase: 'counting'; remaining: number }
+  | { phase: 'prompt' }
+  | { phase: 'closed' }
+  | { phase: 'closeFailed' };
+
+interface UseAutoCloseReturn {
+  state: AutoClosePhase;
+  /** User opted in via the checkbox — persist "3s" and start countdown. */
+  enableAndStart: () => void;
+}
+
+type GlimpseWindow = Window & {
+  glimpse?: {
+    close?: () => void;
+  };
+};
+
+function requestGlimpseClose(): boolean {
+  const glimpseClose = (window as GlimpseWindow).glimpse?.close;
+  if (typeof glimpseClose === 'function') {
+    glimpseClose();
+    return true;
+  }
+
+  if (window.parent && window.parent !== window) {
+    window.parent.postMessage({ __plannotator_glimpse_close: true }, '*');
+    return true;
+  }
+
+  return false;
+}
+
+function tryClose(onFail: () => void): void {
+  const requestedNativeClose = requestGlimpseClose();
+  if (requestedNativeClose) {
+    return;
+  }
+
+  window.close();
+  // window.close() is silently ignored when the tab wasn't opened by script.
+  // Check after a short delay whether we're still alive.
+  setTimeout(() => {
+    if (!window.closed) onFail();
+  }, 300);
+}
+
+/**
+ * Manages the auto-close countdown that runs after a submission overlay appears.
+ *
+ * @param active - pass `true` once the overlay should appear (i.e. form was submitted)
+ */
+export function useAutoClose(active: boolean): UseAutoCloseReturn {
+  const [state, setState] = useState<AutoClosePhase>({ phase: 'idle' });
+
+  // On activation, read persisted delay and transition to the right phase.
+  useEffect(() => {
+    if (!active) return;
+
+    const delay = getAutoCloseDelay();
+    if (delay === '0') {
+      tryClose(() => setState({ phase: 'closeFailed' }));
+      setState({ phase: 'closed' });
+    } else if (delay !== 'off') {
+      setState({ phase: 'counting', remaining: Number(delay) });
+    } else {
+      setState({ phase: 'prompt' });
+    }
+  }, [active]);
+
+  // Tick the countdown once per second.
+  useEffect(() => {
+    if (state.phase !== 'counting') return;
+    if (state.remaining <= 0) {
+      tryClose(() => setState({ phase: 'closeFailed' }));
+      return;
+    }
+    const timer = setTimeout(
+      () => setState((prev) => (prev.phase === 'counting' ? { phase: 'counting', remaining: prev.remaining - 1 } : prev)),
+      1000,
+    );
+    return () => clearTimeout(timer);
+  }, [state]);
+
+  const enableAndStart = useCallback(() => {
+    setAutoCloseDelay('3');
+    setState({ phase: 'counting', remaining: 3 });
+  }, []);
+
+  return { state, enableAndStart };
+}

package/hooks/useCodeAnnotationDraft.ts

@@ -0,0 +1,194 @@
+/**
+ * Auto-save code review annotation drafts to the server.
+ *
+ * Similar to useAnnotationDraft but stores CodeAnnotation[] directly
+ * (they're already compact — no tuple conversion needed).
+ */
+
+import { useState, useEffect, useCallback, useRef } from 'react';
+import type { CodeAnnotation, Annotation, CommentAnnotation } from '../types';
+import { getDraftTransport } from './useAnnotationDraft';
+
+const DEBOUNCE_MS = 500;
+
+interface DraftData {
+  codeAnnotations: CodeAnnotation[];
+  descriptionAnnotations?: Annotation[];
+  commentAnnotations?: CommentAnnotation[];
+  viewedFiles?: string[];
+  draftGeneration?: number;
+  ts: number;
+}
+
+interface MissingDraftData {
+  found?: false;
+  draftGeneration?: number;
+}
+
+function readDraftGeneration(value: unknown): number | null {
+  return typeof value === 'number' && Number.isInteger(value) && value >= 0 ? value : null;
+}
+
+function formatTimeAgo(ts: number): string {
+  const seconds = Math.floor((Date.now() - ts) / 1000);
+  if (seconds < 60) return 'just now';
+  const minutes = Math.floor(seconds / 60);
+  if (minutes < 60) return `${minutes} minute${minutes !== 1 ? 's' : ''} ago`;
+  const hours = Math.floor(minutes / 60);
+  if (hours < 24) return `${hours} hour${hours !== 1 ? 's' : ''} ago`;
+  const days = Math.floor(hours / 24);
+  return `${days} day${days !== 1 ? 's' : ''} ago`;
+}
+
+interface UseCodeAnnotationDraftOptions {
+  annotations: CodeAnnotation[];
+  descriptionAnnotations?: Annotation[];
+  commentAnnotations?: CommentAnnotation[];
+  viewedFiles: Set<string>;
+  isApiMode: boolean;
+  submitted: boolean;
+}
+
+interface UseCodeAnnotationDraftResult {
+  draftBanner: { count: number; viewedCount: number; timeAgo: string } | null;
+  restoreDraft: () => { annotations: CodeAnnotation[]; descriptionAnnotations: Annotation[]; commentAnnotations: CommentAnnotation[]; viewedFiles: string[] };
+  getDraftGeneration: () => number;
+  dismissDraft: () => void;
+}
+
+export function useCodeAnnotationDraft({
+  annotations,
+  descriptionAnnotations = [],
+  commentAnnotations = [],
+  viewedFiles,
+  isApiMode,
+  submitted,
+}: 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);
+  // 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 —
+  // see the autosave effect for why viewedFiles must not count.
+  const hasHadAnnotationsRef = useRef(false);
+
+  // Load draft on mount
+  useEffect(() => {
+    if (!isApiMode) return;
+
+    getDraftTransport().load()
+      .then(({ data, generation }) => {
+        if (generation !== null) {
+          draftGenerationRef.current = Math.max(draftGenerationRef.current, generation);
+        }
+        return data as DraftData | null;
+      })
+      .then((data: DraftData | null) => {
+        const generation = readDraftGeneration(data?.draftGeneration);
+        if (generation !== null) {
+          draftGenerationRef.current = Math.max(draftGenerationRef.current, generation);
+        }
+        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;
+        if (annotationCount > 0 || viewedCount > 0) {
+          draftDataRef.current = data;
+          setDraftBanner({
+            count: annotationCount,
+            viewedCount,
+            timeAgo: formatTimeAgo(data?.ts || 0),
+          });
+        }
+        hasMountedRef.current = true;
+      })
+      .catch(() => {
+        hasMountedRef.current = true;
+      });
+  }, [isApiMode]);
+
+  // Debounced auto-save on annotation/viewed changes
+  useEffect(() => {
+    if (!isApiMode || submitted) return;
+    if (!hasMountedRef.current) return;
+
+    // Track engagement on USER-AUTHORED annotations only. Two things that arrive
+    // without user action must NOT count as "had content", or a later empty state
+    // would look like the user deleted everything and wrongly delete the draft:
+    //   - viewedFiles are seeded from GitHub's already-viewed state on mount
+    //     (review App.tsx) before the user does anything.
+    //   - external/SSE annotations (source-tagged, e.g. an eslint plugin) arrive
+    //     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;
+    // 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).
+    if (isEmpty && !hasHadAnnotationsRef.current) return;
+
+    if (timerRef.current) clearTimeout(timerRef.current);
+
+    timerRef.current = setTimeout(() => {
+      const draftGeneration = draftGenerationRef.current + 1;
+      draftGenerationRef.current = draftGeneration;
+
+      if (isEmpty) {
+        // The user cleared everything (#948). Delete the draft with a generation
+        // tombstone so it can't resurface on refresh and a late save can't revive
+        // it. Mirrors useAnnotationDraft.persistNow — routed through the draft
+        // transport seam so a host backend tombstones its own stored draft too.
+        getDraftTransport().remove(draftGeneration, { keepalive: false }).catch(() => {});
+        return;
+      }
+
+      const payload: DraftData = {
+        codeAnnotations: annotations,
+        descriptionAnnotations,
+        commentAnnotations,
+        viewedFiles: [...viewedFiles],
+        draftGeneration,
+        ts: Date.now(),
+      };
+
+      getDraftTransport().save(payload, { keepalive: false }).catch(() => {});
+    }, DEBOUNCE_MS);
+
+    return () => {
+      if (timerRef.current) clearTimeout(timerRef.current);
+    };
+  }, [annotations, descriptionAnnotations, commentAnnotations, viewedFiles, isApiMode, submitted]);
+
+  const restoreDraft = useCallback(() => {
+    // Cancel any pending autosave so it can't fire with pre-restore state and
+    // overwrite what we're about to restore.
+    if (timerRef.current) clearTimeout(timerRef.current);
+    const data = draftDataRef.current;
+    setDraftBanner(null);
+    draftDataRef.current = null;
+    return {
+      annotations: data?.codeAnnotations ?? [],
+      descriptionAnnotations: data?.descriptionAnnotations ?? [],
+      commentAnnotations: data?.commentAnnotations ?? [],
+      viewedFiles: data?.viewedFiles ?? [],
+    };
+  }, []);
+
+  const getDraftGeneration = useCallback(() => draftGenerationRef.current + 1, []);
+
+  const dismissDraft = useCallback(() => {
+    // Cancel any pending autosave so a late save can't revive the draft the user
+    // just dismissed.
+    if (timerRef.current) clearTimeout(timerRef.current);
+    const deletedGeneration = draftGenerationRef.current + 1;
+    draftGenerationRef.current = deletedGeneration;
+    setDraftBanner(null);
+    draftDataRef.current = null;
+    getDraftTransport().remove(deletedGeneration, { keepalive: false }).catch(() => {});
+  }, []);
+
+  return { draftBanner, restoreDraft, getDraftGeneration, dismissDraft };
+}

package/hooks/useCodeFilePopout.ts

@@ -0,0 +1 @@
+export { useCodeFilePopout, type UseCodeFilePopoutReturn } from "./pfm/useCodeFilePopout";

package/hooks/useDismissOnOutsideAndEscape.ts

@@ -0,0 +1,50 @@
+import { useEffect } from "react";
+
+export function useDismissOnOutsideAndEscape({
+  enabled,
+  ref,
+  onDismiss,
+}: {
+  enabled: boolean;
+  ref: React.RefObject<HTMLElement | null>;
+  onDismiss: () => void;
+}) {
+  useEffect(() => {
+    if (!enabled) return;
+
+    const handleMouseDown = (event: MouseEvent) => {
+      // Don't dismiss on multi-click (double-click, triple-click). These
+      // are part of an active selection gesture — the web-highlighter
+      // CREATE handler already cleans up any stale pending highlight when
+      // a new selection commits.  Dismissing here triggers DOM mutations
+      // (mark removal + text-node normalisation) that reset the browser's
+      // click-count tracking and prevent the triple-click paragraph
+      // selection from ever firing.
+      // Note: we use mousedown (not pointerdown) because MouseEvent.detail
+      // is spec-guaranteed to carry the click count, whereas the Pointer
+      // Events spec says PointerEvent.detail SHOULD be 0.
+      if (event.detail >= 2) return;
+
+      const target = event.target as Node | null;
+      if (!target) return;
+      if (ref.current && ref.current.contains(target)) {
+        return;
+      }
+      onDismiss();
+    };
+
+    const handleKeyDown = (event: KeyboardEvent) => {
+      if (event.key === "Escape") {
+        onDismiss();
+      }
+    };
+
+    document.addEventListener("mousedown", handleMouseDown, true);
+    window.addEventListener("keydown", handleKeyDown);
+
+    return () => {
+      document.removeEventListener("mousedown", handleMouseDown, true);
+      window.removeEventListener("keydown", handleKeyDown);
+    };
+  }, [enabled, ref, onDismiss]);
+}

package/hooks/useDraggable.ts

@@ -0,0 +1,108 @@
+import { useState, useRef, useCallback, useEffect } from 'react';
+
+const DRAG_THRESHOLD = 3;
+const VISIBLE_MIN = 50;
+
+interface DragPosition {
+  top: number;
+  left: number;
+}
+
+/**
+ * Makes a fixed-position element draggable by its header/handle.
+ * Reads the element's actual rendered position on drag start via getBoundingClientRect,
+ * so it works regardless of CSS transforms (flipAbove, translateX, etc.).
+ *
+ * @param elementRef - Ref to the positioned element (the popover/toolbar container)
+ */
+export function useDraggable(elementRef: React.RefObject<HTMLElement | null>) {
+  const [dragPosition, setDragPosition] = useState<DragPosition | null>(null);
+  const [isDragging, setIsDragging] = useState(false);
+  const [wasDragged, setWasDragged] = useState(false);
+
+  const startPointerRef = useRef({ x: 0, y: 0 });
+  const startElRef = useRef({ top: 0, left: 0 });
+  const thresholdMetRef = useRef(false);
+
+  const reset = useCallback(() => {
+    setDragPosition(null);
+    setIsDragging(false);
+    setWasDragged(false);
+  }, []);
+
+  // Document-level pointermove/pointerup while dragging
+  useEffect(() => {
+    if (!isDragging) return;
+
+    const onMove = (e: PointerEvent) => {
+      const dx = e.clientX - startPointerRef.current.x;
+      const dy = e.clientY - startPointerRef.current.y;
+
+      if (!thresholdMetRef.current) {
+        if (Math.abs(dx) < DRAG_THRESHOLD && Math.abs(dy) < DRAG_THRESHOLD) return;
+        thresholdMetRef.current = true;
+      }
+
+      // Clamp to keep at least VISIBLE_MIN px visible on screen
+      const top = Math.max(
+        -((elementRef.current?.offsetHeight ?? 0) - VISIBLE_MIN),
+        Math.min(startElRef.current.top + dy, window.innerHeight - VISIBLE_MIN),
+      );
+      const left = Math.max(
+        -((elementRef.current?.offsetWidth ?? 0) - VISIBLE_MIN),
+        Math.min(startElRef.current.left + dx, window.innerWidth - VISIBLE_MIN),
+      );
+
+      setDragPosition({ top, left });
+    };
+
+    const onUp = () => {
+      setIsDragging(false);
+      if (thresholdMetRef.current) {
+        setWasDragged(true);
+      }
+    };
+
+    document.addEventListener('pointermove', onMove);
+    document.addEventListener('pointerup', onUp);
+    return () => {
+      document.removeEventListener('pointermove', onMove);
+      document.removeEventListener('pointerup', onUp);
+    };
+  }, [isDragging, elementRef]);
+
+  const onPointerDown = useCallback(
+    (e: React.PointerEvent) => {
+      // Only primary button (left click / single touch)
+      if (e.button !== 0) return;
+      // Don't drag if clicking on an interactive element inside the handle
+      const target = e.target as HTMLElement;
+      if (target.closest('button, a, input, textarea, select')) return;
+
+      const el = elementRef.current;
+      if (!el) return;
+
+      const rect = el.getBoundingClientRect();
+      startPointerRef.current = { x: e.clientX, y: e.clientY };
+      startElRef.current = { top: rect.top, left: rect.left };
+      thresholdMetRef.current = false;
+      setIsDragging(true);
+    },
+    [elementRef],
+  );
+
+  return {
+    dragPosition,
+    isDragging,
+    wasDragged,
+    reset,
+    dragHandleProps: {
+      onPointerDown,
+      style: {
+        cursor: isDragging ? 'grabbing' : 'grab',
+        userSelect: 'none' as const,
+        touchAction: 'none' as const,
+      },
+    },
+  };
+}

package/hooks/useEditorAnnotations.ts

@@ -0,0 +1,64 @@
+import { useState, useEffect, useCallback, useRef } from 'react';
+import type { EditorAnnotation } from '../types';
+
+const POLL_INTERVAL = 500;
+const IS_VSCODE = typeof window !== 'undefined' && (window as any).__PLANNOTATOR_VSCODE === true;
+
+interface UseEditorAnnotationsReturn {
+  editorAnnotations: EditorAnnotation[];
+  deleteEditorAnnotation: (id: string) => void;
+}
+
+/**
+ * Polls the server for editor annotations created by the VS Code extension.
+ *
+ * Only activates when running inside a VS Code webview (detected via
+ * window.__PLANNOTATOR_VSCODE set by the theme bridge). In browser/shared URL
+ * contexts, returns an empty array with zero network cost.
+ */
+export function useEditorAnnotations(): UseEditorAnnotationsReturn {
+  const [annotations, setAnnotations] = useState<EditorAnnotation[]>([]);
+  const intervalRef = useRef<ReturnType<typeof setInterval> | null>(null);
+
+  const fetchAnnotations = useCallback(async () => {
+    try {
+      const res = await fetch('/api/editor-annotations');
+      if (!res.ok) return;
+      const data = await res.json();
+      const incoming: EditorAnnotation[] = data.annotations ?? [];
+      setAnnotations((prev) => {
+        if (prev.length === incoming.length && prev.every((a, i) => a.id === incoming[i].id)) return prev;
+        return incoming;
+      });
+    } catch {
+      // Silently fail — next poll will retry
+    }
+  }, []);
+
+  useEffect(() => {
+    if (!IS_VSCODE) return;
+
+    // Initial fetch + start polling
+    fetchAnnotations();
+    intervalRef.current = setInterval(fetchAnnotations, POLL_INTERVAL);
+
+    return () => {
+      if (intervalRef.current) {
+        clearInterval(intervalRef.current);
+        intervalRef.current = null;
+      }
+    };
+  }, [fetchAnnotations]);
+
+  const deleteEditorAnnotation = useCallback(async (id: string) => {
+    if (!IS_VSCODE) return;
+    try {
+      await fetch(`/api/editor-annotation?id=${encodeURIComponent(id)}`, { method: 'DELETE' });
+      setAnnotations((prev) => prev.filter((a) => a.id !== id));
+    } catch {
+      // Silently fail — next poll will reconcile
+    }
+  }, []);
+
+  return { editorAnnotations: annotations, deleteEditorAnnotation };
+}