@polderlabs/bizar 5.1.0 → 5.2.0

package/bizar-dash/node_modules/.vite/vitest/da39a3ee5e6b4b0d3255bfef95601890afd80709/results.json

@@ -1 +1 @@
-{"version":"4.1.9","results":[[":tests/lib/utils.test.ts",{"duration":28.89169000000004,"failed":false}],[":tests/components/Button.test.tsx",{"duration":117.69011,"failed":false}],[":tests/components/Card.test.tsx",{"duration":30.92253400000004,"failed":false}],[":tests/hooks/useModal.test.tsx",{"duration":119.64900699999998,"failed":false}],[":tests/components/Toast.test.tsx",{"duration":159.04681100000005,"failed":false}],[":tests/components/Modal.test.tsx",{"duration":150.9410469999999,"failed":false}],[":tests/lib/i18n.test.ts",{"duration":3.2969249999999874,"failed":false}],[":tests/components/StatusBadge.test.tsx",{"duration":41.157249999999976,"failed":false}],[":tests/hooks/useToast.test.tsx",{"duration":104.85745599999996,"failed":false}],[":tests/components/Spinner.test.tsx",{"duration":70.16560200000004,"failed":false}],[":tests/backup-restore.test.tsx",{"duration":179.13565300000005,"failed":false}],[":tests/a11y.test.tsx",{"duration":715.4879470000001,"failed":false}],[":tests/lib/search-fuzzy.test.ts",{"duration":7.532295999999974,"failed":false}],[":tests/components/settings-search.test.tsx",{"duration":712.275263,"failed":false}],[":tests/memory-graph-view.test.tsx",{"duration":59.40099399999997,"failed":false}],[":tests/components/workspace-selector.test.tsx",{"duration":113.71114899999998,"failed":false}],[":tests/components/screenshot-ocr.test.tsx",{"duration":51.13657699999999,"failed":false}],[":tests/voice-recorder.test.tsx",{"duration":128.61647900000003,"failed":false}],[":tests/autosave.test.tsx",{"duration":251.98326499999996,"failed":false}],[":tests/settings-layout.test.tsx",{"duration":201.76037699999995,"failed":false}],[":tests/settings-nav.test.tsx",{"duration":228.42296299999998,"failed":false}],[":tests/components/doctor-panel.test.tsx",{"duration":67.53857800000003,"failed":false}],[":tests/chat-composer.test.tsx",{"duration":189.9785320000001,"failed":false}],[":tests/settings-mode-wiring.test.tsx",{"duration":205.661208,"failed":false}],[":tests/minimax-bar.test.ts",{"duration":0,"failed":true}],[":tests/minimax-bar.test.tsx",{"duration":30.342043999999987,"failed":false}]]}
+{"version":"4.1.9","results":[[":tests/lib/utils.test.ts",{"duration":16.303165999999976,"failed":false}],[":tests/components/Button.test.tsx",{"duration":106.694435,"failed":false}],[":tests/components/Card.test.tsx",{"duration":19.81299100000001,"failed":false}],[":tests/hooks/useModal.test.tsx",{"duration":159.28117799999995,"failed":false}],[":tests/components/Toast.test.tsx",{"duration":196.709385,"failed":false}],[":tests/components/Modal.test.tsx",{"duration":196.62032399999998,"failed":false}],[":tests/lib/i18n.test.ts",{"duration":3.903647000000035,"failed":false}],[":tests/components/StatusBadge.test.tsx",{"duration":49.069886,"failed":false}],[":tests/hooks/useToast.test.tsx",{"duration":120.39812900000004,"failed":false}],[":tests/components/Spinner.test.tsx",{"duration":77.51955700000008,"failed":false}],[":tests/backup-restore.test.tsx",{"duration":205.62362600000006,"failed":false}],[":tests/a11y.test.tsx",{"duration":754.295168,"failed":false}],[":tests/lib/search-fuzzy.test.ts",{"duration":5.431500000000028,"failed":false}],[":tests/components/settings-search.test.tsx",{"duration":723.2007870000001,"failed":false}],[":tests/memory-graph-view.test.tsx",{"duration":47.14713799999993,"failed":false}],[":tests/components/workspace-selector.test.tsx",{"duration":152.31454200000007,"failed":false}],[":tests/components/screenshot-ocr.test.tsx",{"duration":54.37460299999998,"failed":false}],[":tests/voice-recorder.test.tsx",{"duration":138.534312,"failed":false}],[":tests/autosave.test.tsx",{"duration":268.9614950000001,"failed":false}],[":tests/settings-layout.test.tsx",{"duration":248.58253200000001,"failed":false}],[":tests/settings-nav.test.tsx",{"duration":311.78257699999995,"failed":false}],[":tests/components/doctor-panel.test.tsx",{"duration":82.92706099999998,"failed":false}],[":tests/chat-composer.test.tsx",{"duration":207.18291899999997,"failed":false}],[":tests/settings-mode-wiring.test.tsx",{"duration":221.4198530000001,"failed":false}],[":tests/minimax-bar.test.ts",{"duration":0,"failed":true}],[":tests/minimax-bar.test.tsx",{"duration":36.76302400000009,"failed":false}],[":tests/components/plugin-permissions.test.tsx",{"duration":104.179755,"failed":false}],[":tests/eval-web-ui.test.tsx",{"duration":152.385127,"failed":false}]]}

