@plannotator/ui 0.22.0

package/components/AttachmentsButton.tsx

@@ -0,0 +1,410 @@
+import React, { useState, useRef, useEffect } from 'react';
+import { createPortal } from 'react-dom';
+import { ImageThumbnail, getImageSrc } from './ImageThumbnail';
+import { ImageAnnotator } from './ImageAnnotator';
+import type { ImageAttachment } from '../types';
+import { modKey } from '../utils/platform';
+import { getUploadTransport } from '../utils/upload';
+
+/**
+ * Derive a clean, human-readable name from an original filename.
+ * "Login Mockup.png" → "login-mockup"
+ * "annotated.png" or generic names → "image-N"
+ */
+export function deriveImageName(originalName: string, existingNames: string[]): string {
+  const base = originalName.replace(/\.[^.]+$/, '');
+  const generic = ['annotated', 'image', 'screenshot', 'paste', 'clipboard', 'untitled'];
+
+  if (generic.includes(base.toLowerCase())) {
+    let n = 1;
+    while (existingNames.includes(`image-${n}`)) n++;
+    return `image-${n}`;
+  }
+
+  let name = base.toLowerCase()
+    .replace(/[_\s]+/g, '-')
+    .replace(/[^a-z0-9-]/g, '')
+    .replace(/-+/g, '-')
+    .replace(/^-|-$/g, '');
+
+  if (!name) {
+    let n = 1;
+    while (existingNames.includes(`image-${n}`)) n++;
+    return `image-${n}`;
+  }
+
+  if (existingNames.includes(name)) {
+    let n = 2;
+    while (existingNames.includes(`${name}-${n}`)) n++;
+    name = `${name}-${n}`;
+  }
+
+  return name;
+}
+
+interface AttachmentsButtonProps {
+  images: ImageAttachment[];
+  onAdd: (image: ImageAttachment) => void;
+  onRemove: (path: string) => void;
+  variant?: 'toolbar' | 'inline';
+  /** Hide the "Images" label (icon-only). When images.length > 0 the
+   *  numeric badge still shows so the user can see the count. */
+  hideLabel?: boolean;
+}
+
+export const AttachmentsButton: React.FC<AttachmentsButtonProps> = ({
+  images,
+  onAdd,
+  onRemove,
+  variant = 'toolbar',
+  hideLabel = false,
+}) => {
+  const [isOpen, setIsOpen] = useState(false);
+  const [manualPath, setManualPath] = useState('');
+  const [uploading, setUploading] = useState(false);
+  const [dragOver, setDragOver] = useState(false);
+  const buttonRef = useRef<HTMLButtonElement>(null);
+  const fileInputRef = useRef<HTMLInputElement>(null);
+  const [position, setPosition] = useState({ top: 0, left: 0 });
+
+  // Annotator state
+  const [annotatorImage, setAnnotatorImage] = useState<{ file: File; blobUrl: string; initialName: string } | null>(null);
+  const [editingImage, setEditingImage] = useState<{ path: string; name: string } | null>(null);
+
+  // Update popover position when opened
+  useEffect(() => {
+    if (isOpen && buttonRef.current) {
+      const rect = buttonRef.current.getBoundingClientRect();
+      setPosition({
+        top: rect.bottom + 8,
+        left: Math.max(8, rect.left - 100), // Center-ish, but keep on screen
+      });
+    }
+  }, [isOpen]);
+
+  // Close on escape
+  useEffect(() => {
+    const handleKeyDown = (e: KeyboardEvent) => {
+      if (e.key === 'Escape' && isOpen) {
+        setIsOpen(false);
+      }
+    };
+    window.addEventListener('keydown', handleKeyDown);
+    return () => window.removeEventListener('keydown', handleKeyDown);
+  }, [isOpen]);
+
+  // Paste image from clipboard when popover is open (per-annotation attachments).
+  // Uses capture phase + stopPropagation to prevent the global paste handler in
+  // App.tsx from also processing the same event.
+  useEffect(() => {
+    if (!isOpen || annotatorImage) return;
+    const handlePaste = (e: ClipboardEvent) => {
+      const items = e.clipboardData?.items;
+      if (!items) return;
+      for (const item of items) {
+        if (item.type.startsWith('image/')) {
+          e.preventDefault();
+          e.stopPropagation();
+          const file = item.getAsFile();
+          if (file) handleFileSelect(file);
+          return;
+        }
+      }
+    };
+    document.addEventListener('paste', handlePaste, true);
+    return () => document.removeEventListener('paste', handlePaste, true);
+  }, [isOpen, annotatorImage]);
+
+  const handleFileSelect = (file: File) => {
+    // Derive name before opening annotator so user sees it immediately
+    const initialName = deriveImageName(file.name, images.map(i => i.name));
+    const blobUrl = URL.createObjectURL(file);
+    setAnnotatorImage({ file, blobUrl, initialName });
+    setIsOpen(false); // Close popover when annotator opens
+  };
+
+  const handleAnnotatorAccept = async (blob: Blob, hasDrawings: boolean, name: string) => {
+    setUploading(true);
+    try {
+      // Use annotated blob if drawings exist, otherwise original file
+      const fileToUpload = annotatorImage
+        ? (hasDrawings
+            ? new File([blob], 'annotated.png', { type: 'image/png' })
+            : annotatorImage.file)
+        : editingImage
+          // Re-editing: always upload the new blob
+          ? new File([blob], 'annotated.png', { type: 'image/png' })
+          : null;
+
+      if (fileToUpload) {
+        const data = await getUploadTransport().upload(fileToUpload);
+        if (data.path) {
+          // If re-editing, remove old path first
+          if (editingImage) {
+            onRemove(editingImage.path);
+          }
+          // Use the name from the annotator (user may have edited it)
+          onAdd({ path: data.path, name });
+        }
+      }
+    } catch (err) {
+      console.error('Upload failed:', err);
+    } finally {
+      setUploading(false);
+      // Cleanup
+      if (annotatorImage) {
+        URL.revokeObjectURL(annotatorImage.blobUrl);
+        setAnnotatorImage(null);
+      }
+      setEditingImage(null);
+    }
+  };
+
+  const handleAnnotatorClose = () => {
+    if (annotatorImage) {
+      URL.revokeObjectURL(annotatorImage.blobUrl);
+      setAnnotatorImage(null);
+    }
+    setEditingImage(null);
+  };
+
+  const handleFileInputChange = (e: React.ChangeEvent<HTMLInputElement>) => {
+    const file = e.target.files?.[0];
+    if (file) {
+      handleFileSelect(file);
+    }
+    e.target.value = ''; // Reset for re-selection
+  };
+
+  const handleDrop = (e: React.DragEvent) => {
+    e.preventDefault();
+    setDragOver(false);
+    const file = e.dataTransfer.files[0];
+    if (file && file.type.startsWith('image/')) {
+      handleFileSelect(file);
+    }
+  };
+
+  const handleManualAdd = () => {
+    const trimmed = manualPath.trim();
+    if (trimmed) {
+      const name = deriveImageName(
+        trimmed.split('/').pop() || 'image',
+        images.map(i => i.name)
+      );
+      onAdd({ path: trimmed, name });
+      setManualPath('');
+    }
+  };
+
+  const handleClearAll = (e: React.MouseEvent) => {
+    e.stopPropagation();
+    images.forEach(img => onRemove(img.path));
+  };
+
+  // Determine annotator props
+  const annotatorOpen = !!annotatorImage || !!editingImage;
+  const annotatorSrc = annotatorImage?.blobUrl ?? (editingImage ? getImageSrc(editingImage.path) : '');
+  const annotatorInitialName = annotatorImage?.initialName ?? editingImage?.name ?? '';
+
+  return (
+    <>
+      {/* Trigger Button */}
+      <button
+        ref={buttonRef}
+        type="button"
+        onClick={() => setIsOpen(!isOpen)}
+        aria-label="Attachments"
+        title="Attachments"
+        className="group relative flex items-center gap-1.5 px-2 py-1.5 rounded-md text-xs font-medium text-muted-foreground hover:text-foreground hover:bg-muted/50 transition-colors"
+      >
+        {/* Show stacked thumbnails if we have images */}
+        {images.length > 0 ? (
+          <>
+            <div className="relative flex items-center">
+              {images.slice(0, 3).map((img, idx) => (
+                <div
+                  key={img.path}
+                  className="relative w-5 h-5 rounded border border-background"
+                  style={{ marginLeft: idx > 0 ? '-6px' : 0, zIndex: 3 - idx }}
+                >
+                  <img
+                    src={getImageSrc(img.path)}
+                    alt={img.name}
+                    loading="lazy"
+                    className="w-5 h-5 rounded object-cover"
+                  />
+                </div>
+              ))}
+              {images.length > 3 && (
+                <div
+                  className="relative w-5 h-5 rounded bg-muted border border-background flex items-center justify-center text-[9px] font-medium"
+                  style={{ marginLeft: '-6px', zIndex: 0 }}
+                >
+                  +{images.length - 3}
+                </div>
+              )}
+            </div>
+            {/* Clear all button on hover */}
+            <button
+              onClick={handleClearAll}
+              className="absolute -top-1 -right-1 w-3.5 h-3.5 bg-destructive text-destructive-foreground rounded-full opacity-0 group-hover:opacity-100 transition-opacity flex items-center justify-center"
+            >
+              <svg className="w-2 h-2" fill="none" viewBox="0 0 24 24" stroke="currentColor" strokeWidth={3}>
+                <path strokeLinecap="round" strokeLinejoin="round" d="M6 18L18 6M6 6l12 12" />
+              </svg>
+            </button>
+          </>
+        ) : (
+          <svg className="w-4 h-4" fill="none" viewBox="0 0 24 24" stroke="currentColor" strokeWidth={2}>
+            <path strokeLinecap="round" strokeLinejoin="round" d="M2.25 15.75l5.159-5.159a2.25 2.25 0 013.182 0l5.159 5.159m-1.5-1.5l1.409-1.409a2.25 2.25 0 013.182 0l2.909 2.909m-18 3.75h16.5a1.5 1.5 0 001.5-1.5V6a1.5 1.5 0 00-1.5-1.5H3.75A1.5 1.5 0 002.25 6v12a1.5 1.5 0 001.5 1.5zm10.5-11.25h.008v.008h-.008V8.25zm.375 0a.375.375 0 11-.75 0 .375.375 0 01.75 0z" />
+          </svg>
+        )}
+        {(!hideLabel || images.length > 0) && (
+          <span className={variant === 'inline' ? 'sr-only' : ''}>
+            {images.length > 0 ? `${images.length}` : 'Images'}
+          </span>
+        )}
+      </button>
+
+      {/* Popover */}
+      {isOpen && createPortal(
+        <>
+          {/* Backdrop */}
+          <div
+            className="fixed inset-0 z-[90]"
+            data-popover-layer
+            onClick={() => setIsOpen(false)}
+          />
+
+          {/* Popover content */}
+          <div
+            className="fixed z-[100] w-72 bg-card border border-border rounded-xl shadow-2xl p-3"
+            data-popover-layer
+            style={{ top: position.top, left: position.left }}
+            onClick={e => e.stopPropagation()}
+          >
+            <div className="space-y-3">
+              {/* Header */}
+              <div className="flex items-center justify-between">
+                <div className="text-sm font-medium">Attachments</div>
+                {images.length > 0 && (
+                  <span className="text-[10px] text-muted-foreground">
+                    {images.length} image{images.length !== 1 ? 's' : ''}
+                  </span>
+                )}
+              </div>
+              <p className="text-[11px] text-muted-foreground -mt-1">
+                Add images to include with your feedback
+              </p>
+
+              {/* Drop zone / file picker */}
+              <div
+                onDragOver={(e) => { e.preventDefault(); setDragOver(true); }}
+                onDragLeave={() => setDragOver(false)}
+                onDrop={handleDrop}
+                onClick={() => fileInputRef.current?.click()}
+                className={`flex flex-col items-center justify-center gap-2 px-3 py-4 border-2 border-dashed rounded-lg cursor-pointer transition-colors ${
+                  dragOver
+                    ? 'border-primary bg-primary/5'
+                    : 'border-border hover:border-muted-foreground'
+                }`}
+              >
+                {uploading ? (
+                  <div className="flex items-center gap-2 text-muted-foreground">
+                    <svg className="w-4 h-4 animate-spin" fill="none" viewBox="0 0 24 24">
+                      <circle className="opacity-25" cx="12" cy="12" r="10" stroke="currentColor" strokeWidth="4" />
+                      <path className="opacity-75" fill="currentColor" d="M4 12a8 8 0 018-8V0C5.373 0 0 5.373 0 12h4zm2 5.291A7.962 7.962 0 014 12H0c0 3.042 1.135 5.824 3 7.938l3-2.647z" />
+                    </svg>
+                    <span className="text-xs">Uploading...</span>
+                  </div>
+                ) : (
+                  <>
+                    <svg className="w-6 h-6 text-muted-foreground" fill="none" viewBox="0 0 24 24" stroke="currentColor" strokeWidth={1.5}>
+                      <path strokeLinecap="round" strokeLinejoin="round" d="M3 16.5v2.25A2.25 2.25 0 005.25 21h13.5A2.25 2.25 0 0021 18.75V16.5m-13.5-9L12 3m0 0l4.5 4.5M12 3v13.5" />
+                    </svg>
+                    <span className="text-xs text-muted-foreground">
+                      Drop image or click to browse
+                    </span>
+                    <span className="text-[10px] text-muted-foreground/70">
+                      {modKey}+V to paste from clipboard
+                    </span>
+                  </>
+                )}
+              </div>
+              <input
+                ref={fileInputRef}
+                type="file"
+                accept="image/*"
+                onChange={handleFileInputChange}
+                className="hidden"
+              />
+
+              {/* Manual path input */}
+              <div className="flex gap-2">
+                <input
+                  type="text"
+                  value={manualPath}
+                  onChange={(e) => setManualPath(e.target.value)}
+                  onKeyDown={(e) => e.key === 'Enter' && !e.nativeEvent.isComposing && handleManualAdd()}
+                  placeholder="Paste path or URL..."
+                  className="flex-1 px-2 py-1.5 text-xs bg-background border border-border rounded-md focus:outline-none focus:ring-1 focus:ring-primary"
+                />
+                <button
+                  type="button"
+                  onClick={handleManualAdd}
+                  disabled={!manualPath.trim()}
+                  className="px-2 py-1.5 text-xs font-medium bg-primary text-primary-foreground rounded-md hover:opacity-90 disabled:opacity-50 disabled:cursor-not-allowed"
+                >
+                  Add
+                </button>
+              </div>
+
+              {/* Grid of current attachments */}
+              {images.length > 0 && (
+                <div className="space-y-2">
+                  <div className="text-xs text-muted-foreground">Current</div>
+                  <div className="grid grid-cols-4 gap-2">
+                    {images.map((img) => (
+                      <div key={img.path} className="text-center">
+                        <ImageThumbnail
+                          path={img.path}
+                          size="md"
+                          onClick={() => {
+                            setEditingImage({ path: img.path, name: img.name });
+                            setIsOpen(false);
+                          }}
+                          onRemove={() => onRemove(img.path)}
+                          showRemove
+                        />
+                        <div
+                          className="text-[9px] text-muted-foreground truncate max-w-[3.5rem] mt-0.5 mx-auto"
+                          title={img.name}
+                        >
+                          {img.name}
+                        </div>
+                      </div>
+                    ))}
+                  </div>
+                </div>
+              )}
+            </div>
+          </div>
+        </>,
+        document.body
+      )}
+
+      {/* Image Annotator Dialog - portaled to body for correct positioning */}
+      {annotatorOpen && createPortal(
+        <ImageAnnotator
+          isOpen={annotatorOpen}
+          imageSrc={annotatorSrc}
+          initialName={annotatorInitialName}
+          onAccept={handleAnnotatorAccept}
+          onClose={handleAnnotatorClose}
+        />,
+        document.body
+      )}
+    </>
+  );
+};

