From 9d2d0e6d2329afeaf77230c931aacd65371127ce Mon Sep 17 00:00:00 2001
From: Matt Toohey <contact@matttoohey.com>
Date: Wed, 21 Oct 2026 11:03:57 -0700
Subject: [PATCH 1/4] feat(staged): add "Add image" to the branch card's
 overflow menu
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The branch timeline's "…" menu gains an "Add image" item, below "Write
note", that picks images and adds them straight to the branch timeline.
Like "Write note" it is offered on every branch: images live in the
store, not the worktree.

macOS (Tauri) opens the native open panel through the dialog plugin's
`open()`, multi-select and filtered to PNG/JPEG/GIF/WebP. A file
`<input>` would not do here: wry's `runOpenPanelWithParameters` ignores
`accept`, so its panel cannot be filtered to images. The plugin and its
`dialog:default` capability (which grants `allow-open`) are already in
place, and the unsandboxed app needs no entitlement or Info.plist key
for NSOpenPanel, so no config changes.

iOS has no Tauri target: Staged runs there as the web build in mobile
Safari. The item clicks a hidden file input with an explicit image
`accept` list, synchronously inside the menu item's click so the tap's
user activation carries through. iOS then presents its own source sheet
— Photo Library (PHPicker) or Files (the document picker, filtered to
the accepted types), plus the Take Photo option iOS always adds for
image inputs — so no custom action sheet is layered on top. Safari owns
photo-library access, so no NSPhotoLibraryUsageDescription is involved.

Picked images reuse the branch card's drag-and-drop pipeline, the
existing way images reach a branch timeline directly: the drop handler's
image branch is extracted into `addTimelineImages`, which both use.
Desktop paths go through `create_image` exactly as a drop does; web
files go through `create_image_from_data`, the endpoint the web build
already uploads through (`create_image` is desktop-only). Both store via
`store_sniffed_image` with no pending session, so a picked image appears
on the timeline immediately, like a dropped one. The chat composer's
attachment path was not reused: its images are pending, hidden until a
session claims them.

Cancelling either picker does nothing. Per-file storage failures toast
like a rejected drop; failing to open the desktop panel goes through the
card's `notifyError`.

The chunked File→base64 loop, duplicated in ImageAttachment and
SessionChatPane, moves to `fileToBase64` rather than gaining a third
copy. `IMAGE_ACCEPT` is split out of `ATTACHMENT_ACCEPT` and
`IMAGE_EXTENSIONS` is exported, so the picker filters come from the
lists the store's other entry points already use.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Signed-off-by: Matt Toohey <contact@matttoohey.com>
---
 .../lib/features/branches/BranchCard.svelte   | 92 +++++++++++++++----
 .../branches/BranchImagePicker.svelte         | 68 ++++++++++++++
 .../features/branches/branchCardHelpers.ts    |  2 +-
 .../branches/branchImagePicker.test.ts        | 49 ++++++++++
 .../features/branches/branchImagePicker.ts    | 25 +++++
 .../features/sessions/ImageAttachment.svelte  | 10 +-
 .../features/sessions/SessionChatPane.svelte  |  9 +-
 .../features/sessions/attachErrors.test.ts    |  8 ++
 .../src/lib/features/sessions/attachErrors.ts |  9 +-
 .../features/sessions/attachmentData.test.ts  | 23 +++++
 .../lib/features/sessions/attachmentData.ts   | 13 +++
 .../features/timeline/BranchTimeline.svelte   | 30 ++++--
 12 files changed, 295 insertions(+), 43 deletions(-)
 create mode 100644 apps/staged/src/lib/features/branches/BranchImagePicker.svelte
 create mode 100644 apps/staged/src/lib/features/branches/branchImagePicker.test.ts
 create mode 100644 apps/staged/src/lib/features/branches/branchImagePicker.ts
 create mode 100644 apps/staged/src/lib/features/sessions/attachmentData.test.ts
 create mode 100644 apps/staged/src/lib/features/sessions/attachmentData.ts

diff --git a/apps/staged/src/lib/features/branches/BranchCard.svelte b/apps/staged/src/lib/features/branches/BranchCard.svelte
index fd987928a..813c318e0 100644
--- a/apps/staged/src/lib/features/branches/BranchCard.svelte
+++ b/apps/staged/src/lib/features/branches/BranchCard.svelte
@@ -63,6 +63,7 @@
   import WriteNoteModal from '../notes/WriteNoteModal.svelte';
   import { splitNoteMarkdown } from '../notes/noteMarkdown';
   import { attachBasename } from '../sessions/attachErrors';
+  import { fileToBase64 } from '../sessions/attachmentData';
   import * as AlertDialog from '$lib/components/ui/alert-dialog';
   import { Button } from '$lib/components/ui/button';
   import {
@@ -81,6 +82,7 @@
   import BranchCardHeaderInfo from './BranchCardHeaderInfo.svelte';
   import BranchCardActionsBar from './BranchCardActionsBar.svelte';
   import BranchCardPrButton from './BranchCardPrButton.svelte';
+  import BranchImagePicker from './BranchImagePicker.svelte';
   import BranchCardSessionManager from './BranchCardSessionManager.svelte';
   import {
     addPendingSession,
@@ -1701,28 +1703,70 @@
     }
 
     if (imagePaths.length > 0) {
-      Promise.all(
-        imagePaths.map(async (filePath) => {
-          try {
-            await commands.createImage(branch.id, branch.projectId, filePath);
-          } catch (e) {
-            console.error('Failed to create image from drop:', e);
-            // Same shape as the text path, so a rejected PDF or oversized
-            // image ("could not open PDF", "media exceeds 10 MB limit") is
-            // not a silent no-op. The extension stays in the name, as in the
-            // composer's attach errors: it is what explains a PDF failure.
-            const reason = e instanceof Error ? e.message : typeof e === 'string' ? e : null;
-            toast.error('Error', {
-              description: `Could not attach "${attachBasename(filePath)}"${reason ? ` \u2014 ${reason}` : ''}`,
-            });
-          }
-        })
-      ).then(() => {
-        loadTimeline();
-      });
+      addImagePaths(imagePaths);
     }
   }
 
