From 9d2b7a7d7a298b56d640ef0eb8930995e7fc966a Mon Sep 17 00:00:00 2001
From: Aaron Gabriel <ag@unforced.org>
Date: Sat, 18 Apr 2026 16:02:04 -0600
Subject: [PATCH] Add attachment upload: drop, paste, picker with progress +
 defer-link on /new

Drag & drop, paste-from-clipboard, and a picker button upload files to the
vault storage endpoint, then insert the right markdown (![alt](url) for
images, [filename](url) otherwise). On /notes/:id/edit attachments link to
the note immediately; on /new they stage and link after create to avoid
orphan storage blobs on cancel. XHR backs the upload so we can show per-file
progress and cancel mid-flight. Inline images in the preview go through
VaultImage, which blob-fetches past the auth-gated storage endpoint.

Size cap 100 MB and extension allowlist (wav/mp3/m4a/ogg/webm/png/jpg/jpeg/
gif/webp) are enforced client-side before any network request. PDF + mp4
tracked upstream in parachute-vault#127. Attachment sidebar is read-only
this PR; remove button is sequenced to #8.5 after the vault DELETE endpoint
lands.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
---
 src/app/routes/NoteEditor.test.tsx      | 189 +++++++++++++++++-
 src/app/routes/NoteEditor.tsx           | 102 +++++++++-
 src/app/routes/NoteNew.test.tsx         | 255 +++++++++++++++++++++++-
 src/app/routes/NoteNew.tsx              |  98 ++++++++-
 src/components/AttachmentDropZone.tsx   |  77 +++++++
 src/components/AttachmentPicker.tsx     |  42 ++++
 src/components/AttachmentUploadList.tsx |  76 +++++++
 src/components/CodeMirrorEditor.tsx     |  57 +++++-
 src/components/MarkdownView.tsx         |   5 +
 src/components/VaultImage.tsx           |  60 ++++++
 src/components/useAttachmentUploader.ts | 148 ++++++++++++++
 src/lib/vault/client.test.ts            | 192 +++++++++++++++++-
 src/lib/vault/client.ts                 | 122 +++++++++++-
 src/lib/vault/queries.ts                |  45 ++++-
 src/lib/vault/types.ts                  |   4 +
 15 files changed, 1441 insertions(+), 31 deletions(-)
 create mode 100644 src/components/AttachmentDropZone.tsx
 create mode 100644 src/components/AttachmentPicker.tsx
 create mode 100644 src/components/AttachmentUploadList.tsx
 create mode 100644 src/components/VaultImage.tsx
 create mode 100644 src/components/useAttachmentUploader.ts

diff --git a/src/app/routes/NoteEditor.test.tsx b/src/app/routes/NoteEditor.test.tsx
index 7c749bf..71b0510 100644
--- a/src/app/routes/NoteEditor.test.tsx
+++ b/src/app/routes/NoteEditor.test.tsx
@@ -1,4 +1,5 @@
 import { NoteEditor } from "@/app/routes/NoteEditor";
+import { useToastStore } from "@/lib/toast/store";
 import { useVaultStore } from "@/lib/vault/store";
 import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
 import { act, fireEvent, render, screen, waitFor } from "@testing-library/react";
@@ -8,14 +9,102 @@ import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
 
 // Swap CodeMirror out for a plain textarea so tests can drive onChange without
 // wrangling CM6 inside jsdom.
