dashboard-blipburst 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ajmal Nasumudeen
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,106 @@
+# dashboard-blipburst
+
+A local, zero-dependency live dashboard for [BlipBurst](https://github.com/stormdotcom/BlipBurst) — see fault injection happen in real time, browse a history of past experiment runs, spot which endpoints get chaos-tested (and which never do), and track MTTR per fault type.
+
+It's a standalone package: installing or running it never touches your `blipburst` install, and `blipburst` has no dependency on it either. Wire the two together with a couple of lines in your own app config.
+
+## Install
+
+```bash
+npm install -g dashboard-blipburst
+```
+
+## Run it
+
+```bash
+blipburst-dashboard
+```
+
+- Binds to port `4477` by default. If that's taken, it auto-increments (`4478`, `4479`, …) and prints the port it actually bound.
+- Writes the resolved port to `.blipburst/port` in the current directory, so the SDK-side adapter (below) can find it automatically without you hardcoding a port anywhere.
+- Open the printed URL in a browser for the live dashboard.
+
+Override the preferred port with `--port` / `-p`, or the `BLIPBURST_DASHBOARD_PORT` env var:
+
+```bash
+blipburst-dashboard --port 5000
+```
+
+## Wire it up to BlipBurst
+
+No changes to `blipburst` itself are needed — everything below plugs into config options `blipburst` already supports.
+
+### Option A — logger transport (recommended, covers everything)
+
+```ts
+import { BlipBurst } from 'blipburst';
+import { toDashboardTransport } from 'dashboard-blipburst';
+
+const sim = new BlipBurst({
+  profile: 'flaky',
+  logger: { transport: toDashboardTransport() },
+});
+```
+
+If the dashboard isn't running when an event fires, `toDashboardTransport` buffers it to `.blipburst/log.jsonl` instead of throwing — nothing is lost, and the backlog flushes automatically the next time a transport is created (e.g. your app restarts with the dashboard now up), or on demand:
+
+```ts
+import { flushBuffer } from 'dashboard-blipburst';
+await flushBuffer();
+```
+
+### Option B — webhook (uses BlipBurst's existing webhook emitter)
+
+```ts
+import { BlipBurst } from 'blipburst';
+import { toDashboardWebhookUrl } from 'dashboard-blipburst';
+
+const sim = new BlipBurst({
+  profile: 'cascade',
+  webhook: { url: toDashboardWebhookUrl() },
+});
+```
+
+### Option C — full request coverage (for the "untested endpoints" heatmap)
+
+BlipBurst only logs when a fault actually fires, so log/webhook wiring alone can't tell "endpoint gets hit constantly but never chaos-tested" apart from "endpoint isn't hit at all." `wrapForDashboard` wraps `makeRequest()` so *every* call is reported, faulted or not:
+
+```ts
+import { BlipBurst } from 'blipburst';
+import { wrapForDashboard, toDashboardTransport } from 'dashboard-blipburst';
+
+const sim = wrapForDashboard(
+  new BlipBurst({ profile: 'flaky', logger: { transport: toDashboardTransport() } })
+);
+
+await sim.makeRequest(); // now tracked whether or not a fault fired
+```
+
+This also unlocks exact MTTR (measured time from a failed call to the next success on that endpoint) instead of the log-only estimate (duration of consecutive fault bursts).
+
+## What the dashboard shows
+
+- **Live fault feed** — streamed over SSE as `fault.injected` / `request.failed` events arrive.
+- **Chaos coverage heatmap** — per endpoint: total requests and how many were faulted. Rows tagged `untested` were exercised but never fault-injected (only available when using `wrapForDashboard`).
+- **MTTR per fault type** — mean time from a fault firing to recovery, per `Fault['kind']`.
+- **Experiment run history** — events grouped by run (one per adapter instance / process), with start/end time, event and failure counts, and a fault-kind breakdown.
+
+History persists to `.blipburst/events.jsonl` in the dashboard's working directory across restarts.
+
+## HTTP API
+
+| Endpoint | Method | Purpose |
+|---|---|---|
+| `/ingest/log` | POST | Used by `toDashboardTransport()` |
+| `/ingest/webhook` | POST | Used by `toDashboardWebhookUrl()` |
+| `/ingest/request` | POST | Used by `wrapForDashboard()` |
+| `/events/stream` | GET (SSE) | Live event stream |
+| `/api/events` | GET | Recent events (`?limit=`, `?since=`) |
+| `/api/runs` | GET | Grouped run history |
+| `/api/heatmap` | GET | Endpoint x fault-kind matrix |
+| `/api/mttr` | GET | MTTR per fault kind |
+| `/api/health` | GET | Liveness check |
+
+## License
+
+MIT © Ajmal N

package/bin/cli.js

@@ -0,0 +1,38 @@
+#!/usr/bin/env node
+import { startDashboardServer } from '../src/server.js';
+import { DEFAULT_PORT } from '../src/port.js';
+
+function parseArgs(argv) {
+  const out = { port: undefined };
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i];
+    if (arg === '--port' || arg === '-p') {
+      out.port = parseInt(argv[++i], 10);
+    } else if (arg.startsWith('--port=')) {
+      out.port = parseInt(arg.split('=')[1], 10);
+    }
+  }
+  return out;
+}
+
+async function main() {
+  const { port } = parseArgs(process.argv.slice(2));
+  const preferredPort = Number.isFinite(port) ? port : DEFAULT_PORT;
+
+  const { port: resolvedPort } = await startDashboardServer({ port: preferredPort });
+
+  console.log(`BlipBurst dashboard running at http://localhost:${resolvedPort}`);
+  if (resolvedPort !== preferredPort) {
+    console.log(`(port ${preferredPort} was in use — auto-selected ${resolvedPort})`);
+  }
+  console.log(`Port written to .blipburst/port — point BlipBurst's logger/webhook adapter at it automatically.`);
+
+  const shutdown = () => process.exit(0);
+  process.on('SIGINT', shutdown);
+  process.on('SIGTERM', shutdown);
+}
+
+main().catch((err) => {
+  console.error('Failed to start BlipBurst dashboard:', err);
+  process.exit(1);
+});