+  // =========================================================================
+  // Images → timeline (drop, or the "…" menu's "Add image")
+  // =========================================================================
+
+  let imagePicker: BranchImagePicker | undefined = $state();
+
+  /**
+   * Stores images straight onto the timeline — not pending, so they show at
+   * once — then refreshes it. A drop and "Add image" both land here, so a
+   * picked image ends up exactly where a dropped one does.
+   */
+  function addTimelineImages(images: { name: string; store: () => Promise<unknown> }[]) {
+    Promise.all(
+      images.map(async ({ name, store }) => {
+        try {
+          await store();
+        } catch (e) {
+          console.error('Failed to add image:', e);
+          // Same shape as the text drop path, so a rejected PDF or oversized
+          // image ("could not open PDF", "media exceeds 10 MB limit") is
+          // not a silent no-op. The extension stays in the name, as in the
+          // composer's attach errors: it is what explains a PDF failure.
+          const reason = e instanceof Error ? e.message : typeof e === 'string' ? e : null;
+          toast.error('Error', {
+            description: `Could not attach "${name}"${reason ? ` \u2014 ${reason}` : ''}`,
+          });
+        }
+      })
+    ).then(() => {
+      loadTimeline();
+    });
+  }
+
+  /** Desktop: files dropped on the card or picked in the open panel. */
+  function addImagePaths(paths: string[]) {
+    addTimelineImages(
+      paths.map((filePath) => ({
+        name: attachBasename(filePath),
+        store: () => commands.createImage(branch.id, branch.projectId, filePath),
+      }))
+    );
+  }
+
+  /** Web: files picked through the file input (on iOS, Photo Library or Files). */
+  function addImageFiles(files: File[]) {
+    addTimelineImages(
+      files.map((file) => ({
+        name: file.name,
+        store: async () =>
+          commands.createImageFromData(
+            branch.id,
+            branch.projectId,
+            file.name,
+            file.type,
+            await fileToBase64(file)
+          ),
+      }))
+    );
+  }
+
   $effect(() => {
     if (!isLocal) return;
 
@@ -1994,6 +2038,7 @@
                 ? (e) => sessionMgr.openNewSession('review', e)
                 : undefined}
               onWriteNote={() => (openWriteNote = { note: null })}
+              onAddImage={() => imagePicker?.open()}
               onPullOrigin={handlePullOrigin}
               onPushOrigin={handlePushOrigin}
               onOpenPushSession={pushSessionId && pushSessionId !== '__pending__'
@@ -2077,6 +2122,15 @@
   {/if}
 </div>
 
+<!-- Outside the "…" menu, whose content unmounts as it closes: the web
+     build's file input has to outlive the tap that opened it. -->
+<BranchImagePicker
+  bind:this={imagePicker}
+  onPickPaths={addImagePaths}
+  onPickFiles={addImageFiles}
+  onError={(e) => notifyError('Could not open the image picker', e)}
+/>
+
 {#if openNote}
   <NoteModal
     open={true}
diff --git a/apps/staged/src/lib/features/branches/BranchImagePicker.svelte b/apps/staged/src/lib/features/branches/BranchImagePicker.svelte
new file mode 100644
index 000000000..91eeec894
--- /dev/null
+++ b/apps/staged/src/lib/features/branches/BranchImagePicker.svelte
@@ -0,0 +1,68 @@
+<!--
+  BranchImagePicker.svelte - The branch card's "Add image" picker
+
+  Call `open()` from the user's tap/click. Desktop (Tauri) shows the native
+  open panel filtered to images and hands back file paths; the web build (iOS
+  Safari) clicks a hidden file input, so iOS presents its own source sheet —
+  Photo Library or Files — and hands back `File`s. Cancelling either picker
+  reports nothing.
+
+  Props:
+    onPickPaths — desktop: the picked file paths
+    onPickFiles — web: the picked files
+    onError     — the desktop panel could not be opened
+-->
+<script lang="ts">
+  import { isTauri } from '../../transport';
+  import { IMAGE_ACCEPT } from '../sessions/attachErrors';
+  import { pickImagePaths } from './branchImagePicker';
+
+  interface Props {
+    onPickPaths: (paths: string[]) => void;
+    onPickFiles: (files: File[]) => void;
+    onError: (error: unknown) => void;
+  }
+
+  let { onPickPaths, onPickFiles, onError }: Props = $props();
+
+  let fileInput: HTMLInputElement | undefined = $state();
+
+  /**
+   * Must run synchronously inside the user's gesture: iOS only opens a file
+   * input's picker while the tap is still being handled.
+   */
+  export function open() {
+    if (!isTauri) {
+      fileInput?.click();
+      return;
+    }
+    pickImagePaths().then((paths) => {
+      if (paths.length > 0) onPickPaths(paths);
+    }, onError);
+  }
+
+  function handleChange(e: Event) {
+    const input = e.currentTarget as HTMLInputElement;
+    const files = Array.from(input.files ?? []);
+    // Cleared so picking the same file again still fires `change`.
+    input.value = '';
+    if (files.length > 0) onPickFiles(files);
+  }
+</script>
+
+{#if !isTauri}
+  <input
+    bind:this={fileInput}
+    type="file"
+    accept={IMAGE_ACCEPT}
+    multiple
+    class="file-input-hidden"
+    onchange={handleChange}
+  />
+{/if}
+
+<style>
+  .file-input-hidden {
+    display: none;
+  }
+</style>
diff --git a/apps/staged/src/lib/features/branches/branchCardHelpers.ts b/apps/staged/src/lib/features/branches/branchCardHelpers.ts
index 1c8b6df9e..326b69c7c 100644
--- a/apps/staged/src/lib/features/branches/branchCardHelpers.ts
+++ b/apps/staged/src/lib/features/branches/branchCardHelpers.ts
@@ -2,7 +2,7 @@ import type { PullState } from '../../stores/pullState.svelte';
 import type { PushState } from '../../stores/pushState.svelte';
 import type { Branch, BranchGitState, PipelineExecution } from '../../types';
 
-const IMAGE_EXTENSIONS = ['.png', '.jpg', '.jpeg', '.gif', '.webp'];
+export const IMAGE_EXTENSIONS = ['.png', '.jpg', '.jpeg', '.gif', '.webp'];
 // Stored through the image attachment store too, as a PDF.
 const PDF_EXTENSIONS = ['.pdf'];
 
diff --git a/apps/staged/src/lib/features/branches/branchImagePicker.test.ts b/apps/staged/src/lib/features/branches/branchImagePicker.test.ts
new file mode 100644
index 000000000..b02a28812
--- /dev/null
+++ b/apps/staged/src/lib/features/branches/branchImagePicker.test.ts
@@ -0,0 +1,49 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+
+const { open } = vi.hoisted(() => ({ open: vi.fn() }));
+vi.mock('@tauri-apps/plugin-dialog', () => ({ open }));
+
+import { IMAGE_PICKER_FILTER, pickImagePaths } from './branchImagePicker';
+import { isImageAttachmentFile, isImageFile } from './branchCardHelpers';
+
+describe('pickImagePaths', () => {
+  beforeEach(() => {
+    open.mockReset();
+  });
+
+  it('opens a multi-select file panel filtered to images', async () => {
+    open.mockResolvedValue([]);
+    await pickImagePaths();
+    expect(open).toHaveBeenCalledWith({
+      title: 'Add image',
+      multiple: true,
+      directory: false,
+      filters: [{ name: 'Images', extensions: ['png', 'jpg', 'jpeg', 'gif', 'webp'] }],
+    });
+  });
+
+  it('returns the picked paths', async () => {
+    open.mockResolvedValue(['/Users/me/shot.png', '/Users/me/photo.jpg']);
+    expect(await pickImagePaths()).toEqual(['/Users/me/shot.png', '/Users/me/photo.jpg']);
+  });
+
+  it('returns no paths when the user cancels', async () => {
+    open.mockResolvedValue(null);
+    expect(await pickImagePaths()).toEqual([]);
+  });
+
+  it('surfaces a panel failure to the caller', async () => {
+    open.mockRejectedValue(new Error('dialog.open not allowed'));
+    await expect(pickImagePaths()).rejects.toThrow('dialog.open not allowed');
+  });
+});
+
+describe('IMAGE_PICKER_FILTER', () => {
+  it('offers exactly the image files a branch-card drop stores', () => {
+    for (const ext of IMAGE_PICKER_FILTER.extensions) {
+      expect(isImageFile(`photo.${ext}`)).toBe(true);
+      expect(isImageAttachmentFile(`photo.${ext}`)).toBe(true);
+    }
+    expect(IMAGE_PICKER_FILTER.extensions).not.toContain('pdf');
+  });
+});
diff --git a/apps/staged/src/lib/features/branches/branchImagePicker.ts b/apps/staged/src/lib/features/branches/branchImagePicker.ts
new file mode 100644
index 000000000..ba9eeb5df
--- /dev/null
+++ b/apps/staged/src/lib/features/branches/branchImagePicker.ts
@@ -0,0 +1,25 @@
+import { IMAGE_EXTENSIONS } from './branchCardHelpers';
+
+/** The open panel's filter: the image formats the image store keeps. */
+export const IMAGE_PICKER_FILTER = {
+  name: 'Images',
+  extensions: IMAGE_EXTENSIONS.map((ext) => ext.slice(1)),
+};
+
+/**
+ * Desktop (Tauri) "Add image": the native open panel, filtered to images.
+ * Resolves to the picked paths — empty when the user cancels.
+ *
+ * The dialog plugin rather than a file `<input>`: wry's open panel ignores
+ * the input's `accept`, so it could not be filtered to images.
+ */
+export async function pickImagePaths(): Promise<string[]> {
+  const { open } = await import('@tauri-apps/plugin-dialog');
+  const paths = await open({
+    title: 'Add image',
+    multiple: true,
+    directory: false,
+    filters: [IMAGE_PICKER_FILTER],
+  });
+  return paths ?? [];
+}
diff --git a/apps/staged/src/lib/features/sessions/ImageAttachment.svelte b/apps/staged/src/lib/features/sessions/ImageAttachment.svelte
index 5f991c221..ddf3aaf61 100644
--- a/apps/staged/src/lib/features/sessions/ImageAttachment.svelte
+++ b/apps/staged/src/lib/features/sessions/ImageAttachment.svelte
@@ -34,6 +34,7 @@
   import type { TextSnippet } from './sessionModalHelpers';
   import AttachmentThumb from './AttachmentThumb.svelte';
   import { localPreview, type AttachmentPreview } from './attachmentPreview';
+  import { fileToBase64 } from './attachmentData';
   import {
     ATTACHMENT_ACCEPT,
     attachErrorReason,
@@ -117,14 +118,7 @@
 
   /** Stores one file, returning the rejection reason or null on success. */
   async function addImageFile(file: File): Promise<string | null> {
-    const buffer = await file.arrayBuffer();
-    const bytes = new Uint8Array(buffer);
-    // Convert to base64 using chunked approach to avoid O(n²) string concatenation
-    const chunks = [];
-    for (let i = 0; i < bytes.length; i += 8192) {
-      chunks.push(String.fromCharCode(...bytes.subarray(i, i + 8192)));
-    }
-    const base64 = btoa(chunks.join(''));
+    const base64 = await fileToBase64(file);
 
     try {
       const image = await createImageFromData(
diff --git a/apps/staged/src/lib/features/sessions/SessionChatPane.svelte b/apps/staged/src/lib/features/sessions/SessionChatPane.svelte
index 745ada78f..bba1615c2 100644
--- a/apps/staged/src/lib/features/sessions/SessionChatPane.svelte
+++ b/apps/staged/src/lib/features/sessions/SessionChatPane.svelte
@@ -130,6 +130,7 @@
   import { hasXmlBlocks, sessionEndMessage, XML_BLOCK_TAGS } from './sessionModalHelpers';
   import AttachmentThumb from './AttachmentThumb.svelte';
   import { localPreview, type AttachmentPreview } from './attachmentPreview';
+  import { fileToBase64 } from './attachmentData';
   import {
     attachBasename,
     attachErrorReason,
@@ -566,13 +567,7 @@
   /** Stores one file, returning the rejection reason or null on success. */
   async function addImageFile(file: File): Promise<string | null> {
     if (!projectId) return null;
-    const buffer = await file.arrayBuffer();
-    const bytes = new Uint8Array(buffer);
-    const chunks: string[] = [];
-    for (let i = 0; i < bytes.length; i += 8192) {
-      chunks.push(String.fromCharCode(...bytes.subarray(i, i + 8192)));
-    }
-    const base64 = btoa(chunks.join(''));
+    const base64 = await fileToBase64(file);
     try {
       const image = await createImageFromData(
         branchId ?? null,
diff --git a/apps/staged/src/lib/features/sessions/attachErrors.test.ts b/apps/staged/src/lib/features/sessions/attachErrors.test.ts
index f834c642b..b75103eea 100644
--- a/apps/staged/src/lib/features/sessions/attachErrors.test.ts
+++ b/apps/staged/src/lib/features/sessions/attachErrors.test.ts
@@ -1,6 +1,7 @@
 import { describe, expect, it } from 'vitest';
 import {
   ATTACHMENT_ACCEPT,
+  IMAGE_ACCEPT,
   attachBasename,
   attachErrorReason,
   formatAttachErrors,
@@ -71,4 +72,11 @@ describe('isAttachableClipboardType', () => {
     expect(ATTACHMENT_ACCEPT.split(',')).toContain('application/pdf');
     expect(ATTACHMENT_ACCEPT.split(',')).toContain('image/png');
   });
+
+  it('offers only image types in the image-only picker', () => {
+    const types = IMAGE_ACCEPT.split(',');
+    expect(types).toEqual(['image/png', 'image/jpeg', 'image/gif', 'image/webp']);
+    expect(types.every(isAttachableClipboardType)).toBe(true);
+    expect(ATTACHMENT_ACCEPT.split(',')).toEqual([...types, 'application/pdf']);
+  });
 });
diff --git a/apps/staged/src/lib/features/sessions/attachErrors.ts b/apps/staged/src/lib/features/sessions/attachErrors.ts
index a6e7e57fa..4fcdbe5f1 100644
--- a/apps/staged/src/lib/features/sessions/attachErrors.ts
+++ b/apps/staged/src/lib/features/sessions/attachErrors.ts
@@ -4,12 +4,19 @@ export interface AttachRejection {
   reason: string;
 }
 
+/**
+ * File-picker `accept` list for the image formats the image store keeps.
+ * Spelled out rather than `image/*` so pickers (the iOS Files browser too)
+ * only offer formats the store accepts — no HEIC, SVG, or TIFF.
+ */
+export const IMAGE_ACCEPT = 'image/png,image/jpeg,image/gif,image/webp';
+
 /**
  * File-picker `accept` list for the image store. A PDF is accepted alongside
  * images: it is stored as a PDF, previewed through a rendering of its first
  * page, and opened in the native PDF viewer.
  */
-export const ATTACHMENT_ACCEPT = 'image/png,image/jpeg,image/gif,image/webp,application/pdf';
+export const ATTACHMENT_ACCEPT = `${IMAGE_ACCEPT},application/pdf`;
 
 /** Whether a pasted clipboard item can be attached through the image store. */
 export function isAttachableClipboardType(type: string): boolean {
diff --git a/apps/staged/src/lib/features/sessions/attachmentData.test.ts b/apps/staged/src/lib/features/sessions/attachmentData.test.ts
new file mode 100644
index 000000000..2aa0cdaab
--- /dev/null
+++ b/apps/staged/src/lib/features/sessions/attachmentData.test.ts
@@ -0,0 +1,23 @@
+import { describe, expect, it } from 'vitest';
+import { fileToBase64 } from './attachmentData';
+
+function decode(base64: string): number[] {
+  return Array.from(atob(base64), (c) => c.charCodeAt(0));
+}
+
+describe('fileToBase64', () => {
+  it('encodes an empty file as an empty string', async () => {
+    expect(await fileToBase64(new Blob([]))).toBe('');
+  });
+
+  it('encodes binary bytes, not text', async () => {
+    const png = new Uint8Array([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a, 0x00, 0xff]);
+    expect(await fileToBase64(new Blob([png]))).toBe('iVBORw0KGgoA/w==');
+  });
+
+  it('round-trips a file spanning several chunks', async () => {
+    const bytes = new Uint8Array(8192 * 2 + 17).map((_, i) => (i * 31) % 256);
+    const encoded = await fileToBase64(new File([bytes], 'photo.jpg', { type: 'image/jpeg' }));
+    expect(decode(encoded)).toEqual(Array.from(bytes));
+  });
+});
diff --git a/apps/staged/src/lib/features/sessions/attachmentData.ts b/apps/staged/src/lib/features/sessions/attachmentData.ts
new file mode 100644
index 000000000..73b469df9
--- /dev/null
+++ b/apps/staged/src/lib/features/sessions/attachmentData.ts
@@ -0,0 +1,13 @@
+/**
+ * A browser `File`'s bytes as base64, the payload `create_image_from_data`
+ * takes. Converted in chunks to avoid O(n²) string concatenation and the
+ * argument-count limit of a single `String.fromCharCode` call.
+ */
+export async function fileToBase64(file: Blob): Promise<string> {
+  const bytes = new Uint8Array(await file.arrayBuffer());
+  const chunks: string[] = [];
+  for (let i = 0; i < bytes.length; i += 8192) {
+    chunks.push(String.fromCharCode(...bytes.subarray(i, i + 8192)));
+  }
+  return btoa(chunks.join(''));
+}
diff --git a/apps/staged/src/lib/features/timeline/BranchTimeline.svelte b/apps/staged/src/lib/features/timeline/BranchTimeline.svelte
index 050b5dd8b..25478e587 100644
--- a/apps/staged/src/lib/features/timeline/BranchTimeline.svelte
+++ b/apps/staged/src/lib/features/timeline/BranchTimeline.svelte
@@ -16,6 +16,7 @@
   import Plus from '@lucide/svelte/icons/plus';
   import MoreHorizontal from '@lucide/svelte/icons/more-horizontal';
   import PencilLine from '@lucide/svelte/icons/pencil-line';
+  import ImagePlus from '@lucide/svelte/icons/image-plus';
   import { isResumableReason } from '../../types';
   import type {
     BranchGitState,
@@ -91,6 +92,8 @@
     onNewReview?: (e?: MouseEvent) => void;
     /** Open the editor for a note the user writes themselves (no agent session). */
     onWriteNote?: () => void;
+    /** Pick image files to add straight to the timeline. */
+    onAddImage?: () => void;
     onPullOrigin?: () => void;
     onPushOrigin?: () => void;
     onRebaseBranch?: () => void;
@@ -176,6 +179,7 @@
     onNewCommit,
     onNewReview,
     onWriteNote,
+    onAddImage,
     onPullOrigin,
     onPushOrigin,
     onRebaseBranch,
@@ -908,7 +912,12 @@
     return actions;
   });
   let actionFooterVisible = $derived(
-    !!onNewNote || !!onNewCommit || !!onNewReview || !!onWriteNote || !!footerActions
+    !!onNewNote ||
+      !!onNewCommit ||
+      !!onNewReview ||
+      !!onWriteNote ||
+      !!onAddImage ||
+      !!footerActions
   );
 
   /** True when the timeline has no content and action buttons should be enlarged. */
@@ -1370,8 +1379,8 @@
             {/if}
             <!-- The menu is the only way to reach an overflowed button, so it
                  renders whenever something overflowed — not just when there is
-                 a "Write note" action to hang off it. -->
-            {#if onWriteNote || overflowMenuActions.length > 0}
+                 a manual action to hang off it. -->
+            {#if onWriteNote || onAddImage || overflowMenuActions.length > 0}
               <DropdownMenu.Root>
                 <DropdownMenu.Trigger
                   class={buttonVariants({ variant: 'outline', size: 'icon-sm' })}
@@ -1383,7 +1392,7 @@
                 <DropdownMenu.Content align="start" sideOffset={4} class="min-w-[180px]">
                   <!-- Overflowed buttons lead, in their footer order, so the menu
                        reads as a continuation of the button row; the manual
-                       "Write note" action sits below them. -->
+                       "Write note" and "Add image" actions sit below them. -->
                   {#each overflowMenuActions as action (action)}
                     {#if action === 'note'}
                       <DropdownMenu.Item
@@ -1410,14 +1419,21 @@
                       </DropdownMenu.Item>
                     {/if}
                   {/each}
+                  {#if (onWriteNote || onAddImage) && overflowMenuActions.length > 0}
+                    <DropdownMenu.Separator />
+                  {/if}
                   {#if onWriteNote}
-                    {#if overflowMenuActions.length > 0}
-                      <DropdownMenu.Separator />
-                    {/if}
                     <DropdownMenu.Item onSelect={() => onWriteNote?.()}>
                       <PencilLine size={14} /> Write note
                     </DropdownMenu.Item>
                   {/if}
+                  {#if onAddImage}
+                    <!-- Called straight from the select so the picker opens
+                         inside the tap, as iOS requires. -->
+                    <DropdownMenu.Item onSelect={() => onAddImage?.()}>
+                      <ImagePlus size={14} /> Add image
+                    </DropdownMenu.Item>
+                  {/if}
                 </DropdownMenu.Content>
               </DropdownMenu.Root>
             {/if}

From d370f72adc6996160384aa631056f75a92ce06d2 Mon Sep 17 00:00:00 2001
From: Matt Toohey <contact@matttoohey.com>
Date: Wed, 21 Oct 2026 11:15:22 -0700
Subject: [PATCH 2/4] fix(staged): add timeline images one at a time, with
 placeholders
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Follow-up to the branch card's "Add image": the review found that
`addTimelineImages`, shared by "Add image" and image drops, started
every store at once, showed nothing until the whole batch had landed,
and toasted once per rejected file.

Images are now stored one at a time, in pick/drop order
(`storeImagesInOrder`, new in timelineImages.ts). On the web build each
store holds the whole file in memory several times over (ArrayBuffer,
binary string, base64, JSON body). One at a time, a 10–20 photo pick in
mobile Safari only holds one file's worth at once, not the whole batch.
It also fixes timeline order: an image's position is the time the
server inserted it, so parallel uploads landed in whichever order they
finished, smallest first. Local `create_image` copies are fast, so
drops lose little.

Each image gets an "adding..." placeholder row as soon as the batch
starts, like the rows text drops already get. Images publish no change
event, so the single refresh after the batch is still what shows them,
and on iOS that can take seconds. The placeholder makes the tap visibly
do something, so the user doesn't pick again and store duplicates. A
rejected image's row goes as soon as it fails. A stored one keeps its
row until the refresh lands, so it never blinks out in between. I
preferred this over refreshing after every store: that would re-fetch
the timeline and re-run the git-state refresh once per image.

To render them, the timeline's `pendingDropNotes` becomes `pendingAdds`.
Each entry carries its row type: `generating-note` for text drops, as
before, and a new `pending-image` TimelineRow type (spinner, image
colours). The `isLocal` gate on the prop is gone. Only local branches
can be dropped on, so the gate never hid anything, but "Add image" is
offered on every branch, and remote branches need the placeholders
too. Keys come from a counter, not the file name, because iOS can hand
back several files all named "image.jpg".

A batch's rejections are reported in one toast through
`formatAttachErrors`, the composer's batch formatter, instead of one
toast per file. This covers drops and picks, since they share the path.

In the composer (`ImageAttachment`, `SessionChatPane`), the
`fileToBase64` read moves inside the `try`. Before, a failed
`file.arrayBuffer()` (e.g. `NotReadableError`) aborted the batch without
setting `attachError` and skipped the input reset, so re-picking the
same file did not fire `change`. Now it counts as that file's rejection.

Tests cover the sequential store order, continuing past rejections with
per-index callbacks, and the one-message batch report.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Signed-off-by: Matt Toohey <contact@matttoohey.com>
---
 .../lib/features/branches/BranchCard.svelte   | 75 ++++++++++-------
 .../features/branches/timelineImages.test.ts  | 80 +++++++++++++++++++
 .../lib/features/branches/timelineImages.ts   | 35 ++++++++
 .../features/sessions/ImageAttachment.svelte  |  3 +-
 .../features/sessions/SessionChatPane.svelte  |  2 +-
 .../features/timeline/BranchTimeline.svelte   | 23 +++---
 .../lib/features/timeline/TimelineRow.svelte  |  4 +-
 7 files changed, 178 insertions(+), 44 deletions(-)
 create mode 100644 apps/staged/src/lib/features/branches/timelineImages.test.ts
 create mode 100644 apps/staged/src/lib/features/branches/timelineImages.ts

diff --git a/apps/staged/src/lib/features/branches/BranchCard.svelte b/apps/staged/src/lib/features/branches/BranchCard.svelte
index 813c318e0..62f456614 100644
--- a/apps/staged/src/lib/features/branches/BranchCard.svelte
+++ b/apps/staged/src/lib/features/branches/BranchCard.svelte
@@ -62,7 +62,7 @@
   import NoteModal from '../notes/NoteModal.svelte';
   import WriteNoteModal from '../notes/WriteNoteModal.svelte';
   import { splitNoteMarkdown } from '../notes/noteMarkdown';
-  import { attachBasename } from '../sessions/attachErrors';
+  import { attachBasename, formatAttachErrors } from '../sessions/attachErrors';
   import { fileToBase64 } from '../sessions/attachmentData';
   import * as AlertDialog from '$lib/components/ui/alert-dialog';
   import { Button } from '$lib/components/ui/button';
@@ -83,6 +83,7 @@
   import BranchCardActionsBar from './BranchCardActionsBar.svelte';
   import BranchCardPrButton from './BranchCardPrButton.svelte';
   import BranchImagePicker from './BranchImagePicker.svelte';
+  import { storeImagesInOrder, type TimelineImageUpload } from './timelineImages';
   import BranchCardSessionManager from './BranchCardSessionManager.svelte';
   import {
     addPendingSession,
@@ -1664,7 +1665,10 @@
   let shouldMountInterior = $state(false);
   let interiorEl: HTMLDivElement | undefined = $state();
 
-  let pendingDropNotes = $state<{ key: string; title: string }[]>([]);
+  /** "adding..." rows for dropped text files and dropped or picked images. */
+  let pendingAdds = $state<
+    { key: string; title: string; type: 'generating-note' | 'pending-image' }[]
+  >([]);
 
   function handleFileDrop(paths: string[]) {
     const textPaths = paths.filter(isMaybeTextFile);
@@ -1674,8 +1678,9 @@
       const placeholders = textPaths.map((filePath) => ({
         key: `drop-${Date.now()}-${filePath}`,
         title: fileNameFromPath(filePath),
+        type: 'generating-note' as const,
       }));
-      pendingDropNotes = [...pendingDropNotes, ...placeholders];
+      pendingAdds = [...pendingAdds, ...placeholders];
 
       Promise.all(
         textPaths.map(async (filePath, i) => {
@@ -1694,7 +1699,7 @@
               description: `Could not read "${fileNameFromPath(filePath)}" \u2014 ${detail}`,
             });
           } finally {
-            pendingDropNotes = pendingDropNotes.filter((p) => p.key !== placeholders[i].key);
+            pendingAdds = pendingAdds.filter((p) => p.key !== placeholders[i].key);
           }
         })
       ).then(() => {
@@ -1712,37 +1717,47 @@
   // =========================================================================
 
   let imagePicker: BranchImagePicker | undefined = $state();
+  let nextPendingImageId = 0;
 
   /**
-   * Stores images straight onto the timeline — not pending, so they show at
-   * once — then refreshes it. A drop and "Add image" both land here, so a
-   * picked image ends up exactly where a dropped one does.
+   * Stores images straight onto the timeline — not pending on a session, so
+   * they show as soon as it refreshes. A drop and "Add image" both land here,
+   * so a picked image ends up exactly where a dropped one does.
+   *
+   * Every image gets an "adding..." row up front: images publish no change
+   * event, so the one refresh after the batch is what shows them, and a
+   * multi-photo upload from iOS can take seconds.
    */
-  function addTimelineImages(images: { name: string; store: () => Promise<unknown> }[]) {
-    Promise.all(
-      images.map(async ({ name, store }) => {
-        try {
-          await store();
-        } catch (e) {
-          console.error('Failed to add image:', e);
-          // Same shape as the text drop path, so a rejected PDF or oversized
-          // image ("could not open PDF", "media exceeds 10 MB limit") is
-          // not a silent no-op. The extension stays in the name, as in the
-          // composer's attach errors: it is what explains a PDF failure.
-          const reason = e instanceof Error ? e.message : typeof e === 'string' ? e : null;
-          toast.error('Error', {
-            description: `Could not attach "${name}"${reason ? ` \u2014 ${reason}` : ''}`,
-          });
-        }
-      })
-    ).then(() => {
-      loadTimeline();
-    });
+  async function addTimelineImages(images: TimelineImageUpload[]) {
+    // Keyed by counter, not name: iOS can hand back several "image.jpg"s.
+    const placeholders = images.map(({ name }) => ({
+      key: `image-${nextPendingImageId++}`,
+      title: name,
+      type: 'pending-image' as const,
+    }));
+    const removePlaceholders = (keys: string[]) => {
+      pendingAdds = pendingAdds.filter((p) => !keys.includes(p.key));
+    };
+    pendingAdds = [...pendingAdds, ...placeholders];
+
+    // A rejected image's row goes at once; a stored one's stays until the
+    // refresh replaces it, so it never blinks out in between.
+    const rejections = await storeImagesInOrder(images, (i) =>
+      removePlaceholders([placeholders[i].key])
+    );
+    // One toast for the batch, like the composer's attach errors, so a
+    // rejected PDF or oversized image is not a silent no-op. The extension
+    // stays in each name: it is what explains a PDF failure.
+    const message = formatAttachErrors(rejections);
+    if (message) toast.error('Error', { description: message });
+
+    await loadTimeline();
+    removePlaceholders(placeholders.map((p) => p.key));
   }
 
   /** Desktop: files dropped on the card or picked in the open panel. */
   function addImagePaths(paths: string[]) {
-    addTimelineImages(
+    void addTimelineImages(
       paths.map((filePath) => ({
         name: attachBasename(filePath),
         store: () => commands.createImage(branch.id, branch.projectId, filePath),
@@ -1752,7 +1767,7 @@
 
   /** Web: files picked through the file input (on iOS, Photo Library or Files). */
   function addImageFiles(files: File[]) {
-    addTimelineImages(
+    void addTimelineImages(
       files.map((file) => ({
         name: file.name,
         store: async () =>
@@ -1981,7 +1996,7 @@
               timeline={timeline ?? emptyTimeline}
               repoDir={branch.worktreePath}
               {hashtagItems}
-              pendingDropNotes={isLocal ? pendingDropNotes : undefined}
+              {pendingAdds}
               pendingItems={getPendingSessionItems(branch.id)}
               {prunedSessionIds}
               {error}
diff --git a/apps/staged/src/lib/features/branches/timelineImages.test.ts b/apps/staged/src/lib/features/branches/timelineImages.test.ts
new file mode 100644
index 000000000..0101f5ec3
--- /dev/null
+++ b/apps/staged/src/lib/features/branches/timelineImages.test.ts
@@ -0,0 +1,80 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import { formatAttachErrors } from '../sessions/attachErrors';
+import { storeImagesInOrder } from './timelineImages';
+
+function deferred() {
+  let resolve!: () => void;
+  const promise = new Promise<void>((r) => (resolve = r));
+  return { promise, resolve };
+}
+
+describe('storeImagesInOrder', () => {
+  beforeEach(() => {
+    vi.spyOn(console, 'error').mockImplementation(() => {});
+  });
+
+  afterEach(() => {
+    vi.restoreAllMocks();
+  });
+
+  it('starts each store only after the previous one settles', async () => {
+    const first = deferred();
+    const second = deferred();
+    const storeFirst = vi.fn(() => first.promise);
+    const storeSecond = vi.fn(() => second.promise);
+
+    const done = storeImagesInOrder([
+      { name: 'a.png', store: storeFirst },
+      { name: 'b.png', store: storeSecond },
+    ]);
+
+    await vi.waitFor(() => expect(storeFirst).toHaveBeenCalled());
+    expect(storeSecond).not.toHaveBeenCalled();
+
+    first.resolve();
+    await vi.waitFor(() => expect(storeSecond).toHaveBeenCalled());
+
+    second.resolve();
+    expect(await done).toEqual([]);
+  });
+
+  it('keeps going past a rejection and returns every rejection in order', async () => {
+    const order: string[] = [];
+    const onRejected = vi.fn();
+    const store = (name: string, error?: unknown) => async () => {
+      order.push(name);
+      if (error !== undefined) throw error;
+    };
+
+    const rejections = await storeImagesInOrder(
+      [
+        { name: 'big.png', store: store('big.png', new Error('media exceeds 10 MB limit')) },
+        { name: 'ok.png', store: store('ok.png') },
+        { name: 'bad.gif', store: store('bad.gif', 'unsupported image format') },
+      ],
+      onRejected
+    );
+
+    expect(order).toEqual(['big.png', 'ok.png', 'bad.gif']);
+    expect(rejections).toEqual([
+      { name: 'big.png', reason: 'media exceeds 10 MB limit' },
+      { name: 'bad.gif', reason: 'unsupported image format' },
+    ]);
+    expect(onRejected.mock.calls).toEqual([[0], [2]]);
+  });
+
+  it('reports a batch of rejections as one message', async () => {
+    const tooBig = async () => {
+      throw new Error('media exceeds 10 MB limit');
+    };
+
+    const rejections = await storeImagesInOrder([
+      { name: 'one.jpg', store: tooBig },
+      { name: 'two.jpg', store: tooBig },
+    ]);
+
+    expect(formatAttachErrors(rejections)).toBe(
+      'Could not attach 2 files (one.jpg, two.jpg): media exceeds 10 MB limit'
+    );
+  });
+});
diff --git a/apps/staged/src/lib/features/branches/timelineImages.ts b/apps/staged/src/lib/features/branches/timelineImages.ts
new file mode 100644
index 000000000..229997706
--- /dev/null
+++ b/apps/staged/src/lib/features/branches/timelineImages.ts
@@ -0,0 +1,35 @@
+import { attachErrorReason, type AttachRejection } from '../sessions/attachErrors';
+
+/** One image headed straight onto a branch timeline (dropped or picked). */
+export interface TimelineImageUpload {
+  name: string;
+  store: () => Promise<unknown>;
+}
+
+/**
+ * Stores a batch of images one at a time, in the order given. A web store
+ * holds the whole file in memory several times over (bytes, base64, request
+ * body), so going one by one keeps a large Photo Library pick in mobile
+ * Safari to one file's worth. It also keeps the batch in pick order: an
+ * image's timeline position is when the store inserted it.
+ *
+ * A rejection does not stop the batch. Each is reported through `onRejected`
+ * as it happens and returned with the rest, so the caller can report the
+ * whole batch in one message.
+ */
+export async function storeImagesInOrder(
+  images: TimelineImageUpload[],
+  onRejected?: (index: number) => void
+): Promise<AttachRejection[]> {
+  const rejections: AttachRejection[] = [];
+  for (const [index, { name, store }] of images.entries()) {
+    try {
+      await store();
+    } catch (e) {
+      console.error('Failed to add image:', e);
+      rejections.push({ name, reason: attachErrorReason(e) });
+      onRejected?.(index);
+    }
+  }
+  return rejections;
+}
diff --git a/apps/staged/src/lib/features/sessions/ImageAttachment.svelte b/apps/staged/src/lib/features/sessions/ImageAttachment.svelte
index ddf3aaf61..4f9bb7db1 100644
--- a/apps/staged/src/lib/features/sessions/ImageAttachment.svelte
+++ b/apps/staged/src/lib/features/sessions/ImageAttachment.svelte
@@ -118,9 +118,8 @@
 
   /** Stores one file, returning the rejection reason or null on success. */
   async function addImageFile(file: File): Promise<string | null> {
-    const base64 = await fileToBase64(file);
-
     try {
+      const base64 = await fileToBase64(file);
       const image = await createImageFromData(
         branchId,
         projectId,
diff --git a/apps/staged/src/lib/features/sessions/SessionChatPane.svelte b/apps/staged/src/lib/features/sessions/SessionChatPane.svelte
index bba1615c2..6b1e6585d 100644
--- a/apps/staged/src/lib/features/sessions/SessionChatPane.svelte
+++ b/apps/staged/src/lib/features/sessions/SessionChatPane.svelte
@@ -567,8 +567,8 @@
   /** Stores one file, returning the rejection reason or null on success. */
   async function addImageFile(file: File): Promise<string | null> {
     if (!projectId) return null;
-    const base64 = await fileToBase64(file);
     try {
+      const base64 = await fileToBase64(file);
       const image = await createImageFromData(
         branchId ?? null,
         projectId,
diff --git a/apps/staged/src/lib/features/timeline/BranchTimeline.svelte b/apps/staged/src/lib/features/timeline/BranchTimeline.svelte
index 25478e587..72d53d00b 100644
--- a/apps/staged/src/lib/features/timeline/BranchTimeline.svelte
+++ b/apps/staged/src/lib/features/timeline/BranchTimeline.svelte
@@ -65,8 +65,11 @@
     timeline: BranchTimelineData;
     /** Repo base directory — tool call paths within it are shown as relative in hints. */
     repoDir?: string | null;
-    /** Placeholder items for notes being created from drag-and-drop. */
-    pendingDropNotes?: { key: string; title: string }[];
+    /**
+     * Placeholder rows for items the user is adding directly: notes from
+     * dropped text files, and dropped or picked images.
+     */
+    pendingAdds?: { key: string; title: string; type: 'generating-note' | 'pending-image' }[];
     /** Placeholder items for newly started sessions before timeline persistence catches up. */
     pendingItems?: PendingItem[];
     /** Session IDs that were just pruned from pendingItems because the real timeline item arrived. */
@@ -159,7 +162,7 @@
   let {
     timeline,
     repoDir,
-    pendingDropNotes = [],
+    pendingAdds = [],
     pendingItems = [],
     prunedSessionIds = new Set(),
     deletingItems = [],
@@ -922,7 +925,7 @@
 
   /** True when the timeline has no content and action buttons should be enlarged. */
   let actionButtonsEnlarged = $derived(
-    items.length === 0 && pendingDropNotes.length === 0 && pendingItems.length === 0
+    items.length === 0 && pendingAdds.length === 0 && pendingItems.length === 0
   );
 
   // ── Footer overflow ───────────────────────────────────────────────────
@@ -1099,7 +1102,7 @@
   }
 </script>
 
-{#if items.length === 0 && !actionFooterVisible && pendingDropNotes.length === 0 && pendingItems.length === 0}
+{#if items.length === 0 && !actionFooterVisible && pendingAdds.length === 0 && pendingItems.length === 0}
   <p class="no-items">No commits or notes yet</p>
 {:else}
   <!-- Unified timeline (vertical) -->
@@ -1138,7 +1141,7 @@
             discardChangesDisabledReason={item.discardChangesDisabledReason}
             deleting={item.deleting}
             isLast={index === normalItems.length - 1 &&
-              pendingDropNotes.length === 0 &&
+              pendingAdds.length === 0 &&
               pendingItems.length === 0 &&
               gitFooterItems.length === 0 &&
               !error &&
@@ -1158,13 +1161,13 @@
           />
         </div>
       {/each}
-      {#each pendingDropNotes as drop, index (drop.key)}
+      {#each pendingAdds as add, index (add.key)}
         <div transition:slide={{ duration: 200 }}>
           <TimelineRow
-            type="generating-note"
-            title={drop.title}
+            type={add.type}
+            title={add.title}
             secondaryMeta="adding..."
-            isLast={index === pendingDropNotes.length - 1 &&
+            isLast={index === pendingAdds.length - 1 &&
               pendingItems.length === 0 &&
               gitFooterItems.length === 0 &&
               !error &&
diff --git a/apps/staged/src/lib/features/timeline/TimelineRow.svelte b/apps/staged/src/lib/features/timeline/TimelineRow.svelte
index d0db2defe..480da2b47 100644
--- a/apps/staged/src/lib/features/timeline/TimelineRow.svelte
+++ b/apps/staged/src/lib/features/timeline/TimelineRow.svelte
@@ -34,6 +34,7 @@
     | 'queued-review'
     | 'failed-review'
     | 'image'
+    | 'pending-image'
     | 'git-info'
     | 'git-warning'
     | 'git-merge'
@@ -152,7 +153,7 @@
       type === 'queued-review' ||
       type === 'failed-review'
   );
-  let isImage = $derived(type === 'image');
+  let isImage = $derived(type === 'image' || type === 'pending-image');
   let isGitState = $derived(
     type === 'git-info' ||
       type === 'git-warning' ||
@@ -171,6 +172,7 @@
       type === 'pending-commit' ||
       type === 'generating-note' ||
       type === 'generating-review' ||
+      type === 'pending-image' ||
       type === 'provisioning'
   );
   let isFailed = $derived(

From 2da771b330b983d0bb3410b5c3abcddc1b285eff Mon Sep 17 00:00:00 2001
From: Matt Toohey <contact@matttoohey.com>
Date: Wed, 21 Oct 2026 11:28:51 -0700
Subject: [PATCH 3/4] fix(staged): swap each image placeholder for its row as
 it lands

Follow-up to d370f72 ("add timeline images one at a time, with
placeholders"). That commit's design rested on a wrong premise: it said
images publish no change event, so the single refresh after a batch was
what showed them. They do publish one. `Store::create_image` publishes
`StoreChange::Branch` for any image with a branch and no session, and
the card's `timeline-invalidated` handler force-reloads on it, on
desktop and over `/api/events` on the web. So each stored image already
showed as a real row shortly after its own store, while its "adding..."
placeholder stayed at the bottom until the whole batch finished. In a
10-photo iOS pick, every finished photo showed twice for the rest of
the upload. The commit's trade-off was wrong too: it said it avoided a
timeline and git-state refresh per image, but those refreshes were
already happening through the change feed.

Each placeholder now records its stored `Image` id (both `createImage`
and `createImageFromData` already resolve to it). `pruneLandedImages`
drops placeholders whose id is already in `timeline.images`. It runs
wherever the card applies a timeline, next to
`prunePendingSessionItems`, through a shared `prunePlaceholders`. So the
reload that brings an image in also removes its placeholder, in the same
update. It also runs once when the id is recorded, in case that reload
landed first. As with pruned session placeholders, the timeline skips
the slide-out for a row that leaves because its image arrived, so the
image replaces it in place. Rejected images and finished text drops
still slide out. `pendingAdds` moves above the card's synchronous cache
hydration, which now prunes it.

The batch-end removal stays as a fallback for an image whose row never
arrives, but it no longer races. A load that a newer one supersedes
returns early (the `timelineLoadVersion` check), so the change-feed
reload for the last image could make the batch's `await loadTimeline()`
return before anything was shown. The placeholders were then removed
before the newer load landed, so they blinked out. `loadTimeline` now
records its newest run, and the batch waits on `timelineLoadsSettled`,
which follows superseding loads until the last one has settled. Only
then does it drop what's left.

Batches are also serialized per card. `createImageStoreQueue` chains
each batch's `storeImagesInOrder` after the previous one. Before, a pick
or drop made during an upload stored alongside it, so mobile Safari held
two files' worth of base64 at once and the batches interleaved on the
timeline. A queued batch's placeholders still appear as soon as it's
picked. Only the storing is chained, so one batch's final refresh
doesn't hold up the next batch.

`storeImagesInOrder` takes `{ onStored, onRejected }` handlers, and
`onStored` gets the stored image. Tests cover pruning (landed, stored
but not landed, not yet stored, and returning the same array when
nothing changed), cross-batch ordering, per-batch rejections, and the
queue continuing past a failed batch.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Signed-off-by: Matt Toohey <contact@matttoohey.com>
---
 .../lib/features/branches/BranchCard.svelte   |  92 +++++++++---
 .../features/branches/timelineImages.test.ts  | 142 +++++++++++++++++-
 .../lib/features/branches/timelineImages.ts   |  50 +++++-
 .../features/timeline/BranchTimeline.svelte   |  24 ++-
 4 files changed, 275 insertions(+), 33 deletions(-)

diff --git a/apps/staged/src/lib/features/branches/BranchCard.svelte b/apps/staged/src/lib/features/branches/BranchCard.svelte
index 62f456614..9a90c3a07 100644
--- a/apps/staged/src/lib/features/branches/BranchCard.svelte
+++ b/apps/staged/src/lib/features/branches/BranchCard.svelte
@@ -83,7 +83,11 @@
   import BranchCardActionsBar from './BranchCardActionsBar.svelte';
   import BranchCardPrButton from './BranchCardPrButton.svelte';
   import BranchImagePicker from './BranchImagePicker.svelte';
-  import { storeImagesInOrder, type TimelineImageUpload } from './timelineImages';
+  import {
+    createImageStoreQueue,
+    pruneLandedImages,
+    type TimelineImageUpload,
+  } from './timelineImages';
   import BranchCardSessionManager from './BranchCardSessionManager.svelte';
   import {
     addPendingSession,
@@ -554,6 +558,21 @@
   /** Session IDs that were just pruned from pendingItems because the real timeline item arrived. */
   let prunedSessionIds = $state<Set<string>>(new Set());
 
+  /**
+   * "adding..." rows for dropped text files and dropped or picked images. An
+   * image's row gets `imageId` once it is stored. Declared before the cache
+   * hydration below, which prunes it.
+   */
+  let pendingAdds = $state<
+    { key: string; title: string; type: 'generating-note' | 'pending-image'; imageId?: string }[]
+  >([]);
+
+  /** Drops the placeholders whose real rows are in `next`, in the same update. */
+  function prunePlaceholders(next: BranchTimelineData) {
+    prunedSessionIds = prunePendingSessionItems(branch.id, next);
+    pendingAdds = pruneLandedImages(pendingAdds, next);
+  }
+
   // Confirm delete dialog
   let confirmDelete = $state<{
     title: string;
@@ -575,6 +594,8 @@
 
   let requestedTimelineKey: string | null = null;
   let timelineLoadVersion = 0;
+  /** The newest `loadTimeline()` run, which `timelineLoadsSettled` follows. */
+  let latestTimelineLoad: Promise<void> = Promise.resolve();
   let revalidationVersion = 0;
   let gitRefreshVersion = 0;
 
@@ -621,7 +642,7 @@
     timeline = cached;
     loadedTimelineKey = timelineKey;
     loading = false;
-    prunedSessionIds = prunePendingSessionItems(branch.id, cached);
+    prunePlaceholders(cached);
     if (fresh) {
       const version = ++revalidationVersion;
       fresh
@@ -632,7 +653,7 @@
           error = null;
           timeline = next;
           loadedTimelineKey = timelineKey;
-          prunedSessionIds = prunePendingSessionItems(branch.id, next);
+          prunePlaceholders(next);
         })
         .catch((e) => {
           if (version !== revalidationVersion || branchTimelineReadyKey(branch) !== timelineKey) {
@@ -819,7 +840,27 @@
     return () => window.removeEventListener('cache-stale', handler);
   });
 
-  async function loadTimeline({
+  function loadTimeline(options?: { timelineKey?: string | null; force?: boolean }) {
+    const load = runTimelineLoad(options);
+    latestTimelineLoad = load;
+    return load;
+  }
+
+  /**
+   * Resolves once the newest timeline load has settled. A load that a newer
+   * one supersedes returns early, before anything it fetched is shown, so
+   * awaiting a `loadTimeline()` does not mean its rows are on screen. This
+   * follows on to whichever load started last.
+   */
+  async function timelineLoadsSettled() {
+    let load: Promise<void>;
+    do {
+      load = latestTimelineLoad;
+      await load;
+    } while (load !== latestTimelineLoad);
+  }
+
+  async function runTimelineLoad({
     timelineKey = branchTimelineReadyKey(branch),
     force = false,
   }: { timelineKey?: string | null; force?: boolean } = {}) {
@@ -853,7 +894,7 @@
       if (!isCurrentTimelineLoad(loadVersion, timelineKey)) return;
       timeline = nextTimeline;
       loadedTimelineKey = timelineKey;
-      prunedSessionIds = prunePendingSessionItems(branch.id, nextTimeline);
+      prunePlaceholders(nextTimeline);
     } catch (e) {
       if (!isCurrentTimelineLoad(loadVersion, timelineKey)) return;
       error = e instanceof Error ? e.message : String(e);
@@ -1665,11 +1706,6 @@
   let shouldMountInterior = $state(false);
   let interiorEl: HTMLDivElement | undefined = $state();
 
-  /** "adding..." rows for dropped text files and dropped or picked images. */
-  let pendingAdds = $state<
-    { key: string; title: string; type: 'generating-note' | 'pending-image' }[]
-  >([]);
-
   function handleFileDrop(paths: string[]) {
     const textPaths = paths.filter(isMaybeTextFile);
     const imagePaths = paths.filter(isImageAttachmentFile);
@@ -1718,15 +1754,19 @@
 
   let imagePicker: BranchImagePicker | undefined = $state();
   let nextPendingImageId = 0;
+  /** One queue per card, so batches also store one file at a time between them. */
+  const storeImages = createImageStoreQueue();
 
   /**
-   * Stores images straight onto the timeline — not pending on a session, so
-   * they show as soon as it refreshes. A drop and "Add image" both land here,
-   * so a picked image ends up exactly where a dropped one does.
+   * Stores images straight onto the timeline — not pending on a session. A
+   * drop and "Add image" both land here, so a picked image ends up exactly
+   * where a dropped one does.
    *
-   * Every image gets an "adding..." row up front: images publish no change
-   * event, so the one refresh after the batch is what shows them, and a
-   * multi-photo upload from iOS can take seconds.
+   * Every image gets an "adding..." row up front, even when its batch queues
+   * behind another, since a multi-photo upload from iOS can take seconds.
+   * Each store publishes a branch change, and the reload it triggers brings in
+   * that image's real row. The placeholder carries the stored image's ID, so
+   * `prunePlaceholders` swaps one for the other in that reload's update.
    */
   async function addTimelineImages(images: TimelineImageUpload[]) {
     // Keyed by counter, not name: iOS can hand back several "image.jpg"s.
@@ -1740,18 +1780,28 @@
     };
     pendingAdds = [...pendingAdds, ...placeholders];
 
-    // A rejected image's row goes at once; a stored one's stays until the
-    // refresh replaces it, so it never blinks out in between.
-    const rejections = await storeImagesInOrder(images, (i) =>
-      removePlaceholders([placeholders[i].key])
-    );
+    const rejections = await storeImages(images, {
+      onStored: (i, image) => {
+        const { key } = placeholders[i];
+        pendingAdds = pendingAdds.map((p) => (p.key === key ? { ...p, imageId: image.id } : p));
+        // In case the change-feed reload landed before the store returned.
+        if (timeline) pendingAdds = pruneLandedImages(pendingAdds, timeline);
+      },
+      onRejected: (i) => removePlaceholders([placeholders[i].key]),
+    });
     // One toast for the batch, like the composer's attach errors, so a
     // rejected PDF or oversized image is not a silent no-op. The extension
     // stays in each name: it is what explains a PDF failure.
     const message = formatAttachErrors(rejections);
     if (message) toast.error('Error', { description: message });
 
+    // Fallback for a stored image whose row never arrives (the refresh
+    // failed, or it was deleted meanwhile), so its spinner can't stay forever.
+    // Wait for the newest load, not just this one: a change-feed reload that
+    // supersedes it makes it return early, and dropping the rows before that
+    // reload lands would blink them out.
     await loadTimeline();
+    await timelineLoadsSettled();
     removePlaceholders(placeholders.map((p) => p.key));
   }
 
diff --git a/apps/staged/src/lib/features/branches/timelineImages.test.ts b/apps/staged/src/lib/features/branches/timelineImages.test.ts
index 0101f5ec3..4c488ba33 100644
--- a/apps/staged/src/lib/features/branches/timelineImages.test.ts
+++ b/apps/staged/src/lib/features/branches/timelineImages.test.ts
@@ -1,6 +1,7 @@
 import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import type { ImageTimelineItem } from '../../types';
 import { formatAttachErrors } from '../sessions/attachErrors';
-import { storeImagesInOrder } from './timelineImages';
+import { createImageStoreQueue, pruneLandedImages, storeImagesInOrder } from './timelineImages';
 
 function deferred() {
   let resolve!: () => void;
@@ -8,6 +9,16 @@ function deferred() {
   return { promise, resolve };
 }
 
+/** A store that waits for `gate` (if any), logs `id` to `order`, and returns it. */
+function storeAs(id: string, order: string[], gate?: Promise<void>) {
+  return vi.fn(async () => {
+    order.push(`start ${id}`);
+    await gate;
+    order.push(`end ${id}`);
+    return { id };
+  });
+}
+
 describe('storeImagesInOrder', () => {
   beforeEach(() => {
     vi.spyOn(console, 'error').mockImplementation(() => {});
@@ -18,10 +29,11 @@ describe('storeImagesInOrder', () => {
   });
 
   it('starts each store only after the previous one settles', async () => {
+    const order: string[] = [];
     const first = deferred();
     const second = deferred();
-    const storeFirst = vi.fn(() => first.promise);
-    const storeSecond = vi.fn(() => second.promise);
+    const storeFirst = storeAs('a', order, first.promise);
+    const storeSecond = storeAs('b', order, second.promise);
 
     const done = storeImagesInOrder([
       { name: 'a.png', store: storeFirst },
@@ -38,12 +50,14 @@ describe('storeImagesInOrder', () => {
     expect(await done).toEqual([]);
   });
 
-  it('keeps going past a rejection and returns every rejection in order', async () => {
+  it('keeps going past a rejection, reporting each image by index', async () => {
     const order: string[] = [];
+    const onStored = vi.fn();
     const onRejected = vi.fn();
     const store = (name: string, error?: unknown) => async () => {
       order.push(name);
       if (error !== undefined) throw error;
+      return { id: `id-${name}` };
     };
 
     const rejections = await storeImagesInOrder(
@@ -52,7 +66,7 @@ describe('storeImagesInOrder', () => {
         { name: 'ok.png', store: store('ok.png') },
         { name: 'bad.gif', store: store('bad.gif', 'unsupported image format') },
       ],
-      onRejected
+      { onStored, onRejected }
     );
 
     expect(order).toEqual(['big.png', 'ok.png', 'bad.gif']);
@@ -60,11 +74,12 @@ describe('storeImagesInOrder', () => {
       { name: 'big.png', reason: 'media exceeds 10 MB limit' },
       { name: 'bad.gif', reason: 'unsupported image format' },
     ]);
+    expect(onStored.mock.calls).toEqual([[1, { id: 'id-ok.png' }]]);
     expect(onRejected.mock.calls).toEqual([[0], [2]]);
   });
 
   it('reports a batch of rejections as one message', async () => {
-    const tooBig = async () => {
+    const tooBig = async (): Promise<{ id: string }> => {
       throw new Error('media exceeds 10 MB limit');
     };
 
@@ -78,3 +93,118 @@ describe('storeImagesInOrder', () => {
     );
   });
 });
+
+describe('createImageStoreQueue', () => {
+  beforeEach(() => {
+    vi.spyOn(console, 'error').mockImplementation(() => {});
+  });
+
+  afterEach(() => {
+    vi.restoreAllMocks();
+  });
+
+  it('holds a second batch until the first has stored every image', async () => {
+    const order: string[] = [];
+    const a1 = deferred();
+    const a2 = deferred();
+    const storeImages = createImageStoreQueue();
+
+    const firstBatch = storeImages([
+      { name: 'a1.jpg', store: storeAs('a1', order, a1.promise) },
+      { name: 'a2.jpg', store: storeAs('a2', order, a2.promise) },
+    ]);
+    const storeB1 = storeAs('b1', order);
+    const secondBatch = storeImages([
+      { name: 'b1.jpg', store: storeB1 },
+      { name: 'b2.jpg', store: storeAs('b2', order) },
+    ]);
+
+    a1.resolve();
+    await vi.waitFor(() => expect(order).toContain('start a2'));
+    expect(storeB1).not.toHaveBeenCalled();
+
+    a2.resolve();
+    await Promise.all([firstBatch, secondBatch]);
+    expect(order).toEqual([
+      'start a1',
+      'end a1',
+      'start a2',
+      'end a2',
+      'start b1',
+      'end b1',
+      'start b2',
+      'end b2',
+    ]);
+  });
+
+  it('returns each batch its own rejections, and a rejection does not stall the queue', async () => {
+    const storeImages = createImageStoreQueue();
+    const rejected = async (): Promise<{ id: string }> => {
+      throw new Error('could not open PDF');
+    };
+
+    const [first, second] = await Promise.all([
+      storeImages([{ name: 'scan.pdf', store: rejected }]),
+      storeImages([{ name: 'ok.png', store: async () => ({ id: 'ok' }) }]),
+    ]);
+
+    expect(first).toEqual([{ name: 'scan.pdf', reason: 'could not open PDF' }]);
+    expect(second).toEqual([]);
+  });
+
+  it('keeps running batches after a handler throws', async () => {
+    const storeImages = createImageStoreQueue();
+    const store = async () => ({ id: 'x' });
+
+    const first = storeImages([{ name: 'a.png', store }], {
+      onStored: () => {
+        throw new Error('handler bug');
+      },
+    });
+    const second = storeImages([{ name: 'b.png', store }]);
+
+    await expect(first).rejects.toThrow('handler bug');
+    expect(await second).toEqual([]);
+  });
+});
+
+describe('pruneLandedImages', () => {
+  function timelineWith(...ids: string[]) {
+    return {
+      images: ids.map((id): ImageTimelineItem => ({
+        id,
+        filename: `${id}.png`,
+        mimeType: 'image/png',
+        sizeBytes: 1,
+        sessionId: null,
+        sessionStatus: null,
+        completionReason: null,
+        createdAt: 0,
+      })),
+    };
+  }
+
+  it('drops rows whose stored image is on the timeline', () => {
+    const adds = [
+      { key: 'note', imageId: undefined },
+      { key: 'landed', imageId: 'img-1' },
+      { key: 'stored', imageId: 'img-2' },
+      { key: 'storing' },
+    ];
+
+    expect(pruneLandedImages(adds, timelineWith('img-1', 'other')).map((a) => a.key)).toEqual([
+      'note',
+      'stored',
+      'storing',
+    ]);
+  });
+
+  it('returns the same rows when nothing has landed', () => {
+    const adds = [{ key: 'stored', imageId: 'img-2' }, { key: 'storing' }];
+
+    const unstored = [{ key: 'storing', imageId: undefined }];
+
+    expect(pruneLandedImages(adds, timelineWith('img-1'))).toBe(adds);
+    expect(pruneLandedImages(unstored, timelineWith())).toBe(unstored);
+  });
+});
diff --git a/apps/staged/src/lib/features/branches/timelineImages.ts b/apps/staged/src/lib/features/branches/timelineImages.ts
index 229997706..38e5684f6 100644
--- a/apps/staged/src/lib/features/branches/timelineImages.ts
+++ b/apps/staged/src/lib/features/branches/timelineImages.ts
@@ -1,9 +1,17 @@
+import type { BranchTimeline, Image } from '../../types';
 import { attachErrorReason, type AttachRejection } from '../sessions/attachErrors';
 
 /** One image headed straight onto a branch timeline (dropped or picked). */
 export interface TimelineImageUpload {
   name: string;
-  store: () => Promise<unknown>;
+  store: () => Promise<Pick<Image, 'id'>>;
+}
+
+export interface StoreImageHandlers {
+  /** The image at `index` was stored as `image`. */
+  onStored?: (index: number, image: Pick<Image, 'id'>) => void;
+  /** The image at `index` was rejected; its reason is in the returned list. */
+  onRejected?: (index: number) => void;
 }
 
 /**
@@ -19,17 +27,53 @@ export interface TimelineImageUpload {
  */
 export async function storeImagesInOrder(
   images: TimelineImageUpload[],
-  onRejected?: (index: number) => void
+  { onStored, onRejected }: StoreImageHandlers = {}
 ): Promise<AttachRejection[]> {
   const rejections: AttachRejection[] = [];
   for (const [index, { name, store }] of images.entries()) {
+    let image: Pick<Image, 'id'>;
     try {
-      await store();
+      image = await store();
     } catch (e) {
       console.error('Failed to add image:', e);
       rejections.push({ name, reason: attachErrorReason(e) });
       onRejected?.(index);
+      continue;
     }
+    onStored?.(index, image);
   }
   return rejections;
 }
+
+/**
+ * Returns a `storeImagesInOrder` that runs each batch only after every earlier
+ * one has finished. A pick or drop made while a batch is still storing then
+ * waits its turn, so across batches too only one file is stored at a time,
+ * and batches land on the timeline in the order they were made instead of
+ * interleaving.
+ */
+export function createImageStoreQueue() {
+  let tail: Promise<unknown> = Promise.resolve();
+  return (images: TimelineImageUpload[], handlers?: StoreImageHandlers) => {
+    const batch = tail.then(() => storeImagesInOrder(images, handlers));
+    tail = batch.catch(() => {});
+    return batch;
+  };
+}
+
+/**
+ * Drops the "adding..." rows whose stored image is already in `timeline`.
+ * Every stored image publishes a branch change, and the reload it triggers
+ * brings in the image's real row; pruning in that same update swaps the row
+ * for the image instead of showing both. Returns `adds` itself when nothing
+ * has landed.
+ */
+export function pruneLandedImages<T extends { imageId?: string }>(
+  adds: T[],
+  timeline: Pick<BranchTimeline, 'images'>
+): T[] {
+  if (!adds.some((add) => add.imageId)) return adds;
+  const landed = new Set(timeline.images.map((image) => image.id));
+  const next = adds.filter((add) => !add.imageId || !landed.has(add.imageId));
+  return next.length === adds.length ? adds : next;
+}
diff --git a/apps/staged/src/lib/features/timeline/BranchTimeline.svelte b/apps/staged/src/lib/features/timeline/BranchTimeline.svelte
index 72d53d00b..40c91035d 100644
--- a/apps/staged/src/lib/features/timeline/BranchTimeline.svelte
+++ b/apps/staged/src/lib/features/timeline/BranchTimeline.svelte
@@ -67,9 +67,15 @@
     repoDir?: string | null;
     /**
      * Placeholder rows for items the user is adding directly: notes from
-     * dropped text files, and dropped or picked images.
+     * dropped text files, and dropped or picked images (with `imageId` once
+     * stored).
      */
-    pendingAdds?: { key: string; title: string; type: 'generating-note' | 'pending-image' }[];
+    pendingAdds?: {
+      key: string;
+      title: string;
+      type: 'generating-note' | 'pending-image';
+      imageId?: string;
+    }[];
     /** Placeholder items for newly started sessions before timeline persistence catches up. */
     pendingItems?: PendingItem[];
     /** Session IDs that were just pruned from pendingItems because the real timeline item arrived. */
@@ -240,6 +246,18 @@
     return slide(node, { duration: 200 });
   }
 
+  /**
+   * The same for an "adding..." image row: when it leaves because its image
+   * is now on the timeline, the image row replaces it in place. Rows that go
+   * for any other reason (a rejected image, a finished text drop) slide out.
+   */
+  function maybeSlideAdd(node: Element, params: { imageId?: string }) {
+    if (params.imageId && timeline.images.some((image) => image.id === params.imageId)) {
+      return { duration: 0 };
+    }
+    return slide(node, { duration: 200 });
+  }
+
   let liveSessionHints = $state<Record<string, string>>({});
   let liveSessionTitles = $state<Record<string, string>>({});
   const liveSessionHintPoller = createLiveSessionHints(
@@ -1162,7 +1180,7 @@
         </div>
       {/each}
       {#each pendingAdds as add, index (add.key)}
-        <div transition:slide={{ duration: 200 }}>
+        <div in:slide={{ duration: 200 }} out:maybeSlideAdd={{ imageId: add.imageId }}>
           <TimelineRow
             type={add.type}
             title={add.title}

From 4e5afedc571d9dcc49b73e2156903e6365a4ba40 Mon Sep 17 00:00:00 2001
From: Matt Toohey <contact@matttoohey.com>
Date: Wed, 21 Oct 2026 11:37:42 -0700
Subject: [PATCH 4/4] refactor(staged): harden and share the timeline image
 store queue

Follow-up to 2da771b ("swap each image placeholder for its row as it
lands"), applying that commit's four review suggestions. Behaviour is
otherwise unchanged.

`addTimelineImages` wraps the store and settle sequence in
try/catch/finally. The queue already survived a batch that rejected
(a handler throwing), but the card did not: the `await` threw past the
toast and the batch-end removal. Every placeholder from the failing
image on then spun forever, and because callers `void` the call, the
rejection went unhandled. The placeholders are now removed in `finally`,
and the error is caught and shown through the card's `notifyError`.

The fallback's `await loadTimeline()` is now
`void loadTimeline(); await timelineLoadsSettled();`. `loadTimeline`
records its run as `latestTimelineLoad` synchronously, and the settle
wait's first pass awaits that run or a newer one, so the extra await
added nothing. The fallback relies on the settle wait, and the code now
says so.

The image store queue is module-level. `storeTimelineImages`, one
`createImageStoreQueue()` exported from timelineImages.ts, replaces the
per-card instance. The one-file-at-a-time guarantee used to end when a
card remounted mid-upload, for example on a project switch. The old
instance kept uploading, and a pick on the new one started a second,
parallel queue, so mobile Safari held two files' base64 at once. The
shared queue keeps the guarantee across remounts and across cards.

timelineImages.ts exports a `PendingAdd` type for the "adding..." rows.
BranchCard's `pendingAdds` state, BranchTimeline's `pendingAdds` prop
and `pruneLandedImages` all use it, so the row shape is no longer
written out twice and constrained structurally a third time. The
`pruneLandedImages` tests now build full `PendingAdd` rows.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Signed-off-by: Matt Toohey <contact@matttoohey.com>
---
 .../lib/features/branches/BranchCard.svelte   | 72 ++++++++++---------
 .../features/branches/timelineImages.test.ts  | 27 +++++--
 .../lib/features/branches/timelineImages.ts   | 26 ++++++-
 .../features/timeline/BranchTimeline.svelte   |  8 +--
 4 files changed, 83 insertions(+), 50 deletions(-)

diff --git a/apps/staged/src/lib/features/branches/BranchCard.svelte b/apps/staged/src/lib/features/branches/BranchCard.svelte
index 9a90c3a07..fd3751dcd 100644
--- a/apps/staged/src/lib/features/branches/BranchCard.svelte
+++ b/apps/staged/src/lib/features/branches/BranchCard.svelte
@@ -84,8 +84,9 @@
   import BranchCardPrButton from './BranchCardPrButton.svelte';
   import BranchImagePicker from './BranchImagePicker.svelte';
   import {
-    createImageStoreQueue,
     pruneLandedImages,
+    storeTimelineImages,
+    type PendingAdd,
     type TimelineImageUpload,
   } from './timelineImages';
   import BranchCardSessionManager from './BranchCardSessionManager.svelte';
@@ -559,13 +560,10 @@
   let prunedSessionIds = $state<Set<string>>(new Set());
 
   /**
-   * "adding..." rows for dropped text files and dropped or picked images. An
-   * image's row gets `imageId` once it is stored. Declared before the cache
-   * hydration below, which prunes it.
+   * "adding..." rows for dropped text files and dropped or picked images.
+   * Declared before the cache hydration below, which prunes it.
    */
-  let pendingAdds = $state<
-    { key: string; title: string; type: 'generating-note' | 'pending-image'; imageId?: string }[]
-  >([]);
+  let pendingAdds = $state<PendingAdd[]>([]);
 
   /** Drops the placeholders whose real rows are in `next`, in the same update. */
   function prunePlaceholders(next: BranchTimelineData) {
@@ -1754,16 +1752,16 @@
 
   let imagePicker: BranchImagePicker | undefined = $state();
   let nextPendingImageId = 0;
-  /** One queue per card, so batches also store one file at a time between them. */
-  const storeImages = createImageStoreQueue();
 
   /**
    * Stores images straight onto the timeline — not pending on a session. A
    * drop and "Add image" both land here, so a picked image ends up exactly
    * where a dropped one does.
    *
-   * Every image gets an "adding..." row up front, even when its batch queues
-   * behind another, since a multi-photo upload from iOS can take seconds.
+   * Batches go through `storeTimelineImages`, one queue shared by every card,
+   * so only one file is stored at a time. Every image gets an "adding..." row
+   * up front, even when its batch queues behind another, since a multi-photo
+   * upload from iOS can take seconds.
    * Each store publishes a branch change, and the reload it triggers brings in
    * that image's real row. The placeholder carries the stored image's ID, so
    * `prunePlaceholders` swaps one for the other in that reload's update.
@@ -1780,29 +1778,35 @@
     };
     pendingAdds = [...pendingAdds, ...placeholders];
 
-    const rejections = await storeImages(images, {
-      onStored: (i, image) => {
-        const { key } = placeholders[i];
-        pendingAdds = pendingAdds.map((p) => (p.key === key ? { ...p, imageId: image.id } : p));
-        // In case the change-feed reload landed before the store returned.
-        if (timeline) pendingAdds = pruneLandedImages(pendingAdds, timeline);
-      },
-      onRejected: (i) => removePlaceholders([placeholders[i].key]),
-    });
-    // One toast for the batch, like the composer's attach errors, so a
-    // rejected PDF or oversized image is not a silent no-op. The extension
-    // stays in each name: it is what explains a PDF failure.
-    const message = formatAttachErrors(rejections);
-    if (message) toast.error('Error', { description: message });
-
-    // Fallback for a stored image whose row never arrives (the refresh
-    // failed, or it was deleted meanwhile), so its spinner can't stay forever.
-    // Wait for the newest load, not just this one: a change-feed reload that
-    // supersedes it makes it return early, and dropping the rows before that
-    // reload lands would blink them out.
-    await loadTimeline();
-    await timelineLoadsSettled();
-    removePlaceholders(placeholders.map((p) => p.key));
+    try {
+      const rejections = await storeTimelineImages(images, {
+        onStored: (i, image) => {
+          const { key } = placeholders[i];
+          pendingAdds = pendingAdds.map((p) => (p.key === key ? { ...p, imageId: image.id } : p));
+          // In case the change-feed reload landed before the store returned.
+          if (timeline) pendingAdds = pruneLandedImages(pendingAdds, timeline);
+        },
+        onRejected: (i) => removePlaceholders([placeholders[i].key]),
+      });
+      // One toast for the batch, like the composer's attach errors, so a
+      // rejected PDF or oversized image is not a silent no-op. The extension
+      // stays in each name: it is what explains a PDF failure.
+      const message = formatAttachErrors(rejections);
+      if (message) toast.error('Error', { description: message });
+
+      // Wait for the newest load, not just this one: a change-feed reload
+      // that supersedes it makes it return early, and dropping the rows below
+      // before that reload lands would blink them out.
+      void loadTimeline();
+      await timelineLoadsSettled();
+    } catch (e) {
+      notifyError('Could not add images', e);
+    } finally {
+      // Fallback for a stored image whose row never arrives (the refresh
+      // failed, or it was deleted meanwhile), and for every row after a batch
+      // that failed outright, so no spinner can stay forever.
+      removePlaceholders(placeholders.map((p) => p.key));
+    }
   }
 
   /** Desktop: files dropped on the card or picked in the open panel. */
diff --git a/apps/staged/src/lib/features/branches/timelineImages.test.ts b/apps/staged/src/lib/features/branches/timelineImages.test.ts
index 4c488ba33..0ff8bb12d 100644
--- a/apps/staged/src/lib/features/branches/timelineImages.test.ts
+++ b/apps/staged/src/lib/features/branches/timelineImages.test.ts
@@ -1,7 +1,12 @@
 import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
 import type { ImageTimelineItem } from '../../types';
 import { formatAttachErrors } from '../sessions/attachErrors';
-import { createImageStoreQueue, pruneLandedImages, storeImagesInOrder } from './timelineImages';
+import {
+  createImageStoreQueue,
+  pruneLandedImages,
+  storeImagesInOrder,
+  type PendingAdd,
+} from './timelineImages';
 
 function deferred() {
   let resolve!: () => void;
@@ -184,12 +189,20 @@ describe('pruneLandedImages', () => {
     };
   }
 
+  function note(key: string): PendingAdd {
+    return { key, title: `${key}.md`, type: 'generating-note' };
+  }
+
+  function image(key: string, imageId?: string): PendingAdd {
+    return { key, title: `${key}.png`, type: 'pending-image', imageId };
+  }
+
   it('drops rows whose stored image is on the timeline', () => {
     const adds = [
-      { key: 'note', imageId: undefined },
-      { key: 'landed', imageId: 'img-1' },
-      { key: 'stored', imageId: 'img-2' },
-      { key: 'storing' },
+      note('note'),
+      image('landed', 'img-1'),
+      image('stored', 'img-2'),
+      image('storing'),
     ];
 
     expect(pruneLandedImages(adds, timelineWith('img-1', 'other')).map((a) => a.key)).toEqual([
@@ -200,9 +213,9 @@ describe('pruneLandedImages', () => {
   });
 
   it('returns the same rows when nothing has landed', () => {
-    const adds = [{ key: 'stored', imageId: 'img-2' }, { key: 'storing' }];
+    const adds = [image('stored', 'img-2'), image('storing')];
 
-    const unstored = [{ key: 'storing', imageId: undefined }];
+    const unstored = [note('note'), image('storing')];
 
     expect(pruneLandedImages(adds, timelineWith('img-1'))).toBe(adds);
     expect(pruneLandedImages(unstored, timelineWith())).toBe(unstored);
diff --git a/apps/staged/src/lib/features/branches/timelineImages.ts b/apps/staged/src/lib/features/branches/timelineImages.ts
index 38e5684f6..ee05e6442 100644
--- a/apps/staged/src/lib/features/branches/timelineImages.ts
+++ b/apps/staged/src/lib/features/branches/timelineImages.ts
@@ -1,6 +1,18 @@
 import type { BranchTimeline, Image } from '../../types';
 import { attachErrorReason, type AttachRejection } from '../sessions/attachErrors';
 
+/**
+ * An "adding..." row for an item headed straight onto a branch timeline: a
+ * note from a dropped text file, or a dropped or picked image. An image's row
+ * gets `imageId` once it is stored.
+ */
+export interface PendingAdd {
+  key: string;
+  title: string;
+  type: 'generating-note' | 'pending-image';
+  imageId?: string;
+}
+
 /** One image headed straight onto a branch timeline (dropped or picked). */
 export interface TimelineImageUpload {
   name: string;
@@ -61,6 +73,14 @@ export function createImageStoreQueue() {
   };
 }
 
+/**
+ * The queue every branch card stores its images through. It is shared, not
+ * per card, so the one-file-at-a-time guarantee holds across cards and
+ * survives a card remounting mid-upload (on a project switch, say), when the
+ * old instance's batch is still storing.
+ */
+export const storeTimelineImages = createImageStoreQueue();
+
 /**
  * Drops the "adding..." rows whose stored image is already in `timeline`.
  * Every stored image publishes a branch change, and the reload it triggers
@@ -68,10 +88,10 @@ export function createImageStoreQueue() {
  * for the image instead of showing both. Returns `adds` itself when nothing
  * has landed.
  */
-export function pruneLandedImages<T extends { imageId?: string }>(
-  adds: T[],
+export function pruneLandedImages(
+  adds: PendingAdd[],
   timeline: Pick<BranchTimeline, 'images'>
-): T[] {
+): PendingAdd[] {
   if (!adds.some((add) => add.imageId)) return adds;
   const landed = new Set(timeline.images.map((image) => image.id));
   const next = adds.filter((add) => !add.imageId || !landed.has(add.imageId));
diff --git a/apps/staged/src/lib/features/timeline/BranchTimeline.svelte b/apps/staged/src/lib/features/timeline/BranchTimeline.svelte
index 40c91035d..739166b6a 100644
--- a/apps/staged/src/lib/features/timeline/BranchTimeline.svelte
+++ b/apps/staged/src/lib/features/timeline/BranchTimeline.svelte
@@ -26,6 +26,7 @@
     UpstreamRelation,
   } from '../../types';
   import type { NoteClickInfo } from '../sessions/noteFreshness';
+  import type { PendingAdd } from '../branches/timelineImages';
   import TimelineRow from './TimelineRow.svelte';
   import TimelineContextMenu, {
     type TimelineContextMenuAction,
@@ -70,12 +71,7 @@
      * dropped text files, and dropped or picked images (with `imageId` once
      * stored).
      */
-    pendingAdds?: {
-      key: string;
-      title: string;
-      type: 'generating-note' | 'pending-image';
-      imageId?: string;
-    }[];
+    pendingAdds?: PendingAdd[];
     /** Placeholder items for newly started sessions before timeline persistence catches up. */
     pendingItems?: PendingItem[];
     /** Session IDs that were just pruned from pendingItems because the real timeline item arrived. */