-vi.mock("@/components/CodeMirrorEditor", () => ({
-  CodeMirrorEditor: ({
-    value,
-    onChange,
-  }: { value: string; onChange(next: string): void; onSave?(): void; onCancel?(): void }) => (
-    <textarea data-testid="cm-editor" value={value} onChange={(e) => onChange(e.target.value)} />
-  ),
-}));
+vi.mock("@/components/CodeMirrorEditor", async () => {
+  const React = await import("react");
+  return {
+    CodeMirrorEditor: React.forwardRef(function MockCodeMirrorEditor(
+      props: {
+        value: string;
+        onChange(next: string): void;
+        onSave?(): void;
+        onCancel?(): void;
+        onPasteFile?(files: File[]): boolean;
+      },
+      ref: React.Ref<{ insertAtCursor(s: string): void; focus(): void }>,
+    ) {
+      const { value, onChange, onPasteFile } = props;
+      React.useImperativeHandle(
+        ref,
+        () => ({
+          insertAtCursor(s: string) {
+            onChange(value + s);
+          },
+          focus() {},
+        }),
+        [value, onChange],
+      );
+      return (
+        <>
+          <textarea
+            data-testid="cm-editor"
+            value={value}
+            onChange={(e) => onChange(e.target.value)}
+          />
+          <button
+            type="button"
+            data-testid="cm-paste-image"
+            onClick={() => {
+              const f = new File([new Uint8Array([1, 2])], "pasted.png", { type: "image/png" });
+              onPasteFile?.([f]);
+            }}
+          >
+            mock paste
+          </button>
+        </>
+      );
+    }),
+  };
+});
+
+class FakeXhrUpload {
+  onprogress: ((e: ProgressEvent) => void) | null = null;
+}
+
+class FakeXhr {
+  method = "";
+  url = "";
+  body: Document | XMLHttpRequestBodyInit | null = null;
+  status = 0;
+  responseText = "";
+  headers: Record<string, string> = {};
+  upload = new FakeXhrUpload();
+  onload: (() => void) | null = null;
+  onerror: (() => void) | null = null;
+  onabort: (() => void) | null = null;
+
+  open(method: string, url: string) {
+    this.method = method;
+    this.url = url;
+  }
+  setRequestHeader(k: string, v: string) {
+    this.headers[k] = v;
+  }
+  send(body: Document | XMLHttpRequestBodyInit | null) {
+    this.body = body;
+  }
+  abort() {
+    this.onabort?.();
+  }
+  resolve(status: number, body: string) {
+    this.status = status;
+    this.responseText = body;
+    this.onload?.();
+  }
+}
+
+function installXhr(): FakeXhr[] {
+  const xhrs: FakeXhr[] = [];
+  vi.stubGlobal(
+    "XMLHttpRequest",
+    // biome-ignore lint/complexity/useArrowFunction: must be `new`-able
+    function () {
+      const x = new FakeXhr();
+      xhrs.push(x);
+      return x;
+    } as unknown as typeof XMLHttpRequest,
+  );
+  return xhrs;
+}
 
 interface FetchEntry {
   status?: number;
@@ -107,6 +196,7 @@ describe("NoteEditor route", () => {
   beforeEach(() => {
     localStorage.clear();
     useVaultStore.setState({ vaults: {}, activeVaultId: null });
+    useToastStore.setState({ toasts: [] });
     seedStore();
     // jsdom doesn't implement confirm; default it to true so paths that gate
     // on user approval proceed.
@@ -224,4 +314,87 @@ describe("NoteEditor route", () => {
     fireEvent.change(pathInput, { target: { value: "Canon/Aaron-v2" } });
     expect(screen.getByText(/renaming moves the note/i)).toBeInTheDocument();
   });
+
+  it("drop file → uploads, inserts markdown, and links to the existing note", async () => {
+    const fetchImpl = installFetch({
+      "GET /api/notes": { body: baseNote },
+      "POST /api/notes/abc-123/attachments": {
+        status: 201,
+        body: {
+          id: "att-1",
+          noteId: "abc-123",
+          path: "2026-04-18/shot.png",
+          mimeType: "image/png",
+        },
+      },
+    });
+    const xhrs = installXhr();
+    renderAt("/notes/abc-123/edit");
+
+    const cm = await screen.findByTestId("cm-editor");
+    const dropZone = cm.closest("div.relative");
+    expect(dropZone).not.toBeNull();
+
+    const file = new File([new Uint8Array([1, 2, 3])], "shot.png", { type: "image/png" });
+    const dataTransfer = {
+      files: [file],
+      items: [{ kind: "file" }],
+      types: ["Files"],
+      dropEffect: "copy",
+    } as unknown as DataTransfer;
+
+    fireEvent.drop(dropZone!, { dataTransfer });
+
+    await waitFor(() => expect(xhrs.length).toBe(1));
+    expect(xhrs[0]!.url).toBe("http://localhost:1940/api/storage/upload");
+
+    await act(async () => {
+      xhrs[0]!.resolve(
+        201,
+        JSON.stringify({ path: "2026-04-18/shot.png", size: 3, mimeType: "image/png" }),
+      );
+    });
+
+    await waitFor(() => {
+      expect((cm as HTMLTextAreaElement).value).toContain(
+        "![shot.png](/api/storage/2026-04-18/shot.png)",
+      );
+    });
+
+    await waitFor(() => {
+      const linkCall = fetchImpl.mock.calls.find(([url, init]) => {
+        const u = typeof url === "string" ? url : url.toString();
+        return (
+          u.includes("/api/notes/abc-123/attachments") &&
+          (init as RequestInit | undefined)?.method === "POST"
+        );
+      });
+      expect(linkCall).toBeDefined();
+    });
+  });
+
+  it("oversized file is rejected before any upload fires", async () => {
+    installFetch({ "GET /api/notes": { body: baseNote } });
+    const xhrs = installXhr();
+    renderAt("/notes/abc-123/edit");
+
+    const cm = await screen.findByTestId("cm-editor");
+    const dropZone = cm.closest("div.relative");
+
+    const big = new File([new Uint8Array([1])], "huge.png", { type: "image/png" });
+    Object.defineProperty(big, "size", { value: 200 * 1024 * 1024 });
+
+    const dataTransfer = {
+      files: [big],
+      items: [{ kind: "file" }],
+      types: ["Files"],
+    } as unknown as DataTransfer;
+    fireEvent.drop(dropZone!, { dataTransfer });
+
+    expect(xhrs.length).toBe(0);
+    await waitFor(() => {
+      const toasts = useToastStore.getState().toasts;
+      expect(toasts.some((t) => /too large/i.test(t.message))).toBe(true);
+    });
+  });
 });
diff --git a/src/app/routes/NoteEditor.tsx b/src/app/routes/NoteEditor.tsx
index f89ecc7..440095e 100644
--- a/src/app/routes/NoteEditor.tsx
+++ b/src/app/routes/NoteEditor.tsx
@@ -1,11 +1,17 @@
+import { AttachmentDropZone } from "@/components/AttachmentDropZone";
+import { AttachmentPicker } from "@/components/AttachmentPicker";
+import { AttachmentUploadList } from "@/components/AttachmentUploadList";
+import type { CodeMirrorEditorHandle } from "@/components/CodeMirrorEditor";
 import { CodeMirrorEditor } from "@/components/CodeMirrorEditor";
 import { DeleteNoteButton } from "@/components/DeleteNoteButton";
 import { MarkdownView, buildWikilinkResolver } from "@/components/MarkdownView";
 import { TagEditor, normalizeTag } from "@/components/TagEditor";
+import { useAttachmentUploader } from "@/components/useAttachmentUploader";
 import { relativeTime } from "@/lib/time";
+import { useToastStore } from "@/lib/toast/store";
 import { useNote, useUpdateNote, useVaultStore } from "@/lib/vault";
 import { type UpdateNotePayload, VaultAuthError, VaultConflictError } from "@/lib/vault/client";
-import type { Note } from "@/lib/vault/types";
+import type { Note, NoteAttachment } from "@/lib/vault/types";
 import { useCallback, useEffect, useMemo, useRef, useState } from "react";
 import { Link, Navigate, useNavigate, useParams } from "react-router";
 
@@ -56,6 +62,7 @@ function toEditorState(note: Note): EditorState {
 
 function EditorSurface({ note }: { note: Note }) {
   const navigate = useNavigate();
+  const pushToast = useToastStore((s) => s.push);
   const resolver = useMemo(() => buildWikilinkResolver(note), [note]);
   const [baseline, setBaseline] = useState<EditorState>(() => toEditorState(note));
   const [draft, setDraft] = useState<EditorState>(() => toEditorState(note));
@@ -64,6 +71,22 @@ function EditorSurface({ note }: { note: Note }) {
   const [saveError, setSaveError] = useState<string | null>(null);
   const mutation = useUpdateNote(note.id);
   const lastServerNote = useRef<Note>(note);
+  const editorRef = useRef<CodeMirrorEditorHandle>(null);
+
+  const uploader = useAttachmentUploader({
+    noteId: note.id,
+    onInsert: (md) => {
+      if (editorRef.current) {
+        editorRef.current.insertAtCursor(md);
+      } else {
+        setDraft((d) => ({ ...d, content: `${d.content}${md}` }));
+      }
+    },
+    onLinked: () => {
+      pushToast("Attachment added", "success");
+    },
+    onError: (msg) => pushToast(msg, "error"),
+  });
 
   // If the server-side note is refetched (e.g., after a background refresh),
   // only update baseline if the user has no in-flight changes.
@@ -241,22 +264,95 @@ function EditorSurface({ note }: { note: Note }) {
       ) : null}
 
       <div className="grid min-h-[60vh] gap-4 lg:grid-cols-2">
-        <div className="min-w-0 rounded-md border border-border bg-card">
+        <AttachmentDropZone
+          onDropFiles={uploader.start}
+          className="min-w-0 rounded-md border border-border bg-card"
+          hint={ALLOWLIST_HINT}
+        >
           <CodeMirrorEditor
+            ref={editorRef}
             value={draft.content}
             onChange={(content) => setDraft((d) => ({ ...d, content }))}
             onSave={handleSave}
             onCancel={handleCancel}
+            onPasteFile={(files) => {
+              uploader.start(files);
+              return true;
+            }}
           />
-        </div>
+        </AttachmentDropZone>
         <div className="min-w-0 overflow-auto rounded-md border border-border bg-card p-4">
           <MarkdownView content={previewContent} resolve={resolver} />
         </div>
       </div>
+
+      <AttachmentsSection
+        attachments={note.attachments ?? []}
+        uploads={uploader.uploads}
+        onPickFiles={uploader.start}
+        onCancel={uploader.cancel}
+        onDismiss={uploader.dismiss}
+      />
     </article>
   );
 }
 
+const ALLOWLIST_HINT = (
+  <>
+    Images, audio, webm video.{" "}
+    <a
+      href="https://github.com/ParachuteComputer/parachute-vault/issues/127"
+      target="_blank"
+      rel="noreferrer"
+      className="underline"
+    >
+      PDF + mp4 coming
+    </a>
+  </>
+);
+
+function AttachmentsSection({
+  attachments,
+  uploads,
+  onPickFiles,
+  onCancel,
+  onDismiss,
+}: {
+  attachments: NoteAttachment[];
+  uploads: ReturnType<typeof useAttachmentUploader>["uploads"];
+  onPickFiles: (files: File[]) => void;
+  onCancel: (id: string) => void;
+  onDismiss: (id: string) => void;
+}) {
+  return (
+    <section className="mt-6 border-t border-border pt-4">
+      <div className="mb-3 flex items-center justify-between">
+        <h2 className="font-serif text-lg">Attachments</h2>
+        <AttachmentPicker onPickFiles={onPickFiles} />
+      </div>
+      <p className="mb-3 text-xs text-fg-dim">
+        Drop or paste files into the editor. Max 100 MB each. {ALLOWLIST_HINT}.
+      </p>
+      <AttachmentUploadList uploads={uploads} onCancel={onCancel} onDismiss={onDismiss} />
+      {attachments.length > 0 ? (
+        <ul className="mt-3 space-y-1 text-sm">
+          {attachments.map((a) => (
+            <li
+              key={a.id}
+              className="flex items-center justify-between gap-2 rounded border border-border bg-card/50 px-3 py-1.5 font-mono text-xs"
+            >
+              <span className="truncate" title={a.path ?? a.id}>
+                {a.filename ?? a.path ?? a.id}
+              </span>
+              {a.mimeType ? <span className="shrink-0 text-fg-dim">{a.mimeType}</span> : null}
+            </li>
+          ))}
+        </ul>
+      ) : null}
+    </section>
+  );
+}
+
 function ConflictBanner({
   conflict,
   onReload,
diff --git a/src/app/routes/NoteNew.test.tsx b/src/app/routes/NoteNew.test.tsx
index 5eee759..84fe158 100644
--- a/src/app/routes/NoteNew.test.tsx
+++ b/src/app/routes/NoteNew.test.tsx
@@ -7,14 +7,52 @@ import type { ReactNode } from "react";
 import { MemoryRouter, Route, Routes } from "react-router";
 import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
 
-vi.mock("@/components/CodeMirrorEditor", () => ({
-  CodeMirrorEditor: ({
-    value,
-    onChange,
-  }: { value: string; onChange(next: string): void; onSave?(): void; onCancel?(): void }) => (
-    <textarea data-testid="cm-editor" value={value} onChange={(e) => onChange(e.target.value)} />
-  ),
-}));
+vi.mock("@/components/CodeMirrorEditor", async () => {
+  const React = await import("react");
+  return {
+    CodeMirrorEditor: React.forwardRef(function MockCodeMirrorEditor(
+      props: {
+        value: string;
+        onChange(next: string): void;
+        onSave?(): void;
+        onCancel?(): void;
+        onPasteFile?(files: File[]): boolean;
+      },
+      ref: React.Ref<{ insertAtCursor(s: string): void; focus(): void }>,
+    ) {
+      const { value, onChange, onPasteFile } = props;
+      React.useImperativeHandle(
+        ref,
+        () => ({
+          insertAtCursor(s: string) {
+            onChange(value + s);
+          },
+          focus() {},
+        }),
+        [value, onChange],
+      );
+      return (
+        <>
+          <textarea
+            data-testid="cm-editor"
+            value={value}
+            onChange={(e) => onChange(e.target.value)}
+          />
+          <button
+            type="button"
+            data-testid="cm-paste-image"
+            onClick={() => {
+              const f = new File([new Uint8Array([1, 2])], "pasted.png", { type: "image/png" });
+              onPasteFile?.([f]);
+            }}
+          >
+            mock paste
+          </button>
+        </>
+      );
+    }),
+  };
+});
 
 interface FetchEntry {
   status?: number;
@@ -52,6 +90,56 @@ function installFetch(map: FetchMap) {
   return fetchImpl;
 }
 
+class FakeXhrUpload {
+  onprogress: ((e: ProgressEvent) => void) | null = null;
+}
+
+class FakeXhr {
+  method = "";
+  url = "";
+  body: Document | XMLHttpRequestBodyInit | null = null;
+  status = 0;
+  responseText = "";
+  headers: Record<string, string> = {};
+  upload = new FakeXhrUpload();
+  onload: (() => void) | null = null;
+  onerror: (() => void) | null = null;
+  onabort: (() => void) | null = null;
+
+  open(method: string, url: string) {
+    this.method = method;
+    this.url = url;
+  }
+  setRequestHeader(k: string, v: string) {
+    this.headers[k] = v;
+  }
+  send(body: Document | XMLHttpRequestBodyInit | null) {
+    this.body = body;
+  }
+  abort() {
+    this.onabort?.();
+  }
+  resolve(status: number, body: string) {
+    this.status = status;
+    this.responseText = body;
+    this.onload?.();
+  }
+}
+
+function installXhr(): FakeXhr[] {
+  const xhrs: FakeXhr[] = [];
+  vi.stubGlobal(
+    "XMLHttpRequest",
+    // biome-ignore lint/complexity/useArrowFunction: must be `new`-able
+    function () {
+      const x = new FakeXhr();
+      xhrs.push(x);
+      return x;
+    } as unknown as typeof XMLHttpRequest,
+  );
+  return xhrs;
+}
+
 function seedStore() {
   useVaultStore.setState({
     vaults: {
@@ -172,6 +260,157 @@ describe("NoteNew route", () => {
     expect(useToastStore.getState().toasts[0]?.message).toContain("Created");
   });
 
+  it("drop file → uploads, inserts image markdown, stages for link-on-create", async () => {
+    installFetch({});
+    const xhrs = installXhr();
+    renderAt("/new");
+
+    const dropZone = screen.getByTestId("cm-editor").closest("div.relative");
+    expect(dropZone).not.toBeNull();
+
+    const file = new File([new Uint8Array([1, 2, 3])], "shot.png", { type: "image/png" });
+    const dataTransfer = {
+      files: [file],
+      items: [{ kind: "file" }],
+      types: ["Files"],
+      dropEffect: "copy",
+    } as unknown as DataTransfer;
+
+    fireEvent.drop(dropZone!, { dataTransfer });
+
+    await waitFor(() => {
+      expect(xhrs.length).toBe(1);
+    });
+    expect(xhrs[0]!.url).toBe("http://localhost:1940/api/storage/upload");
+    expect(xhrs[0]!.method).toBe("POST");
+
+    await act(async () => {
+      xhrs[0]!.resolve(
+        201,
+        JSON.stringify({ path: "2026-04-18/shot.png", size: 3, mimeType: "image/png" }),
+      );
+      await Promise.resolve();
+    });
+
+    await waitFor(() => {
+      expect((screen.getByTestId("cm-editor") as HTMLTextAreaElement).value).toContain(
+        "![shot.png](/api/storage/2026-04-18/shot.png)",
+      );
+    });
+    expect(await screen.findByText("staged")).toBeInTheDocument();
+  });
+
+  it("paste image triggers upload through onPasteFile", async () => {
+    installFetch({});
+    const xhrs = installXhr();
+    renderAt("/new");
+
+    await act(async () => {
+      fireEvent.click(screen.getByTestId("cm-paste-image"));
+    });
+
+    await waitFor(() => {
+      expect(xhrs.length).toBe(1);
+    });
+    expect(xhrs[0]!.url).toBe("http://localhost:1940/api/storage/upload");
+    expect((xhrs[0]!.body as FormData).get("file")).toBeInstanceOf(File);
+  });
+
+  it("oversized file is rejected before any upload fires", async () => {
+    installFetch({});
+    const xhrs = installXhr();
+    renderAt("/new");
+
+    const big = new File([new Uint8Array([1])], "huge.png", { type: "image/png" });
+    Object.defineProperty(big, "size", { value: 200 * 1024 * 1024 });
+
+    const dropZone = screen.getByTestId("cm-editor").closest("div.relative");
+    const dataTransfer = {
+      files: [big],
+      items: [{ kind: "file" }],
+      types: ["Files"],
+    } as unknown as DataTransfer;
+
+    fireEvent.drop(dropZone!, { dataTransfer });
+
+    // No upload attempted; an error toast was pushed.
+    expect(xhrs.length).toBe(0);
+    await waitFor(() => {
+      const toasts = useToastStore.getState().toasts;
+      expect(toasts.some((t) => /too large/i.test(t.message))).toBe(true);
+    });
+  });
+
+  it("happy path on /new: create succeeds and staged attachments get linked", async () => {
+    const fetchImpl = installFetch({
+      "POST /api/notes/new-id/attachments": {
+        status: 201,
+        body: {
+          id: "att-1",
+          noteId: "new-id",
+          path: "2026-04-18/shot.png",
+          mimeType: "image/png",
+        },
+      },
+      "POST /api/notes": {
+        status: 201,
+        body: {
+          id: "new-id",
+          path: "Projects/README",
+          createdAt: "2026-04-18T12:00:00Z",
+          content: "ok",
+          tags: [],
+        },
+      },
+    });
+    const xhrs = installXhr();
+    renderAt("/new");
+
+    // Drop first so we have something staged.
+    const dropZone = screen.getByTestId("cm-editor").closest("div.relative");
+    const file = new File([new Uint8Array([1])], "shot.png", { type: "image/png" });
+    const dataTransfer = {
+      files: [file],
+      items: [{ kind: "file" }],
+      types: ["Files"],
+    } as unknown as DataTransfer;
+    fireEvent.drop(dropZone!, { dataTransfer });
+    await waitFor(() => expect(xhrs.length).toBe(1));
+    await act(async () => {
+      xhrs[0]!.resolve(
+        201,
+        JSON.stringify({ path: "2026-04-18/shot.png", size: 1, mimeType: "image/png" }),
+      );
+    });
+    await waitFor(() => expect(screen.getByText("staged")).toBeInTheDocument());
+
+    // Now fill path + content and create.
+    fireEvent.change(screen.getByLabelText(/note path/i), {
+      target: { value: "Projects/README" },
+    });
+    fireEvent.change(screen.getByTestId("cm-editor"), { target: { value: "# hi" } });
+    await act(async () => {
+      fireEvent.click(screen.getByRole("button", { name: /^create$/i }));
+    });
+
+    await waitFor(() => {
+      expect(screen.getByText("NoteViewPage")).toBeInTheDocument();
+    });
+
+    const linkCall = fetchImpl.mock.calls.find(([url, init]) => {
+      const u = typeof url === "string" ? url : url.toString();
+      return (
+        u.includes("/api/notes/new-id/attachments") &&
+        (init as RequestInit | undefined)?.method === "POST"
+      );
+    });
+    expect(linkCall).toBeDefined();
+    expect(JSON.parse((linkCall![1] as RequestInit).body as string)).toEqual({
+      path: "2026-04-18/shot.png",
+      mimeType: "image/png",
+    });
+  });
+
   it("duplicate path: error is visible and content/path are preserved", async () => {
     installFetch({
       "POST /api/notes": {
diff --git a/src/app/routes/NoteNew.tsx b/src/app/routes/NoteNew.tsx
index b2053a6..02e4580 100644
--- a/src/app/routes/NoteNew.tsx
+++ b/src/app/routes/NoteNew.tsx
@@ -1,13 +1,24 @@
+import { AttachmentDropZone } from "@/components/AttachmentDropZone";
+import { AttachmentPicker } from "@/components/AttachmentPicker";
+import { AttachmentUploadList } from "@/components/AttachmentUploadList";
+import type { CodeMirrorEditorHandle } from "@/components/CodeMirrorEditor";
 import { CodeMirrorEditor } from "@/components/CodeMirrorEditor";
 import { MarkdownView, buildWikilinkResolver } from "@/components/MarkdownView";
 import { TagEditor, normalizeTag } from "@/components/TagEditor";
+import { useAttachmentUploader } from "@/components/useAttachmentUploader";
 import { useToastStore } from "@/lib/toast/store";
-import { useCreateNote, useVaultStore } from "@/lib/vault";
+import { useCreateNote, useLinkAttachment, useVaultStore } from "@/lib/vault";
 import { type CreateNotePayload, VaultAuthError } from "@/lib/vault/client";
 import type { Note } from "@/lib/vault/types";
-import { useCallback, useEffect, useState } from "react";
+import { useCallback, useEffect, useRef, useState } from "react";
 import { Link, Navigate, useNavigate } from "react-router";
 
+interface StagedUpload {
+  path: string;
+  mimeType: string;
+  filename: string;
+}
+
 interface DraftState {
   content: string;
   path: string;
@@ -22,9 +33,25 @@ export function NoteNew() {
   const navigate = useNavigate();
   const pushToast = useToastStore((s) => s.push);
   const mutation = useCreateNote();
+  const linkAttachment = useLinkAttachment();
   const [draft, setDraft] = useState<DraftState>(EMPTY_DRAFT);
   const [tagInput, setTagInput] = useState("");
   const [saveError, setSaveError] = useState<string | null>(null);
+  const [staged, setStaged] = useState<StagedUpload[]>([]);
+  const editorRef = useRef<CodeMirrorEditorHandle>(null);
+
+  const uploader = useAttachmentUploader({
+    noteId: null,
+    onInsert: (md) => {
+      if (editorRef.current) {
+        editorRef.current.insertAtCursor(md);
+      } else {
+        setDraft((d) => ({ ...d, content: `${d.content}${md}` }));
+      }
+    },
+    onStaged: (s) => setStaged((prev) => [...prev, s]),
+    onError: (msg) => pushToast(msg, "error"),
+  });
 
   if (!activeVault) return <Navigate to="/" replace />;
 
@@ -48,7 +75,19 @@ export function NoteNew() {
 
     setSaveError(null);
     mutation.mutate(payload, {
-      onSuccess: (created: Note) => {
+      onSuccess: async (created: Note) => {
+        for (const s of staged) {
+          try {
+            await linkAttachment.mutateAsync({
+              noteId: created.id,
+              path: s.path,
+              mimeType: s.mimeType,
+            });
+          } catch (err) {
+            const msg = err instanceof Error ? err.message : "Link failed";
+            pushToast(`Failed to attach ${s.filename}: ${msg}`, "error");
+          }
+        }
         pushToast(`Created ${created.path ?? created.id}`, "success");
         navigate(`/notes/${encodeURIComponent(created.id)}`);
       },
@@ -66,7 +105,7 @@ export function NoteNew() {
         }
       },
     });
-  }, [draft, isValid, mutation, navigate, pushToast]);
+  }, [draft, isValid, linkAttachment, mutation, navigate, pushToast, staged]);
 
   const handleCancel = useCallback(() => {
     if (isDirty && !confirm("Discard this draft?")) return;
@@ -175,14 +214,23 @@ export function NoteNew() {
         ) : null}
 
         <div className="grid min-h-[60vh] gap-4 lg:grid-cols-2">
-          <div className="min-w-0 rounded-md border border-border bg-card">
+          <AttachmentDropZone
+            onDropFiles={uploader.start}
+            className="min-w-0 rounded-md border border-border bg-card"
+            hint="Images, audio, webm video"
+          >
             <CodeMirrorEditor
+              ref={editorRef}
               value={draft.content}
               onChange={(content) => setDraft((d) => ({ ...d, content }))}
               onSave={handleCreate}
               onCancel={handleCancel}
+              onPasteFile={(files) => {
+                uploader.start(files);
+                return true;
+              }}
             />
-          </div>
+          </AttachmentDropZone>
           <div className="min-w-0 overflow-auto rounded-md border border-border bg-card p-4">
             {draft.content.trim() ? (
               <MarkdownView content={draft.content} resolve={resolver} />
@@ -191,6 +239,44 @@ export function NoteNew() {
             )}
           </div>
         </div>
+
+        <section className="mt-6 border-t border-border pt-4">
+          <div className="mb-3 flex items-center justify-between">
+            <h2 className="font-serif text-lg">Attachments</h2>
+            <AttachmentPicker onPickFiles={uploader.start} />
+          </div>
+          <p className="mb-3 text-xs text-fg-dim">
+            Drop or paste files into the editor. Attachments link to the note when you save. Max 100
+            MB each. Images, audio, webm video.{" "}
+            <a
+              href="https://github.com/ParachuteComputer/parachute-vault/issues/127"
+              target="_blank"
+              rel="noreferrer"
+              className="underline"
+            >
+              PDF + mp4 coming
+            </a>
+            .
+          </p>
+          <AttachmentUploadList
+            uploads={uploader.uploads}
+            onCancel={uploader.cancel}
+            onDismiss={uploader.dismiss}
+          />
+          {staged.length > 0 ? (
+            <ul className="mt-3 space-y-1 text-sm">
+              {staged.map((s) => (
+                <li
+                  key={s.path}
+                  className="flex items-center justify-between gap-2 rounded border border-border bg-card/50 px-3 py-1.5 font-mono text-xs text-fg-muted"
+                >
+                  <span className="truncate">{s.filename}</span>
+                  <span className="shrink-0 text-fg-dim">staged</span>
+                </li>
+              ))}
+            </ul>
+          ) : null}
+        </section>
       </article>
     </div>
   );
diff --git a/src/components/AttachmentDropZone.tsx b/src/components/AttachmentDropZone.tsx
new file mode 100644
index 0000000..e4bd5ce
--- /dev/null
+++ b/src/components/AttachmentDropZone.tsx
@@ -0,0 +1,77 @@
+import { type ReactNode, useCallback, useRef, useState } from "react";
+
+interface Props {
+  onDropFiles: (files: File[]) => void;
+  children: ReactNode;
+  className?: string;
+  hint?: ReactNode;
+}
+
+export function AttachmentDropZone({ onDropFiles, children, className, hint }: Props) {
+  const [over, setOver] = useState(false);
+  // Track nested dragenter/leave depth so child elements don't flicker the overlay.
+  const depthRef = useRef(0);
+
+  const onDragEnter = useCallback((e: React.DragEvent) => {
+    if (!hasFiles(e.dataTransfer)) return;
+    e.preventDefault();
+    depthRef.current += 1;
+    setOver(true);
+  }, []);
+
+  const onDragLeave = useCallback((e: React.DragEvent) => {
+    if (!hasFiles(e.dataTransfer)) return;
+    e.preventDefault();
+    depthRef.current = Math.max(0, depthRef.current - 1);
+    if (depthRef.current === 0) setOver(false);
+  }, []);
+
+  const onDragOver = useCallback((e: React.DragEvent) => {
+    if (!hasFiles(e.dataTransfer)) return;
+    e.preventDefault();
+    e.dataTransfer.dropEffect = "copy";
+  }, []);
+
+  const onDrop = useCallback(
+    (e: React.DragEvent) => {
+      if (!hasFiles(e.dataTransfer)) return;
+      e.preventDefault();
+      setOver(false);
+      depthRef.current = 0;
+      const files = Array.from(e.dataTransfer.files);
+      if (files.length > 0) onDropFiles(files);
+    },
+    [onDropFiles],
+  );
+
+  return (
+    <div
+      className={`relative ${className ?? ""}`}
+      onDragEnter={onDragEnter}
+      onDragLeave={onDragLeave}
+      onDragOver={onDragOver}
+      onDrop={onDrop}
+    >
+      {children}
+      {over ? (
+        <div
+          aria-hidden="true"
+          className="pointer-events-none absolute inset-0 z-20 flex items-center justify-center rounded-md border-2 border-dashed border-accent bg-accent/10 text-sm text-accent"
+        >
+          <div className="rounded-md bg-bg/80 px-4 py-2 font-medium shadow">
+            Drop to attach{hint ? <span className="ml-2 text-fg-dim">— {hint}</span> : null}
+          </div>
+        </div>
+      ) : null}
+    </div>
+  );
+}
+
+function hasFiles(dt: DataTransfer | null): boolean {
+  if (!dt) return false;
+  const types = dt.types;
+  for (let i = 0; i < types.length; i++) {
+    if (types[i] === "Files") return true;
+  }
+  return false;
+}
diff --git a/src/components/AttachmentPicker.tsx b/src/components/AttachmentPicker.tsx
new file mode 100644
index 0000000..0fec558
--- /dev/null
+++ b/src/components/AttachmentPicker.tsx
@@ -0,0 +1,42 @@
+import { useRef } from "react";
+
+interface Props {
+  onPickFiles: (files: File[]) => void;
+  label?: string;
+  className?: string;
+}
+
+const ACCEPT =
+  "image/png,image/jpeg,image/gif,image/webp,audio/wav,audio/mpeg,audio/mp4,audio/ogg,audio/webm,video/webm,.wav,.mp3,.m4a,.ogg,.webm,.png,.jpg,.jpeg,.gif,.webp";
+
+export function AttachmentPicker({ onPickFiles, label = "Attach files…", className }: Props) {
+  const inputRef = useRef<HTMLInputElement>(null);
+
+  return (
+    <>
+      <button
+        type="button"
+        onClick={() => inputRef.current?.click()}
+        className={
+          className ??
+          "rounded-md border border-border bg-card px-3 py-1.5 text-sm text-fg-muted hover:text-accent"
+        }
+        title="Upload an attachment"
+      >
+        {label}
+      </button>
+      <input
+        ref={inputRef}
+        type="file"
+        multiple
+        accept={ACCEPT}
+        className="hidden"
+        onChange={(e) => {
+          const files = Array.from(e.target.files ?? []);
+          if (files.length > 0) onPickFiles(files);
+          e.target.value = "";
+        }}
+      />
+    </>
+  );
+}
diff --git a/src/components/AttachmentUploadList.tsx b/src/components/AttachmentUploadList.tsx
new file mode 100644
index 0000000..d0fb834
--- /dev/null
+++ b/src/components/AttachmentUploadList.tsx
@@ -0,0 +1,76 @@
+import type { UploadEntry } from "./useAttachmentUploader";
+
+interface Props {
+  uploads: UploadEntry[];
+  onCancel(id: string): void;
+  onDismiss(id: string): void;
+}
+
+export function AttachmentUploadList({ uploads, onCancel, onDismiss }: Props) {
+  if (uploads.length === 0) return null;
+  return (
+    <ul className="space-y-2">
+      {uploads.map((u) => (
+        <li
+          key={u.id}
+          className="rounded-md border border-border bg-card/60 px-3 py-2 text-xs text-fg-muted"
+        >
+          <div className="flex items-center justify-between gap-2">
+            <span className="truncate font-mono" title={u.filename}>
+              {u.filename}
+            </span>
+            <span className="shrink-0">{label(u)}</span>
+          </div>
+          {u.status === "uploading" ? (
+            <div className="mt-1 h-1 w-full overflow-hidden rounded bg-border/40">
+              <div
+                className="h-full bg-accent transition-[width]"
+                style={{ width: `${progressPct(u)}%` }}
+              />
+            </div>
+          ) : null}
+          {u.status === "error" && u.error ? <p className="mt-1 text-red-400">{u.error}</p> : null}
+          <div className="mt-1 flex justify-end gap-2 text-xs">
+            {u.status === "uploading" || u.status === "linking" ? (
+              <button
+                type="button"
+                onClick={() => onCancel(u.id)}
+                className="text-fg-dim hover:text-fg"
+              >
+                Cancel
+              </button>
+            ) : (
+              <button
+                type="button"
+                onClick={() => onDismiss(u.id)}
+                className="text-fg-dim hover:text-fg"
+              >
+                Dismiss
+              </button>
+            )}
+          </div>
+        </li>
+      ))}
+    </ul>
+  );
+}
+
+function progressPct(u: UploadEntry): number {
+  if (u.size === 0) return 0;
+  return Math.min(100, Math.round((u.loaded / u.size) * 100));
+}
+
+function label(u: UploadEntry): string {
+  switch (u.status) {
+    case "uploading":
+      return `${progressPct(u)}%`;
+    case "linking":
+      return "Linking…";
+    case "done":
+      return "Done";
+    case "cancelled":
+      return "Cancelled";
+    case "error":
+      return "Error";
+  }
+}
diff --git a/src/components/CodeMirrorEditor.tsx b/src/components/CodeMirrorEditor.tsx
index e5fb334..a3fe87e 100644
--- a/src/components/CodeMirrorEditor.tsx
+++ b/src/components/CodeMirrorEditor.tsx
@@ -4,7 +4,7 @@ import { HighlightStyle, syntaxHighlighting } from "@codemirror/language";
 import { EditorState } from "@codemirror/state";
 import { EditorView, keymap, lineNumbers } from "@codemirror/view";
 import { tags as t } from "@lezer/highlight";
-import { useEffect, useRef } from "react";
+import { forwardRef, useEffect, useImperativeHandle, useRef } from "react";
 
 const lensHighlight = HighlightStyle.define([
   { tag: t.heading, color: "var(--color-fg)", fontWeight: "600" },
@@ -47,22 +47,53 @@ const lensTheme = EditorView.theme({
   },
 });
 
+export interface CodeMirrorEditorHandle {
+  insertAtCursor(text: string): void;
+  focus(): void;
+}
+
 interface Props {
   value: string;
   onChange(next: string): void;
   onSave?(): void;
   onCancel?(): void;
+  onPasteFile?(files: File[]): boolean;
 }
 
-export function CodeMirrorEditor({ value, onChange, onSave, onCancel }: Props) {
+export const CodeMirrorEditor = forwardRef<CodeMirrorEditorHandle, Props>(function CodeMirrorEditor(
+  { value, onChange, onSave, onCancel, onPasteFile },
+  ref,
+) {
   const host = useRef<HTMLDivElement>(null);
   const view = useRef<EditorView | null>(null);
   const onChangeRef = useRef(onChange);
   const onSaveRef = useRef(onSave);
   const onCancelRef = useRef(onCancel);
+  const onPasteFileRef = useRef(onPasteFile);
   onChangeRef.current = onChange;
   onSaveRef.current = onSave;
   onCancelRef.current = onCancel;
+  onPasteFileRef.current = onPasteFile;
+
+  useImperativeHandle(
+    ref,
+    () => ({
+      insertAtCursor(text: string) {
+        const v = view.current;
+        if (!v) return;
+        const pos = v.state.selection.main.head;
+        v.dispatch({
+          changes: { from: pos, insert: text },
+          selection: { anchor: pos + text.length },
+        });
+        v.focus();
+      },
+      focus() {
+        view.current?.focus();
+      },
+    }),
+    [],
+  );
 
   // biome-ignore lint/correctness/useExhaustiveDependencies: editor builds once; handlers are re-read via refs
   useEffect(() => {
@@ -76,6 +107,26 @@ export function CodeMirrorEditor({ value, onChange, onSave, onCancel }: Props) {
         syntaxHighlighting(lensHighlight),
         lensTheme,
         EditorView.lineWrapping,
+        EditorView.domEventHandlers({
+          paste(event) {
+            const items = event.clipboardData?.items;
+            if (!items) return false;
+            const files: File[] = [];
+            for (const item of items) {
+              if (item.kind === "file") {
+                const f = item.getAsFile();
+                if (f) files.push(f);
+              }
+            }
+            if (files.length === 0) return false;
+            const handled = onPasteFileRef.current?.(files);
+            if (handled) {
+              event.preventDefault();
+              return true;
+            }
+            return false;
+          },
+        }),
         keymap.of([
           ...defaultKeymap,
           ...historyKeymap,
@@ -118,4 +169,4 @@ export function CodeMirrorEditor({ value, onChange, onSave, onCancel }: Props) {
   }, [value]);
 
   return <div ref={host} className="h-full overflow-auto" />;
-}
+});
diff --git a/src/components/MarkdownView.tsx b/src/components/MarkdownView.tsx
index 1fe51c1..0a353c8 100644
--- a/src/components/MarkdownView.tsx
+++ b/src/components/MarkdownView.tsx
@@ -4,6 +4,7 @@ import ReactMarkdown, { type Components } from "react-markdown";
 import { Link } from "react-router";
 import rehypeHighlight from "rehype-highlight";
 import remarkGfm from "remark-gfm";
+import { VaultImage } from "./VaultImage";
 
 export function buildWikilinkResolver(note: Note): WikilinkResolver {
   const map = new Map<string, string>();
@@ -19,6 +20,10 @@ export function buildWikilinkResolver(note: Note): WikilinkResolver {
 }
 
 const MARKDOWN_COMPONENTS: Components = {
+  img({ node: _node, src, alt, className }) {
+    if (!src) return null;
+    return <VaultImage src={src} alt={alt ?? ""} className={className} />;
+  },
   a({ node: _node, href, className, children, ...rest }) {
     const classes = className ?? "";
     if (classes.includes("wikilink")) {
diff --git a/src/components/VaultImage.tsx b/src/components/VaultImage.tsx
new file mode 100644
index 0000000..3fb73be
--- /dev/null
+++ b/src/components/VaultImage.tsx
@@ -0,0 +1,60 @@
+import { useActiveVaultClient } from "@/lib/vault";
+import { useEffect, useState } from "react";
+
+interface Props {
+  src: string;
+  alt?: string;
+  className?: string;
+}
+
+export function VaultImage({ src, alt, className }: Props) {
+  const client = useActiveVaultClient();
+  const [blobUrl, setBlobUrl] = useState<string | null>(null);
+  const [error, setError] = useState<string | null>(null);
+
+  const needsAuth = isVaultStorageUrl(src);
+
+  useEffect(() => {
+    if (!needsAuth || !client) return;
+    let cancelled = false;
+    let objectUrl: string | null = null;
+    setError(null);
+    client
+      .fetchAttachmentBlob(src)
+      .then((blob) => {
+        if (cancelled) return;
+        objectUrl = URL.createObjectURL(blob);
+        setBlobUrl(objectUrl);
+      })
+      .catch((err: unknown) => {
+        if (cancelled) return;
+        setError(err instanceof Error ? err.message : "Failed to load image");
+      });
+    return () => {
+      cancelled = true;
+      if (objectUrl) URL.revokeObjectURL(objectUrl);
+    };
+  }, [needsAuth, src, client]);
+
+  if (error) {
+    return (
+      <span className="text-xs text-red-400">
+        [{alt ?? "image"}: {error}]
+      </span>
+    );
+  }
+  const displaySrc = needsAuth ? blobUrl : src;
+  if (needsAuth && !displaySrc) {
+    return (
+      <span
+        className={`inline-block h-24 w-40 animate-pulse rounded bg-border/40 ${className ?? ""}`}
+        aria-busy="true"
+      />
+    );
+  }
+  return <img src={displaySrc ?? undefined} alt={alt ?? ""} className={className} />;
+}
+
+function isVaultStorageUrl(src: string): boolean {
+  return src.startsWith("/api/storage/") || /^https?:\/\/[^/]+\/api\/storage\//.test(src);
+}
diff --git a/src/components/useAttachmentUploader.ts b/src/components/useAttachmentUploader.ts
new file mode 100644
index 0000000..032b605
--- /dev/null
+++ b/src/components/useAttachmentUploader.ts
@@ -0,0 +1,148 @@
+import { useLinkAttachment, useUploadStorageFile } from "@/lib/vault";
+import { STORAGE_ALLOWED_EXTENSIONS, STORAGE_MAX_BYTES } from "@/lib/vault/client";
+import type { StorageUploadResult } from "@/lib/vault/client";
+import { useCallback, useRef, useState } from "react";
+
+export type UploadStatus = "uploading" | "linking" | "done" | "error" | "cancelled";
+
+export interface UploadEntry {
+  id: string;
+  filename: string;
+  mimeType: string;
+  size: number;
+  loaded: number;
+  status: UploadStatus;
+  error?: string;
+  result?: StorageUploadResult;
+  abort: () => void;
+}
+
+export function fileExt(filename: string): string {
+  const i = filename.lastIndexOf(".");
+  return i >= 0 ? filename.slice(i + 1).toLowerCase() : "";
+}
+
+export function validateFile(file: File): string | null {
+  if (file.size > STORAGE_MAX_BYTES) {
+    return `${file.name} is too large (${formatMB(file.size)}). Max: 100 MB.`;
+  }
+  const ext = fileExt(file.name);
+  if (!STORAGE_ALLOWED_EXTENSIONS.has(ext)) {
+    return `${file.name}: .${ext || "?"} is not in the vault allowlist.`;
+  }
+  return null;
+}
+
+function formatMB(bytes: number): string {
+  return `${(bytes / (1024 * 1024)).toFixed(1)} MB`;
+}
+
+export function markdownForUpload(result: StorageUploadResult, filename: string): string {
+  const url = `/api/storage/${result.path}`;
+  if (result.mimeType.startsWith("image/")) {
+    return `![${filename}](${url})\n`;
+  }
+  return `[${filename}](${url})\n`;
+}
+
+interface UploaderArgs {
+  noteId: string | null;
+  onInsert: (markdown: string) => void;
+  onStaged?: (staged: { path: string; mimeType: string; filename: string }) => void;
+  onLinked?: () => void;
+  onError?: (message: string) => void;
+}
+
+export function useAttachmentUploader({
+  noteId,
+  onInsert,
+  onStaged,
+  onLinked,
+  onError,
+}: UploaderArgs) {
+  const [uploads, setUploads] = useState<UploadEntry[]>([]);
+  const uploadsRef = useRef(uploads);
+  uploadsRef.current = uploads;
+  const upload = useUploadStorageFile();
+  const link = useLinkAttachment();
+
+  const update = useCallback((id: string, patch: Partial<UploadEntry>) => {
+    setUploads((prev) => prev.map((u) => (u.id === id ? { ...u, ...patch } : u)));
+  }, []);
+
+  const start = useCallback(
+    (files: File[]) => {
+      for (const file of files) {
+        const id = `${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
+        const validation = validateFile(file);
+        if (validation) {
+          onError?.(validation);
+          continue;
+        }
+        const controller = new AbortController();
+        const entry: UploadEntry = {
+          id,
+          filename: file.name,
+          mimeType: file.type || "application/octet-stream",
+          size: file.size,
+          loaded: 0,
+          status: "uploading",
+          abort: () => controller.abort(),
+        };
+        setUploads((prev) => [...prev, entry]);
+
+        upload
+          .mutateAsync({
+            file,
+            signal: controller.signal,
+            onProgress: ({ loaded }) => update(id, { loaded }),
+          })
+          .then(async (result) => {
+            update(id, { result, loaded: result.size, mimeType: result.mimeType });
+            onInsert(markdownForUpload(result, file.name));
+
+            if (noteId) {
+              update(id, { status: "linking" });
+              try {
+                await link.mutateAsync({
+                  noteId,
+                  path: result.path,
+                  mimeType: result.mimeType,
+                });
+                update(id, { status: "done" });
+                onLinked?.();
+              } catch (err) {
+                const msg = err instanceof Error ? err.message : "Link failed";
+                update(id, { status: "error", error: msg });
+                onError?.(msg);
+              }
+            } else {
+              update(id, { status: "done" });
+              onStaged?.({ path: result.path, mimeType: result.mimeType, filename: file.name });
+            }
+          })
+          .catch((err: unknown) => {
+            if (err instanceof DOMException && err.name === "AbortError") {
+              update(id, { status: "cancelled" });
+              return;
+            }
+            const msg = err instanceof Error ? err.message : "Upload failed";
+            update(id, { status: "error", error: msg });
+            onError?.(msg);
+          });
+      }
+    },
+    [noteId, onInsert, onStaged, onLinked, onError, upload, link, update],
+  );
+
+  const cancel = useCallback((id: string) => {
+    const entry = uploadsRef.current.find((u) => u.id === id);
+    entry?.abort();
+  }, []);
+
+  const dismiss = useCallback((id: string) => {
+    setUploads((prev) => prev.filter((u) => u.id !== id));
+  }, []);
+
+  return { uploads, start, cancel, dismiss };
+}
diff --git a/src/lib/vault/client.test.ts b/src/lib/vault/client.test.ts
index d874f75..3815e4b 100644
--- a/src/lib/vault/client.test.ts
+++ b/src/lib/vault/client.test.ts
@@ -1,5 +1,5 @@
 import { describe, expect, it, vi } from "vitest";
-import { VaultAuthError, VaultClient, VaultConflictError } from "./client";
+import { VaultAuthError, VaultClient, VaultConflictError, VaultUploadError } from "./client";
 
 function mockFetch(response: { ok?: boolean; status?: number; json?: unknown; text?: string }) {
   return vi.fn<typeof fetch>(async () => {
@@ -12,6 +12,49 @@ function mockFetch(response: { ok?: boolean; status?: number; json?: unknown; te
   });
 }
 
+class FakeXhrUpload {
+  onprogress: ((e: ProgressEvent) => void) | null = null;
+}
+
+class FakeXhr {
+  method = "";
+  url = "";
+  headers: Record<string, string> = {};
+  body: Document | XMLHttpRequestBodyInit | null = null;
+  status = 0;
+  responseText = "";
+  upload = new FakeXhrUpload();
+  onload: (() => void) | null = null;
+  onerror: (() => void) | null = null;
+  onabort: (() => void) | null = null;
+
+  open(method: string, url: string) {
+    this.method = method;
+    this.url = url;
+  }
+  setRequestHeader(k: string, v: string) {
+    this.headers[k] = v;
+  }
+  send(body: Document | XMLHttpRequestBodyInit | null) {
+    this.body = body;
+  }
+  abort() {
+    // Real XHRs fire onabort when abort() is called.
+    this.fireAbort();
+  }
+  fireProgress(loaded: number, total: number) {
+    this.upload.onprogress?.({ lengthComputable: true, loaded, total } as ProgressEvent);
+  }
+  resolve(status: number, body: string) {
+    this.status = status;
+    this.responseText = body;
+    this.onload?.();
+  }
+  fireAbort() {
+    this.onabort?.();
+  }
+}
+
 describe("VaultClient", () => {
   it("sends Bearer token on every request and returns parsed JSON", async () => {
     const fetchImpl = mockFetch({
@@ -291,6 +334,153 @@ describe("VaultClient", () => {
     await expect(client.deleteNote("abc")).rejects.toBeInstanceOf(VaultAuthError);
   });
 
+  it("uploadStorageFile POSTs multipart to /api/storage/upload with Bearer + progress", async () => {
+    const xhrs: FakeXhr[] = [];
+    const factory = () => {
+      const x = new FakeXhr();
+      xhrs.push(x);
+      return x as unknown as XMLHttpRequest;
+    };
+    const client = new VaultClient({
+      vaultUrl: "http://localhost:1940",
+      accessToken: "pvt_abc",
+      fetchImpl: vi.fn(),
+      xhrFactory: factory,
+    });
+
+    const file = new File([new Uint8Array([1, 2, 3, 4])], "shot.png", { type: "image/png" });
+    const progressSeen: number[] = [];
+    const promise = client.uploadStorageFile(file, {
+      onProgress: (p) => progressSeen.push(p.loaded),
+    });
+
+    const xhr = xhrs[0]!;
+    expect(xhr.method).toBe("POST");
+    expect(xhr.url).toBe("http://localhost:1940/api/storage/upload");
+    expect(xhr.headers.Authorization).toBe("Bearer pvt_abc");
+    expect(xhr.body).toBeInstanceOf(FormData);
+    expect((xhr.body as FormData).get("file")).toBeInstanceOf(File);
+
+    xhr.fireProgress(2, 4);
+    xhr.fireProgress(4, 4);
+    xhr.resolve(
+      201,
+      JSON.stringify({ path: "2026-04-18/abc.png", size: 4, mimeType: "image/png" }),
+    );
+
+    const result = await promise;
+    expect(result).toEqual({ path: "2026-04-18/abc.png", size: 4, mimeType: "image/png" });
+    expect(progressSeen).toEqual([2, 4]);
+  });
+
+  it("uploadStorageFile throws VaultAuthError on 401", async () => {
+    const xhrs: FakeXhr[] = [];
+    const factory = () => {
+      const x = new FakeXhr();
+      xhrs.push(x);
+      return x as unknown as XMLHttpRequest;
+    };
+    const client = new VaultClient({
+      vaultUrl: "http://localhost:1940",
+      accessToken: "pvt_abc",
+      fetchImpl: vi.fn(),
+      xhrFactory: factory,
+    });
+    const file = new File([new Uint8Array([1])], "x.png", { type: "image/png" });
+    const p = client.uploadStorageFile(file);
+    xhrs[0]!.resolve(401, '{"error":"unauthorized"}');
+    await expect(p).rejects.toBeInstanceOf(VaultAuthError);
+  });
+
+  it("uploadStorageFile surfaces 413 with VaultUploadError carrying status", async () => {
+    const xhrs: FakeXhr[] = [];
+    const factory = () => {
+      const x = new FakeXhr();
+      xhrs.push(x);
+      return x as unknown as XMLHttpRequest;
+    };
+    const client = new VaultClient({
+      vaultUrl: "http://localhost:1940",
+      accessToken: "pvt_abc",
+      fetchImpl: vi.fn(),
+      xhrFactory: factory,
+    });
+    const file = new File([new Uint8Array([1])], "x.png", { type: "image/png" });
+    const p = client.uploadStorageFile(file);
+    xhrs[0]!.resolve(413, '{"error":"File too large (200MB). Max: 100MB"}');
+    const err = await p.catch((e) => e);
+    expect(err).toBeInstanceOf(VaultUploadError);
+    expect((err as VaultUploadError).status).toBe(413);
+    expect((err as Error).message).toMatch(/too large/i);
+  });
+
+  it("uploadStorageFile aborts when signal is aborted", async () => {
+    const xhrs: FakeXhr[] = [];
+    const factory = () => {
+      const x = new FakeXhr();
+      xhrs.push(x);
+      return x as unknown as XMLHttpRequest;
+    };
+    const client = new VaultClient({
+      vaultUrl: "http://localhost:1940",
+      accessToken: "pvt_abc",
+      fetchImpl: vi.fn(),
+      xhrFactory: factory,
+    });
+    const file = new File([new Uint8Array([1])], "x.png", { type: "image/png" });
+    const controller = new AbortController();
+    const p = client.uploadStorageFile(file, { signal: controller.signal });
+    controller.abort();
+    xhrs[0]!.fireAbort();
+    const err = await p.catch((e) => e);
+    expect(err).toBeInstanceOf(DOMException);
+    expect((err as DOMException).name).toBe("AbortError");
+  });
+
+  it("linkAttachment POSTs JSON to /api/notes/:id/attachments and returns the attachment", async () => {
+    const fetchImpl = mockFetch({
+      status: 201,
+      json: {
+        id: "att-1",
+        noteId: "note-a",
+        path: "2026-04-18/abc.png",
+        mimeType: "image/png",
+        createdAt: "2026-04-18T12:00:00Z",
+      },
+    });
+    const client = new VaultClient({
+      vaultUrl: "http://localhost:1940",
+      accessToken: "pvt_abc",
+      fetchImpl,
+    });
+    const att = await client.linkAttachment("note-a", {
+      path: "2026-04-18/abc.png",
+      mimeType: "image/png",
+    });
+    expect(att.id).toBe("att-1");
+    const call = fetchImpl.mock.calls[0];
+    expect(call?.[0]).toBe("http://localhost:1940/api/notes/note-a/attachments");
+    const init = call?.[1] as RequestInit;
+    expect(init.method).toBe("POST");
+    expect(new Headers(init.headers).get("Content-Type")).toBe("application/json");
+    expect(JSON.parse(init.body as string)).toEqual({
+      path: "2026-04-18/abc.png",
+      mimeType: "image/png",
+    });
+  });
+
+  it("linkAttachment propagates 401 as VaultAuthError", async () => {
+    const fetchImpl = mockFetch({ ok: false, status: 401 });
+    const client = new VaultClient({
+      vaultUrl: "http://localhost:1940",
+      accessToken: "pvt_abc",
+      fetchImpl,
+    });
+    await expect(
+      client.linkAttachment("note-a", { path: "x", mimeType: "image/png" }),
+    ).rejects.toBeInstanceOf(VaultAuthError);
+  });
+
   it("listTags hits /api/tags and returns the summary array", async () => {
     const fetchImpl = mockFetch({
       json: [
diff --git a/src/lib/vault/client.ts b/src/lib/vault/client.ts
index b8f3169..df7bf34 100644
--- a/src/lib/vault/client.ts
+++ b/src/lib/vault/client.ts
@@ -1,9 +1,44 @@
-import type { Note, TagSummary, VaultInfo } from "./types";
+import type { Note, NoteAttachment, TagSummary, VaultInfo } from "./types";
+
+export const STORAGE_MAX_BYTES = 100 * 1024 * 1024;
+export const STORAGE_ALLOWED_EXTENSIONS = new Set([
+  "wav",
+  "mp3",
+  "m4a",
+  "ogg",
+  "webm",
+  "png",
+  "jpg",
+  "jpeg",
+  "gif",
+  "webp",
+]);
 
 export interface VaultClientOptions {
   vaultUrl: string;
   accessToken: string;
   fetchImpl?: typeof fetch;
+  xhrFactory?: () => XMLHttpRequest;
+}
+
+export interface StorageUploadResult {
+  path: string;
+  size: number;
+  mimeType: string;
+}
+
+export interface UploadProgress {
+  loaded: number;
+  total: number;
+}
+
+export class VaultUploadError extends Error {
+  readonly status: number;
+  constructor(message: string, status: number) {
+    super(message);
+    this.name = "VaultUploadError";
+    this.status = status;
+  }
 }
 
 export class VaultAuthError extends Error {
@@ -47,11 +82,17 @@ export class VaultClient {
   private readonly baseUrl: string;
   private readonly token: string;
   private readonly fetchImpl: typeof fetch;
+  private readonly xhrFactory: () => XMLHttpRequest;
 
   constructor(opts: VaultClientOptions) {
     this.baseUrl = opts.vaultUrl.replace(/\/$/, "");
     this.token = opts.accessToken;
     this.fetchImpl = opts.fetchImpl ?? fetch;
+    this.xhrFactory = opts.xhrFactory ?? (() => new XMLHttpRequest());
+  }
+
+  get vaultBaseUrl(): string {
+    return this.baseUrl;
   }
 
   private async request<T>(path: string, init: RequestInit = {}): Promise<T> {
@@ -131,6 +172,85 @@ export class VaultClient {
     return this.request<TagSummary[]>("/api/tags");
   }
 
+  uploadStorageFile(
+    file: File,
+    opts: {
+      onProgress?: (p: UploadProgress) => void;
+      signal?: AbortSignal;
+    } = {},
+  ): Promise<StorageUploadResult> {
+    return new Promise((resolve, reject) => {
+      const xhr = this.xhrFactory();
+      const form = new FormData();
+      form.append("file", file);
+
+      xhr.open("POST", `${this.baseUrl}/api/storage/upload`);
+      xhr.setRequestHeader("Authorization", `Bearer ${this.token}`);
+      xhr.setRequestHeader("Accept", "application/json");
+
+      if (opts.onProgress && xhr.upload) {
+        xhr.upload.onprogress = (e) => {
+          if (e.lengthComputable) opts.onProgress?.({ loaded: e.loaded, total: e.total });
+        };
+      }
+
+      xhr.onload = () => {
+        if (xhr.status === 401 || xhr.status === 403) {
+          reject(new VaultAuthError(`Vault rejected the token (${xhr.status})`));
+          return;
+        }
+        if (xhr.status < 200 || xhr.status >= 300) {
+          let message = `Upload failed (${xhr.status})`;
+          try {
+            const body = JSON.parse(xhr.responseText) as { error?: string };
+            if (body.error) message = body.error;
+          } catch {}
+          reject(new VaultUploadError(message, xhr.status));
+          return;
+        }
+        try {
+          resolve(JSON.parse(xhr.responseText) as StorageUploadResult);
+        } catch (e) {
+          reject(e instanceof Error ? e : new Error("Invalid upload response"));
+        }
+      };
+
+      xhr.onerror = () => reject(new VaultUploadError("Network error during upload", 0));
+      xhr.onabort = () => reject(new DOMException("Upload aborted", "AbortError"));
+
+      if (opts.signal) {
+        if (opts.signal.aborted) {
+          xhr.abort();
+          return;
+        }
+        opts.signal.addEventListener("abort", () => xhr.abort(), { once: true });
+      }
+
+      xhr.send(form);
+    });
+  }
+
+  async linkAttachment(
+    noteIdOrPath: string,
+    body: { path: string; mimeType: string },
+  ): Promise<NoteAttachment> {
+    return this.request<NoteAttachment>(
+      `/api/notes/${encodeURIComponent(noteIdOrPath)}/attachments`,
+      { method: "POST", body: JSON.stringify(body) },
+    );
+  }
+
+  async listAttachments(noteIdOrPath: string): Promise<NoteAttachment[]> {
+    return this.request<NoteAttachment[]>(
+      `/api/notes/${encodeURIComponent(noteIdOrPath)}/attachments`,
+    );
+  }
+
+  storageUrl(path: string): string {
+    const trimmed = path.startsWith("/") ? path.slice(1) : path;
+    return `${this.baseUrl}/api/storage/${trimmed}`;
+  }
+
   async fetchAttachmentBlob(url: string): Promise<Blob> {
     const target = url.startsWith("http")
       ? url
diff --git a/src/lib/vault/queries.ts b/src/lib/vault/queries.ts
index a69a640..1a8232f 100644
--- a/src/lib/vault/queries.ts
+++ b/src/lib/vault/queries.ts
@@ -1,9 +1,16 @@
 import { keepPreviousData, useMutation, useQuery, useQueryClient } from "@tanstack/react-query";
 import { useMemo } from "react";
-import { type CreateNotePayload, type UpdateNotePayload, VaultClient } from "./client";
+import {
+  type CreateNotePayload,
+  type StorageUploadResult,
+  type UpdateNotePayload,
+  type UploadProgress,
+  VaultClient,
+} from "./client";
 import { type NoteQueryState, buildNoteQueryParams } from "./note-query";
 import { loadToken } from "./storage";
 import { useVaultStore } from "./store";
+import type { NoteAttachment } from "./types";
 
 export function useActiveVaultClient(): VaultClient | null {
   const vault = useVaultStore((s) => s.getActiveVault());
@@ -106,6 +113,42 @@ export function useCreateNote() {
   });
 }
 
+export function useUploadStorageFile() {
+  const client = useActiveVaultClient();
+  return useMutation({
+    mutationFn: async (args: {
+      file: File;
+      onProgress?: (p: UploadProgress) => void;
+      signal?: AbortSignal;
+    }): Promise<StorageUploadResult> => {
+      if (!client) throw new Error("No active vault");
+      return client.uploadStorageFile(args.file, {
+        onProgress: args.onProgress,
+        signal: args.signal,
+      });
+    },
+  });
+}
+
+export function useLinkAttachment() {
+  const client = useActiveVaultClient();
+  const activeId = useVaultStore((s) => s.activeVaultId);
+  const qc = useQueryClient();
+  return useMutation({
+    mutationFn: async (args: {
+      noteId: string;
+      path: string;
+      mimeType: string;
+    }): Promise<NoteAttachment> => {
+      if (!client) throw new Error("No active vault");
+      return client.linkAttachment(args.noteId, { path: args.path, mimeType: args.mimeType });
+    },
+    onSuccess: (_att, args) => {
+      qc.invalidateQueries({ queryKey: ["note", activeId, args.noteId] });
+    },
+  });
+}
+
 export function useDeleteNote() {
   const client = useActiveVaultClient();
   const activeId = useVaultStore((s) => s.activeVaultId);
diff --git a/src/lib/vault/types.ts b/src/lib/vault/types.ts
index 0e16b5c..7d01526 100644
--- a/src/lib/vault/types.ts
+++ b/src/lib/vault/types.ts
@@ -86,10 +86,14 @@ export interface NoteLink {
 
 export interface NoteAttachment {
   id: string;
+  noteId?: string;
   filename?: string;
   mimeType?: string;
+  path?: string;
   url?: string;
   size?: number;
+  createdAt?: string;
+  metadata?: Record<string, unknown>;
   [key: string]: unknown;
 }