From 355a16e4468bb6e2e00392173d7c30032c117337 Mon Sep 17 00:00:00 2001
From: James Thiessen <25james1234@gmail.com>
Date: Mon, 27 Apr 2026 17:40:36 -0500
Subject: [PATCH 1/4] Add waypoints feature with polished UI

- Add runChain.ts to orchestrate chained conversions through waypoints
- Update main.ts with waypoint state management and rendering
- Polish via/waypoints section: clearer labels, hover states, animations,
  self-explanatory round-trip button, entry animation on chips
- Add chainOrchestrator tests and update README/CLAUDE.md

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
---
 CLAUDE.md                               |  78 ++++++++++
 README.md                               |  18 +++
 index.html                              |  23 +++
 src/main.ts                             | 196 ++++++++++++++++++++++--
 src/runChain.ts                         |  85 ++++++++++
 style.css                               | 175 ++++++++++++++++++++-
 test/handlers/chainOrchestrator.test.ts | 136 ++++++++++++++++
 7 files changed, 693 insertions(+), 18 deletions(-)
 create mode 100644 CLAUDE.md
 create mode 100644 src/runChain.ts
 create mode 100644 test/handlers/chainOrchestrator.test.ts

diff --git a/CLAUDE.md b/CLAUDE.md
new file mode 100644
index 00000000..fb761481
--- /dev/null
+++ b/CLAUDE.md
@@ -0,0 +1,78 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Commands
+
+```bash
+# Install dependencies (requires Bun)
+bun install
+
+# Development server
+bunx vite
+
+# Production build
+bun run build
+
+# Run tests
+bun test
+
+# Run a single test file
+bun test test/TraversionGraph.test.ts
+
+# Generate format cache (run after build; uses puppeteer/Chromium — slow first run)
+bun run cache:build
+
+# Type-check only (no emit)
+bunx tsc --noEmit
+
+# Docker (prebuilt image)
+docker compose -f docker/docker-compose.yml up -d
+
+# Docker (local build)
+docker compose -f docker/docker-compose.yml -f docker/docker-compose.override.yml up --build -d
+```
+
+## Architecture
+
+The app is a **browser-based, privacy-first file converter** that runs all conversions client-side. It supports cross-medium conversion (e.g. AVI → PDF) by chaining multiple handlers together.
+
+### Core abstractions (`src/`)
+
+- **`FormatHandler.ts`** — Defines the key interfaces:
+  - `FileFormat` — a format with MIME, extension, `from`/`to` booleans, `internal` ref, `category`, and `lossless` flag.
+  - `FileData` — `{ name: string, bytes: Uint8Array }`. Handlers own the buffer's lifetime; clone with `new Uint8Array()` if mutation is possible.
+  - `FormatHandler` — interface all handlers implement: `name`, `supportedFormats`, `ready`, `init()`, `doConvert()`. Optional `supportAnyInput` flag marks generic "catch-all" handlers (e.g. archive wrappers).
+  - `FormatDefinition` / `builder()` — fluent API for defining formats in handlers (`.allowFrom()`, `.allowTo()`, `.markLossless()`, etc.).
+
+- **`TraversionGraph.ts`** — Dijkstra's algorithm over the format graph. Nodes are unique formats (identified by `mime(format)`); edges are handler-provided conversions. Cost factors: depth, category-change penalties, lossy multiplier, handler/format priority index. `searchPath()` is an async generator yielding candidate paths. Handlers registered with `supportAnyInput` get edges from every known node to their output formats (with an `ANY_INPUT_COST` penalty to prefer specific paths).
+
+- **`CommonFormats.ts`** — Pre-built `FormatDefinition` instances (PNG, JPEG, MP4, MP3, PDF, etc.) and the `Category` enum (`image`, `video`, `audio`, `text`, `document`, `archive`, `data`, `vector`, `font`, `code`, `spreadsheet`, `presentation`). Reuse these in handlers to avoid duplicate format definitions.
+
+- **`PriorityQueue.ts`** — Min-heap used by `TraversionGraph`.
+
+### Handlers (`src/handlers/`)
+
+Each handler wraps one conversion tool. Naming convention: file `foo.ts`, class `fooHandler`, registered in `src/handlers/index.ts`. Handler order in `index.ts` matters — it affects the `handlerIndex` cost term in pathfinding (earlier = slightly preferred).
+
+Key handlers: `FFmpeg.ts` (video/audio), `ImageMagick.ts` (images), `pandoc.ts` (documents), `font.ts`, `threejs.ts` (3D), `sevenZip.ts`, `sqlite.ts`, and ~60 others.
+
+**WASM dependencies** must be declared in `vite.config.js` under `viteStaticCopy` targets, served from `/convert/wasm/`. Never link directly to `node_modules` for WASM. External git-repo dependencies are added as submodules under `src/handlers/`.
+
+### Format cache
+
+On first load, the app builds the supported-format map by calling `init()` on every handler. This is slow (~seconds). The result can be serialized to `cache.json` via `printSupportedFormatCache()` in the browser console, then rebuilt offline with `bun run cache:build`. Disable the cache when testing handler changes.
+
+### Build targets
+
+- **Web** — Vite SPA served under `/convert/` base path.
+- **Electron** — `src/electron.cjs` is the main process; built with `IS_DESKTOP=true`.
+- **Docker** — nginx serves the built output; Dockerfile installs Chromium for `buildCache.js`.
+
+### Testing
+
+- `test/TraversionGraph.test.ts` — graph traversal unit tests.
+- `test/commonFormats.test.ts` — format definition tests.
+- `test/handlers/<handlerName>.test.ts` — optional per-handler unit tests (add for handlers with non-trivial parsing/serialization logic).
+- `test/MockedHandler.ts` — test utility for creating stub handlers.
+- Test resources live in `test/resources/`.
diff --git a/README.md b/README.md
index 16705757..7ab9b17d 100644
--- a/README.md
+++ b/README.md
@@ -18,6 +18,24 @@ For a semi-technical overview of this tool, check out the video: https://youtu.b
 5. Click **Convert**!
 6. Hopefully, after a bit (or a lot) of thinking, the program will spit out the file you wanted. If not, see the "Issues" section below.
 