package/bizar-dash/src/server/api.mjs

@@ -181,6 +181,10 @@ export async function createApiRouter({
   // v5.0.0 — Screenshot OCR routes. Accepts images, extracts text.
   const { createOcrRouter } = await import('./routes/ocr.mjs');
   router.use(await createOcrRouter({ projectRoot }));
+  // v5.2 — Tailscale auth key integration. Registered before misc.mjs so
+  // /tailscale/* routes here take precedence over any overlapping misc routes.
+  const { createTailscaleRouter } = await import('./routes/tailscale.mjs');
+  router.use(createTailscaleRouter({}));
   router.use(createMiscRouter({ state, broadcast }));
 
   // /api/auth/* must be reachable WITHOUT the bearer token so a fresh

package/bizar-dash/src/server/routes/plugins.mjs

@@ -134,10 +134,18 @@ export function createPluginsRouter() {
       userAgent: _req.headers?.['user-agent'],
     });
     const installed = store.listInstalled();
-    span.setAttribute('plugin.installed.count', installed.length);
-    res.json({ plugins: installed });
+    const enhanced = installed.map(p => ({
+      ...p,
+      permissions: p.permissions || [],
+      config: p.config || {},
+      methodCount: p.methodCount || 0,
+      invocations: p.invocations || 0,
+      lastInvokedAt: p.lastInvokedAt || null,
+    }));
+    span.setAttribute('plugin.installed.count', enhanced.length);
+    res.json({ plugins: enhanced });
     recordTrace('plugin.installed.list', {
-      count_bucket: installed.length === 0 ? '0' : installed.length < 10 ? '1-9' : '10+',
+      count_bucket: enhanced.length === 0 ? '0' : enhanced.length < 10 ? '1-9' : '10+',
     });
   })));
 

package/bizar-dash/src/server/routes/tailscale.mjs

@@ -0,0 +1,46 @@
+/**
+ * src/server/routes/tailscale.mjs
+ *
+ * v5.2 — Tailscale auth key integration endpoints.
+ *
+ * Endpoints:
+ *   GET  /api/tailscale/status   — tailscale state (installed, authenticated, serve config)
+ *   POST /api/tailscale/setup    — authenticate + set up tailscale serve
+ *   POST /api/tailscale/unserve — remove tailscale serve
+ */
+import { Router } from 'express';
+import { tailscaleStore } from '../tailscale-store.mjs';
+import { wrap } from './_shared.mjs';
+
+/**
+ * @param {object} _deps
+ * @returns {import('express').Router}
+ */
+export function createTailscaleRouter(_deps) {
+  const router = Router();
+
+  // GET /api/tailscale/status
+  router.get('/status', wrap(async (_req, res) => {
+    res.json(await tailscaleStore.status());
+  }));
+
+  // POST /api/tailscale/setup — authenticate + enable serve
+  // Body: { authKey?: string, port?: number, https?: boolean, hostname?: string }
+  router.post('/setup', wrap(async (req, res) => {
+    const { authKey, port = 4321, https = true, hostname = '' } = req.body || {};
+    // If authKey is provided, set it in env for tailscale-store to pick up
+    if (authKey) {
+      process.env.TAILSCALE_AUTHKEY = authKey;
+    }
+    // delegates to tailscaleStore.enable() which runs `tailscale serve ...`
+    const result = await tailscaleStore.enable({ port, https, hostname });
+    res.json(result);
+  }));
+
+  // POST /api/tailscale/unserve — remove tailscale serve
+  router.post('/unserve', wrap(async (_req, res) => {
+    res.json(await tailscaleStore.disable());
+  }));
+
+  return router;
+}

