From ea1590bbc7bfe80db5191cae80c3f302c8978cfa Mon Sep 17 00:00:00 2001
From: Universe <universe@grida.co>
Date: Wed, 14 Oct 2026 02:35:36 +0900
Subject: [PATCH] Download a run's outputs as one zip from the viewer
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

A run's outputs could only be saved one file at a time. The workflow's
details now offer Download all (.zip) above its outputs.

- Each file is named as the run folder's outputs/ names it (store.md §8
  "Names"): `<name><suffix>` for an output that is one file,
  `<name>/<label><suffix>` for each file of any other, long segments cut
  as the run folder cuts them. The archive is named after the run, and
  files are stored uncompressed.
- The bytes come from the viewer's artifact URLs, and each file is checked
  against its recorded size and SHA-256 before it goes in. Files the
  viewer cannot serve are left out, and the details say how many.
- One vanilla class in fx-web builds it with fflate (MIT, no
  dependencies, bundled so installed viewers stay offline); the viewer
  only mounts it.
- An archive over 2 GiB, or one the tab cannot hold, fails with an error
  that says so; each output's own link still saves it.
- The viewing guide and AGENT_READINESS say so: a viewer-only convenience,
  with --deliver and export covering the job for agents.

The website's showcases do not offer it: a zip of a recording's outputs
does not help a visitor. #87 records the idea that replaces it.

Closes #82.
---
 AGENT_READINESS.md               |   2 +-
 bun.lock                         |   7 +-
 docs/guide/07-viewing.md         |   6 ++
 web/fx-web/package.json          |   1 +
 web/fx-web/src/index.ts          |   1 +
 web/fx-web/src/outputs.ts        | 171 +++++++++++++++++++++++++++++++
 web/fx-web/tests/outputs.test.ts |  95 +++++++++++++++++
 web/viewer/src/main.tsx          |  29 ++++--
 web/viewer/src/style.css         |   2 +
 9 files changed, 304 insertions(+), 10 deletions(-)
 create mode 100644 web/fx-web/src/outputs.ts
 create mode 100644 web/fx-web/tests/outputs.test.ts

diff --git a/AGENT_READINESS.md b/AGENT_READINESS.md
index 4a94612f..b52ed294 100644
--- a/AGENT_READINESS.md
+++ b/AGENT_READINESS.md
@@ -105,7 +105,7 @@ narrower target rules.
 | Reclaim disk: `cache prune [--forget-user ID] [--yes] --json` | What would be (or was) removed per store, with the cost of the removed paid answers; or the refusals | Previews until `--yes`. Keeps everything a remaining run names; refuses (`shared_cache`, `job_outstanding`, `cache_in_use`, unreadable runs, interrupted older runs) rather than guess, and removes nothing then. `--forget-user` is the explicit statement that another project no longer uses the cache. CLI-only. |
 | Diagnose jobs: `jobs`; reconcile: `jobs --forget <key>` | Text job records; explicit deletion of a job record | Forgetting can permit a fresh paid submission. Use only after reconciling the provider outcome, not as generic failure recovery. |
 | Maintain node locks: `lock [where] --check` / `lock [where]` | Lock verification / lockfile updates | `--same` asserts unchanged behavior; it is not a way to silence a real identity change. |
-| Deliver: `run ... --deliver output=path` or SDK result delivery | Copies of available declared outputs | CLI delivery happens after execution and reports missing outputs. Preserve immutable store/placed files; copy out before editing bytes. |
+| Deliver: `run ... --deliver output=path` or SDK result delivery | Copies of available declared outputs | CLI delivery happens after execution and reports missing outputs. Preserve immutable store/placed files; copy out before editing bytes. The viewer's **Download all (.zip)** is a viewer-only convenience for a person (the same files under their `outputs/` names); agents use `--deliver` or `export`, so it has no command or SDK form. |
 
 Python and JavaScript SDKs expose planning, named execution/resume, result files
 and delivery. Each also hosts node bodies, builders and stand-ins in its language:
diff --git a/bun.lock b/bun.lock
index 28167c41..f85be4f5 100644
--- a/bun.lock
+++ b/bun.lock
@@ -7,7 +7,7 @@
     },
     "web/fx-react": {
       "name": "@grida/fx-react",
-      "version": "0.5.0",
+      "version": "0.6.0",
       "dependencies": {
         "@grida/fx-web": "workspace:*",
       },
@@ -20,8 +20,9 @@
     },
     "web/fx-web": {
       "name": "@grida/fx-web",
-      "version": "0.5.0",
+      "version": "0.6.0",
       "dependencies": {
+        "fflate": "0.8.3",
         "lucide": "1.52.0",
       },
     },
