@plannotator/ui 0.53.1 → 0.55.0

package/hooks/useAIChat.ts

@@ -30,6 +30,9 @@ export interface AIChatThread {
 
 export interface AskAIParams {
   prompt: string;
+  /** What the chat shows as the question when it differs from `prompt`, which
+   *  is what the agent gets (e.g. a short "Explain this finding: …"). */
+  displayPrompt?: string;
   filePath?: string;
   lineStart?: number;
   lineEnd?: number;
@@ -52,6 +55,12 @@ export interface AskAIParams {
    *  received, and the server frames it as read-only context, never as
    *  feedback (#1748). Leave unset for every other provider. */
   draftAnnotations?: string;
+  /** Called once, when the stream first shows the question reached the
+   *  session (an answer started, or the session took it over). A busy, gone
+   *  or failed ask never calls it; a retry keeps it, so the retried question
+   *  calls it when it lands. Lets a caller record what the session was told
+   *  (e.g. which document a note named) only once it was received. */
+  onDelivered?: () => void;
 }
 
 /** What to send as `draftAnnotations` for one question: the list when this
@@ -73,6 +82,15 @@ const BRIDGE_DRAFTS_KEY = 'session-bridge';
 /** Stream messages that show the session received the question. */
 const DELIVERED_MESSAGE_TYPES = new Set(['text_delta', 'text', 'tool_use', 'tool_result', 'result']);
 
+/**
+ * A busy "Ask this session" answer still offers its choice ("Ask when it
+ * finishes" / "Interrupt and ask now"): the question has not been asked yet,
+ * and clearing the thread would drop it without a word.
+ */
+export function hasPendingBusyChoice(messages: AIChatEntry[]): boolean {
+  return messages.some(m => m.response.errorCode === SESSION_ASK_ERROR_CODES.agentBusy);
+}
+
 /** Overrides for re-asking a question that ended in a busy/gone/blocked answer. */
 export interface AIRetryOptions {
   busyPolicy?: 'wait' | 'interrupt';
@@ -179,8 +197,9 @@ export interface AITransport {
   session(body: unknown, signal: AbortSignal): Promise<Response>;
   /** POST /api/ai/query — send a message; returns the streaming SSE response. */
   query(body: unknown, signal: AbortSignal): Promise<Response>;
-  /** POST /api/ai/abort — abort a session (supersede + standalone). Resolves once
-      the server acknowledges so a following query can await it (best-effort, never rejects). */
+  /** POST /api/ai/abort. A superseding question sends `reason: 'supersede'`
+   * so session bridges close the answer without stopping the host turn.
+   * Resolves once acknowledged, before the old fetch is disconnected. */
   abort(body: unknown): Promise<unknown>;
   /** POST /api/ai/permission — respond to a permission request. Fire-and-forget. */
   permission(body: unknown): void;
@@ -238,9 +257,9 @@ export const resetAITransport = (): void => {
  * ask() relies on this resolving. Single-sourced so every abort call site stays
  * hardened. Reads `aiTransport` at call time so a late override is honored.
  */
-function safeAbort(sessionId: string): Promise<unknown> {
+function safeAbort(sessionId: string, reason?: 'supersede'): Promise<unknown> {
   return Promise.resolve()
-    .then(() => aiTransport.abort({ sessionId }))
+    .then(() => aiTransport.abort({ sessionId, ...(reason && { reason }) }))
     .catch(() => {});
 }
 
@@ -261,10 +280,15 @@ export function useAIChat({
   // In-flight server abort (from Stop or a superseding question). The next ask()
   // waits on it so a new query can't race the still-active turn into busy.
   const pendingAbortRef = useRef<Promise<unknown> | null>(null);
+  // Answers a newer question replaced. Their fetch stays open until the server
+  // acknowledges the supersede, but nothing more they stream is shown.
+  const supersededRef = useRef(new WeakSet<AbortController>());
   const sessionEpochRef = useRef(0);
   const createRequestRef = useRef(0);
   const sessionIdRef = useRef<string | null>(null);
   sessionIdRef.current = thread.sessionId;
+  const threadRef = useRef(thread);
+  threadRef.current = thread;
 
   const updateMessages = useCallback((updater: (messages: AIChatEntry[]) => AIChatEntry[]) => {
     setThread(prev => ({ ...prev, messages: updater(prev.messages) }));
@@ -316,16 +340,13 @@ export function useAIChat({
     }
   }, [context, model, providerId, reasoningEffort, setSessionId]);
 
-  // Tell the server to stop the current session's in-flight turn, and resolve
-  // once it has. Used by the Stop button and when a new question supersedes a
-  // streaming one — aborting the browser fetch alone leaves the agent's turn
-  // running. The /api/ai/abort handler clears the session's active flag before
-  // it responds, so awaiting this guarantees a following query won't race it
-  // into a session_busy error. Best-effort (never rejects).
-  const postServerAbort = useCallback((): Promise<unknown> => {
+  // Stop cancels the turn. Supersede closes the old answer but lets a session
+  // bridge's host keep working until the reviewer chooses to interrupt it.
+  // Both clear the server's query before the next one. Best-effort (never rejects).
+  const postServerAbort = useCallback((reason?: 'supersede'): Promise<unknown> => {
     const sessionId = sessionIdRef.current; // capture the session being aborted now
     if (!sessionId) return Promise.resolve();
-    return safeAbort(sessionId);
+    return safeAbort(sessionId, reason);
   }, []);
 
   // The params each question was asked with, so a busy answer can be
@@ -341,19 +362,18 @@ export function useAIChat({
   const deliveredDraftsRef = useRef<{ sessionId: string; text: string } | null>(null);
 
   const ask = useCallback(async (params: AskAIParams, askOptions?: { providerId?: string }) => {
-    if (abortRef.current) {
-      abortRef.current.abort();
-      // Supersede: stop the server-side turn (not just the browser fetch).
-      pendingAbortRef.current = postServerAbort();
+    const previous = abortRef.current;
+    if (previous) {
+      supersededRef.current.add(previous);
+      pendingAbortRef.current = postServerAbort('supersede');
     }
-    // Wait for any in-flight server abort — from this supersede OR a prior Stop
-    // click — so the query below doesn't race the still-active turn into a
-    // session_busy error. Stopping still kills the turn; chatting right after
-    // just waits the one round-trip for the stop to land.
+    // Let the server distinguish supersede from Stop before disconnecting:
+    // cancelling the SSE fetch first would still abort the host's turn.
     if (pendingAbortRef.current) {
       await pendingAbortRef.current;
       pendingAbortRef.current = null;
     }
+    previous?.abort();
 
     const controller = new AbortController();
     abortRef.current = controller;
@@ -364,7 +384,7 @@ export function useAIChat({
     paramsByQuestionRef.current.set(questionId, params);
     const question: AIQuestion = {
       id: questionId,
-      prompt: params.prompt,
+      prompt: params.displayPrompt ?? params.prompt,
       scope: params.scope,
       filePath: params.filePath,
       lineStart: params.lineStart,
@@ -392,7 +412,7 @@ export function useAIChat({
         sid = await createSession(controller.signal, epoch);
       }
 
-      if (controller.signal.aborted || epoch !== sessionEpochRef.current) {
+      if (controller.signal.aborted || supersededRef.current.has(controller) || epoch !== sessionEpochRef.current) {
         throw createAbortError('AI question was superseded');
       }
 
@@ -400,11 +420,20 @@ export function useAIChat({
       const drafts = draftAnnotationsToSend(deliveredDraftsRef.current, BRIDGE_DRAFTS_KEY, params.draftAnnotations);
       // Recorded once the session shows it received the question, so a busy,
       // gone or failed ask sends the list again next time.
+      let deliveredCalled = false;
       const markDraftsDelivered = (msg: { type?: unknown; code?: unknown }) => {
-        if (drafts === undefined) return;
         const received = DELIVERED_MESSAGE_TYPES.has(String(msg.type))
           || (msg.type === 'error' && msg.code === SESSION_ASK_ERROR_CODES.takenOver);
-        if (received) deliveredDraftsRef.current = { sessionId: BRIDGE_DRAFTS_KEY, text: drafts };
+        if (!received) return;
+        if (drafts !== undefined) deliveredDraftsRef.current = { sessionId: BRIDGE_DRAFTS_KEY, text: drafts };
+        if (!deliveredCalled) {
+          deliveredCalled = true;
+          try {
+            params.onDelivered?.();
+          } catch {
+            // A caller's bookkeeping must never break the stream.
+          }
+        }
       };
       const res = await aiTransport.query({
         sessionId: sid,
@@ -425,6 +454,7 @@ export function useAIChat({
 
       while (true) {
         const { done, value } = await reader.read();
+        if (supersededRef.current.has(controller)) throw createAbortError('AI question was superseded');
         if (done) break;
         buffer += decoder.decode(value, { stream: true });
 
@@ -566,7 +596,7 @@ export function useAIChat({
         )
       );
     } finally {
-      if (abortRef.current === controller) {
+      if (abortRef.current === controller && !supersededRef.current.has(controller)) {
         setIsStreaming(false);
         abortRef.current = null;
       }
@@ -649,6 +679,22 @@ export function useAIChat({
     setError(null);
   }, [postServerAbort, threadTitle]);
 
+  // The panel's "New chat": clears the thread and forgets the Plannotator AI
+  // session, so the next question starts a fresh one (a separate AI then gets
+  // the full context again). Unlike `resetThread` (a document switch), it never
+  // stops anything: while a question is in flight (streaming, creating its
+  // session, or waiting on a busy "Ask this session") or a busy answer still
+  // offers its choice, it does nothing and answers false, so a running turn is
+  // not aborted and a pending ask is not dropped. What the agent session already received (`deliveredDraftsRef`) is
+  // kept: with "Ask this session" a new chat reaches the SAME host session,
+  // which still remembers it.
+  const newChat = useCallback((): boolean => {
+    if (abortRef.current) return false;
+    if (hasPendingBusyChoice(threadRef.current.messages)) return false;
+    resetThread();
+    return true;
+  }, [resetThread]);
+
   useEffect(() => {
     return () => {
       sessionEpochRef.current += 1;
@@ -672,6 +718,7 @@ export function useAIChat({
     abort,
     resetSession,
     resetThread,
+    newChat,
     sessionId: thread.sessionId,
   };
 }

package/hooks/useAnnotationDraft.ts

@@ -144,6 +144,19 @@ export interface DraftSavedFileChange {
   sourceSave: DraftSourceSaveCapability;
 }
 
+/**
+ * A linked document's saved comments, offered with the session draft. The
+ * server writes this list (`documents` on GET /api/draft, plan review and
+ * annotate sessions on a URL or the last message: packages/shared/annotate-draft.ts);
+ * the hook never sends it. Each entry belongs to the document at `path`, not
+ * to the session's root.
+ */
+export interface DraftDocumentCopy {
+  path: string;
+  annotations: Annotation[];
+  globalAttachments: ImageAttachment[];
+}
+
 /** New format: full objects. */
 interface DraftData {
   annotations: Annotation[];
@@ -158,6 +171,8 @@ interface DraftData {
   savedFileChanges?: DraftSavedFileChange[];
   /** Client-side generation used to ignore stale saves after a draft delete. */
   draftGeneration?: number;
+  /** Server-written on load only: other documents' saved comments. */
+  documents?: unknown;
   ts: number;
 }
 
@@ -253,6 +268,28 @@ function isDraftSourceSaveCapability(value: unknown): value is DraftSourceSaveCa
   );
 }
 
+/** The server's `documents` list: entries with a path and at least one comment or attachment. */
+function parseDraftDocuments(value: unknown): DraftDocumentCopy[] {
+  if (!Array.isArray(value)) return [];
+  const documents: DraftDocumentCopy[] = [];
+  for (const entry of value) {
+    const doc = entry as Partial<DraftDocumentCopy> | null;
+    if (!doc || typeof doc.path !== 'string' || doc.path.length === 0) continue;
+    const annotations = Array.isArray(doc.annotations)
+      ? doc.annotations.filter((a): a is Annotation => !!a && typeof a === 'object' && typeof (a as Annotation).id === 'string')
+      : [];
+    const globalAttachments = Array.isArray(doc.globalAttachments)
+      ? doc.globalAttachments.filter((g): g is ImageAttachment => !!g && typeof g === 'object' && typeof (g as ImageAttachment).path === 'string')
+      : [];
+    if (annotations.length === 0 && globalAttachments.length === 0) continue;
+    documents.push({ path: doc.path, annotations, globalAttachments });
+  }
+  return documents;
+}
+
+const countDraftDocuments = (documents: DraftDocumentCopy[]): number =>
+  documents.reduce((total, doc) => total + doc.annotations.length + doc.globalAttachments.length, 0);
+
 function readDraftGeneration(value: unknown): number | null {
   return typeof value === 'number' && Number.isInteger(value) && value >= 0 ? value : null;
 }
@@ -291,17 +328,37 @@ interface RestoredDraft {
   editedMarkdown: string | null;
   editedDocuments: DraftEditedDocument[];
   savedFileChanges: DraftSavedFileChange[];
+  /** Other documents' saved comments, each for the document at its path.
+      `annotations` / `globalAttachments` above are the root document's. */
+  documents: DraftDocumentCopy[];
+}
+
+/** What the Draft Recovered banner says it found. */
+export interface DraftBanner {
+  count: number;
+  timeAgo: string;
+  hasEdits: boolean;
+  /** How many other documents hold comments (absent: the root's alone). */
+  documents?: number;
+  /** How many of `count` are on those other documents. */
+  documentComments?: number;
 }
 
 interface UseAnnotationDraftResult {
-  draftBanner: { count: number; timeAgo: string; hasEdits: boolean } | null;
+  /** `count` includes the other documents' comments; `documents` is how many
+      other documents hold some and `documentComments` how many of `count`
+      they hold (both absent when the draft is the root's alone). */
+  draftBanner: DraftBanner | null;
   restoreDraft: () => RestoredDraft;
   /** Debounced save trigger for changes the reactive deps can't see
       (editor keystrokes, edit commit/discard). Stable identity. */
   scheduleDraftSave: () => void;
   scheduleDraftSaveAfterSubmitFailure: () => void;
   getDraftGeneration: () => number;
-  dismissDraft: () => void;
+  /** Discard the offered draft. Returns the other documents' comments that
+      were offered with it (empty for a root-only draft), so the host can
+      discard their copies too. */
+  dismissDraft: () => DraftDocumentCopy[];
   /** Send a pending (debounced) save now, if there is one. For a session
       that ends WITHOUT a decision body (the agent closed it): the comment
       typed just before must still reach the kept draft. */
@@ -319,7 +376,7 @@ export function useAnnotationDraft({
   isSharedSession,
   submitted,
 }: UseAnnotationDraftOptions): UseAnnotationDraftResult {
-  const [draftBanner, setDraftBanner] = useState<{ count: number; timeAgo: string; hasEdits: boolean } | null>(null);
+  const [draftBanner, setDraftBanner] = useState<DraftBanner | null>(null);
   const draftDataRef = useRef<RestoredDraft | null>(null);
   const timerRef = useRef<ReturnType<typeof setTimeout> | null>(null);
   const hasMountedRef = useRef(false);
@@ -394,8 +451,10 @@ export function useAnnotationDraft({
           !isLegacyDraft(data) && Array.isArray((data as DraftData).savedFileChanges)
             ? (data as DraftData).savedFileChanges!.filter(isDraftSavedFileChange)
             : [];
+        const restoredDocuments = !isLegacyDraft(data) ? parseDraftDocuments((data as DraftData).documents) : [];
 
-        const totalCount = restoredAnnotations.length + restoredCodeAnnotations.length + restoredGlobal.length;
+        const totalCount =
+          restoredAnnotations.length + restoredCodeAnnotations.length + restoredGlobal.length + countDraftDocuments(restoredDocuments);
         if (totalCount > 0 || restoredEdited !== null || restoredEditedDocuments.length > 0 || restoredSavedFileChanges.length > 0) {
           draftDataRef.current = {
             annotations: restoredAnnotations,
@@ -404,11 +463,15 @@ export function useAnnotationDraft({
             editedMarkdown: restoredEdited,
             editedDocuments: restoredEditedDocuments,
             savedFileChanges: restoredSavedFileChanges,
+            documents: restoredDocuments,
           };
           setDraftBanner({
             count: totalCount,
             timeAgo: formatTimeAgo(data.ts || 0),
             hasEdits: restoredEdited !== null || restoredEditedDocuments.length > 0 || restoredSavedFileChanges.length > 0,
+            ...(restoredDocuments.length > 0
+              ? { documents: restoredDocuments.length, documentComments: countDraftDocuments(restoredDocuments) }
+              : {}),
           });
         }
         hasMountedRef.current = true;
@@ -547,12 +610,13 @@ export function useAnnotationDraft({
     setDraftBanner(null);
     draftDataRef.current = null;
 
-    if (!data) return { annotations: [], codeAnnotations: [], globalAttachments: [], editedMarkdown: null, editedDocuments: [], savedFileChanges: [] };
+    if (!data) return { annotations: [], codeAnnotations: [], globalAttachments: [], editedMarkdown: null, editedDocuments: [], savedFileChanges: [], documents: [] };
 
     return data;
   }, []);
 
-  const dismissDraft = useCallback(() => {
+  const dismissDraft = useCallback((): DraftDocumentCopy[] => {
+    const offeredDocuments = draftDataRef.current?.documents ?? [];
     const deletedGeneration = draftGenerationRef.current + 1;
     draftGenerationRef.current = deletedGeneration;
     if (timerRef.current) {
@@ -563,6 +627,7 @@ export function useAnnotationDraft({
     draftDataRef.current = null;
 
     getDraftTransport().remove(deletedGeneration, { keepalive: false }).catch(() => {});
+    return offeredDocuments;
   }, []);
 
   return { draftBanner, restoreDraft, scheduleDraftSave, scheduleDraftSaveAfterSubmitFailure, getDraftGeneration, dismissDraft, flushPendingSave };

package/hooks/useAnnotationHighlighter.ts

@@ -8,11 +8,17 @@
 import { useEffect, useRef, useState, useCallback, type RefObject } from 'react';
 import Highlighter from '@plannotator/web-highlighter';
 import type { Annotation, EditorMode, HostDraft, ImageAttachment } from '../types';
+import { metaWithBelowTitle, metaWithoutBelowTitle, snapRangeOutOfBelowTitle } from '../utils/belowTitleSlot';
 import { AnnotationType } from '../types';
 import type { QuickLabel } from '../utils/quickLabels';
+import {
+  trimWhitespaceOnlyBoundaryNodes,
+  type SelectedNodeLike,
+} from '../utils/selectionBoundary';
 import { getIdentity } from '../utils/identity';
 import { annotationOwnsHighlight } from '../utils/annotationOwnsHighlight';
 import { transformPlainText } from '../utils/inlineTransforms';
+import { richCopySourceFromRange, type RichCopySource } from '../utils/richClipboard';
 
 // --- Exported state types ---
 
@@ -20,6 +26,9 @@ export interface ToolbarState {
   element: HTMLElement;
   source: any;
   selectionText: string;
+  /** Builds the selection's rich-text copy when the toolbar button is pressed
+   *  (synchronous in the markdown Viewer, a bridge round trip on HTML surfaces). */
+  getRichCopy?: () => RichCopySource | Promise<RichCopySource>;
 }
 
 export interface CommentPopoverState {
@@ -1248,6 +1257,10 @@ export function useAnnotationHighlighter({
       // verdict, so it is neither attempted nor unanchored here (the same
       // rule the raw-HTML pinpoints follow on their surface).
       if (ann.diagramAnchor) return;
+      // A comment on part of an image has no text either: the image viewer
+      // draws its box, and the Viewer reports it unanchored when its image is
+      // gone from the document.
+      if (ann.imageRegion != null) return;
       // An answer to a `:::question` block quotes the prompt but is not a
       // selection: the question block draws it from the annotation, so it is
       // never painted as a highlight (and never reported as unanchored here).
@@ -1286,7 +1299,12 @@ export function useAnnotationHighlighter({
 
       if (ann.startMeta && ann.endMeta) {
         try {
-          highlighter.fromStore(ann.startMeta, ann.endMeta, ann.originalText, ann.id);
+          highlighter.fromStore(
+            metaWithBelowTitle(containerRef.current, ann.startMeta),
+            metaWithBelowTitle(containerRef.current, ann.endMeta),
+            ann.originalText,
+            ann.id,
+          );
           const restoredDoms = highlighter.getDoms(ann.id);
           if (restoredDoms && restoredDoms.length > 0) {
             const restoredText = paintedTextOf(restoredDoms as HTMLElement[]);
@@ -1480,6 +1498,15 @@ export function useAnnotationHighlighter({
       style: { className: 'annotation-highlight' },
     });
 
+    // Chromium can extend a triple-clicked line into empty or indentation nodes of the next block.
+    // Trim only boundary whitespace so spacing inside genuine multi-node selections stays highlighted.
+    // The hook's callback type is `(...args: unknown[]) => SelectedNode[]`; a SelectedNode
+    // structurally satisfies SelectedNodeLike, so the trimmed subset goes back through the
+    // hook's own callback type rather than importing SelectedNode from the package's dist/.
+    type SelectedNodesTap = Parameters<typeof highlighter.hooks.Render.SelectedNodes.tap>[0];
+    highlighter.hooks.Render.SelectedNodes.tap(((...args: unknown[]) =>
+      trimWhitespaceOnlyBoundaryNodes(args[1] as SelectedNodeLike[])) as SelectedNodesTap);
+
     highlighterRef.current = highlighter;
 
     // Stored positions can resolve into chrome the reviewer could never have
@@ -1499,6 +1526,15 @@ export function useAnnotationHighlighter({
 
     highlighter.on(Highlighter.event.CREATE, ({ sources, type }: { sources: any[]; type?: string }) => {
       if (type === 'from-store') return;
+      // Store positions as if a host's `belowTitle` slot were not there, so
+      // its contents never renumber a comment's parent element (identity
+      // when the document has no slot). See utils/belowTitleSlot.
+      for (const created of sources) {
+        const startMeta = metaWithoutBelowTitle(containerRef.current, created.startMeta, 'start');
+        const endMeta = metaWithoutBelowTitle(containerRef.current, created.endMeta, 'end');
+        if (startMeta !== created.startMeta) created.startMeta = startMeta;
+        if (endMeta !== created.endMeta) created.endMeta = endMeta;
+      }
       if (sources.length > 0) {
         const source = sources[0];
         const doms = highlighter.getDoms(source.id);
@@ -1561,10 +1597,24 @@ export function useAnnotationHighlighter({
           } else {
             // Selection mode — show toolbar
             pendingSourceRef.current = source;
+            const marks = [...doms] as HTMLElement[];
+            const selectionText = source.text;
             setToolbarState({
               element: doms[0] as HTMLElement,
               source,
-              selectionText: source.text,
+              selectionText,
+              // Built only when Copy (rich text) is pressed: the pending
+              // highlight's marks still bound the selected words, and the
+              // sanitizer drops the marks themselves.
+              getRichCopy: () => {
+                const first = marks[0];
+                const last = marks[marks.length - 1];
+                if (!first?.isConnected || !last?.isConnected) return null;
+                const range = document.createRange();
+                range.setStartBefore(first);
+                range.setEndAfter(last);
+                return richCopySourceFromRange(range, selectionText);
+              },
             });
           }
         }
@@ -1609,7 +1659,9 @@ export function useAnnotationHighlighter({
         pendingRangeRunsRef.current = null;
         return;
       }
-      if (snapRangeStartPastExcluded(range)) {
+      const snappedOutOfSlot = snapRangeOutOfBelowTitle(container, range);
+      const snappedPastExcluded = snapRangeStartPastExcluded(range);
+      if (snappedOutOfSlot || snappedPastExcluded) {
         selection.removeAllRanges();
         selection.addRange(range);
       }
@@ -1724,6 +1776,7 @@ export function useAnnotationHighlighter({
       // Same fail-closed rule as the pointer-end guard (#881): touch
       // selections settle on block boundaries just as often.
       if (isBlankQuote(sel.toString()) || !isSerializableRange(range)) return false;
+      snapRangeOutOfBelowTitle(containerRef.current, range);
       snapRangeStartPastExcluded(range);
       pendingRangeRunsRef.current = rangeTextPieces(range);
       try {
@@ -1776,6 +1829,7 @@ export function useAnnotationHighlighter({
     // visually hidden type word; snap off it before painting (the caller's own
     // range is left untouched).
     const painted = range.cloneRange();
+    snapRangeOutOfBelowTitle(container, painted);
     snapRangeStartPastExcluded(painted);
     pendingRangeRunsRef.current = rangeTextPieces(painted);