From b01e1a751572b50029e772cfe288f7255c7c09d9 Mon Sep 17 00:00:00 2001
From: 0xPratik <sariapratik@gmail.com>
Date: Thu, 22 Oct 2026 00:44:52 +0530
Subject: [PATCH 1/8] feat(attachments): add Attachments and the file drop zone

Attachments renders files as a stack above the input, tiles in a
message, or a list, with preview, info, remove and more parts. The host
owns the list: useAttachments applies the count, size and duplicate
limits, builds previews and revokes every object URL it made once its
attachment leaves the list. useFileDrop and AttachmentDropZone accept
files and whole folders, and a stray drop elsewhere never replaces the
page.
---
 e2e/attachments.spec.ts              | 289 +++++++++++
 e2e/fixtures.tsx                     |  97 +++-
 src/hooks/use-attachments.test.ts    | 270 +++++++++++
 src/hooks/use-attachments.ts         | 149 ++++++
 src/hooks/use-file-drop.test.ts      | 416 ++++++++++++++++
 src/hooks/use-file-drop.ts           | 368 ++++++++++++++
 src/index.ts                         |   4 +
 src/ui/attachment-drop-zone.tsx      |  76 +++
 src/ui/attachments.test.tsx          | 117 +++++
 src/ui/attachments.tsx               | 702 +++++++++++++++++++++++++++
 stories/chat/attachments.stories.tsx | 315 ++++++++++++
 11 files changed, 2802 insertions(+), 1 deletion(-)
 create mode 100644 e2e/attachments.spec.ts
 create mode 100644 src/hooks/use-attachments.test.ts
 create mode 100644 src/hooks/use-attachments.ts
 create mode 100644 src/hooks/use-file-drop.test.ts
 create mode 100644 src/hooks/use-file-drop.ts
 create mode 100644 src/ui/attachment-drop-zone.tsx
 create mode 100644 src/ui/attachments.test.tsx
 create mode 100644 src/ui/attachments.tsx
 create mode 100644 stories/chat/attachments.stories.tsx