+### Chained / waypoint conversion
+
+Between the "Convert from" and "Convert to" columns is a **Via (optional)** panel. It lets you force the conversion through one or more intermediate formats in a single click — no re-uploading required.
+
+**Example — PNG → WAV → PNG (round-trip / reinterpretation):**
+
+1. Drop a PNG and let the tool auto-select it as the input format.
+2. Click **Round trip ↺** to automatically mirror the input as the output (PNG → PNG).
+3. Click **+ Add intermediate format** and pick **WAV** from the picker.
+4. Click **Convert**. One download arrives: the final PNG.
+
+**Tips:**
+
+- Add as many waypoints as you like by clicking **+ Add intermediate format** multiple times.
+- Remove a waypoint by clicking **×** on its chip.
+- Tick **Also download intermediate files** to also receive each leg's output (e.g. the WAV above).
+- Switching between Simple / Advanced mode clears the waypoint list.
+
 ## Issues
 
 Ever since the YouTube video released, we've been getting spammed with issues suggesting the addition of all kinds of niche file formats. To keep things organized, I've decided to specify what counts as a valid issue and what doesn't.
diff --git a/index.html b/index.html
index f85e0f68..dc0f15bd 100644
--- a/index.html
+++ b/index.html
@@ -41,6 +41,20 @@ <h2>Convert from:</h2>
       </div>
     </div>
 
+    <div id="via-container" class="format-container">
+      <h2>Waypoints <span class="via-optional">(optional)</span></h2>
+      <p class="via-hint">Force conversion through a specific intermediate format</p>
+      <div id="via-list" class="via-list"></div>
+      <div id="via-controls">
+        <button id="add-via" type="button">+ Add waypoint</button>
+        <button id="round-trip" type="button">&#x21BA; Output same format as input</button>
+        <label class="via-toggle">
+          <input id="dl-intermediates" type="checkbox">
+          Also download intermediate files
+        </label>
+      </div>
+    </div>
+
     <div id="to-container" class="format-container">
       <h2>Convert to:</h2>
       <input type="text" id="search-to" class="search" placeholder="Search">
@@ -53,6 +67,15 @@ <h2>Convert to:</h2>
 
   <button id="convert-button" class="disabled">Convert</button>
 
+  <dialog id="via-picker">
+    <div class="via-picker-inner">
+      <h2>Add a waypoint</h2>
+      <input type="text" id="search-via" class="search" placeholder="Search">
+      <div id="via-picker-list" class="format-list"></div>
+      <button id="via-picker-cancel" type="button">Cancel</button>
+    </div>
+  </dialog>
+
   <div id="popup-bg"></div>
   <div id="popup">
     <h2>Loading tools...</h2>
diff --git a/src/main.ts b/src/main.ts
index 0298e2eb..feda045c 100644
--- a/src/main.ts
+++ b/src/main.ts
@@ -2,6 +2,8 @@ import type { FileFormat, FileData, FormatHandler, ConvertPathNode } from "./For
 import normalizeMimeType from "./normalizeMimeType.js";
 import handlers from "./handlers";
 import { TraversionGraph } from "./TraversionGraph.js";
+import { runChain } from "./runChain.js";
+import type { FormatOption, SegmentRunner } from "./runChain.js";
 
 /** Files currently selected for conversion */
 let selectedFiles: File[] = [];
@@ -13,6 +15,9 @@ let selectedFiles: File[] = [];
  */
 let simpleMode: boolean = true;
 