package/index.d.ts

@@ -0,0 +1,66 @@
+// Structural copies of the BlipBurst shapes these adapters plug into.
+// Kept local (rather than imported from `blipburst`) so this package stays
+// dependency-free and independently publishable; the shapes must match
+// `LogEntry` / `LogTransport` exported by `blipburst/src/types.ts`.
+
+export type BlipBurstLogLevel = 'debug' | 'info' | 'warn' | 'error' | 'silent';
+
+export interface BlipBurstLogEntry {
+  timestamp: string;
+  level: BlipBurstLogLevel;
+  event: string;
+  data?: Record<string, unknown>;
+}
+
+export type BlipBurstLogTransport = (entry: BlipBurstLogEntry) => void;
+
+/** Minimal shape of a `blipburst` instance that `wrapForDashboard` needs. */
+export interface BlipBurstLike {
+  makeRequest(overrideUrl?: string): Promise<unknown>;
+  getMetrics(): { faultStats: Record<string, number>; [key: string]: unknown };
+}
+
+export interface DashboardAdapterOptions {
+  /** Group events from this call under a specific run id instead of a freshly generated one. */
+  runId?: string;
+  /** Dashboard port override; otherwise read from `.blipburst/port` or defaults to 4477. */
+  port?: number;
+}
+
+/**
+ * Builds a `LogTransport` for `new BlipBurst({ logger: { transport } })`
+ * that forwards fault/log events to a running dashboard-blipburst
+ * instance, buffering to `.blipburst/log.jsonl` when it isn't reachable.
+ */
+export function toDashboardTransport(port?: number, options?: DashboardAdapterOptions): BlipBurstLogTransport;
+
+/** Builds the URL to pass as `webhook.url` so BlipBurst's own WebhookEmitter posts straight at the dashboard. */
+export function toDashboardWebhookUrl(port?: number): string;
+
+/**
+ * Wraps a BlipBurst instance so every `makeRequest()` call — faulted or
+ * not — is reported to the dashboard, enabling accurate chaos-coverage
+ * heatmaps (which endpoints were exercised but never fault-tested).
+ */
+export function wrapForDashboard<T extends BlipBurstLike>(sim: T, options?: DashboardAdapterOptions): T;
+
+/** Replays any events buffered in `.blipburst/log.jsonl` while the dashboard was unreachable. */
+export function flushBuffer(port?: number): Promise<{ flushed: number; remaining?: number }>;
+
+export interface StartDashboardServerOptions {
+  /** Preferred port to bind; auto-increments on EADDRINUSE. Defaults to 4477. */
+  port?: number;
+  /** How many ports above `port` to try before giving up. Defaults to 20. */
+  maxPortAttempts?: number;
+}
+
+export interface StartDashboardServerResult {
+  server: import('node:http').Server;
+  port: number;
+}
+
+/** Starts the dashboard HTTP+SSE server. Used by the `blipburst-dashboard` bin; importable for embedding/tests. */
+export function startDashboardServer(options?: StartDashboardServerOptions): Promise<StartDashboardServerResult>;
+
+export const DEFAULT_PORT: number;
+export function resolvePort(explicitPort?: number): number;

package/index.js

@@ -0,0 +1,3 @@
+export { toDashboardTransport, toDashboardWebhookUrl, wrapForDashboard, flushBuffer } from './src/adapter.js';
+export { startDashboardServer } from './src/server.js';
+export { DEFAULT_PORT, resolvePort } from './src/port.js';

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "dashboard-blipburst",
+  "version": "0.1.0",
+  "description": "Local live dashboard for BlipBurst — fault feed, experiment run history, endpoint/tenant chaos heatmap, and MTTR per fault type. Install globally, point BlipBurst's logger/webhook at it.",
+  "type": "module",
+  "main": "./index.js",
+  "types": "./index.d.ts",
+  "bin": {
+    "blipburst-dashboard": "./bin/cli.js"
+  },
+  "files": [
+    "bin",
+    "src",
+    "public",
+    "index.js",
+    "index.d.ts",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "start": "node ./bin/cli.js"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "keywords": [
+    "blipburst",
+    "chaos-engineering",
+    "dashboard",
+    "observability",
+    "fault-injection",
+    "cli"
+  ],
+  "author": "Ajmal N",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/stormdotcom/BlipBurst.git",
+    "directory": "dashboard-blipburst"
+  },
+  "homepage": "https://github.com/stormdotcom/BlipBurst/tree/main/dashboard-blipburst#readme"
+}

package/public/index.html

