@hybridlabor-api/bdb-synapse 1.0.0

package/web/src/api/client.ts

@@ -0,0 +1,74 @@
+import type { AgentGraph, CityMap, JudgeChoice, ReportStatus, SessionMeta, Trace } from "../types";
+
+async function getJSON<T>(url: string): Promise<T> {
+  const res = await fetch(url);
+  if (!res.ok) {
+    const detail = (await res.text()).trim();
+    throw new Error(detail || `${res.status} ${res.statusText}`);
+  }
+  return res.json() as Promise<T>;
+}
+
+// raw fetch failures read like stack noise in the toast; translate the two
+// failure shapes (server gone vs. server said no) into something actionable
+export function describeError(err: unknown, doing: string): string {
+  if (err instanceof TypeError) {
+    return `Can't reach the Synapse server while ${doing} — is it still running?`;
+  }
+  const detail = (err instanceof Error ? err.message : String(err)).trim();
+  return detail ? `Couldn't finish ${doing}: ${detail}` : `Couldn't finish ${doing}`;
+}
+
+export function listSessions(fresh = false): Promise<SessionMeta[]> {
+  return getJSON<SessionMeta[]>(fresh ? "/api/sessions?fresh=1" : "/api/sessions");
+}
+
+export function getTrace(key: string): Promise<Trace> {
+  return getJSON<Trace>(`/api/sessions/${encodeURIComponent(key)}/trace`);
+}
+
+export function getCityMap(key: string): Promise<CityMap> {
+  return getJSON<CityMap>(`/api/sessions/${encodeURIComponent(key)}/citymap`);
+}
+
+export function getSessionSnapshot(key: string): Promise<{ trace: Trace; city: CityMap }> {
+  return getJSON<{ trace: Trace; city: CityMap }>(`/api/sessions/${encodeURIComponent(key)}/snapshot`);
+}
+
+export function getSessionAgents(rootKey: string): Promise<AgentGraph> {
+  return getJSON<AgentGraph>(`/api/sessions/${encodeURIComponent(rootKey)}/agents`);
+}
+
+export function getAgentTrace(rootKey: string, agentID: string): Promise<Trace> {
+  return getJSON<Trace>(
+    `/api/sessions/${encodeURIComponent(rootKey)}/agents/${encodeURIComponent(agentID)}/trace`
+  );
+}
+
+export function getSessionReport(key: string): Promise<ReportStatus> {
+  return getJSON<ReportStatus>(`/api/sessions/${encodeURIComponent(key)}/report`);
+}
+
+// kicks off a judge run on the server; progress is observed by polling
+// getSessionReport until state leaves "running". The choice picks judge CLI
+// and model; omitted fields fall back to the server's defaults.
+export async function startSessionAnalyze(key: string, choice?: JudgeChoice): Promise<ReportStatus> {
+  const res = await fetch(`/api/sessions/${encodeURIComponent(key)}/analyze`, {
+    method: "POST",
+    headers: choice ? { "Content-Type": "application/json" } : undefined,
+    body: choice ? JSON.stringify(choice) : undefined
+  });
+  if (!res.ok) {
+    const detail = (await res.text()).trim();
+    throw new Error(detail || `${res.status} ${res.statusText}`);
+  }
+  return res.json() as Promise<ReportStatus>;
+}
+
+// backs the static full-repo map view: the citymap for a repo, with no session
+// or trace attached. Without a repo path the server falls back to its
+// configured RepoRoot (the `mindwalk map <repo>` case).
+export function getRepoMap(repo?: string): Promise<CityMap> {
+  const url = repo ? `/api/repomap?repo=${encodeURIComponent(repo)}` : "/api/repomap";
+  return getJSON<CityMap>(url);
+}

package/web/src/main.tsx

@@ -0,0 +1,12 @@
+import { StrictMode } from "react";
+import { createRoot } from "react-dom/client";
+import "@fontsource-variable/fraunces/standard.css";
+import "@fontsource-variable/fraunces/standard-italic.css";
+import "@fontsource-variable/schibsted-grotesk";
+import App from "./App";
+
+createRoot(document.getElementById("root")!).render(
+  <StrictMode>
+    <App />
+  </StrictMode>
+);

package/web/src/playback/recorder.ts