@@ -309,6 +310,8 @@
 
     "fdir": ["fdir@6.5.0", "", { "peerDependencies": { "picomatch": "^3 || ^4" }, "optionalPeers": ["picomatch"] }, "sha512-tIbYtZbucOs0BRGqPJkshJUYdL+SDH7dVM8gjy+ERp3WAUjLEFJE+02kanyHtwjWOnwrKYBiwAmM0p4kLJAnXg=="],
 
+    "fflate": ["fflate@0.8.3", "", {}, "sha512-tbZNuJrLwGUp3zshBtdy4W+ORxZuIh8a5ilyIEQDC5rY1f3U20JMry0Ll3WBzU58EZKsEuJFXhb5gwv8CsPvgA=="],
+
     "framer-motion": ["framer-motion@14.0.0", "", { "dependencies": { "motion-dom": "14.0.0", "motion-utils": "14.0.0", "tslib": "^2.4.0" }, "peerDependencies": { "react": "^18.0.0 || ^19.0.0", "react-dom": "^18.0.0 || ^19.0.0" }, "optionalPeers": ["react", "react-dom"] }, "sha512-QAtHmybrDFSliyW1sexMtSQTQd+1jw2ajibEmzpuI4XdPVzQkn+dAzJMm2sW3pl9MJuSS4xN51djQ7huhlP/VA=="],
 
     "fsevents": ["fsevents@2.3.3", "", { "os": "darwin" }, "sha512-5xoDfX+fL7faATnagmWPpbFtwh/R77WmMMqqHGS65C3vvB0YHrgF+B1YmZ3441tMj5n63k0212XNoJwzlhffQw=="],
diff --git a/docs/guide/07-viewing.md b/docs/guide/07-viewing.md
index 04e76b5e..ddff3121 100644
--- a/docs/guide/07-viewing.md
+++ b/docs/guide/07-viewing.md
@@ -65,6 +65,12 @@ open it. Under the title is the step's id (`state['waving'].draw#1`), the same o
 to ask an agent about that exact step. Select the workflow's name in the bar for the
 workflow's own inputs, outputs and notices, and the run's name. Esc, the background
 or × closes them; a second Esc closes the step list.
+
+In a run's details, **Download all (.zip)** saves its output files in one zip named after
+the run, each under its name in the run folder's `outputs/` (`hero.png`, `looks/ada.png`).
+Files the viewer cannot serve are left out, and the details say how many. A zip too large
+for the browser tab fails and says so; each output's own link still saves it. To put
+outputs in your project, use `run --deliver`.
 Identities, digests and raw records stay on the command line
 (`grida fx inspect runs/example --json`).
 
diff --git a/web/fx-web/package.json b/web/fx-web/package.json
index 656036fb..616e672e 100644
--- a/web/fx-web/package.json
+++ b/web/fx-web/package.json
@@ -7,6 +7,7 @@
   "type": "module",
   "exports": { ".": "./src/index.ts", "./canvas.css": "./src/canvas.css" },
   "dependencies": {
+    "fflate": "0.8.3",
     "lucide": "1.52.0"
   }
 }
diff --git a/web/fx-web/src/index.ts b/web/fx-web/src/index.ts
index 31ceabe8..e5b69ed5 100644
--- a/web/fx-web/src/index.ts
+++ b/web/fx-web/src/index.ts
@@ -192,3 +192,4 @@ export * from "./service";
 export * from "./export";
 export * from "./export-controller";
 export * from "./values";
