@plannotator/ui 0.30.0 → 0.32.0

package/components/html-viewer/useHtmlAnnotation.ts

@@ -1,6 +1,6 @@
 import { useState, useEffect, useCallback, useRef, type RefObject } from "react";
 import { AnnotationType, type Annotation, type EditorMode, type HtmlAnnotationTarget, type HtmlElementAnchor, type ImageAttachment } from "../../types";
-import type { QuickLabel } from "../../utils/quickLabels";
+import { THUMBS_UP_LABEL, type QuickLabel } from "../../utils/quickLabels";
 import { getIdentity } from "../../utils/identity";
 import type {
   ToolbarState,
@@ -18,6 +18,21 @@ function nextHtmlAnnId(): string {
   return `html-ann-${Date.now().toString(36)}-${(htmlAnnSeq++).toString(36)}`;
 }
 
+/** Ids minted by this module for locally created annotations (create-mark).
+ * Module-scoped like the sequence above: a host that swaps a local id for
+ * its own server id keeps the local mark until it removes it, and the
+ * unanchored union needs to recognise such ids whichever viewer instance
+ * minted them. Bounded: only ids from this page load, one entry per create. */
+const mintedHtmlAnnIds = new Set<string>();
+
+function htmlCommentDraftKey(
+  text: string,
+  anchor?: HtmlElementAnchor | null,
+  targetKey?: string,
+): string {
+  return `html-selection:${targetKey ?? JSON.stringify(anchor ?? null)}:${text}`;
+}
+
 interface BridgeSelectionMessage {
   type: `${typeof PREFIX}selection`;
   text: string;
@@ -66,7 +81,30 @@ type BridgeMessage =
   | { type: `${typeof PREFIX}keytype`; key: string }
   | { type: `${typeof PREFIX}mark-click`; id: string }
   | { type: `${typeof PREFIX}unanchored`; ids: string[] }
-  | { type: `${typeof PREFIX}resize`; height: number };
+  | { type: `${typeof PREFIX}resize`; height: number }
+  | { type: `${typeof PREFIX}page-change`; pageUrl: string };
+
+/** Live proxied-app session credentials: the proxy origin messages must come
+ * from, and the per-session token every message must echo. */
+export interface HtmlLiveSession {
+  origin: string;
+  token: string;
+}
+
+/** Cap for live-mode page identity strings (mirrors the bridge's slice). */
+export const MAX_PAGE_URL_LENGTH = 2048;
+
+/** True when a live-session message event fails the origin or token check.
+ * Exported for protocol tests. */
+export function rejectsLiveMessage(
+  live: HtmlLiveSession,
+  origin: string,
+  data: unknown,
+): boolean {
+  if (origin !== live.origin) return true;
+  if (!isRecord(data) || data.token !== live.token) return true;
+  return false;
+}
 
 /** Dependencies and callbacks for the sandboxed HTML annotation bridge. */
 export interface UseHtmlAnnotationOptions {
@@ -79,6 +117,12 @@ export interface UseHtmlAnnotationOptions {
   selectedAnnotationId: string | null;
   mode: EditorMode;
   onResize?: (height: number) => void;
+  /** Live proxied-app session: reject messages that fail the origin or token
+   *  check before parsing, and stamp token + concrete targetOrigin on every
+   *  outbound post. Absent for srcdoc sessions (behavior unchanged). */
+  live?: HtmlLiveSession;
+  /** Live-mode page navigation reports (validated, capped at 2048 chars). */
+  onPageChange?: (pageUrl: string) => void;
   /** Validated pointer positions relayed from inside the iframe while a
    *  pinpoint draft is open (iframe-local viewport coordinates), with the
    *  Shift state observed by the iframe (the parent cannot see modifiers
@@ -92,9 +136,39 @@ export interface UseHtmlAnnotationOptions {
    *  empty on recovery. Delivered in readOnly mode too: view-only surfaces
    *  are exactly where silently missing markers would go unnoticed. */
   onUnanchoredChange?: (ids: string[]) => void;
+  /** Product cap on additional (shift-click) targets per comment, 0..16.
+   *  Applied at the trust boundary, on submit, on restore, and carried to
+   *  the bridge on arm-multi-select so the in-page toggle stops at the
+   *  same number. Absent: the package's 16, and the arm message is unchanged. */
+  maxAdditionalTargets?: number;
+  /** scrollIntoView behavior for scroll-to (selecting an annotation).
+   *  Absent: smooth, as before; pass 'auto' to honor reduced motion. */
+  scrollBehavior?: 'smooth' | 'auto';
 }
 
-function postToIframe(iframe: HTMLIFrameElement | null, msg: Record<string, unknown>) {
+/** Clamp a host cap into the package's bound; anything unusable is the default. */
+export function resolveMaxAdditionalTargets(value: number | undefined): number {
+  if (value === undefined || !Number.isFinite(value)) return MAX_ADDITIONAL_TARGETS;
+  return Math.max(0, Math.min(MAX_ADDITIONAL_TARGETS, Math.floor(value)));
+}
+
+function postToIframe(
+  iframe: HTMLIFrameElement | null,
+  msg: Record<string, unknown>,
+  live?: HtmlLiveSession | null,
+) {
+  if (live) {
+    // Live proxied-app sessions: token on every message, concrete targetOrigin.
+    // Browsers silently DROP a post whose targetOrigin does not match the
+    // receiving window (mid-navigation frames); some DOM environments throw
+    // instead, so align with the browser semantics explicitly.
+    try {
+      iframe?.contentWindow?.postMessage({ ...msg, token: live.token }, live.origin);
+    } catch {
+      // Dropped, matching browser behavior for unmatched target origins.
+    }
+    return;
+  }
   iframe?.contentWindow?.postMessage(msg, "*");
 }
 
@@ -282,6 +356,13 @@ export function parseBridgeMessage(value: unknown): BridgeMessage | null {
       return typeof value.height === "number" && Number.isFinite(value.height)
         ? { type: value.type, height: value.height }
         : null;
+    case `${PREFIX}page-change`:
+      // Live-mode SPA navigation report. Bounded like every bridge string.
+      return typeof value.pageUrl === "string"
+        && value.pageUrl.length > 0
+        && value.pageUrl.length <= MAX_PAGE_URL_LENGTH
+        ? { type: value.type, pageUrl: value.pageUrl }
+        : null;
     default:
       return null;
   }
@@ -301,8 +382,12 @@ export function useHtmlAnnotation({
   selectedAnnotationId,
   mode,
   onResize,
+  live,
+  onPageChange,
   onBridgePointer,
   onUnanchoredChange,
+  maxAdditionalTargets,
+  scrollBehavior,
 }: UseHtmlAnnotationOptions): Omit<
   UseAnnotationHighlighterReturn,
   "highlighterRef" | "highlightRange" | "highlightMathElement"
@@ -315,6 +400,13 @@ export function useHtmlAnnotation({
   flashDraftTarget: (key: string) => void;
   /** Bumped after every target add/remove so the composer can refocus its textarea. */
   composerFocusToken: number;
+  /** Composer one-click "Looks good": submits the hardcoded positive label
+   *  with the same anchor and multi-select targets a typed comment would carry. */
+  handleCommentLooksGood: () => void;
+  /** Ids this module minted for locally created annotations (create-mark),
+   *  for the unanchored union: a minted id the host never listed is a
+   *  swapped-out local mark, not a host row. Read-only, stable identity. */
+  createdAnnotationIds: ReadonlySet<string>;
 } {
   const [toolbarState, setToolbarState] = useState<ToolbarState | null>(null);
   const [commentPopover, setCommentPopover] = useState<CommentPopoverState | null>(null);
@@ -351,9 +443,28 @@ export function useHtmlAnnotation({
   onSelectRef.current = onSelectAnnotation;
   const onUnanchoredChangeRef = useRef(onUnanchoredChange);
   onUnanchoredChangeRef.current = onUnanchoredChange;
+  const liveRef = useRef<HtmlLiveSession | null>(live ?? null);
+  liveRef.current = live ?? null;
+  const onPageChangeRef = useRef(onPageChange);
+  onPageChangeRef.current = onPageChange;
+  // The effective cap and whether the host set one: only an explicit cap
+  // rides on arm-multi-select, so an unconfigured viewer posts today's message.
+  const maxTargetsRef = useRef(resolveMaxAdditionalTargets(maxAdditionalTargets));
+  maxTargetsRef.current = resolveMaxAdditionalTargets(maxAdditionalTargets);
+  const hostCapRef = useRef(maxAdditionalTargets !== undefined);
+  hostCapRef.current = maxAdditionalTargets !== undefined;
 
   const anchorRef = useRef<HTMLDivElement | null>(null);
 
+  /** Post into the iframe with the live token + targetOrigin when a live
+   *  session is active; srcdoc posts keep targetOrigin "*" and no token. */
+  const post = useCallback(
+    (msg: Record<string, unknown>) => {
+      postToIframe(iframeRef.current, msg, liveRef.current);
+    },
+    [iframeRef],
+  );
+
   /**
    * Remove one draft target. Removing the primary promotes the next remaining
    * target (the composer's context text and pending anchor follow it);
@@ -368,7 +479,7 @@ export function useHtmlAnnotation({
       const targets = draftTargetsRef.current;
       const index = targets.findIndex((t) => t.key === key);
       if (index < 0) return;
-      postToIframe(iframeRef.current, { type: `${PREFIX}remove-target`, key });
+      post({ type: `${PREFIX}remove-target`, key });
       const remaining = targets.filter((t) => t.key !== key);
       if (remaining.length === 0) {
         // Final target removed — the draft is cancelled (bridge side already
@@ -392,7 +503,7 @@ export function useHtmlAnnotation({
       setDraftTargets(remaining);
       setComposerFocusToken((t) => t + 1);
     },
-    [iframeRef],
+    [post],
   );
 
   const getOrCreateAnchor = useCallback(() => {
@@ -429,6 +540,11 @@ export function useHtmlAnnotation({
   useEffect(() => {
     function handler(e: MessageEvent<unknown>) {
       if (e.source !== iframeRef.current?.contentWindow) return;
+      // Live sessions verify origin + session token BEFORE parsing. The
+      // existing caps stay exactly as they are: live content is friendlier
+      // but the trust boundary does not relax.
+      const liveSession = liveRef.current;
+      if (liveSession && rejectsLiveMessage(liveSession, e.origin, e.data)) return;
       const message = parseBridgeMessage(e.data);
       if (!message) return;
 
@@ -439,6 +555,8 @@ export function useHtmlAnnotation({
         && type !== `${PREFIX}mark-click`
         && type !== `${PREFIX}unanchored`
         && type !== `${PREFIX}resize`
+        // Page identity is navigation state, not an annotation mutation.
+        && type !== `${PREFIX}page-change`
       ) {
         return;
       }
@@ -450,25 +568,20 @@ export function useHtmlAnnotation({
         const anchor = positionAnchor(message.rect);
         if (!anchor) return;
 
-        const currentMode = message.modeOverride ?? modeRef.current;
-
-        if (currentMode === "redline") {
-          const id = nextHtmlAnnId();
-          postToIframe(iframeRef.current, { type: `${PREFIX}create-mark`, id, annotationType: "deletion" });
-          onAddRef.current?.({
-            id,
-            blockId: "",
-            startOffset: 0,
-            endOffset: 0,
-            type: AnnotationType.DELETION,
-            originalText: message.text,
-            author: getIdentity(),
-            createdA: Date.now(),
-            htmlAnchor: message.anchor,
-          });
-          pendingTextRef.current = "";
-          pendingAnchorRef.current = null;
-        } else if (
+        // HTML and live-app surfaces are COMMENT-ONLY: redline (auto-DELETION)
+        // and quickLabel are markdown-surface features, so both the host's
+        // mode and any bridge-posted modeOverride clamp to the plain selection
+        // flow here (a hostile page can post modeOverride, so the clamp sits
+        // at the trust boundary, not in the host). Persisted DELETION
+        // annotations still restore through applyAnnotations — only CREATION
+        // is comment-only.
+        const requestedMode = message.modeOverride ?? modeRef.current;
+        const currentMode =
+          requestedMode === "redline" || requestedMode === "quickLabel"
+            ? "selection"
+            : requestedMode;
+
+        if (
           currentMode === "comment"
           // Pinpoint click-to-pin: the click already chose the target, so skip
           // the intermediate toolbar and go straight to the comment composer.
@@ -481,6 +594,7 @@ export function useHtmlAnnotation({
             anchorEl: anchor,
             contextText: message.text,
             selectedText: message.text,
+            draftKey: htmlCommentDraftKey(message.text, message.anchor, message.targetKey),
           });
           // Pinpoint drafts arm shift-click multi-select: the clicked element
           // becomes the primary target of the (single) draft comment. The
@@ -496,16 +610,12 @@ export function useHtmlAnnotation({
                 anchor: message.anchor ?? null,
               },
             ]);
-            postToIframe(iframeRef.current, {
+            post({
               type: `${PREFIX}arm-multi-select`,
               key: message.targetKey,
+              ...(hostCapRef.current ? { max: maxTargetsRef.current } : {}),
             });
           }
-        } else if (currentMode === "quickLabel") {
-          setQuickLabelPicker({
-            anchorEl: anchor,
-            cursorHint: { x: parseFloat(anchor.style.left), y: parseFloat(anchor.style.top) },
-          });
         } else {
           setToolbarState({
             element: anchor,
@@ -523,7 +633,7 @@ export function useHtmlAnnotation({
         if (
           commentPopoverRef.current
           && targets.length > 0
-          && targets.length < 1 + MAX_ADDITIONAL_TARGETS
+          && targets.length < 1 + maxTargetsRef.current
           && !targets.some((t) => t.key === message.key)
         ) {
           setDraftTargets([
@@ -585,7 +695,13 @@ export function useHtmlAnnotation({
         // the typing) — otherwise the iframe keeps focus and the bridge eats keys.
         iframeRef.current?.blur();
         setToolbarState(null);
-        setCommentPopover({ anchorEl: anchor, contextText: text, selectedText: text, initialText: key });
+        setCommentPopover({
+          anchorEl: anchor,
+          contextText: text,
+          selectedText: text,
+          initialText: key,
+          draftKey: htmlCommentDraftKey(text, pendingAnchorRef.current),
+        });
       }
 
       if (type === `${PREFIX}mark-click`) {
@@ -599,6 +715,10 @@ export function useHtmlAnnotation({
       if (type === `${PREFIX}resize`) {
         onResize?.(message.height);
       }
+
+      if (type === `${PREFIX}page-change`) {
+        onPageChangeRef.current?.(message.pageUrl);
+      }
     }
 
     window.addEventListener("message", handler);
@@ -609,7 +729,7 @@ export function useHtmlAnnotation({
         anchorRef.current = null;
       }
     };
-  }, [iframeRef, positionAnchor, onResize, getOrCreateAnchor, applyTargetRemoval]);
+  }, [post, iframeRef, positionAnchor, onResize, getOrCreateAnchor, applyTargetRemoval]);
 
   useEffect(() => {
     if (enabled) return;
@@ -621,22 +741,25 @@ export function useHtmlAnnotation({
     pendingAnchorRef.current = null;
     anchorRef.current?.remove();
     anchorRef.current = null;
-    postToIframe(iframeRef.current, { type: `${PREFIX}cancel-selection` });
-  }, [enabled, iframeRef]);
+    post({ type: `${PREFIX}cancel-selection` });
+  }, [enabled, post]);
 
   useEffect(() => {
     if (selectedAnnotationId) {
-      postToIframe(iframeRef.current, {
+      post({
         type: `${PREFIX}scroll-to`,
         id: selectedAnnotationId,
+        // Only an explicit host preference rides along; the default message
+        // is unchanged and the bridge scrolls smoothly as before.
+        ...(scrollBehavior ? { behavior: scrollBehavior } : {}),
       });
     } else {
-      postToIframe(iframeRef.current, {
+      post({
         type: `${PREFIX}focus-mark`,
         id: null,
       });
     }
-  }, [selectedAnnotationId, iframeRef]);
+  }, [selectedAnnotationId, post, scrollBehavior]);
 
   const handleAnnotate = useCallback(
     (type: AnnotationType) => {
@@ -645,7 +768,8 @@ export function useHtmlAnnotation({
       if (!text || type !== AnnotationType.DELETION) return;
 
       const id = nextHtmlAnnId();
-      postToIframe(iframeRef.current, { type: `${PREFIX}create-mark`, id, annotationType: "deletion" });
+      mintedHtmlAnnIds.add(id);
+      post({ type: `${PREFIX}create-mark`, id, annotationType: "deletion" });
       onAddRef.current?.({
         id,
         blockId: "",
@@ -662,7 +786,7 @@ export function useHtmlAnnotation({
       pendingTextRef.current = "";
       pendingAnchorRef.current = null;
     },
-    [iframeRef],
+    [post],
   );
 
   const handleRequestComment = useCallback(
@@ -672,7 +796,13 @@ export function useHtmlAnnotation({
       if (!text) return;
       const anchor = anchorRef.current ?? getOrCreateAnchor();
       setToolbarState(null);
-      setCommentPopover({ anchorEl: anchor, contextText: text, selectedText: text, initialText: initialChar });
+      setCommentPopover({
+        anchorEl: anchor,
+        contextText: text,
+        selectedText: text,
+        initialText: initialChar,
+        draftKey: htmlCommentDraftKey(text, pendingAnchorRef.current),
+      });
     },
     [getOrCreateAnchor],
   );
@@ -689,7 +819,7 @@ export function useHtmlAnnotation({
       const targets = draftTargetsRef.current;
       const additionalTargets: HtmlAnnotationTarget[] | undefined =
         targets.length > 1
-          ? targets.slice(1, 1 + MAX_ADDITIONAL_TARGETS).map((t) => ({
+          ? targets.slice(1, 1 + maxTargetsRef.current).map((t) => ({
               label: t.label,
               text: t.text,
               anchor: t.anchor ?? undefined,
@@ -697,7 +827,8 @@ export function useHtmlAnnotation({
           : undefined;
 
       const id = nextHtmlAnnId();
-      postToIframe(iframeRef.current, { type: `${PREFIX}create-mark`, id, annotationType: "comment" });
+      mintedHtmlAnnIds.add(id);
+      post({ type: `${PREFIX}create-mark`, id, annotationType: "comment" });
       onAddRef.current?.({
         id,
         blockId: "",
@@ -718,16 +849,61 @@ export function useHtmlAnnotation({
       pendingTextRef.current = "";
       pendingAnchorRef.current = null;
     },
-    [iframeRef],
+    [post],
   );
 
+  // The composer's one-click "Looks good" (the restored thumbs-up for
+  // comment-only surfaces, where pinpoint clicks land straight in the
+  // composer and never see the selection toolbar). Mirrors
+  // handleCommentSubmit — same anchor, same multi-select targets — but
+  // emits the hardcoded positive label instead of typed prose.
+  const handleCommentLooksGood = useCallback(() => {
+    if (!enabledRef.current) return;
+    const text = commentPopoverRef.current?.selectedText || pendingTextRef.current;
+    if (!text) return;
+
+    const targets = draftTargetsRef.current;
+    const additionalTargets: HtmlAnnotationTarget[] | undefined =
+      targets.length > 1
+        ? targets.slice(1, 1 + maxTargetsRef.current).map((t) => ({
+            label: t.label,
+            text: t.text,
+            anchor: t.anchor ?? undefined,
+          }))
+        : undefined;
+
+    const id = nextHtmlAnnId();
+    mintedHtmlAnnIds.add(id);
+    post({ type: `${PREFIX}create-mark`, id, annotationType: "comment" });
+    onAddRef.current?.({
+      id,
+      blockId: "",
+      startOffset: 0,
+      endOffset: 0,
+      type: AnnotationType.COMMENT,
+      text: THUMBS_UP_LABEL.text,
+      originalText: text,
+      isQuickLabel: true,
+      quickLabelTip: THUMBS_UP_LABEL.tip,
+      author: getIdentity(),
+      createdA: Date.now(),
+      htmlAnchor: pendingAnchorRef.current ?? undefined,
+      htmlAdditionalTargets: additionalTargets,
+    });
+
+    setCommentPopover(null);
+    setDraftTargets([]);
+    pendingTextRef.current = "";
+    pendingAnchorRef.current = null;
+  }, [post]);
+
   const handleCommentClose = useCallback(() => {
-    postToIframe(iframeRef.current, { type: `${PREFIX}cancel-selection` });
+    post({ type: `${PREFIX}cancel-selection` });
     setCommentPopover(null);
     setDraftTargets([]);
     pendingTextRef.current = "";
     pendingAnchorRef.current = null;
-  }, [iframeRef]);
+  }, [post]);
 
   const removeDraftTarget = useCallback(
     (key: string) => {
@@ -739,17 +915,17 @@ export function useHtmlAnnotation({
 
   const flashDraftTarget = useCallback(
     (key: string) => {
-      postToIframe(iframeRef.current, { type: `${PREFIX}flash-target`, key });
+      post({ type: `${PREFIX}flash-target`, key });
     },
-    [iframeRef],
+    [post],
   );
 
   const handleToolbarClose = useCallback(() => {
-    postToIframe(iframeRef.current, { type: `${PREFIX}cancel-selection` });
+    post({ type: `${PREFIX}cancel-selection` });
     setToolbarState(null);
     pendingTextRef.current = "";
     pendingAnchorRef.current = null;
-  }, [iframeRef]);
+  }, [post]);
 
   const applyQuickLabel = useCallback(
     (label: QuickLabel, clearState: () => void) => {
@@ -757,7 +933,8 @@ export function useHtmlAnnotation({
       const text = pendingTextRef.current;
       if (!text) return;
       const id = nextHtmlAnnId();
-      postToIframe(iframeRef.current, { type: `${PREFIX}create-mark`, id, annotationType: "comment" });
+      mintedHtmlAnnIds.add(id);
+      post({ type: `${PREFIX}create-mark`, id, annotationType: "comment" });
       onAddRef.current?.({
         id,
         blockId: "",
@@ -776,7 +953,7 @@ export function useHtmlAnnotation({
       pendingTextRef.current = "";
       pendingAnchorRef.current = null;
     },
-    [iframeRef],
+    [post],
   );
 
   const handleQuickLabel = useCallback(
@@ -790,22 +967,22 @@ export function useHtmlAnnotation({
   );
 
   const handleQuickLabelPickerDismiss = useCallback(() => {
-    postToIframe(iframeRef.current, { type: `${PREFIX}cancel-selection` });
+    post({ type: `${PREFIX}cancel-selection` });
     setQuickLabelPicker(null);
     pendingTextRef.current = "";
     pendingAnchorRef.current = null;
-  }, [iframeRef]);
+  }, [post]);
 
   const removeHighlight = useCallback(
     (id: string) => {
-      postToIframe(iframeRef.current, { type: `${PREFIX}remove-mark`, id });
+      post({ type: `${PREFIX}remove-mark`, id });
     },
-    [iframeRef],
+    [post],
   );
 
   const clearAllHighlights = useCallback(() => {
-    postToIframe(iframeRef.current, { type: `${PREFIX}clear-marks` });
-  }, [iframeRef]);
+    post({ type: `${PREFIX}clear-marks` });
+  }, [post]);
 
   const applyAnnotations = useCallback(
     (anns: Annotation[]) => {
@@ -817,8 +994,8 @@ export function useHtmlAnnotation({
         const additionalAnchors = (ann.htmlAdditionalTargets ?? [])
           .map((t) => t.anchor)
           .filter((a): a is HtmlElementAnchor => !!a)
-          .slice(0, MAX_ADDITIONAL_TARGETS);
-        postToIframe(iframeRef.current, {
+          .slice(0, maxTargetsRef.current);
+        post({
           type: `${PREFIX}find-and-mark`,
           id: ann.id,
           originalText: ann.originalText,
@@ -830,7 +1007,7 @@ export function useHtmlAnnotation({
         });
       }
     },
-    [iframeRef],
+    [post],
   );
 
   return {
@@ -842,6 +1019,7 @@ export function useHtmlAnnotation({
     handleToolbarClose,
     handleRequestComment,
     handleCommentSubmit,
+    handleCommentLooksGood,
     handleCommentClose,
     handleFloatingQuickLabel,
     handleQuickLabelPickerDismiss,
@@ -852,5 +1030,6 @@ export function useHtmlAnnotation({
     removeDraftTarget,
     flashDraftTarget,
     composerFocusToken,
+    createdAnnotationIds: mintedHtmlAnnIds,
   };
 }

package/components/plan-diff/PlanCleanDiffView.tsx

@@ -330,6 +330,7 @@ export const PlanCleanDiffView: React.FC<PlanCleanDiffViewProps> = ({
           contextText={commentPopover.contextText}
           isGlobal={false}
           initialText={commentPopover.initialText}
+          draftKey={`plan-diff:${commentPopover.index}:${commentPopover.diffContext}:${commentPopover.contextText}`}
           onSubmit={handleCommentSubmit}
           onClose={handleCommentClose}
           skillReferences

package/components/sidebar/FileBrowser.tsx

@@ -27,6 +27,8 @@ interface FileBrowserProps {
   annotationCounts?: Map<string, number>;
   highlightedFiles?: Set<string>;
   editStatuses?: Map<string, FileEditStatus>;
+  /** Prevent competing destination changes while a document is activating. */
+  selectionPending?: boolean;
 }
 
 export interface FileEditStatus {
@@ -246,7 +248,8 @@ const TreeNode: React.FC<{
   editStatuses?: Map<string, FileEditStatus>;
   workspaceStatus?: WorkspaceStatusPayload;
   forceExpandFolders?: boolean;
-}> = ({ node, depth, dirPath, expandedFolders, onToggleFolder, onSelectFile, activeFile, annotationCounts, highlightedFiles, editStatuses, workspaceStatus, forceExpandFolders = false }) => {
+  selectionPending?: boolean;
+}> = ({ node, depth, dirPath, expandedFolders, onToggleFolder, onSelectFile, activeFile, annotationCounts, highlightedFiles, editStatuses, workspaceStatus, forceExpandFolders = false, selectionPending = false }) => {
   const folderKey = `${dirPath}:${node.path}`;
   const absolutePath = `${dirPath}/${node.path}`;
   const isExpanded = forceExpandFolders || expandedFolders.has(folderKey);
@@ -305,6 +308,7 @@ const TreeNode: React.FC<{
             editStatuses={editStatuses}
             workspaceStatus={workspaceStatus}
             forceExpandFolders={forceExpandFolders}
+            selectionPending={selectionPending}
           />
         ))}
       </>
@@ -347,7 +351,8 @@ const TreeNode: React.FC<{
       onClick={() => {
         if (!isSelectionDisabled) onSelectFile(absolutePath, dirPath);
       }}
-      disabled={isSelectionDisabled}
+      disabled={isSelectionDisabled || selectionPending}
+      aria-busy={isActive && selectionPending ? true : undefined}
       className={`file-tree-item w-full text-left group ${isActive ? "active" : ""} ${fileCount > 0 ? "has-annotations" : ""} ${isHighlighted ? 'file-annotation-flash' : ''} ${isSelectionDisabled ? 'opacity-70 cursor-default' : ''}`}
       style={{ paddingLeft: paddingLeft + 15 }}
       title={isDeleted ? `${node.path} (${editStatus?.status === "missing" ? "missing on disk" : "deleted on disk"})` : node.path}
@@ -357,6 +362,9 @@ const TreeNode: React.FC<{
       </svg>
       <span className={`truncate flex-1 min-w-0 ${isDeleted ? "line-through" : ""}`}>{displayName}</span>
       <div className="ml-auto flex flex-shrink-0 items-center gap-1.5 text-[10px]">
+        {isActive && selectionPending && (
+          <span className="text-primary">Opening…</span>
+        )}
         {editMarker && (
           <span
             className={`inline-flex h-4 min-w-4 items-center justify-center rounded-full px-1 text-[9px] font-semibold leading-none ${editMarker.className}`}
@@ -393,7 +401,8 @@ const DirSection: React.FC<{
   highlightedFiles?: Set<string>;
   editStatuses?: Map<string, FileEditStatus>;
   forceExpandFolders?: boolean;
-}> = ({ dir, expandedFolders, onToggleFolder, onSelectFile, activeFile, onRetry, annotationCounts, highlightedFiles, editStatuses, forceExpandFolders = false }) => {
+  selectionPending?: boolean;
+}> = ({ dir, expandedFolders, onToggleFolder, onSelectFile, activeFile, onRetry, annotationCounts, highlightedFiles, editStatuses, forceExpandFolders = false, selectionPending = false }) => {
   const workspaceStatus = React.useMemo(() => normalizeWorkspaceStatus(dir.workspaceStatus), [dir.workspaceStatus]);
 
   if (dir.isLoading) {
@@ -443,6 +452,7 @@ const DirSection: React.FC<{
           editStatuses={editStatuses}
           workspaceStatus={workspaceStatus}
           forceExpandFolders={forceExpandFolders}
+          selectionPending={selectionPending}
         />
       ))}
     </div>
@@ -462,6 +472,7 @@ export const FileBrowser: React.FC<FileBrowserProps> = ({
   annotationCounts,
   highlightedFiles,
   editStatuses,
+  selectionPending = false,
 }) => {
   const [isFilterOpen, setIsFilterOpen] = React.useState(false);
   const [filterQuery, setFilterQuery] = React.useState("");
@@ -528,7 +539,7 @@ export const FileBrowser: React.FC<FileBrowserProps> = ({
         {showFilterInput ? (
           <div
             onBlur={handleFilterBlur}
-            className="flex h-6 items-center gap-1.5 rounded-sm bg-muted/25 px-1.5 text-muted-foreground focus-within:bg-muted/40"
+            className="file-browser-filter-field flex h-6 items-center gap-1.5 rounded-sm bg-muted/25 px-1.5 text-muted-foreground focus-within:bg-muted/40"
           >
             <Search size={12} className="shrink-0 text-muted-foreground/55" aria-hidden="true" />
             <input
@@ -556,7 +567,7 @@ export const FileBrowser: React.FC<FileBrowserProps> = ({
                   setFilterQuery("");
                   inputRef.current?.focus();
                 }}
-                className="flex h-5 w-5 shrink-0 items-center justify-center rounded-sm text-muted-foreground/55 hover:bg-muted hover:text-foreground focus-visible:outline-none focus-visible:bg-muted"
+                className="file-browser-filter-clear flex h-5 w-5 shrink-0 items-center justify-center rounded-sm text-muted-foreground/55 hover:bg-muted hover:text-foreground focus-visible:outline-none focus-visible:bg-muted"
                 aria-label="Clear file filter"
                 title="Clear file filter"
               >
@@ -617,6 +628,7 @@ export const FileBrowser: React.FC<FileBrowserProps> = ({
                 highlightedFiles={highlightedFiles}
                 editStatuses={editStatuses}
                 forceExpandFolders={isFiltering}
+                selectionPending={selectionPending}
               />
             )}
           </div>