@vimoxshah/tokenflow 1.1.2 → 1.2.0

package/src/ui/views/branches.js

@@ -0,0 +1,304 @@
+/**
+ * The Compare branches tab: any two branch receipts from buildReceipts()
+ * (src/analytics/receipt.js), side by side on a symmetric log scale.
+ *
+ * Reads ctx.bundle.receipts directly, never ctx.view: a branch receipt is
+ * bounded by its branch, not by the date/provider filter bar (see
+ * viewReceipts in app.js). That also means this tab needs nothing from the
+ * server — everything here is already in the bundle the exporter embeds, so
+ * it works the same in the live dashboard and in a saved offline snapshot.
+ */
+import { el } from '../charts.js';
+import { compareBranches, pickDefault, findBranch } from '../../analytics/branch-compare.js';
+
+/** @typedef {import('./index.js').ViewContext} ViewContext */
+
+export const id = 'branches';
+export const label = 'Compare branches';
+export const order = 125;
+export const css = './styles/branches.css';
+
+const AXIS_TICKS = [
+  { position: -1, label: '1/4x or less' },
+  { position: -0.5, label: '1/2x' },
+  { position: 0, label: 'parity' },
+  { position: 0.5, label: '2x' },
+  { position: 1, label: '4x or more' },
+];
+
+/** `>= 10` rounds to a whole multiple; below that a decimal still means something. */
+function timesFmt(v) {
+  return `${v >= 10 ? Math.round(v) : v.toFixed(1)}x`;
+}
+
+function fmtByKind(ctx, kind, v) {
+  const { usd, int, pct } = ctx.fmt;
+  if (kind === 'cost') return usd(v);
+  if (kind === 'count') return int(v);
+  if (kind === 'share') return pct(v, 0);
+  if (kind === 'ratio') return timesFmt(v);
+  return String(v);
+}
+
+/** A value formatted for one end of a bar row; never a bare 0 for "missing". */
+function endText(ctx, row, value) {
+  return value === null || value === undefined ? '—' : fmtByKind(ctx, row.kind, value);
+}
+
+function modelsText(ctx, models) {
+  if (!models || !models.length) return null;
+  const top = models.slice(0, 3).map((m) => `${m.model} ${ctx.fmt.pct(m.share, 0)}`).join(', ');
+  return models.length > 3 ? `${top}, …` : top;
+}
+
+/**
+ * Read the persisted selection, or fall back to pickDefault() — checked
+ * against the current bundle every render, so a branch that disappeared
+ * after a refresh never leaves a dead selector behind.
+ * @param {ViewContext} ctx
+ * @param {object} receipts
+ * @returns {{a:{repo:string,key:string}, b:{repo:string,key:string}}|null}
+ */
+function ensureSelection(ctx, receipts) {
+  const valid = (ref) => ref && findBranch(receipts, ref.repo, ref.key);
+  const cur = ctx.S.branchCompare;
+  if (cur && valid(cur.a) && valid(cur.b)) return cur;
+  const def = pickDefault(receipts);
+  if (!def) return null;
+  ctx.S.branchCompare = def;
+  return def;
+}
+
+/**
+ * The Compare branches tab body.
+ * @param {ViewContext} ctx
+ * @returns {HTMLElement}
+ */
+export function view(ctx) {
+  const receipts = ctx.bundle.receipts;
+  const root = el('div', { class: 'grid' });
+
+  if (!receipts || !Array.isArray(receipts.repos) || !receipts.repos.length) {
+    root.appendChild(ctx.card('Compare branches', 'Any two branches, side by side.', ctx.emptyCard(
+      'No branch receipts yet',
+      'Receipts need sessions that recorded a git branch and a priced model. See the Receipts tab.',
+    )));
+    return root;
+  }
+
+  const sel = ensureSelection(ctx, receipts);
+  if (!sel) {
+    root.appendChild(ctx.card('Compare branches', 'Any two branches, side by side.', ctx.emptyCard(
+      'Need at least two branches to compare',
+      'Only one branch has been attributed to a receipt so far on this machine.',
+    )));
+    return root;
+  }
+
+  const a = findBranch(receipts, sel.a.repo, sel.a.key);
+  const b = findBranch(receipts, sel.b.repo, sel.b.key);
+
+  root.appendChild(selectorCard(ctx, receipts, sel, a, b));
+  root.appendChild(divergingCard(ctx, a, b));
+  root.appendChild(sideCards(ctx, sel, a, b));
+  root.appendChild(el('p', { class: 'hint branches-foot', text: 'Branch receipts are estimated from the logs on this machine. Cost per 100 lines needs a pull request join from the CLI.' }));
+  return root;
+}
+
+// ------------------------------------------------------------------ selectors
+
+function headerRow(sel, a, b) {
+  const row = el('div', { class: 'branches-head' });
+  const nameBlock = (repo, key, br) => {
+    const parts = [el('span', { class: 'branches-head-name', text: `${repo} · ${key}` })];
+    if (br && br.longLived) {
+      parts.push(el('span', { class: 'badge', text: 'long-lived', title: 'A branch that lives forever: this is a receipt for a period of work on it, not for one change.' }));
+    }
+    if (br && br.pr) parts.push(el('span', { class: 'badge', text: `PR #${br.pr.number}` }));
+    return el('div', {}, parts);
+  };
+  row.appendChild(nameBlock(sel.a.repo, sel.a.key, a));
+  row.appendChild(el('span', { class: 'branches-head-vs', text: 'vs' }));
+  row.appendChild(nameBlock(sel.b.repo, sel.b.key, b));
+  return row;
+}
+
+function sideSelector(ctx, receipts, sel, side) {
+  const wrap = el('div', { class: 'branches-side' });
+  wrap.appendChild(el('div', { class: 'branches-side-label', text: side === 'a' ? 'Side A' : 'Side B' }));
+  const fields = el('div', { class: 'branches-fields' });
+
+  const repoSel = el('select', { 'aria-label': `Repository ${side.toUpperCase()}` });
+  for (const R of receipts.repos) repoSel.appendChild(el('option', { value: R.repo, text: R.repo }));
+  repoSel.value = sel[side].repo;
+
+  const branchSel = el('select', { 'aria-label': `Branch ${side.toUpperCase()}` });
+  const fillBranches = (repoName) => {
+    branchSel.textContent = '';
+    const R = receipts.repos.find((r) => r.repo === repoName);
+    for (const br of (R ? R.branches : [])) {
+      branchSel.appendChild(el('option', { value: br.key, text: `${br.key} · ${br.cost === null ? '—' : ctx.fmt.usd(br.cost)}` }));
+    }
+  };
+  fillBranches(sel[side].repo);
+  branchSel.value = sel[side].key;
+
+  repoSel.addEventListener('change', () => {
+    fillBranches(repoSel.value);
+    const R = receipts.repos.find((r) => r.repo === repoSel.value);
+    const firstKey = R && R.branches.length ? R.branches[0].key : null;
+    if (!firstKey) return;
+    ctx.S.branchCompare = { ...ctx.S.branchCompare, [side]: { repo: repoSel.value, key: firstKey } };
+    ctx.rerender({ recompute: false });
+  });
+  branchSel.addEventListener('change', () => {
+    ctx.S.branchCompare = { ...ctx.S.branchCompare, [side]: { repo: repoSel.value, key: branchSel.value } };
+    ctx.rerender({ recompute: false });
+  });
+
+  fields.appendChild(repoSel);
+  fields.appendChild(branchSel);
+  wrap.appendChild(fields);
+  return wrap;
+}
+
+function selectorCard(ctx, receipts, sel, a, b) {
+  const body = el('div');
+  body.appendChild(headerRow(sel, a, b));
+  const selRow = el('div', { class: 'branches-select-row' });
+  selRow.appendChild(sideSelector(ctx, receipts, sel, 'a'));
+  selRow.appendChild(sideSelector(ctx, receipts, sel, 'b'));
+  body.appendChild(selRow);
+  return ctx.card(
+    'Compare branches',
+    "Any two branches, side by side. Defaults to the most expensive feature branch against the median-cost feature branch in the same repository.",
+    body,
+  );
+}
+
+// -------------------------------------------------------------- diverging bar
+
+function barColor(position, side) {
+  const p = Math.abs(position);
+  if (p < 0.1) return 'var(--div-3)';
+  if (p < 0.5) return side === 'a' ? 'var(--div-2)' : 'var(--div-4)';
+  return side === 'a' ? 'var(--div-1)' : 'var(--div-5)';
+}
+
+function axisRow() {
+  const row = el('div', { class: 'branches-axis' });
+  row.appendChild(el('div', { class: 'branches-axis-spacer' }));
+  row.appendChild(el('div', { class: 'branches-axis-ends' }));
+  const track = el('div', { class: 'branches-axis-track' });
+  for (const t of AXIS_TICKS) {
+    const tick = el('div', { class: 'branches-axis-tick', text: t.label });
+    tick.style.left = `${((t.position + 1) / 2) * 100}%`;
+    track.appendChild(tick);
+  }
+  row.appendChild(track);
+  row.appendChild(el('div', { class: 'branches-axis-ends' }));
+  return row;
+}
+
+function barRow(ctx, row) {
+  const wrap = el('div', { class: 'branches-row' });
+  wrap.appendChild(el('div', { class: 'branches-row-label', text: row.label }));
+  const bar = el('div', { class: 'branches-bar' });
+  bar.appendChild(el('span', { class: 'branches-end branches-end-a', text: endText(ctx, row, row.valueA) }));
+
+  const track = el('div', { class: 'branches-track' });
+  const halfA = el('div', { class: 'branches-half branches-half-a' });
+  const halfB = el('div', { class: 'branches-half branches-half-b' });
+  if (row.position !== null) {
+    const fill = el('div', { class: 'branches-fill' });
+    fill.style.width = `${Math.abs(row.position) * 100}%`;
+    if (row.position >= 0) {
+      fill.style.background = barColor(row.position, 'a');
+      halfA.appendChild(fill);
+    } else {
+      fill.style.background = barColor(row.position, 'b');
+      halfB.appendChild(fill);
+    }
+  }
+  track.appendChild(halfA);
+  track.appendChild(el('div', { class: 'branches-centre' }));
+  track.appendChild(halfB);
+  bar.appendChild(track);
+
+  bar.appendChild(el('span', { class: 'branches-end branches-end-b', text: endText(ctx, row, row.valueB) }));
+  wrap.appendChild(bar);
+  return wrap;
+}
+
+function legendRow() {
+  const row = el('div', { class: 'branches-legend' });
+  const swatch = (color) => el('span', { class: 'branches-swatch', style: `background:${color}` });
+  row.appendChild(el('span', {}, [swatch('var(--div-1)'), 'A costs more']));
+  row.appendChild(el('span', {}, [swatch('var(--div-3)'), 'parity']));
+  row.appendChild(el('span', {}, [swatch('var(--div-5)'), 'B costs more']));
+  return row;
+}
+
+function renderDivergingChart(ctx, rows) {
+  const root = el('div');
+  root.appendChild(axisRow());
+  for (const row of rows) root.appendChild(barRow(ctx, row));
+  root.appendChild(legendRow());
+  return root;
+}
+
+function tableCell(ctx, row, value) {
+  if (row.kind === 'models') return modelsText(ctx, value);
+  return value === null || value === undefined ? null : fmtByKind(ctx, row.kind, value);
+}
+
+function divergingCard(ctx, a, b) {
+  const rows = compareBranches(a, b);
+  const barRows = rows.filter((r) => r.kind !== 'models');
+  const tableSpec = {
+    columns: [
+      { key: 'label', label: 'Metric', text: true, value: (r) => r.label },
+      { key: 'a', label: 'A', value: (r) => tableCell(ctx, r, r.valueA) },
+      { key: 'b', label: 'B', value: (r) => tableCell(ctx, r, r.valueB) },
+      { key: 'ratio', label: 'Ratio (A / B)', value: (r) => (r.ratio === null ? null : timesFmt(r.ratio)) },
+    ],
+    rows,
+  };
+  return ctx.chartCard(
+    'branches-diverging',
+    'Branch comparison',
+    'A on the left, B on the right. Bar length is a symmetric log scale: twice as expensive moves the same distance whichever side it is on.',
+    () => renderDivergingChart(ctx, barRows),
+    tableSpec,
+  );
+}
+
+// ------------------------------------------------------------------ side cards
+
+function sideSummary(ctx, sideLabel, repo, key, br) {
+  const { usd, pct, int, shortDate } = ctx.fmt;
+  const card = el('div', { class: 'branches-side-card' });
+  card.appendChild(el('h4', { text: `${sideLabel}: ${repo} · ${key}` }));
+  if (!br) {
+    card.appendChild(el('p', { text: 'This branch is no longer in the receipt store.' }));
+    return card;
+  }
+  const costText = usd(br.cost);
+  const shareText = br.contextShare === null ? '' : ` (${pct(br.contextShare, 0)} re-sent context, ${pct(1 - br.contextShare, 0)} fresh work)`;
+  card.appendChild(el('p', { text: `${costText} across ${int(br.sessions)} session(s) and ${int(br.turns)} turn(s)${shareText}.` }));
+  if (br.subagentTurns > 0) card.appendChild(el('p', { text: `${pct(br.subagentShare, 0)} of turns ran as a subagent.` }));
+  const modelsLine = modelsText(ctx, br.models);
+  if (modelsLine) card.appendChild(el('p', { text: `Models: ${modelsLine}.` }));
+  if (br.vsMedian !== null) card.appendChild(el('p', { text: `${timesFmt(br.vsMedian)} this repo's median branch cost.` }));
+  if (br.first && br.last) card.appendChild(el('p', { text: `Active ${shortDate(br.first.slice(0, 10))} to ${shortDate(br.last.slice(0, 10))}.` }));
+  if (br.longLived) card.appendChild(el('p', { text: 'Long-lived branch: this is a receipt for a period of work on it, not for one change.' }));
+  if (br.pr) card.appendChild(el('p', { text: `PR #${br.pr.number}${br.pr.mergedAt ? ` merged ${shortDate(br.pr.mergedAt.slice(0, 10))}` : ' still open'}.` }));
+  return card;
+}
+
+function sideCards(ctx, sel, a, b) {
+  const wrap = el('div', { class: 'branches-side-cards' });
+  wrap.appendChild(sideSummary(ctx, 'A', sel.a.repo, sel.a.key, a));
+  wrap.appendChild(sideSummary(ctx, 'B', sel.b.repo, sel.b.key, b));
+  return ctx.card('Receipts', "The same numbers as the Receipts tab, for just these two branches.", wrap);
+}