+export * from "./outputs";
diff --git a/web/fx-web/src/outputs.ts b/web/fx-web/src/outputs.ts
new file mode 100644
index 00000000..5337eb20
--- /dev/null
+++ b/web/fx-web/src/outputs.ts
@@ -0,0 +1,171 @@
+import { Zip, ZipPassThrough } from "fflate";
+
+/** One file of a run's declared outputs. */
+export interface OutputFile {
+  /** Its name in the run folder's `outputs/` (spec/store.md §8 "Names"), before [`placedName`] cuts long segments. */
+  name: string;
+  digest: string;
+  kind: string;
+  size: number;
+  /** Where the viewer serves its bytes; null when it cannot. */
+  url: string | null;
+}
+
+/** The first suffix identity.md §4 lists for each kind, the one a run folder writes; `annotations` takes `.json`. */
+const SUFFIXES = new Map(Object.entries({
+  "image/png": ".png", "image/jpeg": ".jpg", "image/webp": ".webp", "image/gif": ".gif",
+  "text/markdown": ".md", "text/plain": ".txt", json: ".json", annotations: ".json", "text/yaml": ".yaml", "text/toml": ".toml", "text/html": ".html",
+  "audio/wav": ".wav", "audio/mpeg": ".mp3", "audio/ogg": ".ogg", "video/mp4": ".mp4", "video/webm": ".webm", "video/x-matroska": ".mkv",
+  "model/gltf-binary": ".glb", "model/gltf+json": ".gltf", "model/fbx": ".fbx", "file/zip": ".zip",
+}));
+/** What one file-system name holds, in UTF-8 bytes (store.md §8 "Length"). */
+const NAME_BYTES = 255;
+/** A zip without ZIP64 holds at most 4 GiB, and a tab often cannot hold half that. */
+const ARCHIVE_LIMIT = 2 * 1024 ** 3;
+const TOO_LARGE = "These outputs are too large for this tab to put in one zip. Save each output from its own link.";
+
+const record = (value: unknown): value is Record<string, unknown> => typeof value === "object" && value !== null && !Array.isArray(value);
+const utf8 = new TextEncoder();
+
+/** A step path as one name: anything but a letter, a digit, `.`, `_` or `-` becomes `_`, outer `_` go, empty is `step`. */
+function safeName(text: string) {
+  return [...text].map((char) => /[\p{L}\p{N}._-]/u.test(char) ? char : "_").join("").replace(/^_+|_+$/g, "") || "step";
+}
+
+/** A key as a path: split at `/`, an empty, `.` or `..` segment becomes `_`, every other one a [`safeName`]. */
+function keyedPath(key: string) {
+  return key.split("/").map((segment) => ["", ".", ".."].includes(segment) ? "_" : safeName(segment)).join("/");
+}
+
+function named(label: string, kind: string) {
+  const suffix = SUFFIXES.get(kind) ?? "";
+  return !suffix || label.endsWith(suffix) ? label : label + suffix;
+}
+
+async function sha256(bytes: Uint8Array<ArrayBuffer>) {
+  return Array.from(new Uint8Array(await crypto.subtle.digest("SHA-256", bytes)), (part) => part.toString(16).padStart(2, "0")).join("");
+}
+
+/**
+ * Each segment of `name` cut to one file-system name, as the run folder cuts it: a longer one keeps
+ * its first whole characters, then `~`, 16 hex characters of its SHA-256 and, last, its suffix.
+ */
+export async function placedName(file: Pick<OutputFile, "name" | "kind">) {
+  const suffix = SUFFIXES.get(file.kind) ?? "";
+  const segments = file.name.split("/");
+  return (await Promise.all(segments.map(async (segment, index) => {
+    const bytes = utf8.encode(segment);
+    if (bytes.length <= NAME_BYTES) return segment;
+    const kept = index === segments.length - 1 && segment.endsWith(suffix) ? suffix : "";
+    let stem = "", room = NAME_BYTES - 1 - 16 - kept.length;
+    for (const char of segment.slice(0, segment.length - kept.length)) {
+      room -= utf8.encode(char).length;
+      if (room < 0) break;
+      stem += char;
+    }
+    return `${stem}~${(await sha256(bytes)).slice(0, 16)}${kept}`;
+  }))).join("/");
+}
+
+/** A value's files in order (a list's items, a collection's in collection order), each with its key or its item's. */
+function filesOf(value: unknown, itemKey: string | null, found: { file: Record<string, unknown>; key: string | null }[]) {
+  if (!record(value)) return found;
+  if (record(value.file)) {
+    const { file } = value;
+    if (typeof file.digest === "string" && /^[a-f0-9]{64}$/.test(file.digest) && typeof file.kind === "string" && Number.isSafeInteger(file.size)) {
+      found.push({ file, key: (typeof file.key === "string" && file.key) || itemKey || null });
+    }
+  } else if (Array.isArray(value.list)) {
+    for (const item of value.list) filesOf(item, null, found);
+  } else if (Array.isArray(value.collection)) {
+    for (const entry of value.collection) if (Array.isArray(entry) && entry.length === 2 && typeof entry[0] === "string") filesOf(entry[1], entry[0], found);
+  }
+  return found;
+}
+
+/**
+ * The files of a run's declared outputs, named as its run folder's `outputs/` names them: an output
+ * that is one file is `<name><suffix>`; each file of any other is `<name>/<label><suffix>`, its label
+ * its key as a path, else its position among the output's files. `locate` gives a file's URL.
+ */
+export function outputFiles(outputs: Record<string, unknown>, locate: (digest: string) => string | null): OutputFile[] {
+  return Object.entries(outputs).flatMap(([output, value]) => filesOf(value, null, []).map(({ file, key }, index) => ({
+    name: named(record(value) && record(value.file) ? output : `${output}/${key === null ? index : keyedPath(key)}`, file.kind as string),
+    digest: file.digest as string,
+    kind: file.kind as string,
+    size: file.size as number,
+    url: locate(file.digest as string),
+  })));
+}
+
+export interface ArchiveOptions { fetcher?: typeof fetch; signal?: AbortSignal; limit?: number }
+
+/**
+ * The files that have a URL in one uncompressed zip (media is compressed already), each checked
+ * against its recorded size and digest. A later file at a name replaces an earlier one, as in the
+ * run folder. Refuses, before reading anything, files that come to more than `limit` bytes.
+ */
+export async function outputArchive(files: OutputFile[], { fetcher = fetch, signal, limit = ARCHIVE_LIMIT }: ArchiveOptions = {}): Promise<Blob> {
+  const entries = new Map<string, OutputFile>();
+  for (const file of files) if (file.url !== null) { const name = await placedName(file); entries.delete(name); entries.set(name, file); }
+  const total = [...entries.values()].reduce((sum, file) => sum + file.size, 0);
+  if (total > limit) throw new Error(`These outputs come to ${(total / 1024 ** 3).toFixed(1)} GB, more than this tab can put in one zip. Save each output from its own link.`);
+  const chunks: Uint8Array<ArrayBuffer>[] = [];
+  const failures: Error[] = [];
+  const zip = new Zip((error, chunk) => { if (error) failures.push(error); else chunks.push(chunk); });
+  for (const [name, file] of entries) {
+    const response = await fetcher(file.url!, { signal });
+    if (!response.ok) throw new Error(`${file.name} could not be read (HTTP ${response.status}).`);
+    const bytes = new Uint8Array(await response.arrayBuffer());
+    if (bytes.length !== file.size || await sha256(bytes) !== file.digest) throw new Error(`${file.name} is not the file the run recorded.`);
+    const entry = new ZipPassThrough(name);
+    zip.add(entry);
+    entry.push(bytes, true);
+  }
+  zip.end();
+  if (failures.length) throw failures[0];
+  return new Blob(chunks, { type: "application/zip" });
+}
+
+export interface OutputArchiveState { building: boolean; error: string | null }
+
+/** Puts a run's output files in one zip and saves it; the viewer only mounts it. */
+export class OutputArchiveController {
+  private state: OutputArchiveState = { building: false, error: null };
+  private listeners = new Set<() => void>();
+  private request: AbortController | null = null;
+
+  constructor(private readonly options: Omit<ArchiveOptions, "signal"> & { save?: (archive: Blob, name: string) => void } = {}) {}
+
+  getSnapshot = () => this.state;
+  subscribe = (listener: () => void) => { this.listeners.add(listener); return () => { this.listeners.delete(listener); }; };
+  private update(next: OutputArchiveState) { this.state = next; this.listeners.forEach((listener) => listener()); }
+
+  /** Saves `files` as `<name>.zip`. */
+  download = async (files: OutputFile[], name: string) => {
+    this.request?.abort();
+    const request = new AbortController();
+    this.request = request;
+    this.update({ building: true, error: null });
+    try {
+      const archive = await outputArchive(files, { ...this.options, signal: request.signal });
+      if (request.signal.aborted) return;
+      (this.options.save ?? save)(archive, `${name}.zip`);
+      this.update({ building: false, error: null });
+    } catch (error) {
+      if (request.signal.aborted) return;
+      this.update({ building: false, error: error instanceof RangeError ? TOO_LARGE : error instanceof Error ? error.message : "The outputs could not be zipped." });
+    }
+  };
+
+  dispose() { this.request?.abort(); }
+}
+
+function save(archive: Blob, name: string) {
+  const link = Object.assign(document.createElement("a"), { href: URL.createObjectURL(archive), download: name });
+  document.body.append(link);
+  link.click();
+  link.remove();
+  // Revoked later: some browsers still read the URL after the click returns.
+  setTimeout(() => URL.revokeObjectURL(link.href), 60_000);
+}
diff --git a/web/fx-web/tests/outputs.test.ts b/web/fx-web/tests/outputs.test.ts
new file mode 100644
index 00000000..a7df5cbd
--- /dev/null
+++ b/web/fx-web/tests/outputs.test.ts
@@ -0,0 +1,95 @@
+import { describe, expect, test } from "bun:test";
+import { unzipSync } from "fflate";
+import { OutputArchiveController, outputArchive, outputFiles, placedName, type OutputFile } from "../src/index";
+
+const bytes = (text: string) => new TextEncoder().encode(text);
+const hash = (data: Uint8Array) => new Bun.CryptoHasher("sha256").update(data).digest("hex");
+const contents = new Map<string, Uint8Array>();
+/** A recorded file value holding `text`. */
+function file(text: string, kind = "image/png", key?: string) {
+  const data = bytes(text);
+  contents.set(hash(data), data);
+  return { file: { digest: hash(data), kind, name: "ignored.bin", size: data.length, ...(key ? { key } : {}) } };
+}
+const locate = (digest: string) => `https://assets.example.com/artifacts/${digest}`;
+const fetcher = (async (url: string) => {
+  const data = contents.get(url.split("/").pop()!);
+  return data ? new Response(data) : new Response(null, { status: 404 });
+}) as unknown as typeof fetch;
+async function unzip(files: OutputFile[]) {
+  return Object.fromEntries(Object.entries(unzipSync(new Uint8Array(await (await outputArchive(files, { fetcher })).arrayBuffer()))).map(([name, data]) => [name, new TextDecoder().decode(data)]));
+}
+
+describe("run output archive", () => {
+  test("names each file as the run folder's outputs/ does", () => {
+    const files = outputFiles({
+      hero: file("hero"),
+      notes: file("{}", "json"),
+      raw: file("raw", "file"),
+      sheet: { list: [file("a"), file("b", "image/jpeg")] },
+      looks: { collection: [["ada", file("ada")], ["hero.png", file("again")], ["a b/../c", file("deep")], ["", file("blank")]] },
+      own: { list: [file("own", "image/png", "keyed")] },
+      text: { value: "not a file" },
+    }, locate);
+    expect(files.map((item) => item.name)).toEqual([
+      "hero.png", "notes.json", "raw",
+      "sheet/0.png", "sheet/1.jpg",
+      "looks/ada.png", "looks/hero.png", "looks/a_b/_/c.png", "looks/3.png",
+      "own/keyed.png",
+    ]);
+    expect(files[0]).toEqual({ name: "hero.png", digest: hash(bytes("hero")), kind: "image/png", size: 4, url: locate(hash(bytes("hero"))) });
+  });
+
+  test("a single file in a list or a collection still gets a folder", () => {
+    expect(outputFiles({ one: { list: [file("x")] }, keyed: { collection: [["k", file("x")]] } }, locate).map((item) => item.name)).toEqual(["one/0.png", "keyed/k.png"]);
+  });
+
+  test("cuts a long segment as the run folder does", async () => {
+    const long = "k".repeat(300);
+    expect(await placedName({ name: `looks/${long}.png`, kind: "image/png" })).toBe(`looks/${"k".repeat(234)}~8830571039dc4b0d.png`);
+    expect(await placedName({ name: `${"é".repeat(200)}/a.png`, kind: "image/png" })).toBe(`${"é".repeat(119)}~df20b2aa6262e99e/a.png`);
+  });
+
+  test("zips the available files uncompressed, leaving out those with no URL", async () => {
+    const files = outputFiles({ hero: file("hero"), looks: { collection: [["ada", file("ada")], ["bo", file("bo")]] } }, (digest) => digest === hash(bytes("bo")) ? null : locate(digest));
+    expect(files.filter((item) => item.url === null).map((item) => item.name)).toEqual(["looks/bo.png"]);
+    expect(await unzip(files)).toEqual({ "hero.png": "hero", "looks/ada.png": "ada" });
+    const archive = new Uint8Array(await (await outputArchive(files, { fetcher })).arrayBuffer());
+    // Local file header: compression method 0, stored.
+    expect(archive[8] | (archive[9] << 8)).toBe(0);
+  });
+
+  test("a later file replaces an earlier one at the same name", async () => {
+    expect(await unzip(outputFiles({ looks: { collection: [["a b", file("first")], ["a_b", file("second")]] } }, locate))).toEqual({ "looks/a_b.png": "second" });
+  });
+
+  test("refuses bytes that are not the recorded file", async () => {
+    const [hero] = outputFiles({ hero: file("hero") }, locate);
+    contents.set(hero.digest, bytes("evil"));
+    await expect(outputArchive([hero], { fetcher })).rejects.toThrow("hero.png is not the file the run recorded.");
+    contents.set(hero.digest, bytes("hero"));
+    await expect(outputArchive([{ ...hero, url: locate("0".repeat(64)) }], { fetcher })).rejects.toThrow("hero.png could not be read (HTTP 404).");
+  });
+
+  test("refuses an archive too large for the tab before reading anything", async () => {
+    let reads = 0;
+    const counting = (async () => { reads += 1; return new Response(null); }) as unknown as typeof fetch;
+    const files = outputFiles({ hero: file("hero") }, locate);
+    await expect(outputArchive(files, { fetcher: counting, limit: 3 })).rejects.toThrow("more than this tab can put in one zip");
+    expect(reads).toBe(0);
+  });
+
+  test("the controller saves <run>.zip and reports a failure", async () => {
+    const saved: string[] = [];
+    const controller = new OutputArchiveController({ fetcher, save: (_, name) => saved.push(name) });
+    const files = outputFiles({ hero: file("hero") }, locate);
+    const states: boolean[] = [];
+    controller.subscribe(() => states.push(controller.getSnapshot().building));
+    await controller.download(files, "run-01");
+    expect(saved).toEqual(["run-01.zip"]);
+    expect(states).toEqual([true, false]);
+    await controller.download([{ ...files[0], url: locate("0".repeat(64)) }], "run-01");
+    expect(controller.getSnapshot()).toEqual({ building: false, error: "hero.png could not be read (HTTP 404)." });
+    expect(saved).toEqual(["run-01.zip"]);
+  });
+});
diff --git a/web/viewer/src/main.tsx b/web/viewer/src/main.tsx
index 77f97572..e8c847ab 100644
--- a/web/viewer/src/main.tsx
+++ b/web/viewer/src/main.tsx
@@ -1,7 +1,7 @@
-import { StrictMode, useEffect, useRef, useState, useSyncExternalStore, type ReactNode } from "react";
+import { StrictMode, useEffect, useMemo, useRef, useState, useSyncExternalStore, type ReactNode } from "react";
 import { createRoot } from "react-dom/client";