diff --git a/e2e/attachments.spec.ts b/e2e/attachments.spec.ts
new file mode 100644
index 00000000..4fafd54b
--- /dev/null
+++ b/e2e/attachments.spec.ts
@@ -0,0 +1,289 @@
+import { expect, test, type Page } from "@playwright/test";
+
+/**
+ * Drops `count` text files named `<prefix>-<n>.txt` on the zone, the way a
+ * browser delivers a drag from the desktop: dragenter, dragover, then drop,
+ * all carrying one real DataTransfer.
+ */
+async function dropFiles(page: Page, prefix: string, count: number) {
+  await page.getByTestId("zone").evaluate(
+    (zone, { prefix, count }) => {
+      const data = new DataTransfer();
+      for (let index = 0; index < count; index += 1) {
+        data.items.add(
+          new File([`${prefix} ${index}`], `${prefix}-${index}.txt`, {
+            type: "text/plain",
+          }),
+        );
+      }
+      for (const type of ["dragenter", "dragover", "drop"]) {
+        zone.dispatchEvent(
+          new DragEvent(type, {
+            dataTransfer: data,
+            bubbles: true,
+            cancelable: true,
+          }),
+        );
+      }
+    },
+    { prefix, count },
+  );
+}
+
+/** Left edges of the stack's cards, from layout (so the tilt doesn't count). */
+function cardOffsets(page: Page): Promise<number[]> {
+  return page
+    .locator("[data-slot=attachment]")
+    .evaluateAll((cards) =>
+      cards.map((card) => (card instanceof HTMLElement ? card.offsetLeft : -1)),
+    );
+}
+
+async function gapBetweenFirstCards(page: Page): Promise<number> {
+  const [first, second] = await cardOffsets(page);
+  if (first === undefined || second === undefined) return Number.NaN;
+  return second - first;
+}
+
+const count = (page: Page) => page.getByRole("status", { name: "Count" });
+
+test("a dropped picture previews, and removing it revokes its URL", async ({
+  page,
+}) => {
+  await page.goto("/attachments");
+  await page.getByTestId("zone").evaluate(async (zone) => {
+    const canvas = document.createElement("canvas");
+    canvas.width = 8;
+    canvas.height = 8;
+    const blob = await new Promise<Blob | null>((resolve) =>
+      canvas.toBlob(resolve, "image/png"),
+    );
+    if (blob === null) throw new Error("no PNG");
+    const data = new DataTransfer();
+    data.items.add(new File([blob], "dot.png", { type: "image/png" }));
+    for (const type of ["dragenter", "dragover", "drop"]) {
+      zone.dispatchEvent(
+        new DragEvent(type, {
+          dataTransfer: data,
+          bubbles: true,
+          cancelable: true,
+        }),
+      );
+    }
+  });
+
+  await expect(count(page)).toHaveText("1");
+  const list = page.getByRole("list", { name: "1 attachment" });
+  const picture = list.locator("img");
+  await expect(picture).toHaveJSProperty("complete", true);
+  expect(
+    await picture.evaluate((image: HTMLImageElement) => image.naturalWidth),
+  ).toBe(8);
+  const url = await picture.getAttribute("src");
+  expect(url).toMatch(/^blob:/);
+  const readable = (target: string) =>
+    page.evaluate(
+      (target) =>
+        fetch(target).then(
+          () => true,
+          () => false,
+        ),
+      target,
+    );
+  expect(await readable(url ?? "")).toBe(true);
+
+  await list.getByRole("button", { name: "Remove dot.png" }).click();
+  await expect(count(page)).toHaveText("0");
+  await expect.poll(() => readable(url ?? "")).toBe(false);
+  // The list is gone with its last attachment; focus went to the message box.
+  await expect(page.getByRole("textbox", { name: "Message" })).toBeFocused();
+  expect(await page.evaluate(() => document.activeElement?.tagName)).not.toBe(
+    "BODY",
+  );
+});
+
+test("25 files fold into a stack that fans out, expands and clears", async ({
+  page,
+}) => {
+  await page.goto("/attachments");
+  await dropFiles(page, "single", 1);
+  await expect(count(page)).toHaveText("1");
+  await dropFiles(page, "batch", 25);
+  await expect(count(page)).toHaveText("26");
+  await expect(page.getByRole("status", { name: "Refused" })).toHaveText("");
+
+  const stack = page.getByRole("list", { name: "26 attachments" });
+  await expect(stack.locator("[data-slot=attachment]")).toHaveCount(4);
+  const more = stack.getByRole("button", { name: "Show 22 more" });
+  await expect(more).toHaveText("+22");
+
+  // At rest the cards overlap: each shows a 10px sliver of the one behind.
+  await page.getByTestId("outside").hover();
+  await expect.poll(() => gapBetweenFirstCards(page)).toBe(10);
+  await expect(more).toHaveCSS("opacity", "0");
+
+  // Pointed at, the deck fans out: a whole 52px card and an 8px gap apart.
+  await stack.hover();
+  await expect.poll(() => gapBetweenFirstCards(page)).toBe(60);
+  await expect(more).toHaveCSS("opacity", "1");
+
+  await more.click();
+  await expect(stack.locator("[data-slot=attachment]")).toHaveCount(26);
+  // Focus lands on the first card "+22" was folding, not the page start.
+  await expect(
+    stack.getByRole("button", { name: "Remove batch-3.txt" }),
+  ).toBeFocused();
+  await expect(stack.getByText("batch-24.txt")).toBeVisible();
+
+  await page.getByRole("button", { name: "Remove all" }).click();
+  await expect(count(page)).toHaveText("0");
+  await expect(page.locator("[data-slot=attachments]")).toHaveCount(0);
+  await expect(page.getByRole("textbox", { name: "Message" })).toBeFocused();
+});
+
+test("the stack fans out for the keyboard, and focus follows removal", async ({
+  page,
+}) => {
+  await page.goto("/attachments");
+  await dropFiles(page, "key", 3);
+  await expect(count(page)).toHaveText("3");
+  await page.getByTestId("outside").hover();
+
+  const stack = page.getByRole("list", { name: "3 attachments" });
+  await page.keyboard.press("Tab");
+  const first = stack.getByRole("button", { name: "Remove key-0.txt" });
+  await expect(first).toBeFocused();
+  await expect.poll(() => gapBetweenFirstCards(page)).toBe(60);
+  await expect(first).toHaveCSS("opacity", "1");
+
+  await page.keyboard.press("Enter");
+  await expect(count(page)).toHaveText("2");
+  await expect(
+    page
+      .getByRole("list", { name: "2 attachments" })
+      .getByRole("button", { name: "Remove key-1.txt" }),
+  ).toBeFocused();
+
+  // The keyboard clears the rest; the last removal hands focus on.
+  await page.keyboard.press("Enter");
+  await page.keyboard.press("Enter");
+  await expect(count(page)).toHaveText("0");
+  await expect(page.locator("[data-slot=attachments]")).toHaveCount(0);
+  await expect(page.getByRole("textbox", { name: "Message" })).toBeFocused();
+  expect(await page.evaluate(() => document.activeElement?.tagName)).not.toBe(
+    "BODY",
+  );
+});
+
+test("past the limit, 100 of 120 files join and the rest are refused", async ({
+  page,
+}) => {
+  await page.goto("/attachments");
+  await dropFiles(page, "many", 120);
+  await expect(count(page)).toHaveText("100");
+  await expect(page.getByRole("status", { name: "Refused" })).toHaveText(
+    "too-many 20",
+  );
+  await expect(
+    page.getByRole("list", { name: "100 attachments" }).getByRole("button", {
+      name: "Show 96 more",
+    }),
+  ).toHaveText("+96");
+});
+
+// A browser only builds file-system entries for a real drag from the
+// desktop, which Playwright cannot make. The drop's items are stubbed to
+// hand back entries of the same shape, so this covers the zone's walk of
+// them, not the browser's side.
+test("a dropped folder is walked to the files inside it", async ({ page }) => {
+  await page.goto("/attachments");
+  await page.getByTestId("zone").evaluate((zone) => {
+    type Entry = {
+      name: string;
+      isFile: boolean;
+      isDirectory: boolean;
+      file?: (success: (file: File) => void) => void;
+      createReader?: () => {
+        readEntries: (success: (entries: Entry[]) => void) => void;
+      };
+    };
+    const file = (name: string): Entry => ({
+      name,
+      isFile: true,
+      isDirectory: false,
+      file: (success) =>
+        success(new File([name], name, { type: "text/plain" })),
+    });
+    const folder = (name: string, entries: Entry[]): Entry => ({
+      name,
+      isFile: false,
+      isDirectory: true,
+      createReader: () => {
+        let read = false;
+        return {
+          readEntries: (success) => {
+            success(read ? [] : entries);
+            read = true;
+          },
+        };
+      },
+    });
+    const project = folder("project", [
+      file("README.md"),
+      file(".DS_Store"),
+      folder("src", [file("index.ts"), file("util.ts")]),
+      folder("test", [file("index.ts")]),
+    ]);
+    const items = [
+      { kind: "file", getAsFile: () => null, webkitGetAsEntry: () => project },
+    ];
+    const data = { types: ["Files"], items, files: [], dropEffect: "none" };
+    for (const type of ["dragenter", "dragover", "drop"]) {
+      const event = new DragEvent(type, { bubbles: true, cancelable: true });
+      Object.defineProperty(event, "dataTransfer", { value: data });
+      zone.dispatchEvent(event);
+    }
+  });
+
+  await expect(count(page)).toHaveText("4");
+  await expect(page.getByRole("status", { name: "Folders" })).toHaveText(
+    "project",
+  );
+  const stack = page.getByRole("list", { name: "4 attachments" });
+  for (const name of [
+    "project/README.md",
+    "project/src/index.ts",
+    "project/src/util.ts",
+    "project/test/index.ts",
+  ]) {
+    await expect(
+      stack.getByRole("button", { name: `Remove ${name}` }),
+    ).toHaveCount(1);
+  }
+});
+
+test("files dropped outside the zone do not open in place of the page", async ({
+  page,
+}) => {
+  await page.goto("/attachments");
+  const handled = await page.getByTestId("outside").evaluate((outside) => {
+    const data = new DataTransfer();
+    data.items.add(new File(["stray"], "stray.txt", { type: "text/plain" }));
+    return ["dragenter", "dragover", "drop"].map((type) => {
+      const event = new DragEvent(type, {
+        dataTransfer: data,
+        bubbles: true,
+        cancelable: true,
+      });
+      outside.dispatchEvent(event);
+      return { type, prevented: event.defaultPrevented };
+    });
+  });
+  expect(handled).toEqual([
+    { type: "dragenter", prevented: false },
+    { type: "dragover", prevented: true },
+    { type: "drop", prevented: true },
+  ]);
+  await expect(page).toHaveURL(/\/attachments$/);
+  await expect(count(page)).toHaveText("0");
+});
diff --git a/e2e/fixtures.tsx b/e2e/fixtures.tsx
index 6a0f1bfc..fd78fc41 100644
--- a/e2e/fixtures.tsx
+++ b/e2e/fixtures.tsx
@@ -1,4 +1,4 @@
-import { useEffect, useLayoutEffect, useState, Profiler } from "react";
+import { useEffect, useLayoutEffect, useRef, useState, Profiler } from "react";
 import type { ReactNode } from "react";
 
 import {
@@ -66,6 +66,16 @@ import {
   useHistoryWindow,
   ConversationMap,
   type ConversationMapTurn,
+  Attachment,
+  AttachmentDropZone,
+  AttachmentInfo,
+  AttachmentMore,
+  AttachmentPreview,
+  AttachmentRemove,
+  Attachments,
+  type AttachmentItem,
+  type AttachmentRejection,
+  useAttachments,
 } from "@corbits/react-ui";
 import {
   CommandPalette,
@@ -1358,6 +1368,90 @@ function ConversationMapScenario({
   );
 }
 
+/** How many of each reason, e.g. "too-many 20". */
+function refusals(rejected: readonly AttachmentRejection<File>[]): string {
+  const counts = new Map<string, number>();
+  for (const { reason } of rejected) {
+    counts.set(reason, (counts.get(reason) ?? 0) + 1);
+  }
+  return [...counts].map(([reason, count]) => `${reason} ${count}`).join(", ");
+}
+
+/** A message box taking dropped files into a folded stack, as a chat would. */
+function AttachmentsScenario() {
+  const [attachments, setAttachments] = useState<readonly AttachmentItem[]>([]);
+  const [expanded, setExpanded] = useState(false);
+  const [refused, setRefused] = useState("");
+  const [folders, setFolders] = useState("");
+  const message = useRef<HTMLTextAreaElement>(null);
+  const { add } = useAttachments({
+    attachments,
+    maxFiles: 100,
+    maxFileBytes: 1024 * 1024,
+  });
+  const folded = !expanded && attachments.length > 5;
+  const shown = folded ? attachments.slice(0, 4) : attachments;
+  return (
+    <div style={{ display: "flex", flexDirection: "column", gap: 24 }}>
+      <div data-testid="outside" style={{ height: 80 }}>
+        Outside the drop zone
+      </div>
+      <AttachmentDropZone
+        data-testid="zone"
+        onFiles={(files, details) => {
+          const { accepted, rejected } = add(files);
+          setAttachments((previous) => [...previous, ...accepted]);
+          setRefused(refusals(rejected));
+          setFolders(details.folders.join(","));
+        }}
+        style={{ padding: "96px 16px 16px", width: 640 }}
+      >
+        {attachments.length === 0 ? null : (
+          <Attachments
+            variant="stack"
+            total={attachments.length}
+            expanded={expanded}
+            onExpandedChange={setExpanded}
+            returnFocusTo={message}
+          >
+            {shown.map((item) => (
+              <Attachment key={item.id} data={item}>
+                <AttachmentPreview />
+                <AttachmentInfo />
+                <AttachmentRemove
+                  onClick={() =>
+                    setAttachments((previous) =>
+                      previous.filter((held) => held.id !== item.id),
+                    )
+                  }
+                />
+              </Attachment>
+            ))}
+            {folded ? (
+              <AttachmentMore count={attachments.length - shown.length} />
+            ) : null}
+          </Attachments>
+        )}
+        {expanded ? (
+          <Button
+            onClick={() => {
+              message.current?.focus();
+              setExpanded(false);
+              setAttachments([]);
+            }}
+          >
+            Remove all
+          </Button>
+        ) : null}
+        <textarea ref={message} aria-label="Message" />
+      </AttachmentDropZone>
+      <output aria-label="Count">{attachments.length}</output>
+      <output aria-label="Refused">{refused}</output>
+      <output aria-label="Folders">{folders}</output>
+    </div>
+  );
+}
+
 export const scenarios: Record<string, () => ReactNode> = {
   smoke: () => <Button>Ready</Button>,
   "approval-card": () => <Approval state="idle" />,
@@ -1427,4 +1521,5 @@ export const scenarios: Record<string, () => ReactNode> = {
       <ConversationMapScenario turns={mapTurns(80)} />
     </>
   ),
+  attachments: () => <AttachmentsScenario />,
 };
diff --git a/src/hooks/use-attachments.test.ts b/src/hooks/use-attachments.test.ts
new file mode 100644
index 00000000..9a3e2f4f
--- /dev/null
+++ b/src/hooks/use-attachments.test.ts
@@ -0,0 +1,270 @@
+import { afterEach, beforeEach, describe, expect, test } from "bun:test";
+import { Activity, StrictMode, act, createElement, useState } from "react";
+import { createRoot } from "react-dom/client";
+
+import type { PartFile } from "../lib/chat-parts.js";
+import type { AttachmentData } from "../ui/attachments.js";
+import {
+  useAttachments,
+  type AttachmentItem,
+  type UseAttachmentsResult,
+} from "./use-attachments.js";
+
+// What the parts render must take what the hook makes and what a message
+// carries, with no mapping in between.
+const fromHook: (item: AttachmentItem) => AttachmentData = (item) => item;
+const fromMessage: (part: PartFile) => AttachmentData = (part) => part;
+void fromHook;
+void fromMessage;
+
+let created: string[] = [];
+let revoked: string[] = [];
+const realCreate = URL.createObjectURL;
+const realRevoke = URL.revokeObjectURL;
+
+beforeEach(() => {
+  created = [];
+  revoked = [];
+  URL.createObjectURL = () => {
+    const url = `blob:test/${created.length + 1}`;
+    created.push(url);
+    return url;
+  };
+  URL.revokeObjectURL = (url: string) => {
+    revoked.push(url);
+  };
+});
+
+afterEach(() => {
+  URL.createObjectURL = realCreate;
+  URL.revokeObjectURL = realRevoke;
+});
+
+function file(name: string, size = 4, type = "text/plain"): File {
+  return new File(["x".repeat(size)], name, { type });
+}
+
+/** Lets the hook's deferred unmount revoke run. */
+function microtasks(): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, 0));
+}
+
+type Options = {
+  readonly maxFiles?: number;
+  readonly maxFileBytes?: number;
+  readonly strict?: boolean;
+  readonly initial?: readonly AttachmentItem[];
+};
+
+/** A host that owns the list, as a composer would. */
+function mountHost({ strict = false, initial = [], ...limits }: Options = {}) {
+  const container = document.createElement("div");
+  document.body.appendChild(container);
+  const root = createRoot(container);
+  let hook: UseAttachmentsResult | undefined;
+  let list: readonly AttachmentItem[] = [];
+  let setList: (next: readonly AttachmentItem[]) => void = () => {};
+  let setHidden: (hidden: boolean) => void = () => {};
+
+  function Host() {
+    const [attachments, setAttachments] =
+      useState<readonly AttachmentItem[]>(initial);
+    list = attachments;
+    setList = setAttachments;
+    hook = useAttachments({ attachments, ...limits });
+    return null;
+  }
+
+  /** Hiding runs the hook's effect cleanups; showing runs them again. */
+  function Shell() {
+    const [hidden, setShellHidden] = useState(false);
+    setHidden = setShellHidden;
+    return createElement(Activity, {
+      mode: hidden ? "hidden" : "visible",
+      children: createElement(Host),
+    });
+  }
+
+  act(() => {
+    root.render(
+      strict
+        ? createElement(StrictMode, null, createElement(Shell))
+        : createElement(Shell),
+    );
+  });
+
+  const api = () => {
+    if (hook === undefined) throw new Error("the hook did not render");
+    return hook;
+  };
+
+  return {
+    get list() {
+      return list;
+    },
+    /** Adds and appends what was accepted, in one update. */
+    drop(files: readonly File[]) {
+      let result: ReturnType<UseAttachmentsResult["add"]> | undefined;
+      act(() => {
+        result = api().add(files);
+        const accepted = result.accepted;
+        setList([...list, ...accepted]);
+      });
+      if (result === undefined) throw new Error("add returned nothing");
+      return result;
+    },
+    add(files: readonly File[]) {
+      return api().add(files);
+    },
+    release(ids: readonly string[]) {
+      api().release(ids);
+    },
+    set(next: readonly AttachmentItem[]) {
+      act(() => setList(next));
+    },
+    rerender() {
+      act(() => setList([...list]));
+    },
+    /**
+     * Runs the hook's effect cleanups and then its setups again before any
+     * microtask can run, as Fast Refresh or an effect replay does.
+     */
+    replayEffects() {
+      act(() => setHidden(true));
+      act(() => setHidden(false));
+    },
+    unmount() {
+      act(() => root.unmount());
+      container.remove();
+    },
+  };
+}
+
+describe("useAttachments", () => {
+  test("refused files carry a reason; accepted ones a preview URL", () => {
+    const host = mountHost({ maxFiles: 2, maxFileBytes: 10 });
+    const big = file("big.png", 20, "image/png");
+    const notes = file("notes.txt");
+    const again = file("notes.txt");
+    const plan = file("plan.md");
+    const extra = file("extra.md");
+    const { accepted, rejected } = host.drop([big, notes, again, plan, extra]);
+
+    expect(accepted.map((item) => item.name)).toEqual(["notes.txt", "plan.md"]);
+    expect(accepted.map((item) => item.file)).toEqual([notes, plan]);
+    expect(accepted.map((item) => item.url)).toEqual(created);
+    expect(new Set(accepted.map((item) => item.id)).size).toBe(2);
+    expect(rejected).toEqual([
+      { file: big, reason: "too-large" },
+      { file: again, reason: "duplicate" },
+      { file: extra, reason: "too-many" },
+    ]);
+    expect(host.list).toEqual(accepted);
+    host.unmount();
+  });
+
+  test("a file with no type is a generic binary", () => {
+    const host = mountHost();
+    const [item] = host.drop([new File(["abc"], "archive.bin")]).accepted;
+    expect(item?.mediaType).toBe("application/octet-stream");
+    expect(item?.size).toBe(3);
+    host.unmount();
+  });
+
+  test("two adds before the list updates still respect the limits", () => {
+    const host = mountHost({ maxFiles: 2 });
+    let second: ReturnType<UseAttachmentsResult["add"]> | undefined;
+    act(() => {
+      host.add([file("a.txt")]);
+      second = host.add([file("a.txt"), file("b.txt"), file("c.txt")]);
+    });
+    expect(second?.accepted.map((item) => item.name)).toEqual(["b.txt"]);
+    expect(second?.rejected.map((rejection) => rejection.reason)).toEqual([
+      "duplicate",
+      "too-many",
+    ]);
+    host.unmount();
+  });
+
+  test("removing an attachment revokes its preview URL and only its", () => {
+    const host = mountHost();
+    const [first, second] = host.drop([file("a.txt"), file("b.txt")]).accepted;
+    if (first === undefined || second === undefined) throw new Error("missing");
+    expect(revoked).toEqual([]);
+
+    host.set([second]);
+    expect(revoked).toEqual([first.url ?? ""]);
+
+    host.set([]);
+    expect(revoked).toEqual([first.url ?? "", second.url ?? ""]);
+    host.unmount();
+  });
+
+  test("an accepted file the host never appended is revoked and can come back", () => {
+    const host = mountHost();
+    act(() => {
+      host.add([file("a.txt")]);
+    });
+    host.rerender();
+    expect(revoked).toEqual(created);
+
+    const { accepted, rejected } = host.drop([file("a.txt")]);
+    expect(rejected).toEqual([]);
+    expect(accepted).toHaveLength(1);
+    host.unmount();
+  });
+
+  test("a released attachment keeps its URL after it leaves the list", async () => {
+    const host = mountHost();
+    const sent = host.drop([file("a.txt"), file("b.txt")]).accepted;
+    host.release(sent.map((item) => item.id));
+    host.set([]);
+    host.unmount();
+    await microtasks();
+    expect(revoked).toEqual([]);
+  });
+
+  test("unmounting revokes every URL still held", async () => {
+    const host = mountHost();
+    host.drop([file("a.txt"), file("b.txt")]);
+    host.unmount();
+    await microtasks();
+    expect([...revoked].sort()).toEqual([...created].sort());
+  });
+
+  // StrictMode replays effects only at mount, before any URL is made, so
+  // the replay here comes after: the effects are torn down and set up again
+  // while the previews are on screen.
+  test("an effect replay while previews are held revokes nothing", async () => {
+    const host = mountHost({ strict: true });
+    host.drop([file("a.txt"), file("b.txt")]);
+    expect(created).toHaveLength(2);
+
+    host.replayEffects();
+    await microtasks();
+    expect(revoked).toEqual([]);
+
+    host.unmount();
+    await microtasks();
+    expect([...revoked].sort()).toEqual([...created].sort());
+  });
+
+  test("the host's own URLs are never revoked", async () => {
+    const uploaded: AttachmentItem = {
+      id: "uploaded-1",
+      name: "report.pdf",
+      mediaType: "application/pdf",
+      size: 2048,
+      url: "https://files.example.com/report.pdf",
+    };
+    const host = mountHost({ initial: [uploaded] });
+    const { rejected } = host.drop([file("report.pdf", 2048)]);
+    expect(rejected.map((rejection) => rejection.reason)).toEqual([
+      "duplicate",
+    ]);
+    host.set([]);
+    host.unmount();
+    await microtasks();
+    expect(revoked).toEqual([]);
+  });
+});
diff --git a/src/hooks/use-attachments.ts b/src/hooks/use-attachments.ts
new file mode 100644
index 00000000..6376e66c
--- /dev/null
+++ b/src/hooks/use-attachments.ts
@@ -0,0 +1,149 @@
+import { useCallback, useEffect, useRef } from "react";
+
+import {
+  checkAttachments,
+  type AttachmentLimits,
+  type AttachmentRejection,
+} from "../lib/attachment-limits.js";
+
+/** A file waiting to be sent, as the host holds it. */
+export type AttachmentItem = {
+  readonly id: string;
+  readonly name: string;
+  readonly mediaType: string;
+  /** In bytes. */
+  readonly size: number;
+  /** Where the bytes are: a preview URL `useAttachments` made, or the host's own. */
+  readonly url?: string;
+  /** The local file, for the host to upload or send. */
+  readonly file?: File;
+};
+
+export type UseAttachmentsOptions = AttachmentLimits & {
+  /** The attachments the host holds now. */
+  readonly attachments: readonly AttachmentItem[];
+};
+
+export type AttachmentIntake = {
+  /** New attachments, each with a preview URL, to append to the host's list. */
+  readonly accepted: readonly AttachmentItem[];
+  /** Files left out, each with why. */
+  readonly rejected: readonly AttachmentRejection<File>[];
+};
+
+export type UseAttachmentsResult = {
+  /** Checks `files` against the limits and the attachments already held. */
+  readonly add: (files: Iterable<File> | ArrayLike<File>) => AttachmentIntake;
+  /**
+   * Hands the preview URLs of `ids` over to the host: the hook stops
+   * tracking them and never revokes them. Call it before moving attachments
+   * out of the list somewhere they are still shown, such as a sent message;
+   * revoking them is then the host's job.
+   */
+  readonly release: (ids: Iterable<string>) => void;
+};
+
+let lastAttachmentId = 0;
+
+function nextAttachmentId(): string {
+  lastAttachmentId += 1;
+  return `attachment-${lastAttachmentId}`;
+}
+
+/**
+ * Takes files into a host-owned attachment list.
+ *
+ * `add` runs `checkAttachments` against the list (and anything it accepted
+ * since the list last changed, so two drops in one tick cannot both slip
+ * past a limit) and gives each accepted file an object URL for its preview.
+ * The host appends `accepted` to its list in the same update and decides
+ * what to say about `rejected`.
+ *
+ * Every URL the hook makes is revoked at the first commit whose list does
+ * not hold its attachment: once the host removes it, however it does, or
+ * right away if the host never appended it. The rest go when the hook
+ * unmounts. Only
+ * URLs the hook made are revoked; the host's own are left alone. To keep an
+ * attachment on screen after it leaves the list (sending moves it into a
+ * message), `release` it first.
+ *
+ * The unmount revoke waits a microtask and is called off if the hook mounts
+ * again, which is what StrictMode's simulated remount does within one
+ * commit. A hook hidden by `<Activity mode="hidden">` counts as unmounted,
+ * and its previews are revoked.
+ */
+export function useAttachments({
+  attachments,
+  maxFiles,
+  maxFileBytes,
+}: UseAttachmentsOptions): UseAttachmentsResult {
+  const urls = useRef(new Map<string, string>());
+  const pending = useRef<AttachmentItem[]>([]);
+  const latest = useRef({ attachments, maxFiles, maxFileBytes });
+  latest.current = { attachments, maxFiles, maxFileBytes };
+  const mounted = useRef(false);
+
+  // After every commit, not only when the list changes: an accepted file the
+  // host did not append must neither keep its URL nor count as a duplicate
+  // of the same file dropped again.
+  useEffect(() => {
+    pending.current = [];
+    const held = new Set(attachments.map((item) => item.id));
+    for (const [id, url] of urls.current) {
+      if (held.has(id)) continue;
+      URL.revokeObjectURL(url);
+      urls.current.delete(id);
+    }
+  });
+
+  useEffect(() => {
+    mounted.current = true;
+    const owned = urls.current;
+    return () => {
+      mounted.current = false;
+      queueMicrotask(() => {
+        if (mounted.current) return;
+        for (const url of owned.values()) URL.revokeObjectURL(url);
+        owned.clear();
+      });
+    };
+  }, []);
+
+  const add = useCallback((files: Iterable<File> | ArrayLike<File>) => {
+    const {
+      attachments: held,
+      maxFiles: max,
+      maxFileBytes: maxBytes,
+    } = latest.current;
+    const limits: AttachmentLimits = {
+      ...(max === undefined ? {} : { maxFiles: max }),
+      ...(maxBytes === undefined ? {} : { maxFileBytes: maxBytes }),
+    };
+    const { accepted, rejected } = checkAttachments(
+      [...held, ...pending.current],
+      Array.from(files),
+      limits,
+    );
+    const items = accepted.map((file): AttachmentItem => {
+      const id = nextAttachmentId();
+      const url = URL.createObjectURL(file);
+      urls.current.set(id, url);
+      return {
+        id,
+        name: file.name === "" ? "Untitled" : file.name,
+        mediaType: file.type === "" ? "application/octet-stream" : file.type,
+        size: file.size,
+        url,
+        file,
+      };
+    });
+    pending.current = [...pending.current, ...items];
+    return { accepted: items, rejected };
+  }, []);
+
+  const release = useCallback((ids: Iterable<string>) => {
+    for (const id of ids) urls.current.delete(id);
+  }, []);
+
+  return { add, release };
+}
diff --git a/src/hooks/use-file-drop.test.ts b/src/hooks/use-file-drop.test.ts
new file mode 100644
index 00000000..1adf118e
--- /dev/null
+++ b/src/hooks/use-file-drop.test.ts
@@ -0,0 +1,416 @@
+import { describe, expect, test } from "bun:test";
+import { act, createElement } from "react";
+import { createRoot } from "react-dom/client";
+
+import {
+  readDroppedFiles,
+  useFileDrop,
+  usePreventStrayDrops,
+  type DropSource,
+  type DroppedEntry,
+  type FileDropDetails,
+} from "./use-file-drop.js";
+
+// Browsers hand a dropped folder over as file-system entries, which no
+// test environment can make; these stand-ins have the same shape.
+function fileEntry(
+  name: string,
+  content = "x",
+  type = "text/plain",
+): DroppedEntry {
+  return {
+    name,
+    isFile: true,
+    isDirectory: false,
+    file: (success) => success(new File([content], name, { type })),
+  };
+}
+
+function brokenFileEntry(name: string): DroppedEntry {
+  return {
+    name,
+    isFile: true,
+    isDirectory: false,
+    file: (_success, failure) =>
+      failure?.(new DOMException("gone", "NotFoundError")),
+  };
+}
+
+/** A folder whose reader hands its entries back `batch` at a time. */
+function folderEntry(
+  name: string,
+  entries: readonly DroppedEntry[],
+  batch = 100,
+): DroppedEntry {
+  return {
+    name,
+    isFile: false,
+    isDirectory: true,
+    createReader: () => {
+      let offset = 0;
+      return {
+        readEntries: (success) => {
+          const next = entries.slice(offset, offset + batch);
+          offset += next.length;
+          success([...next]);
+        },
+      };
+    },
+  };
+}
+
+function source(
+  dropped: readonly (DroppedEntry | File)[],
+  types: readonly string[] = ["Files"],
+): DropSource {
+  return {
+    types,
+    files: dropped.filter((item) => item instanceof File),
+    items: dropped.map((item) => ({
+      kind: "file",
+      getAsFile: () => (item instanceof File ? item : null),
+      webkitGetAsEntry: () => (item instanceof File ? null : item),
+    })),
+  };
+}
+
+const PROJECT = folderEntry(
+  "project",
+  [
+    fileEntry("README.md"),
+    fileEntry(".DS_Store"),
+    folderEntry(".git", [fileEntry("HEAD")]),
+    folderEntry("src", [fileEntry("index.ts"), fileEntry("util.ts")]),
+    folderEntry("test", [fileEntry("index.ts")]),
+    folderEntry("empty", []),
+  ],
+  2,
+);
+
+describe("readDroppedFiles", () => {
+  test("walks a folder to its files, named by their path inside it", async () => {
+    const loose = new File(["hi"], "note.txt");
+    const dropped = await readDroppedFiles(source([PROJECT, loose]));
+    expect(dropped.files.map((file) => file.name)).toEqual([
+      "note.txt",
+      "project/README.md",
+      "project/src/index.ts",
+      "project/src/util.ts",
+      "project/test/index.ts",
+    ]);
+    expect(dropped.files[0]).toBe(loose);
+    expect(dropped.files[1]?.type).toBe("text/plain");
+    expect(dropped.folders).toEqual(["project"]);
+    expect(dropped.truncated).toBe(false);
+    expect(dropped.errors).toEqual([]);
+  });
+
+  test("stops past the entry budget and says so", async () => {
+    const big = folderEntry(
+      "big",
+      Array.from({ length: 30 }, (_, index) => fileEntry(`${index}.txt`)),
+    );
+    const dropped = await readDroppedFiles(source([big]), {
+      maxFolderEntries: 10,
+    });
+    expect(dropped.files).toHaveLength(10);
+    expect(dropped.truncated).toBe(true);
+  });
+
+  test("stops listing once the budget is spent, later folders included", async () => {
+    let calls = 0;
+    /** A flat folder of `size` files, read 100 a batch, counting the reads. */
+    const huge = (name: string, size: number): DroppedEntry => ({
+      name,
+      isFile: false,
+      isDirectory: true,
+      createReader: () => {
+        let offset = 0;
+        return {
+          readEntries: (success) => {
+            calls += 1;
+            const count = Math.min(100, size - offset);
+            const batch = Array.from({ length: count }, (_, index) =>
+              fileEntry(`${offset + index}.txt`),
+            );
+            offset += count;
+            success(batch);
+          },
+        };
+      },
+    });
+    const dropped = await readDroppedFiles(
+      source([huge("first", 20_000), huge("second", 20_000)]),
+      { maxFolderEntries: 250 },
+    );
+    expect(dropped.files).toHaveLength(250);
+    expect(dropped.truncated).toBe(true);
+    expect(dropped.folders).toEqual(["first", "second"]);
+    // Three batches cover 250 entries; the full listing would be 402.
+    expect(calls).toBe(3);
+  });
+
+  test("skips a file that cannot be read and keeps the rest", async () => {
+    const folder = folderEntry("docs", [
+      fileEntry("a.md"),
+      brokenFileEntry("b.md"),
+      fileEntry("c.md"),
+    ]);
+    const dropped = await readDroppedFiles(source([folder]));
+    expect(dropped.files.map((file) => file.name)).toEqual([
+      "docs/a.md",
+      "docs/c.md",
+    ]);
+    expect(dropped.errors).toHaveLength(1);
+  });
+
+  test("reads plain files when the drop has no items", async () => {
+    const files = [new File(["a"], "a.txt"), new File(["b"], "b.txt")];
+    const dropped = await readDroppedFiles({ types: ["Files"], files });
+    expect(dropped.files).toEqual(files);
+    expect(dropped.folders).toEqual([]);
+  });
+});
+
+/** A drag event carrying `data`, as a browser would dispatch it. */
+function dragEvent(
+  type: string,
+  data: DropSource,
+  relatedTarget: EventTarget | null = null,
+): Event {
+  const event = new Event(type, { bubbles: true, cancelable: true });
+  const dataTransfer = { ...data, dropEffect: "none" };
+  Object.defineProperty(event, "dataTransfer", { value: dataTransfer });
+  Object.defineProperty(event, "relatedTarget", { value: relatedTarget });
+  return event;
+}
+
+function dropEffectOf(event: Event): unknown {
+  return Object.getOwnPropertyDescriptor(event, "dataTransfer")?.value
+    ?.dropEffect;
+}
+
+type Received = { files: readonly File[]; details: FileDropDetails };
+
+function mountTarget({ guard = true }: { guard?: boolean } = {}) {
+  const container = document.createElement("div");
+  document.body.appendChild(container);
+  const root = createRoot(container);
+  const received: Received[] = [];
+  let over = false;
+
+  function Target() {
+    const drop = useFileDrop<HTMLDivElement>({
+      onFiles: (files, details) => received.push({ files, details }),
+    });
+    usePreventStrayDrops(guard);
+    over = drop.over;
+    return createElement(
+      "div",
+      { "data-testid": "zone", ...drop.dropProps },
+      createElement("span", null, "Drop here"),
+    );
+  }
+
+  act(() => root.render(createElement(Target)));
+  const zone = container.querySelector("[data-testid=zone]");
+  const child = container.querySelector("span");
+  if (zone === null || child === null) throw new Error("no zone");
+  return {
+    zone,
+    child,
+    received,
+    get over() {
+      return over;
+    },
+    fire(target: EventTarget, event: Event) {
+      act(() => {
+        target.dispatchEvent(event);
+      });
+      return event;
+    },
+    unmount() {
+      act(() => root.unmount());
+      container.remove();
+    },
+  };
+}
+
+function settle(): Promise<void> {
+  return act(async () => {
+    await new Promise((resolve) => setTimeout(resolve, 0));
+  });
+}
+
+describe("useFileDrop", () => {
+  test("a dropped folder reaches onFiles walked to its files", async () => {
+    const target = mountTarget();
+    const drop = target.fire(target.zone, dragEvent("drop", source([PROJECT])));
+    expect(drop.defaultPrevented).toBe(true);
+    await settle();
+    expect(target.received).toHaveLength(1);
+    expect(target.received[0]?.files.map((file) => file.name)).toEqual([
+      "project/README.md",
+      "project/src/index.ts",
+      "project/src/util.ts",
+      "project/test/index.ts",
+    ]);
+    expect(target.received[0]?.details.folders).toEqual(["project"]);
+    target.unmount();
+  });
+
+  test("an empty folder still reports the folder", async () => {
+    const target = mountTarget();
+    target.fire(
+      target.zone,
+      dragEvent("drop", source([folderEntry("empty", [])])),
+    );
+    await settle();
+    expect(target.received).toEqual([
+      {
+        files: [],
+        details: { folders: ["empty"], truncated: false, errors: [] },
+      },
+    ]);
+    target.unmount();
+  });
+
+  test("tracks files held over the target, children included", () => {
+    const target = mountTarget();
+    const files = source([new File(["a"], "a.txt")]);
+    const enter = target.fire(target.zone, dragEvent("dragenter", files));
+    expect(enter.defaultPrevented).toBe(true);
+    const over = target.fire(target.zone, dragEvent("dragover", files));
+    expect(over.defaultPrevented).toBe(true);
+    expect(dropEffectOf(over)).toBe("copy");
+    expect(target.over).toBe(true);
+
+    target.fire(target.zone, dragEvent("dragleave", files, document.body));
+    expect(target.over).toBe(false);
+    target.unmount();
+  });
+
+  // WebKit leaves relatedTarget null on every drag event. Moving between
+  // children enters the next before leaving the last, as browsers do.
+  test("stays over across children when relatedTarget is null", () => {
+    const target = mountTarget();
+    const files = source([new File(["a"], "a.txt")]);
+    const enter = (element: Element) =>
+      target.fire(element, dragEvent("dragenter", files));
+    const leave = (element: Element) =>
+      target.fire(element, dragEvent("dragleave", files));
+
+    enter(target.zone);
+    expect(target.over).toBe(true);
+    for (let crossing = 0; crossing < 3; crossing += 1) {
+      enter(target.child);
+      leave(target.zone);
+      expect(target.over).toBe(true);
+      enter(target.zone);
+      leave(target.child);
+      expect(target.over).toBe(true);
+    }
+
+    leave(target.zone);
+    expect(target.over).toBe(false);
+    target.unmount();
+  });
+
+  test("a drag that ends, or enters elsewhere, clears a count thrown off", () => {
+    const target = mountTarget();
+    const files = source([new File(["a"], "a.txt")]);
+    // Into a child with the target's own leave missed, as when an element
+    // is removed from under the pointer: leaving the child for somewhere
+    // outside no longer brings the count to 0.
+    const offCount = () => {
+      target.fire(target.zone, dragEvent("dragenter", files));
+      target.fire(target.child, dragEvent("dragenter", files));
+      target.fire(target.child, dragEvent("dragleave", files));
+      expect(target.over).toBe(true);
+    };
+
+    offCount();
+    target.fire(window, new Event("dragend"));
+    expect(target.over).toBe(false);
+
+    offCount();
+    target.fire(document.body, dragEvent("dragenter", files));
+    expect(target.over).toBe(false);
+
+    // Back over the target, the count starts afresh.
+    target.fire(target.zone, dragEvent("dragenter", files));
+    target.fire(target.zone, dragEvent("dragleave", files));
+    expect(target.over).toBe(false);
+    target.unmount();
+  });
+
+  test("a drag without files is left alone", async () => {
+    const target = mountTarget();
+    const text = source([], ["text/plain"]);
+    const over = target.fire(target.zone, dragEvent("dragover", text));
+    const drop = target.fire(target.zone, dragEvent("drop", text));
+    expect(over.defaultPrevented).toBe(false);
+    expect(drop.defaultPrevented).toBe(false);
+    expect(target.over).toBe(false);
+    await settle();
+    expect(target.received).toEqual([]);
+    target.unmount();
+  });
+});
+
+describe("usePreventStrayDrops", () => {
+  test("a drop outside the target does not navigate", () => {
+    const target = mountTarget();
+    const files = source([new File(["a"], "a.txt")]);
+    const over = target.fire(document.body, dragEvent("dragover", files));
+    const drop = target.fire(document.body, dragEvent("drop", files));
+    expect(over.defaultPrevented).toBe(true);
+    expect(dropEffectOf(over)).toBe("none");
+    expect(drop.defaultPrevented).toBe(true);
+
+    // The target's own handling is not overridden on its way up.
+    const inside = target.fire(target.zone, dragEvent("dragover", files));
+    expect(dropEffectOf(inside)).toBe("copy");
+    target.unmount();
+  });
+
+  test("leaves native file inputs and other drags alone", () => {
+    const target = mountTarget();
+    const input = document.createElement("input");
+    input.type = "file";
+    document.body.appendChild(input);
+    const files = source([new File(["a"], "a.txt")]);
+    expect(target.fire(input, dragEvent("drop", files)).defaultPrevented).toBe(
+      false,
+    );
+    const text = source([], ["text/plain"]);
+    expect(
+      target.fire(document.body, dragEvent("drop", text)).defaultPrevented,
+    ).toBe(false);
+    input.remove();
+    target.unmount();
+  });
+
+  test("stops guarding once the last user unmounts", () => {
+    const first = mountTarget();
+    const second = mountTarget();
+    const files = source([new File(["a"], "a.txt")]);
+    first.unmount();
+    expect(
+      second.fire(document.body, dragEvent("drop", files)).defaultPrevented,
+    ).toBe(true);
+    second.unmount();
+    const after = dragEvent("drop", files);
+    document.body.dispatchEvent(after);
+    expect(after.defaultPrevented).toBe(false);
+  });
+
+  test("does nothing when disabled", () => {
+    const target = mountTarget({ guard: false });
+    const files = source([new File(["a"], "a.txt")]);
+    expect(
+      target.fire(document.body, dragEvent("drop", files)).defaultPrevented,
+    ).toBe(false);
+    target.unmount();
+  });
+});
diff --git a/src/hooks/use-file-drop.ts b/src/hooks/use-file-drop.ts
new file mode 100644
index 00000000..c926d65d
--- /dev/null
+++ b/src/hooks/use-file-drop.ts
@@ -0,0 +1,368 @@
+import { useEffect, useRef, useState } from "react";
+import type { DragEvent as ReactDragEvent } from "react";
+
+/**
+ * What a drop's file-system entry needs to offer. A browser's
+ * `FileSystemEntry` fits; so does a plain object, which is how tests stand
+ * in for a dropped folder.
+ */
+export type DroppedEntry = {
+  readonly name: string;
+  readonly isFile: boolean;
+  readonly isDirectory: boolean;
+  /** On a file entry. */
+  file?(
+    success: (file: File) => void,
+    failure?: (error: DOMException) => void,
+  ): void;
+  /** On a folder entry. */
+  createReader?(): {
+    readEntries(
+      success: (entries: DroppedEntry[]) => void,
+      failure?: (error: DOMException) => void,
+    ): void;
+  };
+};
+
+/** The parts of a `DataTransfer` a drop is read from. */
+export type DropSource = {
+  readonly types: readonly string[];
+  readonly items?: ArrayLike<{
+    readonly kind: string;
+    getAsFile(): File | null;
+    webkitGetAsEntry(): DroppedEntry | null;
+  }>;
+  readonly files: ArrayLike<File>;
+};
+
+export type DroppedFiles = {
+  /** Loose files first, in drop order, then each folder's files depth first. */
+  readonly files: readonly File[];
+  /** Names of the folders dropped. */
+  readonly folders: readonly string[];
+  /** A folder held more entries than were read. */
+  readonly truncated: boolean;
+  /** Entries that could not be read and were skipped. */
+  readonly errors: readonly unknown[];
+};
+
+export type ReadDroppedFilesOptions = {
+  /** Most entries read across every dropped folder. */
+  readonly maxFolderEntries?: number;
+};
+
+const DEFAULT_MAX_FOLDER_ENTRIES = 500;
+
+/** Whether a drag carries files, as opposed to text or a link. */
+export function carriesFiles(
+  source: Pick<DropSource, "types"> | null,
+): boolean {
+  return source !== null && source.types.includes("Files");
+}
+
+function readBatch(
+  reader: ReturnType<NonNullable<DroppedEntry["createReader"]>>,
+): Promise<DroppedEntry[]> {
+  return new Promise((resolve, reject) => reader.readEntries(resolve, reject));
+}
+
+function readFile(entry: DroppedEntry): Promise<File> {
+  return new Promise((resolve, reject) => {
+    if (entry.file === undefined)
+      reject(new Error(`${entry.name} is not a file`));
+    else entry.file(resolve, reject);
+  });
+}
+
+type Walk = { remaining: number; truncated: boolean; errors: unknown[] };
+
+/**
+ * A folder's files, depth first, each renamed to its path from the dropped
+ * folder ("photos/2024/a.jpg") so files of the same name in different
+ * subfolders stay distinct. Hidden entries (`.git`, `.DS_Store`) are skipped.
+ *
+ * Entries are taken a batch at a time, and no further batch is asked for
+ * once the budget is spent, so a huge folder costs a few `readEntries`
+ * calls rather than its whole listing.
+ */
+async function filesInFolder(
+  folder: DroppedEntry,
+  path: string,
+  walk: Walk,
+): Promise<File[]> {
+  const files: File[] = [];
+  if (walk.truncated || folder.createReader === undefined) return files;
+  const reader = folder.createReader();
+  // `readEntries` hands back a batch at a time until it returns none.
+  while (!walk.truncated) {
+    let batch: DroppedEntry[];
+    try {
+      batch = await readBatch(reader);
+    } catch (error) {
+      walk.errors.push(error);
+      break;
+    }
+    if (batch.length === 0) break;
+    for (const entry of batch) {
+      if (entry.name.startsWith(".")) continue;
+      if (walk.remaining <= 0) {
+        walk.truncated = true;
+        break;
+      }
+      walk.remaining -= 1;
+      const entryPath = `${path}/${entry.name}`;
+      if (entry.isDirectory) {
+        files.push(...(await filesInFolder(entry, entryPath, walk)));
+        if (walk.truncated) break;
+      } else if (entry.isFile) {
+        try {
+          const file = await readFile(entry);
+          // A File made from a File shares its bytes; nothing is copied.
+          files.push(
+            new File([file], entryPath, {
+              type: file.type,
+              lastModified: file.lastModified,
+            }),
+          );
+        } catch (error) {
+          walk.errors.push(error);
+        }
+      }
+    }
+  }
+  return files;
+}
+
+/**
+ * The files in a drop, with every dropped folder walked for the files inside
+ * it. A folder shows up in `files` as one unreadable entry, so its entries
+ * are read instead; past `maxFolderEntries` the walk stops, folders not yet
+ * reached are not listed, and the result is `truncated`. An entry that
+ * cannot be read is skipped and kept in `errors`.
+ *
+ * Call it from the drop handler itself: the browser empties the drop's items
+ * once the event is over, so they are taken before anything is awaited.
+ */
+export function readDroppedFiles(
+  source: DropSource,
+  {
+    maxFolderEntries = DEFAULT_MAX_FOLDER_ENTRIES,
+  }: ReadDroppedFilesOptions = {},
+): Promise<DroppedFiles> {
+  const taken =
+    source.items === undefined
+      ? Array.from(source.files, (file) => ({ entry: null, file }))
+      : Array.from(source.items).flatMap((item) =>
+          item.kind === "file"
+            ? [{ entry: item.webkitGetAsEntry(), file: item.getAsFile() }]
+            : [],
+        );
+  return (async () => {
+    const loose: File[] = [];
+    const nested: File[] = [];
+    const folders: string[] = [];
+    const walk: Walk = {
+      remaining: maxFolderEntries,
+      truncated: false,
+      errors: [],
+    };
+    for (const { entry, file } of taken) {
+      if (entry !== null && entry.isDirectory) {
+        folders.push(entry.name);
+        nested.push(...(await filesInFolder(entry, entry.name, walk)));
+      } else if (file !== null) {
+        loose.push(file);
+      }
+    }
+    return {
+      files: [...loose, ...nested],
+      folders,
+      truncated: walk.truncated,
+      errors: walk.errors,
+    };
+  })();
+}
+
+let strayDropGuards = 0;
+
+function guardStrayDrop(event: DragEvent) {
+  // A drop target already took it, or there are no files to open.
+  if (event.defaultPrevented || !carriesFiles(event.dataTransfer)) return;
+  // A native file input takes files by its default action.
+  const target = event.target;
+  if (target instanceof HTMLInputElement && target.type === "file") return;
+  event.preventDefault();
+  if (event.dataTransfer !== null) event.dataTransfer.dropEffect = "none";
+}
+
+/**
+ * Stops files dropped outside every drop target from opening in the tab and
+ * leaving the page. While any component using it is mounted, a file drag
+ * over the rest of the page shows the no-drop cursor and its drop does
+ * nothing. Drops onto drop targets, native file inputs and anything that
+ * handles its own drop (calls `preventDefault`) are untouched; a
+ * `contenteditable` that relies on the browser's own image drop does not get
+ * it while the guard is on.
+ *
+ * However many components use it, the window gets one pair of listeners.
+ */
+export function usePreventStrayDrops(enabled = true): void {
+  useEffect(() => {
+    if (!enabled) return;
+    if (strayDropGuards === 0) {
+      window.addEventListener("dragover", guardStrayDrop);
+      window.addEventListener("drop", guardStrayDrop);
+    }
+    strayDropGuards += 1;
+    return () => {
+      strayDropGuards -= 1;
+      if (strayDropGuards === 0) {
+        window.removeEventListener("dragover", guardStrayDrop);
+        window.removeEventListener("drop", guardStrayDrop);
+      }
+    };
+  }, [enabled]);
+}
+
+export type FileDropDetails = Omit<DroppedFiles, "files">;
+
+export type UseFileDropOptions = ReadDroppedFilesOptions & {
+  /**
+   * Called once a drop has been read, with its files (folders walked) and
+   * what it held. A drop of only empty folders calls it with no files.
+   */
+  readonly onFiles: (files: readonly File[], details: FileDropDetails) => void;
+  /** While true, drags are ignored and the browser's default stands. */
+  readonly disabled?: boolean;
+  /**
+   * Called when a drop could not be read in full: a folder that could not
+   * be listed or a file that could not be opened. The rest of the drop
+   * still reaches `onFiles`. Without it, errors go to `reportError`.
+   */
+  readonly onError?: (error: unknown) => void;
+};
+
+export type FileDropTargetProps<T extends Element> = {
+  readonly onDragEnter: (event: ReactDragEvent<T>) => void;
+  readonly onDragOver: (event: ReactDragEvent<T>) => void;
+  readonly onDragLeave: (event: ReactDragEvent<T>) => void;
+  readonly onDrop: (event: ReactDragEvent<T>) => void;
+};
+
+export type UseFileDropResult<T extends Element> = {
+  /** Whether files are being held over the target. */
+  readonly over: boolean;
+  /** Spread onto the drop target. */
+  readonly dropProps: FileDropTargetProps<T>;
+};
+
+function report(error: unknown) {
+  if (typeof globalThis.reportError === "function")
+    globalThis.reportError(error);
+  else console.error(error);
+}
+
+/**
+ * Makes an element a target for dropped files and folders. Only drags that
+ * carry files are taken; text and links dragged over it behave as usual.
+ *
+ * `over` is true while files are held over the target, including over its
+ * children. It turns false when the drag leaves the target, is dropped, or
+ * ends anywhere on the page.
+ *
+ * Pair it with `usePreventStrayDrops` so a drop that misses the target does
+ * not open the file in place of the page; `AttachmentDropZone` does both.
+ */
+export function useFileDrop<T extends Element = HTMLElement>({
+  onFiles,
+  disabled = false,
+  maxFolderEntries,
+  onError,
+}: UseFileDropOptions): UseFileDropResult<T> {
+  const [over, setOver] = useState(false);
+  const latest = useRef({ onFiles, onError, maxFolderEntries });
+  latest.current = { onFiles, onError, maxFolderEntries };
+  // Counted rather than read from `relatedTarget`, which WebKit leaves null:
+  // moving between two children enters one before leaving the other, so the
+  // count only reaches zero once the drag has left the target.
+  const depth = useRef(0);
+  const entered = useRef<Event | null>(null);
+
+  useEffect(() => {
+    if (!over) return;
+    const reset = () => {
+      depth.current = 0;
+      setOver(false);
+    };
+    // A drag dropped elsewhere or ended never comes back to this target. A
+    // count thrown off (a child removed from under the pointer takes its
+    // leave with it) is put right by the next enter outside the target: one
+    // that did not pass through `onDragEnter` on its way up.
+    const enteredElsewhere = (event: DragEvent) => {
+      if (event !== entered.current) reset();
+    };
+    window.addEventListener("dragend", reset);
+    window.addEventListener("drop", reset);
+    document.addEventListener("dragenter", enteredElsewhere);
+    return () => {
+      window.removeEventListener("dragend", reset);
+      window.removeEventListener("drop", reset);
+      document.removeEventListener("dragenter", enteredElsewhere);
+    };
+  }, [over]);
+
+  useEffect(() => {
+    if (!disabled) return;
+    depth.current = 0;
+    setOver(false);
+  }, [disabled]);
+
+  const takes = (event: ReactDragEvent<T>) =>
+    !disabled && carriesFiles(event.dataTransfer);
+
+  return {
+    over: over && !disabled,
+    dropProps: {
+      onDragEnter: (event) => {
+        if (!takes(event)) return;
+        event.preventDefault();
+        entered.current = event.nativeEvent;
+        depth.current += 1;
+        setOver(true);
+      },
+      onDragOver: (event) => {
+        if (!takes(event)) return;
+        event.preventDefault();
+        event.dataTransfer.dropEffect = "copy";
+        // Over the target after a reset, its enter long gone.
+        if (depth.current === 0) depth.current = 1;
+        setOver(true);
+      },
+      onDragLeave: (event) => {
+        if (!takes(event)) return;
+        depth.current = Math.max(0, depth.current - 1);
+        if (depth.current === 0) setOver(false);
+      },
+      onDrop: (event) => {
+        if (!takes(event)) return;
+        event.preventDefault();
+        depth.current = 0;
+        setOver(false);
+        const options = latest.current.maxFolderEntries;
+        readDroppedFiles(
+          event.dataTransfer,
+          options === undefined ? {} : { maxFolderEntries: options },
+        ).then(
+          ({ files, ...details }) => {
+            const { onFiles: deliver, onError: fail } = latest.current;
+            for (const error of details.errors) (fail ?? report)(error);
+            if (files.length > 0 || details.folders.length > 0) {
+              deliver(files, details);
+            }
+          },
+          (error: unknown) => (latest.current.onError ?? report)(error),
+        );
+      },
+    },
+  };
+}
diff --git a/src/index.ts b/src/index.ts
index 323b8508..2564847d 100644
--- a/src/index.ts
+++ b/src/index.ts
@@ -27,6 +27,8 @@ export * from "./hooks/use-tab-drag.js";
 export * from "./hooks/use-copy.js";
 export * from "./hooks/use-history-window.js";
 export * from "./hooks/use-reading-position.js";
