api-tracer-kit 1.0.0

package/cli/web/app.js

@@ -0,0 +1,2260 @@
+/* API Tracker UI. Plain DOM, no framework, no build step. */
+
+const $ = (sel, root = document) => root.querySelector(sel);
+const esc = (s) =>
+  String(s ?? '').replace(/[&<>"]/g, (c) => ({ '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;' })[c]);
+
+const state = {
+  endpoints: [],
+  baseUrls: {},
+  auth: {},
+  env: 'dev',
+  results: {}, // id -> { ok, status, ms, error, at }
+  tokensHeld: [],
+  vars: {},
+  samples: {}, // endpoint id -> request captured from real traffic
+  live: { on: false, count: 0, unmatched: [] },
+  contracts: {},
+  locks: { recording: false, env: null },
+  login: { supported: false, fields: [] }, // the sign-in flow the server declares
+  name: 'API',
+  tokenOwner: null,
+  lastRun: null,
+  lastRunOnlyFailed: false,
+  openModule: null,
+  selected: null,
+  drafts: new Map(), // filled from localStorage at boot
+  response: null,
+  tab: 'body',
+  busy: false,
+};
+
+let toastTimer;
+function toast(msg) {
+  const el = $('#toast');
+  el.textContent = msg;
+  el.classList.add('on');
+  clearTimeout(toastTimer);
+  toastTimer = setTimeout(() => el.classList.remove('on'), 3000);
+}
+
+/**
+ * Resolves a request against the page itself, so the console works whether it is
+ * served at / or mounted under a path like /api-console/.
+ *
+ * Credentials are stripped: fetch() refuses a URL containing them, which is what
+ * you get if someone opens the console as https://user:pass@host/api-console/.
+ */
+const REQUEST_BASE = (() => {
+  const base = new URL(document.baseURI);
+  base.username = '';
+  base.password = '';
+  return base.toString();
+})();
+
+const url = (path) => new URL(path.replace(/^\//, ''), REQUEST_BASE).toString();
+
+async function api(path, opts) {
+  const res = await fetch(url(path), opts);
+  const data = await res.json();
+  if (!res.ok) throw new Error(data.error || res.statusText);
+  return data;
+}
+
+const post = (path, body) =>
+  api(path, { method: 'POST', headers: { 'content-type': 'application/json' }, body: JSON.stringify(body) });
+
+/** the two downloads read headers off the response, so they call fetch directly */
+const fetchAt = (path) => fetch(url(path));
+
+/* ------------------------------------------------------------------ drafts */
+
+const DRAFT_KEY = 'api-tracker-drafts';
+
+function loadDrafts() {
+  try {
+    return new Map(Object.entries(JSON.parse(localStorage.getItem(DRAFT_KEY) ?? '{}')));
+  } catch {
+    return new Map(); // private window, cleared storage, or corrupt value
+  }
+}
+
+let saveDraftTimer;
+function saveDrafts() {
+  clearTimeout(saveDraftTimer);
+  saveDraftTimer = setTimeout(() => {
+    try {
+      localStorage.setItem(DRAFT_KEY, JSON.stringify(Object.fromEntries(state.drafts)));
+    } catch {
+      /* storage full or blocked; drafts just stop surviving reloads */
+    }
+  }, 300);
+}
+
+function draftFor(ep) {
+  const sample = state.samples[ep.id];
+  let d = state.drafts.get(ep.id);
+  // a capture newer than your last edit wins: recording the app then opening the
+  // endpoint should show what the app actually sent, not a stale empty draft
+  if (d && !(sample && sample.seenAt > (d.editedAt ?? ''))) return d;
+  if (d && sample) toast(`filled from the call the app just made (${sample.from})`);
+  d = {
+    holes: Object.fromEntries(
+      ep.holes.map((h) => [h.expr, sample?.pathValues?.[h.expr] ?? '']),
+    ),
+    params: JSON.stringify(sample?.params ?? {}, null, 2),
+    rawQuery: '',
+    paramsMode: 'json', // 'json' | 'raw' | 'stringified'
+    stringifyKey: 'params',
+    data: JSON.stringify(sample?.data ?? {}, null, 2),
+    // the app's own encoding wins; otherwise assume JSON for methods that carry a body
+    bodyType:
+      sample?.bodyType ??
+      (['POST', 'PUT', 'PATCH', 'DELETE'].includes(ep.method) ? 'json' : 'none'),
+    headers: d?.headers ?? [],
+    tab: d?.tab ?? (['POST', 'PUT', 'PATCH', 'DELETE'].includes(ep.method) ? 'body' : 'params'),
+    capture: d?.capture ?? [], // capture rules are yours; keep them across refills
+    editedAt: '',
+  };
+  state.drafts.set(ep.id, d);
+  return d;
+}
+
+/** call after any draft edit so a reload does not lose typed ids and payloads */
+function touchDraft(d) {
+  if (d) d.editedAt = new Date().toISOString();
+  saveDrafts();
+}
+
+/** axios-style params -> query string; same rules as the server */
+function toQueryString(params, prefix = '') {
+  const out = [];
+  const enc = encodeURIComponent;
+  for (const [rawKey, v] of Object.entries(params)) {
+    const key = prefix ? `${prefix}[${rawKey}]` : rawKey;
+    if (v === undefined || v === null || v === '') continue;
+    if (Array.isArray(v)) {
+      for (const item of v) {
+        if (item !== null && typeof item === 'object') out.push(toQueryString(item, `${key}[]`));
+        else out.push(`${enc(`${key}[]`)}=${enc(item)}`);
+      }
+    } else if (typeof v === 'object') {
+      out.push(toQueryString(v, key));
+    } else {
+      out.push(`${enc(key)}=${enc(v)}`);
+    }
+  }
+  return out.filter(Boolean).join('&');
+}
+
+/** `a=1&b[]=2` -> { a: '1', b: ['2'] }, enough to round-trip back to the JSON editor */
+function fromQueryString(raw) {
+  const out = {};
+  for (const [k, v] of new URLSearchParams(raw.trim().replace(/^[?&]+/, ''))) {
+    if (k.endsWith('[]')) {
+      const key = k.slice(0, -2);
+      (out[key] ??= []).push(v);
+    } else {
+      out[k] = v;
+    }
+  }
+  return out;
+}
+
+const bodyLabel = (t) =>
+  ({ json: 'application/json', formdata: 'multipart/form-data', urlencoded: 'application/x-www-form-urlencoded', none: 'no body' })[t] ?? t;
+
+/** how many query params are actually going out, for the tab counter */
+function countParams(d) {
+  if (d.paramsMode === 'raw') {
+    return d.rawQuery.trim().replace(/^[?&]+/, '') ? new URLSearchParams(d.rawQuery.trim().replace(/^[?&]+/, '')).size : 0;
+  }
+  try {
+    return Object.keys(JSON.parse(d.params || '{}')).length;
+  } catch {
+    return 0;
+  }
+}
+
+/** the JSON body as editable key/value rows, the way form-data is really shaped */
+function bodyRows(d) {
+  try {
+    return Object.entries(JSON.parse(d.data || '{}')).map(([k, v]) => ({
+      k,
+      v: typeof v === 'object' && v !== null ? JSON.stringify(v) : String(v),
+      on: true,
+    }));
+  } catch {
+    return [];
+  }
+}
+
+/** Postman-style key/value table */
+function kvRows(rows, kind) {
+  return `<table class="kv">${rows
+    .map(
+      (r, i) => `<tr>
+        <td class="x"><input type="checkbox" data-kv-on="${kind}:${i}" ${r.on ? 'checked' : ''} /></td>
+        <td class="k"><input data-kv-k="${kind}:${i}" value="${esc(r.k)}" placeholder="key" /></td>
+        <td><input data-kv-v="${kind}:${i}" value="${esc(r.v)}" placeholder="value" /></td>
+        <td class="x"><button class="link" data-kv-del="${kind}:${i}">&times;</button></td>
+      </tr>`,
+    )
+    .join('')}</table>`;
+}
+
+/** mirrors the server's URL builder so the preview matches what will be sent */
+function previewUrl(ep, d) {
+  let path = ep.subUrl;
+  for (const h of ep.holes) path = path.replaceAll(`\${${h.expr}}`, d.holes[h.expr] || `:${h.label}`);
+  const base = ep.absolute || /^https?:\/\//.test(path) ? '' : state.baseUrls[state.env] ?? '';
+  let qs = '';
+  if (d.paramsMode === 'raw') {
+    qs = d.rawQuery.trim().replace(/^[?&]+/, '');
+  } else {
+    try {
+      const parsed = JSON.parse(d.params || '{}');
+      qs =
+        d.paramsMode === 'stringified'
+          ? `${encodeURIComponent(d.stringifyKey)}=${encodeURIComponent(JSON.stringify(parsed))}`
+          : toQueryString(parsed);
+    } catch {
+      /* invalid JSON is reported by the editor itself */
+    }
+  }
+  return `${base}${path}${qs ? `?${qs}` : ''}`;
+}
+
+/* ---------------------------------------------------------- code colouring */
+
+/**
+ * JSON -> highlighted HTML, VS Code Dark+ colours.
+ *
+ * Deliberately tolerant: this runs on every keystroke, including while the JSON
+ * is half-typed and invalid, so it tokenises rather than parses.
+ */
+function highlightJson(text) {
+  const token =
+    /("(?:\\.|[^"\\])*")(\s*:)?|\b(true|false|null)\b|(-?\d+(?:\.\d+)?(?:[eE][+-]?\d+)?)/g;
+
+  let out = '';
+  let last = 0;
+  let m;
+  while ((m = token.exec(text))) {
+    out += esc(text.slice(last, m.index)); // punctuation and whitespace
+    const [whole, str, colon, literal, number] = m;
+    if (str) {
+      // a string followed by a colon is a property name, and reads differently
+      out += colon
+        ? `<span class="t-key">${esc(str)}</span>${esc(colon)}`
+        : `<span class="t-str">${esc(str)}</span>`;
+    } else if (literal) {
+      out += `<span class="t-lit">${esc(literal)}</span>`;
+    } else {
+      out += `<span class="t-num">${esc(number)}</span>`;
+    }
+    last = m.index + whole.length;
+  }
+  return `${out + esc(text.slice(last))}\n`; // trailing newline keeps the last line visible
+}
+
+/** a textarea with a highlighted layer behind it, kept in sync */
+function codeEditor(id, value, { placeholder = '', rows = 12 } = {}) {
+  return `<div class="code-edit">
+    <div class="gutter" data-gutter-for="${id}"></div>
+    <pre class="hl" data-hl-for="${id}" aria-hidden="true"></pre>
+    <textarea id="${id}" spellcheck="false" wrap="off" rows="${rows}"
+      placeholder="${esc(placeholder)}">${esc(value)}</textarea>
+  </div>`;
+}
+
+/** paints the highlight layer and line numbers for one editor */
+function paintEditor(ta) {
+  const hl = $(`[data-hl-for="${ta.id}"]`);
+  const gutter = $(`[data-gutter-for="${ta.id}"]`);
+  if (hl) hl.innerHTML = highlightJson(ta.value);
+  if (gutter) {
+    const lines = ta.value.split('\n').length;
+    gutter.innerHTML = Array.from({ length: lines }, (_, i) => i + 1).join('<br />');
+  }
+}
+
+/** the layers only line up while they scroll together */
+function syncEditorScroll(ta) {
+  const hl = $(`[data-hl-for="${ta.id}"]`);
+  const gutter = $(`[data-gutter-for="${ta.id}"]`);
+  if (hl) {
+    hl.scrollTop = ta.scrollTop;
+    hl.scrollLeft = ta.scrollLeft;
+  }
+  if (gutter) gutter.scrollTop = ta.scrollTop;
+}
+
+function wireEditor(ta) {
+  if (!ta) return;
+  paintEditor(ta);
+  ta.addEventListener('scroll', () => syncEditorScroll(ta));
+  ta.addEventListener('input', () => {
+    paintEditor(ta);
+    syncEditorScroll(ta);
+  });
+  // Tab should indent, not jump out of the editor
+  ta.addEventListener('keydown', (e) => {
+    if (e.key !== 'Tab' || e.shiftKey) return;
+    e.preventDefault();
+    const { selectionStart: a, selectionEnd: b } = ta;
+    ta.value = `${ta.value.slice(0, a)}  ${ta.value.slice(b)}`;
+    ta.selectionStart = ta.selectionEnd = a + 2;
+    ta.dispatchEvent(new Event('input'));
+  });
+}
+
+/* -------------------------------------------------------------------- tree */
+
+function matching() {
+  const q = $('#search').value.trim().toLowerCase();
+  const method = $('#filter-method').value;
+  const status = $('#filter-status').value;
+
+  return state.endpoints.filter((e) => {
+    if (method && e.method !== method) return false;
+    const r = state.results[e.id];
+    if (status === 'pass' && !r?.ok) return false;
+    if (status === 'fail' && (!r || r.ok)) return false;
+    if (status === 'untested' && r) return false;
+    if (status === 'regressed' && !(r && !r.ok && r.wasOk)) return false;
+    if (status === 'unused' && e.usedIn !== 0) return false;
+    if (status === 'drift' && !r?.drift) return false;
+    if (status === 'captured' && !state.samples[e.id]) return false;
+    if (status === 'uncaptured' && state.samples[e.id]) return false;
+    if (status === 'uncatalogued' && !e.uncatalogued) return false;
+    if (!q) return true;
+    return `${e.name} ${e.subUrl} ${e.module}`.toLowerCase().includes(q);
+  });
+}
+
+function groupByModule(list) {
+  const map = new Map();
+  for (const e of list) {
+    if (!map.has(e.module)) map.set(e.module, []);
+    map.get(e.module).push(e);
+  }
+  // keep the adopted-from-traffic bucket at the bottom, out of the alphabet
+  return [...map.entries()].sort((a, b) => {
+    const rank = (n) => (n === '(uncatalogued)' ? 1 : 0);
+    return rank(a[0]) - rank(b[0]) || a[0].localeCompare(b[0]);
+  });
+}
+
+function statusDot(id) {
+  const r = state.results[id];
+  if (!r) return '<span class="dot"></span>';
+  // broke since the last run: worth spotting without reading the whole list
+  if (r.ok && r.drift) {
+    return `<span class="dot drift" title="passing, but the response shape changed: ${esc(
+      r.drift.summary,
+    )}"></span>`;
+  }
+  const cls = r.ok ? 'pass' : r.wasOk ? 'fail regressed' : 'fail';
+  const title = r.ok
+    ? 'passing'
+    : r.failedInReplay
+      ? 'failed when replayed'
+      : r.wasOk
+        ? 'was passing, now failing'
+        : 'failing';
+  return `<span class="dot ${cls}" title="${title}"></span>`;
+}
+
+function renderTree() {
+  const groups = groupByModule(matching());
+
+  $('#tree').innerHTML =
+    groups
+      .map(([name, eps]) => {
+        const open = state.openModule === name;
+        const failed = eps.filter((e) => state.results[e.id] && !state.results[e.id].ok).length;
+        const passed = eps.filter((e) => state.results[e.id]?.ok).length;
+        const rows = open
+          ? eps
+              .map(
+                (e) => `<button class="endpoint ${state.selected === e.id ? 'active' : ''}"
+                  data-id="${esc(e.id)}" title="${esc(e.method)} ${esc(e.subUrl)}">
+                  ${statusDot(e.id)}
+                  <span class="method m-${esc(e.method)}">${esc(e.method)}</span>
+                  <span class="nm">${esc(e.name)}</span>
+                  ${state.samples[e.id] ? '<span class="tick" title="sample from real traffic">&#9679;</span>' : ''}
+                </button>`,
+              )
+              .join('')
+          : '';
+        const caught = eps.filter((e) => state.samples[e.id]).length;
+        const tally = failed
+          ? `<span class="n fail">${failed} failing</span>`
+          : passed
+            ? `<span class="n pass">${passed}/${eps.length}</span>`
+            : caught
+              ? `<span class="n pass">${caught}/${eps.length} seen</span>`
+              : `<span class="n">${eps.length}</span>`;
+        return `<button class="module ${open ? 'active' : ''} ${
+          name === '(uncatalogued)' ? 'odd' : ''
+        }" data-module="${esc(name)}"
+          aria-expanded="${open}">${open ? '&#9662;' : '&#9656;'} ${esc(name)}${tally}</button>${rows}`;
+      })
+      .join('') || '<p class="muted" style="padding:14px">nothing matches</p>';
+
+  renderHealth();
+}
+
+function renderHealth() {
+  const total = state.endpoints.length;
+  const run = Object.keys(state.results).length;
+  const pass = Object.values(state.results).filter((r) => r.ok).length;
+  const fail = run - pass;
+
+  $('#health').innerHTML = run
+    ? `<div class="bar" title="${pass} passing, ${fail} failing, ${total - run} not run">
+        <i class="p" style="width:${(pass / total) * 100}%"></i>
+        <i class="f" style="width:${(fail / total) * 100}%"></i>
+      </div>
+      <span><b class="pass">${pass}</b> pass &middot; <b class="fail">${fail}</b> fail &middot;
+        <span class="muted">${total - run} not run</span></span>`
+    : `<span class="muted">${total} endpoints, none run yet</span>`;
+}
+
+/**
+ * The last replay, kept on the home page so closing the dialog or opening one of
+ * the endpoints does not lose the results.
+ */
+function lastRunPanel() {
+  const run = state.lastRun;
+  if (!run?.finished?.length) return '';
+
+  const rows = state.lastRunOnlyFailed ? run.finished.filter((r) => !r.ok) : run.finished;
+  const when = run.startedAt ? new Date(run.startedAt).toLocaleString() : '';
+
+  return `
+    <div class="lastrun">
+      <div class="lastrun-head">
+        <b>Last replay</b>
+        <span class="pass">${run.passed} passed</span>
+        <span class="fail">${run.failed} failed</span>
+        ${run.cancelled ? '<span class="badge warn">stopped early</span>' : ''}
+        <span class="muted">${esc(when)}</span>
+        <span class="spacer"></span>
+        ${
+          run.failed
+            ? `<button class="link" id="lastrun-filter">${
+                state.lastRunOnlyFailed ? 'show all' : 'only failed'
+              }</button>`
+            : ''
+        }
+        <button class="link" id="lastrun-again">replay again</button>
+      </div>
+      ${ranList(rows)}
+    </div>`;
+}
+
+/**
+ * How much of the API the app has actually exercised. An endpoint nobody has
+ * triggered has never been proven either way, which is different from failing.
+ */
+function coveragePanel() {
+  const scanned = state.endpoints.filter((e) => !e.uncatalogued);
+  const extra = state.endpoints.filter((e) => e.uncatalogued);
+  const total = scanned.length;
+  const seen = scanned.filter((e) => state.samples[e.id]).length;
+  const drifted = Object.values(state.results).filter((r) => r.drift).length;
+  if (!seen) {
+    return `<p class="muted">Nothing captured yet. Turn on <b>Live</b> and use the app, or import
+      a HAR.</p>`;
+  }
+
+  const byModule = new Map();
+  for (const e of scanned) {
+    const m = byModule.get(e.module) ?? { total: 0, seen: 0 };
+    m.total++;
+    if (state.samples[e.id]) m.seen++;
+    byModule.set(e.module, m);
+  }
+  const untouched = [...byModule.entries()].filter(([, m]) => !m.seen);
+
+  return `
+    <div class="coverage">
+      <div class="bar" style="width:220px">
+        <i class="p" style="width:${(seen / total) * 100}%"></i>
+      </div>
+      <p><b>${seen}</b> of ${total} endpoints exercised
+        (${Math.round((seen / total) * 100)}%)${
+          drifted ? ` &middot; <b class="warn">${drifted}</b> with a changed response shape` : ''
+        }</p>
+      ${
+        extra.length
+          ? `<p class="muted"><b class="warn">${extra.length}</b> call${
+              extra.length === 1 ? '' : 's'
+            } recorded that no service file explains &mdash;
+             <button class="link" id="show-uncatalogued">show them</button></p>`
+          : ''
+      }
+      <p class="muted">
+        ${untouched.length
+          ? `${untouched.length} module${untouched.length === 1 ? '' : 's'} untouched:
+             ${untouched.slice(0, 8).map(([n]) => esc(n)).join(', ')}${
+               untouched.length > 8 ? `, and ${untouched.length - 8} more` : ''
+             }`
+          : 'every module has at least one captured call'}
+      </p>
+      <p><button class="link" id="show-uncaptured">show what is still uncaptured</button>
+         ${drifted ? '<button class="link" id="show-drift">show contract drift</button>' : ''}</p>
+    </div>`;
+}
+
+/* ---------------------------------------------------------------- overview */
+
+function renderModule(name) {
+  const eps = state.endpoints.filter((e) => e.module === name);
+  const shown = matching().filter((e) => e.module === name);
+  const captured = eps.filter((e) => state.samples[e.id]).length;
+
+  $('#panel').innerHTML = `
+    ${crumbs(name)}
+    <h1>${esc(name)}</h1>
+    <div class="sub">
+      <span>${eps.length} endpoints</span>
+      <span class="badge ${captured ? 'pass' : ''}">${captured} captured</span>
+      ${
+        name === '(uncatalogued)'
+          ? '<span class="badge warn">seen in traffic, not in the source</span>'
+          : `<span class="badge">${esc(name)}</span>`
+      }
+      <span class="spacer"></span>
+      <button class="primary" id="run-module">Run all GETs in this module</button>
+      <button id="export-har" ${captured ? '' : 'disabled'}
+        title="${captured ? `${captured} captured request(s)` : 'nothing captured in this module yet'}">
+        Export HAR</button>
+      <button id="export-curl" ${captured ? '' : 'disabled'}>Export cURL</button>
+      <button id="export-postman" ${captured ? '' : 'disabled'}>Export Postman</button>
+    </div>
+    ${
+      name === '(uncatalogued)'
+        ? `<p class="muted" style="margin-top:-6px">
+             Your app called these, but nothing in the scanned source builds them. Either
+             the call is made outside the services layer, or the scanner and the code disagree about
+             a URL &mdash; often a stale path left commented in the service file.
+             <button class="link" id="forget-uncatalogued">forget these</button>
+           </p>`
+        : ''
+    }
+    <p class="muted" style="margin-top:-6px">
+      Bulk runs only fire GETs, with every path placeholder left blank &mdash; enough to prove the
+      endpoint answers, not to exercise it properly. POST/PUT/PATCH/DELETE are never run in bulk
+      because they change real data; open one and send it deliberately.
+    </p>
+    <table class="list">
+      <thead><tr><th></th><th>method</th><th>function</th><th>path</th><th>last run</th></tr></thead>
+      <tbody>
+        ${shown
+          .map((e) => {
+            const r = state.results[e.id];
+            return `<tr data-id="${esc(e.id)}">
+              <td>${statusDot(e.id)}</td>
+              <td class="method m-${esc(e.method)}">${esc(e.method)}</td>
+              <td>${esc(e.name)}</td>
+              <td class="path">${esc(e.subUrl)}${
+                e.usedIn === 0 ? ' <span class="badge warn">unused</span>' : ''
+              }</td>
+              <td class="${r ? (r.ok ? 'pass' : 'fail') : 'muted'}">
+                ${r ? esc(r.error ?? `${r.status}${r.innerCode ? ` (body ${r.innerCode})` : ''} in ${r.ms}ms`) : '&mdash;'}
+                ${r?.failedInReplay ? '<span class="badge fail">failed when replayed</span>' : ''}
+              </td>
+            </tr>`;
+          })
+          .join('')}
+      </tbody>
+    </table>`;
+
+  wireCrumbs();
+  $('#run-module').onclick = () => runBatch(eps.map((e) => e.id), `module ${name}`);
+  const forget = $('#forget-uncatalogued');
+  if (forget) {
+    forget.onclick = async () => {
+      await api('/api/uncatalogued', { method: 'DELETE' });
+      await load();
+      toast('uncatalogued endpoints cleared');
+    };
+  }
+  $('#export-har').onclick = () => download(name, 'har');
+  $('#export-curl').onclick = () => download(name, 'curl');
+  $('#export-postman').onclick = () => download(name, 'postman');
+  $('#panel').querySelector('tbody').onclick = (e) => {
+    const tr = e.target.closest('tr');
+    if (tr) select(tr.dataset.id);
+  };
+}
+
+/* ------------------------------------------------------------------ detail */
+
+function renderDetail() {
+  const ep = state.endpoints.find((e) => e.id === state.selected);
+  if (!ep) return;
+  const d = draftFor(ep);
+  const r = state.results[ep.id];
+  const sample = state.samples[ep.id];
+  // what the app actually sent beats what the scanner inferred
+  const showParams = ep.usesParams || Object.keys(sample?.params ?? {}).length > 0;
+  const sendsBody =
+    ['POST', 'PUT', 'PATCH', 'DELETE'].includes(ep.method) ||
+    Object.keys(sample?.data ?? {}).length > 0;
+
+  $('#panel').innerHTML = `
+    ${crumbs(ep.module, ep.name)}
+    <h1><span class="method m-${esc(ep.method)}">${esc(ep.method)}</span> ${esc(ep.name)}</h1>
+    <div class="sub">
+      <span class="badge">${esc(ep.module)}</span>
+      <span>${esc(ep.file)}:${ep.line}</span>
+      ${r ? `<span class="badge ${r.ok ? 'pass' : 'fail'}">${r.ok ? 'passing' : 'failing'}</span>` : ''}
+      ${ep.absolute ? '<span class="badge warn">third-party URL, token not sent</span>' : ''}
+      ${
+        ep.customToken === 'ACCESS_TOKEN'
+          ? '<span class="badge">ACCESS_TOKEN signed per call</span>'
+          : ep.customToken
+            ? `<span class="badge warn">uses ${esc(ep.customToken)}</span>`
+            : ''
+      }
+      ${ep.dynamicUrl ? '<span class="badge warn">URL supplied by caller</span>' : ''}
+      ${
+        ep.uncatalogued
+          ? '<span class="badge warn" title="the app called this, but nothing in the scanned source builds it">not in the source</span>'
+          : ''
+      }
+      ${
+        ep.uncatalogued
+          ? ''
+          : ep.usedIn === 0
+            ? '<span class="badge warn" title="nothing outside its own service file references this function">unused in app</span>'
+            : `<span class="badge">used in ${ep.usedIn} file${ep.usedIn === 1 ? '' : 's'}</span>`
+      }
+      ${r?.failedInReplay ? '<span class="badge fail">failed when replayed</span>' : ''}
+      ${r && !r.ok && r.wasOk ? '<span class="badge fail">broke since last run</span>' : ''}
+      ${
+        state.samples[ep.id]
+          ? `<span class="badge pass" title="${esc(state.samples[ep.id].from)}">from real traffic</span>`
+          : ''
+      }
+      ${
+        state.samples[ep.id]?.bodyType && state.samples[ep.id].bodyType !== 'json'
+          ? `<span class="badge warn">${esc(state.samples[ep.id].bodyType)}</span>`
+          : ''
+      }
+    </div>
+
+    ${
+      r?.drift
+        ? `<div class="drift-box">
+             <b class="warn">Response shape changed</b> since the baseline recorded
+             ${state.contracts[ep.id] ? new Date(state.contracts[ep.id].at).toLocaleString() : ''}.
+             <div class="mono" style="margin:6px 0">${esc(r.drift.summary)}</div>
+             <button class="link" id="accept-contract">This change is expected, make it the baseline</button>
+           </div>`
+        : ''
+    }
+
+    <div class="urlbar">
+      <span class="method m-${esc(ep.method)}">${esc(ep.method)}</span>
+      <span class="mono" id="url-preview"></span>
+    </div>
+
+    ${
+      sample
+        ? `<p class="muted" style="margin:-4px 0 12px">
+             Filled from the call your app made ${
+               sample.live ? 'live' : 'in the imported traffic'
+             } &mdash; <span class="mono">${esc(sample.from)}</span>${
+               sample.status ? `, answered ${sample.status}` : ''
+             }, ${new Date(sample.seenAt).toLocaleString()}.
+             ${
+               sample.bodyType && sample.bodyType !== 'json'
+                 ? `<br />Your app sent this as
+                    <b>${sample.bodyType === 'formdata' ? 'multipart/form-data' : 'form-urlencoded'}</b>,
+                    so Send replays it that way. Edit the fields below as normal.`
+                 : ''
+             }
+           </p>`
+        : ''
+    }
+
+    ${
+      ep.holes.length
+        ? `<fieldset><legend>path values</legend><div class="holes">
+        ${ep.holes
+          .map(
+            (h) => `<label>${esc(h.expr)}
+            <input data-hole="${esc(h.expr)}" value="${esc(d.holes[h.expr] ?? '')}"
+              placeholder="${esc(h.label)}" /></label>`,
+          )
+          .join('')}
+      </div></fieldset>`
+        : ''
+    }
+
+    <div class="reqtabs">
+      ${[
+        ['params', `Params${countParams(d) ? ` <b>${countParams(d)}</b>` : ''}`],
+        ['headers', `Headers${d.headers.filter((h) => h.on && h.k).length ? ` <b>${d.headers.filter((h) => h.on && h.k).length}</b>` : ''}`],
+        ['body', `Body${d.bodyType !== 'none' ? ' <i class="dotmark"></i>' : ''}`],
+        ['capture', `Capture${(d.capture ?? []).filter((c) => c.name).length ? ` <b>${d.capture.filter((c) => c.name).length}</b>` : ''}`],
+      ]
+        .map(
+          ([key, label]) =>
+            `<button data-reqtab="${key}" class="${d.tab === key ? 'on' : ''}">${label}</button>`,
+        )
+        .join('')}
+      <span class="spacer"></span>
+      <span class="muted">${esc(bodyLabel(d.bodyType))}</span>
+    </div>
+
+    <div class="reqpane">
+    ${
+      d.tab === 'params'
+        ? `<div class="editor-bar">
+          <div class="tabs">
+            <button data-pmode="json" class="${d.paramsMode === 'json' ? 'on' : ''}">JSON</button>
+            <button data-pmode="stringified" class="${d.paramsMode === 'stringified' ? 'on' : ''}"
+              title="whole object as one encoded JSON param">stringified</button>
+            <button data-pmode="raw" class="${d.paramsMode === 'raw' ? 'on' : ''}">query string</button>
+          </div>
+          ${
+            d.paramsMode === 'stringified'
+              ? `<label class="inline">key <input id="f-stringify-key" size="8"
+                   value="${esc(d.stringifyKey)}" /></label>`
+              : ''
+          }
+          ${d.paramsMode !== 'raw' ? '<button class="link" data-fmt="params">format</button>' : ''}
+          <span class="err" id="err-params"></span>
+        </div>
+        ${
+          d.paramsMode === 'raw'
+            ? `<textarea id="f-rawquery" spellcheck="false" placeholder="page=1&per_page=20&ids[]=3"
+                 style="min-height:64px">${esc(d.rawQuery)}</textarea>
+               <p class="muted" style="margin:6px 0 0">Sent exactly as typed &mdash; nothing is
+                 re-encoded.</p>`
+            : `${codeEditor('f-params', d.params, { rows: 9 })}
+               ${
+                 d.paramsMode === 'stringified'
+                   ? `<p class="muted" style="margin:6px 0 0">Sent as
+                      <code>?${esc(d.stringifyKey)}=</code> plus
+                      <code>encodeURIComponent(JSON.stringify(params))</code>.</p>`
+                   : ''
+               }`
+        }`
+        : ''
+    }
+
+    ${
+      d.tab === 'headers'
+        ? `${kvRows(d.headers, 'hdr')}
+           <button class="link" data-kv-add="hdr">+ add</button>
+           <p class="muted" style="margin:6px 0 0">
+             <code>${esc(state.auth.header)}</code> and <code>Content-Type</code> are added by the
+             server on send. Anything here is merged on top.
+           </p>`
+        : ''
+    }
+
+    ${
+      d.tab === 'body'
+        ? `<div class="editor-bar bodytypes">
+             ${[
+               ['none', 'none'],
+               ['json', 'JSON'],
+               ['formdata', 'multipart/form-data'],
+               ['urlencoded', 'x-www-form-urlencoded'],
+             ]
+               .map(
+                 ([key, label]) => `<label class="radio ${d.bodyType === key ? 'on' : ''}">
+                   <input type="radio" name="bodytype" value="${key}"
+                     ${d.bodyType === key ? 'checked' : ''} /> ${label}</label>`,
+               )
+               .join('')}
+             ${d.bodyType === 'json' ? '<button class="link" data-fmt="data">format</button>' : ''}
+             <span class="err" id="err-data"></span>
+           </div>
+           ${
+             d.bodyType === 'none'
+               ? '<p class="muted">No body is sent.</p>'
+               : d.bodyType === 'json'
+                 ? codeEditor('f-data', d.data, { rows: 14 })
+                 : `${kvRows(bodyRows(d), 'body')}
+                    <button class="link" data-kv-add="body">+ add</button>
+                    <p class="muted" style="margin:6px 0 0">
+                      Sent as ${esc(bodyLabel(d.bodyType))}, field by field &mdash; the same way your
+                      app sent it.
+                    </p>`
+           }`
+        : ''
+    }
+
+    ${
+      d.tab === 'capture'
+        ? `<div id="capture-rows">
+        ${(d.capture ?? [])
+          .map(
+            (c, i) => `<div class="row" data-cap="${i}">
+              <input data-cap-name="${i}" value="${esc(c.name)}" placeholder="variable name" size="14" />
+              <span class="muted">=</span>
+              <input data-cap-path="${i}" value="${esc(c.path)}" placeholder="data.0.id" />
+              <button class="link" data-cap-del="${i}">&times;</button>
+            </div>`,
+          )
+          .join('')}
+      </div>
+      <button class="link" id="cap-add">+ add</button>
+      <p class="muted" style="margin:6px 0 0">
+        After a passing response, the value at that path is stored as <code>{{name}}</code> for later
+        calls. Dotted paths walk arrays: <code>data.0.id</code>.
+      </p>`
+        : ''
+    }
+    </div>
+
+    <div class="row">
+      <button class="primary" id="send">Send</button>
+      ${sendsBody ? '<span class="muted">this writes to the real API on the selected environment</span>' : ''}
+      <span class="spacer"></span>
+      ${state.samples[ep.id] ? '<button id="reset-sample">Reset to captured</button>' : ''}
+      <button id="copy-curl">Copy as cURL</button>
+    </div>
+
+    <div id="response"></div>`;
+
+  wireCrumbs();
+  for (const el of document.querySelectorAll('[data-hole]')) {
+    el.oninput = () => {
+      d.holes[el.dataset.hole] = el.value;
+      touchDraft(d);
+      updatePreview(ep, d);
+    };
+  }
+  for (const which of ['params', 'data']) {
+    const ta = $(`#f-${which}`);
+    if (!ta) continue;
+    // fromUser: rendering the pane must not mark the draft as edited, or a live
+    // refill would think it is about to overwrite your work
+    const validate = (fromUser) => {
+      d[which] = ta.value;
+      if (fromUser) touchDraft(d);
+      const err = $(`#err-${which}`);
+      try {
+        JSON.parse(ta.value || '{}');
+        ta.classList.remove('invalid');
+        err.textContent = '';
+      } catch (e) {
+        ta.classList.add('invalid');
+        err.textContent = e.message;
+      }
+      if (which === 'params') updatePreview(ep, d);
+    };
+    ta.oninput = () => validate(true);
+    validate(false);
+    wireEditor(ta);
+  }
+  const rawTa = $('#f-rawquery');
+  if (rawTa) {
+    rawTa.oninput = () => {
+      d.rawQuery = rawTa.value;
+      touchDraft(d);
+      updatePreview(ep, d);
+    };
+  }
+  const keyIn = $('#f-stringify-key');
+  if (keyIn) {
+    keyIn.oninput = () => {
+      d.stringifyKey = keyIn.value;
+      touchDraft(d);
+      updatePreview(ep, d);
+    };
+  }
+  for (const btn of document.querySelectorAll('[data-pmode]')) {
+    btn.onclick = () => {
+      const next = btn.dataset.pmode;
+      if (next === d.paramsMode) return;
+      // json and stringified share the same editor, so only raw needs converting
+      if (next !== 'raw' && d.paramsMode !== 'raw') {
+        d.paramsMode = next;
+        touchDraft(d);
+        renderDetail();
+        return;
+      }
+      // carry what is already typed across, so switching never loses work
+      if (next === 'raw') {
+        try {
+          d.rawQuery = toQueryString(JSON.parse(d.params || '{}'));
+        } catch {
+          toast('params are not valid JSON, starting the query string empty');
+          d.rawQuery = '';
+        }
+      } else {
+        d.params = JSON.stringify(fromQueryString(d.rawQuery), null, 2);
+      }
+      d.paramsMode = next;
+      touchDraft(d);
+      renderDetail();
+    };
+  }
+  for (const btn of document.querySelectorAll('[data-fmt]')) {
+    btn.onclick = () => {
+      const ta = $(`#f-${btn.dataset.fmt}`);
+      try {
+        ta.value = JSON.stringify(JSON.parse(ta.value || '{}'), null, 2);
+        ta.dispatchEvent(new Event('input'));
+      } catch {
+        toast('not valid JSON, cannot format');
+      }
+    };
+  }
+
+  for (const btn of document.querySelectorAll('[data-reqtab]')) {
+    btn.onclick = () => {
+      d.tab = btn.dataset.reqtab;
+      touchDraft(d);
+      renderDetail();
+    };
+  }
+
+  for (const radio of document.querySelectorAll('input[name="bodytype"]')) {
+    radio.onchange = () => {
+      d.bodyType = radio.value;
+      touchDraft(d);
+      renderDetail();
+    };
+  }
+
+  // key/value tables: headers, and the body when it is form-data or urlencoded
+  const rowsFor = (kind) => (kind === 'hdr' ? d.headers : bodyRows(d));
+  const writeBack = (kind, rows) => {
+    if (kind === 'hdr') {
+      d.headers = rows;
+    } else {
+      d.data = JSON.stringify(
+        Object.fromEntries(rows.filter((r) => r.on && r.k).map((r) => [r.k, r.v])),
+        null,
+        2,
+      );
+    }
+    touchDraft(d);
+  };
+
+  for (const el of document.querySelectorAll('[data-kv-k], [data-kv-v], [data-kv-on]')) {
+    const [kind, idx] = (el.dataset.kvK ?? el.dataset.kvV ?? el.dataset.kvOn).split(':');
+    const i = Number(idx);
+    const field = el.dataset.kvK !== undefined ? 'k' : el.dataset.kvV !== undefined ? 'v' : 'on';
+    const handler = () => {
+      const rows = rowsFor(kind);
+      rows[i][field] = field === 'on' ? el.checked : el.value;
+      writeBack(kind, rows);
+      // a body row rename would rebuild the table under the cursor, so only redraw on toggle
+      if (field === 'on') renderDetail();
+    };
+    if (field === 'on') el.onchange = handler;
+    else el.oninput = handler;
+  }
+  for (const el of document.querySelectorAll('[data-kv-del]')) {
+    el.onclick = () => {
+      const [kind, idx] = el.dataset.kvDel.split(':');
+      const rows = rowsFor(kind);
+      rows.splice(Number(idx), 1);
+      writeBack(kind, rows);
+      renderDetail();
+    };
+  }
+  for (const el of document.querySelectorAll('[data-kv-add]')) {
+    el.onclick = () => {
+      const kind = el.dataset.kvAdd;
+      const rows = [...rowsFor(kind), { k: '', v: '', on: true }];
+      if (kind === 'hdr') d.headers = rows;
+      else {
+        // an empty key would vanish on write-back, so keep the row in the JSON
+        const obj = rows.filter((r) => r.k).reduce((a, r) => ({ ...a, [r.k]: r.v }), {});
+        obj[''] = '';
+        d.data = JSON.stringify(obj, null, 2);
+      }
+      touchDraft(d);
+      renderDetail();
+    };
+  }
+
+  const capAdd = $('#cap-add');
+  if (capAdd) {
+    capAdd.onclick = () => {
+      d.capture = [...(d.capture ?? []), { name: '', path: '' }];
+      touchDraft(d);
+      renderDetail();
+    };
+  }
+  for (const el of document.querySelectorAll('[data-cap-name], [data-cap-path]')) {
+    el.oninput = () => {
+      const i = Number(el.dataset.capName ?? el.dataset.capPath);
+      d.capture[i][el.dataset.capName !== undefined ? 'name' : 'path'] = el.value;
+      touchDraft(d);
+    };
+  }
+  for (const el of document.querySelectorAll('[data-cap-del]')) {
+    el.onclick = () => {
+      d.capture.splice(Number(el.dataset.capDel), 1);
+      touchDraft(d);
+      renderDetail();
+    };
+  }
+
+  const acceptBtn = $('#accept-contract');
+  if (acceptBtn) {
+    acceptBtn.onclick = async () => {
+      try {
+        // the server kept the drifted shape, so nothing needs computing here
+        const out = await post('/api/contracts', { id: ep.id });
+        state.contracts = out.contracts;
+        state.results = out.results;
+        renderTree();
+        renderDetail();
+        toast('baseline updated');
+      } catch (e) {
+        toast(`${e.message} - send it once, or let the app call it again`);
+      }
+    };
+  }
+
+  $('#send').onclick = () => send(ep, d);
+  const resetBtn = $('#reset-sample');
+  if (resetBtn) {
+    resetBtn.onclick = () => {
+      state.drafts.delete(ep.id);
+      touchDraft();
+      renderDetail();
+      toast('restored the captured request');
+    };
+  }
+  $('#copy-curl').onclick = () => copyCurl(ep, d);
+  updatePreview(ep, d);
+  renderResponse(ep);
+}
+
+function updatePreview(ep, d) {
+  const el = $('#url-preview');
+  if (el) el.textContent = previewUrl(ep, d);
+}
+
+/* -------------------------------------------------------------------- send */
+
+function payload(ep, d) {
+  const parse = (s) => {
+    try {
+      return JSON.parse(s || '{}');
+    } catch {
+      return {};
+    }
+  };
+  return {
+    id: ep.id,
+    holes: d.holes,
+    params: d.paramsMode !== 'raw' ? parse(d.params) : {},
+    rawQuery: d.paramsMode === 'raw' ? d.rawQuery : '',
+    stringifyKey: d.paramsMode === 'stringified' ? d.stringifyKey : '',
+    bodyType: d.bodyType,
+    headers: Object.fromEntries((d.headers ?? []).filter((h) => h.on && h.k).map((h) => [h.k, h.v])),
+    capture: Object.fromEntries((d.capture ?? []).filter((c) => c.name && c.path).map((c) => [c.name, c.path])),
+    data: d.bodyType === 'none' ? {} : parse(d.data),
+  };
+}
+
+async function send(ep, d) {
+  const btn = $('#send');
+  btn.disabled = true;
+  btn.textContent = 'Sending';
+  try {
+    state.response = await post('/api/call', payload(ep, d));
+    state.results[ep.id] = state.response;
+  } catch (e) {
+    state.response = { ok: false, status: null, error: e.message, ms: 0 };
+  }
+  btn.disabled = false;
+  btn.textContent = 'Send';
+  renderTree();
+  renderDetail();
+}
+
+async function runBatch(ids, label) {
+  if (state.busy) return;
+  state.busy = true;
+  toast(`running ${label}...`);
+  try {
+    const out = await post('/api/run', { ids });
+    state.results = out.results;
+    renderTree();
+    if (state.selected) renderDetail();
+    else if (state.openModule) renderModule(state.openModule);
+    const failed = Object.values(state.results).filter((r) => !r.ok).length;
+    toast(
+      `ran ${out.ran}${out.skipped ? `, skipped ${out.skipped} write endpoints` : ''} - ${failed} failing` +
+        (out.unfilled ? ` - ${out.unfilled} ran with a blank path value, so treat those loosely` : ''),
+    );
+  } catch (e) {
+    toast(e.message);
+  }
+  state.busy = false;
+}
+
+function copyCurl(ep, d) {
+  const p = payload(ep, d);
+  const q = (s) => `'${String(s).replaceAll("'", `'\\''`)}'`;
+  const parts = [`curl -X ${ep.method} ${q(previewUrl(ep, d))}`, `  -H 'Content-Type: application/json'`];
+  if (!ep.absolute) parts.push(`  -H '${state.auth.header}: <your token>'`);
+  if (['POST', 'PUT', 'PATCH', 'DELETE'].includes(ep.method)) {
+    parts.push(`  -d ${q(JSON.stringify(p.data))}`);
+  }
+  navigator.clipboard.writeText(parts.join(' \\\n'));
+  toast('cURL copied (token left as a placeholder)');
+}
+
+/* ---------------------------------------------------------------- response */
+
+function renderResponse(ep) {
+  const el = $('#response');
+  const stored = state.results[ep.id]?.failure;
+
+  // nothing sent from here yet, but the last run kept the failure worth reading
+  if (!state.response && stored) {
+    el.innerHTML = `
+      <div class="status">
+        <span class="code fail">${stored.status ?? 'failed'}</span>
+        ${stored.innerCode ? `<span class="badge fail">body code ${stored.innerCode}</span>` : ''}
+        <span class="muted">${
+          stored.from === 'replay' ? 'from the last replay' : `from the last ${esc(stored.from)}`
+        }, ${new Date(stored.at).toLocaleString()}</span>
+        <span class="spacer"></span>
+        <button class="link" id="copy-stored">copy</button>
+      </div>
+      <p class="muted mono" style="margin:0 0 8px;word-break:break-all">${esc(stored.url ?? '')}</p>
+      <pre class="body">${
+        stored.error ? esc(stored.error) : highlightJson(prettyJson(stored.body ?? ''))
+      }</pre>`;
+    $('#copy-stored').onclick = () => {
+      navigator.clipboard.writeText(stored.body ?? stored.error ?? '');
+      toast('copied');
+    };
+    return;
+  }
+
+  const r = state.response;
+  if (!r) {
+    el.innerHTML = '';
+    return;
+  }
+  if (r.error) {
+    el.innerHTML = `<div class="status"><span class="code fail">failed</span>
+      <span>${esc(r.error)}</span><span class="muted">${r.ms} ms</span></div>`;
+    return;
+  }
+
+  const pretty = prettyJson(r.body);
+  const view = state.tab === 'headers' ? Object.entries(r.headers ?? {}).map(([k, v]) => `${k}: ${v}`).join('\n') : pretty;
+
+  const captured = Object.entries(r.captured ?? {});
+  el.innerHTML = `
+    ${
+      captured.length
+        ? `<div class="sub">${captured
+            .map(([name, c]) =>
+              c.error
+                ? `<span class="badge fail" title="${esc(c.path)}">${esc(name)}: ${esc(c.error)}</span>`
+                : `<span class="badge pass">${esc(name)} = ${esc(c.value)}</span>`,
+            )
+            .join('')}</div>`
+        : ''
+    }
+    <div class="status">
+      <span class="code ${r.ok ? 'pass' : 'fail'}">${r.status}</span>
+      ${r.innerCode ? `<span class="badge ${r.ok ? '' : 'fail'}">body code ${r.innerCode}</span>` : ''}
+      <span class="muted">${r.ms} ms</span>
+      <span class="muted">${(r.size / 1024).toFixed(1)} kB</span>
+      <span class="spacer"></span>
+      <div class="tabs">
+        ${['body', 'headers']
+          .map((t) => `<button data-tab="${t}" class="${state.tab === t ? 'on' : ''}">${t}</button>`)
+          .join('')}
+        <button id="copy-res">copy</button>
+      </div>
+    </div>
+    <pre class="body">${state.tab === 'headers' ? esc(view) : highlightJson(view)}</pre>`;
+
+  for (const b of el.querySelectorAll('[data-tab]')) {
+    b.onclick = () => {
+      state.tab = b.dataset.tab;
+      renderResponse(ep);
+    };
+  }
+  $('#copy-res').onclick = () => {
+    navigator.clipboard.writeText(view);
+    toast('copied');
+  };
+}
+
+/* ------------------------------------------------------------------- token */
+
+function renderTokenButton() {
+  const held = state.tokensHeld.includes(state.auth.header);
+  const btn = $('#token-btn');
+  const owner = state.tokenOwner;
+  btn.textContent = held
+    ? owner?.name
+      ? `signed in: ${owner.name.split(' ')[0]}`
+      : `${state.auth.header} set`
+    : `Set ${state.auth.header}`;
+  btn.title = held && owner
+    ? `token belongs to ${owner.name} (${owner.email}), signed in ${new Date(owner.at).toLocaleString()} - everyone here replays as this user`
+    : '';
+  btn.style.borderColor = held ? 'var(--pass)' : 'var(--warn)';
+  btn.style.color = held ? 'var(--pass)' : 'var(--warn)';
+}
+
+/*
+ * Signing in, driven entirely by what the server says the flow is.
+ *
+ * The console has no idea whether the API wants an email and a password, a
+ * one-time code, an organisation picked from a list, or all three. It asks for
+ * the current step, renders whatever fields that step declares, posts them
+ * back, and repeats until the server says it holds a token. A project with no
+ * sign-in flow configured gets the paste-a-token form instead.
+ */
+const loginState = { stage: null, fields: [], choices: null, title: null, user: null, busy: false };
+
+/** a field descriptor from the server -> one labelled input */
+function loginField(f) {
+  const id = `login-f-${f.name}`;
+  if (f.options || f.type === 'select') {
+    return `<label>${esc(f.label ?? f.name)}
+      <select id="${id}" data-field="${esc(f.name)}">
+        ${(f.options ?? []).map((o) => `<option value="${esc(o.value ?? o.id)}">${esc(o.label ?? o.name)}</option>`).join('')}
+      </select></label>`;
+  }
+  return `<label>${esc(f.label ?? f.name)}
+    <input id="${id}" data-field="${esc(f.name)}" type="${esc(f.type ?? 'text')}"
+      ${f.type === 'password' ? 'autocomplete="current-password"' : ''}
+      ${f.inputmode ? `inputmode="${esc(f.inputmode)}"` : ''}
+      placeholder="${esc(f.placeholder ?? '')}" /></label>`;
+}
+
+function renderLoginStep() {
+  const el = $('#login-step');
+  if (!el) return;
+  const held = state.tokensHeld.includes(state.auth.header);
+
+  if (held && !loginState.stage) {
+    const who = loginState.user ?? state.tokenOwner;
+    el.innerHTML = `<div class="report">
+      <b class="pass">Signed in.</b>
+      ${
+        who?.name
+          ? `${esc(who.name)} &middot; <span class="muted">${esc(who.email ?? '')}</span>`
+          : `A ${esc(state.auth.header)} is held.`
+      }
+      <p class="muted" style="margin:6px 0 0">
+        Everyone using this console replays with this session.
+      </p>
+      <p class="muted" style="margin:6px 0 0">
+        Kept owner-only in the console's data directory so a restart does not sign you out.
+        <b>Sign out</b> deletes it.
+      </p>
+    </div>`;
+    return;
+  }
+
+  if (!state.login?.supported) {
+    el.innerHTML = `<p class="muted">This console has no sign-in flow configured.
+      Paste a token below instead.</p>`;
+    return;
+  }
+
+  const fields = loginState.fields.length ? loginState.fields : state.login.fields ?? [];
+  el.innerHTML = `
+    <div class="login-form">
+      ${loginState.title ? `<p class="muted">${esc(loginState.title)}</p>` : ''}
+      ${fields.map(loginField).join('')}
+      <div class="row end">
+        <span class="err" id="login-err"></span>
+        <span class="spacer"></span>
+        <button class="primary" id="login-go">Continue</button>
+      </div>
+    </div>`;
+
+  $('#login-go').onclick = submitLoginStep;
+  for (const input of el.querySelectorAll('input')) {
+    // must not return the comparison: a falsy return from onkeydown cancels the key
+    input.onkeydown = (e) => {
+      if (e.key === 'Enter') submitLoginStep();
+    };
+  }
+  el.querySelector('input, select')?.focus();
+}
+
+const loginError = (msg) => {
+  const el = $('#login-err');
+  if (el) el.textContent = msg;
+};
+
+async function submitLoginStep() {
+  if (loginState.busy) return;
+  loginState.busy = true;
+  loginError('');
+  try {
+    const input = { stage: loginState.stage ?? state.login?.stage ?? null };
+    for (const el of $('#login-step').querySelectorAll('[data-field]')) {
+      input[el.dataset.field] = el.value.trim ? el.value.trim() : el.value;
+    }
+    const out = await post('/api/login', input);
+
+    if (out.done) {
+      state.tokensHeld = out.tokensHeld;
+      loginState.user = out.user;
+      loginState.stage = null;
+      loginState.fields = [];
+      renderTokenButton();
+      renderLoginStep();
+      toast(`signed in${out.user?.name ? ` as ${out.user.name}` : ''}`);
+    } else {
+      loginState.stage = out.stage;
+      loginState.title = out.title;
+      loginState.fields = out.fields ?? [];
+      renderLoginStep();
+    }
+  } catch (e) {
+    loginError(e.message);
+  }
+  loginState.busy = false;
+}
+
+/** a second showModal while another dialog is open traps focus in the first one */
+function closeOtherDialogs(keep) {
+  for (const d of document.querySelectorAll('dialog[open]')) {
+    if (d.id !== keep) d.close();
+  }
+}
+
+function openTokenDialog() {
+  closeOtherDialogs('token-dialog');
+  $('#hdr').textContent = state.auth.header;
+  // only some projects can say where the live token is readable from
+  const snippet = $('#snippet');
+  snippet.textContent = state.auth.snippet ?? '';
+  snippet.hidden = !state.auth.snippet;
+  $('#copy-snippet').hidden = !state.auth.snippet;
+
+  loginState.stage = null;
+  loginState.fields = state.login?.fields ?? [];
+  loginState.title = state.login?.title ?? null;
+  renderLoginStep();
+  $('#token-dialog').showModal();
+}
+
+/** pulls the export straight from the server so the file is built in one place */
+async function download(module, format) {
+  const res = await fetchAt(`/api/export?module=${encodeURIComponent(module)}&format=${format}`);
+  if (!res.ok) return toast((await res.json()).error ?? 'export failed');
+
+  const blob = await res.blob();
+  const name = /filename="([^"]+)"/.exec(res.headers.get('content-disposition') ?? '')?.[1];
+  const url = URL.createObjectURL(blob);
+  const a = Object.assign(document.createElement('a'), {
+    href: url,
+    download: name ?? `${module || 'all'}.${format}`,
+  });
+  document.body.append(a);
+  a.click();
+  a.remove();
+  URL.revokeObjectURL(url);
+  toast(`downloaded ${name}`);
+}
+
+/* -------------------------------------------------------------------- live */
+
+let livePoll;
+
+function renderLive() {
+  const btn = $('#live-btn');
+  btn.classList.toggle('on', state.live.on);
+  btn.textContent = state.live.on ? `Live · ${state.live.count}` : 'Live';
+  if (state.locks.recording) {
+    // shared console: one person must not be able to stop everyone's recording
+    btn.disabled = true;
+    btn.title = `recording every developer's calls - ${state.live.count} captured, and it cannot be paused here`;
+    return;
+  }
+  btn.disabled = false;
+  btn.title = state.live.on
+    ? `recording API calls from the running app - ${state.live.count} captured`
+    : 'paused; click to record API calls from the running app';
+}
+
+/**
+ * Polls while recording. Only the tree and health bar are redrawn, never the open
+ * editor -- refreshing that under someone mid-edit would throw their work away.
+ */
+async function pollLive() {
+  if (!state.live.on) return;
+  try {
+    const d = await api('/api/live');
+    const changed = d.count !== state.live.count;
+    const openBefore = state.selected ? state.samples[state.selected]?.seenAt : null;
+
+    state.live = { on: d.on, count: d.count, unmatched: d.unmatched ?? [] };
+    state.samples = d.samples ?? {};
+    state.results = d.results ?? {};
+    renderLive();
+    if (!changed) return;
+
+    for (const id of Object.keys(state.samples)) {
+      if (id !== state.selected) state.drafts.delete(id);
+    }
+    saveDrafts();
+    renderTree();
+
+    // the endpoint you are looking at was just called again by the app
+    const openAfter = state.selected ? state.samples[state.selected]?.seenAt : null;
+    if (openAfter && openAfter !== openBefore) refreshOpenEndpoint(openBefore);
+    else if (!state.selected && state.openModule) renderModule(state.openModule);
+    else if (!state.selected) renderEmpty();
+  } catch {
+    /* tracker restarting; the next tick will catch up */
+  }
+}
+
+/**
+ * Refills the open endpoint from the call that just happened -- unless doing so
+ * would throw away work: your own edits, or a field you are typing in right now.
+ * In that case the new capture waits behind a button instead.
+ */
+function refreshOpenEndpoint(previousSeenAt) {
+  const draft = state.drafts.get(state.selected);
+  const edited = Boolean(draft?.editedAt) && draft.editedAt > (previousSeenAt ?? '');
+  const active = document.activeElement;
+  const typing =
+    active && $('#panel')?.contains(active) && /INPUT|TEXTAREA|SELECT/.test(active.tagName);
+
+  if (edited || typing) {
+    showCaptureHint();
+    return;
+  }
+  state.drafts.delete(state.selected);
+  saveDrafts();
+  renderDetail();
+  toast('updated from the call your app just made');
+}
+
+/** formats a response body when it is JSON, leaves it alone when it is not */
+function prettyJson(text) {
+  try {
+    return JSON.stringify(JSON.parse(text), null, 2);
+  } catch {
+    return text ?? '';
+  }
+}
+
+/** a non-destructive nudge when we cannot safely refill in place */
+function showCaptureHint() {
+  const panel = $('#panel');
+  if (!panel || $('#capture-hint')) return;
+  const bar = document.createElement('div');
+  bar.id = 'capture-hint';
+  bar.className = 'hint';
+  bar.innerHTML = `Your app just called this again.
+    <button class="link" id="load-latest">load the new payload</button>
+    <span class="muted">your current edits stay until you do</span>`;
+  panel.prepend(bar);
+  $('#load-latest').onclick = () => {
+    state.drafts.delete(state.selected);
+    saveDrafts();
+    renderDetail();
+    toast('loaded the latest call');
+  };
+}
+
+async function setLive(on) {
+  state.live = { ...state.live, ...(await post('/api/live', { on })) };
+  renderLive();
+  clearInterval(livePoll);
+  if (state.live.on) {
+    livePoll = setInterval(pollLive, 2000);
+    toast('recording - use the app at localhost:3000 and calls will appear here');
+  } else {
+    toast('recording paused');
+  }
+}
+
+/* ------------------------------------------------------------------ import */
+
+function renderImportReport(out) {
+  const covered = Object.keys(out.samples ?? {}).length;
+  $('#import-report').innerHTML = `
+    <div class="report">
+      <b class="${out.matched ? 'pass' : 'fail'}">${out.matched} request${out.matched === 1 ? '' : 's'} matched</b>
+      &mdash; ${covered} of ${state.endpoints.length} endpoints now have a real sample.
+      ${
+        out.unmatched?.length
+          ? `<div class="muted" style="margin-top:6px">${out.unmatched.length} API request${
+              out.unmatched.length === 1 ? '' : 's'
+            } matched no known endpoint:</div>
+             <ul class="muted">${out.unmatched.slice(0, 20).map((u) => `<li>${esc(u)}</li>`).join('')}</ul>
+             ${out.unmatched.length > 20 ? `<div class="muted">and ${out.unmatched.length - 20} more</div>` : ''}`
+          : ''
+      }
+    </div>`;
+}
+
+async function importTraffic(kind, text) {
+  toast(kind === 'har' ? 'reading HAR...' : 'parsing cURL...');
+  try {
+    const out = await post('/api/import', { kind, text });
+    state.samples = out.samples;
+    // drafts were seeded from the old samples, so drop the untouched ones
+    for (const id of Object.keys(out.samples)) state.drafts.delete(id);
+    saveDrafts();
+    renderImportReport(out);
+    renderTree();
+    if (state.selected) renderDetail();
+    else if (state.openModule) renderModule(state.openModule);
+    else renderEmpty();
+    toast(`${out.matched} matched, ${Object.keys(out.samples).length} endpoints have samples`);
+  } catch (e) {
+    toast(e.message);
+  }
+}
+
+/* ------------------------------------------------------------------ report */
+
+const card = (label, value, cls = '') =>
+  `<div class="card"><b class="${cls}">${value}</b><span>${label}</span></div>`;
+
+const idLinks = (ids, limit = 12) =>
+  ids.length
+    ? ids.slice(0, limit).map((i) => `<button class="link mono" data-goto="${esc(i)}">${esc(i)}</button>`).join(', ') +
+      (ids.length > limit ? ` <span class="muted">and ${ids.length - limit} more</span>` : '')
+    : '<span class="muted">none</span>';
+
+async function renderReport() {
+  state.selected = null;
+  state.openModule = null;
+  renderTree();
+  $('#panel').innerHTML = '<p class="muted">building the report...</p>';
+
+  const r = await api('/api/report');
+  const c = r.coverage;
+  const h = r.health;
+
+  $('#panel').innerHTML = `
+    <nav class="crumbs"><button class="link" data-home>Overview</button><span>/</span>
+      <span class="here">report</span></nav>
+    <h1>API report</h1>
+    <div class="sub">
+      <span class="badge">${esc(r.env)}</span>
+      <span class="mono">${esc(r.baseUrl ?? '')}</span>
+      <span class="muted">generated ${new Date(r.generatedAt).toLocaleString()}</span>
+      <span class="spacer"></span>
+      <button id="report-md">Export Markdown</button>
+      <button id="report-json">Export JSON</button>
+    </div>
+
+    <div class="cards">
+      ${card('endpoints', c.total)}
+      ${card('exercised', `${c.seen} <small>${c.pct}%</small>`, c.pct > 50 ? 'pass' : 'warn')}
+      ${card('passing', h.passed, 'pass')}
+      ${card('failing', h.failed, h.failed ? 'fail' : '')}
+      ${card('regressions', h.regressions.length, h.regressions.length ? 'fail' : '')}
+      ${card('contract drift', r.drift.length, r.drift.length ? 'warn' : '')}
+      ${card('never exercised', c.total - c.seen, 'muted')}
+      ${card('unused in app', r.hygiene.unused.length, r.hygiene.unused.length ? 'warn' : '')}
+    </div>
+
+    ${section('Failing', h.failing.length, failingTable(h))}
+    ${section('Contract drift', r.drift.length, driftList(r.drift))}
+    ${section('Risks', null, risksBlock(r.risks))}
+    ${section('Coverage by module', null, coverageTable(c))}
+    ${section('Hygiene', null, hygieneBlock(r.hygiene))}
+    ${section('Auth surface', null, authBlock(r.auth))}
+    ${section('Latency', null, latencyBlock(r.performance))}
+    ${section('Trend', r.trends.length, trendTable(r.trends))}
+    ${section('Request and response inventory', r.inventory.length, inventoryTable(r.inventory), true)}`;
+
+  wireCrumbs();
+  wireGotoRows();
+  for (const b of document.querySelectorAll('#panel [data-goto]')) {
+    b.onclick = () => select(b.dataset.goto);
+  }
+  $('#report-md').onclick = () => downloadReport('md');
+  $('#report-json').onclick = () => downloadReport('json');
+}
+
+const section = (title, count, body, collapsed = false) => `
+  <details class="rsec" ${collapsed ? '' : 'open'}>
+    <summary>${esc(title)}${count !== null && count !== undefined ? ` <b>${count}</b>` : ''}</summary>
+    <div class="rsec-body">${body}</div>
+  </details>`;
+
+function failingTable(h) {
+  if (!h.failing.length) return '<p class="muted">Nothing is failing.</p>';
+  return `<table class="list"><thead><tr>
+      <th>endpoint</th><th>method</th><th>status</th><th>body</th><th>message</th></tr></thead><tbody>
+    ${h.failing
+      .map(
+        (f) => `<tr data-goto="${esc(f.id)}">
+          <td class="mono">${esc(f.id)}
+            ${f.regression ? '<span class="badge fail">regression</span>' : ''}
+            ${f.failedInReplay ? '<span class="badge warn">replay</span>' : ''}</td>
+          <td class="method m-${esc(f.method)}">${esc(f.method)}</td>
+          <td class="fail">${esc(f.status ?? '—')}</td>
+          <td>${esc(f.innerCode ?? '—')}</td>
+          <td class="muted msg" title="${esc(f.message ?? '')}">${esc(
+            (f.message ?? '').length > 150 ? `${f.message.slice(0, 150)}…` : f.message ?? '',
+          )}</td>
+        </tr>`,
+      )
+      .join('')}</tbody></table>`;
+}
+
+const driftList = (drift) =>
+  drift.length
+    ? `<ul class="plain">${drift
+        .map(
+          (d) => `<li><button class="link mono" data-goto="${esc(d.id)}">${esc(d.id)}</button>
+            <span class="mono warn">${esc(d.summary)}</span>
+            <span class="muted">baseline ${d.baselineAt ? new Date(d.baselineAt).toLocaleDateString() : '—'}</span></li>`,
+        )
+        .join('')}</ul>`
+    : '<p class="muted">No response shapes have changed.</p>';
+
+const risksBlock = (k) => `
+  <dl class="rlist">
+    <dt>Writes never exercised <b>${k.untestedWrites.length}</b></dt><dd>${idLinks(k.untestedWrites)}</dd>
+    <dt>Captured DELETEs <b>${k.capturedDeletes.length}</b></dt><dd>${idLinks(k.capturedDeletes)}</dd>
+    <dt>2xx carrying an error code <b>${k.envelopeErrors.length}</b></dt>
+      <dd>${idLinks(k.envelopeErrors.map((e) => e.id))}</dd>
+    <dt>Payloads with stripped secrets <b>${k.redactedPayloads.length}</b></dt>
+      <dd>${idLinks(k.redactedPayloads)}</dd>
+  </dl>`;
+
+const coverageTable = (c) => `
+  <table class="list"><thead><tr><th>module</th><th>exercised</th><th>total</th><th></th></tr></thead><tbody>
+    ${c.modules
+      .map(
+        (m) => `<tr><td>${esc(m.module)}</td><td>${m.seen}</td><td>${m.total}</td>
+          <td><div class="bar" style="width:120px"><i class="p" style="width:${m.pct}%"></i></div></td></tr>`,
+      )
+      .join('')}</tbody></table>`;
+
+const hygieneBlock = (g) => `
+  <dl class="rlist">
+    <dt>Referenced nowhere <b>${g.unused.length}</b></dt><dd>${idLinks(g.unused.map((u) => u.id), 20)}</dd>
+    <dt>Duplicate routes <b>${g.duplicates.length}</b></dt>
+      <dd>${
+        g.duplicates.length
+          ? `<ul class="plain">${g.duplicates
+              .map((d) => `<li><span class="mono">${esc(d.route)}</span> &mdash; ${idLinks(d.ids)}</li>`)
+              .join('')}</ul>`
+          : '<span class="muted">none</span>'
+      }</dd>
+    <dt>Called but not found in the source <b>${g.uncatalogued.length}</b></dt>
+      <dd>${idLinks(g.uncatalogued.map((u) => u.id))}</dd>
+  </dl>`;
+
+const authBlock = (a) => `
+  <dl class="rlist">
+    <dt>Signed ACCESS_TOKEN <b>${a.accessToken.length}</b></dt><dd>${idLinks(a.accessToken)}</dd>
+    <dt>SECRET_TOKEN <b>${a.secretToken.length}</b></dt><dd>${idLinks(a.secretToken)}</dd>
+    <dt>CS token <b>${a.csToken.length}</b></dt><dd>${idLinks(a.csToken)}</dd>
+    <dt>Third-party, no token sent <b>${a.thirdParty.length}</b></dt><dd>${idLinks(a.thirdParty)}</dd>
+    <dt>Standard ${esc(state.auth.header)} <b>${a.standard}</b></dt><dd class="muted">everything else</dd>
+  </dl>`;
+
+const latencyBlock = (p) => `
+  <p>median <b>${p.median}ms</b> &middot; p95 <b>${p.p95}ms</b>
+    <span class="muted">over ${p.samples} endpoints &mdash; ${esc(p.caveat)}</span></p>
+  <ul class="plain">${p.slowest
+    .map((s) => `<li><b>${s.ms}ms</b> <button class="link mono" data-goto="${esc(s.id)}">${esc(s.id)}</button></li>`)
+    .join('')}</ul>`;
+
+const trendTable = (t) =>
+  t.length
+    ? `<table class="list"><thead><tr><th>when</th><th>ran</th><th>passed</th><th>failed</th>
+        <th>pass rate</th><th>coverage</th></tr></thead><tbody>
+        ${t
+          .map(
+            (x) => `<tr><td>${new Date(x.at).toLocaleString()}</td><td>${x.ran}</td>
+              <td class="pass">${x.passed}</td><td class="fail">${x.failed}</td>
+              <td>${x.passRate}%</td><td>${x.coverage ?? '—'}%</td></tr>`,
+          )
+          .join('')}</tbody></table>`
+    : '<p class="muted">No runs recorded yet. Every replay from now on adds a row here.</p>';
+
+const inventoryTable = (inv) => `
+  <table class="list"><thead><tr><th>endpoint</th><th>params</th><th>body</th><th>response</th></tr></thead>
+  <tbody>${inv
+    .map(
+      (i) => `<tr data-goto="${esc(i.id)}">
+        <td class="mono">${esc(i.method)} ${esc(i.path)}</td>
+        <td class="muted">${esc(i.params.join(', ') || '—')}</td>
+        <td class="muted">${esc(i.body.join(', ') || '—')}</td>
+        <td class="muted">${esc(i.response.slice(0, 6).join(', ') || '—')}${
+          i.response.length > 6 ? ` +${i.response.length - 6}` : ''
+        }</td>
+      </tr>`,
+    )
+    .join('')}</tbody></table>`;
+
+async function downloadReport(format) {
+  const res = await fetchAt(`/api/report/export?format=${format}`);
+  const blob = await res.blob();
+  const name = /filename="([^"]+)"/.exec(res.headers.get('content-disposition') ?? '')?.[1];
+  const url = URL.createObjectURL(blob);
+  const a = Object.assign(document.createElement('a'), { href: url, download: name ?? `report.${format}` });
+  document.body.append(a);
+  a.click();
+  a.remove();
+  URL.revokeObjectURL(url);
+  toast(`downloaded ${name}`);
+}
+
+/* ------------------------------------------------------------------ replay */
+
+const capturedIds = () => state.endpoints.filter((e) => state.samples[e.id]).map((e) => e.id);
+
+const replayOptions = () => ({
+  allowMutating: true,
+  includeDeletes: $('#opt-deletes')?.checked ?? false,
+  includeLogout: $('#opt-logout')?.checked ?? false,
+  includeAccessToken: $('#opt-access')?.checked ?? false,
+});
+
+/** shows exactly what is about to happen before anything is sent */
+async function renderReplayPlan() {
+  const plan = await post('/api/run/preview', { ids: capturedIds(), ...replayOptions() });
+  const s = plan.skippedDetail;
+  const list = (label, ids) =>
+    ids.length
+      ? `<li>${label}: ${ids.map((i) => `<code>${esc(i)}</code>`).join(', ')}</li>`
+      : '';
+
+  const writes = Object.entries(plan.byMethod)
+    .filter(([m]) => m !== 'GET')
+    .map(([m, n]) => `${n} ${m}`)
+    .join(', ');
+
+  $('#replay-plan').innerHTML = `
+    <div class="report">
+      <b>${plan.total}</b> call${plan.total === 1 ? '' : 's'} against
+      <b class="${plan.env === 'prod' ? 'fail' : 'warn'}">${esc(plan.env)}</b>
+      <span class="muted mono">${esc(plan.baseUrl)}</span>
+      <div style="margin-top:6px">
+        ${Object.entries(plan.byMethod)
+          .map(([m, n]) => `<span class="badge m-${esc(m)}">${n} ${esc(m)}</span>`)
+          .join(' ')}
+      </div>
+      ${
+        writes
+          ? `<p class="warn" style="margin:8px 0 0">${esc(writes)} will change real data.</p>`
+          : '<p class="muted" style="margin:8px 0 0">Read-only: nothing will be modified.</p>'
+      }
+      ${
+        s.deletes.length || s.logout.length || s.redacted.length || s.accessToken.length
+          ? `<ul class="muted" style="margin:8px 0 0">
+              ${list('DELETE, left out', s.deletes)}
+              ${list('logout, left out', s.logout)}
+              ${list('needs ACCESS_TOKEN, left out', s.accessToken)}
+              ${list('payload has a stripped secret, cannot be replayed', s.redacted)}
+            </ul>`
+          : ''
+      }
+    </div>`;
+
+  const go = $('#replay-go');
+  go.disabled = plan.env === 'prod' || !plan.total;
+  go.textContent = plan.env === 'prod' ? 'Not allowed on prod' : `Run ${plan.total}`;
+}
+
+async function openReplayDialog() {
+  closeOtherDialogs('replay-dialog');
+  for (const id of ['#opt-deletes', '#opt-logout', '#opt-access']) $(id).disabled = false;
+  $('#replay-close').textContent = 'Cancel';
+  $('#replay-close').onclick = () => $('#replay-dialog').close();
+  $('#replay-go').disabled = false;
+  $('#replay-dialog').showModal();
+  $('#replay-plan').innerHTML = '<p class="muted">working out what would run...</p>';
+  await renderReplayPlan();
+}
+
+/** the rows a run produced, clickable through to each endpoint */
+function ranList(rows) {
+  return `<ul class="ran">
+    ${rows
+      .map(
+        (r) => `<li>
+          <button class="ran-row ${r.ok ? 'pass' : 'fail'}" data-goto="${esc(r.id)}"
+            title="open ${esc(r.id)}">
+            <span class="method m-${esc(r.method)}">${esc(r.method)}</span>
+            <span class="mono">${esc(r.id)}</span>
+            <span class="spacer"></span>
+            <span class="outcome">${esc(
+              r.error ?? `${r.status}${r.innerCode ? ` · ${r.innerCode}` : ''}`,
+            )}</span>
+            <span class="muted">${r.ms}ms</span>
+            <span class="go">&rsaquo;</span>
+          </button>
+        </li>`,
+      )
+      .join('')}
+  </ul>`;
+}
+
+/** rows jump to their endpoint; the dialog closes itself if it is open */
+function wireGotoRows() {
+  for (const btn of document.querySelectorAll('[data-goto]')) {
+    btn.onclick = () => {
+      $('#replay-dialog').close();
+      select(btn.dataset.goto);
+    };
+  }
+}
+
+/** live progress, polled while the run is in flight */
+function renderProgress(run) {
+  const pct = run.total ? Math.round((run.done / run.total) * 100) : 0;
+  const recent = [...run.finished].reverse().slice(0, 8);
+
+  $('#replay-plan').innerHTML = `
+    <div class="progress">
+      <div class="progress-head">
+        <b>${run.done} of ${run.total}</b>
+        <span class="pass">${run.passed} passed</span>
+        <span class="fail">${run.failed} failed</span>
+        <span class="spacer"></span>
+        <span class="muted">${pct}%</span>
+      </div>
+      <div class="bar">
+        <i class="p" style="width:${run.total ? (run.passed / run.total) * 100 : 0}%"></i>
+        <i class="f" style="width:${run.total ? (run.failed / run.total) * 100 : 0}%"></i>
+      </div>
+      <div class="progress-now">
+        ${
+          run.current
+            ? `<span class="spin"></span>
+               <span class="method m-${esc(run.current.method)}">${esc(run.current.method)}</span>
+               <span class="mono">${esc(run.current.id)}</span>`
+            : `<span class="muted">${run.active ? 'starting...' : 'finished'}</span>`
+        }
+      </div>
+      ${ranList(recent)}
+    </div>`;
+
+  wireGotoRows();
+}
+
+async function runReplay() {
+  if (state.busy) return;
+  const opts = replayOptions();
+  state.busy = true;
+
+  // the dialog stays open and turns into a progress view
+  for (const id of ['#opt-deletes', '#opt-logout', '#opt-access']) $(id).disabled = true;
+  $('#replay-go').disabled = true;
+  $('#replay-go').textContent = 'Running';
+  $('#replay-close').textContent = 'Stop';
+  $('#replay-close').onclick = async () => {
+    $('#replay-close').textContent = 'Stopping';
+    await post('/api/run/cancel', {});
+  };
+
+  const poll = setInterval(async () => {
+    try {
+      const run = await api('/api/run/status');
+      if (run.total) renderProgress(run);
+    } catch {
+      /* the next tick will catch up */
+    }
+  }, 350);
+
+  try {
+    const out = await post('/api/run', { ids: capturedIds(), ...opts });
+    clearInterval(poll);
+    state.results = out.results;
+
+    const run = await api('/api/run/status');
+    state.lastRun = run;
+    renderProgress(run);
+    renderTree();
+
+    // hand the controls back: the run is over, so the primary button runs it again
+    for (const id of ['#opt-deletes', '#opt-logout', '#opt-access']) $(id).disabled = false;
+    $('#replay-go').disabled = false;
+    $('#replay-go').textContent = 'Run again';
+    $('#replay-close').textContent = 'Close';
+    $('#replay-close').onclick = () => {
+      $('#replay-dialog').close();
+      renderEmpty();
+    };
+    toast(
+      `${out.cancelled ? 'stopped after ' : 'ran '}${out.ran}, ${out.failed} failing` +
+        (out.skipped ? `, ${out.skipped} left out` : ''),
+    );
+  } catch (e) {
+    clearInterval(poll);
+    $('#replay-dialog').close();
+    toast(e.message);
+  }
+  state.busy = false;
+}
+
+/* --------------------------------------------------------------- variables */
+
+function renderVars() {
+  const entries = Object.entries(state.vars);
+  $('#vars-list').innerHTML = entries.length
+    ? entries
+        .map(
+          ([k, v]) => `<div class="row" data-var="${esc(k)}">
+            <code style="min-width:120px">{{${esc(k)}}}</code>
+            <input data-var-value="${esc(k)}" value="${esc(v)}" />
+            <button class="link" data-var-del="${esc(k)}">&times;</button>
+          </div>`,
+        )
+        .join('')
+    : '<p class="muted">none yet</p>';
+
+  for (const el of document.querySelectorAll('[data-var-value]')) {
+    el.onchange = () => setVar(el.dataset.varValue, el.value);
+  }
+  for (const el of document.querySelectorAll('[data-var-del]')) {
+    el.onclick = () => setVar(el.dataset.varDel, '');
+  }
+}
+
+async function setVar(name, value) {
+  state.vars = (await post('/api/variables', { name, value })).vars;
+  renderVars();
+}
+
+/* -------------------------------------------------------------------- boot */
+
+function select(id) {
+  state.selected = id;
+  state.response = null;
+  const ep = state.endpoints.find((e) => e.id === id);
+  state.openModule = ep.module;
+  renderTree();
+  renderDetail();
+}
+
+/** back to the overview, from anywhere */
+function goHome() {
+  state.selected = null;
+  state.openModule = null;
+  state.response = null;
+  renderTree();
+  renderEmpty();
+}
+
+/** where you are, and the way back */
+function crumbs(module, endpoint) {
+  return `<nav class="crumbs">
+    <button class="link" data-home>Overview</button>
+    <span>/</span>
+    ${
+      endpoint
+        ? `<button class="link" data-module-crumb="${esc(module)}">${esc(module)}</button>
+           <span>/</span><span class="here">${esc(endpoint)}</span>`
+        : `<span class="here">${esc(module)}</span>`
+    }
+  </nav>`;
+}
+
+/** wires whichever crumbs are on screen */
+function wireCrumbs() {
+  const home = $('[data-home]');
+  if (home) home.onclick = goHome;
+  const mod = $('[data-module-crumb]');
+  if (mod) {
+    mod.onclick = () => {
+      state.selected = null;
+      state.openModule = mod.dataset.moduleCrumb;
+      renderTree();
+      renderModule(state.openModule);
+    };
+  }
+}
+
+function renderEmpty() {
+  $('#panel').innerHTML = `
+    <div class="empty">
+      <h2>${state.endpoints.length} endpoints across ${new Set(state.endpoints.map((e) => e.module)).size} modules</h2>
+      <p>Read straight out of your source. Pick a module on the left, or check
+        everything at once.</p>
+      <p><button class="primary" id="run-all">Run every GET endpoint</button>
+        ${Object.keys(state.results).length ? '<button id="clear-results">Clear results</button>' : ''}
+        ${
+          Object.keys(state.samples).length
+            ? '<button id="replay-all">Replay every captured call</button>'
+            : ''
+        }</p>
+      <p>
+        ${
+          Object.keys(state.samples).length
+            ? `<button id="export-all-postman">Export Postman collection</button>
+               <button id="export-all-har">Export all captured (HAR)</button>
+               <button id="clear-results-2" hidden></button>`
+            : ''
+        }</p>
+      ${lastRunPanel()}
+      ${coveragePanel()}
+      ${
+        state.endpoints.filter((e) => e.usedIn === 0).length
+          ? `<p class="muted">${state.endpoints.filter((e) => e.usedIn === 0).length} endpoints are
+             referenced nowhere outside their own service file &mdash;
+             <button class="link" id="show-unused">show them</button></p>`
+          : ''
+      }
+      <p class="muted">Set your ${esc(state.auth.header)} first, or everything will come back
+        unauthorised.</p>
+    </div>`;
+  $('#run-all').onclick = () => runBatch(state.endpoints.map((e) => e.id), 'all GET endpoints');
+  const unusedBtn = $('#show-unused');
+  if (unusedBtn) {
+    unusedBtn.onclick = () => {
+      $('#filter-status').value = 'unused';
+      renderTree();
+    };
+  }
+  const jump = (filter, id) => {
+    const btn = $(id);
+    if (btn) {
+      btn.onclick = () => {
+        $('#filter-status').value = filter;
+        renderTree();
+        toast(`filtered to ${filter}`);
+      };
+    }
+  };
+  jump('uncaptured', '#show-uncaptured');
+  jump('uncatalogued', '#show-uncatalogued');
+  jump('drift', '#show-drift');
+
+  const replayBtn = $('#replay-all');
+  if (replayBtn) replayBtn.onclick = openReplayDialog;
+  wireGotoRows();
+  const filterBtn = $('#lastrun-filter');
+  if (filterBtn) {
+    filterBtn.onclick = () => {
+      state.lastRunOnlyFailed = !state.lastRunOnlyFailed;
+      renderEmpty();
+    };
+  }
+  const againBtn = $('#lastrun-again');
+  if (againBtn) againBtn.onclick = openReplayDialog;
+  const exportAll = $('#export-all-har');
+  if (exportAll) exportAll.onclick = () => download('', 'har');
+  const exportPostman = $('#export-all-postman');
+  if (exportPostman) exportPostman.onclick = () => download('', 'postman');
+  const clearBtn = $('#clear-results');
+  if (clearBtn) {
+    clearBtn.onclick = async () => {
+      state.results = (await api('/api/results', { method: 'DELETE' })).results;
+      renderTree();
+      renderEmpty();
+      toast('results cleared');
+    };
+  }
+}
+
+async function load() {
+  state.drafts = loadDrafts();
+  const d = await api('/api/endpoints');
+  Object.assign(state, {
+    endpoints: d.endpoints,
+    baseUrls: d.baseUrls,
+    auth: d.auth,
+    env: d.env,
+    results: d.results ?? {},
+    tokensHeld: d.tokensHeld ?? [],
+    vars: d.vars ?? {},
+    samples: d.samples ?? {},
+    live: d.live ?? state.live,
+    contracts: d.contracts ?? {},
+    lastRun: d.lastRun ?? null,
+    locks: d.locks ?? state.locks,
+    login: d.login ?? state.login,
+    name: d.name ?? state.name,
+    tokenOwner: d.tokenOwner ?? null,
+  });
+
+  // a console recording live traffic before its first scan has no scan time
+  $('#scanned').textContent = d.scannedAt
+    ? `scanned ${new Date(d.scannedAt).toLocaleString()}`
+    : 'not scanned yet';
+  document.title = `${state.name} console`;
+  // the console is named after the API it is pointed at, not after itself
+  $('#console-name').textContent = state.name === 'API' ? 'API console' : `${state.name} console`;
+  $('#env').innerHTML = Object.entries(d.baseUrls)
+    .map(([k, v]) => `<option value="${esc(k)}" ${k === d.env ? 'selected' : ''} title="${esc(v)}">${esc(k)}</option>`)
+    .join('');
+  $('#filter-method').innerHTML =
+    '<option value="">any method</option>' +
+    [...new Set(d.endpoints.map((e) => e.method))].sort().map((m) => `<option>${m}</option>`).join('');
+
+  if (state.locks.env) {
+    const sel = $('#env');
+    sel.disabled = true;
+    sel.title = `this console is pinned to ${state.locks.env}`;
+  }
+  renderTokenButton();
+  renderLive();
+  if (state.live.on) livePoll = setInterval(pollLive, 2000);
+  renderTree();
+  if (state.selected) renderDetail();
+  else if (state.openModule) renderModule(state.openModule);
+  else renderEmpty();
+}
+
+$('#tree').onclick = (e) => {
+  const mod = e.target.closest('.module');
+  if (mod) {
+    const name = mod.dataset.module;
+    state.openModule = state.openModule === name ? null : name;
+    state.selected = null;
+    renderTree();
+    if (state.openModule) renderModule(state.openModule);
+    else renderEmpty();
+    return;
+  }
+  const row = e.target.closest('.endpoint');
+  if (row) select(row.dataset.id);
+};
+
+for (const id of ['#search', '#filter-method', '#filter-status']) $(id).oninput = renderTree;
+
+$('#env').onchange = async (e) => {
+  await post('/api/env', { env: e.target.value });
+  state.env = e.target.value;
+  // results from another environment would be misleading
+  state.results = {};
+  renderTree();
+  if (state.selected) renderDetail();
+  toast(`switched to ${state.env} (${state.baseUrls[state.env]})`);
+};
+
+$('#live-btn').onclick = () => setLive(!state.live.on);
+
+$('#import-btn').onclick = () => {
+  closeOtherDialogs('import-dialog');
+  $('#import-report').innerHTML = '';
+  $('#import-dialog').showModal();
+};
+$('#import-close').onclick = () => $('#import-dialog').close();
+$('#curl-import').onclick = () => {
+  const text = $('#curl-input').value.trim();
+  if (!text) return toast('paste a cURL command first');
+  importTraffic('curl', text);
+};
+$('#samples-clear').onclick = async () => {
+  state.samples = (await api('/api/samples', { method: 'DELETE' })).samples;
+  state.drafts.clear();
+  saveDrafts();
+  renderTree();
+  renderEmpty();
+  $('#import-report').innerHTML = '';
+  toast('samples cleared');
+};
+
+// drop a HAR anywhere on the page
+let dragDepth = 0;
+document.addEventListener('dragenter', (e) => {
+  e.preventDefault();
+  if (++dragDepth === 1) $('#drop').classList.add('on');
+});
+document.addEventListener('dragover', (e) => e.preventDefault());
+document.addEventListener('dragleave', () => {
+  if (--dragDepth <= 0) {
+    dragDepth = 0;
+    $('#drop').classList.remove('on');
+  }
+});
+document.addEventListener('drop', async (e) => {
+  e.preventDefault();
+  dragDepth = 0;
+  $('#drop').classList.remove('on');
+  const file = e.dataTransfer?.files?.[0];
+  if (!file) return;
+  $('#import-dialog').open || $('#import-dialog').showModal();
+  importTraffic('har', await file.text());
+});
+
+$('#replay-close').onclick = () => $('#replay-dialog').close();
+$('#replay-go').onclick = runReplay;
+for (const id of ['#opt-deletes', '#opt-logout', '#opt-access']) $(id).onchange = renderReplayPlan;
+
+$('#vars-btn').onclick = () => {
+  closeOtherDialogs('vars-dialog');
+  renderVars();
+  $('#vars-dialog').showModal();
+};
+$('#vars-close').onclick = () => $('#vars-dialog').close();
+$('#var-add').onclick = async () => {
+  const name = $('#var-name').value.trim();
+  if (!name) return toast('name required');
+  await setVar(name, $('#var-value').value);
+  $('#var-name').value = '';
+  $('#var-value').value = '';
+};
+
+$('#home-btn').onclick = goHome;
+$('#report-btn').onclick = renderReport;
+
+// Escape backs out: endpoint -> module -> overview
+document.addEventListener('keydown', (e) => {
+  if (e.key !== 'Escape' || document.querySelector('dialog[open]')) return;
+  const active = document.activeElement;
+  if (active && /INPUT|TEXTAREA|SELECT/.test(active.tagName)) return;
+  if (state.selected) {
+    state.selected = null;
+    renderTree();
+    renderModule(state.openModule);
+  } else if (state.openModule) {
+    goHome();
+  }
+});
+
+$('#token-btn').onclick = openTokenDialog;
+$('#copy-snippet').onclick = () => {
+  navigator.clipboard.writeText(state.auth.snippet);
+  toast('snippet copied - run it in the app tab DevTools console');
+};
+$('#token-save').onclick = async () => {
+  const token = $('#token-input').value.trim();
+  if (!token) return toast('nothing pasted');
+  state.tokensHeld = (await post('/api/token', { token })).tokensHeld;
+  $('#token-input').value = '';
+  loginState.stage = 'done';
+  renderTokenButton();
+  renderLoginStep();
+  toast('token stored in server memory');
+};
+$('#token-close').onclick = () => $('#token-dialog').close();
+$('#token-clear').onclick = async () => {
+  state.tokensHeld = (await post('/api/token', { token: '' })).tokensHeld;
+  $('#token-input').value = '';
+  loginState.stage = 'credentials';
+  loginState.user = null;
+  renderTokenButton();
+  renderLoginStep();
+  toast('signed out, token cleared');
+};
+
+document.addEventListener('keydown', (e) => {
+  if ((e.metaKey || e.ctrlKey) && e.key === 'Enter') $('#send')?.click();
+});
+
+load();