package/bizar-dash/src/server/routes/voice.mjs

@@ -2,9 +2,11 @@
  * src/server/routes/voice.mjs
  *
  * v5.0.0 — Voice notes REST API.
+ * v5.2   — Upload now saves audio immediately and enqueues background
+ *           transcription instead of blocking the request on Whisper.
  *
  * Endpoints:
- *   POST   /api/voice/upload            — multipart upload, transcribe, save
+ *   POST   /api/voice/upload            — multipart upload, enqueue transcription
  *   GET    /api/voice/list?vaultPath=   — list notes (optionally filtered)
  *   GET    /api/voice/:id              — get note details
  *   DELETE /api/voice/:id              — delete note + audio + transcript
@@ -16,7 +18,7 @@ import { createReadStream, existsSync } from 'node:fs';
 import { join } from 'node:path';
 import { info, warn, child } from '../logger.mjs';
 import { saveVoiceNote, listVoiceNotes, getVoiceNote, deleteVoiceNote } from '../voice-store.mjs';
-import { transcribe } from '../voice-transcribe.mjs';
+import { enqueueTranscription } from '../workers/transcription-worker.mjs';
 import { wrap } from './_shared.mjs';
 import formidable from 'formidable';
 
@@ -29,6 +31,14 @@ const log = child({ module: 'voice-routes' });
 export function createVoiceRouter(_deps) {
   const router = Router();
 
+  /**
+   * Whether Whisper is configured. When false, the worker is skipped
+   * entirely — uploads still succeed, just without transcripts.
+   */
+  function whisperAvailable() {
+    return Boolean(process.env.OPENAI_API_KEY) || Boolean(process.env.BIZAR_WHISPER_ENDPOINT);
+  }
+
   // POST /api/voice/upload — multipart: audio file + vaultPath field
   router.post('/voice/upload', wrap(async (req, res) => {
     const form = formidable({ maxFileSize: 50 * 1024 * 1024 }); // 50 MB limit
@@ -60,8 +70,11 @@ export function createVoiceRouter(_deps) {
         return;
       }
 
-      // Transcribe
-      const transcript = await transcribe(audioBuffer, { mimeType: 'audio/webm' });
+      // v5.2 — Transcription is now asynchronous. Save the audio first;
+      // the worker fills in the transcript when Whisper (or a local
+      // proxy) responds. Clients can poll GET /api/voice/:id or watch
+      // the `voice:updated` WS event for the transcript to appear.
+      const transcript = null;
 
       // Duration from audioFile (formidable provides size but not duration — we
       // store null and the frontmatter will show '?')
@@ -77,8 +90,31 @@ export function createVoiceRouter(_deps) {
         return;
       }
 
-      log.info('voice note saved via upload', { id: saved.id, transcriptLength: transcript?.length ?? 0 });
-      res.json({ notePath: saved.notePath, audioPath: saved.audioPath, id: saved.id, transcription: transcript });
+      // Kick the background worker ONLY when we have a place to send
+      // the audio. Without credentials the worker would just return
+      // null forever and waste an open file descriptor.
+      let transcriptionPending = false;
+      if (whisperAvailable()) {
+        try {
+          enqueueTranscription(saved.id);
+          transcriptionPending = true;
+        } catch (enqErr) {
+          warn('transcription enqueue failed', { id: saved.id, err: enqErr.message });
+        }
+      }
+
+      log.info('voice note saved via upload', {
+        id: saved.id,
+        transcriptionPending,
+        transcriptLength: 0,
+      });
+      res.json({
+        notePath: saved.notePath,
+        audioPath: saved.audioPath,
+        id: saved.id,
+        transcription: null,
+        transcriptionPending,
+      });
     });
   }));
 

package/bizar-dash/src/server/server.mjs

