@plannotator/ui 0.53.0 → 0.54.0

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);
 

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,
+  };
+}