package/components/BlockRenderer.tsx

@@ -0,0 +1,163 @@
+import React from "react";
+import { Block } from "../types";
+import { InlineMarkdown } from "./InlineMarkdown";
+import { ListItemBody } from "./ListItemBody";
+import { CodeBlock } from "./blocks/CodeBlock";
+import { HtmlBlock } from "./blocks/HtmlBlock";
+import { Callout } from "./blocks/Callout";
+import { AlertBlock } from "./blocks/AlertBlock";
+import { TableBlock } from "./blocks/TableBlock";
+import { MathBlock } from "./blocks/MathBlock";
+
+export const BlockRenderer: React.FC<{
+  block: Block;
+  onOpenLinkedDoc?: (path: string) => void;
+  onOpenCodeFile?: (path: string) => void;
+  imageBaseDir?: string;
+  onImageClick?: (src: string, alt: string) => void;
+  onToggleCheckbox?: (blockId: string, checked: boolean) => void;
+  checkboxOverrides?: Map<string, boolean>;
+  orderedIndex?: number | null;
+  githubRepo?: string;
+  headingAnchorId?: string;
+  onNavigateAnchor?: (hash: string) => void;
+}> = ({ block, onOpenLinkedDoc, onOpenCodeFile, imageBaseDir, onImageClick, onToggleCheckbox, checkboxOverrides, orderedIndex, githubRepo, headingAnchorId, onNavigateAnchor }) => {
+  switch (block.type) {
+    case 'heading': {
+      const Tag = `h${block.level || 1}` as React.ElementType;
+      const styles = {
+        1: 'text-2xl font-bold mb-4 mt-6 first:mt-0 tracking-tight',
+        2: 'text-xl font-semibold mb-3 mt-8 text-foreground/90',
+        3: 'text-base font-semibold mb-2 mt-6 text-foreground/80',
+      }[block.level || 1] || 'text-base font-semibold mb-2 mt-4';
+      return (
+        <Tag
+          id={headingAnchorId}
+          className={styles}
+          data-block-id={block.id}
+          data-block-type="heading"
+        >
+          <InlineMarkdown imageBaseDir={imageBaseDir} onImageClick={onImageClick} text={block.content} onOpenLinkedDoc={onOpenLinkedDoc} onOpenCodeFile={onOpenCodeFile} githubRepo={githubRepo} onNavigateAnchor={onNavigateAnchor} />
+        </Tag>
+      );
+    }
+
+    case 'blockquote': {
+      if (block.alertKind) {
+        return (
+          <AlertBlock
+            blockId={block.id}
+            kind={block.alertKind}
+            body={block.content}
+            onOpenLinkedDoc={onOpenLinkedDoc}
+            onOpenCodeFile={onOpenCodeFile}
+            imageBaseDir={imageBaseDir}
+            onImageClick={onImageClick}
+            githubRepo={githubRepo}
+            onNavigateAnchor={onNavigateAnchor}
+          />
+        );
+      }
+      // Content may span multiple merged `>` lines. Split on blank-line
+      // paragraph breaks so `> a\n>\n> b` renders as two <p> children.
+      const paragraphs = block.content.split(/\n\n+/);
+      return (
+        <blockquote
+          className="border-l-2 border-primary/50 pl-4 my-4 text-muted-foreground italic"
+          data-block-id={block.id}
+        >
+          {paragraphs.map((para, i) => (
+            <p key={i} className={i > 0 ? 'mt-2' : ''}>
+              <InlineMarkdown imageBaseDir={imageBaseDir} onImageClick={onImageClick} text={para} onOpenLinkedDoc={onOpenLinkedDoc} onOpenCodeFile={onOpenCodeFile} githubRepo={githubRepo} onNavigateAnchor={onNavigateAnchor} />
+            </p>
+          ))}
+        </blockquote>
+      );
+    }
+
+    case 'list-item': {
+      const indent = (block.level || 0) * 1.25; // 1.25rem per level
+      const isCheckbox = block.checked !== undefined;
+      const isChecked = checkboxOverrides?.has(block.id)
+        ? checkboxOverrides.get(block.id)!
+        : block.checked;
+      const isInteractive = isCheckbox && !!onToggleCheckbox;
+      const textClass = `text-sm leading-relaxed ${isCheckbox && isChecked ? 'text-muted-foreground line-through' : 'text-foreground/90'}`;
+      const inlineProps = { imageBaseDir, onImageClick, onOpenLinkedDoc, onOpenCodeFile, githubRepo, onNavigateAnchor };
+      return (
+        <div
+          className="flex items-start gap-3 my-1.5"
+          data-block-id={block.id}
+          style={{ marginLeft: `${indent}rem` }}
+        >
+          <ListItemBody
+            level={block.level || 0}
+            ordered={block.ordered}
+            orderedIndex={orderedIndex}
+            checked={isChecked}
+            interactive={isInteractive}
+            onToggle={isInteractive ? () => onToggleCheckbox!(block.id, !isChecked) : undefined}
+            textClassName={textClass}
+            content={block.content}
+            renderInline={(text) => <InlineMarkdown {...inlineProps} text={text} />}
+          />
+        </div>
+      );
+    }
+
+    case 'code':
+      return <CodeBlock block={block} onHover={() => {}} onLeave={() => {}} isHovered={false} />;
+
+    case 'table':
+      return (
+        <TableBlock
+          block={block}
+          imageBaseDir={imageBaseDir}
+          onImageClick={onImageClick}
+          onOpenLinkedDoc={onOpenLinkedDoc}
+          onOpenCodeFile={onOpenCodeFile}
+          githubRepo={githubRepo}
+          onNavigateAnchor={onNavigateAnchor}
+        />
+      );
+
+    case 'math':
+      return <MathBlock block={block} />;
+
+    case 'hr':
+      return <hr className="border-border/30 my-8" data-block-id={block.id} />;
+
+    case 'html':
+      return <HtmlBlock block={block} imageBaseDir={imageBaseDir} onOpenLinkedDoc={onOpenLinkedDoc} onOpenCodeFile={onOpenCodeFile} onNavigateAnchor={onNavigateAnchor} />;
+
+    case 'directive': {
+      const kind = block.directiveKind || 'note';
+      return (
+        <Callout
+          blockId={block.id}
+          kind={kind}
+          body={block.content}
+          containerClassName={`directive directive-${kind} my-4 px-4 py-3 rounded-md border`}
+          blockType="directive"
+          kindAttribute={kind}
+          onOpenLinkedDoc={onOpenLinkedDoc}
+          onOpenCodeFile={onOpenCodeFile}
+          imageBaseDir={imageBaseDir}
+          onImageClick={onImageClick}
+          githubRepo={githubRepo}
+          onNavigateAnchor={onNavigateAnchor}
+        />
+      );
+    }
+
+    default:
+      return (
+        <p
+          className="mb-4 leading-relaxed text-foreground/90 text-[15px]"
+          data-block-id={block.id}
+        >
+          <InlineMarkdown imageBaseDir={imageBaseDir} onImageClick={onImageClick} text={block.content} onOpenLinkedDoc={onOpenLinkedDoc} onOpenCodeFile={onOpenCodeFile} githubRepo={githubRepo} onNavigateAnchor={onNavigateAnchor} />
+        </p>
+      );
+  }
+};