+let waypointOptions: FormatOption[] = [];
+let downloadIntermediates = false;
+
 const ui = {
   fileInput: document.querySelector("#file-input") as HTMLInputElement,
   fileSelectArea: document.querySelector("#file-area") as HTMLDivElement,
@@ -26,6 +31,8 @@ const ui = {
   popupBackground: document.querySelector("#popup-bg") as HTMLDivElement
 };
 
+const viaPicker = document.querySelector("#via-picker") as HTMLDialogElement;
+
 /**
  * Filters a list of butttons to exclude those not matching a substring.
  * @param list Button list (div) to filter.
@@ -67,6 +74,46 @@ const searchHandler = (event: Event) => {
 // Assign search handler to both search boxes
 ui.inputSearch.oninput = searchHandler;
 ui.outputSearch.oninput = searchHandler;
+(document.querySelector("#search-via") as HTMLInputElement).oninput = (event) => {
+  const input = event.target as HTMLInputElement;
+  filterButtonList(
+    document.querySelector("#via-picker-list") as HTMLDivElement,
+    input.value.toLowerCase()
+  );
+};
+
+function renderWaypoints() {
+  const viaList = document.querySelector("#via-list") as HTMLDivElement;
+  viaList.innerHTML = "";
+  waypointOptions.forEach((opt, i) => {
+    const chip = document.createElement("div");
+    chip.className = "via-chip";
+
+    if (waypointOptions.length > 1) {
+      const step = document.createElement("span");
+      step.className = "via-chip-step";
+      step.textContent = `${i + 1} of ${waypointOptions.length}`;
+      chip.appendChild(step);
+    }
+
+    const label = document.createElement("span");
+    label.className = "via-chip-label";
+    label.textContent = opt.format.format.toUpperCase();
+
+    const remove = document.createElement("button");
+    remove.className = "via-chip-remove";
+    remove.type = "button";
+    remove.textContent = "×";
+    remove.onclick = () => {
+      waypointOptions.splice(i, 1);
+      renderWaypoints();
+    };
+
+    chip.appendChild(label);
+    chip.appendChild(remove);
+    viaList.appendChild(chip);
+  });
+}
 
 // Map clicks in the file selection area to the file input element
 ui.fileSelectArea.onclick = () => {
@@ -195,6 +242,48 @@ window.printSupportedFormatCache = () => {
   return JSON.stringify(entries, null, 2);
 }
 
+function buildPickerList() {
+  const pickerList = document.querySelector("#via-picker-list") as HTMLDivElement;
+  pickerList.innerHTML = "";
+  const seen = new Set<string>();
+
+  for (let i = 0; i < allOptions.length; i++) {
+    const { format, handler } = allOptions[i];
+    if (!format.from || !format.to) continue;
+
+    if (simpleMode) {
+      const key = `${format.mime}|${format.format}`;
+      if (seen.has(key)) continue;
+      seen.add(key);
+    }
+
+    const btn = document.createElement("button");
+    btn.setAttribute("format-index", i.toString());
+    btn.setAttribute("mime-type", format.mime);
+
+    const formatDescriptor = format.format.toUpperCase();
+    if (simpleMode) {
+      const cleanName = format.name
+        .split("(").join(")").split(")")
+        .filter((_, j) => j % 2 === 0)
+        .filter(c => c !== "")
+        .join(" ");
+      btn.textContent = `${formatDescriptor} - ${cleanName} (${format.mime})`;
+    } else {
+      btn.textContent = `${formatDescriptor} - ${format.name} (${format.mime}) ${handler.name}`;
+    }
+
+    btn.onclick = () => {
+      waypointOptions.push(allOptions[i]);
+      renderWaypoints();
+      viaPicker.close();
+      (document.querySelector("#search-via") as HTMLInputElement).value = "";
+      filterButtonList(pickerList, "");
+    };
+
+    pickerList.appendChild(btn);
+  }
+}
 
 async function buildOptionList () {
 
@@ -285,6 +374,7 @@ async function buildOptionList () {
   window.traversionGraph.init(window.supportedFormatCache, handlers);
   filterButtonList(ui.inputList, ui.inputSearch.value);
   filterButtonList(ui.outputList, ui.outputSearch.value);
+  buildPickerList();
 
   window.hidePopup();
 
@@ -314,9 +404,42 @@ ui.modeToggleButton.addEventListener("click", () => {
     ui.modeToggleButton.textContent = "Simple mode";
     document.body.style.setProperty("--highlight-color", "#FF6F1C");
   }
+  waypointOptions = [];
+  renderWaypoints();
   buildOptionList();
 });
 
+document.querySelector("#add-via")!.addEventListener("click", () => {
+  viaPicker.showModal();
+});
+
+document.querySelector("#via-picker-cancel")!.addEventListener("click", () => {
+  viaPicker.close();
+});
+
+document.querySelector("#round-trip")!.addEventListener("click", () => {
+  const inputSelected = document.querySelector("#from-list .selected") as HTMLButtonElement | null;
+  if (!inputSelected) {
+    alert("Pick an input format first.");
+    return;
+  }
+  const inputOpt = allOptions[Number(inputSelected.getAttribute("format-index"))];
+  const outputButton = Array.from(ui.outputList.children).find(btn => {
+    if (!(btn instanceof HTMLButtonElement)) return false;
+    const opt = allOptions[Number(btn.getAttribute("format-index"))];
+    return opt?.format.mime === inputOpt.format.mime && opt?.format.format === inputOpt.format.format;
+  }) as HTMLButtonElement | undefined;
+  if (outputButton) {
+    outputButton.click();
+  } else {
+    alert("No matching output format found for round-trip.");
+  }
+});
+
+document.querySelector("#dl-intermediates")!.addEventListener("change", (e) => {
+  downloadIntermediates = (e.target as HTMLInputElement).checked;
+});
+
 let deadEndAttempts: ConvertPathNode[][];
 
 async function attemptConvertPath (files: FileData[], path: ConvertPathNode[]) {
@@ -434,43 +557,84 @@ ui.convertButton.onclick = async function () {
   const inputOption = allOptions[Number(inputButton.getAttribute("format-index"))];
   const outputOption = allOptions[Number(outputButton.getAttribute("format-index"))];
 
-  const inputFormat = inputOption.format;
-  const outputFormat = outputOption.format;
-
   try {
 
-    const inputFileData = [];
+    const inputFileData: FileData[] = [];
     for (const inputFile of inputFiles) {
-      const inputBuffer = await inputFile.arrayBuffer();
-      const inputBytes = new Uint8Array(inputBuffer);
+      const bytes = new Uint8Array(await inputFile.arrayBuffer());
       if (
-        inputFormat.mime === outputFormat.mime
-        && inputFormat.format === outputFormat.format
+        waypointOptions.length === 0 &&
+        inputOption.format.mime === outputOption.format.mime &&
+        inputOption.format.format === outputOption.format.format
       ) {
-        downloadFile(inputBytes, inputFile.name);
+        downloadFile(bytes, inputFile.name);
         continue;
       }
-      inputFileData.push({ name: inputFile.name, bytes: inputBytes });
+      inputFileData.push({ name: inputFile.name, bytes });
     }
+    if (inputFileData.length === 0) return;
 
     window.showPopup("<h2>Finding conversion route...</h2>");
-    // Delay for a bit to give the browser time to render
     await new Promise(resolve => requestAnimationFrame(() => requestAnimationFrame(resolve)));
 
-    const output = await window.tryConvertByTraversing(inputFileData, inputOption, outputOption);
-    if (!output) {
+    const segments: FormatOption[] = [inputOption, ...waypointOptions, outputOption];
+
+    const segmentRunner: SegmentRunner = async (files, from, to, legIndex, totalLegs) => {
+      if (totalLegs > 1) {
+        window.showPopup(
+          `<h2>Step ${legIndex + 1} of ${totalLegs}</h2>` +
+          `<p>Converting ${from.format.format} → ${to.format.format}…</p>`
+        );
+        await new Promise(resolve => requestAnimationFrame(() => requestAnimationFrame(resolve)));
+      }
+      return window.tryConvertByTraversing(files, from as any, to as any);
+    };
+
+    const result = await runChain(inputFileData, segments, segmentRunner);
+
+    if (result.failedAt !== undefined) {
+      window.hidePopup();
+      const failFrom = segments[result.failedAt];
+      const failTo = segments[result.failedAt + 1];
+      alert(
+        `Step ${result.failedAt + 1} of ${segments.length - 1} failed: ` +
+        `${failFrom.format.format} → ${failTo.format.format}`
+      );
+      return;
+    }
+
+    if (result.finalFiles.length === 0) {
       window.hidePopup();
       alert("Failed to find conversion route.");
       return;
     }
 
-    for (const file of output.files) {
+    if (downloadIntermediates) {
+      for (let i = 0; i < result.legs.length - 1; i++) {
+        for (const file of result.legs[i].files) {
+          const dot = file.name.lastIndexOf(".");
+          const base = dot > 0 ? file.name.slice(0, dot) : file.name;
+          const ext = dot > 0 ? file.name.slice(dot) : "";
+          downloadFile(file.bytes, `${base}.step${i + 1}${ext}`);
+        }
+      }
+    }
+
+    for (const file of result.finalFiles) {
       downloadFile(file.bytes, file.name);
     }
 
+    const fullPath = result.legs.length > 0
+      ? result.legs.flatMap((leg, i) =>
+          i === 0
+            ? leg.path.map(n => n.format.format)
+            : leg.path.slice(1).map(n => n.format.format)
+        )
+      : [inputOption.format.format, outputOption.format.format];
+
     window.showPopup(
-      `<h2>Converted ${inputOption.format.format} to ${outputOption.format.format}!</h2>` +
-      `<p>Path used: <b>${output.path.map(c => c.format.format).join(" → ")}</b>.</p>\n` +
+      `<h2>Converted!</h2>` +
+      `<p>Path: <b>${fullPath.join(" → ")}</b></p>\n` +
       `<button onclick="window.hidePopup()">OK</button>`
     );
 
diff --git a/src/runChain.ts b/src/runChain.ts
new file mode 100644
index 00000000..04dfb63b
--- /dev/null
+++ b/src/runChain.ts
@@ -0,0 +1,85 @@
+import type { FileData, FileFormat, FormatHandler, ConvertPathNode } from "./FormatHandler.ts";
+
+export type FormatOption = { format: FileFormat; handler: FormatHandler };
+
+export type Leg = {
+  files: FileData[];
+  path: ConvertPathNode[];
+  from: FormatOption;
+  to: FormatOption;
+};
+
+export type ChainResult = {
+  finalFiles: FileData[];
+  legs: Leg[];
+  failedAt?: number;
+};
+
+/**
+ * Single-leg conversion primitive — `runChain` is decoupled from the DOM by
+ * receiving this as a callback rather than reaching for `window`.
+ */
+export type SegmentRunner = (
+  files: FileData[],
+  from: FormatOption,
+  to: FormatOption,
+  legIndex: number,
+  totalLegs: number
+) => Promise<{ files: FileData[]; path: ConvertPathNode[] } | null>;
+
+const stripExt = (name: string): string => {
+  const dot = name.lastIndexOf(".");
+  return dot > 0 ? name.slice(0, dot) : name;
+};
+
+const sameFormat = (a: FormatOption, b: FormatOption): boolean =>
+  a.format.mime === b.format.mime && a.format.format === b.format.format;
+
+/**
+ * Orchestrates a chained conversion across `[input, ...waypoints, output]`.
+ * Each leg is delegated to the supplied {@link SegmentRunner}, which in
+ * production is a thin wrapper around `window.tryConvertByTraversing` and in
+ * tests can be any function returning fake `FileData`/path data.
+ *
+ * Each leg's outputs are retained on the returned {@link Leg} so the caller
+ * can offer optional intermediate downloads without re-running anything.
+ */
+export async function runChain(
+  initialFiles: FileData[],
+  segments: FormatOption[],
+  runSegment: SegmentRunner
+): Promise<ChainResult> {
+  if (segments.length < 2) {
+    return { finalFiles: initialFiles, legs: [] };
+  }
+
+  let files: FileData[] = initialFiles;
+  const legs: Leg[] = [];
+
+  // We may "skip" no-op adjacent segments (input == waypoint), so the legs
+  // we actually run can be fewer than segments.length-1. Compute the planned
+  // count first so progress messaging is accurate.
+  const plannedPairs: Array<{ from: FormatOption; to: FormatOption }> = [];
+  for (let i = 0; i < segments.length - 1; i++) {
+    if (sameFormat(segments[i], segments[i + 1])) continue;
+    plannedPairs.push({ from: segments[i], to: segments[i + 1] });
+  }
+
+  for (let i = 0; i < plannedPairs.length; i++) {
+    const { from, to } = plannedPairs[i];
+    const result = await runSegment(files, from, to, i, plannedPairs.length);
+    if (!result) {
+      return { finalFiles: files, legs, failedAt: i };
+    }
+    // Stamp the output extension to match the leg's target format. Most
+    // handlers already do this, but keep it consistent for downstream legs
+    // and for the optional intermediate-download UX.
+    files = result.files.map((f) => ({
+      name: stripExt(f.name) + "." + to.format.extension,
+      bytes: f.bytes,
+    }));
+    legs.push({ files, path: result.path, from, to });
+  }
+
+  return { finalFiles: files, legs };
+}
diff --git a/style.css b/style.css
index 8b47ce29..7cfa7d01 100644
--- a/style.css
+++ b/style.css
@@ -75,9 +75,11 @@ body {
   display: flex;
   flex-flow: column nowrap;
   align-items: center;
-  width: 50vw;
+  flex: 1 1 0;
+  min-width: 0;
   min-height: 70vh;
-  padding: 0.8em 7em;
+  padding: 0.8em 3em;
+  box-sizing: border-box;
 }
 .format-container h2 {
   text-align: center;
@@ -87,10 +89,175 @@ body {
 #from-container {
   background-color: lightgray;
 }
+#via-container {
+  background-color: rgb(212, 212, 212);
+}
 #to-container {
   background-color: rgb(184, 184, 184);
 }
 