package/src/ui/views/cache.js

@@ -0,0 +1,232 @@
+/**
+ * The Cache health tab: is the prompt cache doing its job.
+ *
+ * The prompt cache is where most of the money goes: a cache hit is cheap, a
+ * cache miss re-sends the whole context. Two halves, kept apart on purpose:
+ *
+ *  - hit rate, write split and the per-model table come from the cube
+ *    (ctx.view), so they work offline, in a snapshot, everywhere.
+ *  - churn events come from request-level records through /api/cache-health,
+ *    so they are live-dashboard only. A snapshot shows why instead of a dead
+ *    control (see docs/ui-views.md, "Working offline").
+ */
+import { el, timeSeries } from '../charts.js';
+import { hitRateSeries, writeSplitSeries } from '../../analytics/cache-health.js';
+
+/** @typedef {import('./index.js').ViewContext} ViewContext */
+
+export const id = 'cache';
+export const label = 'Cache health';
+export const order = 95;
+export const css = './styles/cache.css';
+
+/**
+ * Fetch state for the churn card, kept in the module rather than in `ctx.S`
+ * because the churn endpoint has nothing to do with the global filter bar
+ * beyond the date window. `key` is the from/to pair the current data (or
+ * in-flight fetch) answers; `view()` compares it on every render and starts
+ * a new fetch only when it changed.
+ */
+let churn = { key: null, status: 'idle', data: null, error: null };
+
+function dateKey(filters) {
+  return `${filters.from || ''}|${filters.to || ''}`;
+}
+
+/**
+ * Start (or skip) the churn fetch for the current date filters.
+ * @param {ViewContext} ctx
+ */
+function ensureChurn(ctx) {
+  if (ctx.snapshot) {
+    if (churn.status !== 'unavailable') churn = { key: 'snapshot', status: 'unavailable', data: null, error: null };
+    return;
+  }
+  const key = dateKey(ctx.filters);
+  if (churn.key === key && churn.status !== 'idle') return;
+  churn = { key, status: 'loading', data: null, error: null };
+  const q = new URLSearchParams();
+  if (ctx.filters.from) q.set('from', ctx.filters.from);
+  if (ctx.filters.to) q.set('to', ctx.filters.to);
+  ctx.fetchJson(`/api/cache-health?${q.toString()}`)
+    .then((data) => {
+      if (churn.key !== key) return; // superseded by a newer filter change
+      churn = { key, status: 'ready', data, error: null };
+      ctx.rerender({ recompute: false });
+    })
+    .catch((err) => {
+      if (churn.key !== key) return;
+      churn = { key, status: 'error', data: null, error: err && err.message ? err.message : String(err) };
+      ctx.rerender({ recompute: false });
+    });
+}
+
+/** @param {ViewContext} ctx */
+export function onEnter(ctx) {
+  ensureChurn(ctx);
+}
+
+/** @param {ViewContext} ctx */
+export function view(ctx) {
+  ensureChurn(ctx);
+  const root = el('div', { class: 'grid' });
+  root.appendChild(kpiRow(ctx));
+  root.appendChild(hitRateCard(ctx));
+  root.appendChild(writeSplitCard(ctx));
+  root.appendChild(modelTableCard(ctx));
+  root.appendChild(churnCard(ctx));
+  return root;
+}
+
+function kpiRow(ctx) {
+  const { pct, usd, int } = ctx.fmt;
+  const t = ctx.view.totals;
+  const hitRate = (t.cr + t.in) > 0 ? t.cr / (t.cr + t.in) : null;
+  const writeShare = t.cw > 0 ? t.cf / t.cw : null;
+
+  const box = el('div', { class: 'cards' });
+  box.appendChild(ctx.kpi('Cache hit rate', pct(hitRate, 1), 'cache_read / (cache_read + input), current filters'));
+  box.appendChild(ctx.kpi('Long-TTL write share', pct(writeShare, 1), 'cache_refresh / cache_write, current filters'));
+
+  const snapshotSub = ctx.snapshot ? 'live dashboard only' : null;
+  const errorSub = churn.status === 'error' ? 'failed to load' : null;
+  const eventsValue = ctx.snapshot ? '—'
+    : churn.status === 'ready' ? int(churn.data.summary.totalEvents)
+    : churn.status === 'error' ? '—'
+    : '…';
+  box.appendChild(ctx.kpi('Churn events', eventsValue, snapshotSub || errorSub));
+
+  const premiumValue = ctx.snapshot ? '—'
+    : churn.status === 'ready' ? usd(churn.data.summary.totalPremiumUsd)
+    : churn.status === 'error' ? '—'
+    : '…';
+  box.appendChild(ctx.kpi('Churn premium (estimated)', premiumValue, snapshotSub || errorSub));
+  return box;
+}
+
+function hitRateCard(ctx) {
+  const { shortDate, pct } = ctx.fmt;
+  const rows = hitRateSeries(ctx.view.daily);
+  const renderChart = (w) => timeSeries({
+    data: rows.map((r) => ({ key: r.date })),
+    keys: [],
+    overlays: [{ values: rows.map((r) => r.hitRate), label: 'Hit rate', color: 'var(--series-1)' }],
+    fmtY: (v) => pct(v, 0),
+    fmtX: (k) => shortDate(k),
+    fmtXLong: (k) => shortDate(k),
+    width: w,
+    height: 220,
+    ariaLabel: 'Daily cache hit rate',
+  });
+  const tableSpec = {
+    columns: [
+      { key: 'date', label: 'Date', text: true, value: (r) => shortDate(r.date) },
+      { key: 'hitRate', label: 'Hit rate', value: (r) => (r.hitRate === null ? null : pct(r.hitRate, 1)) },
+    ],
+    rows,
+  };
+  return ctx.chartCard(
+    'cache-hit-rate',
+    'Cache hit rate over time',
+    'Daily cache_read / (cache_read + input) for the current filters. A day with no input or cache tokens shows no value, not 0%.',
+    renderChart,
+    tableSpec,
+  );
+}
+
+function writeSplitCard(ctx) {
+  const { shortDate, compact } = ctx.fmt;
+  const rows = writeSplitSeries(ctx.view.daily);
+  const keys = [
+    { key: 'shortTTL', label: 'Short-TTL writes', color: 'var(--series-1)' },
+    { key: 'longTTL', label: 'Long-TTL writes', color: 'var(--series-2)' },
+  ];
+  const renderChart = (w) => timeSeries({
+    data: rows.map((r) => ({ key: r.date, shortTTL: r.shortTTL, longTTL: r.longTTL })),
+    keys,
+    mode: 'stacked',
+    fmtY: (v) => compact(v),
+    fmtX: (k) => shortDate(k),
+    fmtXLong: (k) => shortDate(k),
+    width: w,
+    height: 220,
+    ariaLabel: 'Daily cache write split, short-TTL versus long-TTL',
+  });
+  const tableSpec = {
+    columns: [
+      { key: 'date', label: 'Date', text: true, value: (r) => shortDate(r.date) },
+      { key: 'shortTTL', label: 'Short-TTL writes', value: (r) => compact(r.shortTTL) },
+      { key: 'longTTL', label: 'Long-TTL writes', value: (r) => compact(r.longTTL) },
+    ],
+    rows,
+  };
+  return ctx.chartCard(
+    'cache-write-split',
+    'Cache write split',
+    'Short-TTL cache writes (cache_write minus cache_refresh) against long-TTL writes (cache_refresh), stacked by day.',
+    renderChart,
+    tableSpec,
+  );
+}
+
+function modelTableCard(ctx) {
+  const { pct, int } = ctx.fmt;
+  const rows = (ctx.view.dimensions.models || []).map((m) => {
+    const denom = (m.cacheRead || 0) + (m.input || 0);
+    return {
+      model: m.key,
+      provider: m.provider,
+      hitRate: denom > 0 ? m.cacheRead / denom : null,
+      requests: m.requests,
+    };
+  });
+  const tbl = ctx.charts.table([
+    { key: 'model', label: 'Model', text: true },
+    { key: 'provider', label: 'Provider', text: true },
+    { key: 'hitRate', label: 'Hit rate', value: (r) => (r.hitRate === null ? null : pct(r.hitRate, 1)) },
+    { key: 'requests', label: 'Requests', value: (r) => int(r.requests) },
+  ], rows, { emptyText: 'No models match the current filters.' });
+  return ctx.card('Cache hit rate by model', 'cache_read / (cache_read + input) per model, for the current filters.', tbl);
+}
+
+function churnCard(ctx) {
+  if (ctx.snapshot) {
+    return ctx.emptyCard(
+      'Churn events need the live dashboard.',
+      'Churn detection reads request records, which stay on the machine. Open the live dashboard to see them.',
+    );
+  }
+
+  const { int, usd } = ctx.fmt;
+  const columns = [
+    { key: 'sessionId', label: 'Session', text: true, value: (r) => (r.sessionId ? String(r.sessionId).slice(0, 12) : null) },
+    { key: 'project', label: 'Project', text: true },
+    { key: 'branch', label: 'Branch', text: true },
+    { key: 'turnIndex', label: 'Turn', value: (r) => int(r.turnIndex) },
+    { key: 'writeTokens', label: 'Write tokens', value: (r) => int(r.writeTokens) },
+    { key: 'previousReadTokens', label: 'Previous read', value: (r) => int(r.previousReadTokens) },
+    { key: 'premiumUsd', label: 'Premium (estimated)', value: (r) => (r.premiumUsd === null ? null : usd(r.premiumUsd)) },
+    { key: 'timestamp', label: 'When', value: (r) => (r.timestamp ? r.timestamp.replace('T', ' ').slice(0, 19) : null) },
+  ];
+
+  let rows = [];
+  let emptyText = 'No churn events in the current window.';
+  let note = null;
+  if (churn.status === 'loading' || churn.status === 'idle') {
+    emptyText = 'Loading churn events...';
+  } else if (churn.status === 'error') {
+    emptyText = `Could not load churn events: ${churn.error}`;
+  } else if (churn.data) {
+    // The route already sorts by estimated premium, highest first.
+    rows = (churn.data.events || []).slice(0, 20);
+    if (churn.data.truncated) {
+      note = `Scan capped at ${int(churn.data.scanned)} records. Some churn events may be missed.`;
+    }
+  }
+
+  const body = el('div');
+  body.appendChild(el('p', { class: 'hint', text: 'A churn event is a turn whose cache write is at least 10,000 tokens. It is also at least half of the previous turn\'s cache read in the same session. That pattern means the cache was invalidated and rewritten, for example when a system prompt changes.' }));
+  if (note) body.appendChild(el('p', { class: 'hint cache-status', text: note }));
+  body.appendChild(ctx.charts.table(columns, rows, { emptyText }));
+  return ctx.card('Churn events', 'Top 20 by estimated cost premium.', body);
+}