package/components/BorderTrail.tsx

@@ -0,0 +1,38 @@
+import { motion, type Transition } from 'motion/react';
+
+export interface BorderTrailProps {
+  className?: string;
+  size?: number;
+  transition?: Transition;
+  style?: React.CSSProperties;
+}
+
+export function BorderTrail({
+  className,
+  size = 60,
+  transition,
+  style,
+}: BorderTrailProps) {
+  const defaultTransition: Transition = {
+    repeat: Infinity,
+    duration: 5,
+    ease: 'linear',
+  };
+
+  return (
+    <div className="pointer-events-none absolute inset-0 rounded-[inherit] border border-transparent [mask-clip:padding-box,border-box] [mask-composite:intersect] [mask-image:linear-gradient(transparent,transparent),linear-gradient(#000,#000)]">
+      <motion.div
+        className={['absolute aspect-square bg-zinc-500', className].filter(Boolean).join(' ')}
+        style={{
+          width: size,
+          offsetPath: `rect(0 auto auto 0 round ${size}px)`,
+          ...style,
+        }}
+        animate={{
+          offsetDistance: ['0%', '100%'],
+        }}
+        transition={transition ?? defaultTransition}
+      />
+    </div>
+  );
+}

package/components/CodeFilePicker.tsx

@@ -0,0 +1,64 @@
+import React, { useEffect, useRef, useState } from "react";
+import { createPortal } from "react-dom";
+import { useDismissOnOutsideAndEscape } from "../hooks/useDismissOnOutsideAndEscape";
+
+/**
+ * Floating popover anchored to a code-file link with multiple repo matches.
+ * Selecting an entry calls `onPick(path)`. Esc / outside-click dismisses.
+ */
+export const CodeFilePicker: React.FC<{
+	anchorEl: HTMLElement | null;
+	matches: string[];
+	onPick: (path: string) => void;
+	onDismiss: () => void;
+}> = ({ anchorEl, matches, onPick, onDismiss }) => {
+	const popoverRef = useRef<HTMLDivElement>(null);
+	const [pos, setPos] = useState<{ top: number; left: number } | null>(null);
+
+	useEffect(() => {
+		if (!anchorEl) return;
+		const rect = anchorEl.getBoundingClientRect();
+		setPos({
+			top: rect.bottom + 4,
+			left: rect.left,
+		});
+	}, [anchorEl]);
+
+	useDismissOnOutsideAndEscape({
+		enabled: true,
+		ref: popoverRef as React.RefObject<HTMLElement>,
+		onDismiss,
+	});
+
+	if (!pos) return null;
+
+	return createPortal(
+		<div
+			ref={popoverRef}
+			role="menu"
+			aria-label="Choose file"
+			className="fixed z-[100] min-w-[240px] max-w-[480px] bg-popover text-popover-foreground border border-border/70 rounded-lg shadow-xl py-1"
+			style={{ top: pos.top, left: pos.left }}
+		>
+			<div className="px-3 py-1.5 text-xs uppercase tracking-wide opacity-60 border-b border-border/40">
+				{matches.length} matches
+			</div>
+			<ul className="max-h-72 overflow-y-auto">
+				{matches.map((m) => (
+					<li key={m}>
+						<button
+							type="button"
+							role="menuitem"
+							onClick={() => onPick(m)}
+							className="w-full text-left px-3 py-1.5 text-sm font-mono hover:bg-muted hover:text-primary transition-colors truncate"
+							title={m}
+						>
+							{m}
+						</button>
+					</li>
+				))}
+			</ul>
+		</div>,
+		document.body,
+	);
+};