@plannotator/ui 0.53.1 → 0.55.0

package/hooks/useCodeAnnotationDraft.ts

@@ -7,12 +7,18 @@
 
 import { useState, useEffect, useCallback, useRef } from 'react';
 import type { CodeAnnotation, Annotation, CommentAnnotation } from '../types';
-import { getDraftTransport } from './useAnnotationDraft';
+import { getDraftTransport, type DraftTransport } 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;
 
+/** A target-bound transport refuses to write into a different review. The host
+ * must refresh/adopt a target before saving can resume; retrying cannot fix it. */
+export class DraftTargetChangedError extends Error {
+  constructor() { super('Review draft target changed'); }
+}
+
 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);
@@ -41,8 +47,8 @@ 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
+   * Set by the review server (never by the client) when a draft is served
+   * through its 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;
@@ -65,6 +71,8 @@ function formatTimeAgo(ts: number): string {
 }
 
 interface UseCodeAnnotationDraftOptions {
+  /** Optional target-bound transport; the configured host transport is the default. */
+  transport?: DraftTransport;
   annotations: CodeAnnotation[];
   descriptionAnnotations?: Annotation[];
   commentAnnotations?: CommentAnnotation[];
@@ -101,6 +109,10 @@ export interface CodeDraftTargetState {
 }
 
 interface UseCodeAnnotationDraftResult {
+  /** Flush pending edits, then hold autosave until adoptDraftTarget resumes it. */
+  flushBeforeSwitch: () => Promise<void>;
+  /** Keep unsaved annotations in memory and offer an in-place refresh. */
+  draftTargetChanged: boolean;
   draftBanner: { count: number; viewedCount: number; timeAgo: string } | null;
   /** `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). */
@@ -114,10 +126,11 @@ interface UseCodeAnnotationDraftResult {
    *  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;
+  adoptDraftTarget: (state: CodeDraftTargetState | undefined, transport?: DraftTransport) => void;
 }
 
 export function useCodeAnnotationDraft({
+  transport: transportOverride,
   annotations,
   descriptionAnnotations = [],
   commentAnnotations = [],
@@ -129,6 +142,14 @@ export function useCodeAnnotationDraft({
   targetLoadTimeoutMs = TARGET_LOAD_TIMEOUT_MS,
   persistViewedFiles = true,
 }: UseCodeAnnotationDraftOptions): UseCodeAnnotationDraftResult {
+  const transport = transportOverride ?? getDraftTransport();
+  const transportRef = useRef(transport);
+  transportRef.current = transport;
+  const pendingSaveRef = useRef<(() => Promise<void>) | null>(null);
+  const savingRef = useRef<Promise<void> | null>(null);
+  const switchPausedRef = useRef(false);
+  const [draftTargetChanged, setDraftTargetChanged] = useState(false);
+  const targetChangedRef = useRef(false);
   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);
@@ -147,6 +168,14 @@ export function useCodeAnnotationDraft({
   // 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 reportTargetChanged = (error: unknown, seq: number): boolean => {
+    if (!(error instanceof DraftTargetChangedError)) return false;
+    if (seq === switchSeqRef.current) {
+      targetChangedRef.current = true;
+      setDraftTargetChanged(true);
+    }
+    return true;
+  };
   const awaitingTargetLoadRef = useRef(false);
   const skippedWhileAwaitingRef = useRef(false);
   // The switched-onto target's draft could not be read (both attempts failed
@@ -182,15 +211,19 @@ export function useCodeAnnotationDraft({
   // Load draft on mount
   useEffect(() => {
     if (!isApiMode) return;
+    const seq = switchSeqRef.current;
+    let cancelled = false;
 
-    getDraftTransport().load()
+    transportRef.current.load()
       .then(({ data, generation }) => {
+        if (cancelled || seq !== switchSeqRef.current) return null;
         if (generation !== null) {
           draftGenerationRef.current = Math.max(draftGenerationRef.current, generation);
         }
         return data as DraftData | null;
       })
       .then((data: DraftData | null) => {
+        if (cancelled || seq !== switchSeqRef.current) return;
         // 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;
@@ -212,9 +245,13 @@ export function useCodeAnnotationDraft({
         }
         hasMountedRef.current = true;
       })
-      .catch(() => {
-        hasMountedRef.current = true;
+      .catch((error) => {
+        if (!cancelled && seq === switchSeqRef.current) {
+          reportTargetChanged(error, seq);
+          hasMountedRef.current = true;
+        }
       });
+    return () => { cancelled = true; };
   }, [isApiMode]);
 
   useEffect(() => {
@@ -248,7 +285,9 @@ export function useCodeAnnotationDraft({
 
     if (timerRef.current) clearTimeout(timerRef.current);
 
-    timerRef.current = setTimeout(() => {
+    const seq = switchSeqRef.current;
+    const persist = async () => {
+      if (targetChangedRef.current) return;
       // 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) {
@@ -268,7 +307,7 @@ export function useCodeAnnotationDraft({
         // 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(() => {});
+        await transport.remove(draftGeneration, { keepalive: false });
         return;
       }
 
@@ -284,18 +323,48 @@ export function useCodeAnnotationDraft({
         ts: Date.now(),
       };
 
-      getDraftTransport().save(payload, { keepalive: false }).catch(() => {});
+      await transport.save(payload, { keepalive: false });
+    };
+    const save = async () => {
+      try { await persist(); } catch (error) {
+        reportTargetChanged(error, seq);
+        throw error;
+      }
+    };
+    pendingSaveRef.current = save;
+    timerRef.current = setTimeout(() => {
+      if (switchPausedRef.current) return;
+      pendingSaveRef.current = null;
+      savingRef.current = save();
+      savingRef.current.catch(() => {});
     }, DEBOUNCE_MS);
 
     return () => {
       if (timerRef.current) clearTimeout(timerRef.current);
+      pendingSaveRef.current = null;
     };
-  }, [annotations, descriptionAnnotations, commentAnnotations, viewedFiles, autoViewSuppressed, isApiMode, submitted, saveNudge, persistViewedFiles]);
+  }, [annotations, descriptionAnnotations, commentAnnotations, viewedFiles, autoViewSuppressed, isApiMode, submitted, saveNudge, persistViewedFiles, transport]);
+
+  const flushBeforeSwitch = useCallback(async () => {
+    switchPausedRef.current = true;
+    if (timerRef.current) clearTimeout(timerRef.current);
+    try {
+      // Persistence is best-effort: a rejected earlier write must neither
+      // block navigation nor skip a newer edit still waiting on debounce.
+      await savingRef.current?.catch(() => {});
+      const pending = pendingSaveRef.current;
+      pendingSaveRef.current = null;
+      if (pending) await pending().catch(() => {});
+    } finally {
+      savingRef.current = null;
+    }
+  }, []);
 
   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);
+    pendingSaveRef.current = null;
     const data = draftDataRef.current;
     setDraftBanner(null);
     draftDataRef.current = null;
@@ -315,19 +384,43 @@ export function useCodeAnnotationDraft({
     // Cancel any pending autosave so a late save can't revive the draft the user
     // just dismissed.
     if (timerRef.current) clearTimeout(timerRef.current);
+    pendingSaveRef.current = null;
     const deletedGeneration = draftGenerationRef.current + 1;
     draftGenerationRef.current = deletedGeneration;
     setDraftBanner(null);
     draftDataRef.current = null;
-    getDraftTransport().remove(deletedGeneration, { keepalive: false }).catch(() => {});
+    const seq = switchSeqRef.current;
+    transportRef.current.remove(deletedGeneration, { keepalive: false }).catch(error => {
+      reportTargetChanged(error, seq);
+    });
   }, []);
 
   // 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) => {
+  const adoptDraftTarget = useCallback((state: CodeDraftTargetState | undefined, nextTransport?: DraftTransport) => {
     if (!isApiMode) return;
+    // undefined also resumes a FAILED switch, which has not repaired a
+    // target mismatch. Only an applied server response may clear the notice.
+    if (state) {
+      targetChangedRef.current = false;
+      setDraftTargetChanged(false);
+    }
+    if (switchPausedRef.current) {
+      switchPausedRef.current = false;
+      setSaveNudge(n => n + 1);
+    }
+    // A failed/superseded request did not adopt another target. Its current
+    // draft may still be loading (or unreadable); retain that write protection.
+    if (!state) return;
+    // An applied switch supersedes the page-load read (its seq guard drops
+    // the result), so it must open autosave itself. A failed/superseded
+    // switch must not: the page-load read may still be in flight, and
+    // saving before it settles could overwrite a draft the banner has not
+    // offered yet.
+    hasMountedRef.current = true;
+    const targetTransport = nextTransport ?? transportRef.current;
     // 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).
@@ -341,7 +434,6 @@ export function useCodeAnnotationDraft({
     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; }
@@ -381,7 +473,7 @@ export function useCodeAnnotationDraft({
       awaitingTargetLoadRef.current = true;
       const attempt = (remaining: number): void => {
         if (switchSeqRef.current !== seq) return; // superseded or unmounted
-        withTimeout(getDraftTransport().load(), loadTimeoutRef.current)
+        withTimeout(targetTransport.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
@@ -396,8 +488,12 @@ export function useCodeAnnotationDraft({
             targetUnreadableRef.current = false;
             resumeHeldWrite();
           })
-          .catch(() => {
+          .catch((error) => {
             if (switchSeqRef.current !== seq) return;
+            if (reportTargetChanged(error, seq)) {
+              awaitingTargetLoadRef.current = false;
+              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
@@ -412,5 +508,5 @@ export function useCodeAnnotationDraft({
     read();
   }, [isApiMode]);
 
-  return { draftBanner, restoreDraft, getDraftGeneration, dismissDraft, adoptDraftTarget };
+  return { draftBanner, draftTargetChanged, restoreDraft, getDraftGeneration, dismissDraft, adoptDraftTarget, flushBeforeSwitch };
 }

package/hooks/useCookieHostSetting.ts

@@ -0,0 +1,96 @@
+import { useCallback, useState } from 'react';
+
+/**
+ * "Open Plannotator at plannotator.localhost" (#2184) for Settings → General: on
+ * writes `urlHost: "plannotator.localhost"` to config.json, off removes it.
+ * The server sends it as `serverConfig.cookieHost` only for a local session
+ * (never remote mode or `--tailscale`), and writes it with POST /api/config.
+ * Deliberately not a settings-registry entry: the registry is bundled into
+ * the portable guides.show viewer, whose pinned build must not change.
+ */
+export interface CookieHostSetting {
+  on: boolean;
+  /** PLANNOTATOR_URL_HOST is set (its value; "" when set empty): the switch is locked. */
+  env?: string;
+  /** config.json holds another `urlHost` (a tailnet name, `auto`, an IP): locked, never replaced. */
+  urlHost?: string;
+  /** The last save failed: the reason, shown under the switch. */
+  error?: string;
+  onChange: (next: boolean) => void;
+}
+
+/**
+ * The cookie switch's one sub line: what it does, or why the switch is
+ * locked. `inbox` adds that the Inbox's notifications need allowing once at
+ * the new address.
+ */
+export function cookieHostDescription(
+  setting: Pick<CookieHostSetting, 'on' | 'env' | 'urlHost'>,
+  options: { inbox?: boolean } = {},
+): string {
+  if (setting.env !== undefined) {
+    return setting.env.trim() === ''
+      ? 'Set by PLANNOTATOR_URL_HOST in your environment (empty).'
+      : `Set by PLANNOTATOR_URL_HOST=${setting.env.trim()} in your environment.`;
+  }
+  if (setting.urlHost !== undefined) return `config.json sets urlHost to ${setting.urlHost}; this switch never replaces it.`;
+  const notifications = options.inbox ? ' Notifications need allowing once there.' : '';
+  return `Keeps Plannotator's cookies away from your other localhost apps. Starts from the next session; this browser's preferences start fresh once.${notifications}`;
+}
+
+interface CookieHostState {
+  on: boolean;
+  env?: string;
+  urlHost?: string;
+}
+
+function parseState(value: unknown): CookieHostState | undefined {
+  if (!value || typeof value !== 'object') return undefined;
+  const v = value as Record<string, unknown>;
+  if (typeof v.on !== 'boolean') return undefined;
+  return {
+    on: v.on,
+    ...(typeof v.env === 'string' && { env: v.env }),
+    ...(typeof v.urlHost === 'string' && { urlHost: v.urlHost }),
+  };
+}
+
+export function useCookieHostSetting(): {
+  setting: CookieHostSetting | undefined;
+  adopt: (serverConfig: Record<string, unknown> | undefined) => void;
+} {
+  const [state, setState] = useState<CookieHostState | undefined>();
+  const [error, setError] = useState<string | undefined>();
+
+  const adopt = useCallback((serverConfig: Record<string, unknown> | undefined) => {
+    setState(parseState(serverConfig?.cookieHost));
+  }, []);
+
+  const onChange = useCallback((next: boolean) => {
+    setError(undefined);
+    setState((current) => (current ? { ...current, on: next } : current));
+    void fetch('/api/config', {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ cookieHost: next }),
+    })
+      .then(async (res) => {
+        const body = (await res.json().catch(() => ({}))) as { error?: unknown; cookieHost?: unknown };
+        const saved = parseState(body.cookieHost);
+        if (saved) setState(saved);
+        if (!res.ok) {
+          if (!saved) setState((current) => (current ? { ...current, on: !next } : current));
+          setError(typeof body.error === 'string' ? body.error : 'The setting could not be saved.');
+        }
+      })
+      .catch(() => {
+        setState((current) => (current ? { ...current, on: !next } : current));
+        setError('The setting could not be saved.');
+      });
+  }, []);
+
+  return {
+    setting: state ? { ...state, ...(error && { error }), onChange } : undefined,
+    adopt,
+  };
+}

package/hooks/useDocumentFont.ts

@@ -0,0 +1,17 @@
+import { useLayoutEffect } from 'react';
+import { useConfigValue } from '../config';
+import { applyDocumentFont } from '../utils/documentFont';
+
+/**
+ * Apply the `documentFontFamily` setting (Settings → Display → Document font)
+ * to the document element for as long as the calling component is mounted. A
+ * layout effect, so a remembered font is on the page before its first paint.
+ * On unmount the theme's font is put back.
+ */
+export function useDocumentFont(): void {
+  const family = useConfigValue('documentFontFamily');
+  useLayoutEffect(() => {
+    applyDocumentFont(document.documentElement, family);
+  }, [family]);
+  useLayoutEffect(() => () => applyDocumentFont(document.documentElement, ''), []);
+}

package/hooks/useDocumentTextSize.ts

@@ -0,0 +1,20 @@
+import { useLayoutEffect } from 'react';
+import { useConfigValue } from '../config';
+import { applyDocumentTextSize, DEFAULT_DOCUMENT_TEXT_SIZE } from '../utils/documentTextSize';
+
+/**
+ * Apply the `documentTextSize` setting (Settings → Display → Text size) to the
+ * document element for as long as the calling component is mounted. A layout
+ * effect, so a remembered size is on the page before its first paint. On
+ * unmount the default is put back.
+ */
+export function useDocumentTextSize(): void {
+  const size = useConfigValue('documentTextSize');
+  useLayoutEffect(() => {
+    applyDocumentTextSize(document.documentElement, size);
+  }, [size]);
+  useLayoutEffect(
+    () => () => applyDocumentTextSize(document.documentElement, DEFAULT_DOCUMENT_TEXT_SIZE),
+    [],
+  );
+}

package/hooks/useFileBrowser.ts

@@ -22,6 +22,13 @@ export interface DirState {
   hasLoadedTree?: boolean;
   /** When true, fetches via /api/reference/obsidian/files and opens docs via /api/reference/obsidian/doc */
   isVault?: boolean;
+  /**
+   * The server left supported files out because the folder holds more than
+   * its cap (PLANNOTATOR_FILE_BROWSER_MAX_FILES). `fileLimit` is that cap.
+   * Absent from a backend that does not cap.
+   */
+  truncated?: boolean;
+  fileLimit?: number;
 }
 
 export interface UseFileBrowserReturn {
@@ -89,7 +96,7 @@ function remapWorkspaceStatusForDir(
  * tree from its own transport instead.
  */
 export interface FileTreeBackend {
-  /** Load a directory tree. Resolves to the same shape the /api/reference/files endpoint returns: a Response whose JSON is { tree, workspaceStatus?, error? }. */
+  /** Load a directory tree. Resolves to the same shape the /api/reference/files endpoint returns: a Response whose JSON is { tree, workspaceStatus?, truncated?, fileLimit?, error? }. */
   loadTree(dirPath: string): Promise<Response>;
   /** Load an Obsidian vault tree. Resolves to a Response whose JSON is { tree, error? }. */
   loadVaultTree(vaultPath: string): Promise<Response>;
@@ -244,6 +251,8 @@ export function useFileBrowser(): UseFileBrowserReturn {
               isLoading: false,
               hasLoadedTree: true,
               error: null,
+              truncated: data.truncated === true,
+              fileLimit: typeof data.fileLimit === "number" && data.fileLimit > 0 ? data.fileLimit : undefined,
             }
             : d
         )

package/hooks/useHeadingScrollSpy.ts

@@ -0,0 +1,77 @@
+import { useCallback, useLayoutEffect, useMemo, useRef, useState } from 'react';
+import { activeHeadingBinding, bindHeadings, type HeadingBinding } from '../utils/headingScrollSpy';
+
+/**
+ * The block id of the heading being read in `scrollViewport`, by the contents
+ * rail's own scroll math (utils/headingScrollSpy): cached heading tops, read
+ * on every scroll frame, the last heading at the document's end. For a
+ * Contents list on the rail's surface (`DocumentContents`), so the two never
+ * disagree. Plan review's list keeps `useActiveSection`.
+ *
+ * Reads at once on mount (a sheet opened mid-document marks the section being
+ * read on its first paint), and re-binds when the document's elements change
+ * (an edit can replace the headings and keep their count) or resize. Before
+ * any heading is drawn the answer stays what it was.
+ */
+export function useHeadingScrollSpy(
+  scrollViewport: HTMLElement | null,
+  blockIds: readonly string[],
+): string | null {
+  const idsKey = blockIds.join('\n');
+  // Stable while the ids are the same, whatever array the caller passes.
+  const ids = useMemo(() => (idsKey === '' ? [] : idsKey.split('\n')), [idsKey]);
+  const [activeIndex, setActiveIndex] = useState<number | null>(null);
+  const bindingsRef = useRef<readonly HeadingBinding[]>([]);
+
+  const refresh = useCallback(() => {
+    if (scrollViewport === null) return;
+    const binding = activeHeadingBinding(bindingsRef.current, scrollViewport);
+    if (binding !== null) setActiveIndex(binding.itemIndex);
+  }, [scrollViewport]);
+
+  useLayoutEffect(() => {
+    setActiveIndex(null);
+    bindingsRef.current = [];
+    if (scrollViewport === null || ids.length === 0) return;
+    const rebind = () => {
+      bindingsRef.current = bindHeadings(scrollViewport, ids);
+      refresh();
+    };
+    rebind();
+
+    let scrollFrame: number | null = null;
+    const onScroll = () => {
+      if (scrollFrame !== null) return;
+      scrollFrame = requestAnimationFrame(() => {
+        scrollFrame = null;
+        refresh();
+      });
+    };
+    let bindFrame: number | null = null;
+    const scheduleRebind = () => {
+      if (bindFrame !== null) cancelAnimationFrame(bindFrame);
+      bindFrame = requestAnimationFrame(() => {
+        bindFrame = null;
+        rebind();
+      });
+    };
+    scrollViewport.addEventListener('scroll', onScroll, { passive: true });
+    window.addEventListener('resize', scheduleRebind);
+    const resizeObserver =
+      typeof ResizeObserver === 'undefined' ? null : new ResizeObserver(scheduleRebind);
+    resizeObserver?.observe(scrollViewport);
+    const mutationObserver =
+      typeof MutationObserver === 'undefined' ? null : new MutationObserver(scheduleRebind);
+    mutationObserver?.observe(scrollViewport, { childList: true, subtree: true });
+    return () => {
+      if (scrollFrame !== null) cancelAnimationFrame(scrollFrame);
+      if (bindFrame !== null) cancelAnimationFrame(bindFrame);
+      scrollViewport.removeEventListener('scroll', onScroll);
+      window.removeEventListener('resize', scheduleRebind);
+      resizeObserver?.disconnect();
+      mutationObserver?.disconnect();
+    };
+  }, [ids, refresh, scrollViewport]);
+
+  return activeIndex === null ? null : (ids[activeIndex] ?? null);
+}

package/hooks/useHoverPreview.ts

@@ -0,0 +1,94 @@
+import { useCallback, useEffect, useRef, useState } from 'react';
+
+/** How long the pointer rests on an anchor before the preview is fetched. */
+export const HOVER_PREVIEW_SHOW_DELAY_MS = 150;
+/** How long a preview stays after the pointer leaves, so it can move into the preview. */
+export const HOVER_PREVIEW_HIDE_DELAY_MS = 200;
+
+export interface HoverPreview<T> {
+  /** The loaded preview while it is open, else null. */
+  preview: T | null;
+  /** Attach to the anchor element; the preview positions against it. */
+  anchorRef: React.MutableRefObject<HTMLElement | null>;
+  /** Pointer or focus arrives on the anchor: load after the show delay. */
+  onEnter: () => void;
+  /** Pointer or focus leaves the anchor: close after the hide delay. */
+  onLeave: () => void;
+  /** Spread onto the preview so moving into it keeps it open. */
+  previewHandlers: { onMouseEnter: () => void; onMouseLeave: () => void };
+  /** Close at once (a click, a scroll). */
+  dismiss: () => void;
+}
+
+/**
+ * Dwell-then-load hover for a floating preview: the timing shared by the
+ * code-file link preview (InlineMarkdown) and Call Flow's source locations.
+ * Nothing loads before the pointer rests for `HOVER_PREVIEW_SHOW_DELAY_MS`; a
+ * load that resolves after the pointer left is dropped. `load` resolving
+ * null means "nothing to show".
+ */
+export function useHoverPreview<T>(load: () => Promise<T | null>, enabled = true): HoverPreview<T> {
+  const [preview, setPreview] = useState<T | null>(null);
+  const previewRef = useRef(preview);
+  previewRef.current = preview;
+  const anchorRef = useRef<HTMLElement | null>(null);
+  const showTimerRef = useRef<ReturnType<typeof setTimeout> | null>(null);
+  const hideTimerRef = useRef<ReturnType<typeof setTimeout> | null>(null);
+  // Bumped on every leave so a load still in flight cannot open a stale preview.
+  const generationRef = useRef(0);
+  const loadRef = useRef(load);
+  loadRef.current = load;
+
+  const cancelShow = useCallback(() => {
+    if (showTimerRef.current) { clearTimeout(showTimerRef.current); showTimerRef.current = null; }
+  }, []);
+  const cancelHide = useCallback(() => {
+    if (hideTimerRef.current) { clearTimeout(hideTimerRef.current); hideTimerRef.current = null; }
+  }, []);
+
+  const scheduleHide = useCallback(() => {
+    cancelHide();
+    hideTimerRef.current = setTimeout(() => setPreview(null), HOVER_PREVIEW_HIDE_DELAY_MS);
+  }, [cancelHide]);
+
+  const onEnter = useCallback(() => {
+    if (!enabled) return;
+    cancelHide();
+    if (previewRef.current || showTimerRef.current) return;
+    const generation = generationRef.current;
+    showTimerRef.current = setTimeout(async () => {
+      showTimerRef.current = null;
+      try {
+        const data = await loadRef.current();
+        if (data != null && generation === generationRef.current) setPreview(data);
+      } catch {}
+    }, HOVER_PREVIEW_SHOW_DELAY_MS);
+  }, [enabled, cancelHide]);
+
+  const onLeave = useCallback(() => {
+    cancelShow();
+    generationRef.current += 1;
+    scheduleHide();
+  }, [cancelShow, scheduleHide]);
+
+  const dismiss = useCallback(() => {
+    cancelShow();
+    cancelHide();
+    generationRef.current += 1;
+    setPreview(null);
+  }, [cancelShow, cancelHide]);
+
+  useEffect(() => () => {
+    cancelShow();
+    cancelHide();
+  }, [cancelShow, cancelHide]);
+
+  return {
+    preview,
+    anchorRef,
+    onEnter,
+    onLeave,
+    previewHandlers: { onMouseEnter: cancelHide, onMouseLeave: scheduleHide },
+    dismiss,
+  };
+}