+export * from "./hooks/use-attachments.js";
+export * from "./hooks/use-file-drop.js";
 export * from "./lib/artifact.js";
 export * from "./lib/chart-palette.js";
 export * from "./lib/chat-message.js";
@@ -152,3 +154,5 @@ export * from "./ui/message-reactions.js";
 export * from "./ui/message-replies.js";
 export * from "./ui/conversation-earlier.js";
 export * from "./ui/conversation-map.js";
+export * from "./ui/attachments.js";
+export * from "./ui/attachment-drop-zone.js";
diff --git a/src/ui/attachment-drop-zone.tsx b/src/ui/attachment-drop-zone.tsx
new file mode 100644
index 00000000..dbf91651
--- /dev/null
+++ b/src/ui/attachment-drop-zone.tsx
@@ -0,0 +1,76 @@
+"use client";
+
+import { Paperclip } from "lucide-react";
+import type * as React from "react";
+
+import {
+  useFileDrop,
+  usePreventStrayDrops,
+  type UseFileDropOptions,
+} from "../hooks/use-file-drop.js";
+import { cn } from "../lib/utils.js";
+
+export type AttachmentDropZoneProps = Omit<
+  React.ComponentProps<"div">,
+  | keyof UseFileDropOptions
+  | "onDragEnter"
+  | "onDragOver"
+  | "onDragLeave"
+  | "onDrop"
+> &
+  UseFileDropOptions & {
+    /** Shown over the zone while files are held over it. */
+    readonly label?: React.ReactNode;
+  };
+
+/**
+ * An area that takes dropped files and whole folders, usually the chat
+ * around its input. While files are held over it, it rings itself and shows
+ * `label`; the content stays visible beneath. A drop that misses it does not
+ * open the file in place of the page.
+ *
+ * Dropping needs a pointer, so put a file picker (such as `FileInput`)
+ * inside it for keyboard and touch.
+ */
+export function AttachmentDropZone({
+  onFiles,
+  disabled = false,
+  maxFolderEntries,
+  onError,
+  label = "Drop files to attach",
+  className,
+  children,
+  ...props
+}: AttachmentDropZoneProps) {
+  const { over, dropProps } = useFileDrop<HTMLDivElement>({
+    onFiles,
+    disabled,
+    ...(maxFolderEntries === undefined ? {} : { maxFolderEntries }),
+    ...(onError === undefined ? {} : { onError }),
+  });
+  usePreventStrayDrops();
+
+  return (
+    <div
+      data-slot="attachment-drop-zone"
+      data-over={over ? "true" : undefined}
+      className={cn("relative", className)}
+      {...props}
+      {...dropProps}
+    >
+      {children}
+      {over ? (
+        <div
+          aria-hidden
+          data-slot="attachment-drop-zone-overlay"
+          className="pointer-events-none absolute inset-0 z-40 flex items-center justify-center rounded-lg bg-background/80 outline-2 -outline-offset-2 outline-primary outline-dashed motion-safe:animate-[corbits-fade-in_120ms_ease-out]"
+        >
+          <span className="flex items-center gap-2 rounded-md bg-card px-3 py-2 text-sm font-medium text-card-foreground shadow-surface">
+            <Paperclip aria-hidden className="size-4 text-primary-emphasis" />
+            {label}
+          </span>
+        </div>
+      ) : null}
+    </div>
+  );
+}
diff --git a/src/ui/attachments.test.tsx b/src/ui/attachments.test.tsx
new file mode 100644
index 00000000..0df55d6a
--- /dev/null
+++ b/src/ui/attachments.test.tsx
@@ -0,0 +1,117 @@
+import { act, useRef, useState } from "react";
+import { createRoot } from "react-dom/client";
+import { describe, expect, test } from "bun:test";
+
+import {
+  Attachment,
+  AttachmentPreview,
+  AttachmentRemove,
+  Attachments,
+  type AttachmentData,
+} from "./attachments.js";
+
+function mount(node: React.ReactElement) {
+  const container = document.createElement("div");
+  document.body.appendChild(container);
+  const root = createRoot(container);
+  act(() => root.render(node));
+  return {
+    container,
+    unmount: () => {
+      act(() => root.unmount());
+      container.remove();
+    },
+  };
+}
+
+const NOTES: AttachmentData = { name: "notes.txt", mediaType: "text/plain" };
+
+/** A composer that stops rendering the list once it is empty. */
+function Composer({ files }: { readonly files: readonly AttachmentData[] }) {
+  const [held, setHeld] = useState(files);
+  const message = useRef<HTMLTextAreaElement>(null);
+  return (
+    <div>
+      {held.length === 0 ? null : (
+        <Attachments variant="list" returnFocusTo={message}>
+          {held.map((data) => (
+            <Attachment key={data.name} data={data}>
+              <AttachmentRemove
+                onClick={() =>
+                  setHeld((previous) =>
+                    previous.filter((item) => item !== data),
+                  )
+                }
+              />
+            </Attachment>
+          ))}
+        </Attachments>
+      )}
+      <textarea ref={message} aria-label="Message" />
+    </div>
+  );
+}
+
+function button(container: HTMLElement, name: string): HTMLButtonElement {
+  const found = container.querySelector<HTMLButtonElement>(
+    `button[aria-label='${name}']`,
+  );
+  if (found === null) throw new Error(`no ${name} button`);
+  return found;
+}
+
+describe("Attachments", () => {
+  test("removing the last attachment returns focus, list gone or not", () => {
+    const { container, unmount } = mount(
+      <Composer files={[NOTES, { name: "plan.md", mediaType: "" }]} />,
+    );
+    const first = button(container, "Remove notes.txt");
+    first.focus();
+    act(() => first.click());
+    expect(document.activeElement).toBe(button(container, "Remove plan.md"));
+
+    act(() => button(container, "Remove plan.md").click());
+    expect(container.querySelector("ul")).toBeNull();
+    expect(document.activeElement?.getAttribute("aria-label")).toBe("Message");
+    unmount();
+  });
+
+  test("a preview that opens keeps the host's props", () => {
+    const opened: string[] = [];
+    const keys: string[] = [];
+    const seen: { element: HTMLElement | null } = { element: null };
+    const { container, unmount } = mount(
+      <Attachments>
+        <Attachment data={NOTES}>
+          <AttachmentPreview
+            ref={(node) => {
+              seen.element = node;
+            }}
+            data-testid="preview"
+            title="Preview"
+            aria-label="Host name"
+            onKeyDown={(event) => keys.push(event.key)}
+            onOpen={(data) => opened.push(data.name)}
+          />
+        </Attachment>
+      </Attachments>,
+    );
+    const preview = container.querySelector<HTMLElement>(
+      "[data-testid=preview]",
+    );
+    expect(preview?.tagName).toBe("BUTTON");
+    expect(seen.element).toBe(preview);
+    expect(preview?.title).toBe("Preview");
+    // Its own name wins.
+    expect(preview?.getAttribute("aria-label")).toBe("Open notes.txt");
+    act(() => {
+      preview?.dispatchEvent(
+        new KeyboardEvent("keydown", { key: "a", bubbles: true }),
+      );
+      preview?.click();
+    });
+    expect(keys).toEqual(["a"]);
+    expect(opened).toEqual(["notes.txt"]);
+    unmount();
+  });
+});
diff --git a/src/ui/attachments.tsx b/src/ui/attachments.tsx
new file mode 100644
index 00000000..f4fdc122
--- /dev/null
+++ b/src/ui/attachments.tsx
@@ -0,0 +1,702 @@
+"use client";
+
+import {
+  File as FileIcon,
+  FileAudio,
+  FileImage,
+  FileText,
+  FileVideo,
+  Play,
+  X,
+} from "lucide-react";
+import {
+  createContext,
+  useCallback,
+  useContext,
+  useLayoutEffect,
+  useRef,
+  useState,
+} from "react";
+import type * as React from "react";
+
+import { useControllableState } from "../hooks/use-controllable-state.js";
+import { mediaKindOf, type MediaKind } from "../lib/media-kind.js";
+import { cn } from "../lib/utils.js";
+
+/**
+ * A file as `Attachment` shows it. An `AttachmentItem` from
+ * `useAttachments` fits, and so does a message's `PartFile`.
+ */
+export type AttachmentData = {
+  readonly name: string;
+  readonly mediaType: string;
+  /** In bytes; left out when not known. */
+  readonly size?: number;
+  /** Where to show or open it from. */
+  readonly url?: string;
+};
+
+/**
+ * `stack`: a deck of cards above the message box that fans out when pointed
+ * at or tabbed into. `tiles`: thumbnails in a message. `list`: one row each.
+ */
+export type AttachmentsVariant = "stack" | "tiles" | "list";
+
+type AttachmentsContextValue = {
+  readonly variant: AttachmentsVariant;
+  readonly expanded: boolean;
+  readonly setExpanded: (expanded: boolean) => void;
+  /** Where focus goes when the attachment holding it is removed. */
+  readonly focusAfterRemove: React.RefObject<HTMLElement | null>;
+  /** Where focus goes when no other attachment is left to take it. */
+  readonly returnFocusTo: React.RefObject<HTMLElement | null> | undefined;
+  /** Which item takes focus once `AttachmentMore`, holding it, expands the list. */
+  readonly focusAfterExpand: React.RefObject<number | null>;
+};
+
+const AttachmentsContext = createContext<AttachmentsContextValue | null>(null);
+
+function useAttachmentsContext(part: string): AttachmentsContextValue {
+  const context = useContext(AttachmentsContext);
+  if (context === null) throw new Error(`${part} must be inside Attachments.`);
+  return context;
+}
+
+type AttachmentContextValue = {
+  readonly data: AttachmentData;
+  readonly kind: MediaKind;
+  /** Whether the preview shows the file itself rather than its type. */
+  readonly pictured: boolean;
+  readonly setBroken: () => void;
+};
+
+const AttachmentContext = createContext<AttachmentContextValue | null>(null);
+
+function useAttachmentContext(part: string): AttachmentContextValue {
+  const context = useContext(AttachmentContext);
+  if (context === null)
+    throw new Error(`${part} must be inside an Attachment.`);
+  return context;
+}
+
+/** "18 KB", "2.4 MB". */
+function formatBytes(bytes: number): string {
+  if (bytes < 1024) return `${bytes} B`;
+  if (bytes < 1024 ** 2) return `${Math.round(bytes / 1024)} KB`;
+  if (bytes < 1024 ** 3) return `${(bytes / 1024 ** 2).toFixed(1)} MB`;
+  return `${(bytes / 1024 ** 3).toFixed(1)} GB`;
+}
+
+/** "PDF", "CSV": the type, for a file with no picture to show. */
+function extensionOf(name: string): string {
+  const base = name.slice(name.lastIndexOf("/") + 1);
+  const dot = base.lastIndexOf(".");
+  return dot <= 0 ? "FILE" : base.slice(dot + 1, dot + 5).toUpperCase();
+}
+
+/** "report.pdf, 2.4 MB": how a control names the file. */
+function describe(data: AttachmentData): string {
+  return data.size === undefined
+    ? data.name
+    : `${data.name}, ${formatBytes(data.size)}`;
+}
+
+function KindIcon({
+  kind,
+  className,
+}: {
+  readonly kind: MediaKind;
+  readonly className?: string;
+}) {
+  const Icon =
+    kind === "image"
+      ? FileImage
+      : kind === "video"
+        ? FileVideo
+        : kind === "audio"
+          ? FileAudio
+          : kind === "pdf" || kind === "text"
+            ? FileText
+            : FileIcon;
+  return <Icon aria-hidden className={className} />;
+}
+
+// The deck is laid out from the list, so a card never has to know where it
+// sits: overlapped and tilted at rest, fanned out and upright while the list
+// is pointed at or holds focus. The list is the hover target, not the cards,
+// so a card lifting away from the pointer does not drop the hover.
+const STACK_DECK = [
+  "relative flex w-fit items-end pt-1",
+  "[&>li+li]:ms-2 motion-safe:[&>li]:transition-[margin,translate,rotate,opacity] motion-safe:[&>li]:duration-200 motion-safe:[&>li]:ease-out",
+  "pointer-fine:[&:not(:hover,:focus-within)>li+li]:-ms-10.5",
+  "pointer-fine:[&:not(:hover,:focus-within)>li:nth-child(odd)]:-rotate-3",
+  "pointer-fine:[&:not(:hover,:focus-within)>li:nth-child(even)]:rotate-3",
+  "pointer-fine:[&:is(:hover,:focus-within)>li]:-translate-y-3.5",
+  // The count, on the top card's corner, until the deck fans out.
+  "after:pointer-events-none after:absolute after:-top-1 after:-end-1.5 after:grid after:h-5 after:min-w-5 after:place-items-center after:rounded-full after:bg-primary after:px-1 after:text-xs after:font-semibold after:text-primary-foreground after:ring-2 after:ring-background after:content-[attr(data-total)_/_''] after:motion-safe:transition-opacity",
+  "pointer-coarse:after:hidden [&:is(:hover,:focus-within)]:after:opacity-0 [&:not([data-total])]:after:hidden",
+].join(" ");
+
+const ROOT: Record<AttachmentsVariant, string> = {
+  stack: STACK_DECK,
+  tiles: "flex flex-wrap gap-2",
+  list: "flex flex-col gap-1.5",
+};
+
+export type AttachmentsState = { readonly expanded: boolean };
+
+export type AttachmentsProps = Omit<React.ComponentProps<"ul">, "children"> & {
+  readonly variant?: AttachmentsVariant;
+  /**
+   * Whether every attachment is shown. The host decides what folds away
+   * while this is false (say, all but the first five) and renders an
+   * `AttachmentMore` for the rest, which sets it to true. A stack that is
+   * expanded lays its cards out in rows, upright, each with its name.
+   */
+  readonly expanded?: boolean | undefined;
+  readonly defaultExpanded?: boolean;
+  readonly onExpandedChange?: ((expanded: boolean) => void) | undefined;
+  /**
+   * How many attachments there are, folded ones included: the stack shows
+   * it on its top card, and it names the list ("3 attachments").
+   */
+  readonly total?: number;
+  /**
+   * Where focus goes when the attachment holding it is removed and no other
+   * is left to take it: the message box, or the file picker. Without it,
+   * focus goes to the list, and is lost if the host stops rendering the list
+   * once it is empty.
+   */
+  readonly returnFocusTo?: React.RefObject<HTMLElement | null>;
+  /**
+   * The `Attachment`s, and an `AttachmentMore` when some are folded away.
+   * A function gets the current `expanded`, for a host that leaves it
+   * uncontrolled.
+   */
+  readonly children?:
+    | React.ReactNode
+    | ((state: AttachmentsState) => React.ReactNode);
+};
+
+/**
+ * Files shown three ways: a `stack` above the message box, `tiles` in a
+ * message, or a `list`. The host renders an `Attachment` for each file and
+ * owns the list itself; this only lays them out.
+ *
+ * When an attachment holding focus is removed, focus moves to the next
+ * attachment's remove button, or the previous one's, or `returnFocusTo`, or
+ * the list. Controls of the host's own that go away as they are used ("Show
+ * less", "Remove all") move focus themselves.
+ */
+export function Attachments({
+  variant = "tiles",
+  expanded: expandedProp,
+  defaultExpanded = false,
+  onExpandedChange,
+  total,
+  returnFocusTo,
+  className,
+  ref,
+  children,
+  ...props
+}: AttachmentsProps) {
+  const [expanded, setExpanded] = useControllableState({
+    value: expandedProp,
+    defaultValue: defaultExpanded,
+    onChange: onExpandedChange,
+    name: "Attachments",
+  });
+  const focusAfterRemove = useRef<HTMLElement | null>(null);
+  const focusAfterExpand = useRef<number | null>(null);
+  const listRef = useRef<HTMLUListElement | null>(null);
+  const setList = useCallback(
+    (element: HTMLUListElement | null) => {
+      listRef.current = element;
+      if (typeof ref === "function") ref(element);
+      else if (ref !== null && ref !== undefined) ref.current = element;
+    },
+    [ref],
+  );
+
+  // "+N" goes away as the list expands; focus moves to the first attachment
+  // it was folding, not back to the start of the page.
+  useLayoutEffect(() => {
+    const index = focusAfterExpand.current;
+    const list = listRef.current;
+    if (!expanded || index === null || list === null) return;
+    focusAfterExpand.current = null;
+    const revealed = list.children.item(index);
+    const control =
+      revealed?.querySelector<HTMLElement>("button, [tabindex='0']") ?? list;
+    control.focus();
+  }, [expanded]);
+
+  return (
+    <AttachmentsContext.Provider
+      value={{
+        variant,
+        expanded,
+        setExpanded,
+        focusAfterRemove,
+        focusAfterExpand,
+        returnFocusTo,
+      }}
+    >
+      <ul
+        ref={setList}
+        data-slot="attachments"
+        data-variant={variant}
+        data-expanded={expanded ? "true" : undefined}
+        data-total={
+          variant === "stack" && total !== undefined && total > 1
+            ? total
+            : undefined
+        }
+        aria-label={
+          total === undefined
+            ? "Attachments"
+            : `${total} ${total === 1 ? "attachment" : "attachments"}`
+        }
+        tabIndex={-1}
+        className={cn(
+          variant === "stack" && expanded
+            ? "flex flex-wrap items-start gap-2"
+            : ROOT[variant],
+          className,
+        )}
+        {...props}
+      >
+        {typeof children === "function" ? children({ expanded }) : children}
+      </ul>
+    </AttachmentsContext.Provider>
+  );
+}
+
+function itemClasses(variant: AttachmentsVariant, expanded: boolean): string {
+  const card =
+    "group/attachment relative shrink-0 rounded-lg bg-card text-card-foreground ring-1 ring-border";
+  switch (variant) {
+    case "stack":
+      return cn(
+        card,
+        "shadow-surface",
+        expanded ? "flex w-19 flex-col items-center gap-1 pb-1.5" : "size-13",
+      );
+    case "tiles":
+      return cn(
+        card,
+        "flex size-30 flex-col gap-1 p-2.5 has-[button[data-slot=attachment-preview]:hover]:ring-border-strong",
+        "data-[pictured=true]:w-auto data-[pictured=true]:max-w-60 data-[pictured=true]:min-w-20 data-[pictured=true]:p-0",
+      );
+    case "list":
+      return cn(card, "flex min-w-0 items-center gap-3 p-2");
+  }
+}
+
+export type AttachmentProps = React.ComponentProps<"li"> & {
+  readonly data: AttachmentData;
+};
+
+/** One file in `Attachments`; its parts read the file from here. */
+export function Attachment({
+  data,
+  className,
+  ref,
+  children,
+  ...props
+}: AttachmentProps) {
+  const { variant, expanded, focusAfterRemove } =
+    useAttachmentsContext("Attachment");
+  const kind = mediaKindOf(data.name, data.mediaType);
+  const [brokenURL, setBrokenURL] = useState<string | null>(null);
+  const pictured =
+    (kind === "image" || kind === "video") &&
+    data.url !== undefined &&
+    data.url !== brokenURL;
+  const setBroken = useCallback(
+    () => setBrokenURL(data.url ?? null),
+    [data.url],
+  );
+  const elementRef = useRef<HTMLLIElement | null>(null);
+
+  const setElement = useCallback(
+    (element: HTMLLIElement | null) => {
+      elementRef.current = element;
+      if (typeof ref === "function") ref(element);
+      else if (ref !== null && ref !== undefined) ref.current = element;
+    },
+    [ref],
+  );
+
+  // A layout cleanup runs while the item is still attached, so `contains`
+  // still sees focus inside it.
+  useLayoutEffect(() => {
+    const element = elementRef.current;
+    return () => {
+      const target = focusAfterRemove.current;
+      if (
+        element === null ||
+        target === null ||
+        !element.contains(document.activeElement)
+      ) {
+        return;
+      }
+      focusAfterRemove.current = null;
+      if (target.isConnected) target.focus();
+    };
+  }, [focusAfterRemove]);
+
+  return (
+    <AttachmentContext.Provider value={{ data, kind, pictured, setBroken }}>
+      <li
+        ref={setElement}
+        data-slot="attachment"
+        data-kind={kind}
+        data-pictured={pictured ? "true" : undefined}
+        className={cn(itemClasses(variant, expanded), className)}
+        {...props}
+      >
+        {children}
+      </li>
+    </AttachmentContext.Provider>
+  );
+}
+
+function previewClasses(
+  variant: AttachmentsVariant,
+  expanded: boolean,
+  pictured: boolean,
+): string {
+  switch (variant) {
+    case "stack":
+      return cn(
+        "grid w-full place-items-center overflow-hidden",
+        expanded ? "h-13 rounded-t-lg" : "h-full rounded-lg",
+      );
+    case "tiles":
+      // A tile without a picture is all preview too, so the whole tile
+      // opens it; the name and size show through from beneath.
+      return pictured
+        ? "grid h-full place-items-center overflow-hidden rounded-lg"
+        : "absolute inset-0 flex items-start rounded-lg p-2.5";
+    case "list":
+      return "grid size-10 shrink-0 place-items-center overflow-hidden rounded-md bg-muted";
+  }
+}
+
+export type AttachmentPreviewProps = Omit<
+  React.HTMLAttributes<HTMLElement>,
+  "children" | "onClick"
+> & {
+  /** A `<span>`, or a `<button>` with `onOpen`. */
+  readonly ref?: React.Ref<HTMLElement>;
+  /**
+   * Makes the preview a button that hands the file over, for a viewer to
+   * open it. Without it the preview is decorative.
+   */
+  readonly onOpen?: ((data: AttachmentData) => void) | undefined;
+};
+
+/**
+ * The file at a glance: the picture, a video's first frame, or for anything
+ * else its type. A picture that fails to load falls back to the type.
+ *
+ * Host props reach the element either way; its own role, name and click
+ * stay its own.
+ */
+export function AttachmentPreview({
+  onOpen,
+  className,
+  ref,
+  ...props
+}: AttachmentPreviewProps) {
+  const { variant, expanded } = useAttachmentsContext("AttachmentPreview");
+  const { data, kind, pictured, setBroken } =
+    useAttachmentContext("AttachmentPreview");
+  const setElement = useCallback(
+    (element: HTMLElement | null) => {
+      if (typeof ref === "function") ref(element);
+      else if (ref !== null && ref !== undefined) ref.current = element;
+    },
+    [ref],
+  );
+  const url = data.url;
+
+  let face: React.ReactNode;
+  if (pictured && kind === "image" && url !== undefined) {
+    face = (
+      <img
+        src={url}
+        alt=""
+        loading="lazy"
+        decoding="async"
+        onError={setBroken}
+        className={cn(
+          "h-full bg-muted object-cover",
+          // A screenshot keeps its heading in view in a tile.
+          variant === "tiles" ? "w-auto max-w-60 object-left-top" : "w-full",
+        )}
+      />
+    );
+  } else if (pictured && kind === "video" && url !== undefined) {
+    face = (
+      <>
+        <video
+          // Without a start time, some browsers paint no frame for metadata.
+          src={url.includes("#") ? url : `${url}#t=0.1`}
+          muted
+          playsInline
+          preload="metadata"
+          onError={setBroken}
+          className={cn(
+            "h-full bg-muted object-cover",
+            variant === "tiles" ? "w-auto max-w-60" : "w-full",
+          )}
+        />
+        <span
+          aria-hidden
+          className="absolute inset-0 m-auto grid size-6 place-items-center rounded-full bg-foreground/70 text-background"
+        >
+          <Play className="size-3" />
+        </span>
+      </>
+    );
+  } else if (variant === "tiles") {
+    face = (
+      <span className="inline-flex items-center gap-1 rounded-sm bg-muted px-1.5 py-0.5 text-xs font-semibold tracking-wide text-muted-foreground">
+        <KindIcon kind={kind} className="size-3" />
+        {extensionOf(data.name)}
+      </span>
+    );
+  } else {
+    face = (
+      <span className="flex flex-col items-center gap-0.5 text-muted-foreground">
+        <KindIcon kind={kind} className="size-4" />
+        {variant === "stack" ? (
+          <span className="text-xs leading-none font-semibold tracking-wide">
+            {extensionOf(data.name)}
+          </span>
+        ) : null}
+      </span>
+    );
+  }
+
+  const shared = cn(
+    "relative",
+    previewClasses(variant, expanded, pictured),
+    className,
+  );
+
+  if (onOpen === undefined) {
+    return (
+      <span
+        {...props}
+        ref={setElement}
+        data-slot="attachment-preview"
+        aria-hidden
+        className={shared}
+      >
+        {face}
+      </span>
+    );
+  }
+  return (
+    <button
+      {...props}
+      ref={setElement}
+      type="button"
+      data-slot="attachment-preview"
+      aria-label={`Open ${describe(data)}`}
+      className={cn(shared, "cursor-pointer", pictured && "cursor-zoom-in")}
+      onClick={() => onOpen(data)}
+    >
+      {face}
+    </button>
+  );
+}
+
+function infoClasses(
+  variant: AttachmentsVariant,
+  expanded: boolean,
+  pictured: boolean,
+): string {
+  switch (variant) {
+    case "stack":
+      return expanded
+        ? "flex w-full flex-col items-center px-1.5 text-center"
+        : cn(
+            "pointer-events-none absolute start-0 bottom-full z-10 mb-2 flex w-max max-w-60 gap-2 rounded-md bg-popover px-2 py-1 text-popover-foreground shadow-surface ring-1 ring-border",
+            "opacity-0 group-hover/attachment:opacity-100 group-focus-within/attachment:opacity-100 motion-safe:transition-opacity",
+          );
+    case "tiles":
+      return pictured ? "sr-only" : "mt-auto flex min-w-0 flex-col gap-0.5";
+    case "list":
+      return "flex min-w-0 flex-1 flex-col";
+  }
+}
+
+export type AttachmentInfoProps = Omit<
+  React.ComponentProps<"span">,
+  "children"
+>;
+
+/** The file's name and size. */
+export function AttachmentInfo({ className, ...props }: AttachmentInfoProps) {
+  const { variant, expanded } = useAttachmentsContext("AttachmentInfo");
+  const { data, pictured } = useAttachmentContext("AttachmentInfo");
+  const stacked = variant === "stack";
+  return (
+    <span
+      data-slot="attachment-info"
+      className={cn(infoClasses(variant, expanded, pictured), className)}
+      {...props}
+    >
+      <span
+        data-slot="attachment-name"
+        className={cn(
+          "min-w-0 font-medium [overflow-wrap:anywhere]",
+          variant === "list" && "truncate text-sm",
+          variant === "tiles" && "line-clamp-3 text-sm leading-snug",
+          stacked && (expanded ? "line-clamp-2 text-xs" : "truncate text-xs"),
+        )}
+      >
+        {data.name}
+      </span>
+      {data.size === undefined || (stacked && expanded) ? null : (
+        <span
+          data-slot="attachment-size"
+          className="shrink-0 text-xs text-muted-foreground"
+        >
+          {variant === "list"
+            ? `${extensionOf(data.name)} · ${formatBytes(data.size)}`
+            : formatBytes(data.size)}
+        </span>
+      )}
+    </span>
+  );
+}
+
+const REMOVE: Record<AttachmentsVariant, string> = {
+  stack:
+    "absolute -top-1.5 -end-1.5 z-10 size-5 rounded-full bg-primary text-primary-foreground ring-2 ring-background opacity-0 group-hover/attachment:opacity-100 focus-visible:opacity-100 pointer-coarse:opacity-100 [&_svg]:size-3",
+  tiles:
+    "absolute top-1 end-1 z-10 size-6 rounded-full bg-background/90 text-foreground ring-1 ring-border opacity-0 group-hover/attachment:opacity-100 focus-visible:opacity-100 pointer-coarse:opacity-100 [&_svg]:size-3.5",
+  list: "size-8 shrink-0 rounded-md text-muted-foreground hover:bg-muted hover:text-foreground [&_svg]:size-4",
+};
+
+export type AttachmentRemoveProps = Omit<
+  React.ComponentProps<"button">,
+  "children"
+> & {
+  /** The accessible name; defaults to "Remove" and the file's name. */
+  readonly label?: string;
+};
+
+/**
+ * Removes the file: `onClick` asks the host to take it out of its list.
+ * Focus moves on to the next attachment once it is gone, or to
+ * `returnFocusTo` on `Attachments` when it was the last.
+ */
+export function AttachmentRemove({
+  label,
+  className,
+  onClick,
+  ...props
+}: AttachmentRemoveProps) {
+  const { variant, focusAfterRemove, returnFocusTo } =
+    useAttachmentsContext("AttachmentRemove");
+  const { data } = useAttachmentContext("AttachmentRemove");
+  return (
+    <button
+      type="button"
+      data-slot="attachment-remove"
+      aria-label={label ?? `Remove ${data.name}`}
+      className={cn(
+        "grid cursor-pointer place-items-center motion-safe:transition-[opacity,background-color,color]",
+        REMOVE[variant],
+        className,
+      )}
+      onClick={(event) => {
+        const item = event.currentTarget.closest("[data-slot=attachment]");
+        const list = item?.parentElement ?? null;
+        const removeOf = (sibling: Element | null) =>
+          sibling?.querySelector<HTMLElement>(
+            "[data-slot=attachment-remove]",
+          ) ?? null;
+        focusAfterRemove.current =
+          removeOf(item?.nextElementSibling ?? null) ??
+          removeOf(item?.previousElementSibling ?? null) ??
+          returnFocusTo?.current ??
+          (list instanceof HTMLElement ? list : null);
+        onClick?.(event);
+      }}
+      {...props}
+    >
+      <X aria-hidden />
+    </button>
+  );
+}
+
+const MORE: Record<AttachmentsVariant, string> = {
+  stack:
+    "size-13 rounded-lg bg-card text-sm font-semibold text-muted-foreground shadow-surface ring-1 ring-border hover:text-foreground pointer-fine:[ul:not([data-expanded],:hover,:focus-within)>li>&]:pointer-events-none pointer-fine:[ul:not([data-expanded],:hover,:focus-within)>li>&]:opacity-0",
+  tiles:
+    "size-30 rounded-lg bg-card text-base font-semibold text-muted-foreground ring-1 ring-border hover:text-foreground",
+  list: "h-9 w-full rounded-md px-3 text-start text-sm font-medium text-muted-foreground hover:bg-muted hover:text-foreground",
+};
+
+export type AttachmentMoreProps = Omit<
+  React.ComponentProps<"button">,
+  "children"
+> & {
+  /** How many attachments are folded away. */
+  readonly count: number;
+};
+
+/**
+ * The attachments folded away, as "+N": clicking it expands `Attachments`.
+ * In a stack it shows once the deck fans out.
+ */
+export function AttachmentMore({
+  count,
+  className,
+  onClick,
+  ...props
+}: AttachmentMoreProps) {
+  const { variant, setExpanded, focusAfterExpand } =
+    useAttachmentsContext("AttachmentMore");
+  return (
+    <li
+      data-slot="attachment-more"
+      className={cn(
+        "flex shrink-0",
+        // Out of the folded deck's flow, so the count sits on the top card.
+        variant === "stack" &&
+          "pointer-fine:[ul:not([data-expanded],:hover,:focus-within)>&]:absolute",
+      )}
+    >
+      <button
+        type="button"
+        aria-label={`Show ${count} more`}
+        className={cn(
+          "cursor-pointer motion-safe:transition-[opacity,background-color,color]",
+          MORE[variant],
+          className,
+        )}
+        onClick={(event) => {
+          onClick?.(event);
+          if (event.defaultPrevented) return;
+          const item = event.currentTarget.closest("li");
+          focusAfterExpand.current =
+            item?.parentElement === null || item === null
+              ? null
+              : Array.prototype.indexOf.call(item.parentElement.children, item);
+          setExpanded(true);
+        }}
+        {...props}
+      >
+        {variant === "list" ? `Show ${count} more` : `+${count}`}
+      </button>
+    </li>
+  );
+}
diff --git a/stories/chat/attachments.stories.tsx b/stories/chat/attachments.stories.tsx
new file mode 100644
index 00000000..2b4c50a4
--- /dev/null
+++ b/stories/chat/attachments.stories.tsx
@@ -0,0 +1,315 @@
+import { useRef, useState, type RefObject } from "react";
+import { flushSync } from "react-dom";
+
+import {
+  useAttachments,
+  type AttachmentItem,
+} from "../../src/hooks/use-attachments.js";
+import type { AttachmentRejection } from "../../src/lib/attachment-limits.js";
+import type { PartFile } from "../../src/lib/chat-parts.js";
+import { AttachmentDropZone } from "../../src/ui/attachment-drop-zone.js";
+import {
+  Attachment,
+  AttachmentInfo,
+  AttachmentMore,
+  AttachmentPreview,
+  AttachmentRemove,
+  Attachments,
+  type AttachmentData,
+  type AttachmentsVariant,
+} from "../../src/ui/attachments.js";
+import { Button } from "../../src/ui/button.js";
+import { FileInput } from "../../src/ui/file-input.js";
+import { Textarea } from "../../src/ui/textarea.js";
+import { generatedImages, shortChat } from "./samples/conversations.js";
+
+export default { title: "Chat / Attachments" };
+
+/** The sample conversations' pictures, as files someone attached. */
+const PICTURES = generatedImages.messages
+  .flatMap((message) => message.parts)
+  .flatMap((part) => (part.kind === "image" ? part.images : []))
+  .map((image) => ({
+    name: `${image.id}.svg`,
+    mediaType: image.mediaType,
+    url:
+      "url" in image
+        ? image.url
+        : `data:${image.mediaType};base64,${image.base64}`,
+  }));
+
+const DOCUMENTS: readonly Omit<AttachmentData, "size">[] = [
+  { name: "quarter-plan.pdf", mediaType: "application/pdf" },
+  { name: "runs-this-week.csv", mediaType: "text/csv" },
+  { name: "handler.ts", mediaType: "" },
+  { name: "standup.m4a", mediaType: "audio/mp4" },
+  { name: "screen-recording.mov", mediaType: "video/quicktime" },
+  { name: "release-notes-for-the-spring-workflow-update.md", mediaType: "" },
+  { name: "exports.zip", mediaType: "application/zip" },
+];
+
+/** `count` files: pictures and documents taking turns, each a little bigger. */
+function files(count: number): readonly AttachmentItem[] {
+  return Array.from({ length: count }, (_, index) => {
+    const pool: readonly Omit<AttachmentData, "size">[] =
+      index % 2 === 0 ? PICTURES : DOCUMENTS;
+    const source = pool[Math.floor(index / 2) % pool.length];
+    if (source === undefined) throw new Error("no sample file");
+    const round = Math.floor(index / (2 * pool.length));
+    return {
+      ...source,
+      id: `file-${index}`,
+      name:
+        round === 0 ? source.name : source.name.replace(".", `-${round + 1}.`),
+      size: 1200 + index * 48_311,
+    };
+  });
+}
+
+const FOLDED: Record<AttachmentsVariant, number> = {
+  stack: 5,
+  tiles: 6,
+  list: 5,
+};
+
+/**
+ * Attachments as a host renders them: removable, folded past a few, with
+ * "Show less" and "Remove all" once expanded, and "Reset" to bring the files
+ * back. Opening reports which file.
+ *
+ * Nothing it removes takes focus with it: the last attachment and "Remove
+ * all" hand focus to `returnFocusTo` (or "Reset"), and "Show less" to "+N".
+ */
+function Host({
+  variant,
+  initial,
+  returnFocusTo,
+}: {
+  readonly variant: AttachmentsVariant;
+  readonly initial: readonly AttachmentData[];
+  /** The message box, when there is one. */
+  readonly returnFocusTo?: RefObject<HTMLElement | null>;
+}) {
+  const fresh = () =>
+    initial.map((data, index) => ({ id: `item-${index}`, data }));
+  const [items, setItems] = useState(fresh);
+  const [expanded, setExpanded] = useState(false);
+  const [opened, setOpened] = useState<string | null>(null);
+  const reset = useRef<HTMLButtonElement>(null);
+  const list = useRef<HTMLUListElement>(null);
+  const more = useRef<HTMLButtonElement>(null);
+  const fallback = returnFocusTo ?? reset;
+  const limit = FOLDED[variant];
+  const folded = !expanded && items.length > limit;
+  const shown = folded ? items.slice(0, limit - 1) : items;
+  const removable = variant !== "tiles";
+
+  return (
+    <div className="flex flex-col gap-3">
+      {items.length === 0 ? (
+        <p className="text-sm text-muted-foreground">No attachments.</p>
+      ) : (
+        <Attachments
+          ref={list}
+          variant={variant}
+          total={items.length}
+          expanded={expanded}
+          onExpandedChange={setExpanded}
+          returnFocusTo={fallback}
+        >
+          {shown.map(({ id, data }) => (
+            <Attachment key={id} data={data}>
+              <AttachmentPreview onOpen={(file) => setOpened(file.name)} />
+              <AttachmentInfo />
+              {removable ? (
+                <AttachmentRemove
+                  onClick={() =>
+                    setItems((previous) =>
+                      previous.filter((item) => item.id !== id),
+                    )
+                  }
+                />
+              ) : null}
+            </Attachment>
+          ))}
+          {folded ? (
+            <AttachmentMore ref={more} count={items.length - shown.length} />
+          ) : null}
+        </Attachments>
+      )}
+      {expanded || removable ? (
+        <div className="flex gap-2">
+          {expanded ? (
+            <Button
+              variant="outline"
+              size="sm"
+              onClick={() => {
+                flushSync(() => setExpanded(false));
+                (more.current ?? list.current)?.focus();
+              }}
+            >
+              Show less
+            </Button>
+          ) : null}
+          {expanded && removable ? (
+            <Button
+              variant="outline"
+              size="sm"
+              onClick={() => {
+                fallback.current?.focus();
+                setExpanded(false);
+                setItems([]);
+              }}
+            >
+              Remove all
+            </Button>
+          ) : null}
+          {removable ? (
+            <Button
+              ref={reset}
+              variant="outline"
+              size="sm"
+              onClick={() => {
+                setExpanded(false);
+                setItems(fresh());
+              }}
+            >
+              Reset
+            </Button>
+          ) : null}
+        </div>
+      ) : null}
+      <p className="text-sm text-muted-foreground">
+        Opened: <output aria-label="Opened file">{opened ?? "nothing"}</output>
+      </p>
+    </div>
+  );
+}
+
+/** The stack sits above the message box, with room for it to lift. */
+function AboveInput({ count }: { readonly count: number }) {
+  const message = useRef<HTMLTextAreaElement>(null);
+  return (
+    <div className="flex max-w-xl flex-col gap-2 pt-24">
+      <Host variant="stack" initial={files(count)} returnFocusTo={message} />
+      <Textarea
+        ref={message}
+        aria-label="Message"
+        placeholder="Ask anything…"
+        rows={2}
+      />
+    </div>
+  );
+}
+
+export const StackOne = () => <AboveInput count={1} />;
+export const StackFive = () => <AboveInput count={5} />;
+/** Folds to four cards and "+21"; point at it or tab in to fan it out. */
+export const StackTwentyFive = () => <AboveInput count={25} />;
+
+export const TilesOne = () => <Host variant="tiles" initial={files(1)} />;
+export const TilesFive = () => <Host variant="tiles" initial={files(5)} />;
+export const TilesTwentyFive = () => (
+  <Host variant="tiles" initial={files(25)} />
+);
+
+/** A sent message's files carry no size; the tiles go without it. */
+export const TilesFromMessage = () => (
+  <Host
+    variant="tiles"
+    initial={shortChat.messages
+      .flatMap((message) => message.parts)
+      .filter((part): part is PartFile => part.kind === "file")}
+  />
+);
+
+export const ListOne = () => (
+  <div className="max-w-md">
+    <Host variant="list" initial={files(1)} />
+  </div>
+);
+export const ListFive = () => (
+  <div className="max-w-md">
+    <Host variant="list" initial={files(5)} />
+  </div>
+);
+export const ListTwentyFive = () => (
+  <div className="max-w-md">
+    <Host variant="list" initial={files(25)} />
+  </div>
+);
+
+function refusal({ file, reason }: AttachmentRejection<File>): string {
+  switch (reason) {
+    case "too-large":
+      return `${file.name} is over 5 MB`;
+    case "duplicate":
+      return `${file.name} is already attached`;
+    case "too-many":
+      return `${file.name} is past the limit of 20`;
+  }
+}
+
+/**
+ * Drop files or folders anywhere on the box, or choose them. Up to 20 files
+ * of 5 MB each; anything refused is said why.
+ */
+export const DropZone = () => {
+  const [attachments, setAttachments] = useState<readonly AttachmentItem[]>([]);
+  const [notice, setNotice] = useState("");
+  const picker = useRef<HTMLInputElement>(null);
+  const { add } = useAttachments({
+    attachments,
+    maxFiles: 20,
+    maxFileBytes: 5 * 1024 * 1024,
+  });
+  const take = (incoming: Iterable<File> | ArrayLike<File>) => {
+    const { accepted, rejected } = add(incoming);
+    setAttachments((previous) => [...previous, ...accepted]);
+    setNotice(rejected.map(refusal).join("; "));
+  };
+
+  return (
+    <AttachmentDropZone
+      onFiles={(dropped, { folders }) => {
+        if (dropped.length === 0 && folders.length > 0) {
+          setNotice(`${folders.join(", ")} has no files to add`);
+        } else {
+          take(dropped);
+        }
+      }}
+      className="flex max-w-xl flex-col gap-3 rounded-lg border border-border p-4 pt-24"
+    >
+      {attachments.length === 0 ? null : (
+        <Attachments
+          variant="stack"
+          total={attachments.length}
+          returnFocusTo={picker}
+        >
+          {attachments.map((item) => (
+            <Attachment key={item.id} data={item}>
+              <AttachmentPreview />
+              <AttachmentInfo />
+              <AttachmentRemove
+                onClick={() =>
+                  setAttachments((previous) =>
+                    previous.filter((held) => held.id !== item.id),
+                  )
+                }
+              />
+            </Attachment>
+          ))}
+        </Attachments>
+      )}
+      <FileInput
+        ref={picker}
+        multiple
+        onFiles={take}
+        hint="or drop files and folders anywhere here"
+      />
+      <p role="status" className="min-h-5 text-sm text-muted-foreground">
+        {notice}
+      </p>
+    </AttachmentDropZone>
+  );
+};