@@ -473,6 +473,19 @@ export async function createServer({
     console.warn('[bizar-dash] headroom startup hook skipped:', err?.message || err);
   }
 
+  // v5.2 — Background transcription worker for voice notes. Uploads
+  // save audio immediately and enqueue the noteId here; the worker
+  // drains the queue, calls Whisper (or BIZAR_WHISPER_ENDPOINT), and
+  // broadcasts a `voice:updated` event so the dashboard updates in
+  // place. Errors here MUST NOT block boot — the worker is best-effort
+  // and a missing transcribe just leaves the note with no transcript.
+  try {
+    const { startTranscriptionWorker } = await import('./workers/transcription-worker.mjs');
+    startTranscriptionWorker({ broadcast: localBroadcast });
+  } catch (err) {
+    console.warn('[bizar-dash] transcription worker failed to start:', err?.message || err);
+  }
+
   // All /api/* routes go through apiRouter (after mod routes are checked).
   // IMPORTANT: mount v2 router FIRST so `/api/v2/*` matches before
   // apiRouter's internal 404 catch-all (api.mjs line ~109) can swallow it.

package/bizar-dash/src/server/voice-store.mjs

@@ -168,6 +168,33 @@ export function getVoiceNote(id) {
   return loadIndex().find((n) => n.id === id);
 }
 
+/**
+ * v5.2 — Patch an existing note in place. Used by the background
+ * transcription worker to attach the transcript after Whisper returns.
+ *
+ * Atomic write via the same `atomicWriteJson` helper as `saveVoiceNote`.
+ * `updatedAtMs` is refreshed on every call so callers / the UI can see
+ * when the note last changed. `createdAtMs` is preserved.
+ *
+ * If the id is unknown, returns null without touching the index. Callers
+ * (e.g. the worker) treat null as "skip and log".
+ *
+ * @param {string} id
+ * @param {Partial<VoiceNote>} patch
+ * @returns {VoiceNote|null}
+ */
+export function updateVoiceNote(id, patch) {
+  if (!id || !patch || typeof patch !== 'object') return null;
+  const notes = loadIndex();
+  const note = notes.find((n) => n.id === id);
+  if (!note) return null;
+
+  Object.assign(note, patch, { updatedAtMs: Date.now() });
+  saveIndex(notes);
+  log.info('voice note updated', { id, fields: Object.keys(patch) });
+  return note;
+}
+
 /**
  * @param {string} id
  * @returns {boolean}

package/bizar-dash/src/server/workers/transcription-worker.mjs

@@ -0,0 +1,213 @@
+/**
+ * src/server/workers/transcription-worker.mjs
+ *
+ * v5.2 — Background transcription worker for voice notes.
+ *
+ * When a user uploads a voice note, the audio is saved immediately and a
+ * reference (noteId) is enqueued here. The worker drains the queue in
+ * FIFO order: it reads the audio from disk, calls `transcribe()` (the
+ * Whisper adapter), persists the result via `updateVoiceNote()`, and
+ * pushes a `voice:updated` event on the dashboard WebSocket so the UI
+ * can replace the "transcribing…" placeholder as soon as the text is
+ * ready.
+ *
+ * Design choices:
+ *   - In-memory queue (per-process). No cross-instance persistence; if
+ *     the server dies with work in the queue, those notes remain
+ *     un-transcribed (the audio file is still on disk and can be
+ *     re-triggered manually if needed).
+ *   - Single-threaded drain (`processing` flag). Multiple callers
+ *     enqueueing during a drain are captured by the while-loop's
+ *     `queue.length > 0` check on each iteration.
+ *   - Errors inside `processOne()` are caught and logged by
+ *     `processQueue()`; a failure on note X does NOT stop note X+1.
+ *   - `broadcast()` is injected at startup so the worker doesn't take
+ *     a hard dependency on server.mjs. In tests, a no-op stub is fine.
+ *   - `setInterval(..., 5000)` is a safety net: any work left in the
+ *     queue (e.g. from a processQueue race during teardown) gets a
+ *     retry tick. `.unref()` keeps the interval from blocking process
+ *     exit — the worker never closes the server by itself.
+ *
+ * Test injection: the four setters / helpers exposed on the bottom of
+ * this file (`setTranscribe`, `setBroadcast`, `drainQueue`, `reset`)
+ * exist so tests can stub the Whisper adapter and observe the queue
+ * without booting a server or hitting the network. They have no effect
+ * in production unless called.
+ */
+
+import { readFileSync, existsSync } from 'node:fs';
+import { getVoiceNote, updateVoiceNote } from '../voice-store.mjs';
+import { transcribe as defaultTranscribe } from '../voice-transcribe.mjs';
+import { child } from '../logger.mjs';
+
+const log = child({ module: 'transcription-worker' });
+
+const POLL_INTERVAL_MS = 5000;
+
+// ── Mutable worker state ────────────────────────────────────────────────────
+
+/** @type {{ noteId: string, enqueuedAt: number }[]} */
+const queue = [];
+let processing = false;
+
+/** Override hooks — defaults call through to the real Whisper adapter / no-op broadcast. */
+let _transcribe = defaultTranscribe;
+let _broadcast = () => {};
+
+const idleWaiters = [];
+
+// ── Core processing ─────────────────────────────────────────────────────────
+
+/**
+ * Process one note end-to-end. Returns a status object so tests (and
+ * the drain loop) can distinguish "skipped for a reason" from "ok".
+ *
+ * @param {string} noteId
+ * @returns {Promise<{ ok?: true, transcript?: string, skipped?: string }>}
+ */
+export async function processOne(noteId) {
+  const note = getVoiceNote(noteId);
+  if (!note) {
+    log.debug('note missing, skipping', { noteId });
+    return { skipped: 'missing' };
+  }
+  if (note.transcript) {
+    log.debug('already transcribed', { noteId });
+    return { skipped: 'already_transcribed' };
+  }
+  if (!existsSync(note.audioPath)) {
+    log.error('audio file missing on disk', { noteId, audioPath: note.audioPath });
+    return { skipped: 'audio_missing' };
+  }
+
+  let transcript;
+  try {
+    const audioBuffer = readFileSync(note.audioPath);
+    transcript = await _transcribe(audioBuffer, { mimeType: 'audio/webm' });
+  } catch (err) {
+    log.error('transcription threw', { noteId, err: err.message });
+    return { skipped: 'error', err: err.message };
+  }
+
+  if (!transcript) {
+    log.warn('transcription returned null', { noteId });
+    return { skipped: 'no_transcript' };
+  }
+
+  const updated = updateVoiceNote(noteId, { transcript });
+  if (!updated) {
+    log.error('updateVoiceNote returned null after successful transcription', { noteId });
+    return { skipped: 'update_failed' };
+  }
+
+  try {
+    _broadcast({ type: 'voice:updated', noteId, patch: { transcript } });
+  } catch (err) {
+    // Broadcast failure must not corrupt the on-disk state.
+    log.warn('broadcast threw', { noteId, err: err.message });
+  }
+
+  log.info('transcription complete', { noteId, length: transcript.length });
+  return { ok: true, transcript };
+}
+
+/**
+ * Drain the queue. Guarded by the `processing` flag so concurrent
+ * callers don't double-drain. Errors inside `processOne` are logged
+ * and swallowed, NOT re-thrown — the next item must always get a
+ * chance.
+ */
+async function processQueue() {
+  if (processing) return;
+  processing = true;
+  try {
+    while (queue.length > 0) {
+      const { noteId } = queue.shift();
+      try {
+        await processOne(noteId);
+      } catch (err) {
+        log.error('transcription failed', { noteId, err: err.message });
+      }
+    }
+  } finally {
+    processing = false;
+    if (queue.length === 0) {
+      const toResolve = idleWaiters.splice(0);
+      for (const r of toResolve) r();
+    }
+  }
+}
+
+// ── Public API ──────────────────────────────────────────────────────────────
+
+/**
+ * Enqueue a note for background transcription.
+ *
+ * @param {string} noteId
+ */
+export function enqueueTranscription(noteId) {
+  if (!noteId || typeof noteId !== 'string') return;
+  queue.push({ noteId, enqueuedAt: Date.now() });
+  // Drain is fire-and-forget — callers don't await per-note work.
+  void processQueue();
+}
+
+/**
+ * Start the worker. Idempotent — calling twice clears the previous
+ * interval and starts a fresh one.
+ *
+ * @param {{ broadcast?: (msg: unknown) => void }} [opts]
+ */
+export function startTranscriptionWorker({ broadcast } = {}) {
+  if (typeof broadcast === 'function') _broadcast = broadcast;
+  // Replace any prior interval so tests + double-boot are safe.
+  if (startTranscriptionWorker._interval) {
+    clearInterval(startTranscriptionWorker._interval);
+  }
+  log.info('transcription worker started', { pollIntervalMs: POLL_INTERVAL_MS });
+  const handle = setInterval(() => void processQueue(), POLL_INTERVAL_MS);
+  if (typeof handle.unref === 'function') handle.unref();
+  startTranscriptionWorker._interval = handle;
+}
+
+// ── Test hooks (no-op in production) ────────────────────────────────────────
+
+/** @param {(buf: Buffer|Uint8Array, opts?: object) => Promise<string|null>} fn */
+export function setTranscribe(fn) {
+  _transcribe = typeof fn === 'function' ? fn : defaultTranscribe;
+}
+
+/** @param {(msg: unknown) => void} fn */
+export function setBroadcast(fn) {
+  _broadcast = typeof fn === 'function' ? fn : () => {};
+}
+
+/** Number of items waiting or currently being processed. */
+export function getQueueDepth() {
+  return queue.length + (processing ? 1 : 0);
+}
+
+/**
+ * Resolve once the queue is fully drained (no items + not processing).
+ * Returns a resolved promise immediately if already idle.
+ */
+export function drainQueue() {
+  if (queue.length === 0 && !processing) return Promise.resolve();
+  return new Promise((resolve) => {
+    idleWaiters.push(resolve);
+    void processQueue();
+  });
+}
+
+/** Reset all mutable state. ONLY for tests. */
+export function reset() {
+  queue.length = 0;
+  processing = false;
+  _transcribe = defaultTranscribe;
+  _broadcast = () => {};
+  idleWaiters.length = 0;
+  if (startTranscriptionWorker._interval) {
+    clearInterval(startTranscriptionWorker._interval);
+    startTranscriptionWorker._interval = null;
+  }
+}

package/bizar-dash/src/web/App.tsx

@@ -31,6 +31,7 @@ import { Activity } from './views/Activity';
 import { Config } from './views/Config';
 import { SettingsView } from './views/Settings';
 import { Mods } from './views/Mods';
+import { Plugins } from './views/Plugins';
 import { ModView, type ModView as ModViewType } from './views/ModView';
 import { Schedules } from './views/Schedules';
 import { Skills } from './views/Skills';
@@ -39,6 +40,8 @@ import { History } from './views/History';
 import { MiniMaxUsage } from './views/MiniMaxUsage';
 import { BackgroundAgents } from './views/BackgroundAgents';
 import { Doctor } from './views/Doctor';
+import { Eval } from './views/Eval';
+import { EvalReport } from './views/EvalReport';
 import { SettingsNav } from './components/SettingsNav';
 import { Spinner } from './components/Spinner';
 import { Button } from './components/Button';
@@ -92,10 +95,16 @@ const VIEW_MAP: Record<string, (p: ViewProps) => React.ReactNode> = {
   skills: Skills,
   history: History,
   minimax: MiniMaxUsage,
+  plugins: Plugins,
   // v6.0.0 — Doctor page (system health + diagnostics surface).
   // Registered here so the tab id 'doctor' from Topbar.tsx TABS
   // resolves to a real view instead of falling back to Overview.
   doctor: Doctor,
+  // v5.2.0 — Eval framework web UI. `eval` is the sidebar tab
+  // (recent runs summary), `evalReport` is reachable from the
+  // Eval view's "Open Eval Report" button (full report + diff).
+  eval: Eval,
+  evalReport: EvalReport,
 };
 
 const VERSION = 'v4.5.0';

package/bizar-dash/src/web/components/EvalDiff.tsx

@@ -0,0 +1,157 @@
+// src/components/EvalDiff.tsx — v5.2.0
+//
+// Side-by-side comparison of two eval runs. Categorizes each fixture
+// as improved / regressed / unchanged and renders a summary block plus
+// a list of changed fixtures.
+//
+// `runA` is the "before" run (typically an older baseline); `runB` is
+// the "after" run (typically the newer run under review).
+
+import type { ReactNode } from 'react';
+import { cn } from '../lib/utils';
+
+/** Per-fixture result row embedded in a run record. */
+export type EvalFixtureResult = {
+  fixtureId: string;
+  ok: boolean;
+  checks?: { kind: string; ok: boolean; message?: string }[];
+  latencyMs?: number;
+};
+
+export type EvalRunWithResults = {
+  id: string;
+  startedAt: string;
+  finishedAt?: string;
+  suitePath?: string;
+  total: number;
+  passed: number;
+  failed: number;
+  results: EvalFixtureResult[];
+};
+
+export type EvalDiffEntry = {
+  fixtureId: string;
+  /** The fixture's pass/fail status in the "before" run, or null if absent. */
+  before: boolean | null;
+  /** The fixture's pass/fail status in the "after" run, or null if absent. */
+  after: boolean | null;
+  /** Bucket label derived from before/after. */
+  change: 'same' | 'improved' | 'regressed' | 'added' | 'removed';
+};
+
+export type EvalDiffProps = {
+  runA: EvalRunWithResults;
+  runB: EvalRunWithResults;
+  /**
+   * Optional override for the section heading. Defaults to
+   * "Regression Analysis".
+   */
+  title?: string;
+};
+
+/**
+ * Pure helper: compute the diff entries from two runs. Exported so
+ * tests can exercise the categorization logic without rendering.
+ */
+export function computeEvalDiff(
+  runA: EvalRunWithResults,
+  runB: EvalRunWithResults,
+): EvalDiffEntry[] {
+  const mapA = new Map(runA.results.map((r) => [r.fixtureId, r]));
+  const mapB = new Map(runB.results.map((r) => [r.fixtureId, r]));
+  const ids = new Set<string>([...mapA.keys(), ...mapB.keys()]);
+
+  const out: EvalDiffEntry[] = [];
+  for (const id of ids) {
+    const a = mapA.get(id);
+    const b = mapB.get(id);
+    const before = a ? a.ok : null;
+    const after = b ? b.ok : null;
+
+    let change: EvalDiffEntry['change'];
+    if (a && b) {
+      if (before === after) change = 'same';
+      else if (before === false && after === true) change = 'improved';
+      else change = 'regressed';
+    } else if (b && !a) {
+      change = 'added';
+    } else {
+      change = 'removed';
+    }
+
+    out.push({ fixtureId: id, before, after, change });
+  }
+  // Stable sort: regressions first, then improvements, then others.
+  const order: Record<EvalDiffEntry['change'], number> = {
+    regressed: 0,
+    improved: 1,
+    added: 2,
+    removed: 3,
+    same: 4,
+  };
+  out.sort((x, y) => {
+    const d = order[x.change] - order[y.change];
+    if (d !== 0) return d;
+    return x.fixtureId.localeCompare(y.fixtureId);
+  });
+  return out;
+}
+
+export function EvalDiff({ runA, runB, title = 'Regression Analysis' }: EvalDiffProps): ReactNode {
+  const diff = computeEvalDiff(runA, runB);
+
+  const improved = diff.filter((d) => d.change === 'improved').length;
+  const regressed = diff.filter((d) => d.change === 'regressed').length;
+  const unchanged = diff.filter((d) => d.change === 'same').length;
+  const changed = diff.filter((d) => d.change !== 'same');
+
+  return (
+    <div className="eval-diff" data-testid="eval-diff">
+      <h3 className="eval-diff-title">{title}</h3>
+      <div className="eval-diff-subtitle muted">
+        Comparing <code className="mono">{runA.id}</code> →{' '}
+        <code className="mono">{runB.id}</code>
+      </div>
+
+      <div className="eval-diff-stats" aria-label="Diff summary">
+        <span className="eval-diff-stat improved">
+          <span className="eval-diff-stat-icon" aria-hidden>+</span>
+          {improved} improved
+        </span>
+        <span className="eval-diff-stat regressed">
+          <span className="eval-diff-stat-icon" aria-hidden>−</span>
+          {regressed} regressed
+        </span>
+        <span className="eval-diff-stat unchanged muted">
+          {unchanged} unchanged
+        </span>
+      </div>
+
+      {changed.length === 0 ? (
+        <p className="eval-diff-empty muted">No fixture-level changes between these runs.</p>
+      ) : (
+        <ul className="eval-diff-list" role="list">
+          {changed.map((d) => (
+            <li
+              key={d.fixtureId}
+              data-fixture-id={d.fixtureId}
+              className={cn('eval-diff-row', `is-${d.change}`)}
+            >
+              <span className="eval-diff-fixture mono">{d.fixtureId}</span>
+              <span className="eval-diff-arrow" aria-hidden>→</span>
+              <span className="eval-diff-states">
+                <span className={cn('eval-diff-state', d.before ? 'is-pass' : 'is-fail')}>
+                  {d.before === null ? '—' : d.before ? 'pass' : 'fail'}
+                </span>
+                <span className="eval-diff-arrow-small" aria-hidden>→</span>
+                <span className={cn('eval-diff-state', d.after ? 'is-pass' : 'is-fail')}>
+                  {d.after === null ? '—' : d.after ? 'pass' : 'fail'}
+                </span>
+              </span>
+            </li>
+          ))}
+        </ul>
+      )}
+    </div>
+  );
+}