@galdor/dashboard 0.3.0

package/dist/index.js

@@ -0,0 +1,1683 @@
+/**
+ * Embedded observability dashboard for galdor.
+ *
+ * A self-contained web UI served over either {@link Bun.serve} (under Bun) or
+ * `node:http` (under Node), chosen at runtime by {@link startDashboard}. It reads
+ * the SQLite span store that the CLI and exporter write to and renders a full
+ * trace explorer:
+ *
+ *   - `GET /`                          run list with a live (SSE) tail
+ *   - `GET /runs/:id`                  run detail: timeline, span tree, graph topology
+ *   - `GET /runs/:id/steps`            step-by-step walkthrough of the run
+ *   - `GET /runs/:id/spans/:spanId`    one span: metadata, attributes, captured messages
+ *   - `GET /api/runs`                  JSON run summaries
+ *   - `GET /api/runs/:id/spans`        JSON spans for a run
+ *   - `GET /api/runs/:id/spans/:spanId`JSON for a single span
+ *   - `GET /api/runs/:id/graph`        JSON graph topology recorded for a run
+ *   - `GET /api/orphans`               orphan-span count
+ *   - `GET /events`                    Server-Sent Events live-tail of the run list
+ *
+ * All HTML, CSS, and the one small client script are inlined in this module —
+ * the interactive timeline and graph are rendered server-side as SVG, so the UI
+ * works without any client-side framework and ships as a single importable unit.
+ *
+ * @see {@link startDashboard} to launch the server.
+ * @see {@link createHandler} to obtain the request handler on its own.
+ */
+import { createServer } from "node:http";
+import { isIP } from "node:net";
+import { END, START } from "@galdor/core/graph";
+import { runDuration, runStatus, spanDuration, Store } from "@galdor/core/store";
+/** `true` when running on the Bun runtime; `false` under Node (or any other host). */
+const isBun = typeof globalThis.Bun !== "undefined";
+/**
+ * Attribute keys and span names recorded by the tracing layer. These mirror the
+ * constants exported from `@galdor/core/observability`; they are kept local so
+ * the viewer depends only on the span store, not on the tracing SDK.
+ */
+const A = {
+    node: "galdor.node.name",
+    label: "galdor.span.label",
+    provider: "galdor.provider.name",
+    streaming: "galdor.provider.streaming",
+    step: "galdor.step",
+    prompt: "gen_ai.prompt",
+    completion: "gen_ai.completion",
+    reasoning: "gen_ai.reasoning",
+    reqModel: "gen_ai.request.model",
+    respModel: "gen_ai.response.model",
+    finish: "gen_ai.response.finish_reasons",
+    inTokens: "gen_ai.usage.input_tokens",
+    outTokens: "gen_ai.usage.output_tokens",
+    toolName: "gen_ai.tool.name",
+    toolIn: "gen_ai.tool.input_size_bytes",
+    toolOut: "gen_ai.tool.output_size_bytes",
+    reqTools: "gen_ai.request.tools",
+    system: "gen_ai.system",
+};
+const SPAN = {
+    run: "galdor.graph.run",
+    node: "galdor.graph.node",
+    generate: "galdor.provider.generate",
+    stream: "galdor.provider.stream",
+    tool: "galdor.tool.execute",
+};
+/** Map a span name to its display kind. */
+function kindOf(name) {
+    if (name === SPAN.run)
+        return "run";
+    if (name === SPAN.node)
+        return "node";
+    if (name === SPAN.generate || name === SPAN.stream)
+        return "model";
+    if (name === SPAN.tool)
+        return "tool";
+    return "other";
+}
+/** CSS custom-property colour for each span kind. */
+const KIND_FILL = {
+    run: "var(--accent)",
+    node: "var(--slate)",
+    model: "var(--blue)",
+    tool: "var(--violet)",
+    other: "var(--subtle)",
+};
+/** Convert a nanosecond count to whole milliseconds. */
+const nanosToMs = (n) => Number(n / 1000000n);
+/** Like {@link JSON.stringify} but renders `bigint` values as decimal numbers (safe at millisecond scale). */
+function toJSON(value) {
+    return JSON.stringify(value, (_k, v) => (typeof v === "bigint" ? Number(v) : v));
+}
+/** Wrap a value as a JSON {@link Response} with the given status. */
+function json(value, status = 200) {
+    return new Response(toJSON(value), { status, headers: { "content-type": "application/json" } });
+}
+/** Wrap an HTML body as a UTF-8 {@link Response} with the given status. */
+function html(body, status = 200) {
+    return new Response(body, { status, headers: { "content-type": "text/html; charset=utf-8" } });
+}
+/** Wrap an SVG document as an `image/svg+xml` {@link Response}. */
+function svg(body) {
+    return new Response(body, { headers: { "content-type": "image/svg+xml; charset=utf-8", "cache-control": "no-cache" } });
+}
+// ── request guards (caps, limits, host allowlist) ────────────────────────────────
+/**
+ * Body-size cap for `POST /api/graph/svg`. A spec larger than this is almost
+ * certainly an attempt to amplify a small POST into a multi-megabyte SVG
+ * buffered in memory, so it is rejected before decoding.
+ */
+const MAX_GRAPH_SVG_BODY = 1 << 20; // 1 MiB
+/**
+ * Node-count cap for a rendered graph. The SVG grows with the node count, so
+ * this bounds peak render memory even for a body that fits under
+ * {@link MAX_GRAPH_SVG_BODY}.
+ */
+const MAX_GRAPH_NODES = 2000;
+/** Floor applied to the SSE poll cadence so a caller can't drive a hot loop against SQLite. */
+const MIN_STREAM_INTERVAL_MS = 100;
+/**
+ * DNS-rebinding protection. A rebinding attack relies on a domain name (which
+ * the attacker can re-point at `127.0.0.1`) in the `Host` header, so only
+ * `localhost`, IP literals (which can't be rebound) and explicitly allowed
+ * hostnames are accepted. A bare/absent host is treated as loopback.
+ *
+ * @param hostname - The request URL hostname (IPv6 arrives bracketed).
+ * @param allowed - Extra hostnames to accept beyond localhost/IP literals.
+ */
+function hostAllowed(hostname, allowed) {
+    let host = hostname;
+    if (host.startsWith("[") && host.endsWith("]"))
+        host = host.slice(1, -1); // unwrap IPv6 literal
+    if (host === "" || host === "localhost")
+        return true;
+    if (isIP(host) !== 0)
+        return true;
+    return allowed.has(host);
+}
+/** Parse a `?limit`, clamping to `1..500`; blank/invalid falls back to `fallback`. */
+function parseLimit(raw, fallback) {
+    if (!raw || !/^-?\d+$/.test(raw.trim()))
+        return fallback;
+    const n = Number.parseInt(raw, 10);
+    if (n <= 0)
+        return fallback;
+    return n > 500 ? 500 : n;
+}
+/** Parse a Go-style duration (`500ms`, `2s`, `1us`) to milliseconds, or `undefined`. */
+function parseDurationMs(raw) {
+    const m = raw.trim().match(/^(\d+(?:\.\d+)?)(ns|us|µs|ms|s|m|h)$/);
+    if (!m)
+        return undefined;
+    const factor = { ns: 1e-6, us: 1e-3, "µs": 1e-3, ms: 1, s: 1000, m: 60000, h: 3600000 };
+    return Number(m[1]) * factor[m[2]];
+}
+/**
+ * Parse the SSE `?interval`: a Go-style duration or a plain millisecond count,
+ * defaulting to `fallbackMs` and floored at {@link MIN_STREAM_INTERVAL_MS}.
+ */
+function parseInterval(raw, fallbackMs) {
+    let ms = fallbackMs;
+    if (raw) {
+        const dur = parseDurationMs(raw);
+        if (dur !== undefined && dur > 0) {
+            ms = dur;
+        }
+        else {
+            const n = Number.parseInt(raw, 10);
+            if (Number.isFinite(n) && n > 0)
+                ms = n;
+        }
+    }
+    return ms < MIN_STREAM_INTERVAL_MS ? MIN_STREAM_INTERVAL_MS : ms;
+}
+/** Parse the test-only `_max-iterations` bound; `0` (the default) means run until the client leaves. */
+function parseMaxIters(raw) {
+    if (!raw || !/^-?\d+$/.test(raw.trim()))
+        return 0;
+    return Number.parseInt(raw, 10);
+}
+/**
+ * Build the dashboard request handler bound to a span store.
+ *
+ * The returned function routes requests to the HTML pages, JSON endpoints, and
+ * the SSE live-tail described in the module overview, and answers `404` for any
+ * unmatched path. Use it directly when embedding the dashboard in an existing
+ * server, or let {@link startDashboard} wire it into {@link Bun.serve} for you.
+ *
+ * Requests whose `Host` header is a domain name (rather than `localhost` or an
+ * IP literal) are rejected with `403` as a DNS-rebinding guard; extend the
+ * allowlist via {@link HandlerOptions.allowedHosts}.
+ *
+ * @param store - The {@link Store} whose runs and spans are served.
+ * @param opts - Optional {@link HandlerOptions}.
+ * @returns A fetch handler that maps a {@link Request} to a {@link Response}.
+ * @example
+ * ```ts
+ * const handler = createHandler(Store.openExisting("spans.db"));
+ * const res = handler(new Request("http://127.0.0.1/api/runs"));
+ * ```
+ */
+export function createHandler(store, opts = {}) {
+    const allowedHosts = new Set(opts.allowedHosts ?? []);
+    return (req) => {
+        const url = new URL(req.url);
+        const path = url.pathname;
+        // DNS-rebinding guard: reject any Host that isn't loopback / an IP literal.
+        if (!hostAllowed(url.hostname, allowedHosts))
+            return new Response("forbidden host", { status: 403 });
+        // Health check for liveness probes.
+        if (path === "/healthz")
+            return new Response("ok", { headers: { "content-type": "text/plain" } });
+        // Render an arbitrary client-supplied graph spec to SVG (not tied to a run).
+        if (path === "/api/graph/svg" && req.method === "POST")
+            return renderPostedGraphSVG(req, url);
+        if (path === "/")
+            return html(runListPage(store, parseLimit(url.searchParams.get("limit"), 50)));
+        if (path === "/graph")
+            return html(graphExplorerPage(store, url));
+        if (path === "/api/runs")
+            return json(runListJSON(store, parseLimit(url.searchParams.get("limit"), 50)));
+        if (path === "/api/orphans")
+            return json({ orphans: store.orphanSpanCount() });
+        if (path === "/events")
+            return sseLiveTail(store, url);
+        let m = path.match(/^\/api\/runs\/([^/]+)\/spans\/([^/]+)$/);
+        if (m) {
+            const s = findSpan(store, decodeURIComponent(m[1]), decodeURIComponent(m[2]));
+            return s ? json(spanJSON(s)) : json({ error: "span not found" }, 404);
+        }
+        m = path.match(/^\/api\/runs\/([^/]+)\/spans$/);
+        if (m) {
+            const runId = decodeURIComponent(m[1]);
+            const spans = store.spansForRun(runId);
+            if (spans.length === 0)
+                return json({ error: `run ${runId} not found` }, 404);
+            return json(spans.map(spanJSON));
+        }
+        m = path.match(/^\/api\/runs\/([^/]+)\/graph\/model$/);
+        if (m) {
+            const id = decodeURIComponent(m[1]);
+            const spec = graphSpec(store, id);
+            return spec
+                ? json(graphModel(spec, store.spansForRun(id)))
+                : json({ error: "no graph topology recorded for this run" }, 404);
+        }
+        m = path.match(/^\/api\/runs\/([^/]+)\/graph\/svg$/);
+        if (m) {
+            const id = decodeURIComponent(m[1]);
+            const spec = graphSpec(store, id);
+            if (!spec)
+                return json({ error: "no graph topology recorded for this run" }, 404);
+            const theme = url.searchParams.get("theme") === "dark" ? "dark" : "light";
+            return svg(graphSVG(id, spec, store.spansForRun(id), { standalone: true, theme }));
+        }
+        m = path.match(/^\/api\/runs\/([^/]+)\/graph$/);
+        if (m) {
+            const spec = graphSpec(store, decodeURIComponent(m[1]));
+            return spec ? json(spec) : json({ error: "no graph topology recorded for this run" }, 404);
+        }
+        m = path.match(/^\/runs\/([^/]+)\/spans\/([^/]+)$/);
+        if (m) {
+            const runId = decodeURIComponent(m[1]), spanId = decodeURIComponent(m[2]);
+            const found = findSpan(store, runId, spanId);
+            return html(spanDetailPage(store, runId, spanId), found ? 200 : 404);
+        }
+        m = path.match(/^\/runs\/([^/]+)\/steps$/);
+        if (m) {
+            const runId = decodeURIComponent(m[1]);
+            const exists = store.spansForRun(runId).length > 0;
+            return html(stepsPage(store, runId), exists ? 200 : 404);
+        }
+        m = path.match(/^\/runs\/([^/]+)$/);
+        if (m) {
+            const runId = decodeURIComponent(m[1]);
+            const exists = store.spansForRun(runId).length > 0;
+            return html(runDetailPage(store, runId), exists ? 200 : 404);
+        }
+        return new Response("not found", { status: 404 });
+    };
+}
+/**
+ * Start the dashboard HTTP server.
+ *
+ * Serves from {@link DashboardOptions.store} when provided, otherwise opens the
+ * store at {@link DashboardOptions.dbPath} (defaulting to an in-memory store).
+ *
+ * The transport is chosen by runtime: on Bun the server is backed by
+ * {@link Bun.serve}; on Node it is backed by `node:http`, with an adapter that
+ * converts each incoming request into a Web {@link Request}, runs the same
+ * {@link createHandler} handler, and streams the Web {@link Response} back —
+ * including unbounded Server-Sent Events bodies. Either way the return value
+ * conforms to {@link DashboardServer}.
+ *
+ * @param opts - Server and store {@link DashboardOptions | options}.
+ * @returns The running {@link DashboardServer}; call `.stop()` to shut it down.
+ * @example
+ * ```ts
+ * const server = startDashboard({ dbPath: "spans.db", port: 7777 });
+ * // ...later
+ * server.stop();
+ * ```
+ */
+export function startDashboard(opts = {}) {
+    const store = opts.store ?? Store.openExisting(opts.dbPath ?? ":memory:");
+    const handler = createHandler(store);
+    const hostname = opts.hostname ?? "127.0.0.1";
+    const port = opts.port ?? 7777;
+    if (isBun) {
+        const server = Bun.serve({ hostname, port, fetch: handler });
+        return {
+            get port() {
+                return server.port ?? port;
+            },
+            get hostname() {
+                return server.hostname ?? hostname;
+            },
+            // Bun resolves the ephemeral port synchronously, so the server is ready at once.
+            ready: Promise.resolve(),
+            stop(force) {
+                void server.stop(force);
+            },
+        };
+    }
+    return startNodeDashboard(handler, hostname, port);
+}
+// ── Node (node:http) transport ───────────────────────────────────────────────────
+/**
+ * Back the dashboard with `node:http` when not running under Bun.
+ *
+ * For every request the Node {@link IncomingMessage} is adapted to a Web
+ * {@link Request} (see {@link toWebRequest}), passed through the shared handler,
+ * and the resulting Web {@link Response} is written back to the
+ * {@link ServerResponse} by streaming its body (see {@link writeWebResponse}).
+ * Open responses are tracked so {@link DashboardServer.stop | stop} can tear
+ * down live SSE streams and let the listener close.
+ */
+function startNodeDashboard(handler, hostname, port) {
+    const active = new Set();
+    const server = createServer((req, res) => {
+        active.add(res);
+        res.on("close", () => active.delete(res));
+        void (async () => {
+            let webRes;
+            try {
+                webRes = await handler(toWebRequest(req, hostname, boundPort()));
+            }
+            catch (e) {
+                res.writeHead(500, { "content-type": "text/plain" });
+                res.end(e.message);
+                return;
+            }
+            await writeWebResponse(res, webRes);
+        })();
+    });
+    // node:http binds asynchronously: server.address() (and thus an ephemeral
+    // port) is null until the "listening" event fires. Expose that as `ready`.
+    const ready = new Promise((resolve) => server.once("listening", () => resolve()));
+    server.listen(port, hostname);
+    /** The OS-assigned port once listening, falling back to the requested port. */
+    const boundPort = () => {
+        const addr = server.address();
+        return addr && typeof addr === "object" ? addr.port : port;
+    };
+    return {
+        get port() {
+            return boundPort();
+        },
+        hostname,
+        ready,
+        stop() {
+            // Destroy live connections (notably open SSE streams) so close() can settle.
+            for (const res of active)
+                res.destroy();
+            active.clear();
+            server.close();
+        },
+    };
+}
+/**
+ * Adapt a Node {@link IncomingMessage} to a Web {@link Request}.
+ *
+ * Reconstructs the absolute URL from the `Host` header (or the bound address),
+ * copies method and headers, and — for methods that carry a body — wraps the
+ * request stream in a {@link ReadableStream}. The dashboard only serves `GET`,
+ * but body forwarding keeps the adapter general.
+ */
+function toWebRequest(req, hostname, port) {
+    const host = req.headers.host ?? `${hostname}:${port}`;
+    const url = `http://${host}${req.url ?? "/"}`;
+    const method = req.method ?? "GET";
+    const headers = new Headers();
+    for (const [key, value] of Object.entries(req.headers)) {
+        if (value === undefined)
+            continue;
+        if (Array.isArray(value))
+            for (const v of value)
+                headers.append(key, v);
+        else
+            headers.set(key, value);
+    }
+    const hasBody = method !== "GET" && method !== "HEAD";
+    if (!hasBody)
+        return new Request(url, { method, headers });
+    const body = new ReadableStream({
+        start(controller) {
+            req.on("data", (chunk) => controller.enqueue(new Uint8Array(chunk)));
+            req.on("end", () => controller.close());
+            req.on("error", (err) => controller.error(err));
+        },
+    });
+    // `duplex` is required when streaming a request body but is missing from the lib DOM types.
+    return new Request(url, { method, headers, body, duplex: "half" });
+}
+/**
+ * Write a Web {@link Response} back to a Node {@link ServerResponse}.
+ *
+ * The status and headers are flushed first, then the response body is streamed
+ * chunk-by-chunk. This handles both finite bodies (HTML/JSON, whose stream ends)
+ * and the unbounded SSE live-tail (whose stream only ends when the client
+ * disconnects): when the socket closes, the reader is cancelled, which runs the
+ * body's `cancel()` and clears the SSE interval. String chunks (the SSE handler
+ * enqueues strings) and byte chunks are both encoded to a {@link Buffer}.
+ */
+async function writeWebResponse(res, webRes) {
+    const headers = {};
+    webRes.headers.forEach((value, key) => {
+        headers[key] = value;
+    });
+    res.writeHead(webRes.status, headers);
+    const body = webRes.body;
+    if (!body) {
+        res.end();
+        return;
+    }
+    const reader = body.getReader();
+    let cancelled = false;
+    const cancel = () => {
+        if (cancelled)
+            return;
+        cancelled = true;
+        void reader.cancel().catch(() => { });
+    };
+    // If the client hangs up (e.g. closes the SSE connection), stop pulling.
+    res.on("close", cancel);
+    try {
+        for (;;) {
+            const { done, value } = await reader.read();
+            if (done)
+                break;
+            const chunk = typeof value === "string" ? Buffer.from(value) : Buffer.from(value);
+            if (!res.write(chunk))
+                await new Promise((resolve) => res.once("drain", resolve));
+        }
+    }
+    catch {
+        // Stream errored or was aborted mid-flight — fall through to end the response.
+    }
+    if (!res.writableEnded)
+        res.end();
+}
+// ── JSON shaping ───────────────────────────────────────────────────────────────
+function runSummaryJSON(r) {
+    return {
+        runId: r.runId,
+        traceId: r.traceId,
+        startMs: nanosToMs(r.startTimeUnixNano),
+        durationMs: nanosToMs(runDuration(r)),
+        spanCount: r.spanCount,
+        errorCount: r.errorCount,
+        status: runStatus(r),
+    };
+}
+function runListJSON(store, limit = 100) {
+    return store.listRuns(limit).map(runSummaryJSON);
+}
+/** Parse the graph topology recorded for a run, or `undefined` when none exists. */
+function graphSpec(store, runId) {
+    const raw = store.getGraphSpec(runId);
+    if (raw === "")
+        return undefined;
+    try {
+        return normalizeSpec(JSON.parse(raw));
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Render an arbitrary {@link GraphSpec} POSTed in the request body to SVG. Lets
+ * tools preview a topology without first recording a run. Accepts either spec
+ * encoding (see {@link normalizeSpec}); `?theme=dark|light` selects colours.
+ */
+async function renderPostedGraphSVG(req, url) {
+    const text = await req.text();
+    // Reject an oversized body before decoding — a spec this large is almost
+    // certainly an attempt to amplify a small POST into a multi-MB SVG.
+    if (byteLength(text) > MAX_GRAPH_SVG_BODY) {
+        return json({ error: "spec too large: body exceeds limit" }, 400);
+    }
+    let body;
+    try {
+        body = JSON.parse(text);
+    }
+    catch (e) {
+        return json({ error: `invalid JSON body: ${e.message}` }, 400);
+    }
+    const spec = normalizeSpec(body);
+    if (!spec)
+        return json({ error: "body is not a valid graph spec" }, 400);
+    // Cap the node count: the SVG grows with the node count, so this bounds peak
+    // render memory even for a body that fits under the byte cap.
+    if (spec.nodes.length > MAX_GRAPH_NODES) {
+        return json({ error: "spec too large: node count exceeds limit" }, 400);
+    }
+    const theme = url.searchParams.get("theme") === "dark" ? "dark" : "light";
+    return svg(graphSVG("(custom)", spec, [], { standalone: true, theme }));
+}
+/** Byte length of a UTF-8 string without allocating the full encoded buffer where possible. */
+function byteLength(s) {
+    return new TextEncoder().encode(s).length;
+}
+/**
+ * Standalone graph-explorer page: a run picker that links to each run's recorded
+ * topology, plus a textarea to paste an arbitrary spec and render it via
+ * `POST /api/graph/svg`.
+ */
+function graphExplorerPage(store, url) {
+    const runs = store.listRuns(100).filter((r) => store.getGraphSpec(r.runId) !== "");
+    // ?run=<id> selects a run directly; default to the latest run with a topology.
+    let selected = url.searchParams.get("run") ?? "";
+    if (selected === "" && runs.length > 0)
+        selected = runs[0].runId;
+    const options = runs.length === 0
+        ? `<li class="muted">(no runs with a recorded topology yet)</li>`
+        : runs.map((r) => {
+            const mark = r.runId === selected ? " ← selected" : "";
+            return `<li><a href="/graph?run=${enc(r.runId)}">${esc(r.runId)}</a>${mark} · <a href="/runs/${enc(r.runId)}">detail</a></li>`;
+        }).join("");
+    // Server-render the selected run's topology inline (clickable per-node SVG).
+    const theme = url.searchParams.get("theme") === "dark" ? "dark" : "light";
+    const spec = selected ? graphSpec(store, selected) : undefined;
+    const selectedSVG = spec
+        ? `<h2>topology for <code>${esc(selected)}</code></h2>${graphSVG(selected, spec, store.spansForRun(selected), { standalone: false, theme })}`
+        : selected
+            ? `<h2>topology for <code>${esc(selected)}</code></h2><p class="muted">no graph topology recorded for this run</p>`
+            : "";
+    const placeholder = esc('{ "entry": "a", "nodes": [{"name":"a"}], "edges": [], "conditional": [] }');
+    return shell("graph explorer", `<h1>graph explorer</h1>
+    <h2>runs with a recorded topology</h2>
+    <ul class="runs-graph">${options}</ul>
+    ${selectedSVG}
+    <h2>render an arbitrary spec</h2>
+    <p class="subtle">Paste a graph spec and render it to SVG.</p>
+    <textarea id="spec" rows="8" style="width:100%;font-family:var(--mono);" placeholder="${placeholder}"></textarea>
+    <p><button id="render">render</button></p>
+    <div id="out"></div>
+    <script>
+    document.getElementById('render').addEventListener('click', async () => {
+      const out = document.getElementById('out');
+      try {
+        const res = await fetch('/api/graph/svg', { method: 'POST', headers: { 'content-type': 'application/json' }, body: document.getElementById('spec').value });
+        if (!res.ok) { out.textContent = 'error: ' + (await res.json()).error; return; }
+        out.innerHTML = await res.text();
+      } catch (e) { out.textContent = 'error: ' + e.message; }
+    });
+    </script>`);
+}
+/**
+ * Normalize a recorded graph spec into {@link GraphSpec}.
+ *
+ * Accepts two equivalent encodings: nodes as plain names with `edges` /
+ * `conditional`, or nodes as `{name}` objects with `static_edges` /
+ * `conditional_edges` whose branches are `[{label,to}]`. Both describe the same
+ * topology, so either renders identically.
+ */
+function normalizeSpec(v) {
+    if (!v || typeof v !== "object")
+        return undefined;
+    const o = v;
+    const entry = typeof o.entry === "string" ? o.entry : "";
+    const rawNodes = Array.isArray(o.nodes) ? o.nodes : [];
+    const nodes = rawNodes
+        .map((n) => {
+        if (typeof n === "string")
+            return { name: n };
+        const obj = n;
+        if (obj && typeof obj.name === "string") {
+            return obj.interrupt ? { name: obj.name, interrupt: true } : { name: obj.name };
+        }
+        return { name: "" };
+    })
+        .filter((n) => n.name.length > 0);
+    const rawEdges = Array.isArray(o.edges) ? o.edges : Array.isArray(o.static_edges) ? o.static_edges : [];
+    const edges = rawEdges
+        .filter((e) => !!e && typeof e.from === "string" && typeof e.to === "string")
+        .map((e) => ({ from: e.from, to: e.to }));
+    let conditional = [];
+    if (Array.isArray(o.conditional)) {
+        conditional = o.conditional
+            .filter((c) => !!c && typeof c.from === "string")
+            .map((c) => (c.labels ? { from: c.from, labels: c.labels } : { from: c.from }));
+    }
+    else if (Array.isArray(o.conditional_edges)) {
+        conditional = o.conditional_edges
+            .filter((c) => !!c && typeof c.from === "string")
+            .map((c) => {
+            if (Array.isArray(c.branches) && c.branches.length > 0) {
+                const labels = {};
+                for (const b of c.branches) {
+                    if (b && typeof b.label === "string" && typeof b.to === "string")
+                        labels[b.label] = b.to;
+                }
+                return { from: c.from, labels };
+            }
+            return { from: c.from };
+        });
+    }
+    if (!entry && nodes.length === 0 && edges.length === 0 && conditional.length === 0)
+        return undefined;
+    return { entry, nodes, edges, conditional };
+}
+function spanJSON(s) {
+    return {
+        spanId: s.spanId,
+        parentSpanId: s.parentSpanId,
+        traceId: s.traceId,
+        name: s.name,
+        startMs: nanosToMs(s.startTimeUnixNano),
+        durationMs: Number(spanDuration(s)) / 1e6,
+        statusCode: s.statusCode,
+        statusMessage: s.statusMessage,
+        attributes: s.attributes,
+        events: s.events.map((e) => ({ name: e.name, timeMs: nanosToMs(e.timeUnixNano), attributes: e.attributes })),
+    };
+}
+function spansJSON(store, runId) {
+    return store.spansForRun(runId).map(spanJSON);
+}
+function findSpan(store, runId, spanId) {
+    return store.spansForRun(runId).find((s) => s.spanId === spanId);
+}
+// ── SSE live tail ───────────────────────────────────────────────────────────────
+/**
+ * Server-Sent Events feed of run summaries as new spans land. Mirrors the
+ * oracle's `handleStreamRuns`:
+ *
+ *   event: run         data: <run summary JSON>   (one per newly-touched run)
+ *   event: heartbeat   data: <unix-ms int>        (every tick, keeps proxies open)
+ *
+ * A rowid cursor (seeded at the current max) means a freshly-connected client
+ * only receives runs touched *after* it connected — the existing runs are
+ * already in the static page render. `?interval` sets the cadence (Go-style
+ * duration or plain ms; floored at {@link MIN_STREAM_INTERVAL_MS}); the internal
+ * `?_max-iterations` bounds the loop for tests.
+ */
+function sseLiveTail(store, url) {
+    const interval = parseInterval(url.searchParams.get("interval"), 1000);
+    const maxIters = Number.parseInt(url.searchParams.get("_max-iterations") ?? "", 10);
+    let timer;
+    // Seed the cursor at the current max so historical runs aren't replayed.
+    let cursor = store.maxSpanRowid();
+    const emitted = new Map(); // runId -> last emitted end time, dedups updates
+    let iter = 0;
+    const stream = new ReadableStream({
+        start(controller) {
+            const send = (event, data) => controller.enqueue(`event: ${event}\ndata: ${data}\n\n`);
+            const tick = () => {
+                try {
+                    iter++;
+                    const { spans, cursor: next } = store.spansSince(cursor, 500);
+                    cursor = next;
+                    const touched = new Set(spans.map((s) => s.traceId));
+                    if (touched.size > 0) {
+                        for (const summary of store.listRuns(500)) {
+                            if (!touched.has(summary.traceId))
+                                continue;
+                            const prev = emitted.get(summary.runId);
+                            if (prev !== undefined && prev === summary.endTimeUnixNano)
+                                continue;
+                            emitted.set(summary.runId, summary.endTimeUnixNano);
+                            send("run", toJSON(runSummaryJSON(summary)));
+                        }
+                    }
+                    send("heartbeat", String(Date.now()));
+                    if (Number.isFinite(maxIters) && maxIters > 0 && iter >= maxIters) {
+                        if (timer)
+                            clearInterval(timer);
+                        controller.close();
+                    }
+                }
+                catch {
+                    if (timer)
+                        clearInterval(timer);
+                }
+            };
+            timer = setInterval(tick, interval);
+            timer.unref?.();
+        },
+        cancel() {
+            if (timer)
+                clearInterval(timer);
+        },
+    });
+    return new Response(stream, {
+        headers: {
+            "content-type": "text/event-stream",
+            "cache-control": "no-cache",
+            connection: "keep-alive",
+            "x-accel-buffering": "no",
+        },
+    });
+}
+// ── formatting helpers ───────────────────────────────────────────────────────────
+function esc(s) {
+    return s.replace(/[&<>"]/g, (c) => ({ "&": "&amp;", "<": "&lt;", ">": "&gt;", '"': "&quot;" })[c]);
+}
+const enc = encodeURIComponent;
+/** Format a nanosecond duration as a compact, human-readable string. */
+function fmtDur(ns) {
+    const ms = Number(ns) / 1e6;
+    if (ms >= 1000)
+        return `${(ms / 1000).toFixed(2)} s`;
+    if (ms >= 1)
+        return `${ms.toFixed(1)} ms`;
+    if (ms > 0)
+        return `${ms.toFixed(2)} ms`;
+    return "0 ms";
+}
+/** Truncate a long id to `head…tail` form for compact display. */
+function shortId(s) {
+    return s.length > 18 ? `${s.slice(0, 8)}…${s.slice(-4)}` : s;
+}
+/** Strip the `galdor.` prefix from a span name for readability. */
+function shortName(name) {
+    return name.replace(/^galdor\./, "");
+}
+/** Display label for a graph node, naming the sentinel start/end nodes. */
+function nodeLabel(n) {
+    return n === START ? "start" : n === END ? "end" : n;
+}
+/** Read a string attribute, or `undefined` when absent or not a string. */
+function attrStr(attrs, key) {
+    const v = attrs[key];
+    return typeof v === "string" ? v : undefined;
+}
+/** Read a numeric attribute, coercing numeric strings, or `undefined`. */
+function attrNum(attrs, key) {
+    const v = attrs[key];
+    if (typeof v === "number")
+        return v;
+    if (typeof v === "string" && v !== "" && !Number.isNaN(Number(v)))
+        return Number(v);
+    return undefined;
+}
+/** Render an arbitrary attribute value for the attributes table. */
+function fmtVal(v) {
+    if (typeof v === "string")
+        return v;
+    if (typeof v === "number" || typeof v === "boolean")
+        return String(v);
+    try {
+        return JSON.stringify(v);
+    }
+    catch {
+        return String(v);
+    }
+}
+/** Lay spans out in depth-first preorder (children under parents, by start time). */
+function orderSpans(spans) {
+    const byId = new Map(spans.map((s) => [s.spanId, s]));
+    const children = new Map();
+    const roots = [];
+    for (const s of spans) {
+        const p = s.parentSpanId;
+        if (p && byId.has(p)) {
+            const arr = children.get(p) ?? [];
+            arr.push(s);
+            children.set(p, arr);
+        }
+        else {
+            roots.push(s);
+        }
+    }
+    const cmp = (a, b) => a.startTimeUnixNano < b.startTimeUnixNano ? -1 : a.startTimeUnixNano > b.startTimeUnixNano ? 1 : 0;
+    const out = [];
+    const walk = (s, depth) => {
+        out.push({ span: s, depth });
+        for (const c of (children.get(s.spanId) ?? []).sort(cmp))
+            walk(c, depth + 1);
+    };
+    for (const r of roots.sort(cmp))
+        walk(r, 0);
+    return out;
+}
+/** The earliest start and latest end across a set of spans. */
+function runBounds(spans) {
+    let t0 = spans[0].startTimeUnixNano;
+    let t1 = spans[0].endTimeUnixNano;
+    for (const s of spans) {
+        if (s.startTimeUnixNano < t0)
+            t0 = s.startTimeUnixNano;
+        if (s.endTimeUnixNano > t1)
+            t1 = s.endTimeUnixNano;
+    }
+    return { t0, t1 };
+}
+// ── HTML shell ───────────────────────────────────────────────────────────────────
+const STYLE = `
+:root{
+  --bg:#131314; --bg2:#1b1c1d; --panel:#1e1f20; --panel2:#28292b; --raised:#2d2f31;
+  --border:#303134; --border2:#3c4043; --fg:#e3e3e3; --muted:#bdc1c6; --subtle:#9aa0a6;
+  --accent:#8ab4f8; --accent-soft:rgba(138,180,248,.12);
+  --blue:#8ab4f8; --violet:#c58af9; --slate:#9aa0a6;
+  --ok:#81c995; --err:#f28b82; --warn:#fdd663;
+  --edge:#5b636f; --node-stroke:#454a52; --grid:#34363a;
+  --radius:12px; --mono:"Roboto Mono",ui-monospace,SFMono-Regular,Menlo,Consolas,monospace;
+  --sans:"Google Sans","Google Sans Text","Product Sans",Inter,system-ui,-apple-system,"Segoe UI",Roboto,Arial,sans-serif;
+}
+:root,:root[data-theme="dark"]{color-scheme:dark;}
+:root[data-theme="light"]{
+  color-scheme:light;
+  --bg:#ffffff; --bg2:#f0f4f9; --panel:#ffffff; --panel2:#f3f6fc; --raised:#e9eef6;
+  --border:#dde3ea; --border2:#c4cad1; --fg:#1f1f1f; --muted:#444746; --subtle:#6f7378;
+  --accent:#0b57d0; --accent-soft:rgba(11,87,208,.08);
+  --blue:#0b57d0; --violet:#8430ce; --slate:#5f6368;
+  --ok:#188038; --err:#c5221f; --warn:#9a6700;
+  --edge:#80868b; --node-stroke:#9aa0a6; --grid:#c4cad1;
+}
+*{box-sizing:border-box;}
+html,body{margin:0;}
+body{
+  background:var(--bg);
+  color:var(--fg); font:14px/1.55 var(--sans); -webkit-font-smoothing:antialiased; text-rendering:optimizeLegibility;
+}
+a{color:var(--accent); text-decoration:none;} a:hover{text-decoration:underline;}
+code,pre,.mono{font-family:var(--mono);}
+.muted{color:var(--muted);} .subtle{color:var(--subtle);}
+
+.topbar{position:sticky; top:0; z-index:10; display:flex; align-items:center; gap:14px;
+  padding:12px 26px; background:var(--bg2); border-bottom:1px solid var(--border);}
+.brand{display:flex; align-items:baseline; gap:9px;}
+.brand .mark{font-weight:500; font-size:16px; letter-spacing:0; color:var(--fg);}
+.brand .mark a{color:var(--fg);}
+.brand .tag{font-size:12px; color:var(--subtle); letter-spacing:0;}
+.topbar .spacer{flex:1;}
+.live{display:inline-flex; align-items:center; gap:7px; font-size:12px; color:var(--subtle);}
+.icon-btn{display:inline-flex; align-items:center; justify-content:center; width:34px; height:34px;
+  border:1px solid var(--border2); border-radius:9px; background:var(--panel2); color:var(--muted);
+  cursor:pointer; font:15px/1 var(--sans); transition:border-color .12s,color .12s,background .12s;}
+.icon-btn:hover{border-color:var(--accent); color:var(--fg); background:var(--raised);}
+.live .pulse{width:7px; height:7px; border-radius:50%; background:var(--ok); opacity:.9; animation:pulse 2.4s ease-in-out infinite;}
+@keyframes pulse{0%,100%{opacity:.3;}50%{opacity:.9;}}
+
+main{padding:26px; max-width:1180px; margin:0 auto;}
+.crumbs{display:flex; gap:8px; align-items:center; font-size:13px; margin-bottom:14px; color:var(--subtle);}
+.crumbs a{color:var(--muted);} .crumbs .sep{color:var(--border2);}
+
+.page-head{display:flex; align-items:flex-start; gap:16px; flex-wrap:wrap; margin-bottom:20px;}
+.page-head h1{margin:0; font-size:20px; letter-spacing:-.2px;}
+.page-head .id{font-family:var(--mono); font-size:13px; color:var(--muted); word-break:break-all;}
+.page-head .actions{margin-left:auto; display:flex; gap:8px;}
+
+.btn{display:inline-block; padding:6px 13px; border:1px solid var(--border2); border-radius:8px;
+  background:var(--panel2); color:var(--fg); font-size:13px; cursor:pointer;}
+.btn:hover{border-color:var(--accent); text-decoration:none; background:var(--raised);}
+.btn.primary{background:var(--accent-soft); border-color:var(--accent);}
+
+.stats{display:flex; gap:10px; flex-wrap:wrap; margin-bottom:18px;}
+.stat{background:var(--panel); border:1px solid var(--border); border-radius:var(--radius); padding:10px 16px; min-width:108px;}
+.stat .k{font-size:11px; text-transform:uppercase; letter-spacing:.6px; color:var(--subtle);}
+.stat .v{font-size:19px; font-weight:600; margin-top:2px; font-variant-numeric:tabular-nums;}
+
+.panel{background:var(--panel); border:1px solid var(--border); border-radius:var(--radius); margin-bottom:20px; overflow:hidden;}
+.panel > h2{margin:0; padding:13px 18px; font-size:13px; font-weight:500; letter-spacing:0;
+  color:var(--muted); border-bottom:1px solid var(--border); background:var(--bg2); display:flex; gap:10px; align-items:center;}
+.panel > h2 .count{color:var(--subtle); font-weight:400; letter-spacing:0;}
+.panel-body{padding:16px 18px;}
+.panel-scroll{overflow-x:auto;}
+
+.banner{margin:0 0 20px; padding:11px 15px; border-radius:var(--radius); font-size:13px;
+  background:rgba(253,214,99,.08); border:1px solid rgba(253,214,99,.32); color:var(--warn);}
+
+table{width:100%; border-collapse:collapse;}
+th,td{text-align:left; padding:10px 16px; border-bottom:1px solid var(--border);}
+tr:last-child td{border-bottom:0;}
+th{color:var(--subtle); font-weight:500; font-size:12px; letter-spacing:0;}
+tbody tr{transition:background .12s;} tbody tr:hover{background:var(--panel2);}
+td.num{font-variant-numeric:tabular-nums;}
+
+.badge{display:inline-block; padding:1px 9px; border-radius:20px; font-size:11.5px; font-weight:600; line-height:1.6;}
+.badge.ok{background:rgba(129,201,149,.14); color:var(--ok);}
+.badge.err,.badge.error{background:rgba(242,139,130,.14); color:var(--err);}
+.dot{display:inline-block; width:9px; height:9px; border-radius:50%; vertical-align:middle;}
+.dot.ok{background:var(--ok);} .dot.error{background:var(--err);}
+.dot.run{background:var(--accent);} .dot.node{background:var(--slate);}
+.dot.model{background:var(--blue);} .dot.tool{background:var(--violet);} .dot.other{background:var(--subtle);}
+
+/* span tree */
+.tree{display:flex; flex-direction:column;}
+.trow{display:flex; align-items:center; gap:12px; padding:7px 18px; border-bottom:1px solid var(--border);
+  color:var(--fg); font-size:13px;}
+.trow:last-child{border-bottom:0;}
+.trow:hover{background:var(--panel2); text-decoration:none;}
+.trow .nm{display:flex; align-items:center; gap:8px; min-width:240px; font-family:var(--mono);}
+.trow .nm .lbl{color:var(--subtle); font-family:var(--sans);}
+.trow .ex{margin-left:8px; color:var(--muted); font-family:var(--sans); font-size:12px; white-space:nowrap;}
+.trow .ex .exk{color:var(--subtle); margin-right:3px;}
+.trow .tbar{flex:1; height:8px; background:var(--bg2); border-radius:5px; position:relative; min-width:120px; overflow:hidden;}
+.trow .tbar i{position:absolute; top:0; bottom:0; border-radius:5px;}
+.trow .tdur{font-variant-numeric:tabular-nums; color:var(--muted); width:78px; text-align:right;}
+
+/* timeline */
+.timeline{display:block; width:100%; height:auto; font-family:var(--mono);}
+.timeline .tl-grid{stroke:var(--grid); stroke-width:1;}
+.timeline .tl-axis{fill:var(--subtle); font-size:10px;}
+.timeline .tl-label{fill:var(--muted); font-size:11px;}
+.timeline .tl-dur{fill:var(--subtle); font-size:10px;}
+.timeline a .tl-hit{fill:transparent;}
+.timeline a:hover .tl-hit{fill:rgba(122,162,255,.08);}
+.timeline a:hover .tl-label{fill:var(--fg);}
+.legend{display:flex; gap:16px; flex-wrap:wrap; padding:10px 18px 0; font-size:12px; color:var(--muted);}
+.legend span{display:inline-flex; align-items:center; gap:6px;}
+
+/* graph */
+.graph{display:block; width:100%; height:auto; font-family:var(--sans);}
+.graph .edge{fill:none; stroke:var(--edge); stroke-width:1.7;}
+.graph .edge.cond{stroke-dasharray:5 4; stroke:var(--slate);}
+.graph .arrow{fill:var(--edge);}
+.graph .edge-label{fill:var(--subtle); font-size:10px; text-anchor:middle;}
+.graph .gnode rect{fill:var(--raised); stroke:var(--node-stroke); stroke-width:1.5;}
+.graph .gnode:hover rect{stroke:var(--accent);}
+.graph .gnode.entry rect{stroke:var(--accent); fill:var(--accent-soft);}
+.graph .gnode.term rect{fill:var(--panel2); stroke:var(--slate);}
+.graph .gnode.interrupt rect{stroke:#d97706; fill:rgba(217,119,6,.16);}
+.graph .gnode.err rect{stroke:var(--err);}
+.graph .gnode-label{fill:var(--fg); font-size:12px; font-weight:600; text-anchor:middle;}
+.graph .gnode-sub{fill:var(--muted); font-size:10px; text-anchor:middle; font-family:var(--mono);}
+
+/* topology lists */
+.topo{display:flex; gap:34px; flex-wrap:wrap;}
+.topo h3{font-size:12px; text-transform:uppercase; letter-spacing:.5px; color:var(--subtle); margin:0 0 8px;}
+.topo ul{margin:0; padding-left:18px; font-family:var(--mono); font-size:13px;}
+.topo li{margin:3px 0;}
+
+/* meta grid */
+.meta{display:grid; grid-template-columns:repeat(auto-fill,minmax(220px,1fr)); gap:1px; background:var(--border); border-radius:var(--radius); overflow:hidden;}
+.meta .cell{background:var(--panel); padding:11px 16px;}
+.meta .k{font-size:11px; text-transform:uppercase; letter-spacing:.5px; color:var(--subtle);}
+.meta .v{margin-top:3px; font-family:var(--mono); font-size:13px; word-break:break-all;}
+
+/* messages */
+.msgs{display:grid; grid-template-columns:1fr 1fr; gap:16px;}
+@media(max-width:820px){.msgs{grid-template-columns:1fr;}}
+.msgcol h3{font-size:12px; text-transform:uppercase; letter-spacing:.5px; color:var(--subtle); margin:0 0 10px;}
+.msg{border:1px solid var(--border); border-radius:9px; margin-bottom:10px; overflow:hidden; background:var(--bg2);}
+.msg-role{font-size:11px; text-transform:uppercase; letter-spacing:.6px; padding:5px 12px; color:var(--muted); border-bottom:1px solid var(--border); background:var(--panel2);}
+.msg.user .msg-role{color:var(--accent);}
+.msg.assistant .msg-role{color:var(--ok);}
+.msg.system .msg-role{color:var(--warn);}
+.msg.tool .msg-role{color:var(--violet);}
+.msg-body{padding:10px 12px;}
+.msg-body pre{margin:0; white-space:pre-wrap; word-break:break-word; font-size:12.5px; line-height:1.5;}
+.msg-body pre.text{font-family:var(--sans);}
+.toolcall{font-family:var(--mono); font-size:12.5px; color:var(--violet); margin:5px 0; word-break:break-word;}
+.toolcall .tname{color:var(--fg);}
+.toolcall code{color:var(--muted);}
+details.reason{margin:6px 0; border-left:2px solid var(--border2); padding-left:10px;}
+details.reason summary{cursor:pointer; color:var(--subtle); font-size:12px;}
+details.reason pre{margin:6px 0 0; white-space:pre-wrap; font-size:12px; color:var(--muted);}
+
+/* steps */
+.step{border:1px solid var(--border); border-radius:var(--radius); margin-bottom:16px; overflow:hidden; background:var(--panel);}
+.step-head{display:flex; align-items:center; gap:12px; padding:11px 16px; background:var(--bg2); border-bottom:1px solid var(--border);}
+.step-head .n{width:26px; height:26px; border-radius:7px; background:var(--accent-soft); color:var(--accent); display:flex; align-items:center; justify-content:center; font-weight:700; font-size:13px;}
+.step-head .nm{font-weight:600;}
+.step-head .meta-inline{margin-left:auto; color:var(--muted); font-size:12px; font-variant-numeric:tabular-nums;}
+.step-body{padding:14px 16px;}
+.call{border:1px solid var(--border); border-radius:9px; padding:11px 13px; margin-bottom:12px; background:var(--bg2);}
+.call:last-child{margin-bottom:0;}
+.call-head{display:flex; gap:10px; align-items:baseline; flex-wrap:wrap; margin-bottom:8px; font-size:13px;}
+.call-head .kind{font-size:11px; text-transform:uppercase; letter-spacing:.5px; padding:1px 8px; border-radius:6px;}
+.call-head .kind.model{background:rgba(138,180,248,.14); color:var(--blue);}
+.call-head .kind.tool{background:rgba(197,138,249,.14); color:var(--violet);}
+.call-head .meta-inline{margin-left:auto; color:var(--subtle); font-size:12px; font-variant-numeric:tabular-nums;}
+.hint{font-size:12.5px; color:var(--subtle); font-style:italic;}
+
+.empty{padding:30px; text-align:center; color:var(--subtle);}
+`;
+/** Top navigation bar shared by every page. */
+function topbar(live) {
+    const liveDot = live
+        ? `<span class="live"><span class="pulse"></span> live</span>`
+        : "";
+    return `<div class="topbar">
+  <div class="brand"><span class="mark"><a href="/">galdor</a></span><span class="tag">trace explorer</span></div>
+  <span class="spacer"></span>${liveDot}
+  <button id="theme-toggle" class="icon-btn" type="button" aria-label="Toggle light or dark theme" title="Toggle light / dark"></button>
+</div>`;
+}
+/** Inline, render-blocking theme bootstrap: applies the saved/system theme before first paint (no flash). */
+const THEME_INIT = `<script>(function(){try{var s=localStorage.getItem('galdor-theme');var t=s||((window.matchMedia&&window.matchMedia('(prefers-color-scheme: light)').matches)?'light':'dark');document.documentElement.setAttribute('data-theme',t);}catch(e){document.documentElement.setAttribute('data-theme','dark');}})();</script>`;
+/** Wire the topbar toggle to flip and persist the theme. */
+const THEME_TOGGLE = `<script>(function(){var b=document.getElementById('theme-toggle');if(!b)return;function sync(){var t=document.documentElement.getAttribute('data-theme');b.textContent=t==='light'?'\\u263E':'\\u2600';}sync();b.addEventListener('click',function(){var next=document.documentElement.getAttribute('data-theme')==='light'?'dark':'light';document.documentElement.setAttribute('data-theme',next);try{localStorage.setItem('galdor-theme',next);}catch(e){}sync();});})();</script>`;
+function shell(title, body, opts = {}) {
+    return `<!doctype html><html lang="en"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1">
+${THEME_INIT}<title>${esc(title)} · galdor</title><style>${STYLE}</style></head>
+<body>${topbar(opts.live ?? false)}<main>${body}</main>${THEME_TOGGLE}</body></html>`;
+}
+// ── run list page ────────────────────────────────────────────────────────────────
+function runListPage(store, limit = 100) {
+    const runs = runListJSON(store, limit);
+    const orphans = store.orphanSpanCount();
+    const banner = orphans > 0
+        ? `<div class="banner">⚠ ${orphans} span(s) carry no run id and won't appear below — instrument through @galdor/core/observability so every span lands in a run.</div>`
+        : "";
+    const rowsHtml = runs.length === 0
+        ? `<tr><td colspan="5" class="empty">No runs recorded yet. Run a traced graph and they'll appear here.</td></tr>`
+        : runs.map(runRow).join("");
+    // Live-tail: re-render the tbody as new runs arrive over SSE.
+    const script = `<script>
+function row(r){
+  var t=new Date(r.startMs).toLocaleTimeString();
+  var dur=r.durationMs>=1000?(r.durationMs/1000).toFixed(2)+' s':r.durationMs+' ms';
+  return '<tr><td><span class="dot '+r.status+'"></span> <a href="/runs/'+encodeURIComponent(r.runId)+'">'+
+    (r.runId||'(no id)')+'</a></td><td><span class="badge '+r.status+'">'+r.status+'</span></td>'+
+    '<td class="num">'+r.spanCount+'</td><td class="num">'+dur+'</td><td class="muted">'+t+'</td></tr>';
+}
+var es=new EventSource('/events');
+es.addEventListener('run',function(e){
+  var r=JSON.parse(e.data); var tb=document.querySelector('tbody');
+  var existing=document.getElementById('run-'+r.runId);
+  var tmp=document.createElement('tbody'); tmp.innerHTML=row(r);
+  var tr=tmp.firstElementChild; tr.id='run-'+r.runId;
+  if(existing) existing.replaceWith(tr); else tb.insertBefore(tr, tb.firstChild);
+});
+</script>`;
+    const body = `${banner}
+<div class="page-head"><h1>Runs</h1></div>
+<div class="panel panel-scroll">
+  <table><thead><tr><th>run</th><th>status</th><th>spans</th><th>duration</th><th>started</th></tr></thead>
+  <tbody>${rowsHtml}</tbody></table>
+</div>${script}`;
+    return shell("runs", body, { live: true });
+}
+function runRow(r) {
+    const dur = r.durationMs >= 1000 ? `${(r.durationMs / 1000).toFixed(2)} s` : `${r.durationMs} ms`;
+    const time = new Date(r.startMs).toLocaleTimeString();
+    return `<tr>
+  <td><span class="dot ${r.status}"></span> <a href="/runs/${enc(r.runId)}">${esc(r.runId || "(no id)")}</a></td>
+  <td><span class="badge ${r.status}">${r.status}</span></td>
+  <td class="num">${r.spanCount}</td>
+  <td class="num">${dur}</td>
+  <td class="muted">${esc(time)}</td>
+</tr>`;
+}
+// ── run detail page ──────────────────────────────────────────────────────────────
+function runDetailPage(store, runId) {
+    const spans = store.spansForRun(runId);
+    if (spans.length === 0) {
+        return shell(runId, `${crumbs([["/", "runs"], [null, shortId(runId)]])}<div class="panel"><div class="empty">No spans recorded for <code>${esc(runId)}</code>.</div></div>`);
+    }
+    const ordered = orderSpans(spans);
+    const { t0, t1 } = runBounds(spans);
+    const total = t1 > t0 ? t1 - t0 : 1n;
+    const errors = spans.filter((s) => s.statusCode === "error").length;
+    const status = errors > 0 ? "error" : "ok";
+    const spec = graphSpec(store, runId);
+    const tok = tokenTotals(spans);
+    const tokStat = tok.input + tok.output > 0
+        ? `<div class="stat"><div class="k">tokens</div><div class="v">${tok.input + tok.output}<span class="subtle" style="font-size:12px"> · ${tok.input}↑ ${tok.output}↓</span></div></div>`
+        : "";
+    const head = `<div class="page-head">
+  <div><h1>Run</h1><div class="id">${esc(runId)}</div></div>
+  <div class="actions"><a class="btn primary" href="/runs/${enc(runId)}/steps">Steps view →</a></div>
+</div>
+<div class="stats">
+  <div class="stat"><div class="k">status</div><div class="v"><span class="badge ${status}">${status}</span></div></div>
+  <div class="stat"><div class="k">duration</div><div class="v">${fmtDur(total)}</div></div>
+  <div class="stat"><div class="k">spans</div><div class="v">${spans.length}</div></div>
+  <div class="stat"><div class="k">errors</div><div class="v">${errors}</div></div>
+  ${tokStat}
+  <div class="stat"><div class="k">started</div><div class="v" style="font-size:13px">${esc(new Date(nanosToMs(t0)).toLocaleString())}</div></div>
+</div>`;
+    const timeline = `<div class="panel">
+  <h2>timeline <span class="count">${ordered.length} spans</span></h2>
+  ${timelineLegend()}
+  <div class="panel-body panel-scroll">${timelineSVG(runId, ordered, t0, total)}</div>
+</div>`;
+    const tree = `<div class="panel">
+  <h2>span tree</h2>
+  <div class="tree">${ordered.map((o) => treeRow(runId, o, t0, total)).join("")}</div>
+</div>`;
+    const graph = spec ? graphPanel(runId, spec, spans) : "";
+    return shell(runId, `${crumbs([["/", "runs"], [null, shortId(runId)]])}${head}${timeline}${graph}${tree}`);
+}
+function timelineLegend() {
+    const item = (k, label) => `<span><span class="dot ${k}"></span>${label}</span>`;
+    return `<div class="legend">${item("run", "run")}${item("node", "node")}${item("model", "model call")}${item("tool", "tool")}<span><span class="dot error"></span>error</span></div>`;
+}
+/** Render the run's spans as a clickable SVG waterfall. */
+function timelineSVG(runId, ordered, t0, total) {
+    const labelW = 250;
+    const barW = 760;
+    const padTop = 26;
+    const rowH = 26;
+    const W = labelW + barW + 70;
+    const H = padTop + ordered.length * rowH + 8;
+    const totalNum = Number(total);
+    const xOf = (ns) => labelW + (Number(ns - t0) * barW) / totalNum;
+    // Time axis: 6 evenly-spaced gridlines with relative-ms labels.
+    let axis = "";
+    for (let i = 0; i <= 5; i++) {
+        const frac = i / 5;
+        const x = labelW + frac * barW;
+        const ms = (totalNum * frac) / 1e6;
+        const lbl = ms >= 1000 ? `${(ms / 1000).toFixed(1)}s` : `${ms.toFixed(ms < 10 ? 1 : 0)}ms`;
+        axis += `<line class="tl-grid" x1="${x.toFixed(1)}" y1="${padTop}" x2="${x.toFixed(1)}" y2="${H - 6}"/>`;
+        axis += `<text class="tl-axis" x="${x.toFixed(1)}" y="${padTop - 8}" text-anchor="${i === 5 ? "end" : "middle"}">${lbl}</text>`;
+    }
+    let rows = "";
+    ordered.forEach(({ span, depth }, i) => {
+        const y = padTop + i * rowH;
+        const cy = y + rowH / 2;
+        const dur = spanDuration(span);
+        let x = xOf(span.startTimeUnixNano);
+        let w = (Number(dur) * barW) / totalNum;
+        if (w < 3)
+            w = 3;
+        if (x + w > labelW + barW)
+            x = labelW + barW - w;
+        const kind = kindOf(span.name);
+        const fill = span.statusCode === "error" ? "var(--err)" : KIND_FILL[kind];
+        const lx = 10 + depth * 11;
+        const label = esc(truncate(shortName(span.name), 30 - depth * 2));
+        rows += `<a href="/runs/${enc(runId)}/spans/${enc(span.spanId)}">
+  <rect class="tl-hit" x="0" y="${y}" width="${W}" height="${rowH}"/>
+  <text class="tl-label" x="${lx}" y="${cy + 4}">${label}</text>
+  <rect x="${x.toFixed(1)}" y="${y + (rowH - 12) / 2}" width="${w.toFixed(1)}" height="12" rx="3" fill="${fill}"><title>${esc(span.name)} — ${fmtDur(dur)}</title></rect>
+  <text class="tl-dur" x="${(x + w + 6).toFixed(1)}" y="${cy + 4}">${fmtDur(dur)}</text>
+</a>`;
+    });
+    return `<svg class="timeline" viewBox="0 0 ${W} ${H}" width="${W}" preserveAspectRatio="xMinYMin meet" role="img">${axis}${rows}</svg>`;
+}
+function truncate(s, n) {
+    return s.length > n ? `${s.slice(0, n - 1)}…` : s;
+}
+/** One row of the textual span tree, with a proportional latency bar. */
+function treeRow(runId, { span, depth }, t0, total) {
+    const dur = spanDuration(span);
+    const kind = kindOf(span.name);
+    const fill = span.statusCode === "error" ? "var(--err)" : KIND_FILL[kind];
+    const totalNum = Number(total);
+    const left = (Number(span.startTimeUnixNano - t0) * 100) / totalNum;
+    const width = Math.max(1.5, (Number(dur) * 100) / totalNum);
+    const err = span.statusCode === "error" ? `<span class="badge err">error</span>` : "";
+    return `<a class="trow" href="/runs/${enc(runId)}/spans/${enc(span.spanId)}">
+  <span class="nm" style="padding-left:${depth * 16}px"><span class="dot ${kind}"></span>${esc(shortName(span.name))}${spanExtras(span.attributes)}</span>
+  <span class="tbar"><i style="left:${left.toFixed(2)}%;width:${width.toFixed(2)}%;background:${fill}"></i></span>
+  <span class="tdur">${fmtDur(dur)}</span>${err}
+</a>`;
+}
+/** Inline key/value chips (label, node, provider, model, tokens) shown beside a span. */
+function spanExtras(a) {
+    const bits = [];
+    const push = (k, v) => {
+        if (v)
+            bits.push(`<span class="ex"><span class="exk">${k}</span>${esc(v)}</span>`);
+    };
+    push("label", attrStr(a, A.label));
+    push("node", attrStr(a, A.node));
+    push("provider", attrStr(a, A.provider) ?? attrStr(a, A.system));
+    push("model", attrStr(a, A.reqModel));
+    push("tool", attrStr(a, A.toolName));
+    const inT = attrNum(a, A.inTokens);
+    const outT = attrNum(a, A.outTokens);
+    if (inT && inT > 0)
+        push("in", String(inT));
+    if (outT && outT > 0)
+        push("out", String(outT));
+    return bits.join("");
+}
+/** Sum input/output token usage across a run's provider spans. */
+function tokenTotals(spans) {
+    let input = 0;
+    let output = 0;
+    for (const s of spans) {
+        input += attrNum(s.attributes, A.inTokens) ?? 0;
+        output += attrNum(s.attributes, A.outTokens) ?? 0;
+    }
+    return { input, output };
+}
+/** Aggregate recorded duration/status for the spans belonging to a graph node. */
+function nodeStat(spans, nodeName) {
+    let dur = 0n;
+    let status = "ok";
+    let found = false;
+    for (const s of spans) {
+        if (s.name === SPAN.node && s.attributes[A.node] === nodeName) {
+            found = true;
+            dur += spanDuration(s);
+            if (s.statusCode === "error")
+                status = "error";
+        }
+    }
+    return found ? { dur, status } : undefined;
+}
+function graphPanel(runId, spec, spans) {
+    const api = `<span class="count" style="margin-left:auto;font-size:12px">
+    API:
+    <a href="/api/runs/${enc(runId)}/graph/model">JSON</a> ·
+    <a href="/api/runs/${enc(runId)}/graph/svg">SVG</a> ·
+    <a href="/api/runs/${enc(runId)}/graph">spec</a></span>`;
+    return `<div class="panel">
+  <h2>graph topology${api}</h2>
+  <div class="panel-body panel-scroll">${graphSVG(runId, spec, spans)}</div>
+  <div class="panel-body" style="border-top:1px solid var(--border)">${topologyLists(spec)}</div>
+</div>`;
+}
+/** Collect the full node set, flattened edge list, and interrupt-gated node names of a spec. */
+function collectGraph(spec) {
+    const interrupt = new Set();
+    const nodeSet = new Set();
+    for (const n of spec.nodes) {
+        nodeSet.add(n.name);
+        if (n.interrupt)
+            interrupt.add(n.name);
+    }
+    const edges = [];
+    for (const e of spec.edges) {
+        nodeSet.add(e.from);
+        nodeSet.add(e.to);
+        edges.push({ from: e.from, to: e.to, cond: false, label: "" });
+    }
+    for (const c of spec.conditional) {
+        nodeSet.add(c.from);
+        if (c.labels) {
+            for (const [label, to] of Object.entries(c.labels)) {
+                nodeSet.add(to);
+                edges.push({ from: c.from, to, cond: true, label });
+            }
+        }
+    }
+    return { nodes: [...nodeSet], edges, interrupt };
+}
+/**
+ * The graph as the dashboard models it: the recorded topology enriched with each
+ * node's measured duration and status. This is the same data the SVG is drawn
+ * from, exposed as plain JSON so it can be rendered or analysed elsewhere.
+ */
+function graphModel(spec, spans) {
+    const { nodes, edges, interrupt } = collectGraph(spec);
+    return {
+        entry: spec.entry,
+        nodes: nodes.map((n) => {
+            const stat = nodeStat(spans, n);
+            return {
+                name: n,
+                role: n === START ? "start" : n === END ? "end" : "node",
+                entry: n === spec.entry,
+                interrupt: interrupt.has(n),
+                durationMs: stat ? Number(stat.dur) / 1e6 : null,
+                status: stat ? stat.status : null,
+            };
+        }),
+        edges: edges.map((e) => ({ from: e.from, to: e.to, conditional: e.cond, label: e.cond ? e.label : null })),
+    };
+}
+/** Render the recorded graph as a layered SVG with per-node run metrics. */
+function graphSVG(runId, spec, spans, opts = {}) {
+    const { nodes, edges, interrupt } = collectGraph(spec);
+    // Longest-path layering (start sinks at layer 0). Iteration count bounds cycles.
+    const layer = new Map(nodes.map((n) => [n, 0]));
+    for (let iter = 0; iter < nodes.length; iter++) {
+        let changed = false;
+        for (const e of edges) {
+            const lu = layer.get(e.from) ?? 0;
+            if ((layer.get(e.to) ?? 0) < lu + 1) {
+                layer.set(e.to, lu + 1);
+                changed = true;
+            }
+        }
+        if (!changed)
+            break;
+    }
+    const NODE_H = 42;
+    const V_GAP = 100;
+    const PAD = 24;
+    const widthOf = (n) => Math.max(96, nodeLabel(n).length * 8 + 30);
+    const layers = [];
+    for (const n of nodes) {
+        const L = layer.get(n) ?? 0;
+        (layers[L] ??= []).push(n);
+    }
+    const maxPer = Math.max(1, ...layers.map((a) => a?.length ?? 0));
+    const maxNodeW = Math.max(96, ...nodes.map(widthOf));
+    const CW = Math.max(720, maxPer * (maxNodeW + 56));
+    const CH = PAD * 2 + Math.max(0, layers.length - 1) * V_GAP + NODE_H;
+    const pos = new Map();
+    layers.forEach((arr, L) => {
+        if (!arr)
+            return;
+        const m = arr.length;
+        arr.forEach((n, i) => {
+            pos.set(n, { cx: (CW * (i + 0.5)) / m, cy: PAD + NODE_H / 2 + L * V_GAP, w: widthOf(n) });
+        });
+    });
+    let edgeSvg = "";
+    for (const e of edges) {
+        const a = pos.get(e.from);
+        const b = pos.get(e.to);
+        if (!a || !b)
+            continue;
+        const x1 = a.cx;
+        const y1 = a.cy + NODE_H / 2;
+        const x2 = b.cx;
+        const y2 = b.cy - NODE_H / 2;
+        const my = (y1 + y2) / 2;
+        const d = `M${x1.toFixed(1)},${y1.toFixed(1)} C${x1.toFixed(1)},${my.toFixed(1)} ${x2.toFixed(1)},${my.toFixed(1)} ${x2.toFixed(1)},${y2.toFixed(1)}`;
+        edgeSvg += `<path class="edge${e.cond ? " cond" : ""}" d="${d}" marker-end="url(#gv-arrow)"/>`;
+        if (e.cond && e.label) {
+            edgeSvg += `<text class="edge-label" x="${((x1 + x2) / 2).toFixed(1)}" y="${my.toFixed(1)}">${esc(e.label)}</text>`;
+        }
+    }
+    let nodeSvg = "";
+    for (const n of nodes) {
+        const p = pos.get(n);
+        if (!p)
+            continue;
+        const term = n === START || n === END;
+        const entry = n === spec.entry;
+        const stat = nodeStat(spans, n);
+        const cls = ["gnode"];
+        if (term)
+            cls.push("term");
+        if (entry)
+            cls.push("entry");
+        if (interrupt.has(n))
+            cls.push("interrupt");
+        if (stat?.status === "error")
+            cls.push("err");
+        const x = p.cx - p.w / 2;
+        const y = p.cy - NODE_H / 2;
+        const sub = stat ? fmtDur(stat.dur) : "";
+        const tip = stat ? `${n} — ${fmtDur(stat.dur)} (${stat.status})` : n;
+        // Link nodes to their step in-page; standalone SVGs carry no page links.
+        const linkable = !opts.standalone && !!stat;
+        const open = linkable
+            ? `<a href="/runs/${enc(runId)}/steps#step-${enc(n)}" class="${cls.join(" ")}">`
+            : `<g class="${cls.join(" ")}">`;
+        const close = linkable ? "</a>" : "</g>";
+        const labelY = sub ? p.cy - 2 : p.cy + 4;
+        nodeSvg += `${open}
+  <rect x="${x.toFixed(1)}" y="${y.toFixed(1)}" width="${p.w}" height="${NODE_H}" rx="10"/>
+  <text class="gnode-label" x="${p.cx.toFixed(1)}" y="${labelY.toFixed(1)}">${esc(nodeLabel(n))}</text>
+  ${sub ? `<text class="gnode-sub" x="${p.cx.toFixed(1)}" y="${(p.cy + 14).toFixed(1)}">${esc(sub)}</text>` : ""}
+  <title>${esc(tip)}</title>
+${close}`;
+    }
+    const defs = `<defs><marker id="gv-arrow" markerWidth="9" markerHeight="9" refX="7.5" refY="3" orient="auto" markerUnits="userSpaceOnUse"><path class="arrow" d="M0,0 L7,3 L0,6 z"/></marker></defs>`;
+    const style = opts.standalone ? graphStyleBlock(opts.theme ?? "light") : "";
+    const ns = opts.standalone ? ` xmlns="http://www.w3.org/2000/svg"` : "";
+    return `<svg class="graph"${ns} viewBox="0 0 ${CW.toFixed(0)} ${CH.toFixed(0)}" width="${CW.toFixed(0)}" preserveAspectRatio="xMinYMin meet" role="img">${style}${defs}${edgeSvg}${nodeSvg}</svg>`;
+}
+/** Embedded stylesheet for a standalone graph SVG (concrete colours, no CSS variables). */
+function graphStyleBlock(theme) {
+    const c = theme === "light"
+        ? { edge: "#80868b", cond: "#5f6368", nodeFill: "#ffffff", nodeStroke: "#9aa0a6", termFill: "#f1f3f4", entryStroke: "#0b57d0", entryFill: "#e8f0fe", err: "#c5221f", label: "#1f1f1f", sub: "#5f6368", elabel: "#6f7378" }
+        : { edge: "#5b636f", cond: "#9aa0a6", nodeFill: "#2d2f31", nodeStroke: "#454a52", termFill: "#28292b", entryStroke: "#8ab4f8", entryFill: "rgba(138,180,248,.14)", err: "#f28b82", label: "#e3e3e3", sub: "#9aa0a6", elabel: "#9aa0a6" };
+    return `<style>
+.graph{font-family:system-ui,-apple-system,"Segoe UI",Roboto,Arial,sans-serif;}
+.graph .edge{fill:none;stroke:${c.edge};stroke-width:1.7;}
+.graph .edge.cond{stroke-dasharray:5 4;stroke:${c.cond};}
+.graph .arrow{fill:${c.edge};}
+.graph .edge-label{fill:${c.elabel};font-size:10px;text-anchor:middle;}
+.graph .gnode rect{fill:${c.nodeFill};stroke:${c.nodeStroke};stroke-width:1.5;}
+.graph .gnode.term rect{fill:${c.termFill};stroke:${c.cond};}
+.graph .gnode.entry rect{stroke:${c.entryStroke};fill:${c.entryFill};}
+.graph .gnode.interrupt rect{stroke:#d97706;fill:${theme === "light" ? "#fef3c7" : "rgba(217,119,6,.16)"};}
+.graph .gnode.err rect{stroke:${c.err};}
+.graph .gnode-label{fill:${c.label};font-size:12px;font-weight:600;text-anchor:middle;}
+.graph .gnode-sub{fill:${c.sub};font-size:10px;text-anchor:middle;font-family:ui-monospace,Menlo,monospace;}
+</style>`;
+}
+/** Textual node/edge listing beneath the graph SVG. */
+function topologyLists(spec) {
+    const nodes = spec.nodes.length === 0
+        ? `<li class="muted">(none)</li>`
+        : spec.nodes
+            .map((n) => {
+            const tags = [
+                n.name === spec.entry ? ` <span class="subtle">(entry)</span>` : "",
+                n.interrupt ? ` <span class="subtle">(interrupt)</span>` : "",
+            ].join("");
+            return `<li>${esc(n.name)}${tags}</li>`;
+        })
+            .join("");
+    const staticEdges = spec.edges.map((e) => `<li>${esc(nodeLabel(e.from))} → ${esc(nodeLabel(e.to))}</li>`).join("");
+    const condEdges = spec.conditional
+        .map((c) => {
+        if (!c.labels)
+            return `<li>${esc(nodeLabel(c.from))} → <span class="subtle">(router)</span></li>`;
+        const labels = Object.entries(c.labels).map(([l, to]) => `${esc(l)}:${esc(nodeLabel(to))}`).join(", ");
+        return `<li>${esc(nodeLabel(c.from))} → <span class="subtle">{${labels}}</span></li>`;
+    })
+        .join("");
+    const edges = staticEdges + condEdges || `<li class="muted">(none)</li>`;
+    return `<div class="topo">
+  <div><h3>nodes</h3><ul>${nodes}</ul></div>
+  <div><h3>edges</h3><ul>${edges}</ul></div>
+</div>`;
+}
+// ── span detail page ─────────────────────────────────────────────────────────────
+function spanDetailPage(store, runId, spanId) {
+    const span = findSpan(store, runId, spanId);
+    if (!span) {
+        return shell("span", `${crumbs([["/", "runs"], [`/runs/${enc(runId)}`, shortId(runId)], [null, "span"]])}<div class="panel"><div class="empty">Span not found.</div></div>`);
+    }
+    const dur = spanDuration(span);
+    const kind = kindOf(span.name);
+    const status = span.statusCode === "error" ? "error" : span.statusCode === "ok" ? "ok" : "unset";
+    const head = `<div class="page-head">
+  <div><h1><span class="dot ${kind}"></span> ${esc(shortName(span.name))}</h1><div class="id">${esc(span.spanId)}</div></div>
+</div>`;
+    const cell = (k, v) => `<div class="cell"><div class="k">${k}</div><div class="v">${v}</div></div>`;
+    const parentLink = span.parentSpanId
+        ? `<a href="/runs/${enc(runId)}/spans/${enc(span.parentSpanId)}">${esc(shortId(span.parentSpanId))}</a>`
+        : `<span class="subtle">(root)</span>`;
+    const meta = `<div class="meta">
+  ${cell("status", status === "unset" ? `<span class="subtle">unset</span>` : `<span class="badge ${status}">${status}</span>`)}
+  ${cell("duration", fmtDur(dur))}
+  ${cell("started", esc(new Date(nanosToMs(span.startTimeUnixNano)).toLocaleString()))}
+  ${cell("parent", parentLink)}
+  ${cell("trace", esc(shortId(span.traceId)))}
+  ${span.statusMessage ? cell("message", esc(span.statusMessage)) : ""}
+</div>`;
+    const modelPanel = modelCallPanel(span);
+    const messages = messagesPanel(span);
+    const toolPanel = toolIOPanel(span);
+    const attrs = attributesPanel(span);
+    const events = eventsPanel(span);
+    return shell(span.name, `${crumbs([["/", "runs"], [`/runs/${enc(runId)}`, shortId(runId)], [null, "span"]])}${head}
+<div class="panel"><div class="panel-body">${meta}</div></div>${modelPanel}${messages}${toolPanel}${attrs}${events}`);
+}
+/** Provider/model/token summary for a provider span (empty for other spans). */
+function modelCallPanel(span) {
+    const a = span.attributes;
+    const provider = attrStr(a, A.provider) ?? attrStr(a, A.system);
+    const reqModel = attrStr(a, A.reqModel);
+    const respModel = attrStr(a, A.respModel);
+    if (!provider && !reqModel && !respModel)
+        return "";
+    const inT = attrNum(a, A.inTokens);
+    const outT = attrNum(a, A.outTokens);
+    const finish = attrStr(a, A.finish);
+    const streaming = a[A.streaming];
+    const cell = (k, v) => v !== undefined && v !== "" ? `<div class="cell"><div class="k">${k}</div><div class="v">${v}</div></div>` : "";
+    const total = inT !== undefined || outT !== undefined ? String((inT ?? 0) + (outT ?? 0)) : undefined;
+    return `<div class="panel"><h2>model call</h2><div class="panel-body"><div class="meta">
+  ${cell("provider", provider ? esc(provider) : undefined)}
+  ${cell("request model", reqModel ? esc(reqModel) : undefined)}
+  ${cell("response model", respModel ? esc(respModel) : undefined)}
+  ${cell("input tokens", inT !== undefined ? String(inT) : undefined)}
+  ${cell("output tokens", outT !== undefined ? String(outT) : undefined)}
+  ${cell("total tokens", total)}
+  ${cell("finish reason", finish ? esc(finish) : undefined)}
+  ${cell("streaming", typeof streaming === "boolean" ? String(streaming) : undefined)}
+</div></div></div>`;
+}
+/** Parse `gen_ai.prompt` / `gen_ai.completion` into message arrays. */
+function parseMessages(raw) {
+    if (!raw)
+        return [];
+    try {
+        const v = JSON.parse(raw);
+        return Array.isArray(v) ? v : [v];
+    }
+    catch {
+        return [];
+    }
+}
+/** Render a single captured message (text, reasoning, tool calls). */
+function renderMessage(m) {
+    const role = String(m.role ?? "?");
+    let body = "";
+    for (const p of m.content ?? []) {
+        if (p.type === "text" && p.text)
+            body += `<pre class="text">${esc(p.text)}</pre>`;
+        else if ((p.type === "thinking" || p.type === "redacted_thinking") && p.text)
+            body += `<details class="reason"><summary>reasoning</summary><pre>${esc(p.text)}</pre></details>`;
+        else if (p.type === "image")
+            body += `<div class="muted">[image]</div>`;
+    }
+    // Tool calls may arrive as `toolCalls` or the snake_case `tool_calls`.
+    const toolCalls = m.toolCalls ?? m.tool_calls ?? [];
+    for (const tc of toolCalls) {
+        let args = "";
+        try {
+            args = JSON.stringify(tc.arguments);
+        }
+        catch {
+            args = String(tc.arguments);
+        }
+        body += `<div class="toolcall">→ <span class="tname">${esc(tc.name)}</span>(<code>${esc(truncate(args, 400))}</code>)</div>`;
+    }
+    if (!body)
+        body = `<div class="muted">(empty)</div>`;
+    return `<div class="msg ${esc(role)}"><div class="msg-role">${esc(role)}</div><div class="msg-body">${body}</div></div>`;
+}
+/** Side-by-side prompt/completion panel when content was captured. */
+function messagesPanel(span) {
+    const prompt = parseMessages(attrStr(span.attributes, A.prompt));
+    const completion = parseMessages(attrStr(span.attributes, A.completion));
+    const reasoning = parseReasoning(attrStr(span.attributes, A.reasoning));
+    if (prompt.length === 0 && completion.length === 0 && reasoning.length === 0)
+        return "";
+    const left = prompt.length
+        ? prompt.map(renderMessage).join("")
+        : `<div class="muted">(no prompt captured)</div>`;
+    let right = completion.length ? completion.map(renderMessage).join("") : "";
+    if (reasoning.length) {
+        right += `<details class="reason" open><summary>reasoning (${reasoning.length})</summary>${reasoning.map((r) => `<pre>${esc(r)}</pre>`).join("")}</details>`;
+    }
+    if (!right)
+        right = `<div class="muted">(no completion captured)</div>`;
+    return `<div class="panel">
+  <h2>messages</h2>
+  <div class="panel-body"><div class="msgs">
+    <div class="msgcol"><h3>prompt → API</h3>${left}</div>
+    <div class="msgcol"><h3>completion ← API</h3>${right}</div>
+  </div></div>
+</div>`;
+}
+function parseReasoning(raw) {
+    if (!raw)
+        return [];
+    try {
+        const v = JSON.parse(raw);
+        return Array.isArray(v) ? v.map(String) : [String(v)];
+    }
+    catch {
+        return [raw];
+    }
+}
+/** Tool-call summary (name + input/output sizes) for tool spans. */
+function toolIOPanel(span) {
+    const name = attrStr(span.attributes, A.toolName);
+    if (!name)
+        return "";
+    const inB = attrNum(span.attributes, A.toolIn);
+    const outB = attrNum(span.attributes, A.toolOut);
+    return `<div class="panel">
+  <h2>tool call</h2>
+  <div class="panel-body"><div class="meta">
+    <div class="cell"><div class="k">tool</div><div class="v">${esc(name)}</div></div>
+    <div class="cell"><div class="k">input size</div><div class="v">${inB ?? "—"} bytes</div></div>
+    <div class="cell"><div class="k">output size</div><div class="v">${outB ?? "—"} bytes</div></div>
+  </div></div>
+</div>`;
+}
+/** Full attribute table (content attributes are shown in their own panels). */
+function attributesPanel(span) {
+    const hidden = new Set([A.prompt, A.completion, A.reasoning]);
+    const entries = Object.entries(span.attributes).filter(([k]) => !hidden.has(k)).sort(([a], [b]) => a.localeCompare(b));
+    if (entries.length === 0)
+        return "";
+    const rows = entries
+        .map(([k, v]) => `<tr><td class="mono">${esc(k)}</td><td class="mono">${esc(truncate(fmtVal(v), 600))}</td></tr>`)
+        .join("");
+    return `<div class="panel panel-scroll">
+  <h2>attributes <span class="count">${entries.length}</span></h2>
+  <table><tbody>${rows}</tbody></table>
+</div>`;
+}
+function eventsPanel(span) {
+    if (span.events.length === 0)
+        return "";
+    const rows = span.events
+        .map((e) => `<tr><td class="mono">${esc(e.name)}</td><td class="muted">${esc(new Date(nanosToMs(e.timeUnixNano)).toISOString())}</td></tr>`)
+        .join("");
+    return `<div class="panel panel-scroll"><h2>events <span class="count">${span.events.length}</span></h2><table><tbody>${rows}</tbody></table></div>`;
+}
+// ── steps page ───────────────────────────────────────────────────────────────────
+function stepsPage(store, runId) {
+    const spans = store.spansForRun(runId);
+    if (spans.length === 0) {
+        return shell(runId, `${crumbs([["/", "runs"], [`/runs/${enc(runId)}`, shortId(runId)], [null, "steps"]])}<div class="panel"><div class="empty">No spans for this run.</div></div>`);
+    }
+    const byParent = new Map();
+    for (const s of spans) {
+        const arr = byParent.get(s.parentSpanId) ?? [];
+        arr.push(s);
+        byParent.set(s.parentSpanId, arr);
+    }
+    const cmp = (a, b) => a.startTimeUnixNano < b.startTimeUnixNano ? -1 : a.startTimeUnixNano > b.startTimeUnixNano ? 1 : 0;
+    const nodeSpans = spans.filter((s) => s.name === SPAN.node).sort(cmp);
+    const anyCaptured = spans.some((s) => s.name === SPAN.generate || s.name === SPAN.stream
+        ? attrStr(s.attributes, A.prompt) !== undefined
+        : false);
+    const replayHint = anyCaptured
+        ? ""
+        : `<div class="banner">No prompts/completions were captured for this run. Re-run with content capture enabled — <code>instrumentProvider(provider, tracer, { captureContent: true })</code> — to see what is sent to and received from the API here.</div>`;
+    const head = `<div class="page-head">
+  <div><h1>Steps</h1><div class="id">${esc(runId)}</div></div>
+  <div class="actions"><a class="btn" href="/runs/${enc(runId)}">← run detail</a></div>
+</div>`;
+    let cards = "";
+    if (nodeSpans.length === 0) {
+        // No graph-node spans: fall back to listing model/tool calls flatly.
+        const calls = spans.filter((s) => s.name !== SPAN.run).sort(cmp);
+        cards = `<div class="step"><div class="step-body">${calls.map((s) => callCard(runId, s)).join("") || `<div class="empty">No calls recorded.</div>`}</div></div>`;
+    }
+    else {
+        cards = nodeSpans
+            .map((node, i) => {
+            const nodeName = attrStr(node.attributes, A.node) ?? attrStr(node.attributes, A.label) ?? `step ${i + 1}`;
+            const children = (byParent.get(node.spanId) ?? []).sort(cmp);
+            const status = node.statusCode === "error" ? "error" : "ok";
+            const inner = children.length
+                ? children.map((c) => callCard(runId, c)).join("")
+                : `<div class="hint">No provider or tool calls in this step.</div>`;
+            return `<div class="step" id="step-${esc(nodeName)}">
+  <div class="step-head"><span class="n">${i + 1}</span><span class="nm">${esc(nodeName)}</span>
+    <span class="badge ${status}">${status}</span>
+    <span class="meta-inline">${fmtDur(spanDuration(node))}</span></div>
+  <div class="step-body">${inner}</div>
+</div>`;
+        })
+            .join("");
+    }
+    return shell(runId, `${crumbs([["/", "runs"], [`/runs/${enc(runId)}`, shortId(runId)], [null, "steps"]])}${replayHint}${head}${cards}`);
+}
+/** Render a provider or tool call inside a step card. */
+function callCard(runId, span) {
+    const link = `/runs/${enc(runId)}/spans/${enc(span.spanId)}`;
+    if (span.name === SPAN.generate || span.name === SPAN.stream) {
+        const model = attrStr(span.attributes, A.respModel) ?? attrStr(span.attributes, A.reqModel) ?? "model";
+        const provider = attrStr(span.attributes, A.provider) ?? attrStr(span.attributes, A.system);
+        const finish = attrStr(span.attributes, A.finish);
+        const inTok = attrNum(span.attributes, A.inTokens);
+        const outTok = attrNum(span.attributes, A.outTokens);
+        const tokens = inTok !== undefined || outTok !== undefined ? ` · in ${inTok ?? "?"} / out ${outTok ?? "?"} tok` : "";
+        const tail = `${tokens}${finish ? ` · ${esc(finish)}` : ""}`;
+        const provLabel = provider ? `<span class="subtle">${esc(provider)}</span> ` : "";
+        const prompt = parseMessages(attrStr(span.attributes, A.prompt));
+        const completion = parseMessages(attrStr(span.attributes, A.completion));
+        const reasoning = parseReasoning(attrStr(span.attributes, A.reasoning));
+        let content = "";
+        if (prompt.length || completion.length || reasoning.length) {
+            const left = prompt.length ? prompt.map(renderMessage).join("") : `<div class="muted">(no prompt)</div>`;
+            let right = completion.map(renderMessage).join("");
+            if (reasoning.length)
+                right += `<details class="reason"><summary>reasoning</summary>${reasoning.map((r) => `<pre>${esc(r)}</pre>`).join("")}</details>`;
+            if (!right)
+                right = `<div class="muted">(no completion)</div>`;
+            content = `<div class="msgs"><div class="msgcol"><h3>prompt → API</h3>${left}</div><div class="msgcol"><h3>completion ← API</h3>${right}</div></div>`;
+        }
+        else {
+            content = `<div class="hint">No captured content. <a href="${link}">span details →</a></div>`;
+        }
+        return `<div class="call">
+  <div class="call-head"><span class="kind model">model call</span>${provLabel}<a href="${link}">${esc(model)}</a><span class="meta-inline">${fmtDur(spanDuration(span))}${tail}</span></div>
+  ${content}
+</div>`;
+    }
+    if (span.name === SPAN.tool) {
+        const name = attrStr(span.attributes, A.toolName) ?? shortName(span.name);
+        const inB = attrNum(span.attributes, A.toolIn);
+        const outB = attrNum(span.attributes, A.toolOut);
+        const sizes = `in ${inB ?? "?"}B / out ${outB ?? "?"}B`;
+        const err = span.statusCode === "error" ? ` <span class="badge err">error</span>` : "";
+        return `<div class="call">
+  <div class="call-head"><span class="kind tool">tool</span><a href="${link}">${esc(name)}</a>${err}<span class="meta-inline">${fmtDur(spanDuration(span))} · ${sizes}</span></div>
+</div>`;
+    }
+    // Any other nested span: a compact line.
+    return `<div class="call"><div class="call-head"><span class="kind tool">${esc(shortName(span.name))}</span><a href="${link}">details</a><span class="meta-inline">${fmtDur(spanDuration(span))}</span></div></div>`;
+}
+// ── shared bits ──────────────────────────────────────────────────────────────────
+/** Render a breadcrumb trail; a `null` href makes the segment plain text. */
+function crumbs(items) {
+    const parts = items.map(([href, label]) => href ? `<a href="${href}">${esc(label)}</a>` : `<span>${esc(label)}</span>`);
+    return `<div class="crumbs">${parts.join(`<span class="sep">/</span>`)}</div>`;
+}
+//# sourceMappingURL=index.js.map