From 7c243eeff287d6b82fb0cec0d0948156b3b0eb82 Mon Sep 17 00:00:00 2001
From: 0xPratik <sariapratik@gmail.com>
Date: Tue, 27 Oct 2026 14:14:25 +0545
Subject: [PATCH 2/8] fix(attachments): rebuild revoked previews and cover the
 disabled option

A hook hidden by Activity for longer than a tick cannot tell the hide
from an unmount, so useAttachments revokes its previews while the host
still holds the items, and the previews came back blank. Attachment
now rebuilds the picture from the item's file when its url fails,
owning that url and revoking it on unmount or hide. The hook's docs
say the held url itself stays dead, so code that reads it should make
its own from the file or keep the hook above the Activity.

No test passed disabled to useFileDrop, and the test named for it
covered the stray-drop guard instead; both are now tested.

AttachmentPreview takes a label for its open button, as
AttachmentRemove already does. The docs say AttachmentMore renders
last and how to name the drop zone as a region, carriesFiles is no
longer public, and tests exercise the uncontrolled fold.
---
 src/hooks/use-attachments.test.ts |  22 ++++
 src/hooks/use-attachments.ts      |   9 +-
 src/hooks/use-file-drop.test.ts   |  47 ++++++-
 src/hooks/use-file-drop.ts        |   4 +-
 src/ui/attachment-drop-zone.tsx   |   3 +-
 src/ui/attachments.test.tsx       | 195 +++++++++++++++++++++++++++++-
 src/ui/attachments.tsx            |  90 +++++++++++---
 7 files changed, 342 insertions(+), 28 deletions(-)

