@freqhole/api-client 0.3.3 → 0.3.5

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@freqhole/api-client",
-  "version": "0.3.3",
+  "version": "0.3.5",
   "type": "module",
   "repository": {
     "type": "git",

package/src/CharnelLocalTransport.ts

@@ -4,37 +4,16 @@
 // calls grimoire::api::dispatch directly via the api_call IPC command.
 // uses Tauri's asset protocol for blob/audio file access (no HTTP streaming).
 
-import type { Transport, TransportResponse, BlobData } from "./transport.js";
+import type { Transport, TransportResponse, BlobData, UploadMetadata } from "./transport.js";
 import type { CloseReason, EventFilter, JobEvent, JobStateSnapshot } from "./codegen/schema.js";
+import { bytesToBase64 } from "./base64.js";
 
 // tauri invoke function type
 type InvokeFn = (cmd: string, args?: unknown) => Promise<unknown>;
 
 // tauri invoke is dynamically imported to avoid bundling in browser builds
 let invoke: InvokeFn | null = null;
-let convertFileSrc: ((path: string) => string) | null = null;
-
-// webkitgtk (linux) can't play asset:// URLs in <audio> elements.
-// detect once at module level so we can use blob: URLs as a workaround.
-//
-// historically there was a second workaround here — an embedded http
-// loopback server (`media_server_info` ipc + `server::media_server`)
-// that served blobs via plain http. it has been removed in favor of
-// the rodio backend (see `client/spume/src/music/services/audio/`),
-// which bypasses the html `<audio>` element entirely on linux. when
-// rodio is *not* enabled and we're on linux, we fall back to the
-// blob: object url path below.
-const isLinuxWebKit = typeof navigator !== "undefined" && navigator.userAgent.includes("Linux");
-
-/**
- * blobs that must never be buffered into memory as a blob: URL, even on
- * linux: a local video can easily be multi-GB, and `fetch().arrayBuffer()`
- * on one hangs the whole app. these stream from asset:// instead, which
- * also gives `<video>` real range requests for seeking.
- */
-function isStreamableMime(mime?: string | null): boolean {
-  return (mime ?? "").startsWith("video/");
-}
+let convertFileSrc: ((path: string, protocol?: string) => string) | null = null;
 
 /**
  * initialize tauri invoke function
@@ -52,6 +31,48 @@ async function ensureInvoke(): Promise<InvokeFn> {
   }
 }
 
+/**
+ * build a playable url for a local file path via the custom
+ * `freqhole-media` protocol (see `client/charnel/src-tauri/src/
+ * media_protocol.rs`) - used on every platform, not just android: tauri's
+ * built-in `asset` protocol caps every range response to ~1MB regardless
+ * of what was actually requested, which a webview's media pipeline
+ * doesn't reliably recover from for anything larger (a compressed file
+ * limps along for ~30s before stalling; an uncompressed one like a wav
+ * can stop in single-digit seconds). `freqhole-media` mirrors the
+ * built-in protocol's shape but removes that cap, and is already
+ * registered on every platform regardless of which protocol the client
+ * actually requests.
+ */
+function mediaSrcFor(path: string): string {
+  if (!convertFileSrc) {
+    throw new Error("convertFileSrc not available");
+  }
+  return convertFileSrc(path, "freqhole-media");
+}
+
+/**
+ * tauri's `invoke()` rejects with the raw `String` from a `Result<T,
+ * String>` command - not an `Error` instance - so a plain
+ * `err instanceof Error ? err.message : "..."` check silently discards
+ * that string. this covers the string case too.
+ */
+function ipcErrorMessage(err: unknown): string {
+  if (err instanceof Error) return err.message;
+  if (typeof err === "string" && err.trim()) return err;
+  return "IPC error";
+}
+
+/**
+ * public, self-contained version of `mediaSrcFor` for callers outside this
+ * file (spume's `localAudio.ts`/`localVideo.ts`) - ensures tauri's invoke/
+ * convertFileSrc/target_os are loaded before resolving.
+ */
+export async function resolveCharnelMediaSrc(path: string): Promise<string> {
+  await ensureInvoke();
+  return mediaSrcFor(path);
+}
+
 /**
  * response shape from api_call command (matches GrimoireResponse)
  */
@@ -74,8 +95,6 @@ export class CharnelLocalTransport implements Transport {
   private blobPathCache = new Map<string, { path: string; mime?: string }>();
   // cache object URLs for db-stored blobs (no local path)
   private blobObjectUrlCache = new Map<string, string>();
-  // single audio blob URL for linux workaround (revoke-on-replace to avoid memory leak)
-  private audioBlobUrl: { blobId: string; url: string } | null = null;
 
   constructor(_baseUrl: string) {
     // baseUrl no longer needed - all requests go through IPC.
@@ -149,18 +168,22 @@ export class CharnelLocalTransport implements Transport {
       console.info(
         `[perf] api_call ${path} failed after ${(performance.now() - requestStart).toFixed(1)}ms`,
       );
-      // IPC error - treat as network error
+      // IPC error - tauri's invoke() rejects with the raw String from a
+      // Result<T, String> command (not an Error instance), so this must
+      // check for a plain string too or the real message gets discarded.
       return {
         status: 0,
         body: JSON.stringify({
-          error: err instanceof Error ? err.message : "IPC error",
+          error: ipcErrorMessage(err),
         }),
       };
     }
   }
 
   /**
-   * upload - converts FormData to base64 JSON and calls dispatch
+   * upload - routes music/video to the chunked local-import path (see
+   * `uploadChunked`); everything else (images etc) still uses the legacy
+   * whole-file base64 path, which is fine at small file sizes.
    *
    * for tauri-local, we use wait_for_completion to block until the job
    * finishes, avoiding the need for polling from the client side.
@@ -168,16 +191,9 @@ export class CharnelLocalTransport implements Transport {
   async upload(
     path: string,
     formData: FormData,
-    _onProgress?: (loaded: number, total: number) => void,
+    onProgress?: (loaded: number, total: number) => void,
+    metadata?: UploadMetadata,
   ): Promise<TransportResponse> {
-    // no byte-level progress possible here - unlike CharnelTransport (P2P),
-    // which already chunks the file for android/memory reasons and can
-    // report progress per chunk, this local-dispatch path reads the whole
-    // file into one base64 JSON body and sends it as a single IPC call.
-    // chunking this too would need a new local (non-P2P) equivalent of the
-    // `-by-blake3` upload route, since that route currently requires a
-    // `node_id` and always pulls from a remote peer.
-    // extract file and other fields from FormData
     const file = formData.get("file") as File | null;
     if (!file) {
       return {
@@ -190,6 +206,87 @@ export class CharnelLocalTransport implements Transport {
       };
     }
 
+    if (path === "/api/upload/music" || path === "/api/upload/video") {
+      return this.uploadChunked(path, file, metadata, onProgress);
+    }
+
+    return this.uploadLegacyBase64(path, file, metadata);
+  }
+
+  /**
+   * stream a music/video file to this local grimoire instance in bounded
+   * chunks via the local_import_* tauri commands (shared with
+   * CharnelTransport's P2P chunked import - see p2p_commands.rs), instead
+   * of buffering the whole file into one base64 JSON body. mirrors
+   * CharnelTransport.uploadMediaViaBytes, but finishes to a plain temp-file
+   * path (this device IS the destination, no remote peer to pull from)
+   * which is then handed to the existing `file_path`-based upload route.
+   *
+   * `onProgress`, if given, is called after each chunk with (bytes sent so
+   * far, file.size) - real, byte-level progress from the chunk loop itself.
+   */
+  private async uploadChunked(
+    path: string,
+    file: File,
+    metadata: UploadMetadata | undefined,
+    onProgress?: (loaded: number, total: number) => void,
+  ): Promise<TransportResponse> {
+    const inv = await ensureInvoke();
+
+    // ~4MB raw per chunk -> ~5.5MB base64 per IPC call, matching the P2P
+    // chunked import's chunk size.
+    const CHUNK_SIZE = 4 * 1024 * 1024;
+
+    const uploadId = (await inv("p2p_import_begin")) as string;
+    let filePath: string;
+    try {
+      for (let offset = 0; offset < file.size; offset += CHUNK_SIZE) {
+        const slice = file.slice(offset, Math.min(offset + CHUNK_SIZE, file.size));
+        const chunkBytes = new Uint8Array(await slice.arrayBuffer());
+        await inv("p2p_import_chunk", { uploadId, data: bytesToBase64(chunkBytes) });
+        onProgress?.(Math.min(offset + chunkBytes.length, file.size), file.size);
+      }
+      filePath = (await inv("local_import_finish", { uploadId })) as string;
+    } catch (err) {
+      try {
+        await inv("p2p_import_abort", { uploadId });
+      } catch {
+        // ignore abort failures
+      }
+      throw err;
+    }
+
+    try {
+      const body: Record<string, unknown> = {
+        file_path: filePath,
+        filename: file.name,
+        wait_for_completion: true,
+        ...metadata,
+      };
+      return await this.request("POST", path, JSON.stringify(body));
+    } finally {
+      try {
+        await inv("local_import_cleanup", { filePath });
+      } catch {
+        // best-effort - a leaked temp file isn't worth failing the upload over
+      }
+    }
+  }
+
+  /**
+   * @deprecated whole-file base64 upload - reads the entire file into
+   * memory and base64-encodes it in one shot, which OOM-crashed the
+   * android webview for large music/video files (see uploadChunked, which
+   * replaced this for those routes). only still used for small non-media
+   * uploads (e.g. images) where this is safe. do not extend this to any
+   * new large-file route - add it to the `uploadChunked` branch in
+   * `upload()` instead.
+   */
+  private async uploadLegacyBase64(
+    path: string,
+    file: File,
+    metadata?: UploadMetadata,
+  ): Promise<TransportResponse> {
     // read file as base64
     const arrayBuffer = await file.arrayBuffer();
     const base64 = btoa(
@@ -203,18 +300,9 @@ export class CharnelLocalTransport implements Transport {
       // tauri-local optimization: wait for job to complete instead of returning job_id
       // this eliminates the need for client-side polling
       wait_for_completion: true,
+      ...metadata,
     };
 
-    // include associate_with if present
-    const associationStr = formData.get("associate_with");
-    if (associationStr && typeof associationStr === "string") {
-      try {
-        body.associate_with = JSON.parse(associationStr);
-      } catch {
-        // ignore parse errors
-      }
-    }
-
     // call through normal request path
     return this.request("POST", path, JSON.stringify(body));
   }
@@ -291,7 +379,7 @@ export class CharnelLocalTransport implements Transport {
     }
 
     // convert to asset URL and fetch via browser
-    const assetUrl = convertFileSrc(pathInfo.path);
+    const assetUrl = mediaSrcFor(pathInfo.path);
     const fetchResponse = await fetch(assetUrl);
     const arrayBuffer = await fetchResponse.arrayBuffer();
 
@@ -339,13 +427,7 @@ export class CharnelLocalTransport implements Transport {
   /**
    * get blob URL — preference order:
    * 1. cached object URL (db-stored blobs)
-   * 2. tauri asset:// (via `convertFileSrc`) on macos/windows
-   * 3. linux fallback: fetch via asset:// and wrap in a blob: object URL
-   *    (webkitgtk can't stream asset:// into `<audio>`)
-   *
-   * the linux fallback buffers the ENTIRE file in memory, so it is never
-   * used for video - a multi-GB local video would exhaust memory and hang
-   * the app (`<video>` also seeks, which a one-shot blob can't stream).
+   * 2. tauri asset:// (via `convertFileSrc`), for any blob with a local path
    *
    * note: when the rodio audio backend is enabled (charnel + opt-in)
    * playback bypasses html `<audio>` entirely and reads files via
@@ -359,25 +441,15 @@ export class CharnelLocalTransport implements Transport {
       return cachedObjectUrl;
     }
 
-    // on linux without rodio, we MUST go async to wrap in a blob:
-    // url (asset:// can't stream into <audio> on webkitgtk) - except for
-    // video, which streams from asset:// directly (see below).
-    const cachedPath = this.blobPathCache.get(blobId);
-    if (isLinuxWebKit && !isStreamableMime(cachedPath?.mime)) {
-      console.debug(`[CharnelLocalTransport] blob ${blobId}: linux fallback (async)`);
-      return this.getBlobUrlAsync(blobId);
-    }
-
     // check path cache (filesystem blobs) — direct asset:// url
-    const cached = cachedPath;
+    const cached = this.blobPathCache.get(blobId);
     if (cached && convertFileSrc) {
-      const url = convertFileSrc(cached.path);
+      const url = mediaSrcFor(cached.path);
       console.debug(`[CharnelLocalTransport] blob ${blobId}: asset:// (cached) -> ${url}`);
       return url;
     }
 
     // need to fetch path (or data) first
-    // console.debug(`[CharnelLocalTransport] blob ${blobId}: async path lookup`);
     return this.getBlobUrlAsync(blobId);
   }
 
@@ -400,22 +472,10 @@ export class CharnelLocalTransport implements Transport {
           throw new Error("convertFileSrc not available");
         }
 
-        // on linux without media server: fall back to blob: workaround.
-        // routes audio + image differently:
-        //   - audio: single-slot cache (revoke-on-replace) since audio
-        //     blobs are large and we only play one at a time
-        //   - other (images / waveforms / cover art): per-blob cache so
-        //     multiple `<img>` and css `background-image` urls coexist
-        //     across the playerbar, queue sidebar, etc.
-        // video is excluded - buffering it would hang the app.
-        if (isLinuxWebKit && !isStreamableMime(parsed.data.mime)) {
-          return this.createBlobObjectUrl(blobId, parsed.data.path, parsed.data.mime);
-        }
-
         console.debug(
           `[CharnelLocalTransport] blob ${blobId}: asset:// stream (mime=${parsed.data.mime ?? "?"})`,
         );
-        return convertFileSrc(parsed.data.path);
+        return mediaSrcFor(parsed.data.path);
       }
     }
 
@@ -437,54 +497,6 @@ export class CharnelLocalTransport implements Transport {
     throw new Error(`failed to get blob path: ${response.body}`);
   }
 
-  /**
-   * create a blob: object URL by fetching via asset:// protocol.
-   * used on linux where webkitgtk can't play asset:// in `<audio>`
-   * elements (and historically also where the embedded http loopback
-   * server stood in for the same workaround).
-   *
-   * mime-aware caching:
-   *   - `audio/*`: single-slot cache, revoke-on-replace. audio blobs
-   *     are large (often tens of MB) and only one ever plays at a
-   *     time, so leaking the rest is wasteful.
-   *   - everything else (images, waveforms, cover art): stored in
-   *     `blobObjectUrlCache` keyed by blob id so multiple `<img>` /
-   *     css `background-image` references coexist without one
-   *     revoking another.
-   */
-  private async createBlobObjectUrl(
-    blobId: string,
-    localPath: string,
-    mime?: string,
-  ): Promise<string> {
-    if (!convertFileSrc) {
-      throw new Error("convertFileSrc not available");
-    }
-
-    const isAudio = (mime ?? "").startsWith("audio/");
-    const effectiveMime = mime ?? (isAudio ? "audio/mpeg" : "application/octet-stream");
-
-    const assetUrl = convertFileSrc(localPath);
-    const resp = await fetch(assetUrl);
-    const arrayBuffer = await resp.arrayBuffer();
-    const blob = new Blob([arrayBuffer], { type: effectiveMime });
-    const objectUrl = URL.createObjectURL(blob);
-
-    if (isAudio) {
-      // revoke previous single-slot audio url (if any) so we don't
-      // leak large buffers as the user moves between tracks.
-      if (this.audioBlobUrl) {
-        URL.revokeObjectURL(this.audioBlobUrl.url);
-      }
-      this.audioBlobUrl = { blobId, url: objectUrl };
-    } else {
-      // per-blob cache so e.g. the playerbar's waveform and the queue
-      // sidebar's matching waveform share a single object url.
-      this.blobObjectUrlCache.set(blobId, objectUrl);
-    }
-    return objectUrl;
-  }
-
   // -----------------------------------------------------------------
   // job events (local ipc shortcut)
   //

package/src/CharnelTransport.ts

@@ -3,11 +3,18 @@
 // uses Tauri IPC commands to make P2P requests via the server's
 // app iroh endpoint. no WASM needed.
 
-import type { BlobData, BlobFetchOptions, Transport, TransportResponse } from "./transport.js";
+import type {
+  BlobData,
+  BlobFetchOptions,
+  Transport,
+  TransportResponse,
+  UploadMetadata,
+} from "./transport.js";
 import type { BlobProgressCallback } from "./WasmTransport.js";
 import { isTauriRuntime } from "./tauriRuntime.js";
 import type { CloseReason, EventFilter, JobEvent, JobStateSnapshot } from "./codegen/schema.js";
 import { JobEventsStreamClosed } from "./CharnelLocalTransport.js";
+import { bytesToBase64 } from "./base64.js";
 
 // tauri invoke function type
 type InvokeFn = (cmd: string, args?: unknown) => Promise<unknown>;
@@ -186,17 +193,6 @@ function base64ToBytes(base64: string): Uint8Array {
   return bytes;
 }
 
-/**
- * encode Uint8Array to base64 string
- */
-function bytesToBase64(bytes: Uint8Array): string {
-  let binary = "";
-  for (let i = 0; i < bytes.length; i++) {
-    binary += String.fromCharCode(bytes[i]);
-  }
-  return btoa(binary);
-}
-
 /**
  * CharnelTransport - P2P transport using Tauri IPC commands
  * implements Transport interface for use with FreqholeClient
@@ -270,6 +266,7 @@ export class CharnelTransport implements Transport {
     path: string,
     formData: FormData,
     onProgress?: (loaded: number, total: number) => void,
+    metadata?: UploadMetadata,
   ): Promise<TransportResponse> {
     // extract file from form data
     const file = formData.get("file") as File | null;
@@ -296,11 +293,11 @@ export class CharnelTransport implements Transport {
     // the import is already chunked (see uploadMediaViaBytes), so real
     // per-chunk progress is reported here, same as HttpTransport's XHR path.
     if (path === "/api/upload/music" || path === "/api/upload/video") {
-      return this.uploadMediaViaBytes(path, file, onProgress);
+      return this.uploadMediaViaBytes(path, file, onProgress, metadata);
     }
 
     // for non-media uploads (images etc), use base64 (small enough)
-    return this.uploadViaBase64(path, file, formData);
+    return this.uploadViaBase64(path, file, metadata);
   }
 
   /**
@@ -356,7 +353,7 @@ export class CharnelTransport implements Transport {
   private async uploadViaBase64(
     path: string,
     file: File,
-    formData: FormData,
+    metadata?: UploadMetadata,
   ): Promise<TransportResponse> {
     if (file.size > MAX_BASE64_UPLOAD_BYTES) {
       throw uploadTooLargeError(file, path);
@@ -368,18 +365,9 @@ export class CharnelTransport implements Transport {
     const body: Record<string, unknown> = {
       data: base64,
       filename: file.name,
+      ...metadata,
     };
 
-    // include associate_with if present
-    const associateWithStr = formData.get("associate_with") as string | null;
-    if (associateWithStr) {
-      try {
-        body.associate_with = JSON.parse(associateWithStr);
-      } catch {
-        // ignore parse errors
-      }
-    }
-
     // send via api_request — routes through offal dispatch on the remote peer
     return this.request("POST", path, JSON.stringify(body));
   }
@@ -405,6 +393,7 @@ export class CharnelTransport implements Transport {
     path: string,
     file: File,
     onProgress?: (loaded: number, total: number) => void,
+    metadata?: UploadMetadata,
   ): Promise<TransportResponse> {
     const inv = await ensureInvoke();
 
@@ -439,7 +428,7 @@ export class CharnelTransport implements Transport {
     console.debug("[P2P] uploadMediaViaBytes: imported blob, blake3 =", blake3);
 
     // tell the remote peer to pull the blob from us
-    const body = { blake3, filename: file.name };
+    const body = { blake3, filename: file.name, ...metadata };
     return tagStep("remote_trigger", () =>
       this.request("POST", `${path}-by-blake3`, JSON.stringify(body)),
     );

package/src/WasmTransport.ts

@@ -3,7 +3,13 @@
 // uses midden's MiddenNode to make API requests to peer nodes.
 // blobs are cached in Cache API for audio playback.
 
-import type { BlobData, BlobFetchOptions, Transport, TransportResponse } from "./transport.js";
+import type {
+  BlobData,
+  BlobFetchOptions,
+  Transport,
+  TransportResponse,
+  UploadMetadata,
+} from "./transport.js";
 import { snapshotJobEventsViaRequest } from "./transport.js";
 import type { CloseReason, EventFilter, JobEvent, JobStateSnapshot } from "./codegen/schema.js";
 import { JobEventsStreamClosed } from "./CharnelLocalTransport.js";
@@ -72,6 +78,16 @@ export interface MiddenNodeLike {
   // import bytes into local iroh-blobs store, returns blake3 hash (64 hex chars)
   // keeps a TempTag so GC won't collect it until release_blob is called
   import_blob?(data: Uint8Array): Promise<string>;
+  // chunked counterpart of import_blob - the wasm boundary never sees the
+  // whole payload at once (see lib/midden's ImportSession doc comment).
+  // push() is backpressured (resolves once the chunk is queued); finish()
+  // completes the import and returns the blake3 hash, pinned the same way
+  // import_blob's result is (until release_blob is called).
+  start_import?(): {
+    push(chunk: Uint8Array): Promise<void>;
+    finish(): Promise<string>;
+    abort(): void;
+  };
   // release a blob's TempTag, allowing GC
   release_blob?(blake3_hash: string): void;
   // start background accept loop for incoming iroh-blobs connections
@@ -84,6 +100,14 @@ export interface MiddenNodeLike {
   // download blob by ID with on-demand blake3 computation - optional
   // returns [Uint8Array, string] but typed as any[] for wasm-bindgen compatibility
   download_verified_by_id?(peer_addr: string, blob_id: string): Promise<any[]>;
+  // same as download_verified_by_id but reports incremental progress -
+  // on_progress receives a fraction in [0, 1]. returns [Uint8Array, string].
+  download_verified_by_id_progress?(
+    peer_addr: string,
+    blob_id: string,
+    total_size: number,
+    on_progress: (fraction: number) => void,
+  ): Promise<any[]>;
   // download blob and stream chunks via callback - preferred for large files
   // on_chunk receives (chunk: Uint8Array, offset: number)
   // on_progress receives (fraction: number) in [0, 1]
@@ -149,6 +173,14 @@ export type BlobProgressCallback = (received: number, total: number) => void;
 // unified cache for all remote blobs (HTTP + P2P) - default if no custom cache name provided
 const DEFAULT_CACHE_NAME = "freqhole-blobs-v1";
 
+// retry ladder for a request that fails at the connection/stream level
+// (e.g. "read error: connection lost") - mirrors playerPairingClient.ts's
+// DIAL_RETRY_DELAYS_MS for the same underlying reason: a freshly-dialed
+// p2p connection can still be settling and drop an early request even
+// though the peer is genuinely reachable. short and small on purpose -
+// this guards a single request, not a whole cold-dial handshake.
+const REQUEST_RETRY_DELAYS_MS = [150, 400];
+
 /**
  * decode base64 string to Uint8Array
  * handles both standard and URL-safe base64 encoding
@@ -319,34 +351,49 @@ export class WasmTransport implements Transport {
   }
 
   async request(method: string, path: string, body?: string): Promise<TransportResponse> {
-    try {
-      // TEMP DEBUG - remove once the first-pair-attempt-fails bug is found
-      console.log(`[debug/WasmTransport] request start ${method} ${path} -> ${this.peerAddr}`);
-      const result = await this.node.api_request(this.peerAddr, method, path, body ?? null);
-      // TEMP DEBUG - remove once the first-pair-attempt-fails bug is found
-      console.log(`[debug/WasmTransport] request ok ${method} ${path} status=${result.status}`);
-      if (result.status < 200 || result.status >= 300) {
-        // TEMP DEBUG - remove once sync-to-local wiring bug is found
-        console.log(`[debug/WasmTransport] ${method} ${path} non-2xx body:`, result.body);
+    let lastErr: unknown;
+    for (let attempt = 0; attempt <= REQUEST_RETRY_DELAYS_MS.length; attempt++) {
+      try {
+        const result = await this.node.api_request(this.peerAddr, method, path, body ?? null);
+        if (result.status < 200 || result.status >= 300) {
+          // TEMP DEBUG - remove once sync-to-local wiring bug is found
+          console.log(`[debug/WasmTransport] ${method} ${path} non-2xx body:`, result.body);
+        }
+        return {
+          status: result.status,
+          body: result.body,
+        };
+      } catch (e) {
+        lastErr = e;
+        // any exception here is a connection/stream-level failure (a real
+        // HTTP-ish response, even non-2xx, resolves normally above) - a
+        // freshly-dialed p2p peer's connection can still be settling (NAT
+        // traversal/relay handoff) and drop an early request with "read
+        // error: connection lost" even though the peer itself is fine, as
+        // seen live pushing a queued song to a just-paired player. retrying
+        // a few times with a short delay (same ladder shape as
+        // playerPairingClient.ts's cold-dial retry) instead of failing
+        // the whole resolve immediately.
+        if (attempt < REQUEST_RETRY_DELAYS_MS.length) {
+          console.warn(
+            `[WasmTransport] ${method} ${path} attempt ${attempt + 1} failed, retrying:`,
+            e,
+          );
+          await new Promise((resolve) => setTimeout(resolve, REQUEST_RETRY_DELAYS_MS[attempt]));
+          continue;
+        }
       }
-      return {
-        status: result.status,
-        body: result.body,
-      };
-    } catch (e) {
-      // P2P connection errors - rethrow with message that isNetworkError will catch
-      const { message, errorType } = extractErrorType(e);
-      // TEMP DEBUG - remove once sync-to-local wiring bug is found
-      console.log(`[debug/WasmTransport] ${method} ${path} threw:`, e);
-      console.warn(`[WasmTransport] P2P request failed: ${message}`);
-      throw new TransportError(`connection failed: ${message}`, { errorType });
     }
+    const { message, errorType } = extractErrorType(lastErr);
+    console.warn(`[WasmTransport] P2P request failed: ${message}`);
+    throw new TransportError(`connection failed: ${message}`, { errorType });
   }
 
   async upload(
     path: string,
     formData: FormData,
     _onProgress?: (loaded: number, total: number) => void,
+    metadata?: UploadMetadata,
   ): Promise<TransportResponse> {
     // no byte-level progress possible here - unlike CharnelTransport's tauri
     // IPC path (which self-chunks and can report per-chunk progress), the
@@ -375,11 +422,11 @@ export class WasmTransport implements Transport {
     // available - chunked/verified streaming, no base64/raw-bytes framing.
     const blobPullPaths = ["/api/upload/music", "/api/upload/video"];
     if (blobPullPaths.includes(path) && this.node.import_blob) {
-      return this.uploadViaIrohBlobs(path, file, formData);
+      return this.uploadViaIrohBlobs(path, file, metadata);
     }
 
     // fallback: base64 encode and send via api_request (works for image uploads)
-    return this.uploadViaBase64(path, file, formData);
+    return this.uploadViaBase64(path, file, metadata);
   }
 
   /**
@@ -392,7 +439,7 @@ export class WasmTransport implements Transport {
   private async uploadViaIrohBlobs(
     path: string,
     file: File,
-    formData: FormData,
+    metadata?: UploadMetadata,
   ): Promise<TransportResponse> {
     try {
       const fileBytes = new Uint8Array(await file.arrayBuffer());
@@ -403,28 +450,9 @@ export class WasmTransport implements Transport {
           blake3: hash,
           filename: file.name,
           size: fileBytes.length,
+          ...metadata,
         };
 
-        // include metadata if present (parsed as JSON)
-        const metadataStr = formData.get("metadata") as string | null;
-        if (metadataStr) {
-          try {
-            body.metadata = JSON.parse(metadataStr);
-          } catch {
-            // ignore parse errors
-          }
-        }
-
-        // include associate_with if present
-        const associateWithStr = formData.get("associate_with") as string | null;
-        if (associateWithStr) {
-          try {
-            body.associate_with = JSON.parse(associateWithStr);
-          } catch {
-            // ignore parse errors
-          }
-        }
-
         const response = await this.request("POST", `${path}-by-blake3`, JSON.stringify(body));
         return response;
       } finally {
@@ -449,7 +477,7 @@ export class WasmTransport implements Transport {
   private async uploadViaBase64(
     path: string,
     file: File,
-    formData: FormData,
+    metadata?: UploadMetadata,
   ): Promise<TransportResponse> {
     if (path === "/api/upload/music" || path === "/api/upload/video") {
       console.warn(
@@ -469,18 +497,9 @@ export class WasmTransport implements Transport {
     const body: Record<string, unknown> = {
       data: base64,
       filename: file.name,
+      ...metadata,
     };
 
-    // include associate_with if present
-    const associateWithStr = formData.get("associate_with") as string | null;
-    if (associateWithStr) {
-      try {
-        body.associate_with = JSON.parse(associateWithStr);
-      } catch {
-        // ignore parse errors
-      }
-    }
-
     // send via api_request — routes through offal dispatch on the remote peer
     return this.request("POST", path, JSON.stringify(body));
   }
@@ -755,14 +774,29 @@ export class WasmTransport implements Transport {
     // fallback because `/api/blobs/{id}/data` only works for DB-backed blobs
     // and file-backed media blobs would otherwise fail first, then fall back
     // anyway.
-    if (!blake3 && this.node.download_verified_by_id && mimeType?.startsWith("audio/")) {
+    // download_verified_by_id_progress always ships alongside plain
+    // download_verified_by_id in the same midden build (both are generated
+    // from the same wasm-bindgen pass) - there's no real scenario where
+    // only the non-progress variant is available, so this only checks for
+    // the progress-capable one. the plain variant has no progress hook at
+    // all - calling it here would only ever report one 0->100% jump at
+    // completion instead of the incremental updates a multi-second
+    // download needs for a usable progress bar.
+    if (!blake3 && this.node.download_verified_by_id_progress && mimeType?.startsWith("audio/")) {
       try {
-        const result = await this.node.download_verified_by_id(this.peerAddr, blobId);
+        const result = await this.node.download_verified_by_id_progress(
+          this.peerAddr,
+          blobId,
+          totalBytes ?? 0,
+          (fraction: number) => {
+            if (totalBytes && totalBytes > 0) {
+              onProgress(Math.min(totalBytes, Math.floor(fraction * totalBytes)), totalBytes);
+            }
+          },
+        );
         const data = result[0] as Uint8Array;
         const contentType = mimeType || "application/octet-stream";
 
-        onProgress(data.length, data.length);
-
         await this.storeInCache(cache, blobId, data, contentType, opts);
 
         return { data, contentType };
@@ -816,14 +850,23 @@ export class WasmTransport implements Transport {
     // this matches fetchBlob() so callers using the progress path (radio
     // timeline playback) do not fail just because the API response omitted
     // blake3 for a song.
-    if (!blake3 && this.node.download_verified_by_id) {
+    if (!blake3 && this.node.download_verified_by_id_progress) {
       try {
-        const result = await this.node.download_verified_by_id(this.peerAddr, blobId);
+        // see the audio-specific branch above for why only the progress
+        // variant is checked for here.
+        const result = await this.node.download_verified_by_id_progress(
+          this.peerAddr,
+          blobId,
+          totalBytes ?? 0,
+          (fraction: number) => {
+            if (totalBytes && totalBytes > 0) {
+              onProgress(Math.min(totalBytes, Math.floor(fraction * totalBytes)), totalBytes);
+            }
+          },
+        );
         const data = result[0] as Uint8Array;
         const contentType = mimeType || "application/octet-stream";
 
-        onProgress(data.length, data.length);
-
         await this.storeInCache(cache, blobId, data, contentType, opts);
 
         return { data, contentType };

package/src/base64.ts

@@ -0,0 +1,16 @@
+// shared byte <-> base64 helpers for chunked tauri IPC uploads.
+// extracted from CharnelTransport.ts so CharnelLocalTransport.ts's chunked
+// upload path can reuse the exact same, already-proven-safe encoding.
+
+/**
+ * encode a Uint8Array to a base64 string.
+ * only ever called with bounded chunk sizes (a few MB at most) by callers
+ * in this package - never the whole file at once.
+ */
+export function bytesToBase64(bytes: Uint8Array): string {
+  let binary = "";
+  for (let i = 0; i < bytes.length; i++) {
+    binary += String.fromCharCode(bytes[i]);
+  }
+  return btoa(binary);
+}

package/src/codegen/routes.ts

@@ -142,6 +142,7 @@ export const routes = {
     get_blob_thumbnail: { method: 'GET', path: '/api/blobs/{id}/thumb/{size}', req: null, resp: null, auth: { type: 'authenticated' } as const },
     get_enrichment_progress: { method: 'POST', path: '/api/music/albums/enrichment/progress', req: s.GetEnrichmentProgressRequestSchema, resp: s.GetEnrichmentProgressResponseSchema, auth: { type: 'role', role: 'admin' } as const },
     get_fetch_job: { method: 'POST', path: '/api/music/fetch/status', req: s.GetJobRequestSchema, resp: s.JobResponseSchema, auth: { type: 'authenticated' } as const },
+    get_import_session_target: { method: 'POST', path: '/api/music/import/session-target', req: s.GetImportSessionTargetRequestSchema, resp: s.ImportSessionSendTargetSchema, auth: { type: 'authenticated' } as const },
     get_job_status: { method: 'POST', path: '/api/jobs/status', req: s.GetJobsStatusRequestSchema, resp: s.GetJobsStatusResponseSchema, auth: { type: 'authenticated' } as const },
     get_musicbrainz_release: { method: 'POST', path: '/api/musicbrainz/release', req: s.GetReleaseRequestSchema, resp: s.MbReleaseDetailSchema, auth: { type: 'role', role: 'admin' } as const },
     get_playback_session: { method: 'POST', path: '/api/analytics/sessions/get', req: s.GetPlaybackSessionRequestSchema, resp: s.PlaybackSessionSchema, auth: { type: 'authenticated' } as const },
@@ -248,6 +249,7 @@ export const routes = {
     get_video_series: { method: 'POST', path: '/api/video/series/get', req: s.GetVideoSeriesRequestSchema, resp: s.VideoSeriesSchema, auth: { type: 'authenticated' } as const },
     get_video_series_detail: { method: 'POST', path: '/api/video/series/detail', req: s.GetVideoSeriesRequestSchema, resp: s.SeriesDetailSchema, auth: { type: 'authenticated' } as const },
     get_video_with_metadata: { method: 'POST', path: '/api/video/videos/get-with-metadata', req: s.GetVideoRequestSchema, resp: s.VideoWithMetadataSchema, auth: { type: 'authenticated' } as const },
+    import_video_paths: { method: 'POST', path: '/api/upload/video-paths', req: null, resp: s.VideoImportResponseSchema, auth: { type: 'role', role: 'member' } as const },
     list_pending_video_import_review: { method: 'POST', path: '/api/video/import/pending', req: s.ListPendingVideoReviewRequestSchema, resp: s.PendingVideoReviewSessionSchema.array(), auth: { type: 'authenticated' } as const },
     list_playback_progress: { method: 'POST', path: '/api/video/progress/list', req: s.ListPlaybackProgressRequestSchema, resp: s.PlaybackProgressSchema.array(), auth: { type: 'authenticated' } as const },
     list_video_seasons: { method: 'POST', path: '/api/video/seasons/list', req: s.ListVideoSeasonsRequestSchema, resp: s.VideoSeasonSchema.array(), auth: { type: 'authenticated' } as const },

package/src/codegen/schema.ts

@@ -1285,6 +1285,12 @@ export const AudioDbAlbumDetailResultSchema = z.object({
 });
 export type AudioDbAlbumDetailResult = z.infer<typeof AudioDbAlbumDetailResultSchema>;
 
+export const AudioDeviceInfoSchema = z.object({
+  name: z.string(),
+  description: z.string()
+});
+export type AudioDeviceInfo = z.infer<typeof AudioDeviceInfoSchema>;
+
 export const AutoConfirmMbMatchesRequestSchema = z.object({
   album_ids: z.array(z.string()),
   min_confidence: z.number(),
@@ -1931,6 +1937,14 @@ export const EventFilterSchema = z.object({
 });
 export type EventFilter = z.infer<typeof EventFilterSchema>;
 
+export const ExistingImportedFileSchema = z.object({
+  file_path: z.string(),
+  song_id: z.string().nullish(),
+  album_id: z.string().nullish(),
+  video_id: z.string().nullish()
+});
+export type ExistingImportedFile = z.infer<typeof ExistingImportedFileSchema>;
+
 export const ExternalUrlSchema = z.object({
   name: z.string(),
   url: z.string()
@@ -2953,6 +2967,11 @@ export const GetFavoriteStatusBulkRequestSchema = z.object({
 });
 export type GetFavoriteStatusBulkRequest = z.infer<typeof GetFavoriteStatusBulkRequestSchema>;
 
+export const GetImportSessionTargetRequestSchema = z.object({
+  session_id: z.string()
+});
+export type GetImportSessionTargetRequest = z.infer<typeof GetImportSessionTargetRequestSchema>;
+
 export const GetJobRequestSchema = z.object({
   job_id: z.string()
 });
@@ -3116,6 +3135,12 @@ export const ImportReviewOkSchema = z.object({
 });
 export type ImportReviewOk = z.infer<typeof ImportReviewOkSchema>;
 
+export const ImportSessionSendTargetSchema = z.object({
+  target_remote_id: z.string().nullish(),
+  target_remote_name: z.string().nullish()
+});
+export type ImportSessionSendTarget = z.infer<typeof ImportSessionSendTargetSchema>;
+
 export const IngestRemoteImageRequestSchema = z.object({
   remote_url: z.string(),
   target: z.union([z.object({
@@ -4373,7 +4398,13 @@ export const MusicImportResponseSchema = z.object({
   jobs_created: z.number(),
   directories_scanned: z.number(),
   files_skipped: z.number(),
-  message: z.string()
+  message: z.string(),
+  existing_files: z.array(z.object({
+  file_path: z.string(),
+  song_id: z.string().nullish(),
+  album_id: z.string().nullish(),
+  video_id: z.string().nullish()
+}))
 });
 export type MusicImportResponse = z.infer<typeof MusicImportResponseSchema>;
 
@@ -4480,7 +4511,9 @@ export const PendingReviewSessionSchema = z.object({
   artwork_blob_id: z.string().nullish(),
   song_count: z.number(),
   pending_blob_count: z.number()
-}))
+})),
+  target_remote_id: z.string().nullish(),
+  target_remote_name: z.string().nullish()
 });
 export type PendingReviewSession = z.infer<typeof PendingReviewSessionSchema>;
 
@@ -4532,7 +4565,9 @@ export const PendingVideoReviewSessionSchema = z.object({
   episode_number: z.number().nullish()
 })),
   pending_blob_count: z.number()
-}))
+})),
+  target_remote_id: z.string().nullish(),
+  target_remote_name: z.string().nullish()
 });
 export type PendingVideoReviewSession = z.infer<typeof PendingVideoReviewSessionSchema>;
 
@@ -4604,7 +4639,9 @@ z.object({ kind: z.literal("next") }),
 z.object({ kind: z.literal("previous") }),
 z.object({ kind: z.literal("seek"), ms: z.number() }),
 z.object({ kind: z.literal("set_volume"), v: z.number() }),
-z.object({ kind: z.literal("status") })
+z.object({ kind: z.literal("status") }),
+z.object({ kind: z.literal("list_output_devices") }),
+z.object({ kind: z.literal("set_output_device"), name: z.string() })
 ]);
 export type PlayerCommand = z.infer<typeof PlayerCommandSchema>;
 
