ompchamber 1.1.0 → 1.2.1

package/src/client/hooks/chat/composer/attachments.ts

@@ -0,0 +1,198 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * Attachment lifecycle for the composer: accept a batch of files (picker,
+ * paste, or OS drop), gate the text ones against the inline budget, hold blob
+ * previews, and read the bytes into the attachment.
+ *
+ * Bytes are read AT ATTACH TIME, not at send time. A `File` handed over by a
+ * drop or a paste is a live handle onto the drag data store, and reading it
+ * later — after the composer has re-rendered, or after the drag that produced
+ * it has ended — is what made a dropped file arrive with an empty body while
+ * its chip still rendered. Reading once, here, means every later step (send,
+ * queue, retry) works from the persisted copy.
+ *
+ * Two shapes of "no content yet" have to be told apart, and getting it wrong is
+ * what produced a prompt sent with no message at all:
+ *
+ * - A file from another app arrives as a PROMISE: the entry exists before its
+ *   bytes do, so the first read comes back empty. That read is retried.
+ * - A genuinely empty file reads empty forever. It is accepted as-is.
+ *
+ * Only a read that stays empty while the file claims bytes is a failure, and a
+ * failure is always reported — never silently omitted.
+ */
+
+import { useCallback, useRef } from 'preact/hooks';
+import type { SetStateAction } from 'preact/compat';
+import type { Attachment } from '@/shared/types';
+import { applyTextAttachmentBudget, isTextAttachment, looksLikeTextFile } from '@/shared/lib/chat/attachments';
+import { delay, primedPrefix, readAsDataUrl, readFileTextWithRetry } from '@/client/hooks/chat/composer/file-reads';
+import type { PrimedReads } from '@/client/hooks/chat/composer/file-reads';
+
+export interface UseComposerAttachmentsOptions {
+  /** Current attachments; the text budget is measured against them. */
+  attachments: Attachment[];
+  setAttachments: (updater: SetStateAction<Attachment[]>) => void;
+}
+
+export interface AddFilesOutcome {
+  /** How many files were attached. */
+  added: number;
+  /** Files refused by the inline text budget, for the caller to report. */
+  skipped: File[];
+  /** Names of files whose contents could not be read, for the caller to report. */
+  unreadable: string[];
+}
+
+export interface ComposerAttachments {
+  /**
+   * Reads every accepted file before resolving, so `unreadable` is complete.
+   *
+   * `primed` carries the reads already started inside the drop handler. Passing
+   * it is not an optimization: a dropped `File` can only be read from a read
+   * begun while the drop's permission was live, so a batch that arrives without
+   * one is the batch that fails. See `file-reads.ts`.
+   */
+  addFiles: (files: File[], primed?: PrimedReads) => Promise<AddFilesOutcome>;
+  removeAttachment: (id: string) => void;
+  /**
+   * Wait for every in-flight read, then return the attachments AS THEY STAND
+   * once those reads have landed.
+   *
+   * The list is returned rather than left to the caller because a read patches
+   * the stored attachment: a caller that captured the array before waiting
+   * would still hold the pre-read entry — the one with no content — and send
+   * that.
+   */
+  readyForSend: () => Promise<Attachment[]>;
+  /**
+   * The attachment list as of right now, read synchronously.
+   *
+   * A drop registers its files in this hook before the enclosing component has
+   * re-rendered, so the component's own `attachments` prop lags by a frame.
+   * Deciding a send from that prop lost the attachment entirely: a send clicked
+   * immediately after a drop saw an empty list, cleared the composer and
+   * dispatched a prompt with nothing in it.
+   */
+  peek: () => Attachment[];
+  /** Empty the composer (state and the hook's own list together). */
+  clear: () => void;
+}
+
+export function useComposerAttachments({
+  attachments,
+  setAttachments,
+}: UseComposerAttachmentsOptions): ComposerAttachments {
+  // In-flight work, so a send can wait for a batch it cannot see the end of.
+  const pendingReadsRef = useRef(new Set<Promise<void>>());
+  // The authoritative list. It is mirrored into the prop on every render, and
+  // updated here the moment this hook changes it — the component has not
+  // re-rendered yet at that point, so the prop is a frame behind.
+  const attachmentsRef = useRef(attachments);
+  attachmentsRef.current = attachments;
+  const setBoth = useCallback((next: Attachment[]) => {
+    attachmentsRef.current = next;
+    setAttachments(next);
+  }, [setAttachments]);
+
+  const addFiles = useCallback(async (files: File[], primed?: PrimedReads): Promise<AddFilesOutcome> => {
+    const { accepted, skipped } = applyTextAttachmentBudget(files, attachments);
+    if (accepted.length === 0) return { added: 0, skipped, unreadable: [] };
+
+    // Display fields are captured at creation: a File does not survive the
+    // queue's JSON round trip or committed history, and every replay path reads
+    // these instead of `file`.
+    const newAttachments: Attachment[] = accepted.map((file) => ({
+      id: Math.random().toString(36).substring(7),
+      name: file.name,
+      type: file.type,
+      size: file.size,
+      file,
+      preview: file.type.startsWith('image/') ? URL.createObjectURL(file) : '',
+    }));
+    setBoth([...attachmentsRef.current, ...newAttachments]);
+
+    const { promise: batch, resolve } = Promise.withResolvers<void>();
+    pendingReadsRef.current.add(batch);
+    const unreadable: string[] = [];
+    try {
+      await Promise.all(newAttachments.map(async (att) => {
+        const file = att.file;
+        if (!file) return;
+        // The read resolves after this call returns, so it addresses the entry
+        // by id — a captured array would be a pre-update snapshot.
+        const store = (patch: Partial<Attachment>) => {
+          setBoth(attachmentsRef.current.map((a) => (a.id === att.id ? { ...a, ...patch } : a)));
+        };
+        const label = att.name ?? file.name;
+
+        if (file.type.startsWith('image/')) {
+          const base64 = await readAsDataUrl(file, primed);
+          if (base64) store({ dataBase64: base64 });
+          else unreadable.push(label);
+          return;
+        }
+
+        // Metadata answers for a classified file; anything else is decided by
+        // its bytes, because a promised-file drag names itself `document` and
+        // reports no type.
+        const classified = isTextAttachment(att);
+        const content = await readFileTextWithRetry(file, primed);
+        if (content === null) {
+          unreadable.push(label);
+          return;
+        }
+        if (content.length === 0) {
+          // Nothing came back. A promised file whose bytes never arrive reads
+          // empty on every attempt, so this is the only place the user can be
+          // told — waiting for the send would just produce an empty prompt.
+          unreadable.push(label);
+          return;
+        }
+        const prefix = await primedPrefix(file, primed);
+        if (!classified && !(await looksLikeTextFile(file, prefix))) {
+          return;
+        }
+        // The marker travels with the content: without it the send path would
+        // re-classify from the same uninformative name and drop it again.
+        store({ content, ...(classified ? {} : { sniffedText: true }) });
+      }));
+    } finally {
+      pendingReadsRef.current.delete(batch);
+      resolve();
+    }
+
+    return { added: newAttachments.length, skipped, unreadable };
+  }, [attachments, setAttachments]);
+
+  const removeAttachment = useCallback((id: string) => {
+    const att = attachmentsRef.current.find((p) => p.id === id);
+    if (att?.preview.startsWith('blob:')) URL.revokeObjectURL(att.preview);
+    setBoth(attachmentsRef.current.filter((p) => p.id !== id));
+  }, [setBoth]);
+
+  const peek = useCallback(() => attachmentsRef.current, []);
+
+  const clear = useCallback(() => {
+    attachmentsRef.current = [];
+    setAttachments([]);
+  }, [setAttachments]);
+
+  const readyForSend = useCallback(async (): Promise<Attachment[]> => {
+    // A batch that finishes during this loop is removed from the set, so the
+    // snapshot below is the complete in-flight set at the time of the call.
+    while (pendingReadsRef.current.size > 0) {
+      await Promise.all([...pendingReadsRef.current]);
+    }
+    // Yield once so the state updates those reads queued are committed before
+    // the list is read back.
+    await delay(0);
+    return attachmentsRef.current;
+  }, []);
+
+  return { addFiles, removeAttachment, readyForSend, peek, clear };
+}

