ompchamber 1.0.0 → 1.2.0

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

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

@@ -0,0 +1,106 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * Turning a dropped file REFERENCE into an attachable File.
+ *
+ * A download dragged out of a web page (WhatsApp Web, Gmail, Slack) hands the
+ * composer a URL, not bytes: there is no `File` in the drag at all. The browser
+ * cannot read it either — a cross-origin `file://` path and a remote URL are
+ * both outside what the page may fetch. The chamber server can, so the
+ * reference is resolved there and returned as text the composer attaches like
+ * any other file.
+ *
+ * Only text is supported on this path. An image or an arbitrary binary cannot
+ * round-trip through JSON as a string, and the drop's own `File` (when the host
+ * provides one) is the path that carries those.
+ */
+
+
+/** Last path segment of a URL or path, for the attachment's display name. */
+export function referenceName(reference: string): string {
+  const withoutQuery = reference.split(/[?#]/)[0] ?? reference;
+  const segment = withoutQuery.replace(/\/+$/, '').split('/').pop();
+  if (!segment) return 'attachment';
+  try {
+    return decodeURIComponent(segment);
+  } catch {
+    return segment;
+  }
+}
+
+/** Why a dropped reference could not be turned into a file. */
+export type ReferenceFailure =
+  /** The path exists but lies outside the roots the chamber may read. */
+  | 'outside-roots'
+  /** A URL from a web page; the chamber does not fetch outbound. */
+  | 'remote'
+  /** The path exists but its contents are not text (an image, an archive). */
+  | 'binary'
+  /** The server could not read it at all — gone, or an unreadable permission. */
+  | 'unavailable';
+
+export type ReferenceReadResult =
+  | { ok: true; file: File }
+  | { ok: false; reason: ReferenceFailure };
+
+/**
+ * Read a dropped reference through the server.
+ *
+ * `path` is used as the filesystem root hint so a relative reference resolves
+ * inside the active workspace; an absolute path or URL ignores it. The failure
+ * carries its REASON because the three cases need three different actions from
+ * the user, and a single "could not be read" left them with no way to tell them
+ * apart — or the developer with no way to tell which branch ran.
+ */
+export async function readDroppedReference(reference: string, rootPath: string | null): Promise<ReferenceReadResult> {
+  const params = new URLSearchParams({ path: reference });
+  if (rootPath) params.set('root', rootPath);
+  const url = `/api/fs/read-reference?${params.toString()}`;
+  let res: Response;
+  try {
+    res = await fetch(url);
+  } catch (error) {
+    return { ok: false, reason: 'unavailable' };
+  }
+  const body = (await res.json().catch(() => null)) as { content?: unknown; name?: unknown; error?: unknown } | null;
+  if (!res.ok) {
+    const error = typeof body?.error === 'string' ? body.error : '';
+    if (/remote/i.test(error)) return { ok: false, reason: 'remote' };
+    if (/image|raw/i.test(error)) return { ok: false, reason: 'binary' };
+    if (res.status === 404 || /not found/i.test(error)) return { ok: false, reason: 'outside-roots' };
+    return { ok: false, reason: 'unavailable' };
+  }
+  if (!body || typeof body.content !== 'string') return { ok: false, reason: 'unavailable' };
+  // The server reports the basename it actually read, which is more reliable
+  // than re-deriving one from a percent-encoded URL.
+  const name = typeof body.name === 'string' && body.name ? body.name : referenceName(reference);
+  return { ok: true, file: new File([body.content], name, { type: 'text/plain' }) };
+}
+
+/** User-facing reason for files whose contents could not be read. */
+export function describeUnreadable(names: string[]): string {
+  if (names.length === 1) {
+    return `"${names[0]}" could not be read and was not attached.`;
+  }
+  return `${names.length} files could not be read and were not attached: ${names.slice(0, 3).join(', ')}${names.length > 3 ? '…' : ''}.`;
+}
+
+/** User-facing reason for a dropped reference the server refused, per cause. */
+export function describeReferenceFailure(names: string[], reason: ReferenceFailure): string {
+  const list = names.slice(0, 3).join(', ');
+  const subject = names.length === 1 ? `"${names[0]}"` : `${names.length} files`;
+  const tail = names.length > 3 ? '…' : '';
+  switch (reason) {
+    case 'outside-roots':
+      return `${subject} lie${names.length === 1 ? 's' : ''} outside the folders the chamber may read, so ${names.length === 1 ? 'it was' : 'they were'} not attached (${list}${tail}).`;
+    case 'remote':
+      return `${subject} ${names.length === 1 ? 'is a web download' : 'are web downloads'}; save ${names.length === 1 ? 'it' : 'them'} into a workspace folder first (${list}${tail}).`;
+    case 'binary':
+      return `${subject} ${names.length === 1 ? 'is not' : 'are not'} a text file and ${names.length === 1 ? 'was' : 'were'} not attached (${list}${tail}).`;
+    default:
+      return describeUnreadable(names);
+  }
+}

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

@@ -0,0 +1,194 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * Dropped-directory resolution for the composer.
+ *
+ * The browser APIs this reads (`webkitGetAsEntry`, `readEntries`) are awkward
+ * in ways that fail silently: a directory's `dataTransfer.files` entry is a
+ * size-0 stub, and `readEntries` returns at most 100 children per call, so a
+ * single call looks like a complete directory of ≤100 files. These tests pin
+ * the contract those quirks break — recursive expansion, paged reads, and the
+ * caps that keep a dropped repo root from queueing thousands of attachments.
+ */
+
+import { describe, expect, test } from 'bun:test';
+import { carriesBytes } from '@/client/hooks/chat/composer/file-drop';
+import {
+  expandDroppedFiles,
+  readDroppedEntries,
+  MAX_DROPPED_FILES,
+} from '@/client/hooks/chat/composer/drop-entries';
+
+function fileEntry(name: string, content = 'x'): FileSystemFileEntry {
+  return {
+    isFile: true,
+    isDirectory: false,
+    name,
+    file: (ok: (f: File) => void) => ok(new File([content], name, { type: 'text/plain' })),
+  } as unknown as FileSystemFileEntry;
+}
+
+/** Directory whose reader hands back `children` in fixed-size batches. */
+function dirEntry(name: string, children: FileSystemEntry[], batchSize = 100): FileSystemDirectoryEntry {
+  return {
+    isFile: false,
+    isDirectory: true,
+    name,
+    createReader: () => {
+      let cursor = 0;
+      return {
+        readEntries: (ok: (batch: FileSystemEntry[]) => void) => {
+          const batch = children.slice(cursor, cursor + batchSize);
+          cursor += batchSize;
+          ok(batch);
+        },
+      } as unknown as FileSystemDirectoryReader;
+    },
+  } as unknown as FileSystemDirectoryEntry;
+}
+
+function fakeDataTransfer(
+  items: { entry: FileSystemEntry | null; file?: File }[],
+  files: File[] = [],
+): DataTransfer {
+  return {
+    items: items.map(({ entry, file }) => ({
+      kind: 'file',
+      webkitGetAsEntry: () => entry,
+      getAsFile: () => file ?? null,
+    })),
+    files,
+  } as unknown as DataTransfer;
+}
+
+describe('readDroppedEntries', () => {
+  // The two views are not interchangeable: the item entry can carry correct
+  // metadata over a backing store that no longer reads, while `files` hands over
+  // one that does. A drop in an installed app window exposed exactly that — the
+  // chip had the right name and size and its contents never arrived, because the
+  // item-list File was the one being read.
+  test('the file list wins over the item list when it holds bytes', () => {
+    const fromItems = new File(['from items'], 'notes.md', { type: 'text/markdown' });
+    const fromFiles = new File(['from files'], 'notes.md', { type: 'text/markdown' });
+    const entries = readDroppedEntries(fakeDataTransfer([{ entry: fileEntry('notes.md'), file: fromItems }], [fromFiles]));
+
+    expect(entries.files.length).toBe(1);
+    expect(entries.files[0]).toBe(fromFiles);
+  });
+
+  // A 0-byte stub in `files` is how a DIRECTORY is listed, so taking it would
+  // attach an empty file in place of the tree the walk is about to expand.
+  test('a stub in the file list falls through to the item entry', () => {
+    const stub = new File([], 'notes.md', { type: '' });
+    const real = new File(['# Title\n\nBody'], 'notes.md', { type: 'text/markdown' });
+    const entries = readDroppedEntries(fakeDataTransfer([{ entry: fileEntry('notes.md'), file: real }], [stub]));
+
+    expect(entries.files.length).toBe(1);
+    expect(entries.files[0].size).toBeGreaterThan(0);
+  });
+
+  test('falls back to the item list when the file list is empty', () => {
+    const fromItems = new File(['item body'], 'only-items.txt', { type: 'text/plain' });
+    const entries = readDroppedEntries(fakeDataTransfer([{ entry: fileEntry('only-items.txt'), file: fromItems }]));
+
+    expect(entries.files.map((f) => f.name)).toEqual(['only-items.txt']);
+  });
+
+  test('stubs are kept when nothing else holds bytes', () => {
+    const stub = new File([], 'from-a-page.txt', { type: 'text/plain' });
+    const entries = readDroppedEntries(fakeDataTransfer([], [stub]));
+
+    expect(entries.files.map((f) => f.name)).toEqual(['from-a-page.txt']);
+  });
+
+  test('passes plain files through untouched', async () => {
+    const file = new File(['a'], 'a.txt', { type: 'text/plain' });
+    const { files, incomplete } = await expandDroppedFiles(
+      readDroppedEntries(fakeDataTransfer([{ entry: fileEntry('a.txt'), file }])),
+    );
+    expect(files.map((f: File) => f.name)).toEqual(['a.txt']);
+    expect(incomplete).toBe(false);
+  });
+
+  test('expands a dropped directory recursively', async () => {
+    const root = dirEntry('root', [
+      fileEntry('a.txt'),
+      dirEntry('sub', [fileEntry('b.txt'), dirEntry('deeper', [fileEntry('c.txt')])]),
+    ]);
+    const { files, incomplete } = await expandDroppedFiles(readDroppedEntries(fakeDataTransfer([{ entry: root }])));
+    expect(files.map((f: File) => f.name).sort()).toEqual(['a.txt', 'b.txt', 'c.txt']);
+    expect(incomplete).toBe(false);
+  });
+
+  test('keeps paging past the 100-children-per-read limit', async () => {
+    const many = Array.from({ length: 250 }, (_, i) => fileEntry(`f${i}.txt`));
+    const { files, incomplete } = await expandDroppedFiles(readDroppedEntries(fakeDataTransfer([{ entry: dirEntry('big', many) }])));
+    expect(files.length).toBe(MAX_DROPPED_FILES);
+    // More files existed than were taken, and the caller must be able to say so.
+    expect(incomplete).toBe(true);
+  });
+
+  test('stops at the nesting cap instead of walking a cycle forever', async () => {
+    let nested: FileSystemEntry = dirEntry('leaf', [fileEntry('deep.txt')]);
+    for (let i = 0; i < 14; i += 1) nested = dirEntry(`wrap${i}`, [nested]);
+    const { incomplete } = await expandDroppedFiles(readDroppedEntries(fakeDataTransfer([{ entry: nested }])));
+    expect(incomplete).toBe(true);
+  });
+
+  test('falls back to the flat file list when no item entries exist', async () => {
+    const listed = Array.from({ length: MAX_DROPPED_FILES + 10 }, (_, i) => new File(['x'], `g${i}.txt`));
+    const { files, incomplete } = await expandDroppedFiles(readDroppedEntries(fakeDataTransfer([], listed)));
+    expect(files.length).toBe(MAX_DROPPED_FILES);
+    expect(incomplete).toBe(true);
+  });
+
+  test('tolerates a directory whose read fails', async () => {
+    const broken = {
+      isFile: false,
+      isDirectory: true,
+      name: 'broken',
+      createReader: () => ({
+        readEntries: (_ok: unknown, err?: (e: unknown) => void) => err?.(new Error('denied')),
+      }),
+    } as unknown as FileSystemDirectoryEntry;
+    const { files, incomplete } = await expandDroppedFiles(readDroppedEntries(fakeDataTransfer([{ entry: broken }])));
+    expect(files).toEqual([]);
+    expect(incomplete).toBe(false);
+  });
+});
+
+describe('carriesBytes', () => {
+  test('a file whose declared size is 0 but holds bytes counts', async () => {
+    // A .md dropped from Finder can report size 0 while its bytes are present.
+    // Treating that as a "path stub" routed it to the reference resolver, which
+    // only reads inside the allow-list — a file in ~/Downloads was refused with
+    // no way for the user to tell why.
+    const real = new File([new TextEncoder().encode('# Title\n\nBody')], 'notes.md', { type: '' });
+    Object.defineProperty(real, 'size', { value: 0 });
+    expect(real.size).toBe(0);
+    expect(await carriesBytes([real])).toBe(true);
+  });
+
+  test('a declared size above zero is enough without reading', async () => {
+    const file = new File([new Uint8Array([1, 2, 3])], 'a.bin', { type: 'application/octet-stream' });
+    expect(await carriesBytes([file])).toBe(true);
+  });
+
+  test('a genuine stub holds nothing, so the reference path still runs', async () => {
+    const stub = new File([], 'from-a-web-page.txt', { type: 'text/plain' });
+    expect(await carriesBytes([stub])).toBe(false);
+  });
+
+  test('one readable file in a batch is enough', async () => {
+    const empty = new File([], 'empty.txt', { type: 'text/plain' });
+    const real = new File([new Uint8Array([65])], 'real.txt', { type: 'text/plain' });
+    expect(await carriesBytes([empty, real])).toBe(true);
+  });
+
+  test('an empty batch carries nothing', async () => {
+    expect(await carriesBytes([])).toBe(false);
+  });
+});

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

@@ -0,0 +1,226 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * OS file drag-and-drop for the chat composer.
+ *
+ * Three browser rules shape this module:
+ *
+ * 1. A `drop` is only delivered when the preceding `dragover` was cancelled, so
+ *    the handlers belong on the whole composer card — a drop aimed at the
+ *    textarea bubbles up to it, and cancelling there also suppresses the
+ *    browser's own "insert the dropped file's path as text" default.
+ * 2. 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.
+ * 3. A file dropped anywhere the app does not cancel lands in the tab as
+ *    `file://` navigation, which throws the chamber away. The guard below is
+ *    window-wide for exactly that reason; it only ever cancels file drags, so
+ *    text and URL drops keep their native behaviour.
+ *
+ * What counts as a file drag is decided in `drop-payload.ts`, because hosts
+ * disagree: a download dragged out of a web page offers no File at all, only a
+ * URL, and those references are handed back to the caller to resolve.
+ *
+ * The drag data store is cleared the moment the drop handler returns, so every
+ * store-bound read (`getAsFile`, `webkitGetAsEntry`, `getData`) happens
+ * synchronously; the entries and Files they return stay valid while the walk
+ * awaits.
+ */
+
+import { useCallback, useEffect, useRef, useState } from 'preact/hooks';
+import type { TargetedDragEvent } from 'preact';
+import { collectDroppedFileUris, hasDraggedFiles } from '@/client/hooks/chat/composer/drop-payload';
+import { primeFileReads, primedPrefix } from '@/client/hooks/chat/composer/file-reads';
+import type { PrimedReads } from '@/client/hooks/chat/composer/file-reads';
+import {
+  expandDroppedFiles,
+  readDroppedEntries,
+  MAX_DROP_DEPTH,
+  MAX_DROPPED_FILES,
+} from '@/client/hooks/chat/composer/drop-entries';
+import type { DroppedEntries } from '@/client/hooks/chat/composer/drop-entries';
+
+/** Reason shown when a drop yielded more than the composer can take. */
+export const DROP_LIMIT_NOTICE =
+  `Some files were skipped — a drop is limited to ${MAX_DROPPED_FILES} files and ${MAX_DROP_DEPTH} folder levels deep.`;
+
+export interface UseFileDropOptions {
+  /**
+   * Called once per drop with every file it resolved to (directories expanded),
+   * plus any file REFERENCES the host offered instead of bytes (a download
+   * dragged out of a web page) for the caller to resolve server-side.
+   */
+  onFiles: (files: File[], incomplete: boolean, references: string[], primed: PrimedReads) => void;
+  /** While true a drop is cancelled but not attached — the composer is closed. */
+  disabled?: boolean;
+}
+
+/** Drag handlers to spread onto the drop target. */
+export interface FileDropProps {
+  onDragEnter: (e: TargetedDragEvent<HTMLElement>) => void;
+  onDragOver: (e: TargetedDragEvent<HTMLElement>) => void;
+  onDragLeave: (e: TargetedDragEvent<HTMLElement>) => void;
+  onDrop: (e: TargetedDragEvent<HTMLElement>) => void;
+}
+
+export interface UseFileDropResult {
+  /** True while a file drag hovers the bound element (drives the overlay). */
+  isDragging: boolean;
+  dropProps: FileDropProps;
+}
+
+export function useFileDrop({ onFiles, disabled = false }: UseFileDropOptions): UseFileDropResult {
+  const [isDragging, setIsDragging] = useState(false);
+  // dragenter/dragleave fire for every nested child the pointer crosses, so a
+  // boolean flag drops to false the instant the cursor moves from the card onto
+  // the textarea. Counting them keeps the overlay steady.
+  const depthRef = useRef(0);
+  // Latest callback and flag behind refs, so the handlers stay referentially
+  // stable and the window guard sees the current `disabled`.
+  const onFilesRef = useRef(onFiles);
+  onFilesRef.current = onFiles;
+  const disabledRef = useRef(disabled);
+  disabledRef.current = disabled;
+
+  const reset = useCallback(() => {
+    depthRef.current = 0;
+    setIsDragging(false);
+  }, []);
+
+  // A drag can end without reaching this element again — released over the
+  // page, cancelled with Escape, or its source node unmounted mid-drag. The
+  // composer's own handlers have already run by the time these fire, so this
+  // only clears state the drop handler did not.
+  useEffect(() => {
+    window.addEventListener('dragend', reset);
+    window.addEventListener('drop', reset);
+    return () => {
+      window.removeEventListener('dragend', reset);
+      window.removeEventListener('drop', reset);
+    };
+  }, [reset]);
+
+  // Files dropped anywhere else would navigate the tab to `file://` and discard
+  // the chamber, so the default is cancelled app-wide. This runs after the
+  // composer's own drop handler (the event bubbles up to window), by which point
+  // that handler has already read the data store it needed.
+  useEffect(() => {
+    const guard = (e: DragEvent) => {
+      if (hasDraggedFiles(e.dataTransfer)) e.preventDefault();
+    };
+    window.addEventListener('dragover', guard);
+    window.addEventListener('drop', guard);
+    return () => {
+      window.removeEventListener('dragover', guard);
+      window.removeEventListener('drop', guard);
+    };
+  }, []);
+
+  const onDragEnter = useCallback((e: TargetedDragEvent<HTMLElement>) => {
+    if (!hasDraggedFiles(e.dataTransfer)) return;
+    e.preventDefault();
+    if (disabledRef.current) return;
+    depthRef.current += 1;
+    setIsDragging(true);
+  }, []);
+
+  const onDragOver = useCallback((e: TargetedDragEvent<HTMLElement>) => {
+    if (!hasDraggedFiles(e.dataTransfer)) return;
+    // Required: without it the browser refuses the drop and navigates to the
+    // file instead of handing it to the app.
+    e.preventDefault();
+    if (!e.dataTransfer) return;
+    // `none` is the only cursor that tells the truth about a closed composer.
+    e.dataTransfer.dropEffect = disabledRef.current ? 'none' : 'copy';
+  }, []);
+
+  // Not gated on the payload: `dataTransfer.types` can already be empty on
+  // dragleave. The counter is the gate — a text drag never raised it.
+  const onDragLeave = useCallback(() => {
+    if (depthRef.current === 0) return;
+    depthRef.current -= 1;
+    if (depthRef.current === 0) setIsDragging(false);
+  }, []);
+
+  const onDrop = useCallback((e: TargetedDragEvent<HTMLElement>) => {
+    const dt = e.dataTransfer;
+    // Read the payload in ONE pass before anything else touches it:
+    // `getAsFile()` and `webkitGetAsEntry()` are not pure accessors on a
+    // file-manager drag, and each call can consume state the other needs.
+    const entries: DroppedEntries = dt ? readDroppedEntries(dt) : { files: [], directories: [], fallbacks: new Map() };
+    const references = dt ? collectDroppedFileUris(dt) : [];
+
+    if (!dt || !hasDraggedFiles(dt)) return;
+    e.preventDefault();
+    reset();
+    if (disabledRef.current) return;
+
+    // START THE READS NOW, in the drop handler's own tick. A dropped File's
+    // read permission is released when this handler returns, and a read started
+    // afterwards fails permanently — the chip rendered with the right name and
+    // size while its contents never arrived, on every retry. `FileReader` takes
+    // the permission at call time, so starting here is what makes the bytes
+    // reachable; the pipeline only awaits these later.
+    const primed = primeFileReads(entries.files, entries.fallbacks);
+
+    if (entries.files.length === 0 && entries.directories.length === 0) {
+      // No File at all: the host named the file without handing it over, and the
+      // reference resolver is the only route left to its contents.
+      if (references.length > 0) onFilesRef.current([], false, references, primed);
+      return;
+    }
+
+    void expandDroppedFiles(entries).then(async ({ files: resolved, incomplete }) => {
+      const carries = resolved.length > 0 ? await carriesBytes(resolved, primed) : false;
+      // A File that carries bytes is attached directly. Deciding from metadata
+      // instead — "size 0 and no type, so it must be a path stub" — misread a
+      // real file whose size the browser had not filled in, and sent it to the
+      // reference resolver, which only reads inside the allow-list. The file
+      // was then refused with no way for the user to tell why. Bytes settle it.
+      if (resolved.length > 0 && carries) {
+        onFilesRef.current(resolved, incomplete, [], primed);
+        return;
+      }
+      if (references.length > 0) {
+        onFilesRef.current([], incomplete, references, primed);
+        return;
+      }
+      // Files that declare no bytes are attached as-is; the attachment hook
+      // reports the ones that never produced content.
+      if (resolved.length > 0) onFilesRef.current(resolved, incomplete, [], primed);
+    });
+  }, [reset]);
+
+  return { isDragging, dropProps: { onDragEnter, onDragOver, onDragLeave, onDrop } };
+}
+
+/**
+ * Whether any dropped file actually holds bytes.
+ *
+ * A promised file (another app's drag) reports `size: 0` until its contents
+ * land, so the check reads rather than trusting the declared size. One readable
+ * file is enough: the batch is attached as a unit, and a member that stays
+ * empty is reported by the attachment hook rather than by re-routing the whole
+ * drop.
+ */
+export async function carriesBytes(files: File[], primed?: PrimedReads): Promise<boolean> {
+  const sample = files.slice(0, 4);
+  const results = await Promise.all(sample.map(async (file) => {
+    if (file.size > 0) return true;
+    // A stub declaring no size is settled by its bytes — read from the primed
+    // prefix where the drop provided one, because a `slice()` started after the
+    // drop window closes is not authorized to read a dropped file at all.
+    const bytes = await primedPrefix(file, primed);
+    if (bytes !== undefined) return bytes.byteLength > 0;
+    try {
+      const raw = await file.slice(0, 1).arrayBuffer();
+      return raw.byteLength > 0;
+    } catch {
+      return false;
+    }
+  }));
+  return results.some(Boolean);
+}