@@ -4615,7 +4652,8 @@ z.object({ kind: z.literal("track_changed"), index: z.number(), path: z.string()
 z.object({ kind: z.literal("ended") }),
 z.object({ kind: z.literal("error"), detail: ErrorDetailSchema }),
 z.object({ kind: z.literal("backend_down"), restart_count: z.number() }),
-z.object({ kind: z.literal("backend_up") })
+z.object({ kind: z.literal("backend_up") }),
+z.object({ kind: z.literal("output_devices"), devices: z.array(AudioDeviceInfoSchema) })
 ]);
 export type PlayerEvent = z.infer<typeof PlayerEventSchema>;
 
@@ -7744,6 +7782,21 @@ export const VideoSchema = z.object({
 });
 export type Video = z.infer<typeof VideoSchema>;
 
+export const VideoImportResponseSchema = z.object({
+  session_id: z.string(),
+  jobs_created: z.number(),
+  directories_scanned: z.number(),
+  files_skipped: z.number(),
+  message: z.string(),
+  existing_files: z.array(z.object({
+  file_path: z.string(),
+  song_id: z.string().nullish(),
+  album_id: z.string().nullish(),
+  video_id: z.string().nullish()
+}))
+});
+export type VideoImportResponse = z.infer<typeof VideoImportResponseSchema>;
+
 export const VideoImportReviewOkSchema = z.object({
   ok: z.boolean()
 });