-import { ArrowLeft, ArrowUpRight, Check, ChevronRight, Copy, FileText, List, RefreshCw, Square, Workflow, X } from "lucide-react";
-import { ServiceIndexProjection, ViewerController, elapsedLabel, ownsKeys, ViewerEntryController, type Artifact, type CanvasStep, type GraphDocument, type GraphInstance, type PendingRepeat, type ServiceEntry, type ServiceIndex, type ViewerRun } from "@grida/fx-web";
+import { ArrowLeft, ArrowUpRight, Check, ChevronRight, Copy, Download, FileText, List, RefreshCw, Square, Workflow, X } from "lucide-react";
+import { OutputArchiveController, ServiceIndexProjection, ViewerController, elapsedLabel, outputFiles, ownsKeys, ViewerEntryController, type Artifact, type CanvasStep, type GraphDocument, type GraphInstance, type PendingRepeat, type ServiceEntry, type ServiceIndex, type ViewerRun } from "@grida/fx-web";
 import { StateIcon, StateLabel, Status, Values, WorkflowCanvas, money, type WorkflowCanvasHandle } from "@grida/fx-react";
 import "./style.css";
 
@@ -10,9 +10,9 @@ const apiBase = entryController.route?.api_base ?? "/api";
 const controller = new ViewerController(undefined, { apiBase });
 const iconProps = { size: 14, strokeWidth: 1.5, "aria-hidden": true } as const;
 