diff --git a/src/hooks/use-attachments.test.ts b/src/hooks/use-attachments.test.ts
index 9a3e2f4f..e8b27e8f 100644
--- a/src/hooks/use-attachments.test.ts
+++ b/src/hooks/use-attachments.test.ts
@@ -133,6 +133,13 @@ function mountHost({ strict = false, initial = [], ...limits }: Options = {}) {
       act(() => setHidden(true));
       act(() => setHidden(false));
     },
+    /** Hides the hook in its `Activity` for longer than a tick, then shows it. */
+    async hideAndShow() {
+      act(() => setHidden(true));
+      await act(microtasks);
+      act(() => setHidden(false));
+      await act(microtasks);
+    },
     unmount() {
       act(() => root.unmount());
       container.remove();
@@ -249,6 +256,21 @@ describe("useAttachments", () => {
     expect([...revoked].sort()).toEqual([...created].sort());
   });
 
+  // Nothing tells a hide from an unmount, so the previews go and the held
+  // items keep their dead URLs; `Attachment` rebuilds the pictures from
+  // `file` (see attachments.test.tsx).
+  test("a hide longer than a tick revokes the held previews", async () => {
+    const host = mountHost();
+    const [item] = host.drop([file("a.png", 4, "image/png")]).accepted;
+    if (item === undefined) throw new Error("missing");
+
+    await host.hideAndShow();
+    expect(revoked).toEqual([item.url ?? ""]);
+    expect(host.list).toEqual([item]);
+    expect(host.list[0]?.file).toBeInstanceOf(File);
+    host.unmount();
+  });
+
   test("the host's own URLs are never revoked", async () => {
     const uploaded: AttachmentItem = {
       id: "uploaded-1",
diff --git a/src/hooks/use-attachments.ts b/src/hooks/use-attachments.ts
index 6376e66c..ee751818 100644
--- a/src/hooks/use-attachments.ts
+++ b/src/hooks/use-attachments.ts
@@ -69,8 +69,13 @@ function nextAttachmentId(): string {
  *
  * The unmount revoke waits a microtask and is called off if the hook mounts
  * again, which is what StrictMode's simulated remount does within one
- * commit. A hook hidden by `<Activity mode="hidden">` counts as unmounted,
- * and its previews are revoked.
+ * commit. A hook hidden by `<Activity mode="hidden">` for longer than that
+ * counts as unmounted: its previews are revoked, and once it shows again
+ * the attachments still held keep URLs that no longer load. `Attachment`
+ * rebuilds their pictures from `file`. Anything else that reads `url`
+ * after such a hide, such as a viewer opened from `AttachmentPreview`'s
+ * `onOpen`, should make its own URL from `file`, or the hook should sit
+ * above the `Activity`.
  */
 export function useAttachments({
   attachments,
diff --git a/src/hooks/use-file-drop.test.ts b/src/hooks/use-file-drop.test.ts
index 1adf118e..656b8dd4 100644
--- a/src/hooks/use-file-drop.test.ts
+++ b/src/hooks/use-file-drop.test.ts
@@ -1,5 +1,5 @@
 import { describe, expect, test } from "bun:test";
-import { act, createElement } from "react";
+import { act, createElement, useState } from "react";
 import { createRoot } from "react-dom/client";
 
 import {
@@ -192,16 +192,23 @@ function dropEffectOf(event: Event): unknown {
 
 type Received = { files: readonly File[]; details: FileDropDetails };
 
-function mountTarget({ guard = true }: { guard?: boolean } = {}) {
+function mountTarget({
+  guard = true,
+  disabled: initiallyDisabled = false,
+}: { guard?: boolean; disabled?: boolean } = {}) {
   const container = document.createElement("div");
   document.body.appendChild(container);
   const root = createRoot(container);
   const received: Received[] = [];
   let over = false;
+  let setDisabled: (disabled: boolean) => void = () => {};
 
   function Target() {
+    const [disabled, setTargetDisabled] = useState(initiallyDisabled);
+    setDisabled = setTargetDisabled;
     const drop = useFileDrop<HTMLDivElement>({
       onFiles: (files, details) => received.push({ files, details }),
+      disabled,
     });
     usePreventStrayDrops(guard);
     over = drop.over;
@@ -223,6 +230,9 @@ function mountTarget({ guard = true }: { guard?: boolean } = {}) {
     get over() {
       return over;
     },
+    disable(disabled = true) {
+      act(() => setDisabled(disabled));
+    },
     fire(target: EventTarget, event: Event) {
       act(() => {
         target.dispatchEvent(event);
@@ -243,6 +253,37 @@ function settle(): Promise<void> {
 }
 
 describe("useFileDrop", () => {
+  // The stray-drop guard is off, so only the hook can claim these events.
+  test("takes no drag while disabled", async () => {
+    const target = mountTarget({ guard: false, disabled: true });
+    const files = source([new File(["a"], "a.txt")]);
+    for (const type of ["dragenter", "dragover", "dragleave", "drop"]) {
+      const event = target.fire(target.zone, dragEvent(type, files));
+      expect(event.defaultPrevented).toBe(false);
+      expect(target.over).toBe(false);
+    }
+    await settle();
+    expect(target.received).toEqual([]);
+    target.unmount();
+  });
+
+  test("disabling mid-drag drops over, and enabling takes drags again", () => {
+    const target = mountTarget({ guard: false });
+    const files = source([new File(["a"], "a.txt")]);
+    target.fire(target.zone, dragEvent("dragenter", files));
+    expect(target.over).toBe(true);
+
+    target.disable();
+    expect(target.over).toBe(false);
+    target.disable(false);
+    expect(target.over).toBe(false);
+
+    const enter = target.fire(target.zone, dragEvent("dragenter", files));
+    expect(enter.defaultPrevented).toBe(true);
+    expect(target.over).toBe(true);
+    target.unmount();
+  });
+
   test("a dropped folder reaches onFiles walked to its files", async () => {
     const target = mountTarget();
     const drop = target.fire(target.zone, dragEvent("drop", source([PROJECT])));
@@ -405,7 +446,7 @@ describe("usePreventStrayDrops", () => {
     expect(after.defaultPrevented).toBe(false);
   });
 
-  test("does nothing when disabled", () => {
+  test("stray-drop guard off leaves body drops alone", () => {
     const target = mountTarget({ guard: false });
     const files = source([new File(["a"], "a.txt")]);
     expect(
diff --git a/src/hooks/use-file-drop.ts b/src/hooks/use-file-drop.ts
index c926d65d..d39d30c9 100644
--- a/src/hooks/use-file-drop.ts
+++ b/src/hooks/use-file-drop.ts
@@ -54,9 +54,7 @@ export type ReadDroppedFilesOptions = {
 const DEFAULT_MAX_FOLDER_ENTRIES = 500;
 
 /** Whether a drag carries files, as opposed to text or a link. */
-export function carriesFiles(
-  source: Pick<DropSource, "types"> | null,
-): boolean {
+function carriesFiles(source: Pick<DropSource, "types"> | null): boolean {
   return source !== null && source.types.includes("Files");
 }
 
diff --git a/src/ui/attachment-drop-zone.tsx b/src/ui/attachment-drop-zone.tsx
index dbf91651..a4fe015d 100644
--- a/src/ui/attachment-drop-zone.tsx
+++ b/src/ui/attachment-drop-zone.tsx
@@ -30,7 +30,8 @@ export type AttachmentDropZoneProps = Omit<
  * open the file in place of the page.
  *
  * Dropping needs a pointer, so put a file picker (such as `FileInput`)
- * inside it for keyboard and touch.
+ * inside it for keyboard and touch. The zone is a plain `div`: give it
+ * `role="region"` and an `aria-label` when it should be a landmark.
  */
 export function AttachmentDropZone({
   onFiles,
diff --git a/src/ui/attachments.test.tsx b/src/ui/attachments.test.tsx
index 0df55d6a..db3a6bd2 100644
--- a/src/ui/attachments.test.tsx
+++ b/src/ui/attachments.test.tsx
@@ -1,9 +1,14 @@
-import { act, useRef, useState } from "react";
+import { Activity, act, useRef, useState } from "react";
 import { createRoot } from "react-dom/client";
-import { describe, expect, test } from "bun:test";
+import { afterEach, beforeEach, describe, expect, test } from "bun:test";
 
+import {
+  useAttachments,
+  type AttachmentItem,
+} from "../hooks/use-attachments.js";
 import {
   Attachment,
+  AttachmentMore,
   AttachmentPreview,
   AttachmentRemove,
   Attachments,
@@ -114,4 +119,190 @@ describe("Attachments", () => {
     expect(opened).toEqual(["notes.txt"]);
     unmount();
   });
+
+  test("a preview that opens takes its name from label", () => {
+    const { container, unmount } = mount(
+      <Attachments>
+        <Attachment data={NOTES}>
+          <AttachmentPreview label="View the notes" onOpen={() => {}} />
+        </Attachment>
+      </Attachments>,
+    );
+    expect(button(container, "View the notes").dataset["slot"]).toBe(
+      "attachment-preview",
+    );
+    unmount();
+  });
+
+  test("an uncontrolled list folds until More expands it", () => {
+    const files: readonly AttachmentData[] = ["a.txt", "b.txt", "c.txt"].map(
+      (name) => ({ name, mediaType: "text/plain" }),
+    );
+    const { container, unmount } = mount(
+      <Attachments variant="list">
+        {({ expanded }) => {
+          const shown = expanded ? files : files.slice(0, 1);
+          return (
+            <>
+              {shown.map((data) => (
+                <Attachment key={data.name} data={data}>
+                  <AttachmentRemove />
+                </Attachment>
+              ))}
+              {expanded ? null : <AttachmentMore count={files.length - 1} />}
+            </>
+          );
+        }}
+      </Attachments>,
+    );
+    const names = () =>
+      [...container.querySelectorAll("[data-slot=attachment-remove]")].map(
+        (element) => element.getAttribute("aria-label"),
+      );
+    expect(names()).toEqual(["Remove a.txt"]);
+
+    const more = button(container, "Show 2 more");
+    more.focus();
+    act(() => more.click());
+    expect(names()).toEqual(["Remove a.txt", "Remove b.txt", "Remove c.txt"]);
+    expect(container.querySelector("ul")?.dataset["expanded"]).toBe("true");
+    // Focus goes to the first attachment that was folded away.
+    expect(document.activeElement).toBe(button(container, "Remove b.txt"));
+    unmount();
+  });
+
+  test("defaultExpanded starts an uncontrolled list expanded", () => {
+    const { container, unmount } = mount(
+      <Attachments variant="list" defaultExpanded>
+        {({ expanded }) => (expanded ? <li>all</li> : <li>some</li>)}
+      </Attachments>,
+    );
+    expect(container.textContent).toBe("all");
+    unmount();
+  });
+});
+
+describe("a preview held across a hidden Activity", () => {
+  let live = new Set<string>();
+  let made = 0;
+  const realCreate = URL.createObjectURL;
+  const realRevoke = URL.revokeObjectURL;
+
+  beforeEach(() => {
+    live = new Set();
+    made = 0;
+    URL.createObjectURL = () => {
+      made += 1;
+      const url = `blob:test/${made}`;
+      live.add(url);
+      return url;
+    };
+    URL.revokeObjectURL = (url: string) => {
+      live.delete(url);
+    };
+  });
+
+  afterEach(() => {
+    URL.createObjectURL = realCreate;
+    URL.revokeObjectURL = realRevoke;
+  });
+
+  function tick(): Promise<void> {
+    return act(() => new Promise<void>((resolve) => setTimeout(resolve, 0)));
+  }
+
+  test("is rebuilt from its file once its URL stops loading", async () => {
+    let attach: (files: readonly File[]) => void = () => {};
+    let setHidden: (hidden: boolean) => void = () => {};
+
+    function Composer() {
+      const [held, setHeld] = useState<readonly AttachmentItem[]>([]);
+      const { add } = useAttachments({ attachments: held });
+      attach = (files) => {
+        const { accepted } = add(files);
+        setHeld((previous) => [...previous, ...accepted]);
+      };
+      return (
+        <Attachments variant="tiles">
+          {held.map((item) => (
+            <Attachment key={item.id} data={item}>
+              <AttachmentPreview />
+            </Attachment>
+          ))}
+        </Attachments>
+      );
+    }
+
+    function Route() {
+      const [hidden, setRouteHidden] = useState(false);
+      setHidden = setRouteHidden;
+      return (
+        <Activity mode={hidden ? "hidden" : "visible"}>
+          <Composer />
+        </Activity>
+      );
+    }
+
+    const { container, unmount } = mount(<Route />);
+    act(() => attach([new File(["x"], "shot.png", { type: "image/png" })]));
+    const picture = () => container.querySelector("img");
+    const first = picture()?.getAttribute("src") ?? "";
+    expect(live.has(first)).toBe(true);
+
+    // Hidden for longer than a tick: the hook's previews go.
+    act(() => setHidden(true));
+    await tick();
+    act(() => setHidden(false));
+    await tick();
+    expect(live.has(first)).toBe(false);
+
+    // The browser fails to load the revoked URL.
+    act(() => {
+      picture()?.dispatchEvent(new Event("error"));
+    });
+    const rebuilt = picture()?.getAttribute("src") ?? "";
+    expect(rebuilt).not.toBe(first);
+    expect(live.has(rebuilt)).toBe(true);
+
+    // The rebuilt URL follows the same rule: gone while hidden, made again
+    // on show.
+    act(() => setHidden(true));
+    expect(live.has(rebuilt)).toBe(false);
+    act(() => setHidden(false));
+    const again = picture()?.getAttribute("src") ?? "";
+    expect(live.has(again)).toBe(true);
+
+    unmount();
+    await tick();
+    expect([...live]).toEqual([]);
+  });
+
+  test("falls back to the type when the rebuilt URL fails too", () => {
+    const shot = new File(["x"], "shot.png", { type: "image/png" });
+    const { container, unmount } = mount(
+      <Attachments variant="tiles">
+        <Attachment
+          data={{
+            name: "shot.png",
+            mediaType: "image/png",
+            url: "blob:test/gone",
+            file: shot,
+          }}
+        >
+          <AttachmentPreview />
+        </Attachment>
+      </Attachments>,
+    );
+    const fail = () =>
+      act(() => {
+        container.querySelector("img")?.dispatchEvent(new Event("error"));
+      });
+    fail();
+    expect(container.querySelector("img")).not.toBeNull();
+    fail();
+    expect(container.querySelector("img")).toBeNull();
+    expect(container.textContent).toContain("PNG");
+    unmount();
+    expect([...live]).toEqual([]);
+  });
 });
diff --git a/src/ui/attachments.tsx b/src/ui/attachments.tsx
index f4fdc122..f49a8ebd 100644
--- a/src/ui/attachments.tsx
+++ b/src/ui/attachments.tsx
@@ -34,6 +34,12 @@ export type AttachmentData = {
   readonly size?: number;
   /** Where to show or open it from. */
   readonly url?: string;
+  /**
+   * The local file, when there is one. A picture whose `url` no longer
+   * loads, such as a preview `useAttachments` revoked while it was hidden,
+   * is rebuilt from it.
+   */
+  readonly file?: File;
 };
 
 /**
@@ -67,6 +73,9 @@ type AttachmentContextValue = {
   readonly kind: MediaKind;
   /** Whether the preview shows the file itself rather than its type. */
   readonly pictured: boolean;
+  /** Where the picture loads from: `data.url`, or one rebuilt from the file. */
+  readonly src: string | undefined;
+  /** The picture failed to load. */
   readonly setBroken: () => void;
 };
 
@@ -297,6 +306,48 @@ export type AttachmentProps = React.ComponentProps<"li"> & {
   readonly data: AttachmentData;
 };
 
+/**
+ * Where a picture loads from: `url`, or, once that fails to load and the
+ * file is at hand, a URL made from the file. A URL made here is revoked
+ * when the attachment unmounts or is hidden, and made again when it shows.
+ * A rebuilt URL that fails too leaves no picture.
+ */
+function usePictureSource(
+  url: string | undefined,
+  file: File | undefined,
+): { readonly src: string | undefined; readonly setBroken: () => void } {
+  const [failed, setFailed] = useState<{
+    readonly url: string | undefined;
+    readonly rebuilt: boolean;
+  } | null>(null);
+  const failedHere = failed !== null && failed.url === url;
+  const source =
+    failedHere && !failed.rebuilt && file !== undefined ? file : undefined;
+  const [rebuilt, setRebuilt] = useState<{
+    readonly file: File;
+    readonly url: string;
+  } | null>(null);
+
+  // Before paint, so the picture never flashes its type on the way.
+  useLayoutEffect(() => {
+    if (source === undefined) return;
+    const made = URL.createObjectURL(source);
+    setRebuilt({ file: source, url: made });
+    return () => URL.revokeObjectURL(made);
+  }, [source]);
+
+  const src = !failedHere
+    ? url
+    : source !== undefined && rebuilt?.file === source
+      ? rebuilt.url
+      : undefined;
+  const setBroken = useCallback(
+    () => setFailed({ url, rebuilt: failedHere }),
+    [url, failedHere],
+  );
+  return { src, setBroken };
+}
+
 /** One file in `Attachments`; its parts read the file from here. */
 export function Attachment({
   data,
@@ -308,15 +359,8 @@ export function Attachment({
   const { variant, expanded, focusAfterRemove } =
     useAttachmentsContext("Attachment");
   const kind = mediaKindOf(data.name, data.mediaType);
-  const [brokenURL, setBrokenURL] = useState<string | null>(null);
-  const pictured =
-    (kind === "image" || kind === "video") &&
-    data.url !== undefined &&
-    data.url !== brokenURL;
-  const setBroken = useCallback(
-    () => setBrokenURL(data.url ?? null),
-    [data.url],
-  );
+  const { src, setBroken } = usePictureSource(data.url, data.file);
+  const pictured = (kind === "image" || kind === "video") && src !== undefined;
   const elementRef = useRef<HTMLLIElement | null>(null);
 
   const setElement = useCallback(
@@ -347,7 +391,9 @@ export function Attachment({
   }, [focusAfterRemove]);
 
   return (
-    <AttachmentContext.Provider value={{ data, kind, pictured, setBroken }}>
+    <AttachmentContext.Provider
+      value={{ data, kind, pictured, src, setBroken }}
+    >
       <li
         ref={setElement}
         data-slot="attachment"
@@ -395,24 +441,33 @@ export type AttachmentPreviewProps = Omit<
    * open it. Without it the preview is decorative.
    */
   readonly onOpen?: ((data: AttachmentData) => void) | undefined;
+  /** The accessible name with `onOpen`; defaults to "Open" and the file. */
+  readonly label?: string;
 };
 
 /**
  * The file at a glance: the picture, a video's first frame, or for anything
- * else its type. A picture that fails to load falls back to the type.
+ * else its type. A picture that fails to load is rebuilt from `data.file`
+ * when there is one, and otherwise falls back to the type.
  *
  * Host props reach the element either way; its own role, name and click
- * stay its own.
+ * stay its own. Name it with `label`.
  */
 export function AttachmentPreview({
   onOpen,
+  label,
   className,
   ref,
   ...props
 }: AttachmentPreviewProps) {
   const { variant, expanded } = useAttachmentsContext("AttachmentPreview");
-  const { data, kind, pictured, setBroken } =
-    useAttachmentContext("AttachmentPreview");
+  const {
+    data,
+    kind,
+    pictured,
+    src: url,
+    setBroken,
+  } = useAttachmentContext("AttachmentPreview");
   const setElement = useCallback(
     (element: HTMLElement | null) => {
       if (typeof ref === "function") ref(element);
@@ -420,8 +475,6 @@ export function AttachmentPreview({
     },
     [ref],
   );
-  const url = data.url;
-
   let face: React.ReactNode;
   if (pictured && kind === "image" && url !== undefined) {
     face = (
@@ -506,7 +559,7 @@ export function AttachmentPreview({
       ref={setElement}
       type="button"
       data-slot="attachment-preview"
-      aria-label={`Open ${describe(data)}`}
+      aria-label={label ?? `Open ${describe(data)}`}
       className={cn(shared, "cursor-pointer", pictured && "cursor-zoom-in")}
       onClick={() => onOpen(data)}
     >
@@ -656,6 +709,9 @@ export type AttachmentMoreProps = Omit<
 /**
  * The attachments folded away, as "+N": clicking it expands `Attachments`.
  * In a stack it shows once the deck fans out.
+ *
+ * Render it last, after the attachments shown: once the list expands, focus
+ * moves to whichever attachment takes its place.
  */
 export function AttachmentMore({
   count,

From 59de8959fd299f1fa3d2086801acf355fb58dd8b Mon Sep 17 00:00:00 2001
From: 0xPratik <sariapratik@gmail.com>
Date: Wed, 28 Oct 2026 16:53:18 +0545
Subject: [PATCH 3/8] fix(attachments): take a nested picker's drop once and
 drop late reads

A drop on a FileInput inside the drop zone reached both the picker and
the zone, so the file was attached and then refused as already there,
or attached twice by a host that does not de-duplicate. The zone now
leaves a drop a child already handled to that child.

A folder walk could also outlive the zone: it still delivered after
the zone was disabled, and after unmount it added files whose preview
URLs nothing would revoke. A read that finishes once the zone is
disabled or unmounted is now dropped, and useAttachments makes no
preview URL once it has unmounted.

A nameless file was checked for duplicates under its empty name but
held as "Untitled", so two of them could slip in and a real Untitled
was refused. The check now uses the name the file is held under.
---
 e2e/attachments.spec.ts           | 22 ++++++++++
 e2e/fixtures.tsx                  | 11 +++--
 src/hooks/use-attachments.test.ts | 29 +++++++++++++
 src/hooks/use-attachments.ts      | 41 ++++++++++++++-----
 src/hooks/use-file-drop.test.ts   | 68 ++++++++++++++++++++++++++++++-
 src/hooks/use-file-drop.ts        | 37 +++++++++++++----
 src/ui/attachment-drop-zone.tsx   |  7 +++-
 7 files changed, 191 insertions(+), 24 deletions(-)

diff --git a/e2e/attachments.spec.ts b/e2e/attachments.spec.ts
index 4fafd54b..59ba6f97 100644
--- a/e2e/attachments.spec.ts
+++ b/e2e/attachments.spec.ts
@@ -262,6 +262,28 @@ test("a dropped folder is walked to the files inside it", async ({ page }) => {
   }
 });
 
+test("a drop on the picker inside the zone is taken once", async ({ page }) => {
+  await page.goto("/attachments");
+  await page.locator("[data-testid=zone] label").evaluate((picker) => {
+    const data = new DataTransfer();
+    data.items.add(new File(["hi"], "notes.txt", { type: "text/plain" }));
+    for (const type of ["dragenter", "dragover", "drop"]) {
+      picker.dispatchEvent(
+        new DragEvent(type, {
+          dataTransfer: data,
+          bubbles: true,
+          cancelable: true,
+        }),
+      );
+    }
+  });
+  await expect(count(page)).toHaveText("1");
+  await expect(page.getByRole("status", { name: "Refused" })).toHaveText("");
+  await expect(
+    page.locator("[data-slot=attachment-drop-zone-overlay]"),
+  ).toHaveCount(0);
+});
+
 test("files dropped outside the zone do not open in place of the page", async ({
   page,
 }) => {
diff --git a/e2e/fixtures.tsx b/e2e/fixtures.tsx
index fd78fc41..1d1cd56e 100644
--- a/e2e/fixtures.tsx
+++ b/e2e/fixtures.tsx
@@ -69,6 +69,7 @@ import {
   Attachment,
   AttachmentDropZone,
   AttachmentInfo,
+  FileInput,
   AttachmentMore,
   AttachmentPreview,
   AttachmentRemove,
@@ -1391,6 +1392,11 @@ function AttachmentsScenario() {
   });
   const folded = !expanded && attachments.length > 5;
   const shown = folded ? attachments.slice(0, 4) : attachments;
+  const take = (files: Iterable<File> | ArrayLike<File>) => {
+    const { accepted, rejected } = add(files);
+    setAttachments((previous) => [...previous, ...accepted]);
+    setRefused(refusals(rejected));
+  };
   return (
     <div style={{ display: "flex", flexDirection: "column", gap: 24 }}>
       <div data-testid="outside" style={{ height: 80 }}>
@@ -1399,9 +1405,7 @@ function AttachmentsScenario() {
       <AttachmentDropZone
         data-testid="zone"
         onFiles={(files, details) => {
-          const { accepted, rejected } = add(files);
-          setAttachments((previous) => [...previous, ...accepted]);
-          setRefused(refusals(rejected));
+          take(files);
           setFolders(details.folders.join(","));
         }}
         style={{ padding: "96px 16px 16px", width: 640 }}
@@ -1444,6 +1448,7 @@ function AttachmentsScenario() {
           </Button>
         ) : null}
         <textarea ref={message} aria-label="Message" />
+        <FileInput multiple onFiles={take} />
       </AttachmentDropZone>
       <output aria-label="Count">{attachments.length}</output>
       <output aria-label="Refused">{refused}</output>
diff --git a/src/hooks/use-attachments.test.ts b/src/hooks/use-attachments.test.ts
index e8b27e8f..38a0549c 100644
--- a/src/hooks/use-attachments.test.ts
+++ b/src/hooks/use-attachments.test.ts
@@ -178,6 +178,24 @@ describe("useAttachments", () => {
     host.unmount();
   });
 
+  test("a nameless file is checked as the Untitled it is held as", () => {
+    const host = mountHost();
+    const [item] = host.drop([file("")]).accepted;
+    if (item === undefined) throw new Error("missing");
+    expect(item.name).toBe("Untitled");
+
+    const nameless = file("");
+    const named = file("Untitled");
+    expect(host.drop([nameless]).rejected).toEqual([
+      { file: nameless, reason: "duplicate" },
+    ]);
+    expect(host.drop([named]).rejected).toEqual([
+      { file: named, reason: "duplicate" },
+    ]);
+    expect(host.list).toEqual([item]);
+    host.unmount();
+  });
+
   test("two adds before the list updates still respect the limits", () => {
     const host = mountHost({ maxFiles: 2 });
     let second: ReturnType<UseAttachmentsResult["add"]> | undefined;
@@ -242,6 +260,17 @@ describe("useAttachments", () => {
   // StrictMode replays effects only at mount, before any URL is made, so
   // the replay here comes after: the effects are torn down and set up again
   // while the previews are on screen.
+  // A drop still being read, or any other late caller.
+  test("an add after unmounting makes no preview URL", async () => {
+    const host = mountHost();
+    host.unmount();
+    await microtasks();
+    const [item] = host.add([file("a.txt")]).accepted;
+    expect(item?.url).toBeUndefined();
+    expect(item?.file).toBeInstanceOf(File);
+    expect(created).toEqual([]);
+  });
+
   test("an effect replay while previews are held revokes nothing", async () => {
     const host = mountHost({ strict: true });
     host.drop([file("a.txt"), file("b.txt")]);
diff --git a/src/hooks/use-attachments.ts b/src/hooks/use-attachments.ts
index ee751818..dccc1615 100644
--- a/src/hooks/use-attachments.ts
+++ b/src/hooks/use-attachments.ts
@@ -45,6 +45,11 @@ export type UseAttachmentsResult = {
 
 let lastAttachmentId = 0;
 
+/** The name a file is held under. */
+function nameOf(file: File): string {
+  return file.name === "" ? "Untitled" : file.name;
+}
+
 function nextAttachmentId(): string {
   lastAttachmentId += 1;
   return `attachment-${lastAttachmentId}`;
@@ -62,7 +67,7 @@ function nextAttachmentId(): string {
  * Every URL the hook makes is revoked at the first commit whose list does
  * not hold its attachment: once the host removes it, however it does, or
  * right away if the host never appended it. The rest go when the hook
- * unmounts. Only
+ * unmounts, and an `add` after that makes no URL. Only
  * URLs the hook made are revoked; the host's own are left alone. To keep an
  * attachment on screen after it leaves the list (sending moves it into a
  * message), `release` it first.
@@ -86,7 +91,9 @@ export function useAttachments({
   const pending = useRef<AttachmentItem[]>([]);
   const latest = useRef({ attachments, maxFiles, maxFileBytes });
   latest.current = { attachments, maxFiles, maxFileBytes };
-  const mounted = useRef(false);
+  // True until the hook unmounts, so an `add` before its effects run still
+  // makes a URL.
+  const mounted = useRef(true);
 
   // After every commit, not only when the list changes: an accepted file the
   // host did not append must neither keep its URL nor count as a duplicate
@@ -124,26 +131,40 @@ export function useAttachments({
       ...(max === undefined ? {} : { maxFiles: max }),
       ...(maxBytes === undefined ? {} : { maxFileBytes: maxBytes }),
     };
+    // Checked under the name each file will be held under, so a nameless
+    // file is a duplicate of the "Untitled" one already held.
     const { accepted, rejected } = checkAttachments(
       [...held, ...pending.current],
-      Array.from(files),
+      Array.from(files, (file) => ({
+        name: nameOf(file),
+        size: file.size,
+        file,
+      })),
       limits,
     );
-    const items = accepted.map((file): AttachmentItem => {
+    const items = accepted.map(({ name, file }): AttachmentItem => {
       const id = nextAttachmentId();
-      const url = URL.createObjectURL(file);
-      urls.current.set(id, url);
-      return {
+      const item = {
         id,
-        name: file.name === "" ? "Untitled" : file.name,
+        name,
         mediaType: file.type === "" ? "application/octet-stream" : file.type,
         size: file.size,
-        url,
         file,
       };
+      // Past unmount nothing would revoke it.
+      if (!mounted.current) return item;
+      const url = URL.createObjectURL(file);
+      urls.current.set(id, url);
+      return { ...item, url };
     });
     pending.current = [...pending.current, ...items];
-    return { accepted: items, rejected };
+    return {
+      accepted: items,
+      rejected: rejected.map(({ file, reason }) => ({
+        file: file.file,
+        reason,
+      })),
+    };
   }, []);
 
   const release = useCallback((ids: Iterable<string>) => {
diff --git a/src/hooks/use-file-drop.test.ts b/src/hooks/use-file-drop.test.ts
index 656b8dd4..6564931a 100644
--- a/src/hooks/use-file-drop.test.ts
+++ b/src/hooks/use-file-drop.test.ts
@@ -1,5 +1,6 @@
 import { describe, expect, test } from "bun:test";
 import { act, createElement, useState } from "react";
+import type { DragEvent as ReactDragEvent } from "react";
 import { createRoot } from "react-dom/client";
 
 import {
@@ -59,6 +60,27 @@ function folderEntry(
   };
 }
 
+/** A folder whose listing waits until `release` is called. */
+function heldFolder(name: string, entries: readonly DroppedEntry[]) {
+  let release = () => {};
+  const listed = new Promise<void>((resolve) => {
+    release = resolve;
+  });
+  const folder = folderEntry(name, entries);
+  const entry: DroppedEntry = {
+    ...folder,
+    createReader: () => {
+      const reader = folder.createReader?.();
+      return {
+        readEntries: (success, failure) => {
+          void listed.then(() => reader?.readEntries(success, failure));
+        },
+      };
+    },
+  };
+  return { entry, release };
+}
+
 function source(
   dropped: readonly (DroppedEntry | File)[],
   types: readonly string[] = ["Files"],
@@ -195,7 +217,8 @@ type Received = { files: readonly File[]; details: FileDropDetails };
 function mountTarget({
   guard = true,
   disabled: initiallyDisabled = false,
-}: { guard?: boolean; disabled?: boolean } = {}) {
+  childTakesDrops = false,
+}: { guard?: boolean; disabled?: boolean; childTakesDrops?: boolean } = {}) {
   const container = document.createElement("div");
   document.body.appendChild(container);
   const root = createRoot(container);
@@ -215,7 +238,13 @@ function mountTarget({
     return createElement(
       "div",
       { "data-testid": "zone", ...drop.dropProps },
-      createElement("span", null, "Drop here"),
+      createElement(
+        "span",
+        childTakesDrops
+          ? { onDrop: (event: ReactDragEvent) => event.preventDefault() }
+          : null,
+        "Drop here",
+      ),
     );
   }
 
@@ -385,6 +414,41 @@ describe("useFileDrop", () => {
     target.unmount();
   });
 
+  // A picker such as FileInput inside the zone reads its own drops.
+  test("a drop a child took itself is left to it", async () => {
+    const target = mountTarget({ childTakesDrops: true });
+    const files = source([new File(["a"], "a.txt")]);
+    target.fire(target.child, dragEvent("dragenter", files));
+    expect(target.over).toBe(true);
+    const drop = target.fire(target.child, dragEvent("drop", files));
+    expect(drop.defaultPrevented).toBe(true);
+    expect(target.over).toBe(false);
+    await settle();
+    expect(target.received).toEqual([]);
+    target.unmount();
+  });
+
+  test("a drop still being read when the target is disabled is dropped", async () => {
+    const target = mountTarget();
+    const folder = heldFolder("photos", [fileEntry("a.jpg")]);
+    target.fire(target.zone, dragEvent("drop", source([folder.entry])));
+    target.disable();
+    folder.release();
+    await settle();
+    expect(target.received).toEqual([]);
+    target.unmount();
+  });
+
+  test("a drop still being read when the target unmounts is dropped", async () => {
+    const target = mountTarget();
+    const folder = heldFolder("photos", [fileEntry("a.jpg")]);
+    target.fire(target.zone, dragEvent("drop", source([folder.entry])));
+    target.unmount();
+    folder.release();
+    await settle();
+    expect(target.received).toEqual([]);
+  });
+
   test("a drag without files is left alone", async () => {
     const target = mountTarget();
     const text = source([], ["text/plain"]);
diff --git a/src/hooks/use-file-drop.ts b/src/hooks/use-file-drop.ts
index d39d30c9..a252d270 100644
--- a/src/hooks/use-file-drop.ts
+++ b/src/hooks/use-file-drop.ts
@@ -1,4 +1,4 @@
-import { useEffect, useRef, useState } from "react";
+import { useEffect, useLayoutEffect, useRef, useState } from "react";
 import type { DragEvent as ReactDragEvent } from "react";
 
 /**
@@ -230,7 +230,10 @@ export type UseFileDropOptions = ReadDroppedFilesOptions & {
    * what it held. A drop of only empty folders calls it with no files.
    */
   readonly onFiles: (files: readonly File[], details: FileDropDetails) => void;
-  /** While true, drags are ignored and the browser's default stands. */
+  /**
+   * While true, drags are ignored and the browser's default stands. A drop
+   * still being read when it turns true is dropped, errors and all.
+   */
   readonly disabled?: boolean;
   /**
    * Called when a drop could not be read in full: a folder that could not
@@ -262,7 +265,10 @@ function report(error: unknown) {
 
 /**
  * Makes an element a target for dropped files and folders. Only drags that
- * carry files are taken; text and links dragged over it behave as usual.
+ * carry files are taken; text and links dragged over it behave as usual. A
+ * drop that a child handles itself (calls `preventDefault`), as `FileInput`
+ * does, is left to the child. A drop still being read when the target
+ * unmounts is dropped.
  *
  * `over` is true while files are held over the target, including over its
  * children. It turns false when the drag leaves the target, is dropped, or
@@ -278,8 +284,18 @@ export function useFileDrop<T extends Element = HTMLElement>({
   onError,
 }: UseFileDropOptions): UseFileDropResult<T> {
   const [over, setOver] = useState(false);
-  const latest = useRef({ onFiles, onError, maxFolderEntries });
-  latest.current = { onFiles, onError, maxFolderEntries };
+  // The latest options, for a drop still being read under an earlier render.
+  const latest = useRef({ onFiles, onError, maxFolderEntries, disabled });
+  useLayoutEffect(() => {
+    latest.current = { onFiles, onError, maxFolderEntries, disabled };
+  });
+  const mounted = useRef(false);
+  useEffect(() => {
+    mounted.current = true;
+    return () => {
+      mounted.current = false;
+    };
+  }, []);
   // Counted rather than read from `relatedTarget`, which WebKit leaves null:
   // moving between two children enters one before leaving the other, so the
   // count only reaches zero once the drag has left the target.
@@ -343,22 +359,29 @@ export function useFileDrop<T extends Element = HTMLElement>({
       },
       onDrop: (event) => {
         if (!takes(event)) return;
-        event.preventDefault();
         depth.current = 0;
         setOver(false);
+        // A child that takes its own drops, such as `FileInput`, took it.
+        if (event.isDefaultPrevented()) return;
+        event.preventDefault();
         const options = latest.current.maxFolderEntries;
+        // Disabled or unmounted while the drop was being read.
+        const stale = () => latest.current.disabled || !mounted.current;
         readDroppedFiles(
           event.dataTransfer,
           options === undefined ? {} : { maxFolderEntries: options },
         ).then(
           ({ files, ...details }) => {
+            if (stale()) return;
             const { onFiles: deliver, onError: fail } = latest.current;
             for (const error of details.errors) (fail ?? report)(error);
             if (files.length > 0 || details.folders.length > 0) {
               deliver(files, details);
             }
           },
-          (error: unknown) => (latest.current.onError ?? report)(error),
+          (error: unknown) => {
+            if (!stale()) (latest.current.onError ?? report)(error);
+          },
         );
       },
     },
diff --git a/src/ui/attachment-drop-zone.tsx b/src/ui/attachment-drop-zone.tsx
index a4fe015d..6ef8e8b0 100644
--- a/src/ui/attachment-drop-zone.tsx
+++ b/src/ui/attachment-drop-zone.tsx
@@ -30,8 +30,11 @@ export type AttachmentDropZoneProps = Omit<
  * open the file in place of the page.
  *
  * Dropping needs a pointer, so put a file picker (such as `FileInput`)
- * inside it for keyboard and touch. The zone is a plain `div`: give it
- * `role="region"` and an `aria-label` when it should be a landmark.
+ * inside it for keyboard and touch. A child that takes its own drops keeps
+ * them: a drop right on `FileInput` reaches only the picker's `onFiles`,
+ * which reads loose files and does not walk folders. The zone is a plain
+ * `div`: give it `role="region"` and an `aria-label` when it should be a
+ * landmark.
  */
 export function AttachmentDropZone({
   onFiles,

From e21e1f849d53de7d023654b130098156a876875a Mon Sep 17 00:00:00 2001
From: 0xPratik <sariapratik@gmail.com>
Date: Wed, 28 Oct 2026 19:38:29 +0545
Subject: [PATCH 4/8] fix(attachments): walk a folder dropped on the picker
 inside the zone

The drop zone left any drop a child had already handled to that child,
and FileInput handles every drop. A folder dropped on the picker inside
the zone therefore reached only the picker, which passed on the single
unreadable entry the browser lists for a folder, instead of the files
inside it.

useFileDrop now reads drops in the capture phase, before any child
sees them, and marks them taken. FileInput leaves a drop that a target
around it already took, so every drop inside the zone, the picker
included, is walked and reaches the zone's onFiles once.
---
 e2e/attachments.spec.ts         | 140 ++++++++++++++++++--------------
 src/hooks/use-file-drop.test.ts |  44 ++++++----
 src/hooks/use-file-drop.ts      |  18 ++--
 src/ui/attachment-drop-zone.tsx |  11 +--
 src/ui/file-input.tsx           |   8 +-
 5 files changed, 125 insertions(+), 96 deletions(-)

diff --git a/e2e/attachments.spec.ts b/e2e/attachments.spec.ts
index 59ba6f97..c9de2036 100644
--- a/e2e/attachments.spec.ts
+++ b/e2e/attachments.spec.ts
@@ -194,73 +194,87 @@ test("past the limit, 100 of 120 files join and the rest are refused", async ({
 // A browser only builds file-system entries for a real drag from the
 // desktop, which Playwright cannot make. The drop's items are stubbed to
 // hand back entries of the same shape, so this covers the zone's walk of
-// them, not the browser's side.
-test("a dropped folder is walked to the files inside it", async ({ page }) => {
-  await page.goto("/attachments");
-  await page.getByTestId("zone").evaluate((zone) => {
-    type Entry = {
-      name: string;
-      isFile: boolean;
-      isDirectory: boolean;
-      file?: (success: (file: File) => void) => void;
-      createReader?: () => {
-        readEntries: (success: (entries: Entry[]) => void) => void;
-      };
-    };
-    const file = (name: string): Entry => ({
-      name,
-      isFile: true,
-      isDirectory: false,
-      file: (success) =>
-        success(new File([name], name, { type: "text/plain" })),
-    });
-    const folder = (name: string, entries: Entry[]): Entry => ({
-      name,
-      isFile: false,
-      isDirectory: true,
-      createReader: () => {
-        let read = false;
-        return {
-          readEntries: (success) => {
-            success(read ? [] : entries);
-            read = true;
-          },
+// them, not the browser's side. On the picker the zone has to read the drop
+// first, or the picker takes the folder as one unreadable file.
+for (const [where, target] of [
+  ["the zone", "[data-testid=zone]"],
+  ["the picker inside it", "[data-testid=zone] label"],
+] as const) {
+  test(`a folder dropped on ${where} is walked to the files inside it`, async ({
+    page,
+  }) => {
+    await page.goto("/attachments");
+    await page.locator(target).evaluate((element) => {
+      type Entry = {
+        name: string;
+        isFile: boolean;
+        isDirectory: boolean;
+        file?: (success: (file: File) => void) => void;
+        createReader?: () => {
+          readEntries: (success: (entries: Entry[]) => void) => void;
         };
-      },
+      };
+      const file = (name: string): Entry => ({
+        name,
+        isFile: true,
+        isDirectory: false,
+        file: (success) =>
+          success(new File([name], name, { type: "text/plain" })),
+      });
+      const folder = (name: string, entries: Entry[]): Entry => ({
+        name,
+        isFile: false,
+        isDirectory: true,
+        createReader: () => {
+          let read = false;
+          return {
+            readEntries: (success) => {
+              success(read ? [] : entries);
+              read = true;
+            },
+          };
+        },
+      });
+      const project = folder("project", [
+        file("README.md"),
+        file(".DS_Store"),
+        folder("src", [file("index.ts"), file("util.ts")]),
+        folder("test", [file("index.ts")]),
+      ]);
+      const items = [
+        {
+          kind: "file",
+          getAsFile: () => null,
+          webkitGetAsEntry: () => project,
+        },
+      ];
+      // A browser lists the folder itself among the files.
+      const files = [new File([], "project")];
+      const data = { types: ["Files"], items, files, dropEffect: "none" };
+      for (const type of ["dragenter", "dragover", "drop"]) {
+        const event = new DragEvent(type, { bubbles: true, cancelable: true });
+        Object.defineProperty(event, "dataTransfer", { value: data });
+        element.dispatchEvent(event);
+      }
     });
-    const project = folder("project", [
-      file("README.md"),
-      file(".DS_Store"),
-      folder("src", [file("index.ts"), file("util.ts")]),
-      folder("test", [file("index.ts")]),
-    ]);
-    const items = [
-      { kind: "file", getAsFile: () => null, webkitGetAsEntry: () => project },
-    ];
-    const data = { types: ["Files"], items, files: [], dropEffect: "none" };
-    for (const type of ["dragenter", "dragover", "drop"]) {
-      const event = new DragEvent(type, { bubbles: true, cancelable: true });
-      Object.defineProperty(event, "dataTransfer", { value: data });
-      zone.dispatchEvent(event);
+
+    await expect(count(page)).toHaveText("4");
+    await expect(page.getByRole("status", { name: "Folders" })).toHaveText(
+      "project",
+    );
+    const stack = page.getByRole("list", { name: "4 attachments" });
+    for (const name of [
+      "project/README.md",
+      "project/src/index.ts",
+      "project/src/util.ts",
+      "project/test/index.ts",
+    ]) {
+      await expect(
+        stack.getByRole("button", { name: `Remove ${name}` }),
+      ).toHaveCount(1);
     }
   });
-
-  await expect(count(page)).toHaveText("4");
-  await expect(page.getByRole("status", { name: "Folders" })).toHaveText(
-    "project",
-  );
-  const stack = page.getByRole("list", { name: "4 attachments" });
-  for (const name of [
-    "project/README.md",
-    "project/src/index.ts",
-    "project/src/util.ts",
-    "project/test/index.ts",
-  ]) {
-    await expect(
-      stack.getByRole("button", { name: `Remove ${name}` }),
-    ).toHaveCount(1);
-  }
-});
+}
 
 test("a drop on the picker inside the zone is taken once", async ({ page }) => {
   await page.goto("/attachments");
diff --git a/src/hooks/use-file-drop.test.ts b/src/hooks/use-file-drop.test.ts
index 6564931a..2601abb9 100644
--- a/src/hooks/use-file-drop.test.ts
+++ b/src/hooks/use-file-drop.test.ts
@@ -1,8 +1,9 @@
 import { describe, expect, test } from "bun:test";
 import { act, createElement, useState } from "react";
-import type { DragEvent as ReactDragEvent } from "react";
 import { createRoot } from "react-dom/client";
 
+import { FileInput } from "../ui/file-input.js";
+
 import {
   readDroppedFiles,
   useFileDrop,
@@ -217,12 +218,13 @@ type Received = { files: readonly File[]; details: FileDropDetails };
 function mountTarget({
   guard = true,
   disabled: initiallyDisabled = false,
-  childTakesDrops = false,
-}: { guard?: boolean; disabled?: boolean; childTakesDrops?: boolean } = {}) {
+  picker = false,
+}: { guard?: boolean; disabled?: boolean; picker?: boolean } = {}) {
   const container = document.createElement("div");
   document.body.appendChild(container);
   const root = createRoot(container);
   const received: Received[] = [];
+  const picked: File[][] = [];
   let over = false;
   let setDisabled: (disabled: boolean) => void = () => {};
 
@@ -238,24 +240,23 @@ function mountTarget({
     return createElement(
       "div",
       { "data-testid": "zone", ...drop.dropProps },
-      createElement(
-        "span",
-        childTakesDrops
-          ? { onDrop: (event: ReactDragEvent) => event.preventDefault() }
-          : null,
-        "Drop here",
-      ),
+      picker
+        ? createElement(FileInput, {
+            onFiles: (files) => picked.push(Array.from(files)),
+          })
+        : createElement("span", null, "Drop here"),
     );
   }
 
   act(() => root.render(createElement(Target)));
   const zone = container.querySelector("[data-testid=zone]");
-  const child = container.querySelector("span");
+  const child = container.querySelector("[data-testid=zone] > *");
   if (zone === null || child === null) throw new Error("no zone");
   return {
     zone,
     child,
     received,
+    picked,
     get over() {
       return over;
     },
@@ -414,17 +415,24 @@ describe("useFileDrop", () => {
     target.unmount();
   });
 
-  // A picker such as FileInput inside the zone reads its own drops.
-  test("a drop a child took itself is left to it", async () => {
-    const target = mountTarget({ childTakesDrops: true });
-    const files = source([new File(["a"], "a.txt")]);
-    target.fire(target.child, dragEvent("dragenter", files));
+  // The picker would take the folder as one unreadable file of its name.
+  test("a folder dropped on a picker inside the target is walked", async () => {
+    const target = mountTarget({ picker: true });
+    const dropped = {
+      ...source([folderEntry("photos", [fileEntry("a.jpg")])]),
+      // As a browser lists a dropped folder.
+      files: [new File([], "photos")],
+    };
+    target.fire(target.child, dragEvent("dragenter", dropped));
     expect(target.over).toBe(true);
-    const drop = target.fire(target.child, dragEvent("drop", files));
+    const drop = target.fire(target.child, dragEvent("drop", dropped));
     expect(drop.defaultPrevented).toBe(true);
     expect(target.over).toBe(false);
     await settle();
-    expect(target.received).toEqual([]);
+    expect(target.picked).toEqual([]);
+    expect(
+      target.received.map(({ files }) => files.map((file) => file.name)),
+    ).toEqual([["photos/a.jpg"]]);
     target.unmount();
   });
 
diff --git a/src/hooks/use-file-drop.ts b/src/hooks/use-file-drop.ts
index a252d270..a9d14de5 100644
--- a/src/hooks/use-file-drop.ts
+++ b/src/hooks/use-file-drop.ts
@@ -247,7 +247,8 @@ export type FileDropTargetProps<T extends Element> = {
   readonly onDragEnter: (event: ReactDragEvent<T>) => void;
   readonly onDragOver: (event: ReactDragEvent<T>) => void;
   readonly onDragLeave: (event: ReactDragEvent<T>) => void;
-  readonly onDrop: (event: ReactDragEvent<T>) => void;
+  /** In the capture phase, so the target reads a drop before its children. */
+  readonly onDropCapture: (event: ReactDragEvent<T>) => void;
 };
 
 export type UseFileDropResult<T extends Element> = {
@@ -265,10 +266,13 @@ function report(error: unknown) {
 
 /**
  * Makes an element a target for dropped files and folders. Only drags that
- * carry files are taken; text and links dragged over it behave as usual. A
- * drop that a child handles itself (calls `preventDefault`), as `FileInput`
- * does, is left to the child. A drop still being read when the target
- * unmounts is dropped.
+ * carry files are taken; text and links dragged over it behave as usual.
+ * Every file drop inside the target is the target's: it reads the drop in
+ * the capture phase, before any child, and marks it taken with
+ * `preventDefault`, so a folder dropped on a child is walked like one
+ * dropped anywhere else. A child that takes drops of its own skips one
+ * already taken, as `FileInput` does. A drop still being read when the
+ * target unmounts is dropped.
  *
  * `over` is true while files are held over the target, including over its
  * children. It turns false when the drag leaves the target, is dropped, or
@@ -357,11 +361,11 @@ export function useFileDrop<T extends Element = HTMLElement>({
         depth.current = Math.max(0, depth.current - 1);
         if (depth.current === 0) setOver(false);
       },
-      onDrop: (event) => {
+      onDropCapture: (event) => {
         if (!takes(event)) return;
         depth.current = 0;
         setOver(false);
-        // A child that takes its own drops, such as `FileInput`, took it.
+        // A target around this one took it first.
         if (event.isDefaultPrevented()) return;
         event.preventDefault();
         const options = latest.current.maxFolderEntries;
diff --git a/src/ui/attachment-drop-zone.tsx b/src/ui/attachment-drop-zone.tsx
index 6ef8e8b0..f7b106f7 100644
--- a/src/ui/attachment-drop-zone.tsx
+++ b/src/ui/attachment-drop-zone.tsx
@@ -17,6 +17,7 @@ export type AttachmentDropZoneProps = Omit<
   | "onDragOver"
   | "onDragLeave"
   | "onDrop"
+  | "onDropCapture"
 > &
   UseFileDropOptions & {
     /** Shown over the zone while files are held over it. */
@@ -30,11 +31,11 @@ export type AttachmentDropZoneProps = Omit<
  * open the file in place of the page.
  *
  * Dropping needs a pointer, so put a file picker (such as `FileInput`)
- * inside it for keyboard and touch. A child that takes its own drops keeps
- * them: a drop right on `FileInput` reaches only the picker's `onFiles`,
- * which reads loose files and does not walk folders. The zone is a plain
- * `div`: give it `role="region"` and an `aria-label` when it should be a
- * landmark.
+ * inside it for keyboard and touch. The zone reads every drop inside it
+ * before its children do, so files and folders dropped on the picker reach
+ * the zone's `onFiles`, folders walked, and not the picker's. The zone is a
+ * plain `div`: give it `role="region"` and an `aria-label` when it should be
+ * a landmark.
  */
 export function AttachmentDropZone({
   onFiles,
diff --git a/src/ui/file-input.tsx b/src/ui/file-input.tsx
index 034fbccd..45eb34a0 100644
--- a/src/ui/file-input.tsx
+++ b/src/ui/file-input.tsx
@@ -27,7 +27,9 @@ export type FileInputProps = Omit<
  *
  * Drag-and-drop is added on top rather than replacing that. A drop-only zone
  * excludes anyone not using a mouse, and every real upload control needs the
- * picker anyway.
+ * picker anyway. A drop that a drop target around the picker has already
+ * taken (called `preventDefault` on), as `AttachmentDropZone` does, is left
+ * to that target.
  *
  * The input is cleared after each selection so choosing the same file twice
  * still fires — the browser's change event will not repeat for an identical
@@ -53,9 +55,9 @@ export function FileInput({
       }}
       onDragLeave={() => setDragging(false)}
       onDrop={(event) => {
-        if (disabled === true) return;
-        event.preventDefault();
         setDragging(false);
+        if (disabled === true || event.isDefaultPrevented()) return;
+        event.preventDefault();
         if (event.dataTransfer.files.length > 0)
           onFiles(event.dataTransfer.files);
       }}

From 0b1e937e54fbe67022ac2c5bbe64c02fc03e6312 Mon Sep 17 00:00:00 2001
From: 0xPratik <sariapratik@gmail.com>
Date: Wed, 28 Oct 2026 19:39:29 +0545
Subject: [PATCH 5/8] fix(attachments): show a picture with no url from its
 file

Attachment rebuilt a picture from its file only after the url failed
to load, and a missing url never fails. useAttachments makes no
preview url once it has unmounted or been hidden for longer than a
tick, so an image added in that window showed as its type for as long
as it was held.

An image or video with no url is now shown from a url made from its
file, revoked on unmount or hide like a rebuilt one, and falls back to
its type if that fails. Other kinds get no url made.
---
 src/hooks/use-attachments.ts |  8 ++++----
 src/ui/attachments.test.tsx  | 33 ++++++++++++++++++++++++++++++
 src/ui/attachments.tsx       | 39 ++++++++++++++++++++++--------------
 3 files changed, 61 insertions(+), 19 deletions(-)

diff --git a/src/hooks/use-attachments.ts b/src/hooks/use-attachments.ts
index dccc1615..d9ef4754 100644
--- a/src/hooks/use-attachments.ts
+++ b/src/hooks/use-attachments.ts
@@ -67,10 +67,10 @@ function nextAttachmentId(): string {
  * Every URL the hook makes is revoked at the first commit whose list does
  * not hold its attachment: once the host removes it, however it does, or
  * right away if the host never appended it. The rest go when the hook
- * unmounts, and an `add` after that makes no URL. Only
- * URLs the hook made are revoked; the host's own are left alone. To keep an
- * attachment on screen after it leaves the list (sending moves it into a
- * message), `release` it first.
+ * unmounts, and an `add` after that makes no URL; `Attachment` shows such an
+ * item's picture from its `file`. Only URLs the hook made are revoked; the
+ * host's own are left alone. To keep an attachment on screen after it leaves
+ * the list (sending moves it into a message), `release` it first.
  *
  * The unmount revoke waits a microtask and is called off if the hook mounts
  * again, which is what StrictMode's simulated remount does within one
diff --git a/src/ui/attachments.test.tsx b/src/ui/attachments.test.tsx
index db3a6bd2..f3f3bfad 100644
--- a/src/ui/attachments.test.tsx
+++ b/src/ui/attachments.test.tsx
@@ -277,6 +277,39 @@ describe("a preview held across a hidden Activity", () => {
     expect([...live]).toEqual([]);
   });
 
+  // Such as one `useAttachments` accepted after its host was hidden.
+  test("with no URL, is shown from its file", () => {
+    const shot = new File(["x"], "shot.png", { type: "image/png" });
+    const notes = new File(["x"], "notes.txt", { type: "text/plain" });
+    const { container, unmount } = mount(
+      <Attachments variant="tiles">
+        <Attachment
+          data={{ name: "shot.png", mediaType: "image/png", file: shot }}
+        >
+          <AttachmentPreview />
+        </Attachment>
+        <Attachment
+          data={{ name: "notes.txt", mediaType: "text/plain", file: notes }}
+        >
+          <AttachmentPreview />
+        </Attachment>
+      </Attachments>,
+    );
+    const picture = () => container.querySelector("img");
+    const made = picture()?.getAttribute("src") ?? "";
+    expect(live.has(made)).toBe(true);
+    // Only the picture needs a URL.
+    expect([...live]).toEqual([made]);
+
+    act(() => {
+      picture()?.dispatchEvent(new Event("error"));
+    });
+    expect(picture()).toBeNull();
+    expect(container.textContent).toContain("PNG");
+    unmount();
+    expect([...live]).toEqual([]);
+  });
+
   test("falls back to the type when the rebuilt URL fails too", () => {
     const shot = new File(["x"], "shot.png", { type: "image/png" });
     const { container, unmount } = mount(
diff --git a/src/ui/attachments.tsx b/src/ui/attachments.tsx
index f49a8ebd..3634236f 100644
--- a/src/ui/attachments.tsx
+++ b/src/ui/attachments.tsx
@@ -35,9 +35,9 @@ export type AttachmentData = {
   /** Where to show or open it from. */
   readonly url?: string;
   /**
-   * The local file, when there is one. A picture whose `url` no longer
-   * loads, such as a preview `useAttachments` revoked while it was hidden,
-   * is rebuilt from it.
+   * The local file, when there is one. A picture with no `url`, or whose
+   * `url` no longer loads (such as a preview `useAttachments` revoked while
+   * it was hidden), is shown from it.
    */
   readonly file?: File;
 };
@@ -307,10 +307,10 @@ export type AttachmentProps = React.ComponentProps<"li"> & {
 };
 
 /**
- * Where a picture loads from: `url`, or, once that fails to load and the
- * file is at hand, a URL made from the file. A URL made here is revoked
- * when the attachment unmounts or is hidden, and made again when it shows.
- * A rebuilt URL that fails too leaves no picture.
+ * Where a picture loads from: `url`, or, when there is none or it fails to
+ * load and the file is at hand, a URL made from the file. A URL made here
+ * is revoked when the attachment unmounts or is hidden, and made again when
+ * it shows. A URL made here that fails too leaves no picture.
  */
 function usePictureSource(
   url: string | undefined,
@@ -321,8 +321,11 @@ function usePictureSource(
     readonly rebuilt: boolean;
   } | null>(null);
   const failedHere = failed !== null && failed.url === url;
+  const usesUrl = url !== undefined && !failedHere;
   const source =
-    failedHere && !failed.rebuilt && file !== undefined ? file : undefined;
+    !usesUrl && !(failedHere && failed.rebuilt) && file !== undefined
+      ? file
+      : undefined;
   const [rebuilt, setRebuilt] = useState<{
     readonly file: File;
     readonly url: string;
@@ -336,14 +339,14 @@ function usePictureSource(
     return () => URL.revokeObjectURL(made);
   }, [source]);
 
-  const src = !failedHere
+  const src = usesUrl
     ? url
     : source !== undefined && rebuilt?.file === source
       ? rebuilt.url
       : undefined;
   const setBroken = useCallback(
-    () => setFailed({ url, rebuilt: failedHere }),
-    [url, failedHere],
+    () => setFailed({ url, rebuilt: !usesUrl }),
+    [url, usesUrl],
   );
   return { src, setBroken };
 }
@@ -359,8 +362,13 @@ export function Attachment({
   const { variant, expanded, focusAfterRemove } =
     useAttachmentsContext("Attachment");
   const kind = mediaKindOf(data.name, data.mediaType);
-  const { src, setBroken } = usePictureSource(data.url, data.file);
-  const pictured = (kind === "image" || kind === "video") && src !== undefined;
+  const picturable = kind === "image" || kind === "video";
+  // Only a picture is shown from its file; nothing else needs a URL made.
+  const { src, setBroken } = usePictureSource(
+    data.url,
+    picturable ? data.file : undefined,
+  );
+  const pictured = picturable && src !== undefined;
   const elementRef = useRef<HTMLLIElement | null>(null);
 
   const setElement = useCallback(
@@ -447,8 +455,9 @@ export type AttachmentPreviewProps = Omit<
 
 /**
  * The file at a glance: the picture, a video's first frame, or for anything
- * else its type. A picture that fails to load is rebuilt from `data.file`
- * when there is one, and otherwise falls back to the type.
+ * else its type. A picture with no `data.url`, or one that fails to load, is
+ * shown from `data.file` when there is one, and otherwise falls back to the
+ * type.
  *
  * Host props reach the element either way; its own role, name and click
  * stay its own. Name it with `label`.

From 0eb9365e67177e30baab8755ab2870fb17c339d2 Mon Sep 17 00:00:00 2001
From: 0xPratik <sariapratik@gmail.com>
Date: Wed, 28 Oct 2026 19:40:28 +0545
Subject: [PATCH 6/8] fix(attachments): check adds against the committed list
 only

useAttachments stored its list and limits for add during render, so a
render that never committed, such as a transition that suspends, left
its list behind. An add from an event in that window checked limits
and duplicates against a list that was not on screen.

The hook now stores them in a layout effect, so add always sees the
committed list plus whatever it accepted since.
---
 src/hooks/use-attachments.test.ts | 58 ++++++++++++++++++++++++++++++-
 src/hooks/use-attachments.ts      |  8 +++--
 2 files changed, 63 insertions(+), 3 deletions(-)

diff --git a/src/hooks/use-attachments.test.ts b/src/hooks/use-attachments.test.ts
index 38a0549c..4cc2a570 100644
--- a/src/hooks/use-attachments.test.ts
+++ b/src/hooks/use-attachments.test.ts
@@ -1,5 +1,14 @@
 import { afterEach, beforeEach, describe, expect, test } from "bun:test";
-import { Activity, StrictMode, act, createElement, useState } from "react";
+import {
+  Activity,
+  StrictMode,
+  Suspense,
+  act,
+  createElement,
+  startTransition,
+  use,
+  useState,
+} from "react";
 import { createRoot } from "react-dom/client";
 
 import type { PartFile } from "../lib/chat-parts.js";
@@ -211,6 +220,53 @@ describe("useAttachments", () => {
     host.unmount();
   });
 
+  // A transition that suspends renders the new list but keeps the old one
+  // on screen until it resolves, here never.
+  test("a list rendered but not yet committed is not checked against", async () => {
+    const container = document.createElement("div");
+    document.body.appendChild(container);
+    const root = createRoot(container);
+    const never = new Promise<never>(() => {});
+    let hook: UseAttachmentsResult | undefined;
+    let show: (list: readonly AttachmentItem[]) => void = () => {};
+
+    function Stall(): null {
+      use(never);
+      return null;
+    }
+
+    function Host() {
+      const [shown, setShown] = useState<{
+        readonly list: readonly AttachmentItem[];
+        readonly stall: boolean;
+      }>({ list: [], stall: false });
+      show = (list) => setShown({ list, stall: true });
+      hook = useAttachments({ attachments: shown.list, maxFiles: 1 });
+      return shown.stall ? createElement(Stall) : null;
+    }
+
+    act(() => {
+      root.render(
+        createElement(Suspense, { fallback: null }, createElement(Host)),
+      );
+    });
+    const held: AttachmentItem = {
+      id: "held-1",
+      name: "a.txt",
+      mediaType: "text/plain",
+      size: 4,
+    };
+    await act(async () => {
+      startTransition(() => show([held]));
+    });
+
+    const { accepted, rejected } = hook?.add([file("a.txt")]) ?? {};
+    expect(rejected).toEqual([]);
+    expect(accepted?.map((item) => item.name)).toEqual(["a.txt"]);
+    act(() => root.unmount());
+    container.remove();
+  });
+
   test("removing an attachment revokes its preview URL and only its", () => {
     const host = mountHost();
     const [first, second] = host.drop([file("a.txt"), file("b.txt")]).accepted;
diff --git a/src/hooks/use-attachments.ts b/src/hooks/use-attachments.ts
index d9ef4754..ab6adee3 100644
--- a/src/hooks/use-attachments.ts
+++ b/src/hooks/use-attachments.ts
@@ -1,4 +1,4 @@
-import { useCallback, useEffect, useRef } from "react";
+import { useCallback, useEffect, useLayoutEffect, useRef } from "react";
 
 import {
   checkAttachments,
@@ -89,8 +89,12 @@ export function useAttachments({
 }: UseAttachmentsOptions): UseAttachmentsResult {
   const urls = useRef(new Map<string, string>());
   const pending = useRef<AttachmentItem[]>([]);
+  // The committed list and limits, for `add`: a render that never commits,
+  // such as a transition that suspends, must not leave its list here.
   const latest = useRef({ attachments, maxFiles, maxFileBytes });
-  latest.current = { attachments, maxFiles, maxFileBytes };
+  useLayoutEffect(() => {
+    latest.current = { attachments, maxFiles, maxFileBytes };
+  });
   // True until the hook unmounts, so an `add` before its effects run still
   // makes a URL.
   const mounted = useRef(true);

From c84bffeaffe47692d490c95d99cdb8cd7d6e0585 Mon Sep 17 00:00:00 2001
From: 0xPratik <sariapratik@gmail.com>
Date: Wed, 28 Oct 2026 19:40:34 +0545
Subject: [PATCH 7/8] test(attachments): put the effect replay comment above
 its test

The comment on why the StrictMode replay comes after the previews are
made sat above the add-after-unmount test instead of the replay test
it explains.
---
 src/hooks/use-attachments.test.ts | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/src/hooks/use-attachments.test.ts b/src/hooks/use-attachments.test.ts
index 4cc2a570..15a9a47d 100644
--- a/src/hooks/use-attachments.test.ts
+++ b/src/hooks/use-attachments.test.ts
@@ -313,9 +313,6 @@ describe("useAttachments", () => {
     expect([...revoked].sort()).toEqual([...created].sort());
   });
 
-  // StrictMode replays effects only at mount, before any URL is made, so
-  // the replay here comes after: the effects are torn down and set up again
-  // while the previews are on screen.
   // A drop still being read, or any other late caller.
   test("an add after unmounting makes no preview URL", async () => {
     const host = mountHost();
@@ -327,6 +324,9 @@ describe("useAttachments", () => {
     expect(created).toEqual([]);
   });
 
+  // StrictMode replays effects only at mount, before any URL is made, so
+  // the replay here comes after: the effects are torn down and set up again
+  // while the previews are on screen.
   test("an effect replay while previews are held revokes nothing", async () => {
     const host = mountHost({ strict: true });
     host.drop([file("a.txt"), file("b.txt")]);

From 414cc0e983c5694e7a16569d3a6a00d02790c136 Mon Sep 17 00:00:00 2001
From: 0xPratik <sariapratik@gmail.com>
Date: Wed, 28 Oct 2026 19:41:50 +0545
Subject: [PATCH 8/8] fix(attachments): forward refs to the list, item and
 preview on React 18

Attachments, Attachment and AttachmentPreview read ref from their
props, which only React 19 passes to a function component. On React
18, which the peer range still covers, a host's ref never reached the
list, the item or the preview.

The three are now wrapped in forwardRef, so the ref reaches the
element on both versions. Their props types are unchanged.
---
 src/ui/attachments.test.tsx |  24 +++
 src/ui/attachments.tsx      | 292 ++++++++++++++++++------------------
 2 files changed, 169 insertions(+), 147 deletions(-)

diff --git a/src/ui/attachments.test.tsx b/src/ui/attachments.test.tsx
index f3f3bfad..3a06d546 100644
--- a/src/ui/attachments.test.tsx
+++ b/src/ui/attachments.test.tsx
@@ -134,6 +134,30 @@ describe("Attachments", () => {
     unmount();
   });
 
+  // React 18 hands a function component no `ref` unless it is wrapped in
+  // `forwardRef`; React 19, which these tests run on, hands it either way.
+  test("the list, an attachment and its preview take refs on React 18 too", () => {
+    for (const part of [Attachments, Attachment, AttachmentPreview]) {
+      expect(part.$$typeof).toBe(Symbol.for("react.forward_ref"));
+    }
+    const list = { current: null as HTMLUListElement | null };
+    const item = { current: null as HTMLLIElement | null };
+    const preview = { current: null as HTMLElement | null };
+    const { container, unmount } = mount(
+      <Attachments ref={list}>
+        <Attachment ref={item} data={NOTES}>
+          <AttachmentPreview ref={preview} />
+        </Attachment>
+      </Attachments>,
+    );
+    expect(list.current).toBe(container.querySelector("ul"));
+    expect(item.current).toBe(container.querySelector("li"));
+    expect(preview.current).toBe(
+      container.querySelector("[data-slot=attachment-preview]"),
+    );
+    unmount();
+  });
+
   test("an uncontrolled list folds until More expands it", () => {
     const files: readonly AttachmentData[] = ["a.txt", "b.txt", "c.txt"].map(
       (name) => ({ name, mediaType: "text/plain" }),
diff --git a/src/ui/attachments.tsx b/src/ui/attachments.tsx
index 3634236f..3f37e905 100644
--- a/src/ui/attachments.tsx
+++ b/src/ui/attachments.tsx
@@ -11,6 +11,7 @@ import {
 } from "lucide-react";
 import {
   createContext,
+  forwardRef,
   useCallback,
   useContext,
   useLayoutEffect,
@@ -197,89 +198,93 @@ export type AttachmentsProps = Omit<React.ComponentProps<"ul">, "children"> & {
  * the list. Controls of the host's own that go away as they are used ("Show
  * less", "Remove all") move focus themselves.
  */
-export function Attachments({
-  variant = "tiles",
-  expanded: expandedProp,
-  defaultExpanded = false,
-  onExpandedChange,
-  total,
-  returnFocusTo,
-  className,
-  ref,
-  children,
-  ...props
-}: AttachmentsProps) {
-  const [expanded, setExpanded] = useControllableState({
-    value: expandedProp,
-    defaultValue: defaultExpanded,
-    onChange: onExpandedChange,
-    name: "Attachments",
-  });
-  const focusAfterRemove = useRef<HTMLElement | null>(null);
-  const focusAfterExpand = useRef<number | null>(null);
-  const listRef = useRef<HTMLUListElement | null>(null);
-  const setList = useCallback(
-    (element: HTMLUListElement | null) => {
-      listRef.current = element;
-      if (typeof ref === "function") ref(element);
-      else if (ref !== null && ref !== undefined) ref.current = element;
+export const Attachments = forwardRef<HTMLUListElement, AttachmentsProps>(
+  function Attachments(
+    {
+      variant = "tiles",
+      expanded: expandedProp,
+      defaultExpanded = false,
+      onExpandedChange,
+      total,
+      returnFocusTo,
+      className,
+      children,
+      ...props
     },
-    [ref],
-  );
+    ref,
+  ) {
+    const [expanded, setExpanded] = useControllableState({
+      value: expandedProp,
+      defaultValue: defaultExpanded,
+      onChange: onExpandedChange,
+      name: "Attachments",
+    });
+    const focusAfterRemove = useRef<HTMLElement | null>(null);
+    const focusAfterExpand = useRef<number | null>(null);
+    const listRef = useRef<HTMLUListElement | null>(null);
+    const setList = useCallback(
+      (element: HTMLUListElement | null) => {
+        listRef.current = element;
+        if (typeof ref === "function") ref(element);
+        else if (ref !== null && ref !== undefined) ref.current = element;
+      },
+      [ref],
+    );
 
-  // "+N" goes away as the list expands; focus moves to the first attachment
-  // it was folding, not back to the start of the page.
-  useLayoutEffect(() => {
-    const index = focusAfterExpand.current;
-    const list = listRef.current;
-    if (!expanded || index === null || list === null) return;
-    focusAfterExpand.current = null;
-    const revealed = list.children.item(index);
-    const control =
-      revealed?.querySelector<HTMLElement>("button, [tabindex='0']") ?? list;
-    control.focus();
-  }, [expanded]);
+    // "+N" goes away as the list expands; focus moves to the first attachment
+    // it was folding, not back to the start of the page.
+    useLayoutEffect(() => {
+      const index = focusAfterExpand.current;
+      const list = listRef.current;
+      if (!expanded || index === null || list === null) return;
+      focusAfterExpand.current = null;
+      const revealed = list.children.item(index);
+      const control =
+        revealed?.querySelector<HTMLElement>("button, [tabindex='0']") ?? list;
+      control.focus();
+    }, [expanded]);
 
-  return (
-    <AttachmentsContext.Provider
-      value={{
-        variant,
-        expanded,
-        setExpanded,
-        focusAfterRemove,
-        focusAfterExpand,
-        returnFocusTo,
-      }}
-    >
-      <ul
-        ref={setList}
-        data-slot="attachments"
-        data-variant={variant}
-        data-expanded={expanded ? "true" : undefined}
-        data-total={
-          variant === "stack" && total !== undefined && total > 1
-            ? total
-            : undefined
-        }
-        aria-label={
-          total === undefined
-            ? "Attachments"
-            : `${total} ${total === 1 ? "attachment" : "attachments"}`
-        }
-        tabIndex={-1}
-        className={cn(
-          variant === "stack" && expanded
-            ? "flex flex-wrap items-start gap-2"
-            : ROOT[variant],
-          className,
-        )}
-        {...props}
+    return (
+      <AttachmentsContext.Provider
+        value={{
+          variant,
+          expanded,
+          setExpanded,
+          focusAfterRemove,
+          focusAfterExpand,
+          returnFocusTo,
+        }}
       >
-        {typeof children === "function" ? children({ expanded }) : children}
-      </ul>
-    </AttachmentsContext.Provider>
-  );
-}
+        <ul
+          ref={setList}
+          data-slot="attachments"
+          data-variant={variant}
+          data-expanded={expanded ? "true" : undefined}
+          data-total={
+            variant === "stack" && total !== undefined && total > 1
+              ? total
+              : undefined
+          }
+          aria-label={
+            total === undefined
+              ? "Attachments"
+              : `${total} ${total === 1 ? "attachment" : "attachments"}`
+          }
+          tabIndex={-1}
+          className={cn(
+            variant === "stack" && expanded
+              ? "flex flex-wrap items-start gap-2"
+              : ROOT[variant],
+            className,
+          )}
+          {...props}
+        >
+          {typeof children === "function" ? children({ expanded }) : children}
+        </ul>
+      </AttachmentsContext.Provider>
+    );
+  },
+);
 
 function itemClasses(variant: AttachmentsVariant, expanded: boolean): string {
   const card =
@@ -352,69 +357,65 @@ function usePictureSource(
 }
 
 /** One file in `Attachments`; its parts read the file from here. */
-export function Attachment({
-  data,
-  className,
-  ref,
-  children,
-  ...props
-}: AttachmentProps) {
-  const { variant, expanded, focusAfterRemove } =
-    useAttachmentsContext("Attachment");
-  const kind = mediaKindOf(data.name, data.mediaType);
-  const picturable = kind === "image" || kind === "video";
-  // Only a picture is shown from its file; nothing else needs a URL made.
-  const { src, setBroken } = usePictureSource(
-    data.url,
-    picturable ? data.file : undefined,
-  );
-  const pictured = picturable && src !== undefined;
-  const elementRef = useRef<HTMLLIElement | null>(null);
-
-  const setElement = useCallback(
-    (element: HTMLLIElement | null) => {
-      elementRef.current = element;
-      if (typeof ref === "function") ref(element);
-      else if (ref !== null && ref !== undefined) ref.current = element;
-    },
-    [ref],
-  );
+export const Attachment = forwardRef<HTMLLIElement, AttachmentProps>(
+  function Attachment({ data, className, children, ...props }, ref) {
+    const { variant, expanded, focusAfterRemove } =
+      useAttachmentsContext("Attachment");
+    const kind = mediaKindOf(data.name, data.mediaType);
+    const picturable = kind === "image" || kind === "video";
+    // Only a picture is shown from its file; nothing else needs a URL made.
+    const { src, setBroken } = usePictureSource(
+      data.url,
+      picturable ? data.file : undefined,
+    );
+    const pictured = picturable && src !== undefined;
+    const elementRef = useRef<HTMLLIElement | null>(null);
+
+    const setElement = useCallback(
+      (element: HTMLLIElement | null) => {
+        elementRef.current = element;
+        if (typeof ref === "function") ref(element);
+        else if (ref !== null && ref !== undefined) ref.current = element;
+      },
+      [ref],
+    );
 
-  // A layout cleanup runs while the item is still attached, so `contains`
-  // still sees focus inside it.
-  useLayoutEffect(() => {
-    const element = elementRef.current;
-    return () => {
-      const target = focusAfterRemove.current;
-      if (
-        element === null ||
-        target === null ||
-        !element.contains(document.activeElement)
-      ) {
-        return;
-      }
-      focusAfterRemove.current = null;
-      if (target.isConnected) target.focus();
-    };
-  }, [focusAfterRemove]);
+    // A layout cleanup runs while the item is still attached, so `contains`
+    // still sees focus inside it.
+    useLayoutEffect(() => {
+      const element = elementRef.current;
+      return () => {
+        const target = focusAfterRemove.current;
+        if (
+          element === null ||
+          target === null ||
+          !element.contains(document.activeElement)
+        ) {
+          return;
+        }
+        focusAfterRemove.current = null;
+        if (target.isConnected) target.focus();
+      };
+    }, [focusAfterRemove]);
 
-  return (
-    <AttachmentContext.Provider
-      value={{ data, kind, pictured, src, setBroken }}
-    >
-      <li
-        ref={setElement}
-        data-slot="attachment"
-        data-kind={kind}
-        data-pictured={pictured ? "true" : undefined}
-        className={cn(itemClasses(variant, expanded), className)}
-        {...props}
+    return (
+      <AttachmentContext.Provider
+        value={{ data, kind, pictured, src, setBroken }}
       >
-        {children}
-      </li>
-    </AttachmentContext.Provider>
-  );
-}
+        <li
+          ref={setElement}
+          data-slot="attachment"
+          data-kind={kind}
+          data-pictured={pictured ? "true" : undefined}
+          className={cn(itemClasses(variant, expanded), className)}
+          {...props}
+        >
+          {children}
+        </li>
+      </AttachmentContext.Provider>
+    );
+  },
+);
 
 function previewClasses(
   variant: AttachmentsVariant,
@@ -462,13 +463,10 @@ export type AttachmentPreviewProps = Omit<
  * Host props reach the element either way; its own role, name and click
  * stay its own. Name it with `label`.
  */
-export function AttachmentPreview({
-  onOpen,
-  label,
-  className,
-  ref,
-  ...props
-}: AttachmentPreviewProps) {
+export const AttachmentPreview = forwardRef<
+  HTMLElement,
+  AttachmentPreviewProps
+>(function AttachmentPreview({ onOpen, label, className, ...props }, ref) {
   const { variant, expanded } = useAttachmentsContext("AttachmentPreview");
   const {
     data,
@@ -575,7 +573,7 @@ export function AttachmentPreview({
       {face}
     </button>
   );
-}
+});
 
 function infoClasses(
   variant: AttachmentsVariant,