@@ -7774,7 +7827,10 @@ export const VideoRenditionSchema = z.object({
   label: z.string(),
   extension: z.string(),
   mime: z.string().nullish(),
-  skipped: z.boolean()
+  skipped: z.boolean(),
+  blake3: z.string().nullish(),
+  width: z.number().nullish(),
+  height: z.number().nullish()
 });
 export type VideoRendition = z.infer<typeof VideoRenditionSchema>;
 

package/src/domains/music.ts

@@ -1818,6 +1818,21 @@ export function createMusicMethods(call: CallFn) {
       );
     },
 
+    // look up a session's send target directly - unlike
+    // listPendingImportReview, still resolves after the session's last
+    // album has been marked reviewed (see GetImportSessionTargetRequest).
+    getImportSessionTarget: (params: s.GetImportSessionTargetRequest) => {
+      return call(
+        "music",
+        "get_import_session_target",
+        routes.music.get_import_session_target.resp,
+        routes.music.get_import_session_target.req,
+        routes.music.get_import_session_target.method,
+        routes.music.get_import_session_target.path,
+        params,
+      );
+    },
+
     markAlbumReviewed: (params: s.MarkAlbumReviewedRequest) => {
       return call(
         "music",

package/src/domains/upload.ts

@@ -7,9 +7,10 @@ import {
   ImageUploadResponseSchema,
   MusicImportResponseSchema,
   MusicUploadResponseSchema,
+  VideoImportResponseSchema,
   VideoUploadResponseSchema,
 } from "../codegen/schema.js";
-import type { Transport } from "../transport.js";
+import type { Transport, UploadMetadata } from "../transport.js";
 import type { SafeParseResult } from "./types.js";
 import { toZodError } from "../errors.js";
 
@@ -51,6 +52,25 @@ export type UploadImageOptions = {
   associate?: s.AssociationHint;
 };
 
+/** "review before send" annotation - see grimoire's
+ * import_session_send_targetz. when set, the session this upload lands
+ * in gets tagged so any client (any device, any restart) can see it
+ * should ultimately be sent to this remote once reviewed. ergonomic
+ * camelCase call-site shape - converted to `UploadMetadata`'s snake_case
+ * wire fields at the `transport.upload()` boundary below. */
+export interface ImportSendTargetOptions {
+  targetRemoteId?: string;
+  targetRemoteName?: string;
+}
+
+function toUploadMetadata(options?: ImportSendTargetOptions): UploadMetadata | undefined {
+  if (!options?.targetRemoteId && !options?.targetRemoteName) return undefined;
+  return {
+    target_remote_id: options.targetRemoteId,
+    target_remote_name: options.targetRemoteName,
+  };
+}
+
 export function createUploadMethods(transport: Transport) {
   return {
     /**
@@ -61,11 +81,17 @@ export function createUploadMethods(transport: Transport) {
     music: async (
       file: File | Blob,
       onProgress?: (loaded: number, total: number) => void,
+      options?: ImportSendTargetOptions,
     ): Promise<SafeParseResult<s.MusicUploadResponse>> => {
       const formData = new FormData();
       formData.append("file", file);
 
-      const response = await transport.upload("/api/upload/music", formData, onProgress);
+      const response = await transport.upload(
+        "/api/upload/music",
+        formData,
+        onProgress,
+        toUploadMetadata(options),
+      );
       return parseResponse(response.body, response.status, MusicUploadResponseSchema);
     },
 
@@ -144,11 +170,11 @@ export function createUploadMethods(transport: Transport) {
       const formData = new FormData();
       formData.append("file", file);
 
-      if (options?.associate) {
-        formData.append("associate_with", JSON.stringify(options.associate));
-      }
+      const metadata: UploadMetadata | undefined = options?.associate
+        ? { associate_with: options.associate }
+        : undefined;
 
-      const response = await transport.upload("/api/upload/image", formData);
+      const response = await transport.upload("/api/upload/image", formData, undefined, metadata);
       return parseResponse(response.body, response.status, ImageUploadResponseSchema);
     },
 
@@ -195,11 +221,13 @@ export function createUploadMethods(transport: Transport) {
      */
     musicByPaths: async (
       paths: string[],
-      options?: { waitForCompletion?: boolean },
+      options?: { waitForCompletion?: boolean } & ImportSendTargetOptions,
     ): Promise<SafeParseResult<s.MusicImportResponse>> => {
       const body = {
         paths,
         wait_for_completion: options?.waitForCompletion ?? false,
+        target_remote_id: options?.targetRemoteId,
+        target_remote_name: options?.targetRemoteName,
       };
 
       const response = await transport.request(
@@ -209,6 +237,34 @@ export function createUploadMethods(transport: Transport) {
       );
       return parseResponse(response.body, response.status, MusicImportResponseSchema);
     },
+
+    /**
+     * import video files by filesystem paths (tauri-local only)
+     * accepts file paths or directory paths (directories are scanned recursively)
+     * bypasses file transfer since files are already local - mirrors musicByPaths
+     *
+     * @param paths - array of file or directory paths to import
+     * @param options - optional settings
+     * @param options.waitForCompletion - if true, wait for all jobs to complete (up to 5 min)
+     */
+    videoByPaths: async (
+      paths: string[],
+      options?: { waitForCompletion?: boolean } & ImportSendTargetOptions,
+    ): Promise<SafeParseResult<s.VideoImportResponse>> => {
+      const body = {
+        paths,
+        wait_for_completion: options?.waitForCompletion ?? false,
+        target_remote_id: options?.targetRemoteId,
+        target_remote_name: options?.targetRemoteName,
+      };
+
+      const response = await transport.request(
+        "POST",
+        "/api/upload/video-paths",
+        JSON.stringify(body),
+      );
+      return parseResponse(response.body, response.status, VideoImportResponseSchema);
+    },
   };
 }
 

package/src/domains/video.ts

@@ -469,6 +469,22 @@ export function createVideoMethods(call: CallFn) {
         params,
       );
     },
+
+    // sync a video by blake3 hash from a remote peer - reused for both
+    // pull-into-local (syncVideoViaLocalGrimoire.ts) and push-to-remote
+    // (sendVideoToRemote.ts): the caller decides direction purely by which
+    // instance it POSTs to and what it puts in `source_node_id`.
+    syncVideoByBlake3: (params: s.SyncVideoByBlake3Request) => {
+      return call(
+        "video",
+        "sync_video_by_blake3",
+        routes.video.sync_video_by_blake3.resp,
+        routes.video.sync_video_by_blake3.req,
+        routes.video.sync_video_by_blake3.method,
+        routes.video.sync_video_by_blake3.path,
+        params,
+      );
+    },
   };
 }
 