package/src/client/hooks/chat/composer/drop-entries.ts

@@ -0,0 +1,204 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * Turning a `DataTransfer` into the flat list of `File`s a drop attaches.
+ *
+ * Split out of `file-drop.ts`, which owns the event wiring: everything here is
+ * about reading the payload, and it is the part with the browser rules worth
+ * documenting.
+ *
+ * Two rules, both of which produced a bug when ignored:
+ *
+ * 1. A dropped DIRECTORY is not a readable File: `dataTransfer.files` carries a
+ *    size-0 stub for it. Only `DataTransferItem.webkitGetAsEntry()` reveals it
+ *    as a directory, so those are walked recursively and attached file by file.
+ * 2. `getAsFile()` and `webkitGetAsEntry()` are read from the SAME item, and on
+ *    a file-manager drag each call can consume state the other needs — so the
+ *    item list is read exactly ONCE, capturing both views in a single pass.
+ *
+ * The `File`s this returns are only as good as the tick they were captured in:
+ * a dropped file's read permission is released when the drop handler returns,
+ * so `file-drop.ts` primes the reads before awaiting anything. See `file-reads.ts`.
+ */
+
+/**
+ * Safety valve: a dropped tree (a repo root, `node_modules`) must not queue
+ * thousands of attachments. The walk stops as soon as it is reached.
+ */
+export const MAX_DROPPED_FILES = 50;
+
+/** Directory nesting limit — a symlinked cycle would otherwise never end. */
+export const MAX_DROP_DEPTH = 10;
+
+function readEntryFile(entry: FileSystemFileEntry): Promise<File | null> {
+  const { promise, resolve } = Promise.withResolvers<File | null>();
+  entry.file(resolve, () => resolve(null));
+  return promise;
+}
+
+/** `readEntries` yields at most 100 children per call; keep pulling until empty. */
+function readAllEntries(reader: FileSystemDirectoryReader): Promise<FileSystemEntry[]> {
+  const { promise, resolve } = Promise.withResolvers<FileSystemEntry[]>();
+  const all: FileSystemEntry[] = [];
+  const readBatch = () => {
+    reader.readEntries((batch) => {
+      if (batch.length === 0) {
+        resolve(all);
+        return;
+      }
+      all.push(...batch);
+      readBatch();
+    }, () => resolve(all));
+  };
+  readBatch();
+  return promise;
+}
+
+/** Walk one directory tree into `out`; true when a cap stopped the walk early. */
+async function walkDirectory(
+  directory: FileSystemDirectoryEntry,
+  out: File[],
+  depth: number,
+): Promise<boolean> {
+  if (depth >= MAX_DROP_DEPTH) return true;
+  const children = await readAllEntries(directory.createReader());
+  for (const child of children) {
+    if (out.length >= MAX_DROPPED_FILES) return true;
+    if (child.isFile) {
+      const file = await readEntryFile(child as FileSystemFileEntry);
+      if (file) out.push(file);
+    } else if (child.isDirectory) {
+      if (await walkDirectory(child as FileSystemDirectoryEntry, out, depth + 1)) return true;
+    }
+  }
+  return false;
+}
+
+/**
+ * The two views of a drop's item list, captured in ONE pass.
+ *
+ * `getAsFile()` and `webkitGetAsEntry()` must both be read from the same item,
+ * and on a file-manager drag each call can consume state the other needs. Two
+ * separate loops over `items` therefore lose one of them; this captures both
+ * while the item is still fresh.
+ *
+ * `dataTransfer.files` is the PREFERRED source of the `File` objects, not the
+ * item list. On a file-manager drag the two are not interchangeable: the item
+ * entry can carry correct metadata (name, size) over a backing store that no
+ * longer reads, while `files` hands over one that does. Preferring the item list
+ * produced a chip with the right name and size whose contents never arrived, and
+ * the failure survived every retry because the object itself was unreadable.
+ * `files` is also what the working reference implementations read first.
+ *
+ * The item list still earns its place: it is the ONLY way to see a dropped
+ * DIRECTORY (`files` carries a size-0 stub for one), and it is the fallback for
+ * a host that populates only `items`.
+ */
+export interface DroppedEntries {
+  /** Real `File` objects, stubs excluded when a better entry exists. */
+  files: File[];
+  /** Directory entries, for the recursive walk. */
+  directories: FileSystemDirectoryEntry[];
+  /**
+   * The other `File` object for the same dropped file, when the payload exposed
+   * it twice — once through `dataTransfer.files`, once through the item list.
+   *
+   * Which of the two is readable is not knowable up front and differs by
+   * context: a drop that reads fine in a browser tab has been observed to fail
+   * in an installed app window, with the failing object still reporting the
+   * correct name and size. So this is a pair to try, not a preference to settle,
+   * and the read path falls back to this entry when the primary yields nothing.
+   */
+  fallbacks: Map<File, File>;
+}
+
+export function readDroppedEntries(dt: DataTransfer): DroppedEntries {
+  const itemFiles: File[] = [];
+  const directories: FileSystemDirectoryEntry[] = [];
+
+  for (const item of Array.from(dt.items ?? [])) {
+    if (item.kind !== 'file') continue;
+    // Order matters: the entry first, then the file, in the same iteration.
+    const entry = typeof item.webkitGetAsEntry === 'function' ? item.webkitGetAsEntry() : null;
+    if (entry?.isDirectory) {
+      directories.push(entry as FileSystemDirectoryEntry);
+      continue;
+    }
+    const file = typeof item.getAsFile === 'function' ? item.getAsFile() : null;
+    // A directory arrives as a 0-byte, type-less stub; it is not a file to read.
+    if (file && (file.size > 0 || file.type !== '')) itemFiles.push(file);
+  }
+
+  const direct = Array.from(dt.files ?? []);
+  const directWithBytes = direct.filter((file) => file.size > 0);
+  const itemsWithBytes = itemFiles.filter((file) => file.size > 0);
+
+  // `files` first, then the item list, then whatever exists. Every step keeps
+  // the counterpart as a fallback so a read can try the other object rather than
+  // depend on this choice being the right one.
+  if (directWithBytes.length > 0) {
+    return { files: directWithBytes, directories, fallbacks: pairByName(directWithBytes, itemFiles) };
+  }
+  if (itemsWithBytes.length > 0) {
+    return { files: itemsWithBytes, directories, fallbacks: pairByName(itemsWithBytes, direct) };
+  }
+  if (itemFiles.length > 0) {
+    return { files: itemFiles, directories, fallbacks: pairByName(itemFiles, direct) };
+  }
+  return { files: direct, directories, fallbacks: new Map() };
+}
+
+/**
+ * Pair each primary file with its counterpart of the same name, so the read path
+ * has something else to try. Matching is by name because that is all the two
+ * views of one dropped file reliably share.
+ */
+function pairByName(primary: readonly File[], others: readonly File[]): Map<File, File> {
+  const byName = new Map<string, File>();
+  for (const file of others) {
+    if (!byName.has(file.name)) byName.set(file.name, file);
+  }
+  const pairs = new Map<File, File>();
+  for (const file of primary) {
+    const other = byName.get(file.name);
+    if (other && other !== file) pairs.set(file, other);
+  }
+  return pairs;
+}
+
+/**
+ * Expand a drop into the flat file list the composer attaches: the files it
+ * already carries plus every directory's contents, walked recursively.
+ * `incomplete` reports that a cap cut the drop short, so the composer can say so
+ * instead of silently attaching a prefix.
+ *
+ * Takes the entries rather than the `DataTransfer`: see {@link readDroppedEntries}
+ * for why the item list may only be read once.
+ */
+export async function expandDroppedFiles(
+  entries: DroppedEntries,
+): Promise<{ files: File[]; incomplete: boolean }> {
+  const files: File[] = [...entries.files];
+
+  // No directory in the payload: the flat list is already the answer.
+  if (entries.directories.length === 0) {
+    return { files: files.slice(0, MAX_DROPPED_FILES), incomplete: files.length > MAX_DROPPED_FILES };
+  }
+
+  let incomplete = false;
+  for (const directory of entries.directories) {
+    if (files.length >= MAX_DROPPED_FILES) {
+      incomplete = true;
+      break;
+    }
+    if (await walkDirectory(directory, files, 0)) {
+      incomplete = true;
+      break;
+    }
+  }
+  return { files: files.slice(0, MAX_DROPPED_FILES), incomplete };
+}
+