@@ -0,0 +1,305 @@
+<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8" />
+<meta name="viewport" content="width=device-width, initial-scale=1" />
+<title>BlipBurst Dashboard</title>
+<style>
+  :root {
+    --bg: #0b0e14;
+    --panel: #12161f;
+    --panel-border: #1f2530;
+    --text: #e6e9ef;
+    --text-dim: #8b93a3;
+    --accent: #7c9dff;
+    --ok: #4ade80;
+    --warn: #fbbf24;
+    --danger: #f87171;
+    --mono: 'SFMono-Regular', Consolas, 'Liberation Mono', Menlo, monospace;
+  }
+  * { box-sizing: border-box; }
+  body {
+    margin: 0;
+    background: var(--bg);
+    color: var(--text);
+    font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif;
+    font-size: 14px;
+  }
+  header {
+    display: flex;
+    align-items: center;
+    gap: 12px;
+    padding: 14px 20px;
+    border-bottom: 1px solid var(--panel-border);
+  }
+  header h1 {
+    font-size: 16px;
+    margin: 0;
+    font-weight: 600;
+    letter-spacing: 0.2px;
+  }
+  header .dot {
+    width: 8px; height: 8px; border-radius: 50%;
+    background: var(--danger);
+    box-shadow: 0 0 0 3px rgba(248,113,113,0.15);
+  }
+  header .dot.live { background: var(--ok); box-shadow: 0 0 0 3px rgba(74,222,128,0.15); }
+  header .status { font-size: 12px; color: var(--text-dim); }
+  header .spacer { flex: 1; }
+  header code { font-family: var(--mono); color: var(--text-dim); font-size: 12px; }
+
+  main {
+    display: grid;
+    grid-template-columns: 1.1fr 1fr;
+    gap: 16px;
+    padding: 16px 20px;
+    max-width: 1400px;
+    margin: 0 auto;
+  }
+  @media (max-width: 900px) { main { grid-template-columns: 1fr; } }
+
+  .panel {
+    background: var(--panel);
+    border: 1px solid var(--panel-border);
+    border-radius: 10px;
+    padding: 14px 16px;
+    min-width: 0;
+  }
+  .panel h2 {
+    font-size: 13px;
+    text-transform: uppercase;
+    letter-spacing: 0.6px;
+    color: var(--text-dim);
+    margin: 0 0 10px 0;
+    display: flex;
+    align-items: center;
+    gap: 8px;
+  }
+  .panel h2 .hint { text-transform: none; letter-spacing: 0; font-size: 11px; color: var(--text-dim); font-weight: 400; }
+
+  .feed { max-height: 360px; overflow-y: auto; display: flex; flex-direction: column; gap: 6px; }
+  .feed-row {
+    display: grid;
+    grid-template-columns: 74px auto 1fr;
+    gap: 8px;
+    align-items: baseline;
+    padding: 6px 8px;
+    border-radius: 6px;
+    background: rgba(255,255,255,0.02);
+    font-family: var(--mono);
+    font-size: 12px;
+  }
+  .feed-row .t { color: var(--text-dim); }
+  .feed-row .kind { padding: 1px 6px; border-radius: 4px; font-weight: 600; white-space: nowrap; }
+  .feed-row .kind.latency { background: rgba(124,157,255,0.15); color: var(--accent); }
+  .feed-row .kind.httpError { background: rgba(248,113,113,0.15); color: var(--danger); }
+  .feed-row .kind.reset { background: rgba(248,113,113,0.15); color: var(--danger); }
+  .feed-row .kind.timeout { background: rgba(251,191,36,0.15); color: var(--warn); }
+  .feed-row .kind.corruption { background: rgba(251,191,36,0.15); color: var(--warn); }
+  .feed-row .kind.none { background: rgba(74,222,128,0.12); color: var(--ok); }
+  .feed-row .url { color: var(--text); overflow: hidden; text-overflow: ellipsis; white-space: nowrap; }
+  .empty { color: var(--text-dim); font-size: 12px; padding: 8px 0; }
+
+  table { width: 100%; border-collapse: collapse; font-size: 12px; }
+  th, td { text-align: left; padding: 6px 8px; border-bottom: 1px solid var(--panel-border); }
+  th { color: var(--text-dim); font-weight: 500; }
+  td.num { text-align: right; font-family: var(--mono); }
+  tr.untested td.url::after {
+    content: 'untested';
+    margin-left: 8px;
+    font-size: 10px;
+    padding: 1px 6px;
+    border-radius: 4px;
+    background: rgba(251,191,36,0.15);
+    color: var(--warn);
+  }
+
+  .runs-list { display: flex; flex-direction: column; gap: 8px; max-height: 360px; overflow-y: auto; }
+  .run { border: 1px solid var(--panel-border); border-radius: 8px; padding: 8px 10px; }
+  .run .row1 { display: flex; justify-content: space-between; font-family: var(--mono); font-size: 12px; color: var(--text-dim); }
+  .run .row2 { margin-top: 4px; font-size: 12px; }
+  .badge { display: inline-block; padding: 1px 6px; border-radius: 4px; margin-right: 6px; font-size: 11px; }
+  .badge.fail { background: rgba(248,113,113,0.15); color: var(--danger); }
+  .badge.ok { background: rgba(74,222,128,0.15); color: var(--ok); }
+
+  .mttr-bars { display: flex; flex-direction: column; gap: 10px; }
+  .mttr-row .label { display: flex; justify-content: space-between; font-size: 12px; margin-bottom: 4px; }
+  .mttr-row .track { background: rgba(255,255,255,0.05); border-radius: 4px; height: 8px; overflow: hidden; }
+  .mttr-row .fill { height: 100%; background: var(--accent); }
+  .mttr-source { font-size: 11px; color: var(--text-dim); margin-top: 6px; }
+
+  ::-webkit-scrollbar { width: 8px; height: 8px; }
+  ::-webkit-scrollbar-thumb { background: var(--panel-border); border-radius: 4px; }
+</style>
+</head>
+<body>
+<header>
+  <div class="dot" id="conn-dot"></div>
+  <h1>BlipBurst Dashboard</h1>
+  <span class="status" id="conn-status">connecting…</span>
+  <span class="spacer"></span>
+  <code id="port-hint"></code>
+</header>
+
+<main>
+  <section class="panel" style="grid-column: 1 / -1;">
+    <h2>Live fault feed <span class="hint">fault.injected / request.failed events as they arrive</span></h2>
+    <div class="feed" id="feed"><div class="empty">Waiting for events — point BlipBurst's <code>logger.transport</code> or <code>webhook.url</code> at this dashboard.</div></div>
+  </section>
+
+  <section class="panel">
+    <h2>Chaos coverage heatmap <span class="hint">by endpoint / url</span></h2>
+    <table>
+      <thead><tr><th>Endpoint</th><th class="num">Requests</th><th class="num">Faulted</th></tr></thead>
+      <tbody id="heatmap-body"><tr><td colspan="3" class="empty">No data yet</td></tr></tbody>
+    </table>
+  </section>
+
+  <section class="panel">
+    <h2>MTTR by fault type <span class="hint" id="mttr-hint"></span></h2>
+    <div class="mttr-bars" id="mttr-bars"><div class="empty">No data yet</div></div>
+  </section>
+
+  <section class="panel" style="grid-column: 1 / -1;">
+    <h2>Experiment run history <span class="hint">grouped by process / adapter instance</span></h2>
+    <div class="runs-list" id="runs-list"><div class="empty">No runs recorded yet</div></div>
+  </section>
+</main>
+
+<script>
+(function () {
+  const feedEl = document.getElementById('feed');
+  const heatmapBody = document.getElementById('heatmap-body');
+  const mttrBars = document.getElementById('mttr-bars');
+  const mttrHint = document.getElementById('mttr-hint');
+  const runsList = document.getElementById('runs-list');
+  const connDot = document.getElementById('conn-dot');
+  const connStatus = document.getElementById('conn-status');
+  document.getElementById('port-hint').textContent = location.host;
+
+  const MAX_FEED_ROWS = 150;
+  let feedRows = [];
+
+  function fmtTime(iso) {
+    try { return new Date(iso).toLocaleTimeString(); } catch { return iso; }
+  }
+
+  function escapeHtml(s) {
+    return String(s ?? '').replace(/[&<>"']/g, (c) => ({'&':'&amp;','<':'&lt;','>':'&gt;','"':'&quot;',"'":'&#39;'}[c]));
+  }
+
+  function renderFeed() {
+    if (feedRows.length === 0) {
+      feedEl.innerHTML = '<div class="empty">Waiting for events — point BlipBurst\'s <code>logger.transport</code> or <code>webhook.url</code> at this dashboard.</div>';
+      return;
+    }
+    feedEl.innerHTML = feedRows.slice(0, MAX_FEED_ROWS).map((e) => {
+      const kind = e.faultKind || (e.success === false ? 'httpError' : 'none');
+      const label = e.faultKind || (e.success === false ? 'failed' : 'ok');
+      return '<div class="feed-row">' +
+        '<span class="t">' + fmtTime(e.timestamp) + '</span>' +
+        '<span class="kind ' + escapeHtml(kind) + '">' + escapeHtml(label) + '</span>' +
+        '<span class="url">' + escapeHtml(e.url || '—') + '</span>' +
+        '</div>';
+    }).join('');
+  }
+
+  function addEvent(e) {
+    feedRows.unshift(e);
+    if (feedRows.length > MAX_FEED_ROWS) feedRows.length = MAX_FEED_ROWS;
+    renderFeed();
+  }
+
+  async function refreshHeatmap() {
+    const res = await fetch('/api/heatmap');
+    const data = await res.json();
+    if (!data.rows || data.rows.length === 0) {
+      heatmapBody.innerHTML = '<tr><td colspan="3" class="empty">No data yet</td></tr>';
+      return;
+    }
+    heatmapBody.innerHTML = data.rows.map((row) => {
+      const requests = data.sawRequestEvents ? row.totalRequests : '—';
+      return '<tr class="' + (row.untested ? 'untested' : '') + '">' +
+        '<td class="url">' + escapeHtml(row.url) + '</td>' +
+        '<td class="num">' + requests + '</td>' +
+        '<td class="num">' + row.faultedCount + '</td>' +
+        '</tr>';
+    }).join('');
+  }
+
+  async function refreshMttr() {
+    const res = await fetch('/api/mttr');
+    const data = await res.json();
+    const entries = Object.entries(data.mttrMsByKind || {});
+    mttrHint.textContent = data.source === 'request'
+      ? '(measured: time-to-next-success)'
+      : '(estimated from fault-injection log bursts — wrap with wrapForDashboard() for exact MTTR)';
+    if (entries.length === 0) {
+      mttrBars.innerHTML = '<div class="empty">No data yet</div>';
+      return;
+    }
+    const max = Math.max(...entries.map(([, ms]) => ms), 1);
+    mttrBars.innerHTML = entries.map(([kind, ms]) => {
+      const pct = Math.max(4, Math.round((ms / max) * 100));
+      return '<div class="mttr-row">' +
+        '<div class="label"><span>' + escapeHtml(kind) + '</span><span>' + ms + ' ms</span></div>' +
+        '<div class="track"><div class="fill" style="width:' + pct + '%"></div></div>' +
+        '</div>';
+    }).join('');
+  }
+
+  async function refreshRuns() {
+    const res = await fetch('/api/runs');
+    const data = await res.json();
+    if (!data.runs || data.runs.length === 0) {
+      runsList.innerHTML = '<div class="empty">No runs recorded yet</div>';
+      return;
+    }
+    runsList.innerHTML = data.runs.map((r) => {
+      const kinds = Object.entries(r.faultKinds || {}).map(([k, n]) => k + ':' + n).join('  ');
+      return '<div class="run">' +
+        '<div class="row1"><span>' + escapeHtml(r.runId) + '</span><span>' + fmtTime(r.startedAt) + ' → ' + fmtTime(r.endedAt) + '</span></div>' +
+        '<div class="row2">' +
+          '<span class="badge ok">' + r.eventCount + ' events</span>' +
+          (r.failureCount ? '<span class="badge fail">' + r.failureCount + ' failed</span>' : '') +
+          '<span>' + escapeHtml(kinds) + '</span>' +
+        '</div>' +
+      '</div>';
+    }).join('');
+  }
+
+  function refreshDerived() {
+    refreshHeatmap();
+    refreshMttr();
+    refreshRuns();
+  }
+
+  async function loadInitial() {
+    const res = await fetch('/api/events?limit=150');
+    const data = await res.json();
+    feedRows = (data.events || []).slice().reverse();
+    renderFeed();
+    refreshDerived();
+  }
+
+  function connectStream() {
+    const es = new EventSource('/events/stream');
+    es.onopen = () => { connDot.classList.add('live'); connStatus.textContent = 'live'; };
+    es.onerror = () => { connDot.classList.remove('live'); connStatus.textContent = 'reconnecting…'; };
+    let refreshTimer = null;
+    es.onmessage = (msg) => {
+      try {
+        const record = JSON.parse(msg.data);
+        addEvent(record);
+        clearTimeout(refreshTimer);
+        refreshTimer = setTimeout(refreshDerived, 500);
+      } catch { /* ignore malformed frame */ }
+    };
+  }
+
+  loadInitial();
+  connectStream();
+})();
+</script>
+</body>
+</html>

package/src/adapter.js

@@ -0,0 +1,171 @@
+import { randomUUID } from 'node:crypto';
+import { appendFileSync, existsSync, readFileSync, writeFileSync } from 'node:fs';
+import { resolvePort, ensureBlipDir, BUFFER_FILE } from './port.js';
+
+function bufferEnvelope(envelope) {
+  ensureBlipDir();
+  try {
+    appendFileSync(BUFFER_FILE, JSON.stringify(envelope) + '\n');
+  } catch {
+    /* if we can't even buffer, drop the event rather than throw */
+  }
+}
+
+async function postJson(port, path, payload) {
+  const res = await fetch(`http://localhost:${port}${path}`, {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify(payload),
+  });
+  if (!res.ok) throw new Error(`dashboard responded ${res.status}`);
+}
+
+/** Best-effort send: on any failure (dashboard not running, network error) buffer to disk instead of throwing. */
+async function sendOrBuffer(port, path, payload) {
+  try {
+    await postJson(port, path, payload);
+  } catch {
+    bufferEnvelope({ path, payload });
+  }
+}
+
+/**
+ * Replays any events buffered while the dashboard was down. Safe to call
+ * repeatedly (e.g. before every send) — it's a no-op once the buffer is
+ * drained. Failures leave the buffer file untouched so nothing is lost.
+ */
+export async function flushBuffer(port) {
+  const resolvedPort = resolvePort(port);
+  if (!existsSync(BUFFER_FILE)) return { flushed: 0 };
+
+  let lines;
+  try {
+    lines = readFileSync(BUFFER_FILE, 'utf8').split('\n').filter(Boolean);
+  } catch {
+    return { flushed: 0 };
+  }
+  if (lines.length === 0) return { flushed: 0 };
+
+  const remaining = [];
+  let flushed = 0;
+  for (const line of lines) {
+    let envelope;
+    try {
+      envelope = JSON.parse(line);
+    } catch {
+      continue; // drop corrupt line
+    }
+    try {
+      await postJson(resolvedPort, envelope.path, envelope.payload);
+      flushed++;
+    } catch {
+      remaining.push(line);
+    }
+  }
+
+  try {
+    writeFileSync(BUFFER_FILE, remaining.length ? remaining.join('\n') + '\n' : '');
+  } catch {
+    /* best-effort */
+  }
+  return { flushed, remaining: remaining.length };
+}
+
+/**
+ * Builds a `LogTransport` (the shape BlipBurst's `LoggerOptions.transport`
+ * expects: `(entry: LogEntry) => void`) that forwards every log entry to a
+ * running dashboard-blipburst instance. If the dashboard isn't reachable,
+ * events are appended to `.blipburst/log.jsonl` instead of being lost, and
+ * are flushed automatically the next time this transport is created (i.e.
+ * the next process start) or on demand via `flushBuffer()`.
+ *
+ * Usage:
+ *   import { toDashboardTransport } from 'dashboard-blipburst';
+ *   const sim = new BlipBurst({ logger: { transport: toDashboardTransport() } });
+ */
+export function toDashboardTransport(port, options = {}) {
+  const resolvedPort = resolvePort(port);
+  const runId = options.runId ?? randomUUID();
+
+  // Try to drain anything buffered from a previous run without blocking
+  // transport creation.
+  flushBuffer(resolvedPort).catch(() => {});
+
+  return function dashboardTransport(entry) {
+    // LogTransport is synchronous/fire-and-forget by contract — never await
+    // or throw here, BlipBurst calls this inline on the request path.
+    sendOrBuffer(resolvedPort, '/ingest/log', { runId, entry, source: 'logger' }).catch(() => {});
+  };
+}
+
+/**
+ * Returns the URL to hand to BlipBurst's `webhook.url` option so its
+ * built-in WebhookEmitter posts fault/circuit events straight at the
+ * dashboard — no adapter function needed on that path since BlipBurst's
+ * webhook is already URL-based.
+ *
+ * Usage:
+ *   const sim = new BlipBurst({ webhook: { url: toDashboardWebhookUrl() } });
+ */
+export function toDashboardWebhookUrl(port) {
+  const resolvedPort = resolvePort(port);
+  return `http://localhost:${resolvedPort}/ingest/webhook`;
+}
+
+function faultKindDiff(before, after) {
+  for (const kind of Object.keys(after)) {
+    if ((after[kind] ?? 0) > (before[kind] ?? 0)) return kind;
+  }
+  return null;
+}
+
+/**
+ * Wraps a `BlipBurst` instance so *every* `makeRequest()` call — faulted or
+ * not — is reported to the dashboard. This is what makes the "chaos
+ * coverage" heatmap able to tell the difference between an endpoint that
+ * is merely faulted often and one that is called constantly but never
+ * chaos-tested: logger/webhook events alone only fire when a fault
+ * actually happens.
+ *
+ * Does not modify BlipBurst itself — it wraps the public `makeRequest` and
+ * `getMetrics` methods on the instance you already constructed.
+ *
+ * Usage:
+ *   const sim = wrapForDashboard(new BlipBurst({ profile: 'flaky' }));
+ *   await sim.makeRequest();
+ */
+export function wrapForDashboard(sim, options = {}) {
+  const resolvedPort = resolvePort(options.port);
+  const runId = options.runId ?? randomUUID();
+  const original = sim.makeRequest.bind(sim);
+
+  sim.makeRequest = async function wrappedMakeRequest(overrideUrl) {
+    const before = sim.getMetrics().faultStats;
+    // `url` is a private TS field on BlipBurst at compile time, but private
+    // fields are a type-checker construct only — the instance property is
+    // readable like any other at runtime, which is what lets us log the
+    // endpoint for calls that don't pass an explicit override.
+    const url = overrideUrl ?? sim.url ?? 'unknown';
+    const startedAt = Date.now();
+    let success = true;
+    try {
+      return await original(overrideUrl);
+    } catch (err) {
+      success = false;
+      throw err;
+    } finally {
+      const after = sim.getMetrics().faultStats;
+      const faultKind = faultKindDiff(before, after);
+      sendOrBuffer(resolvedPort, '/ingest/request', {
+        runId,
+        url,
+        faultKind,
+        success,
+        durationMs: Date.now() - startedAt,
+        timestamp: new Date().toISOString(),
+      }).catch(() => {});
+    }
+  };
+
+  return sim;
+}

package/src/port.js

@@ -0,0 +1,45 @@
+import { mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+export const DEFAULT_PORT = 4477;
+export const BLIP_DIR = '.blipburst';
+export const PORT_FILE = join(BLIP_DIR, 'port');
+export const BUFFER_FILE = join(BLIP_DIR, 'log.jsonl');
+export const EVENTS_FILE = join(BLIP_DIR, 'events.jsonl');
+
+export function ensureBlipDir() {
+  try {
+    mkdirSync(BLIP_DIR, { recursive: true });
+  } catch {
+    /* best-effort */
+  }
+}
+
+/** Read the port the dashboard server last advertised in this cwd, if any. */
+export function readPortFile() {
+  try {
+    const raw = readFileSync(PORT_FILE, 'utf8').trim();
+    const parsed = parseInt(raw, 10);
+    if (Number.isFinite(parsed) && parsed > 0) return parsed;
+  } catch {
+    /* no port file yet */
+  }
+  return null;
+}
+
+export function writePortFile(port) {
+  ensureBlipDir();
+  try {
+    writeFileSync(PORT_FILE, String(port), 'utf8');
+  } catch {
+    /* best-effort */
+  }
+}
+
+/** Resolve the port the dashboard is (or should be) reachable on. */
+export function resolvePort(explicitPort) {
+  if (explicitPort) return explicitPort;
+  const fromEnv = process.env.BLIPBURST_DASHBOARD_PORT;
+  if (fromEnv && Number.isFinite(parseInt(fromEnv, 10))) return parseInt(fromEnv, 10);
+  return readPortFile() ?? DEFAULT_PORT;
+}

package/src/server.js

@@ -0,0 +1,168 @@
+import { createServer } from 'node:http';
+import { readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { dirname, join } from 'node:path';
+import { EventStore } from './store.js';
+import { writePortFile } from './port.js';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const INDEX_HTML_PATH = join(__dirname, '..', 'public', 'index.html');
+
+function readJsonBody(req) {
+  return new Promise((resolve, reject) => {
+    let raw = '';
+    req.on('data', (chunk) => {
+      raw += chunk;
+      if (raw.length > 5_000_000) req.destroy(new Error('payload too large'));
+    });
+    req.on('end', () => {
+      if (!raw) return resolve({});
+      try {
+        resolve(JSON.parse(raw));
+      } catch (err) {
+        reject(err);
+      }
+    });
+    req.on('error', reject);
+  });
+}
+
+function sendJson(res, status, payload) {
+  const body = JSON.stringify(payload);
+  res.writeHead(status, {
+    'Content-Type': 'application/json',
+    'Access-Control-Allow-Origin': '*',
+  });
+  res.end(body);
+}
+
+function createRequestHandler(store) {
+  const sseClients = new Set();
+
+  return async function handler(req, res) {
+    const url = new URL(req.url, `http://localhost`);
+    const { pathname } = url;
+
+    if (req.method === 'OPTIONS') {
+      res.writeHead(204, {
+        'Access-Control-Allow-Origin': '*',
+        'Access-Control-Allow-Methods': 'GET,POST,OPTIONS',
+        'Access-Control-Allow-Headers': 'Content-Type',
+      });
+      return res.end();
+    }
+
+    if (req.method === 'GET' && pathname === '/') {
+      try {
+        const html = readFileSync(INDEX_HTML_PATH, 'utf8');
+        res.writeHead(200, { 'Content-Type': 'text/html; charset=utf-8' });
+        return res.end(html);
+      } catch {
+        res.writeHead(500);
+        return res.end('dashboard UI missing');
+      }
+    }
+
+    if (req.method === 'GET' && pathname === '/api/health') {
+      return sendJson(res, 200, { ok: true });
+    }
+
+    if (req.method === 'GET' && pathname === '/api/events') {
+      const since = url.searchParams.get('since') ?? undefined;
+      const limit = parseInt(url.searchParams.get('limit') ?? '500', 10);
+      return sendJson(res, 200, { events: store.recent(limit, since) });
+    }
+
+    if (req.method === 'GET' && pathname === '/api/runs') {
+      return sendJson(res, 200, { runs: store.runs() });
+    }
+
+    if (req.method === 'GET' && pathname === '/api/heatmap') {
+      return sendJson(res, 200, store.heatmap());
+    }
+
+    if (req.method === 'GET' && pathname === '/api/mttr') {
+      return sendJson(res, 200, store.mttr());
+    }
+
+    if (req.method === 'GET' && pathname === '/events/stream') {
+      res.writeHead(200, {
+        'Content-Type': 'text/event-stream',
+        'Cache-Control': 'no-cache',
+        Connection: 'keep-alive',
+        'Access-Control-Allow-Origin': '*',
+      });
+      res.write(': connected\n\n');
+      const send = (record) => res.write(`data: ${JSON.stringify(record)}\n\n`);
+      sseClients.add(send);
+      const unsubscribe = store.subscribe(send);
+      const keepAlive = setInterval(() => res.write(': ping\n\n'), 25_000);
+      req.on('close', () => {
+        clearInterval(keepAlive);
+        sseClients.delete(send);
+        unsubscribe();
+      });
+      return;
+    }
+
+    if (req.method === 'POST' && pathname === '/ingest/log') {
+      try {
+        const body = await readJsonBody(req);
+        const record = store.ingest('log', body);
+        return sendJson(res, 202, { ok: true, id: record.id });
+      } catch {
+        return sendJson(res, 400, { ok: false, error: 'invalid JSON body' });
+      }
+    }
+
+    if (req.method === 'POST' && pathname === '/ingest/webhook') {
+      try {
+        const body = await readJsonBody(req);
+        const record = store.ingest('webhook', body);
+        return sendJson(res, 202, { ok: true, id: record.id });
+      } catch {
+        return sendJson(res, 400, { ok: false, error: 'invalid JSON body' });
+      }
+    }
+
+    if (req.method === 'POST' && pathname === '/ingest/request') {
+      try {
+        const body = await readJsonBody(req);
+        const record = store.ingest('request', body);
+        return sendJson(res, 202, { ok: true, id: record.id });
+      } catch {
+        return sendJson(res, 400, { ok: false, error: 'invalid JSON body' });
+      }
+    }
+
+    res.writeHead(404, { 'Content-Type': 'text/plain' });
+    res.end('not found');
+  };
+}
+
+function listenWithAutoIncrement(server, port, attemptsLeft) {
+  return new Promise((resolve, reject) => {
+    server.once('error', (err) => {
+      if (err.code === 'EADDRINUSE' && attemptsLeft > 0) {
+        resolve(listenWithAutoIncrement(server, port + 1, attemptsLeft - 1));
+      } else {
+        reject(err);
+      }
+    });
+    server.listen(port, () => resolve(port));
+  });
+}
+
+/**
+ * Starts the dashboard HTTP+SSE server. Tries `preferredPort` first and
+ * auto-increments on EADDRINUSE, writing the port that was actually bound
+ * to `.blipburst/port` in the current working directory so the BlipBurst
+ * SDK adapter can discover it.
+ */
+export async function startDashboardServer({ port: preferredPort = 4477, maxPortAttempts = 20 } = {}) {
+  const store = new EventStore();
+  const server = createServer(createRequestHandler(store));
+  const port = await listenWithAutoIncrement(server, preferredPort, maxPortAttempts);
+  writePortFile(port);
+  return { server, store, port };
+}

package/src/store.js

@@ -0,0 +1,263 @@
+import { appendFileSync, existsSync, readFileSync } from 'node:fs';
+import { randomUUID } from 'node:crypto';
+import { EVENTS_FILE, ensureBlipDir } from './port.js';
+
+const MAX_IN_MEMORY = 5000;
+// Consecutive fault.injected log lines of the same kind+url within this gap
+// are treated as one "incident" for the log-only MTTR fallback.
+const INCIDENT_GAP_MS = 10_000;
+
+/**
+ * Normalizes the three ingest shapes (log-transport entries, webhook
+ * payloads, and the richer /ingest/request events from wrapForDashboard)
+ * into one flat event record the dashboard UI and derived views consume.
+ */
+function normalize(kind, body) {
+  const receivedAt = new Date().toISOString();
+  const id = randomUUID();
+
+  if (kind === 'request') {
+    return {
+      id,
+      kind,
+      receivedAt,
+      runId: body.runId ?? 'unknown',
+      timestamp: body.timestamp ?? receivedAt,
+      url: body.url ?? 'unknown',
+      faultKind: body.faultKind ?? null,
+      success: body.success !== false,
+      durationMs: typeof body.durationMs === 'number' ? body.durationMs : null,
+      event: body.faultKind ? 'fault.injected' : 'request.ok',
+      level: body.success === false ? 'warn' : 'info',
+      raw: body,
+    };
+  }
+
+  // 'log' (logger.transport) and 'webhook' both carry a BlipBurst LogEntry
+  // shape by default: { timestamp, level, event, data? }. A custom
+  // webhook.transform can change that shape entirely, so fall back
+  // gracefully when the expected fields are missing.
+  const entry = kind === 'log' ? body.entry ?? body : body;
+  const data = entry && typeof entry === 'object' ? entry.data ?? {} : {};
+  return {
+    id,
+    kind,
+    receivedAt,
+    runId: body.runId ?? 'unknown',
+    timestamp: entry?.timestamp ?? receivedAt,
+    url: data.url ?? null,
+    faultKind: entry?.event === 'fault.injected' ? data.kind ?? null : null,
+    success: entry?.event !== 'request.failed',
+    durationMs: null,
+    event: entry?.event ?? 'unknown',
+    level: entry?.level ?? 'info',
+    raw: body,
+  };
+}
+
+export class EventStore {
+  constructor() {
+    this.events = [];
+    this.subscribers = new Set();
+    this._loadFromDisk();
+  }
+
+  _loadFromDisk() {
+    ensureBlipDir();
+    if (!existsSync(EVENTS_FILE)) return;
+    try {
+      const lines = readFileSync(EVENTS_FILE, 'utf8').split('\n').filter(Boolean);
+      for (const line of lines.slice(-MAX_IN_MEMORY)) {
+        try {
+          this.events.push(JSON.parse(line));
+        } catch {
+          /* skip corrupt line */
+        }
+      }
+    } catch {
+      /* best-effort load */
+    }
+  }
+
+  ingest(kind, body) {
+    const record = normalize(kind, body);
+    this.events.push(record);
+    if (this.events.length > MAX_IN_MEMORY) this.events.shift();
+    try {
+      ensureBlipDir();
+      appendFileSync(EVENTS_FILE, JSON.stringify(record) + '\n');
+    } catch {
+      /* best-effort persistence */
+    }
+    for (const send of this.subscribers) send(record);
+    return record;
+  }
+
+  subscribe(send) {
+    this.subscribers.add(send);
+    return () => this.subscribers.delete(send);
+  }
+
+  recent(limit = 500, since) {
+    let list = this.events;
+    if (since) list = list.filter((e) => e.receivedAt > since);
+    return list.slice(-limit);
+  }
+
+  /** Group events by runId into a chronological experiment-run timeline. */
+  runs() {
+    const byRun = new Map();
+    for (const e of this.events) {
+      if (!byRun.has(e.runId)) {
+        byRun.set(e.runId, {
+          runId: e.runId,
+          startedAt: e.timestamp,
+          endedAt: e.timestamp,
+          eventCount: 0,
+          faultCount: 0,
+          failureCount: 0,
+          faultKinds: {},
+          urls: new Set(),
+        });
+      }
+      const run = byRun.get(e.runId);
+      run.eventCount++;
+      if (e.timestamp < run.startedAt) run.startedAt = e.timestamp;
+      if (e.timestamp > run.endedAt) run.endedAt = e.timestamp;
+      if (e.faultKind) {
+        run.faultCount++;
+        run.faultKinds[e.faultKind] = (run.faultKinds[e.faultKind] ?? 0) + 1;
+      }
+      if (e.success === false) run.failureCount++;
+      if (e.url) run.urls.add(e.url);
+    }
+    return [...byRun.values()]
+      .map((r) => ({ ...r, urls: [...r.urls] }))
+      .sort((a, b) => (a.startedAt < b.startedAt ? 1 : -1));
+  }
+
+  /**
+   * Endpoint x fault-kind matrix. `requestEvents` (from wrapForDashboard)
+   * tell us every call made, faulted or not, so we can surface endpoints
+   * that were exercised but never chaos-tested. Log/webhook-only setups
+   * only ever see faulted calls, so "untested" can't be computed for them
+   * — those rows are marked `coverageKnown: false`.
+   */
+  heatmap() {
+    const byUrl = new Map();
+    let sawRequestEvents = false;
+
+    for (const e of this.events) {
+      if (!e.url) continue;
+      if (e.kind === 'request') sawRequestEvents = true;
+      if (!byUrl.has(e.url)) byUrl.set(e.url, { url: e.url, totalRequests: 0, faultCounts: {}, coverageKnown: false });
+      const row = byUrl.get(e.url);
+      if (e.kind === 'request') {
+        row.totalRequests++;
+        row.coverageKnown = true;
+      }
+      if (e.faultKind) row.faultCounts[e.faultKind] = (row.faultCounts[e.faultKind] ?? 0) + 1;
+    }
+
+    const rows = [...byUrl.values()].map((row) => {
+      const faulted = Object.values(row.faultCounts).reduce((a, b) => a + b, 0);
+      return {
+        ...row,
+        faultedCount: faulted,
+        untested: row.coverageKnown && row.totalRequests > 0 && faulted === 0,
+      };
+    });
+    rows.sort((a, b) => b.faultedCount - a.faultedCount);
+    return { sawRequestEvents, rows };
+  }
+
+  /**
+   * MTTR per fault kind.
+   *
+   * Preferred method (`source: 'request'`): wrapForDashboard reports every
+   * call's success/failure, so MTTR is the mean time between a failed call
+   * attributed to a fault kind and the next successful call on that url.
+   *
+   * Fallback (`source: 'log'`): plain logger/webhook wiring only sees
+   * fault.injected lines, so we approximate recovery time as the duration
+   * of each "incident" — a run of same-kind faults on the same url with no
+   * gap larger than INCIDENT_GAP_MS between them.
+   */
+  mttr() {
+    const requestEvents = this.events.filter((e) => e.kind === 'request');
+    if (requestEvents.length > 0) return this._mttrFromRequests(requestEvents);
+    return this._mttrFromLogs();
+  }
+
+  _mttrFromRequests(requestEvents) {
+    const byUrl = new Map();
+    for (const e of requestEvents) {
+      const list = byUrl.get(e.url) ?? [];
+      list.push(e);
+      byUrl.set(e.url, list);
+    }
+
+    const durationsByKind = new Map();
+    for (const list of byUrl.values()) {
+      list.sort((a, b) => (a.timestamp < b.timestamp ? -1 : 1));
+      let openFault = null;
+      for (const e of list) {
+        if (!e.success && e.faultKind) {
+          if (!openFault) openFault = { kind: e.faultKind, since: e.timestamp };
+        } else if (e.success && openFault) {
+          const ms = Date.parse(e.timestamp) - Date.parse(openFault.since);
+          if (Number.isFinite(ms) && ms >= 0) {
+            const arr = durationsByKind.get(openFault.kind) ?? [];
+            arr.push(ms);
+            durationsByKind.set(openFault.kind, arr);
+          }
+          openFault = null;
+        }
+      }
+    }
+    return { source: 'request', mttrMsByKind: average(durationsByKind) };
+  }
+
+  _mttrFromLogs() {
+    const faultEvents = this.events
+      .filter((e) => e.faultKind)
+      .slice()
+      .sort((a, b) => (a.timestamp < b.timestamp ? -1 : 1));
+
+    const byUrlKind = new Map();
+    for (const e of faultEvents) {
+      const key = `${e.url ?? 'unknown'}::${e.faultKind}`;
+      const list = byUrlKind.get(key) ?? [];
+      list.push(e);
+      byUrlKind.set(key, list);
+    }
+
+    const durationsByKind = new Map();
+    for (const [key, list] of byUrlKind) {
+      const kind = key.split('::')[1];
+      let incidentStart = list[0].timestamp;
+      let prev = list[0].timestamp;
+      for (let i = 1; i <= list.length; i++) {
+        const cur = list[i]?.timestamp;
+        const gap = cur ? Date.parse(cur) - Date.parse(prev) : Infinity;
+        if (gap > INCIDENT_GAP_MS || !cur) {
+          const duration = Date.parse(prev) - Date.parse(incidentStart);
+          const arr = durationsByKind.get(kind) ?? [];
+          arr.push(duration);
+          durationsByKind.set(kind, arr);
+          incidentStart = cur;
+        }
+        prev = cur ?? prev;
+      }
+    }
+    return { source: 'log', mttrMsByKind: average(durationsByKind) };
+  }
+}
+
+function average(mapOfArrays) {
+  const out = {};
+  for (const [kind, arr] of mapOfArrays) {
+    out[kind] = arr.length ? Math.round(arr.reduce((a, b) => a + b, 0) / arr.length) : 0;
+  }
+  return out;
+}