@@ -0,0 +1,160 @@
+// Client-side video export: capture the live WebGL canvas with MediaRecorder
+// while driving the playhead from the first event to the last, then hand back a
+// webm Blob. No server, no extra dependency — captureStream + MediaRecorder are
+// native browser APIs.
+
+export interface RecordOptions {
+  canvas: HTMLCanvasElement;
+  total: number; // number of playback events (trace.events.length)
+  setSeq: (seq: number) => void; // drives the store's currentSeq
+  fps?: number; // capture frame rate
+  durationMs?: number; // wall-clock length of the exported run
+  onProgress?: (fraction: number) => void; // 0..1
+  signal?: AbortSignal; // cancel an in-flight recording
+}
+
+export interface RecordResult {
+  blob: Blob;
+  extension: string; // matches the recorded container (webm / mp4 / …)
+}
+
+// Map a MediaRecorder mimeType to a sensible file extension. Falls back to the
+// container subtype when it's an unknown-but-plausible type.
+function extensionForMime(mimeType: string): string {
+  const base = mimeType.split(";")[0].trim().toLowerCase(); // strip codecs
+  const subtype = base.split("/")[1] ?? "";
+  if (subtype.includes("webm")) return "webm";
+  if (subtype.includes("mp4")) return "mp4";
+  if (subtype.includes("x-matroska") || subtype.includes("matroska")) return "mkv";
+  if (subtype.includes("ogg")) return "ogv";
+  return subtype || "webm";
+}
+
+const DEFAULT_FPS = 30;
+// Long sessions would otherwise produce minutes of video; cap the run and let
+// the playhead cover more events per frame. Short sessions play close to
+// real-ish time via the per-event floor.
+const MAX_DURATION_MS = 30_000;
+const PER_EVENT_MS = 120;
+
+function pickMimeType(): string | undefined {
+  const candidates = ["video/webm;codecs=vp9", "video/webm;codecs=vp8", "video/webm"];
+  for (const type of candidates) {
+    if (typeof MediaRecorder !== "undefined" && MediaRecorder.isTypeSupported(type)) return type;
+  }
+  return undefined;
+}
+
+export function recordingSupported(): boolean {
+  return (
+    typeof MediaRecorder !== "undefined" &&
+    typeof HTMLCanvasElement !== "undefined" &&
+    typeof HTMLCanvasElement.prototype.captureStream === "function"
+  );
+}
+
+// Records the playback and resolves with the recorded blob and a file extension
+// that matches the actual container. Rejects if the browser can't record or the
+// run is aborted.
+export function recordPlayback(opts: RecordOptions): Promise<RecordResult> {
+  const { canvas, total, setSeq, onProgress, signal } = opts;
+  const fps = opts.fps ?? DEFAULT_FPS;
+
+  if (!recordingSupported()) {
+    return Promise.reject(new Error("This browser can't record the canvas (MediaRecorder unavailable)."));
+  }
+  if (total <= 0) {
+    return Promise.reject(new Error("Nothing to record — load a session first."));
+  }
+
+  const durationMs = opts.durationMs ?? Math.min(MAX_DURATION_MS, Math.max(1000, total * PER_EVENT_MS));
+  const mimeType = pickMimeType();
+  const stream = canvas.captureStream(fps);
+  const recorder = mimeType ? new MediaRecorder(stream, { mimeType }) : new MediaRecorder(stream);
+  const chunks: BlobPart[] = [];
+
+  return new Promise<RecordResult>((resolve, reject) => {
+    let rafId = 0;
+    let startTs = 0;
+    let settled = false;
+
+    const cleanup = () => {
+      if (rafId) cancelAnimationFrame(rafId);
+      stream.getTracks().forEach((track) => track.stop());
+      signal?.removeEventListener("abort", onAbort);
+    };
+
+    const finish = () => {
+      if (settled) return;
+      settled = true;
+      cleanup();
+      // the browser may have chosen a container different from what we
+      // requested; trust recorder.mimeType so the blob type and file extension
+      // match what was actually recorded
+      const actualType = recorder.mimeType || mimeType || "video/webm";
+      resolve({ blob: new Blob(chunks, { type: actualType }), extension: extensionForMime(actualType) });
+    };
+
+    const fail = (err: Error) => {
+      if (settled) return;
+      settled = true;
+      cleanup();
+      try {
+        if (recorder.state !== "inactive") recorder.stop();
+      } catch {
+        // recorder already torn down
+      }
+      reject(err);
+    };
+
+    const onAbort = () => fail(new Error("Recording cancelled."));
+
+    recorder.ondataavailable = (e) => {
+      if (e.data && e.data.size > 0) chunks.push(e.data);
+    };
+    recorder.onerror = () => fail(new Error("Recording failed."));
+    recorder.onstop = finish;
+
+    if (signal) {
+      if (signal.aborted) {
+        fail(new Error("Recording cancelled."));
+        return;
+      }
+      signal.addEventListener("abort", onAbort);
+    }
+
+    const tick = (ts: number) => {
+      if (settled) return;
+      if (!startTs) startTs = ts;
+      const fraction = Math.min(1, (ts - startTs) / durationMs);
+      const seq = Math.min(total - 1, Math.floor(fraction * (total - 1)));
+      setSeq(seq);
+      onProgress?.(fraction);
+      if (fraction >= 1) {
+        // let the final frame paint before closing the recorder
+        rafId = requestAnimationFrame(() => {
+          if (recorder.state !== "inactive") recorder.stop();
+        });
+        return;
+      }
+      rafId = requestAnimationFrame(tick);
+    };
+
+    setSeq(0);
+    recorder.start();
+    rafId = requestAnimationFrame(tick);
+  });
+}
+
+// Triggers a browser download of the recorded Blob.
+export function downloadBlob(blob: Blob, filename: string): void {
+  const url = URL.createObjectURL(blob);
+  const a = document.createElement("a");
+  a.href = url;
+  a.download = filename;
+  document.body.appendChild(a);
+  a.click();
+  a.remove();
+  // revoke on the next tick so the download has a chance to start
+  setTimeout(() => URL.revokeObjectURL(url), 1000);
+}