package/src/ui/views/index.js

@@ -0,0 +1,85 @@
+/**
+ * The dashboard view registry.
+ *
+ * A registered view is a whole tab that lives outside app.js: one module in
+ * this directory, one stylesheet under src/ui/styles/, and nothing else. app.js
+ * merges this list with its built-in tabs and dispatches to it, so adding a tab
+ * never means editing app.js — which is what lets several tabs be written at
+ * the same time without a merge conflict in one 2600-line file.
+ *
+ * A view module must NOT import app.js. It receives everything it may use as a
+ * ViewContext argument. That keeps the module graph acyclic, which the offline
+ * snapshot bundler (src/export/bundler.js) requires.
+ *
+ * The full contract, including how a view degrades offline, is in
+ * docs/ui-views.md.
+ */
+import * as live from './live.js';
+import * as cache from './cache.js';
+import * as annotations from './annotations.js';
+import * as branches from './branches.js';
+import * as anatomy from './anatomy.js';
+import * as whatif from './whatif.js';
+import * as rhythm from './rhythm.js';
+
+/**
+ * Everything a view is allowed to use from the host application.
+ *
+ * app.js rebuilds this object for every render, and `bundle`, `view`, `filters`
+ * and `live` are getters over the live state, so a ctx captured in a closure
+ * (a timer, an event handler) never reads a stale value.
+ *
+ * @typedef {object} ViewContext
+ * @property {object} S dashboard state. Read freely; write only fields you own.
+ * @property {object} bundle the aggregate bundle this page was loaded with.
+ * @property {object} view the computed analytics view for the current filters.
+ * @property {object} filters the active filter object (same object as `S.filters`).
+ * @property {boolean} snapshot true when running from an offline HTML snapshot.
+ * @property {(tag:string, attrs?:object, kids?:any)=>any} el build a DOM element.
+ * @property {(title:string, hint:string, body:any, actions?:any)=>any} card
+ * @property {(id:string, title:string, hint:string, renderChart:(w:number)=>any, tableSpec?:object, extraActions?:any)=>any} chartCard chart with its mandatory table twin.
+ * @property {(label:string, onClick:(ev:any)=>void, cls?:string, id?:string)=>any} btn
+ * @property {(label:string, value:string, sub?:any, opt?:object)=>any} kpi
+ * @property {(change:number|null, opt?:{goodUp?:boolean})=>any} deltaChip
+ * @property {(t:string)=>any} sectionTitle
+ * @property {(text:string, detail?:string)=>any} emptyCard
+ * @property {(title:string, body:any, foot?:any)=>void} openModal
+ * @property {()=>void} closeModal
+ * @property {(key:string, value:string)=>void} drillTo filter to one value and re-render.
+ * @property {object} fmt the number and date formatters from core/units.js.
+ * @property {object} charts namespace import of src/ui/charts.js.
+ * @property {(path:string, opt?:object)=>Promise<any>} fetchJson resolves to null in a snapshot.
+ * @property {(fn:()=>void, ms:number)=>any} schedule an interval app.js clears for you.
+ * @property {(opt?:{recompute?:boolean})=>void} rerender recompute and repaint.
+ */
+
+/**
+ * One tab. `id`, `label`, `order` and `view` are required; the rest optional.
+ *
+ * `order` places the tab: the built-in tabs hold 10, 20, 40 … 140, so a view
+ * can slot anywhere by picking a number between them. `css` is a path relative
+ * to src/ui/ and must point at a single file under src/ui/styles/.
+ *
+ * @typedef {object} ViewModule
+ * @property {string} id unique, and never one of app.js's built-in tab ids.
+ * @property {string} label the tab caption.
+ * @property {number} order position among all tabs.
+ * @property {string} [css] e.g. './styles/live.css'.
+ * @property {(ctx: ViewContext) => any} view returns the element for the tab body.
+ * @property {(ctx: ViewContext) => void} [onEnter] the tab became active.
+ * @property {(ctx: ViewContext) => void} [onLeave] the tab stopped being active.
+ */
+
+/**
+ * Every registered view, in registration order. app.js sorts by `order`.
+ * @type {ViewModule[]}
+ */
+export const VIEWS = [
+  live,
+  cache,
+  annotations,
+  branches,
+  anatomy,
+  whatif,
+  rhythm,
+];