package/src/index.ts

@@ -31,6 +31,7 @@ export {
   CharnelLocalTransport,
   createCharnelLocalTransport,
   JobEventsStreamClosed,
+  resolveCharnelMediaSrc,
 } from "./CharnelLocalTransport.js";
 export type {
   MiddenNodeLike,

package/src/transport.ts

@@ -4,7 +4,32 @@
 // FreqholeClient uses a transport to make requests, then handles
 // Zod validation on top.
 
-import type { CloseReason, EventFilter, JobEvent, JobStateSnapshot } from "./codegen/schema.js";
+import type {
+  AssociationHint,
+  CloseReason,
+  EventFilter,
+  JobEvent,
+  JobStateSnapshot,
+} from "./codegen/schema.js";
+
+/**
+ * typed metadata for an upload, passed as `Transport.upload()`'s 4th
+ * argument. P2P/IPC transports (CharnelLocalTransport, CharnelTransport,
+ * WasmTransport) consume this object directly - no FormData string
+ * parsing involved. `HttpTransport` is the only implementation that has
+ * to fold it back into real multipart form fields, since that's what its
+ * wire format actually is. see docs/add-media-review-refactor-plan.md §6
+ * for why this replaced the previous FormData-only design.
+ */
+export interface UploadMetadata {
+  /** associate the uploaded blob with an existing entity (album/song/etc). */
+  associate_with?: AssociationHint;
+  /** "review before send" annotation - see grimoire's
+   * import_session_send_targetz - tags the resulting session as destined
+   * for this remote once reviewed. */
+  target_remote_id?: string;
+  target_remote_name?: string;
+}
 
 /**
  * response from a transport request
@@ -59,12 +84,16 @@ export interface Transport {
    *   progress event - plain fetch has no cross-browser upload progress
    *   API); P2P/tauri transports accept but ignore it since their upload
    *   path doesn't stream raw bytes over a trackable request body.
+   * @param metadata - typed upload metadata (association hint, review-before-
+   *   send target). non-HTTP transports use this directly; HttpTransport
+   *   folds it into real form fields internally.
    * @returns response with status code and body string
    */
   upload(
     path: string,
     formData: FormData,
     onProgress?: (loaded: number, total: number) => void,
+    metadata?: UploadMetadata,
   ): Promise<TransportResponse>;
 
   /**
@@ -196,7 +225,20 @@ export class HttpTransport implements Transport {
     path: string,
     formData: FormData,
     onProgress?: (loaded: number, total: number) => void,
+    metadata?: UploadMetadata,
   ): Promise<TransportResponse> {
+    // this is the one transport whose wire format actually is multipart
+    // form fields - fold the typed metadata back into FormData here so
+    // every other transport (and every caller) can deal with a plain
+    // object instead.
+    if (metadata?.associate_with) {
+      formData.append("associate_with", JSON.stringify(metadata.associate_with));
+    }
+    if (metadata?.target_remote_id) formData.append("target_remote_id", metadata.target_remote_id);
+    if (metadata?.target_remote_name) {
+      formData.append("target_remote_name", metadata.target_remote_name);
+    }
+
     const url = this.baseUrl + path;
 
     // plain fetch has no cross-browser upload-progress event, so only

package/src/uploadMetadata.test.ts

@@ -0,0 +1,142 @@
+// tests for the typed `UploadMetadata` param on `Transport.upload()` (see
+// docs/add-media-review-refactor-plan.md §6 in the tomb repo).
+//
+// previously, "review before send" target info and the image
+// `associate_with` hint were smuggled through FormData string fields that
+// every non-HTTP transport had to parse back out. now they're a plain typed
+// object passed as `upload()`'s 4th argument - only `HttpTransport` (whose
+// wire format actually is multipart form fields) converts it back to
+// FormData internally.
+
+import { describe, expect, it, vi } from "vitest";
+import { HttpTransport } from "./transport.js";
+import { createUploadMethods } from "./domains/upload.js";
+import type { Transport, TransportResponse, UploadMetadata } from "./transport.js";
+
+function okResponse(data: unknown): TransportResponse {
+  return { status: 200, body: JSON.stringify({ success: true, data }) };
+}
+
+describe("HttpTransport.upload metadata -> FormData", () => {
+  it("folds associate_with and target_remote_id/name into real form fields", async () => {
+    let capturedFormData: FormData | undefined;
+    const fetchMock = vi.fn(async (_url: string, init: RequestInit) => {
+      capturedFormData = init.body as FormData;
+      return new Response(JSON.stringify({ success: true, data: {} }), { status: 200 });
+    });
+    vi.stubGlobal("fetch", fetchMock);
+
+    const transport = new HttpTransport("https://example.test");
+    const formData = new FormData();
+    formData.append("file", new Blob(["x"]), "song.mp3");
+    const metadata: UploadMetadata = {
+      associate_with: {
+        entity_type: "album",
+        entity_id: "abc",
+      } as UploadMetadata["associate_with"],
+      target_remote_id: "remote-1",
+      target_remote_name: "my server",
+    };
+
+    await transport.upload("/api/upload/music", formData, undefined, metadata);
+
+    expect(capturedFormData).toBeDefined();
+    expect(capturedFormData!.get("target_remote_id")).toBe("remote-1");
+    expect(capturedFormData!.get("target_remote_name")).toBe("my server");
+    expect(JSON.parse(capturedFormData!.get("associate_with") as string)).toEqual({
+      entity_type: "album",
+      entity_id: "abc",
+    });
+
+    vi.unstubAllGlobals();
+  });
+
+  it("omits fields entirely when no metadata is passed", async () => {
+    let capturedFormData: FormData | undefined;
+    vi.stubGlobal(
+      "fetch",
+      vi.fn(async (_url: string, init: RequestInit) => {
+        capturedFormData = init.body as FormData;
+        return new Response(JSON.stringify({ success: true, data: {} }), { status: 200 });
+      }),
+    );
+
+    const transport = new HttpTransport("https://example.test");
+    const formData = new FormData();
+    formData.append("file", new Blob(["x"]), "song.mp3");
+
+    await transport.upload("/api/upload/music", formData);
+
+    expect(capturedFormData!.get("target_remote_id")).toBeNull();
+    expect(capturedFormData!.get("target_remote_name")).toBeNull();
+    expect(capturedFormData!.get("associate_with")).toBeNull();
+
+    vi.unstubAllGlobals();
+  });
+});
+
+describe("domains/upload.ts music()/image() metadata passthrough", () => {
+  it("music() passes targetRemoteId/targetRemoteName as typed metadata, not FormData fields", async () => {
+    let receivedFormData: FormData | undefined;
+    let receivedMetadata: UploadMetadata | undefined;
+    const fakeTransport: Pick<Transport, "upload"> = {
+      upload: async (_path, formData, _onProgress, metadata) => {
+        receivedFormData = formData;
+        receivedMetadata = metadata;
+        return okResponse({ job_id: "job-1" });
+      },
+    };
+
+    const upload = createUploadMethods(fakeTransport as Transport);
+    await upload.music(new Blob(["x"]), undefined, {
+      targetRemoteId: "remote-1",
+      targetRemoteName: "my server",
+    });
+
+    expect(receivedMetadata).toEqual({
+      target_remote_id: "remote-1",
+      target_remote_name: "my server",
+    });
+    // the send-target fields must NOT be smuggled into FormData anymore -
+    // only the file itself belongs there.
+    expect(receivedFormData!.get("target_remote_id")).toBeNull();
+    expect(receivedFormData!.get("target_remote_name")).toBeNull();
+  });
+
+  it("music() passes no metadata when no send target is given", async () => {
+    let receivedMetadata: UploadMetadata | undefined = { target_remote_id: "should-be-cleared" };
+    const fakeTransport: Pick<Transport, "upload"> = {
+      upload: async (_path, _formData, _onProgress, metadata) => {
+        receivedMetadata = metadata;
+        return okResponse({ job_id: "job-1" });
+      },
+    };
+
+    const upload = createUploadMethods(fakeTransport as Transport);
+    await upload.music(new Blob(["x"]));
+
+    expect(receivedMetadata).toBeUndefined();
+  });
+
+  it("image() passes associate_with as typed metadata, not a FormData field", async () => {
+    let receivedFormData: FormData | undefined;
+    let receivedMetadata: UploadMetadata | undefined;
+    const fakeTransport: Pick<Transport, "upload"> = {
+      upload: async (_path, formData, _onProgress, metadata) => {
+        receivedFormData = formData;
+        receivedMetadata = metadata;
+        return okResponse({ blob_id: "blob-1" });
+      },
+    };
+
+    const upload = createUploadMethods(fakeTransport as Transport);
+    const associate = {
+      entity_type: "album",
+      entity_id: "abc",
+    } as UploadMetadata["associate_with"];
+    await upload.image(new Blob(["x"]), { associate });
+
+    expect(receivedMetadata).toEqual({ associate_with: associate });
+    expect(receivedFormData!.get("associate_with")).toBeNull();
+  });
+});