package/web/src/playback/reducer.ts

@@ -0,0 +1,91 @@
+import type { CityMap, Target, Touch, Trace, TraceEvent } from "../types";
+
+export const touchRank: Record<Touch, number> = {
+  hit: 1,
+  read: 2,
+  edit: 3
+};
+
+export interface FilePlayback {
+  touchByFile: Map<number, Touch>;
+  touchByPath: Map<string, Touch>;
+  visitsByFile: Map<number, number>;
+  historyByPath: Map<string, TraceEvent[]>;
+  recentTargets: Target[];
+}
+
+const RECENT_WINDOW = 12;
+
+// Incremental playback state. Stepping the playhead forward applies only the
+// events it crossed; scrubbing backward replays from the start once. Snapshots
+// share the engine's live collections — consumers must treat them as read-only
+// and re-read whenever the snapshot identity changes (one fresh wrapper per
+// snapshotAt call).
+export class PlaybackEngine {
+  private readonly events: TraceEvent[];
+  private readonly idByPath = new Map<string, number>();
+  private cursor = -1;
+  private readonly touchByFile = new Map<number, Touch>();
+  private readonly touchByPath = new Map<string, Touch>();
+  private readonly visitsByFile = new Map<number, number>();
+  private readonly historyByPath = new Map<string, TraceEvent[]>();
+  private readonly recentTargets: Target[] = [];
+
+  constructor(trace: Trace | undefined, city: CityMap | undefined) {
+    this.events = trace?.events ?? [];
+    for (const file of city?.files ?? []) {
+      this.idByPath.set(file.path, file.id);
+    }
+  }
+
+  snapshotAt(seq: number): FilePlayback {
+    const lastSeq = Math.min(seq, this.events.length - 1);
+    if (lastSeq < this.cursor) this.reset();
+    for (let i = this.cursor + 1; i <= lastSeq; i++) {
+      this.apply(this.events[i]);
+    }
+    this.cursor = Math.max(this.cursor, lastSeq);
+    return {
+      touchByFile: this.touchByFile,
+      touchByPath: this.touchByPath,
+      visitsByFile: this.visitsByFile,
+      historyByPath: this.historyByPath,
+      recentTargets: this.recentTargets
+    };
+  }
+
+  private reset() {
+    this.cursor = -1;
+    this.touchByFile.clear();
+    this.touchByPath.clear();
+    this.visitsByFile.clear();
+    this.historyByPath.clear();
+    this.recentTargets.length = 0;
+  }
+
+  private apply(event: TraceEvent) {
+    for (const target of event.targets) {
+      const prev = this.touchByPath.get(target.path);
+      if (!prev || touchRank[target.touch] > touchRank[prev]) {
+        this.touchByPath.set(target.path, target.touch);
+      }
+      const fileId = target.fileId ?? this.idByPath.get(target.path);
+      if (fileId !== undefined) {
+        const prevFile = this.touchByFile.get(fileId);
+        if (!prevFile || touchRank[target.touch] > touchRank[prevFile]) {
+          this.touchByFile.set(fileId, target.touch);
+        }
+        this.visitsByFile.set(fileId, (this.visitsByFile.get(fileId) ?? 0) + 1);
+      }
+      const history = this.historyByPath.get(target.path);
+      if (history) history.push(event);
+      else this.historyByPath.set(target.path, [event]);
+    }
+    if (event.targets.length > 0) {
+      // the trail follows the strongest signal: skip weak (heuristic) targets
+      const primary = event.targets.find((target) => !target.weak) ?? event.targets[0];
+      this.recentTargets.push({ ...primary, fileId: primary.fileId ?? this.idByPath.get(primary.path) });
+      if (this.recentTargets.length > RECENT_WINDOW) this.recentTargets.shift();
+    }
+  }
+}