+.via-optional {
+  font-weight: normal;
+  font-size: 0.8em;
+  opacity: 0.6;
+}
+
+.via-hint {
+  font-size: 0.8rem;
+  color: #555;
+  text-align: center;
+  margin: -12px 0 14px;
+  font-style: italic;
+}
+
+#via-list {
+  display: flex;
+  flex-flow: column nowrap;
+  align-items: stretch;
+  gap: 6px;
+  width: 100%;
+  min-height: 60px;
+  padding: 12px;
+  background-color: white;
+  border-radius: 10px;
+  box-sizing: border-box;
+  margin-bottom: 12px;
+}
+#via-list:empty::before {
+  content: "No waypoints — will convert directly";
+  color: #888;
+  font-style: italic;
+  text-align: center;
+  font-size: 0.9rem;
+  align-self: center;
+  margin: auto;
+}
+
+.via-chip {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  background-color: var(--highlight-color);
+  color: white;
+  border-radius: 8px;
+  padding: 8px 10px;
+  font-family: monospace;
+  font-weight: bold;
+  word-break: break-word;
+  animation: chipIn 0.15s ease;
+}
+@keyframes chipIn {
+  from { opacity: 0; transform: translateY(-4px); }
+  to   { opacity: 1; transform: translateY(0); }
+}
+.via-chip-label {
+  flex: 1;
+  text-align: left;
+}
+.via-chip-step {
+  opacity: 0.6;
+  font-size: 0.75em;
+  margin-right: 8px;
+  font-weight: normal;
+  background: rgba(255,255,255,0.2);
+  border-radius: 4px;
+  padding: 1px 5px;
+}
+.via-chip-remove {
+  background: transparent;
+  border: 0;
+  color: white;
+  font-size: 1.1rem;
+  cursor: pointer;
+  padding: 0 4px 0 8px;
+  line-height: 1;
+  border-radius: 4px;
+  transition: background-color 0.12s ease;
+}
+.via-chip-remove:hover {
+  background-color: rgba(255,255,255,0.25);
+}
+
+#via-controls {
+  display: flex;
+  flex-flow: column nowrap;
+  align-items: stretch;
+  gap: 8px;
+  width: 100%;
+}
+
+#add-via,
+#round-trip {
+  font-size: 0.95rem;
+  padding: 10px 12px;
+  border: 0;
+  border-radius: 8px;
+  background-color: white;
+  color: var(--highlight-color);
+  font-weight: bold;
+  cursor: pointer;
+  box-shadow: 0 3px 0 0 rgba(169, 169, 169, 0.4);
+  transition: background-color 0.15s ease;
+}
+#add-via:hover,
+#round-trip:hover {
+  background-color: #f0f4ff;
+}
+#add-via:active,
+#round-trip:active {
+  transform: translateY(3px);
+  box-shadow: 0 0 0 0;
+}
+
+.via-toggle {
+  font-size: 0.85rem;
+  display: flex;
+  align-items: center;
+  gap: 6px;
+  cursor: pointer;
+  user-select: none;
+  padding: 4px 0;
+}
+
+#via-picker {
+  border: 0;
+  border-radius: 12px;
+  padding: 0;
+  max-width: 600px;
+  width: 90vw;
+  max-height: 80vh;
+}
+#via-picker::backdrop {
+  background-color: rgba(0, 0, 0, 0.5);
+}
+.via-picker-inner {
+  display: flex;
+  flex-flow: column nowrap;
+  padding: 20px;
+  gap: 10px;
+  max-height: 80vh;
+  box-sizing: border-box;
+}
+.via-picker-inner h2 {
+  margin: 0 0 5px 0;
+  text-align: center;
+}
+.via-picker-inner .format-list {
+  flex: 1 1 auto;
+  overflow-y: auto;
+  margin-bottom: 0;
+}
+#via-picker-cancel {
+  font-size: 1rem;
+  padding: 10px 20px;
+  border: 0;
+  border-radius: 10px;
+  background-color: lightgray;
+  color: black;
+  cursor: pointer;
+  align-self: center;
+}
+
 .search {
   text-align: center;
   margin-bottom: 30px;
@@ -123,6 +290,10 @@ body {
   font-family: monospace;
   word-break: break-word;
   cursor: pointer;
+  transition: background-color 0.15s ease, color 0.15s ease;
+}
+.format-list button:hover:not(.selected) {
+  background-color: #c0c0c0;
 }
 
 button.selected {
diff --git a/test/handlers/chainOrchestrator.test.ts b/test/handlers/chainOrchestrator.test.ts
new file mode 100644
index 00000000..f4f59abc
--- /dev/null
+++ b/test/handlers/chainOrchestrator.test.ts
@@ -0,0 +1,136 @@
+import { describe, it, expect } from "bun:test";
+import { runChain } from "../../src/runChain";
+import type { FormatOption, SegmentRunner } from "../../src/runChain";
+import type { FileData, FileFormat } from "../../src/FormatHandler";
+import { MockedHandler } from "../MockedHandler";
+
+const makeFormat = (format: string, mime: string): FileFormat => ({
+  format,
+  mime,
+  extension: format,
+  name: format,
+  from: true,
+  to: true,
+  lossless: false,
+  internal: undefined,
+  category: "data" as any,
+});
+
+const makeOption = (format: string, mime: string): FormatOption => {
+  const handler = new MockedHandler(`handler-${format}`);
+  return { format: makeFormat(format, mime), handler };
+};
+
+const makeFiles = (name: string): FileData[] => [
+  { name, bytes: new Uint8Array([1, 2, 3]) },
+];
+
+const successRunner =
+  (label: string): SegmentRunner =>
+  async (files, from, to) => ({
+    files: [{ name: `${label}.${to.format.extension}`, bytes: files[0].bytes }],
+    path: [
+      { format: from.format, handler: from.handler } as any,
+      { format: to.format, handler: to.handler } as any,
+    ],
+  });
+
+const failRunner: SegmentRunner = async () => null;
+
+describe("runChain", () => {
+  it("fewer than 2 segments returns input unchanged", async () => {
+    const png = makeOption("png", "image/png");
+    const files = makeFiles("image.png");
+    const result = await runChain(files, [png], successRunner("out"));
+    expect(result.legs).toHaveLength(0);
+    expect(result.finalFiles).toBe(files);
+    expect(result.failedAt).toBeUndefined();
+  });
+
+  it("single leg direct conversion runs one segment", async () => {
+    const png = makeOption("png", "image/png");
+    const wav = makeOption("wav", "audio/wav");
+    const files = makeFiles("image.png");
+    const calls: string[] = [];
+    const runner: SegmentRunner = async (f, from, to, legIndex, totalLegs) => {
+      calls.push(`${from.format.format}->${to.format.format} leg=${legIndex}/${totalLegs}`);
+      return { files: [{ name: `out.wav`, bytes: f[0].bytes }], path: [] };
+    };
+    const result = await runChain(files, [png, wav], runner);
+    expect(calls).toEqual(["png->wav leg=0/1"]);
+    expect(result.legs).toHaveLength(1);
+    expect(result.finalFiles[0].name).toBe("out.wav");
+    expect(result.failedAt).toBeUndefined();
+  });
+
+  it("three-leg chain runs segments in order with chained inputs", async () => {
+    const a = makeOption("a", "type/a");
+    const b = makeOption("b", "type/b");
+    const c = makeOption("c", "type/c");
+    const d = makeOption("d", "type/d");
+    const callOrder: string[] = [];
+    const runner: SegmentRunner = async (files, from, to) => {
+      callOrder.push(`${from.format.format}->${to.format.format}`);
+      return {
+        files: [{ name: `out.${to.format.format}`, bytes: new Uint8Array([callOrder.length]) }],
+        path: [],
+      };
+    };
+    const result = await runChain(makeFiles("in.a"), [a, b, c, d], runner);
+    expect(callOrder).toEqual(["a->b", "b->c", "c->d"]);
+    expect(result.legs).toHaveLength(3);
+    expect(result.finalFiles[0].name).toBe("out.d");
+    expect(result.failedAt).toBeUndefined();
+    // Each leg's input bytes come from the previous leg's output
+    expect(result.legs[1].files[0].bytes[0]).toBe(2);
+    expect(result.legs[2].files[0].bytes[0]).toBe(3);
+  });
+
+  it("failing middle leg sets failedAt and preserves prior legs", async () => {
+    const a = makeOption("a", "type/a");
+    const b = makeOption("b", "type/b");
+    const c = makeOption("c", "type/c");
+    let callCount = 0;
+    const runner: SegmentRunner = async (files, from, to) => {
+      callCount++;
+      if (callCount === 2) return null;
+      return { files: [{ name: `out.${to.format.format}`, bytes: files[0].bytes }], path: [] };
+    };
+    const result = await runChain(makeFiles("in.a"), [a, b, c], runner);
+    expect(result.failedAt).toBe(1);
+    expect(result.legs).toHaveLength(1);
+  });
+
+  it("identical adjacent segments are skipped", async () => {
+    const png = makeOption("png", "image/png");
+    const wav = makeOption("wav", "audio/wav");
+    const calls: string[] = [];
+    const runner: SegmentRunner = async (f, from, to) => {
+      calls.push(`${from.format.format}->${to.format.format}`);
+      return { files: [{ name: `out.${to.format.format}`, bytes: f[0].bytes }], path: [] };
+    };
+    // [png, png, wav] — first segment is a no-op
+    const result = await runChain(makeFiles("in.png"), [png, png, wav], runner);
+    expect(calls).toEqual(["png->wav"]);
+    expect(result.legs).toHaveLength(1);
+  });
+
+  it("legs retain per-leg output files for intermediate downloads", async () => {
+    const a = makeOption("a", "type/a");
+    const b = makeOption("b", "type/b");
+    const c = makeOption("c", "type/c");
+    let step = 0;
+    const runner: SegmentRunner = async (f, from, to) => {
+      step++;
+      return {
+        files: [{ name: `step${step}.${to.format.format}`, bytes: new Uint8Array([step]) }],
+        path: [],
+      };
+    };
+    const result = await runChain(makeFiles("in.a"), [a, b, c], runner);
+    expect(result.legs[0].files[0].name).toBe("step1.b");
+    expect(result.legs[1].files[0].name).toBe("step2.c");
+    // finalFiles should equal the last leg's output
+    expect(result.finalFiles[0].name).toBe("step2.c");
+  });
+});

From e4c4a665bf5042961f4d54d224cb52d5ea9ad343 Mon Sep 17 00:00:00 2001
From: James <168039748+TheGeneral4757@users.noreply.github.com>
Date: Mon, 27 Apr 2026 17:45:01 -0500
Subject: [PATCH 2/4] Add CLAUDE.md to .gitignore

---
 .gitignore | 1 +
 1 file changed, 1 insertion(+)

diff --git a/.gitignore b/.gitignore
index 93b3bcee..f5ad3135 100644
--- a/.gitignore
+++ b/.gitignore
@@ -5,3 +5,4 @@ start.sh
 dist
 release
 cache.json
+CLAUDE.md

From 6a8743d1f880340f0b4c44d82e68a301a7fd814a Mon Sep 17 00:00:00 2001
From: James <168039748+TheGeneral4757@users.noreply.github.com>
Date: Mon, 27 Apr 2026 17:45:19 -0500
Subject: [PATCH 3/4] Delete CLAUDE.md

---
 CLAUDE.md | 78 -------------------------------------------------------
 1 file changed, 78 deletions(-)
 delete mode 100644 CLAUDE.md

diff --git a/CLAUDE.md b/CLAUDE.md
deleted file mode 100644
index fb761481..00000000
--- a/CLAUDE.md
+++ /dev/null
@@ -1,78 +0,0 @@
-# CLAUDE.md
-
-This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
-
-## Commands
-
-```bash
-# Install dependencies (requires Bun)
-bun install
-
-# Development server
-bunx vite
-
-# Production build
-bun run build
-
-# Run tests
-bun test
-
-# Run a single test file
-bun test test/TraversionGraph.test.ts
-
-# Generate format cache (run after build; uses puppeteer/Chromium — slow first run)
-bun run cache:build
-
-# Type-check only (no emit)
-bunx tsc --noEmit
-
-# Docker (prebuilt image)
-docker compose -f docker/docker-compose.yml up -d
-
-# Docker (local build)
-docker compose -f docker/docker-compose.yml -f docker/docker-compose.override.yml up --build -d
-```
-
-## Architecture
-
-The app is a **browser-based, privacy-first file converter** that runs all conversions client-side. It supports cross-medium conversion (e.g. AVI → PDF) by chaining multiple handlers together.
-
-### Core abstractions (`src/`)
-
-- **`FormatHandler.ts`** — Defines the key interfaces:
-  - `FileFormat` — a format with MIME, extension, `from`/`to` booleans, `internal` ref, `category`, and `lossless` flag.
-  - `FileData` — `{ name: string, bytes: Uint8Array }`. Handlers own the buffer's lifetime; clone with `new Uint8Array()` if mutation is possible.
-  - `FormatHandler` — interface all handlers implement: `name`, `supportedFormats`, `ready`, `init()`, `doConvert()`. Optional `supportAnyInput` flag marks generic "catch-all" handlers (e.g. archive wrappers).
-  - `FormatDefinition` / `builder()` — fluent API for defining formats in handlers (`.allowFrom()`, `.allowTo()`, `.markLossless()`, etc.).
-
-- **`TraversionGraph.ts`** — Dijkstra's algorithm over the format graph. Nodes are unique formats (identified by `mime(format)`); edges are handler-provided conversions. Cost factors: depth, category-change penalties, lossy multiplier, handler/format priority index. `searchPath()` is an async generator yielding candidate paths. Handlers registered with `supportAnyInput` get edges from every known node to their output formats (with an `ANY_INPUT_COST` penalty to prefer specific paths).
-
-- **`CommonFormats.ts`** — Pre-built `FormatDefinition` instances (PNG, JPEG, MP4, MP3, PDF, etc.) and the `Category` enum (`image`, `video`, `audio`, `text`, `document`, `archive`, `data`, `vector`, `font`, `code`, `spreadsheet`, `presentation`). Reuse these in handlers to avoid duplicate format definitions.
-
-- **`PriorityQueue.ts`** — Min-heap used by `TraversionGraph`.
-
-### Handlers (`src/handlers/`)
-
-Each handler wraps one conversion tool. Naming convention: file `foo.ts`, class `fooHandler`, registered in `src/handlers/index.ts`. Handler order in `index.ts` matters — it affects the `handlerIndex` cost term in pathfinding (earlier = slightly preferred).
-
-Key handlers: `FFmpeg.ts` (video/audio), `ImageMagick.ts` (images), `pandoc.ts` (documents), `font.ts`, `threejs.ts` (3D), `sevenZip.ts`, `sqlite.ts`, and ~60 others.
-
-**WASM dependencies** must be declared in `vite.config.js` under `viteStaticCopy` targets, served from `/convert/wasm/`. Never link directly to `node_modules` for WASM. External git-repo dependencies are added as submodules under `src/handlers/`.
-
-### Format cache
-
-On first load, the app builds the supported-format map by calling `init()` on every handler. This is slow (~seconds). The result can be serialized to `cache.json` via `printSupportedFormatCache()` in the browser console, then rebuilt offline with `bun run cache:build`. Disable the cache when testing handler changes.
-
-### Build targets
-
-- **Web** — Vite SPA served under `/convert/` base path.
-- **Electron** — `src/electron.cjs` is the main process; built with `IS_DESKTOP=true`.
-- **Docker** — nginx serves the built output; Dockerfile installs Chromium for `buildCache.js`.
-
-### Testing
-
-- `test/TraversionGraph.test.ts` — graph traversal unit tests.
-- `test/commonFormats.test.ts` — format definition tests.
-- `test/handlers/<handlerName>.test.ts` — optional per-handler unit tests (add for handlers with non-trivial parsing/serialization logic).
-- `test/MockedHandler.ts` — test utility for creating stub handlers.
-- Test resources live in `test/resources/`.

From 638efb4c929cd798b73c83f114eb81fb27755902 Mon Sep 17 00:00:00 2001
From: James Thiessen <25james1234@gmail.com>
Date: Mon, 27 Apr 2026 18:03:10 -0500
Subject: [PATCH 4/4] style: make via/waypoints column narrower and visually
 distinct
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Reduce flex ratio to 0.6 and lower horizontal padding so the optional
waypoints panel reads as secondary relative to the from/to columns.
Change background from rgb(212,212,212) — nearly identical to lightgray
— to #ececec so it is clearly differentiated from both neighbours.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
---
 style.css | 5 ++++-
 1 file changed, 4 insertions(+), 1 deletion(-)

diff --git a/style.css b/style.css
index 7cfa7d01..0c1563fd 100644
--- a/style.css
+++ b/style.css
@@ -90,7 +90,10 @@ body {
   background-color: lightgray;
 }
 #via-container {
-  background-color: rgb(212, 212, 212);
+  background-color: #ececec;
+  flex: 0.6 1 0;
+  padding: 0.8em 1.5em;
+  min-width: 180px;
 }
 #to-container {
   background-color: rgb(184, 184, 184);