-/** A titled set of named values; nothing when the set is empty. */
-function Section({ title, values, artifacts }: { title: string; values: Record<string, unknown>; artifacts: Map<string, Artifact> }) {
-  return Object.keys(values).length > 0 && <section className="fx-detail-section"><h3>{title}</h3><Values values={values} artifacts={artifacts} /></section>;
+/** A titled set of named values, after `children`; nothing when the set is empty. */
+function Section({ title, values, artifacts, children }: { title: string; values: Record<string, unknown>; artifacts: Map<string, Artifact>; children?: ReactNode }) {
+  return Object.keys(values).length > 0 && <section className="fx-detail-section"><h3>{title}</h3>{children}<Values values={values} artifacts={artifacts} /></section>;
 }
 
 /** Copies `text`, and says so for a moment. */
@@ -83,6 +83,21 @@ function Problem({ children }: { children: ReactNode }) {
   return <p role="alert" className="fx-detail-problem">{children}</p>;
 }
 
+/** Download all (.zip): the run's output files the viewer can serve, named as in its `outputs/`. */
+function OutputsDownload({ run, artifacts }: { run: ViewerRun; artifacts: Map<string, Artifact> }) {
+  const files = outputFiles(run.outputs, (digest) => { const artifact = artifacts.get(digest); return artifact?.available ? artifact.url : null; });
+  const archive = useMemo(() => new OutputArchiveController(), []);
+  const { building, error } = useSyncExternalStore(archive.subscribe, archive.getSnapshot);
+  useEffect(() => () => archive.dispose(), [archive]);
+  const left = files.filter((file) => file.url === null).length;
+  if (left === files.length) return null;
+  return <div className="fx-detail-download">
+    <button onClick={() => void archive.download(files, run.run_name)} disabled={building} className="fx-action"><Download {...iconProps} />{building ? "Zipping…" : "Download all (.zip)"}</button>
+    {left > 0 && <p className="fx-value-note">{left} {left === 1 ? "file is" : "files are"} not available and left out.</p>}
+    {error && <Problem>{error}</Problem>}
+  </div>;
+}
+
 function PlanDetails({ plan, instance, pending, canvasNode }: { plan: GraphDocument; instance?: GraphInstance; pending?: PendingRepeat; canvasNode?: CanvasStep }) {
   const none = new Map<string, Artifact>();
   if (pending) return <Heading title={pending.path} id={pending.path} kind="step path" state="unexpanded" meta={[`up to ${pending.max} items`, pending.high_usd > 0 && `at most ${money(pending.high_usd)}`]} />;
@@ -108,7 +123,7 @@ function RunDetails({ run, node, canvasNode }: { run: ViewerRun; node?: ViewerRu
   if (!node) return <>
     <Heading title={run.workflow.title} id={run.run_name} kind="run name" meta={[run.workflow.id]} />
     {run.workflow.description && <p className="fx-detail-copy">{run.workflow.description}</p>}
-    <Section title="Outputs" values={run.outputs} artifacts={artifacts} />
+    <Section title="Outputs" values={run.outputs} artifacts={artifacts}><OutputsDownload run={run} artifacts={artifacts} /></Section>
     <Section title="Inputs" values={run.inputs} artifacts={artifacts} />
   </>;
   const [inputs, settings] = split(node.with, canvasNode);
diff --git a/web/viewer/src/style.css b/web/viewer/src/style.css
index b5156d16..2e780bb6 100644
--- a/web/viewer/src/style.css
+++ b/web/viewer/src/style.css
@@ -66,6 +66,8 @@ button { touch-action: manipulation; }
 .fx-detail-problem { margin-top: 10px; padding: 8px 10px; border-radius: 4px; background: #fdf4f4; color: #a14c57; font-size: 11px; line-height: 17px; white-space: pre-wrap; overflow-wrap: anywhere; }
 .fx-detail-section { margin-top: 18px; }
 .fx-detail-section > h3 { margin-bottom: 8px; color: #71717a; font-size: 10px; font-weight: 600; line-height: 14px; }
+.fx-detail-download { display: grid; justify-items: start; gap: 6px; margin-bottom: 12px; }
+.fx-detail-download .fx-detail-problem { margin-top: 0; }
 .fx-values { display: grid; gap: 10px; margin: 0; }
 .fx-values > div { display: grid; gap: 4px; }
 .fx-values dt { color: #8b8b94; font-family: var(--font-mono); font-size: 10px; line-height: 14px; overflow-wrap: anywhere; }