package/src/client/hooks/chat/composer/drop-payload.test.ts

@@ -0,0 +1,97 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * Reading a drop's payload.
+ *
+ * Hosts describe a dragged file in incompatible ways, and the difference decides
+ * whether the drop is accepted at all. Two failures this pins:
+ *
+ * - Gating on the `Files` type alone rejected every drag that carries no File —
+ *   a download dragged out of WhatsApp Web offers only a URL in `DownloadURL`,
+ *   and a bare path arrives as `text/plain`.
+ * - Accepting `text/plain` on its own would turn every text selection into a
+ *   file drag, so a path-bearing payload only counts when it actually looks like
+ *   a path or URL.
+ */
+
+import { describe, expect, test } from 'bun:test';
+import { collectDroppedFileUris, hasDraggedFiles } from '@/client/hooks/chat/composer/drop-payload';
+
+function transfer(types: Record<string, string>, files: File[] = [], items: DataTransferItem[] = []): DataTransfer {
+  return {
+    types: Object.keys(types),
+    files: files as unknown as FileList,
+    items: items as unknown as DataTransferItemList,
+    getData: (type: string) => types[type] ?? types[type.toLowerCase()] ?? '',
+  } as unknown as DataTransfer;
+}
+
+describe('hasDraggedFiles', () => {
+  test('a real file list is always a file drag', () => {
+    const file = new File(['x'], 'a.txt', { type: 'text/plain' });
+    expect(hasDraggedFiles(transfer({}, [file]))).toBe(true);
+  });
+
+  test('a browser download with no File is still a file drag', () => {
+    // WhatsApp Web / Gmail / Slack: the payload is a URL, nothing else.
+    expect(hasDraggedFiles(transfer({
+      'text/plain': 'https://web.whatsapp.com/download/xyz.txt',
+      DownloadURL: 'text/plain:xyz.txt:https://web.whatsapp.com/download/xyz.txt',
+    }))).toBe(true);
+  });
+
+  test('a uri-list is a file drag', () => {
+    expect(hasDraggedFiles(transfer({ 'text/uri-list': 'file:///repo/a.ts' }))).toBe(true);
+  });
+
+  test('a bare absolute path is a file drag', () => {
+    expect(hasDraggedFiles(transfer({ 'text/plain': '/repo/a.ts' }))).toBe(true);
+    expect(hasDraggedFiles(transfer({ 'text/plain': '~/notes.md' }))).toBe(true);
+    expect(hasDraggedFiles(transfer({ 'text/plain': 'C:\\repo\\a.ts' }))).toBe(true);
+  });
+
+  test('selected prose is NOT a file drag', () => {
+    // Otherwise every text selection would light up the drop target.
+    expect(hasDraggedFiles(transfer({ 'text/plain': 'just some selected words' }))).toBe(false);
+    expect(hasDraggedFiles(transfer({ 'text/plain': 'see /repo/a.ts for details' }))).toBe(false);
+    expect(hasDraggedFiles(transfer({}))).toBe(false);
+    expect(hasDraggedFiles(null)).toBe(false);
+  });
+
+  test('the check is case-insensitive', () => {
+    // Chrome lowercases the declared types; some hosts do not.
+    expect(hasDraggedFiles(transfer({ Files: '' }))).toBe(true);
+    expect(hasDraggedFiles(transfer({ DownloadURL: 'https://x/y.txt' }))).toBe(true);
+  });
+});
+
+describe('collectDroppedFileUris', () => {
+  test('reads a uri-list, skipping comments and blanks', () => {
+    const dt = transfer({ 'text/uri-list': '# a comment\nfile:///repo/a.ts\n\nfile:///repo/b.ts' });
+    expect(collectDroppedFileUris(dt)).toEqual(['file:///repo/a.ts', 'file:///repo/b.ts']);
+  });
+
+  test('prefers a file URL over the bare path on the same drag', () => {
+    // macOS puts both on a Finder drag; one file must not become two entries.
+    const dt = transfer({ 'text/uri-list': 'file:///repo/a.ts', 'text/plain': '/repo/a.ts' });
+    expect(collectDroppedFileUris(dt)).toEqual(['file:///repo/a.ts']);
+  });
+
+  test('ignores a payload that is not a path or URL', () => {
+    expect(collectDroppedFileUris(transfer({ 'text/plain': 'hello world' }))).toEqual([]);
+    expect(collectDroppedFileUris(transfer({ 'text/plain': 'line one\nline two' }))).toEqual([]);
+  });
+
+  test('keeps a remote download URL', () => {
+    expect(collectDroppedFileUris(transfer({ DownloadURL: 'https://x.example/f.txt' }))).toEqual(['https://x.example/f.txt']);
+  });
+
+  test('an unreadable data store yields nothing instead of throwing', () => {
+    const dt = { getData: () => { throw new Error('not allowed during dragover'); } } as unknown as DataTransfer;
+    expect(collectDroppedFileUris(dt)).toEqual([]);
+  });
+});
+

