ompchamber 1.0.0 → 1.2.0

package/src/client/hooks/chat/btw/mode.ts

@@ -0,0 +1,179 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * BTW mode: the state behind the side-question form.
+ *
+ * Entering the mode replaces the chat composer with the form itself — an ask
+ * card ("Ask your question", always a new topic) above the side session's
+ * composer (follow-ups to the topic in view). The mode flag, both drafts and
+ * the selected topic live in per-session state, so a reload lands back in the
+ * form the user left and leaving the mode loses nothing.
+ *
+ * `/btw [question]` in the main composer is the entry point; a question that
+ * arrived with the command is asked immediately, which is what the TUI does.
+ */
+
+import { useCallback } from 'preact/hooks';
+import type { BtwState, BtwTopic } from '@/shared/types';
+import { useBtwSession, type BtwImage, type BtwLiveAnswer } from '@/client/hooks/chat/btw';
+import { useChamberEvent } from '@/client/hooks/ui/window-event';
+import { useSessionState } from '@/client/hooks/workspace/session-state';
+import { useSearchParams } from '@/client/lib/router/search-params';
+import { readStreamTransport } from '@/shared/lib/chat/omp/transport';
+
+/** Question sent when a question arrived carrying only images. */
+const ATTACHMENT_ONLY_QUESTION = 'Describe the attached image.';
+
+export interface BtwMode {
+  open: boolean;
+  topics: BtwTopic[];
+  activeTopic: BtwTopic | null;
+  /** Topic with a turn in flight, if any. */
+  runningTopicId: string | null;
+  /** A command is still in flight — the panel holds its actions meanwhile. */
+  busy: boolean;
+  /** Partial answer of the running turn, when it belongs to the active topic. */
+  liveAnswer: string;
+  error: string | null;
+  askDraft: string;
+  followUpDraft: string;
+  setAskDraft: (value: string) => void;
+  setFollowUpDraft: (value: string) => void;
+  /** Open the form on the current history (bare `/btw`). */
+  enter: () => void;
+  /** Leave the form; drafts and history stay. */
+  exit: () => void;
+  /** ⟳ — clear the question in flight and let the newest topic show. */
+  resetQuestion: () => void;
+  /** Submit the ask card: a question of its own. */
+  submitAsk: () => void;
+  /** Submit the side session's composer: a follow-up to the active topic. */
+  submitFollowUp: (question: string, images?: BtwImage[]) => void;
+  abort: () => void;
+  /** Returns the session id to open, or null when promotion was refused. */
+  promote: () => Promise<string | null>;
+  removeTopic: (topicId: string) => void;
+  selectTopic: (topicId: string) => void;
+  clearError: () => void;
+}
+
+export function useBtwMode(sessionId: string | null, appSettings: Record<string, unknown>): BtwMode {
+  const [open, setOpen] = useSessionState<boolean>('chat.btwOpen', false);
+  const [askDraft, setAskDraft] = useSessionState<string>('chat.btwAsk', '');
+  const [followUpDraft, setFollowUpDraft] = useSessionState<string>('chat.btwFollowUp', '');
+  const [selectedTopicId, setSelectedTopicId] = useSessionState<string | null>('chat.btwTopicId', null);
+  const [, setSearchParams] = useSearchParams();
+
+  // `enabled` only gates the stream: the commands must work the moment the form
+  // opens, which is before the stream has attached.
+  const session = useBtwSession(sessionId, {
+    enabled: open && Boolean(sessionId),
+    transport: readStreamTransport(appSettings),
+  });
+
+  const topics = session.state?.topics ?? [];
+  const activeTopic = topics.find((topic) => topic.id === selectedTopicId) ?? topics[topics.length - 1] ?? null;
+  const runningTopicId = session.state?.runningTopicId ?? null;
+  const live: BtwLiveAnswer | null = session.live && session.live.topicId === activeTopic?.id ? session.live : null;
+
+  const selectNewest = useCallback(
+    (next: BtwState | null) => {
+      if (!next) return;
+      setSelectedTopicId(next.topics[next.topics.length - 1]?.id ?? null);
+    },
+    [setSelectedTopicId],
+  );
+
+  // `/btw [question]` hands the question over; a bare `/btw` only opens the
+  // form, which is the history view.
+  useChamberEvent('omp:btw', (event) => {
+    const detail = (event as CustomEvent<{ question?: string; images?: BtwImage[] }>).detail;
+    const question = detail?.question?.trim();
+    setOpen(true);
+    if (question || detail?.images?.length) {
+      setAskDraft('');
+      void session.ask(question || ATTACHMENT_ONLY_QUESTION, detail?.images).then(selectNewest);
+    }
+  });
+
+  const submitAsk = useCallback(() => {
+    const question = askDraft.trim();
+    if (!question) return;
+    setAskDraft('');
+    void session.ask(question).then(selectNewest);
+  }, [askDraft, session, setAskDraft, selectNewest]);
+
+  const submitFollowUp = useCallback(
+    (question: string, images?: BtwImage[]) => {
+      const text = question.trim();
+      if (!text && !images?.length) return;
+      setFollowUpDraft('');
+      // With no topic in view yet, the side session's first question is the
+      // topic — there is nothing to follow up on.
+      void session.ask(text || ATTACHMENT_ONLY_QUESTION, images, activeTopic?.id).then((next) => {
+        if (!activeTopic) selectNewest(next);
+      });
+    },
+    [activeTopic, session, setFollowUpDraft, selectNewest],
+  );
+
+  const promote = useCallback(async () => {
+    if (!activeTopic) return null;
+    const created = await session.promote(activeTopic.id);
+    if (!created) return null;
+    setOpen(false);
+    setSelectedTopicId(null);
+    setSearchParams((prev) => {
+      const next = new URLSearchParams(prev);
+      next.set('sessionId', created);
+      if (next.has('subagent')) next.delete('subagent');
+      return next;
+    });
+    window.dispatchEvent(new CustomEvent('omp:session-updated', { detail: { sessionId: created } }));
+    return created;
+  }, [activeTopic, session, setOpen, setSelectedTopicId, setSearchParams]);
+
+  const removeTopic = useCallback(
+    (topicId: string) => {
+      if (topicId === selectedTopicId) setSelectedTopicId(null);
+      void session.remove(topicId);
+    },
+    [selectedTopicId, session, setSelectedTopicId],
+  );
+
+  return {
+    open,
+    topics,
+    activeTopic,
+    runningTopicId,
+    busy: session.busy,
+    liveAnswer: live ? live.text : '',
+    error: session.error,
+    askDraft,
+    followUpDraft,
+    setAskDraft,
+    setFollowUpDraft,
+    enter: () => setOpen(true),
+    exit: () => setOpen(false),
+    resetQuestion: () => {
+      setAskDraft('');
+      setSelectedTopicId(null);
+      session.clearError();
+    },
+    submitAsk,
+    submitFollowUp,
+    abort: () => {
+      if (runningTopicId) void session.abort(runningTopicId);
+    },
+    promote,
+    removeTopic,
+    selectTopic: (topicId: string) => {
+      setSelectedTopicId(topicId);
+      session.clearError();
+    },
+    clearError: session.clearError,
+  };
+}

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([]);
+  });
+});
+