experimental-a2 0.4.0 → 0.5.0

package/src/devtools-app.ts

@@ -0,0 +1,989 @@
+/** Private browser application served by `experimental-a2/devtools/server`. */
+
+import {
+  DEVTOOLS_PROTOCOL_VERSION,
+  DEVTOOLS_SESSION_PAGE_LIMIT,
+} from './devtools.ts'
+
+import type {
+  DevtoolsSessionDetail,
+  DevtoolsWireSessionSummary,
+} from './devtools.ts'
+
+export type DevtoolsBootstrap = {
+  contracts: Array<{ name: string }>
+  contract: string | null
+  sessions: DevtoolsWireSessionSummary[]
+  cursor: string | null
+  session: string | null
+  detail: DevtoolsSessionDetail | null
+  error: string | null
+}
+
+const escapeText = (value: string): string =>
+  value.replaceAll('&', '&amp;').replaceAll('<', '&lt;').replaceAll('>', '&gt;')
+
+const escapeAttribute = (value: string): string =>
+  escapeText(value).replaceAll('"', '&quot;')
+
+const formatDuration = (milliseconds: number): string => {
+  if (milliseconds < 1_000) {
+    return `${Math.max(0, Math.round(milliseconds))} ms`
+  }
+  if (milliseconds < 60_000) {
+    return `${(milliseconds / 1_000).toFixed(milliseconds < 10_000 ? 2 : 1)} s`
+  }
+  return `${(milliseconds / 60_000).toFixed(1)} min`
+}
+
+const formatRelative = (value: string): string => {
+  const delta = Date.now() - new Date(value).getTime()
+  if (delta < 1_000) return 'now'
+  if (delta < 60_000) return `${Math.floor(delta / 1_000)}s ago`
+  if (delta < 3_600_000) return `${Math.floor(delta / 60_000)}m ago`
+  if (delta < 86_400_000) return `${Math.floor(delta / 3_600_000)}h ago`
+  return `${Math.floor(delta / 86_400_000)}d ago`
+}
+
+const sessionStatus = (
+  session: DevtoolsBootstrap['sessions'][number],
+): 'failed' | 'pending' | 'settled' =>
+  session.failedCount > 0
+    ? 'failed'
+    : session.pendingCount > 0
+      ? 'pending'
+      : 'settled'
+
+const metricHtml = (label: string, value: string): string =>
+  `<div class="card"><span>${escapeText(label)}</span><strong>${escapeText(value)}</strong></div>`
+
+const shellHtml = (bootstrap: DevtoolsBootstrap): string => {
+  const options = bootstrap.contracts
+    .map(
+      ({ name }) =>
+        `<option value="${escapeAttribute(name)}"${name === bootstrap.contract ? ' selected' : ''}>${escapeText(name)}</option>`,
+    )
+    .join('')
+  const sessions = bootstrap.sessions.length
+    ? bootstrap.sessions
+        .map((session) => {
+          const active =
+            session.sessionId === bootstrap.session ? ' active' : ''
+          const events = `${session.eventCount} ${session.eventCount === 1 ? 'event' : 'events'}`
+          return `<button class="session-button${active}" type="button"><span class="session-name">${escapeText(session.sessionId)}</span><span class="dot ${sessionStatus(session)}"></span><span class="session-meta">${events}</span><span class="session-meta">${formatRelative(session.updatedAt)}</span></button>`
+        })
+        .join('')
+    : '<div class="session-meta">No durable sessions yet.</div>'
+  const more = bootstrap.cursor
+    ? '<button class="load-more" type="button">Load more</button>'
+    : ''
+
+  let main: string
+  if (!bootstrap.session) {
+    main =
+      '<main class="main"><div class="empty"><div><strong>No session selected</strong><span>Choose a durable session to inspect its lifecycle.</span></div></div></main>'
+  } else if (!bootstrap.detail) {
+    const error = bootstrap.error
+      ? `<div class="error-box">${escapeText(bootstrap.error)}</div>`
+      : ''
+    main = `<main class="main">${error}<div class="empty"><div><strong>Session unavailable</strong><span>The selected durable session could not be read.</span></div></div></main>`
+  } else {
+    const { events } = bootstrap.detail
+    const pending = events.filter(
+      (event) => event.processedAt === null && event.failedAt === null,
+    ).length
+    const attempts = events.reduce(
+      (total, event) => total + event.attemptCount,
+      0,
+    )
+    const failures = events.reduce(
+      (total, event) => total + event.failureCount,
+      0,
+    )
+    const first = events[0]
+    const last = events.at(-1)
+    const lifetime =
+      first && last
+        ? formatDuration(
+            new Date(
+              last.failedAt ?? last.processedAt ?? Date.now(),
+            ).getTime() - new Date(first.createdAt).getTime(),
+          )
+        : '0 ms'
+    const error = bootstrap.error
+      ? `<div class="error-box">${escapeText(bootstrap.error)}</div>`
+      : ''
+    main = `<main class="main">${error}<header class="session-header"><div class="session-title"><p class="eyebrow">${escapeText(bootstrap.contract ?? '')} / session</p><h1>${escapeText(bootstrap.session)}</h1><p>Read-only · durable data · refreshed by SSE</p></div><span class="live"><i></i>live</span></header><div class="cards">${metricHtml('Events', String(events.length))}${metricHtml('Pending', String(pending))}${metricHtml('Dispatches', String(attempts))}${metricHtml('Caught failures', String(failures))}${metricHtml('Lifetime', lifetime)}</div></main>`
+  }
+
+  return `<div class="shell"><aside class="sidebar"><div class="brand"><span class="mark">A2</span><div class="brand-copy"><strong>A2 Devtools</strong><span>Durable execution data</span></div></div><div class="side-controls"><p class="eyebrow">Contract</p><select class="contract-select" aria-label="Contract">${options}</select></div><div class="sessions"><p class="eyebrow">Sessions</p>${sessions}${more}</div></aside>${main}</div>`
+}
+
+const bootstrapJson = (bootstrap: DevtoolsBootstrap): string =>
+  JSON.stringify(bootstrap)
+    .replaceAll('<', '\\u003c')
+    .replaceAll('\u2028', '\\u2028')
+    .replaceAll('\u2029', '\\u2029')
+
+export const devtoolsHtml = (
+  basePath: string,
+  bootstrap: DevtoolsBootstrap,
+): string => `<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1">
+    <meta name="color-scheme" content="light">
+    <base href="${escapeAttribute(basePath)}">
+    <title>A2 Devtools</title>
+    <link rel="stylesheet" href="_a2/app.css">
+  </head>
+  <body>
+    <div id="app">${shellHtml(bootstrap)}</div>
+    <script id="a2-bootstrap" type="application/json">${bootstrapJson(bootstrap)}</script>
+    <script type="module" src="_a2/app.js"></script>
+  </body>
+</html>`
+
+export const DEVTOOLS_APP_CSS: string = String.raw`
+:root {
+  color: #1a1a1a;
+  background: #fff;
+  font-family: Geist, "Geist Sans", ui-sans-serif, system-ui, -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif;
+  font-synthesis: none;
+  --surface: #fafafa;
+  --line: #eaeaea;
+  --line-strong: #d4d4d4;
+  --muted: #666;
+  --faint: #8f8f8f;
+  --success: #15803d;
+  --warning: #b45309;
+  --danger: #dc2626;
+}
+
+* { box-sizing: border-box; }
+html, body, #app { min-height: 100%; margin: 0; }
+body { min-width: 320px; background: #fff; }
+button, select { font: inherit; }
+button { color: inherit; }
+button:focus-visible, select:focus-visible, summary:focus-visible { outline: 2px solid #000; outline-offset: 2px; }
+
+.mark {
+  display: inline-grid;
+  place-items: center;
+  width: 30px;
+  height: 30px;
+  border-radius: 6px;
+  background: #000;
+  color: #fff;
+  font-size: 12px;
+  font-weight: 700;
+  letter-spacing: -.04em;
+}
+
+.shell {
+  min-height: 100vh;
+  display: grid;
+  grid-template-columns: 248px minmax(0, 1fr);
+}
+
+.sidebar {
+  position: sticky;
+  top: 0;
+  height: 100vh;
+  display: flex;
+  flex-direction: column;
+  border-right: 1px solid var(--line);
+  background: var(--surface);
+}
+
+.brand {
+  display: flex;
+  align-items: center;
+  gap: 10px;
+  padding: 18px;
+  border-bottom: 1px solid var(--line);
+}
+
+.brand-copy strong { display: block; font-size: 13px; font-weight: 600; letter-spacing: -.01em; }
+.brand-copy span { color: var(--muted); font-size: 10px; }
+.side-controls { padding: 14px; border-bottom: 1px solid var(--line); }
+.eyebrow { margin: 0 0 8px; color: var(--muted); font-size: 10px; font-weight: 500; letter-spacing: .08em; text-transform: uppercase; }
+
+.contract-select {
+  width: 100%;
+  padding: 8px 9px;
+  color: #1a1a1a;
+  border: 1px solid var(--line-strong);
+  border-radius: 6px;
+  outline: none;
+  background: #fff;
+}
+.contract-select:focus { border-color: #000; }
+
+.sessions { min-height: 0; flex: 1; overflow: auto; padding: 12px 8px; }
+.session-button {
+  width: 100%;
+  display: grid;
+  grid-template-columns: minmax(0, 1fr) auto;
+  gap: 5px 9px;
+  padding: 9px 10px;
+  margin-bottom: 2px;
+  text-align: left;
+  border: 1px solid transparent;
+  border-radius: 6px;
+  background: transparent;
+  cursor: pointer;
+}
+.session-button:hover { background: #f0f0f0; }
+.session-button.active { border-color: var(--line-strong); background: #fff; }
+.session-name { overflow: hidden; text-overflow: ellipsis; white-space: nowrap; font-family: ui-monospace, SFMono-Regular, Menlo, monospace; font-size: 12px; }
+.session-meta { color: var(--muted); font-size: 10px; }
+.dot { align-self: center; width: 6px; height: 6px; border-radius: 99px; background: #999; }
+.dot.pending { background: var(--warning); }
+.dot.failed { background: var(--danger); }
+.dot.settled { background: var(--success); }
+.load-more { width: 100%; margin: 6px 0 10px; padding: 8px; border: 1px solid var(--line-strong); border-radius: 6px; background: #fff; cursor: pointer; color: var(--muted); }
+.load-more:hover { color: #000; border-color: #999; }
+
+.main { min-width: 0; width: 100%; max-width: 1440px; padding: 38px clamp(24px, 5vw, 72px) 72px; }
+.empty { min-height: 70vh; display: grid; place-items: center; color: var(--muted); text-align: center; }
+.empty strong { display: block; margin-bottom: 7px; color: #1a1a1a; font-size: 16px; font-weight: 500; }
+
+.session-header { display: flex; justify-content: space-between; align-items: flex-start; gap: 24px; margin-bottom: 28px; }
+.session-title { min-width: 0; }
+.session-title h1 { margin: 4px 0 8px; overflow-wrap: anywhere; font-family: ui-monospace, SFMono-Regular, Menlo, monospace; font-size: clamp(22px, 3vw, 32px); font-weight: 500; letter-spacing: -.04em; }
+.session-title p { margin: 0; color: var(--muted); font-size: 12px; }
+.live { display: inline-flex; align-items: center; gap: 7px; padding: 6px 9px; color: var(--muted); border: 1px solid var(--line); border-radius: 99px; font-size: 11px; }
+.live i { width: 6px; height: 6px; border-radius: 99px; background: var(--success); }
+
+.cards { display: grid; grid-template-columns: repeat(5, minmax(0, 1fr)); margin-bottom: 32px; overflow: hidden; border: 1px solid var(--line); border-radius: 8px; }
+.card { padding: 15px 16px; border-right: 1px solid var(--line); background: #fff; }
+.card:last-child { border-right: 0; }
+.card span { display: block; margin-bottom: 8px; color: var(--muted); font-size: 10px; font-weight: 500; }
+.card strong { font-size: 20px; font-weight: 500; letter-spacing: -.03em; }
+
+.section { margin-top: 32px; }
+.section-head { display: flex; align-items: end; justify-content: space-between; gap: 20px; margin-bottom: 11px; }
+.section-head h2 { margin: 0; font-size: 14px; font-weight: 500; letter-spacing: -.01em; }
+.section-head p { margin: 0; color: var(--muted); font-size: 11px; }
+
+.forest { overflow: hidden; border: 1px solid var(--line); border-radius: 8px; background: #fff; }
+.forest-row { --depth: 0; position: relative; display: grid; grid-template-columns: minmax(0, 1fr) auto; align-items: center; gap: 16px; min-height: 42px; padding: 9px 13px 9px calc(13px + var(--depth) * 22px); border-bottom: 1px solid var(--line); }
+.forest-row:last-child { border-bottom: 0; }
+.forest-row::before { content: ""; position: absolute; top: 0; bottom: 0; left: calc(20px + (var(--depth) - 1) * 22px); width: 1px; background: var(--depth-line, transparent); }
+.forest-row.nested { --depth-line: var(--line-strong); }
+.forest-main { min-width: 0; display: flex; align-items: center; gap: 8px; }
+.forest-main .dot { flex: none; }
+.forest-type { overflow: hidden; text-overflow: ellipsis; white-space: nowrap; font: 11px ui-monospace, SFMono-Regular, Menlo, monospace; }
+.forest-edge { color: var(--muted); font-size: 10px; white-space: nowrap; }
+.forest-edge.unknown { color: var(--warning); }
+
+.timeline { overflow: hidden; border: 1px solid var(--line); border-radius: 8px; background: #fff; }
+.timeline-axis, .event-row { display: grid; grid-template-columns: 310px minmax(320px, 1fr); }
+.timeline-axis { min-height: 37px; border-bottom: 1px solid var(--line); color: var(--muted); font-size: 9px; }
+.axis-label { padding: 12px 14px; border-right: 1px solid var(--line); font-weight: 500; }
+.axis-track { position: relative; display: flex; justify-content: space-between; padding: 12px 16px; }
+.event-row { min-height: 84px; border-bottom: 1px solid var(--line); }
+.event-row:last-child { border-bottom: 0; }
+.event-info { min-width: 0; padding: 11px 14px; border-right: 1px solid var(--line); }
+.event-line { display: flex; align-items: center; gap: 8px; min-width: 0; }
+.event-index { color: var(--muted); font-family: ui-monospace, SFMono-Regular, Menlo, monospace; font-size: 10px; }
+.event-type { overflow: hidden; text-overflow: ellipsis; white-space: nowrap; font-family: ui-monospace, SFMono-Regular, Menlo, monospace; font-size: 12px; }
+.event-sub { display: flex; flex-wrap: wrap; gap: 5px 9px; margin-top: 7px; color: var(--muted); font-size: 9px; }
+.event-sub .danger { color: var(--danger); }
+.event-sub .warning { color: var(--warning); }
+.event-facts { display: flex; flex-wrap: wrap; gap: 4px 9px; margin-top: 7px; color: var(--muted); font-size: 9px; }
+.event-facts .warning { color: var(--warning); }
+.event-details { margin-top: 8px; }
+.event-details summary { color: var(--muted); cursor: pointer; font-size: 9px; }
+.event-details pre { max-height: 220px; overflow: auto; margin: 8px 0 0; padding: 10px; border: 1px solid var(--line); border-radius: 6px; background: var(--surface); color: #333; font: 10px/1.55 ui-monospace, SFMono-Regular, Menlo, monospace; white-space: pre-wrap; overflow-wrap: anywhere; }
+.event-track { position: relative; min-height: 84px; }
+.event-track::before { content: ""; position: absolute; top: 42px; right: 0; left: 0; height: 1px; background: var(--line); }
+.event-bar { position: absolute; top: 39px; height: 7px; min-width: 4px; border-radius: 99px; background: #111; }
+.event-bar.processed { background: #111; }
+.event-bar.pending { top: 38px; height: 9px; border: 1px solid #777; background: #fff; }
+.event-bar.failed { background: var(--danger); }
+.lifecycle-marker { position: absolute; z-index: 2; width: 11px; height: 11px; margin-left: -5px; border: 2px solid #fff; border-radius: 99px; background: #777; box-shadow: 0 0 0 1px #777; }
+.lifecycle-marker.created { top: 27px; border-radius: 2px; background: #fff; box-shadow: 0 0 0 1px #777; }
+.lifecycle-marker.claim { top: 37px; background: #111; box-shadow: 0 0 0 1px #111; }
+.lifecycle-marker.failure { top: 47px; background: var(--danger); box-shadow: 0 0 0 1px var(--danger); }
+.lifecycle-marker.complete { top: 47px; background: var(--success); box-shadow: 0 0 0 1px var(--success); }
+.lifecycle-marker.dead-letter { top: 57px; background: #fff; box-shadow: 0 0 0 1px var(--danger); }
+.timeline-legend { display: flex; flex-wrap: wrap; gap: 7px 14px; margin: 9px 2px 0; color: var(--muted); font-size: 9px; }
+.legend-item { display: inline-flex; align-items: center; gap: 6px; }
+.legend-key { width: 7px; height: 7px; border-radius: 99px; background: #777; }
+.legend-key.created { border: 1px solid #777; border-radius: 1px; background: #fff; }
+.legend-key.claim { background: #111; }
+.legend-key.failure { background: var(--danger); }
+.legend-key.dead-letter { border: 1px solid var(--danger); background: #fff; }
+.legend-key.complete { background: var(--success); }
+
+.snapshots { display: grid; grid-template-columns: repeat(auto-fill, minmax(220px, 1fr)); gap: 8px; }
+.snapshot { padding: 14px; border: 1px solid var(--line); border-radius: 8px; background: #fff; }
+.snapshot strong { display: block; margin-bottom: 8px; font: 12px ui-monospace, SFMono-Regular, Menlo, monospace; }
+.snapshot div { display: flex; justify-content: space-between; color: var(--muted); font-size: 10px; }
+.snapshot b { color: #111; font-weight: 500; }
+.error-box { margin-bottom: 20px; padding: 12px 14px; border: 1px solid #fecaca; border-radius: 7px; background: #fffafa; color: var(--danger); font: 11px/1.5 ui-monospace, SFMono-Regular, Menlo, monospace; white-space: pre-wrap; }
+
+@media (max-width: 850px) {
+  .shell { grid-template-columns: 1fr; }
+  .sidebar { position: static; height: auto; max-height: 310px; border-right: 0; border-bottom: 1px solid var(--line); }
+  .sessions { max-height: 180px; }
+  .cards { grid-template-columns: repeat(2, minmax(0, 1fr)); }
+  .card { border-bottom: 1px solid var(--line); }
+  .card:nth-child(2n) { border-right: 0; }
+  .card:last-child { border-bottom: 0; }
+  .timeline-axis, .event-row { grid-template-columns: 260px minmax(300px, 1fr); }
+  .timeline { overflow-x: auto; }
+  .timeline-axis, .event-row { min-width: 610px; }
+  .main { padding: 28px 20px 60px; }
+}
+`
+
+export const DEVTOOLS_APP_JS: string = String.raw`
+const root = document.querySelector('#app')
+const readBootstrap = () => {
+  const element = document.querySelector('#a2-bootstrap')
+  if (!element) return null
+  try {
+    const bootstrap = JSON.parse(element.textContent || 'null')
+    element.remove()
+    return bootstrap
+  } catch {
+    return null
+  }
+}
+const navigationFromUrl = () => {
+  const params = new URL(window.location.href).searchParams
+  return {
+    contract: params.get('contract'),
+    session: params.get('session'),
+  }
+}
+const initialNavigation = navigationFromUrl()
+const bootstrap = readBootstrap()
+const state = {
+  contracts: bootstrap?.contracts || [],
+  contract: bootstrap ? bootstrap.contract : initialNavigation.contract,
+  sessions: bootstrap?.sessions || [],
+  cursor: bootstrap?.cursor || null,
+  session: bootstrap ? bootstrap.session : initialNavigation.session,
+  detail: bootstrap?.detail || null,
+  watch: null,
+  error: bootstrap?.error || null,
+}
+
+const syncUrl = (replace) => {
+  const url = new URL(window.location.href)
+  if (state.contract) url.searchParams.set('contract', state.contract)
+  else url.searchParams.delete('contract')
+  if (state.session) url.searchParams.set('session', state.session)
+  else url.searchParams.delete('session')
+  const historyState = { contract: state.contract, session: state.session }
+  if (replace) window.history.replaceState(historyState, '', url)
+  else window.history.pushState(historyState, '', url)
+}
+
+const node = (tag, className, text) => {
+  const element = document.createElement(tag)
+  if (className) element.className = className
+  if (text !== undefined) element.textContent = text
+  return element
+}
+
+const append = (parent, ...children) => {
+  for (const child of children) if (child) parent.append(child)
+  return parent
+}
+
+const request = async (resource, params = {}) => {
+  const url = new URL('_a2/' + resource, document.baseURI)
+  for (const [key, value] of Object.entries(params)) {
+    if (value !== null && value !== undefined) url.searchParams.set(key, String(value))
+  }
+  const response = await fetch(url, { headers: { accept: 'application/json' } })
+  if (!response.ok) {
+    let message = response.status + ' ' + response.statusText
+    try { message = (await response.json()).error || message } catch {}
+    throw new Error(message)
+  }
+  return response.json()
+}
+
+const detailRevision = async (detail) => {
+  const timestamp = (value) => value === null ? null : new Date(value).getTime()
+  const bytes = new TextEncoder().encode(JSON.stringify({
+    events: detail.events.map((event) => [
+      event.id,
+      event.index,
+      event.cause?.index ?? null,
+      event.cause?.attempt ?? null,
+      timestamp(event.processedAt),
+      event.processedByAttempt,
+      timestamp(event.firstClaimedAt),
+      timestamp(event.lastClaimedAt),
+      event.attemptCount,
+      event.failureCount,
+      timestamp(event.lastFailedAt),
+      event.lastFailedAttempt,
+      event.lastError,
+      timestamp(event.failedAt),
+    ]),
+    snapshots: detail.snapshots.map((snapshot) => [
+      snapshot.reducerName,
+      snapshot.index,
+      snapshot.updatedAt === null ? 0 : new Date(snapshot.updatedAt).getTime(),
+    ]),
+  }))
+  const digest = await crypto.subtle.digest('SHA-256', bytes)
+  return Array.from(new Uint8Array(digest), (byte) => byte.toString(16).padStart(2, '0')).join('')
+}
+
+const requestDetail = async (contract, session) => {
+  const events = []
+  let snapshots = []
+  let cursor = null
+  let throughIndex = null
+  const seenCursors = new Set()
+  do {
+    const page = await request('session', {
+      contract,
+      session,
+      limit: ${DEVTOOLS_SESSION_PAGE_LIMIT},
+      cursor,
+    })
+    if ('revision' in page) return page
+    if (page.contract !== contract || page.sessionId !== session) {
+      throw new Error('Session page identity changed during inspection.')
+    }
+    if (throughIndex === null) {
+      throughIndex = page.throughIndex
+      snapshots = page.snapshots
+    } else if (page.throughIndex !== throughIndex || page.snapshots.length > 0) {
+      throw new Error('Session page frontier changed during inspection.')
+    }
+    for (const event of page.events) {
+      if (event.index !== events.length + 1 || event.index > throughIndex) {
+        throw new Error('Session event pages are not contiguous.')
+      }
+      events.push(event)
+    }
+    if (page.cursor !== null) {
+      if (
+        page.events.length === 0 ||
+        events.length === throughIndex ||
+        seenCursors.has(page.cursor)
+      ) {
+        throw new Error('Session cursor did not advance.')
+      }
+      seenCursors.add(page.cursor)
+    }
+    cursor = page.cursor
+  } while (cursor !== null)
+  if (throughIndex !== events.length) {
+    throw new Error('Session event pages ended before their frozen frontier.')
+  }
+  const detail = {
+    protocolVersion: ${DEVTOOLS_PROTOCOL_VERSION},
+    contract,
+    sessionId: session,
+    revision: '',
+    events,
+    snapshots,
+  }
+  detail.revision = await detailRevision(detail)
+  return detail
+}
+
+const watchUrl = () => {
+  const url = new URL('_a2/watch', document.baseURI)
+  url.searchParams.set('contract', state.contract)
+  url.searchParams.set('session', state.session)
+  if (state.detail?.revision) url.searchParams.set('revision', state.detail.revision)
+  return url
+}
+
+const formatTime = (value) => new Intl.DateTimeFormat(undefined, {
+  hour: '2-digit', minute: '2-digit', second: '2-digit', fractionalSecondDigits: 3,
+}).format(new Date(value))
+
+const formatRelative = (value) => {
+  const delta = Date.now() - new Date(value).getTime()
+  if (delta < 1000) return 'now'
+  if (delta < 60000) return Math.floor(delta / 1000) + 's ago'
+  if (delta < 3600000) return Math.floor(delta / 60000) + 'm ago'
+  if (delta < 86400000) return Math.floor(delta / 3600000) + 'h ago'
+  return Math.floor(delta / 86400000) + 'd ago'
+}
+
+const formatDuration = (milliseconds) => {
+  if (milliseconds < 1000) return Math.max(0, Math.round(milliseconds)) + ' ms'
+  if (milliseconds < 60000) return (milliseconds / 1000).toFixed(milliseconds < 10000 ? 2 : 1) + ' s'
+  return (milliseconds / 60000).toFixed(1) + ' min'
+}
+
+const sessionStatus = (session) => session.failedCount > 0 ? 'failed' : session.pendingCount > 0 ? 'pending' : 'settled'
+const eventStatus = (event) => event.failedAt ? 'failed' : event.processedAt ? 'processed' : 'pending'
+const eventStatusLabel = (event) => event.failedAt ? 'dead-lettered' : event.processedAt ? 'completed' : 'pending'
+
+const durableOutcomeGap = (event) => Math.max(
+  0,
+  event.attemptCount - event.failureCount - (event.processedByAttempt === null ? 0 : 1),
+)
+
+const causalEntries = (events) => {
+  const byIndex = new Map(events.map((event) => [event.index, event]))
+  const children = new Map()
+  for (const event of events) {
+    if (!event.cause || !byIndex.has(event.cause.index)) continue
+    const siblings = children.get(event.cause.index) || []
+    siblings.push(event)
+    children.set(event.cause.index, siblings)
+  }
+
+  const roots = events.filter((event) => !event.cause || !byIndex.has(event.cause.index))
+  const entries = []
+  const visited = new Set()
+  const visit = (event, depth) => {
+    if (visited.has(event.index)) return
+    visited.add(event.index)
+    entries.push({ event, depth })
+    for (const child of children.get(event.index) || []) visit(child, depth + 1)
+  }
+  for (const root of roots) visit(root, 0)
+  for (const event of events) visit(event, 0)
+  return entries
+}
+
+const loadContracts = async () => {
+  const data = await request('contracts')
+  state.contracts = data.contracts
+  if (!data.contracts.some((contract) => contract.name === state.contract)) {
+    state.contract = data.contracts[0]?.name || null
+    state.session = null
+  }
+  if (state.contract) await loadSessions(true)
+  syncUrl(true)
+  render()
+}
+
+const loadSessions = async (reset) => {
+  if (!state.contract) return
+  const data = await request('sessions', {
+    contract: state.contract,
+    cursor: reset ? null : state.cursor,
+    limit: 50,
+  })
+  state.sessions = reset ? data.sessions : state.sessions.concat(data.sessions)
+  state.cursor = data.cursor
+  if (reset && !state.session) {
+    state.session = state.sessions[0]?.sessionId || null
+  }
+  if (state.session) await loadDetail()
+}
+
+const loadDetail = async () => {
+  if (!state.contract || !state.session) return
+  state.detail = await requestDetail(state.contract, state.session)
+  state.error = null
+  render()
+}
+
+const beginWatch = () => {
+  state.watch?.close()
+  if (!state.session) return
+  const watchedContract = state.contract
+  const watchedSession = state.session
+  const source = new EventSource(watchUrl())
+  source.addEventListener('invalidate', async () => {
+    if (state.contract !== watchedContract || state.session !== watchedSession) return
+    try {
+      await Promise.all([loadDetail(), refreshSelectedSummary()])
+    } catch (error) {
+      state.error = error instanceof Error ? error.message : String(error)
+      render()
+    }
+  })
+  source.onerror = () => {
+    // EventSource reconnects. Durable state is fetched on the next
+    // invalidation, so a dropped frame cannot make the view incorrect.
+  }
+  state.watch = source
+}
+
+const refreshSelectedSummary = async () => {
+  const data = await request('sessions', { contract: state.contract, limit: 100 })
+  const fresh = data.sessions.find((session) => session.sessionId === state.session)
+  const index = state.sessions.findIndex((session) => session.sessionId === state.session)
+  if (fresh && index !== -1) state.sessions[index] = fresh
+  render()
+}
+
+const selectContract = async (name) => {
+  state.watch?.close()
+  state.contract = name
+  state.session = null
+  state.detail = null
+  state.sessions = []
+  state.cursor = null
+  state.error = null
+  syncUrl(false)
+  render()
+  try {
+    await loadSessions(true)
+    syncUrl(true)
+    beginWatch()
+  } catch (error) {
+    state.error = error instanceof Error ? error.message : String(error)
+    render()
+  }
+}
+
+const selectSession = async (id) => {
+  if (id === state.session) return
+
+  state.watch?.close()
+  state.session = id
+  state.detail = null
+  state.error = null
+  syncUrl(false)
+  render()
+  try {
+    await loadDetail()
+    beginWatch()
+  } catch (error) {
+    state.error = error instanceof Error ? error.message : String(error)
+    render()
+  }
+}
+
+const renderSidebar = () => {
+  const sidebar = node('aside', 'sidebar')
+  const brand = node('div', 'brand')
+  const copy = node('div', 'brand-copy')
+  append(copy, node('strong', '', 'A2 Devtools'), node('span', '', 'Durable execution data'))
+  append(brand, node('span', 'mark', 'A2'), copy)
+  sidebar.append(brand)
+
+  const controls = node('div', 'side-controls')
+  controls.append(node('p', 'eyebrow', 'Contract'))
+  const select = node('select', 'contract-select')
+  select.setAttribute('aria-label', 'Contract')
+  for (const contract of state.contracts) {
+    const option = node('option', '', contract.name)
+    option.value = contract.name
+    option.selected = contract.name === state.contract
+    select.append(option)
+  }
+  select.addEventListener('change', () => void selectContract(select.value))
+  controls.append(select)
+  sidebar.append(controls)
+
+  const sessions = node('div', 'sessions')
+  sessions.append(node('p', 'eyebrow', 'Sessions'))
+  if (state.sessions.length === 0) sessions.append(node('div', 'session-meta', 'No durable sessions yet.'))
+  for (const session of state.sessions) {
+    const status = sessionStatus(session)
+    const button = node('button', 'session-button' + (session.sessionId === state.session ? ' active' : ''))
+    button.type = 'button'
+    button.addEventListener('click', () => void selectSession(session.sessionId))
+    append(
+      button,
+      node('span', 'session-name', session.sessionId),
+      node('span', 'dot ' + status),
+      node('span', 'session-meta', session.eventCount + (session.eventCount === 1 ? ' event' : ' events')),
+      node('span', 'session-meta', formatRelative(session.updatedAt)),
+    )
+    sessions.append(button)
+  }
+  if (state.cursor) {
+    const more = node('button', 'load-more', 'Load more')
+    more.type = 'button'
+    more.addEventListener('click', async () => {
+      more.disabled = true
+      try { await loadSessions(false); render() } catch (error) {
+        state.error = error instanceof Error ? error.message : String(error)
+        render()
+      }
+    })
+    sessions.append(more)
+  }
+  sidebar.append(sessions)
+  return sidebar
+}
+
+const metric = (label, value) => {
+  const card = node('div', 'card')
+  append(card, node('span', '', label), node('strong', '', value))
+  return card
+}
+
+const renderCausalForest = (events) => {
+  const forest = node('div', 'forest')
+  const indexes = new Set(events.map((event) => event.index))
+  for (const { event, depth } of causalEntries(events)) {
+    const row = node('div', 'forest-row' + (depth > 0 ? ' nested' : ''))
+    row.style.setProperty('--depth', String(depth))
+    const main = node('div', 'forest-main')
+    append(
+      main,
+      node('span', 'dot ' + eventStatus(event)),
+      node('span', 'event-index', '#' + event.index),
+      node('span', 'forest-type', event.type),
+    )
+    row.append(main)
+
+    let edge
+    if (!event.cause) {
+      edge = node('span', 'forest-edge unknown', 'origin unknown')
+      edge.title = 'This may be a root append or an event written before causal metadata existed.'
+    } else if (!indexes.has(event.cause.index)) {
+      edge = node('span', 'forest-edge unknown', 'parent #' + event.cause.index + ' unavailable · attempt ' + event.cause.attempt)
+    } else {
+      edge = node('span', 'forest-edge', 'from #' + event.cause.index + ' · attempt ' + event.cause.attempt)
+    }
+    row.append(edge)
+    forest.append(row)
+  }
+  return forest
+}
+
+const renderTimeline = (events) => {
+  const timeline = node('div', 'timeline')
+  const now = Date.now()
+  const times = events.flatMap((event) => [
+    event.createdAt,
+    event.firstClaimedAt,
+    event.lastClaimedAt,
+    event.lastFailedAt,
+    event.processedAt,
+    event.failedAt,
+    eventStatus(event) === 'pending' ? now : null,
+  ].filter((value) => value !== null).map((value) => new Date(value).getTime()))
+  const minimum = Math.min(...events.map((event) => new Date(event.createdAt).getTime()))
+  const maximum = Math.max(...times, minimum + 1)
+  const range = maximum - minimum
+  const position = (value) => Math.max(0, Math.min(100, (new Date(value).getTime() - minimum) / range * 100))
+  const markerPosition = (value) => Math.max(.75, Math.min(99.25, position(value)))
+  const lifecycleMarker = (kind, value, title) => {
+    const marker = node('span', 'lifecycle-marker ' + kind)
+    marker.style.left = markerPosition(value) + '%'
+    marker.title = title + ' · ' + formatTime(value)
+    return marker
+  }
+
+  const axis = node('div', 'timeline-axis')
+  axis.append(node('div', 'axis-label', 'Event'))
+  const track = node('div', 'axis-track')
+  for (const percent of [0, 25, 50, 75, 100]) {
+    track.append(node('span', '', formatDuration(range * percent / 100)))
+  }
+  axis.append(track)
+  timeline.append(axis)
+
+  for (const event of events) {
+    const status = eventStatus(event)
+    const start = new Date(event.createdAt).getTime()
+    const end = new Date(event.failedAt || event.processedAt || now).getTime()
+    const left = position(event.createdAt)
+    const width = Math.max((end - start) / range * 100, .45)
+    const row = node('div', 'event-row')
+    const info = node('div', 'event-info')
+    const line = node('div', 'event-line')
+    append(line, node('span', 'event-index', '#' + event.index), node('span', 'event-type', event.type))
+    info.append(line)
+    const sub = node('div', 'event-sub')
+    sub.append(node('span', status === 'failed' ? 'danger' : '', eventStatusLabel(event)))
+    sub.append(node('span', '', event.attemptCount + (event.attemptCount === 1 ? ' dispatch' : ' dispatches')))
+    sub.append(node('span', event.failureCount > 0 ? 'danger' : '', event.failureCount + (event.failureCount === 1 ? ' caught failure' : ' caught failures')))
+    sub.append(node('span', '', 'created ' + formatTime(event.createdAt)))
+    info.append(sub)
+
+    const facts = node('div', 'event-facts')
+    if (event.attemptCount === 0) {
+      facts.append(node('span', '', 'not dispatched'))
+    } else if (!event.firstClaimedAt) {
+      facts.append(node('span', 'warning', 'first dispatch time unknown'))
+    }
+    if (event.attemptCount > 1) {
+      facts.append(node('span', '', (event.attemptCount - 1) + (event.attemptCount === 2 ? ' redispatch' : ' redispatches')))
+    }
+    const outcomeGap = durableOutcomeGap(event)
+    if (outcomeGap > 0) {
+      const hint = node('span', 'warning', outcomeGap + (outcomeGap === 1 ? ' dispatch without outcome' : ' dispatches without outcomes'))
+      hint.title = 'May indicate active work, a hard crash, or a superseded attempt.'
+      facts.append(hint)
+    }
+    if (event.lastFailedAttempt !== null) {
+      facts.append(node('span', 'danger', 'latest failure · attempt ' + event.lastFailedAttempt))
+    }
+    if (event.processedAt) {
+      facts.append(node('span', '', event.processedByAttempt === null ? 'completing attempt not recorded' : 'completed by attempt ' + event.processedByAttempt))
+    }
+    if (facts.childNodes.length > 0) info.append(facts)
+
+    const details = node('details', 'event-details')
+    details.append(node('summary', '', 'payload'))
+    details.append(node('pre', '', JSON.stringify(event.payload, null, 2)))
+    info.append(details)
+    if (event.lastError) {
+      const failure = node('details', 'event-details')
+      failure.append(node('summary', 'danger', 'last error'))
+      failure.append(node('pre', '', event.lastError))
+      info.append(failure)
+    }
+    row.append(info)
+
+    const eventTrack = node('div', 'event-track')
+    const bar = node('span', 'event-bar ' + status)
+    bar.style.left = left + '%'
+    bar.style.width = Math.min(width, 100 - left) + '%'
+    bar.title = eventStatusLabel(event) + ' · ' + formatDuration(end - start)
+    append(eventTrack, bar)
+    eventTrack.append(lifecycleMarker('created', event.createdAt, 'Created'))
+    if (event.firstClaimedAt && event.lastClaimedAt === event.firstClaimedAt) {
+      eventTrack.append(lifecycleMarker('claim', event.firstClaimedAt, 'First and latest dispatch'))
+    } else {
+      if (event.firstClaimedAt) eventTrack.append(lifecycleMarker('claim', event.firstClaimedAt, 'First dispatch'))
+      if (event.lastClaimedAt) eventTrack.append(lifecycleMarker('claim', event.lastClaimedAt, 'Latest dispatch'))
+    }
+    if (event.lastFailedAt) {
+      eventTrack.append(lifecycleMarker('failure', event.lastFailedAt, 'Latest caught failure' + (event.lastFailedAttempt === null ? '' : ' · attempt ' + event.lastFailedAttempt)))
+    }
+    if (event.processedAt) {
+      eventTrack.append(lifecycleMarker('complete', event.processedAt, 'Completed' + (event.processedByAttempt === null ? '' : ' · attempt ' + event.processedByAttempt)))
+    }
+    if (event.failedAt) eventTrack.append(lifecycleMarker('dead-letter', event.failedAt, 'Dead-lettered'))
+    row.append(eventTrack)
+    timeline.append(row)
+  }
+
+  const legend = node('div', 'timeline-legend')
+  for (const [kind, label] of [
+    ['created', 'Created'],
+    ['claim', 'First / latest dispatch'],
+    ['failure', 'Latest caught failure'],
+    ['complete', 'Completion'],
+    ['dead-letter', 'Dead-letter'],
+  ]) {
+    const item = node('span', 'legend-item')
+    append(item, node('i', 'legend-key ' + kind), document.createTextNode(label))
+    legend.append(item)
+  }
+  return append(node('div'), timeline, legend)
+}
+
+const renderMain = () => {
+  const main = node('main', 'main')
+  if (state.error) main.append(node('div', 'error-box', state.error))
+  if (!state.session) {
+    const empty = node('div', 'empty')
+    const copy = node('div')
+    append(copy, node('strong', '', 'No session selected'), node('span', '', 'Choose a durable session to inspect its lifecycle.'))
+    empty.append(copy)
+    main.append(empty)
+    return main
+  }
+  if (!state.detail) {
+    main.append(node('div', 'empty', 'Reading the durable store…'))
+    return main
+  }
+
+  const events = state.detail.events
+  const snapshots = state.detail.snapshots
+  const pending = events.filter((event) => eventStatus(event) === 'pending').length
+  const failed = events.filter((event) => eventStatus(event) === 'failed').length
+  const attempts = events.reduce((total, event) => total + event.attemptCount, 0)
+  const failures = events.reduce((total, event) => total + event.failureCount, 0)
+  const first = new Date(events[0].createdAt).getTime()
+  const lastEvent = events[events.length - 1]
+  const last = new Date(lastEvent.failedAt || lastEvent.processedAt || Date.now()).getTime()
+
+  const header = node('header', 'session-header')
+  const title = node('div', 'session-title')
+  append(title, node('p', 'eyebrow', state.contract + ' / session'), node('h1', '', state.session), node('p', '', 'Read-only · durable data · refreshed by SSE'))
+  const live = node('span', 'live')
+  append(live, node('i'), document.createTextNode('live'))
+  append(header, title, live)
+  main.append(header)
+
+  const cards = node('div', 'cards')
+  append(cards, metric('Events', String(events.length)), metric('Pending', String(pending)), metric('Dispatches', String(attempts)), metric('Caught failures', String(failures)), metric('Lifetime', formatDuration(last - first)))
+  main.append(cards)
+
+  const forestSection = node('section', 'section')
+  const forestHead = node('div', 'section-head')
+  append(forestHead, node('h2', '', 'Causal forest'), node('p', '', 'Unknown origins may be roots or legacy events'))
+  append(forestSection, forestHead, renderCausalForest(events))
+  main.append(forestSection)
+
+  const section = node('section', 'section')
+  const head = node('div', 'section-head')
+  append(head, node('h2', '', 'Event lifecycle'), node('p', '', 'Durable operation boundaries · missing history stays unknown'))
+  append(section, head, renderTimeline(events))
+  main.append(section)
+
+  const snapshotSection = node('section', 'section')
+  const snapshotHead = node('div', 'section-head')
+  append(snapshotHead, node('h2', '', 'Snapshots'), node('p', '', failed ? 'Session is stalled' : snapshots.length ? 'Latest durable reducer frontiers' : 'No cached folds'))
+  snapshotSection.append(snapshotHead)
+  if (snapshots.length) {
+    const grid = node('div', 'snapshots')
+    for (const snapshot of snapshots) {
+      const card = node('div', 'snapshot')
+      card.append(node('strong', '', snapshot.reducerName))
+      const detail = node('div')
+      append(detail, node('span', '', snapshot.updatedAt ? formatRelative(snapshot.updatedAt) : 'time unknown'), node('b', '', '#' + snapshot.index))
+      card.append(detail)
+      grid.append(card)
+    }
+    snapshotSection.append(grid)
+  }
+  main.append(snapshotSection)
+  return main
+}
+
+const render = () => {
+  root.replaceChildren(append(node('div', 'shell'), renderSidebar(), renderMain()))
+}
+
+const restoreFromUrl = async () => {
+  state.watch?.close()
+  const navigation = navigationFromUrl()
+  state.contract = state.contracts.some((contract) => contract.name === navigation.contract)
+    ? navigation.contract
+    : state.contracts[0]?.name || null
+  state.session = navigation.session
+  state.sessions = []
+  state.cursor = null
+  state.detail = null
+  state.error = null
+  render()
+  try {
+    if (state.contract) await loadSessions(true)
+    syncUrl(true)
+    beginWatch()
+  } catch (error) {
+    state.error = error instanceof Error ? error.message : String(error)
+    render()
+  }
+}
+
+window.addEventListener('popstate', () => void restoreFromUrl())
+
+setInterval(() => {
+  if (state.detail?.events.some((event) => eventStatus(event) === 'pending')) render()
+}, 1000)
+
+if (bootstrap) {
+  syncUrl(true)
+  render()
+  beginWatch()
+} else {
+  loadContracts().then(() => beginWatch()).catch((error) => {
+    state.error = error instanceof Error ? error.message : String(error)
+    render()
+  })
+}
+`