package/src/client/hooks/chat/composer/drop-payload.ts

@@ -0,0 +1,130 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * Reading a drop's payload.
+ *
+ * Every host describes a dragged file differently, and the differences decide
+ * whether a drop is accepted at all:
+ *
+ * - A file manager (Finder, Explorer, Nautilus) exposes real `File` entries.
+ *   macOS additionally attaches a `text/plain` item carrying the absolute path,
+ *   so the item list holds a `string` entry beside the `file` one.
+ * - A browser page dragging a DOWNLOAD (WhatsApp Web, Gmail, Slack) has no File
+ *   at all: it offers a URL in `DownloadURL` / `text/uri-list`. Gating on the
+ *   `Files` type rejected those outright, which is why a file dragged out of
+ *   WhatsApp never attached.
+ * - VS Code's explorer offers only proprietary types whose payloads must be
+ *   parsed for paths.
+ *
+ * These helpers answer the three questions the composer asks of a
+ * `DataTransfer`, and are pure so they can be exercised without a browser.
+ *
+ * `getData` throws in some hosts when called during `dragover` rather than
+ * `drop`; every read is guarded so one unreadable type cannot abort the scan.
+ */
+
+
+/** Data types that, by their presence alone, mean files are being dragged. */
+const FILE_BEARING_TYPES = ['files', 'text/uri-list', 'codefiles', 'downloadurl'];
+
+/** Types whose payload is a path or URL to resolve, not a readable File. */
+const PATH_BEARING_TYPES = ['text/uri-list', 'downloadurl', 'text/plain', 'codefiles'];
+
+/** Data type marking a drag that started in the chamber's own file tree. */
+export const INTERNAL_FILE_PATH_TYPE = 'application/x-chamber-file-path';
+
+/**
+ * Read one declared type's payload.
+ *
+ * `getData` is case-sensitive while the format names hosts use are not: Chrome
+ * reports `downloadurl` in `types` after a page set `DownloadURL`, and a
+ * lowercase lookup misses it. The declared list is the ground truth, so the
+ * requested type is matched against it first and the host's own spelling is used
+ * for the read.
+ */
+function readData(dataTransfer: DataTransfer, type: string): string {
+  try {
+    const declared = dataTransfer.types ? Array.from(dataTransfer.types) : [];
+    const match = declared.find((candidate) => candidate.toLowerCase() === type.toLowerCase());
+    return match ? dataTransfer.getData(match) : '';
+  } catch {
+    return '';
+  }
+}
+
+/**
+ * Whether this drag carries files at all — the gate for showing the drop target
+ * and for cancelling the browser's own handling.
+ *
+ * Checked on dragenter/dragover, where payloads are often unreadable, so the
+ * declared types are the primary signal and the file list is the fallback for
+ * hosts that declare nothing useful. A `text/plain` payload is NOT accepted on
+ * its own: that would make every text selection a drop target.
+ */
+export function hasDraggedFiles(dataTransfer: DataTransfer | null | undefined): boolean {
+  if (!dataTransfer) {
+    return false;
+  }
+  if (dataTransfer.files && dataTransfer.files.length > 0) {
+    return true;
+  }
+
+  const types = dataTransfer.types ? Array.from(dataTransfer.types).map((type) => type.toLowerCase()) : [];
+  if (FILE_BEARING_TYPES.some((type) => types.includes(type))) {
+    return true;
+  }
+  if (types.some((type) => type.includes('vnd.code.tree'))) {
+    return true;
+  }
+
+  // A path-bearing type only counts when its payload looks like a path or URL:
+  // `text/plain` alone is how every text selection arrives, and treating that as
+  // a file drag would make the drop target light up for ordinary prose.
+  const references = collectDroppedFileUris(dataTransfer);
+  return references.length > 0;
+}
+
+/** True for a payload that is a path or URL rather than a document body. */
+function looksLikeFileReference(value: string): boolean {
+  const candidate = value.trim();
+  if (!candidate || candidate.includes('\n')) return false;
+  if (/^(file|https?):\/\/\S+$/i.test(candidate)) return true;
+  // A POSIX absolute path, a `~` path, or a Windows drive path.
+  return /^(~\/|\/|[A-Za-z]:[\\/])\S*$/.test(candidate);
+}
+
+/**
+ * File references from a drop that carries no `File` objects — a download
+ * dragged out of a web page, or VS Code handing over paths.
+ *
+ * macOS puts up to two payloads on the same drag: a `text/uri-list` with a
+ * `file://` URL and a `text/plain` with the bare path. `file://` wins outright
+ * when present, because the bare path is the same file spelled less precisely —
+ * collecting both would attach one file twice.
+ */
+export function collectDroppedFileUris(dataTransfer: DataTransfer | null | undefined): string[] {
+  if (!dataTransfer || typeof dataTransfer.getData !== 'function') return [];
+
+  const references: string[] = [];
+  const seen = new Set<string>();
+  const add = (value: string) => {
+    const candidate = value.trim();
+    // A uri-list is newline-separated and may carry `#` comments.
+    for (const line of candidate.split('\n')) {
+      const entry = line.trim();
+      if (!entry || entry.startsWith('#') || !looksLikeFileReference(entry)) continue;
+      if (seen.has(entry)) continue;
+      seen.add(entry);
+      references.push(entry);
+    }
+  };
+
+  for (const type of PATH_BEARING_TYPES) {
+    if (type === 'text/plain' && references.length > 0) continue;
+    add(readData(dataTransfer, type));
+  }
+  return references;
+}