@seanmars/tospec 0.4.2

package/assets/dashboard/app.js

@@ -0,0 +1,1032 @@
+// tospec dashboard — vanilla SPA. No framework, no build, no external resources.
+// Charts: vendored Chart.js (assets/chart.umd.js), themed via CSS variables.
+
+const view = document.getElementById('view');
+const rootPathEl = document.getElementById('root-path');
+const connEl = document.getElementById('conn-status');
+const refreshBtn = document.getElementById('refresh-btn');
+const themeSelect = document.getElementById('theme-select');
+
+let overview = null; // cached /api/overview payload
+let activity = null; // cached /api/activity payload (git series + health)
+let activityRange = '30'; // '30' | '90' | '365' | 'all' — overview chart window
+
+// --- theme (persisted choice: system | light | dark | dracula) -------------
+
+const THEME_KEY = 'tospec-theme';
+const systemDark = window.matchMedia('(prefers-color-scheme: dark)');
+
+// Apply a user choice: 'system' resolves to light/dark from the OS; the rest
+// map straight to a data-theme value.
+function applyTheme(choice) {
+  const resolved = choice === 'system' ? (systemDark.matches ? 'dark' : 'light') : choice;
+  document.documentElement.setAttribute('data-theme', resolved);
+  themeSelect.value = choice;
+}
+
+const savedTheme = localStorage.getItem(THEME_KEY) || 'system';
+applyTheme(savedTheme);
+
+// Theme switches rebuild the route: charts read CSS variables at build time,
+// so they must be recreated to pick up the new palette (rare event, morph
+// loss is fine). The initial applyTheme above must NOT rebuild — chart state
+// (liveCharts, ov) is declared further down and would still be in its TDZ.
+systemDark.addEventListener('change', () => {
+  if ((localStorage.getItem(THEME_KEY) || 'system') === 'system') {
+    applyTheme('system');
+    rebuildRoute();
+  }
+});
+themeSelect.addEventListener('change', () => {
+  localStorage.setItem(THEME_KEY, themeSelect.value);
+  applyTheme(themeSelect.value);
+  rebuildRoute();
+});
+
+// --- tiny helpers ----------------------------------------------------------
+
+async function api(path, options) {
+  const res = await fetch(path, options);
+  if (!res.ok) {
+    let detail = 'HTTP ' + res.status;
+    try {
+      const body = await res.json();
+      if (body && body.error) detail = body.error;
+    } catch {
+      // no JSON body; keep the status line
+    }
+    const err = new Error(detail);
+    err.status = res.status;
+    throw err;
+  }
+  return res.json();
+}
+
+/** Writes a task checkbox back to its markdown file. */
+function postTask(file, line, done) {
+  return api('/api/task', {
+    method: 'POST',
+    headers: { 'content-type': 'application/json' },
+    body: JSON.stringify({ file, line, done }),
+  });
+}
+
+/** Minimal DOM builder; all text goes in as textContent (XSS-safe). */
+function el(tag, props = {}, children = []) {
+  const node = document.createElement(tag);
+  for (const [k, v] of Object.entries(props)) {
+    if (v == null) continue;
+    if (k === 'class') node.className = v;
+    else if (k === 'text') node.textContent = v;
+    else node.setAttribute(k, v);
+  }
+  for (const child of [].concat(children)) {
+    if (child == null) continue;
+    node.append(child.nodeType ? child : document.createTextNode(String(child)));
+  }
+  return node;
+}
+
+function emptyNote(text) {
+  return el('p', { class: 'empty', text });
+}
+
+function relTime(iso) {
+  const then = new Date(iso).getTime();
+  if (Number.isNaN(then)) return '';
+  const mins = Math.floor((Date.now() - then) / 60000);
+  const hours = Math.floor(mins / 60);
+  const days = Math.floor(hours / 24);
+  if (days > 30) return new Date(iso).toLocaleDateString();
+  if (days > 0) return days + 'd ago';
+  if (hours > 0) return hours + 'h ago';
+  if (mins > 0) return mins + 'm ago';
+  return 'just now';
+}
+
+/** `20260713_123649` -> `2026-07-13 12:36`. */
+function fmtStamp(s) {
+  const m = /^(\d{4})(\d{2})(\d{2})_(\d{2})(\d{2})(\d{2})$/.exec(s || '');
+  return m ? `${m[1]}-${m[2]}-${m[3]} ${m[4]}:${m[5]}` : s || '';
+}
+
+function typeBadge(type) {
+  const label = type === 'requirement' ? 'sdd' : type || '?';
+  return el('span', { class: 'badge badge-' + (type || 'unknown'), text: label });
+}
+
+function artifactBlocks(done, total) {
+  const wrap = el('span', { class: 'blocks' });
+  for (let i = 0; i < total; i++) {
+    wrap.append(el('span', { class: 'block ' + (i < done ? 'block-done' : 'block-todo') }));
+  }
+  return wrap;
+}
+
+function setConnected(ok) {
+  connEl.textContent = ok ? '' : 'disconnected';
+  connEl.classList.toggle('disconnected', !ok);
+}
+
+// --- charts (Chart.js, themed via CSS variables) ----------------------------
+
+const hasChart = typeof Chart !== 'undefined';
+const liveCharts = new Set();
+
+function cssVar(name) {
+  return getComputedStyle(document.documentElement).getPropertyValue(name).trim();
+}
+
+function newChart(canvas, config) {
+  const chart = new Chart(canvas, config);
+  liveCharts.add(chart);
+  return chart;
+}
+
+function destroyCharts() {
+  for (const chart of liveCharts) chart.destroy();
+  liveCharts.clear();
+}
+
+/** Shared recessive axes/legend styling read from the active theme. */
+function chartTheme() {
+  return {
+    text: cssVar('--text'),
+    muted: cssVar('--muted'),
+    grid: cssVar('--border'),
+    surface: cssVar('--surface'),
+    series1: cssVar('--chart-1'),
+    series2: cssVar('--chart-2'),
+    done: cssVar('--done'),
+    ready: cssVar('--ready'),
+    blocked: cssVar('--blocked'),
+    track: cssVar('--border'),
+  };
+}
+
+/** Doughnut center text (e.g. "68%"), drawn in the theme's text color. */
+const centerTextPlugin = {
+  id: 'centerText',
+  afterDraw(chart, _args, opts) {
+    if (!opts || !opts.text) return;
+    const meta = chart.getDatasetMeta(0);
+    const arc = meta.data[0];
+    if (!arc) return;
+    const { ctx } = chart;
+    ctx.save();
+    ctx.font = '600 16px system-ui, sans-serif';
+    ctx.fillStyle = opts.color;
+    ctx.textAlign = 'center';
+    ctx.textBaseline = 'middle';
+    ctx.fillText(opts.text, arc.x, arc.y);
+    ctx.restore();
+  },
+};
+if (hasChart) Chart.register(centerTextPlugin);
+
+/** 30-day activity line chart: solid tospec series + dashed repo context. */
+function buildActivityChart(canvas, tospecLabel) {
+  const t = chartTheme();
+  return newChart(canvas, {
+    type: 'line',
+    data: {
+      labels: [],
+      datasets: [
+        {
+          label: tospecLabel,
+          data: [],
+          borderColor: t.series1,
+          backgroundColor: t.series1,
+          borderWidth: 2,
+          pointRadius: 2,
+          pointHitRadius: 10,
+          tension: 0.2,
+        },
+        {
+          label: 'all commits',
+          data: [],
+          borderColor: t.series2,
+          backgroundColor: t.series2,
+          borderWidth: 2,
+          borderDash: [5, 4], // secondary encoding: identity is never color-alone
+          pointRadius: 2,
+          pointHitRadius: 10,
+          tension: 0.2,
+        },
+      ],
+    },
+    options: {
+      responsive: true,
+      maintainAspectRatio: false,
+      interaction: { mode: 'index', intersect: false },
+      plugins: {
+        legend: { labels: { color: t.muted, boxWidth: 18, boxHeight: 2 } },
+        tooltip: { intersect: false },
+      },
+      scales: {
+        x: {
+          ticks: { color: t.muted, maxTicksLimit: 8, maxRotation: 0 },
+          grid: { display: false },
+        },
+        y: {
+          beginAtZero: true,
+          ticks: { color: t.muted, precision: 0 },
+          grid: { color: t.grid },
+        },
+      },
+    },
+  });
+}
+
+function updateActivityChart(chart, days) {
+  // mm-dd is ambiguous once the window spans more than a year.
+  const short = days.length <= 366;
+  chart.data.labels = days.map((d) => (short ? d.date.slice(5) : d.date));
+  chart.data.datasets[0].data = days.map((d) => d.tospec);
+  chart.data.datasets[1].data = days.map((d) => d.repo);
+  chart.update();
+}
+
+/** Status doughnut (done/ready/blocked) with a completion % in the center. */
+function buildStatusDoughnut(canvas, labels, colors) {
+  const t = chartTheme();
+  return newChart(canvas, {
+    type: 'doughnut',
+    data: {
+      labels,
+      datasets: [
+        {
+          data: labels.map(() => 0),
+          backgroundColor: colors,
+          borderColor: t.surface, // 2px surface gap between segments
+          borderWidth: 2,
+        },
+      ],
+    },
+    options: {
+      responsive: true,
+      maintainAspectRatio: false,
+      cutout: '70%',
+      plugins: {
+        legend: { position: 'bottom', labels: { color: t.muted, boxWidth: 10 } },
+        centerText: { text: '', color: t.text },
+      },
+    },
+  });
+}
+
+function updateStatusDoughnut(chart, values, centerText) {
+  chart.data.datasets[0].data = values;
+  chart.options.plugins.centerText.text = centerText;
+  chart.update();
+}
+
+// --- dynamics (count-up, flash) ---------------------------------------------
+
+/** Animates an element's number from its last shown value to `to` (~400ms). */
+function countUp(node, to) {
+  const from = Number(node.dataset.value || 0);
+  node.dataset.value = String(to);
+  if (from === to) {
+    node.textContent = String(to);
+    return;
+  }
+  const start = performance.now();
+  const dur = 400;
+  function tick(now) {
+    const p = Math.min(1, (now - start) / dur);
+    const eased = 1 - (1 - p) * (1 - p);
+    node.textContent = String(Math.round(from + (to - from) * eased));
+    if (p < 1) requestAnimationFrame(tick);
+  }
+  requestAnimationFrame(tick);
+}
+
+/** Briefly highlights a row after an SSE-driven change. */
+function flash(node) {
+  node.classList.add('flash');
+  node.addEventListener('animationend', () => node.classList.remove('flash'), { once: true });
+}
+
+// Previous snapshots keyed for change detection (what to flash after updates).
+let prevChangeStamps = null; // Map<name, lastModified>
+let prevTicketFiles = null; // Set<file>
+
+// --- data loading ------------------------------------------------------------
+
+async function loadOverview() {
+  try {
+    overview = await api('/api/overview');
+    setConnected(true);
+    rootPathEl.textContent = overview.root;
+    rootPathEl.setAttribute('title', overview.root);
+    if (isOverviewRoute()) renderOverview();
+  } catch (e) {
+    setConnected(false);
+    if (isOverviewRoute() && !overview) {
+      const msg = e.status
+        ? `Failed to load overview: ${e.message}`
+        : 'Cannot reach the dashboard server.';
+      view.replaceChildren(el('p', { class: 'error', text: msg }));
+    }
+  }
+}
+
+async function loadActivity() {
+  try {
+    activity = await api('/api/activity?days=' + activityRange);
+  } catch {
+    activity = null; // health strip and charts degrade below
+  }
+  if (isOverviewRoute()) renderOverview();
+}
+
+// --- overview: skeleton + update ---------------------------------------------
+
+// The overview keeps one DOM skeleton alive across data refreshes so chart
+// instances survive and Chart.js morphs to new values (SSE-driven dynamics).
+let ov = null;
+
+function card(label) {
+  const count = el('span', { class: 'card-count', text: '0' });
+  const node = el('div', { class: 'card' }, [
+    count,
+    el('span', { class: 'card-label', text: label }),
+  ]);
+  return { node, count };
+}
+
+function chartPanel(title, height) {
+  const canvas = el('canvas');
+  const wrap = el('div', { class: 'chart-wrap' }, [canvas]);
+  wrap.style.height = height + 'px';
+  const note = el('p', { class: 'empty chart-note', text: '' });
+  note.style.display = 'none';
+  const panel = el('div', { class: 'chart-panel' }, [
+    el('h2', { class: 'section-title', text: title }),
+    wrap,
+    note,
+  ]);
+  return { panel, canvas, wrap, note };
+}
+
+// --- task progress -----------------------------------------------------------
+
+// Names of changes whose task list is expanded. Module-level so an SSE refresh,
+// which rebuilds these rows, doesn't collapse what the user opened.
+const expandedTasks = new Set();
+
+/**
+ * One task, as a checkbox that writes straight back to its markdown file. The
+ * file is the source of truth: a failed write reverts the box rather than
+ * leaving the UI claiming something the file doesn't say.
+ */
+function taskItem(task) {
+  const item = el('label', { class: 'task-item' + (task.done ? ' task-item-done' : '') });
+  // Mirror the file's own nesting; 2 spaces of markdown indent reads as one step.
+  if (task.indent) item.style.marginLeft = task.indent * 8 + 'px';
+  const box = el('input', { type: 'checkbox', class: 'task-box' });
+  box.checked = task.done;
+  item.append(box, el('span', { class: 'task-text', text: task.text }));
+
+  box.addEventListener('change', async () => {
+    const want = box.checked;
+    box.disabled = true;
+    item.querySelectorAll('.task-error').forEach((n) => n.remove());
+    try {
+      await postTask(task.file, task.line, want);
+      item.classList.toggle('task-item-done', want);
+      // The file watcher normally refreshes us; reload anyway so the counts move
+      // even where the watch is unavailable.
+      await loadOverview();
+    } catch (e) {
+      box.checked = !want;
+      item.append(el('span', { class: 'task-error', text: 'save failed: ' + e.message }));
+    } finally {
+      box.disabled = false;
+    }
+  });
+  return item;
+}
+
+/** A change's tasks, headed by their file path only when they span several. */
+function taskListBody(change) {
+  const body = el('div', { class: 'task-body' });
+  const files = [...new Set(change.tasks.map((t) => t.file))];
+  for (const file of files) {
+    if (files.length > 1) body.append(el('p', { class: 'task-file mono', text: file }));
+    for (const task of change.tasks) {
+      if (task.file === file) body.append(taskItem(task));
+    }
+  }
+  return body;
+}
+
+/** Collapsed: name + bar + `x/y`. Expanded: every task, each one clickable. */
+function taskChangeRow(c) {
+  const { completed, total } = c.taskProgress;
+  if (total === 0) {
+    return el('div', { class: 'row task-none' }, [
+      el('span', { class: 'row-name', text: c.name }),
+      el('span', { class: 'row-meta', text: 'no tasks' }),
+    ]);
+  }
+  const details = el('details', { class: 'task-change' });
+  if (expandedTasks.has(c.name)) details.setAttribute('open', '');
+  details.append(
+    el('summary', {}, [
+      el('span', { class: 'row-name', text: c.name }),
+      el('progress', { class: 'task-bar', value: String(completed), max: String(total) }),
+      el('span', { class: 'task-count', text: completed + '/' + total }),
+      c.artifactSummary.blocked > 0
+        ? el('span', { class: 'badge badge-blocked-warn', text: 'blocked' })
+        : null,
+    ]),
+    taskListBody(c)
+  );
+  details.addEventListener('toggle', () => {
+    if (details.open) expandedTasks.add(c.name);
+    else expandedTasks.delete(c.name);
+  });
+  return details;
+}
+
+function updateTaskProgress() {
+  const s = ov.taskSection;
+  s.replaceChildren(el('h2', { class: 'section-title', text: 'Task progress' }));
+  if (!overview.changes.length) {
+    s.append(emptyNote('No active changes.'));
+    return;
+  }
+  for (const c of overview.changes) s.append(taskChangeRow(c));
+}
+
+function buildOverviewSkeleton() {
+  destroyCharts();
+  ov = {
+    health: el('div', { class: 'health' }),
+    cards: {
+      changes: card('Changes'),
+      tickets: card('Tickets'),
+      specs: card('Specs'),
+      archived: card('Archived'),
+    },
+    activity: chartPanel('Activity', 180),
+    doughnut: chartPanel('Artifacts', 180),
+    taskSection: el('section', { class: 'panel', id: 'task-progress-panel' }),
+    changesSection: el('section', { class: 'panel', id: 'changes-panel' }),
+    ticketsSection: el('section', { class: 'panel', id: 'tickets-panel' }),
+    specsSection: el('section', { class: 'panel' }),
+    archiveSlot: el('div'),
+    archiveCount: -1,
+  };
+
+  const cards = el('section', { class: 'cards' }, [
+    ov.cards.changes.node,
+    ov.cards.tickets.node,
+    ov.cards.specs.node,
+    ov.cards.archived.node,
+  ]);
+  const chartsGrid = el('section', { class: 'charts-grid' }, [
+    ov.activity.panel,
+    ov.doughnut.panel,
+  ]);
+
+  view.replaceChildren(
+    ov.health,
+    cards,
+    chartsGrid,
+    ov.taskSection,
+    ov.changesSection,
+    ov.ticketsSection,
+    ov.specsSection,
+    ov.archiveSlot
+  );
+
+  // Window selector lives in the panel title; changing it refetches the series.
+  const range = el('select', { class: 'range-select', title: 'Activity window' }, [
+    el('option', { value: '30', text: '30 days' }),
+    el('option', { value: '90', text: '90 days' }),
+    el('option', { value: '365', text: '1 year' }),
+    el('option', { value: 'all', text: 'All history' }),
+  ]);
+  range.value = activityRange;
+  range.addEventListener('change', () => {
+    activityRange = range.value;
+    loadActivity();
+  });
+  ov.activity.panel.firstChild.append(range);
+
+  if (hasChart) {
+    const t = chartTheme();
+    ov.activityChart = buildActivityChart(ov.activity.canvas, 'tospec/');
+    ov.doughnutChart = buildStatusDoughnut(
+      ov.doughnut.canvas,
+      ['done', 'ready', 'blocked'],
+      [t.done, t.ready, t.blocked]
+    );
+  } else {
+    ov.activity.wrap.style.display = 'none';
+    ov.doughnut.wrap.style.display = 'none';
+  }
+}
+
+/** True when a change's last modification is older than the stale threshold. */
+function isStale(change, staleDays) {
+  const age = Date.now() - new Date(change.lastModified).getTime();
+  return age > staleDays * 86400000;
+}
+
+function healthItem(text, targetId) {
+  const item = el('a', { class: 'health-item', href: '#', text });
+  item.addEventListener('click', (e) => {
+    e.preventDefault();
+    const target = document.getElementById(targetId);
+    if (target) target.scrollIntoView({ behavior: 'smooth' });
+  });
+  return item;
+}
+
+function updateHealthStrip(staleDays) {
+  const items = [];
+  const staleChanges = overview.changes.filter((c) => isStale(c, staleDays));
+  if (staleChanges.length) {
+    items.push(
+      healthItem(
+        `${staleChanges.length} change(s) inactive > ${staleDays} days`,
+        'changes-panel'
+      )
+    );
+  }
+  const blocked = overview.changes.reduce((n, c) => n + c.artifactSummary.blocked, 0);
+  if (blocked) {
+    items.push(healthItem(`${blocked} blocked artifact(s)`, 'changes-panel'));
+  }
+  const parseErrors = overview.tickets.filter((t) => t.parseError).length;
+  if (parseErrors) {
+    items.push(healthItem(`${parseErrors} ticket parse error(s)`, 'tickets-panel'));
+  }
+  if (activity && activity.available && activity.specDrift) {
+    items.push(el('span', { class: 'health-item', text: 'spec drift: code moved, tospec/ did not (7d)' }));
+  }
+
+  ov.health.classList.toggle('health-warn', items.length > 0);
+  ov.health.classList.toggle('health-ok', items.length === 0);
+  if (items.length === 0) {
+    ov.health.replaceChildren(el('span', { class: 'health-item', text: 'All good — no stale changes, blocked artifacts, or parse errors' }));
+  } else {
+    ov.health.replaceChildren(...items);
+  }
+}
+
+function changeRow(c, staleDays, changed) {
+  const row = el('a', { class: 'row change-row', href: '#/changes/' + encodeURIComponent(c.name) });
+  row.append(el('span', { class: 'row-name', text: c.name }));
+  row.append(typeBadge(c.type));
+  if (c.artifactSummary.blocked > 0) {
+    row.append(el('span', { class: 'badge badge-blocked-warn', text: 'blocked' }));
+  }
+  if (isStale(c, staleDays)) {
+    row.append(el('span', { class: 'badge badge-stale', text: 'stale' }));
+  }
+  row.append(artifactBlocks(c.artifactSummary.done, c.artifactSummary.total));
+  row.append(el('span', { class: 'row-meta', text: `${c.artifactSummary.done}/${c.artifactSummary.total} artifacts` }));
+  row.append(el('span', { class: 'row-meta', text: `tasks ${c.taskProgress.completed}/${c.taskProgress.total}` }));
+  row.append(el('span', { class: 'row-time', text: relTime(c.lastModified) }));
+  if (changed) flash(row);
+  return row;
+}
+
+function updateChangesSection(staleDays) {
+  const s = ov.changesSection;
+  s.replaceChildren(el('h2', { class: 'section-title', text: 'Changes' }));
+  if (!overview.changes.length) {
+    s.append(emptyNote('No active changes. Create one with: tospec new change <name>'));
+    return;
+  }
+  const changedNames = new Set();
+  if (prevChangeStamps) {
+    for (const c of overview.changes) {
+      const prev = prevChangeStamps.get(c.name);
+      if (prev !== undefined && prev !== c.lastModified) changedNames.add(c.name);
+    }
+  }
+  for (const c of overview.changes) {
+    s.append(changeRow(c, staleDays, changedNames.has(c.name)));
+  }
+  prevChangeStamps = new Map(overview.changes.map((c) => [c.name, c.lastModified]));
+}
+
+function updateTicketsSection() {
+  const s = ov.ticketsSection;
+  s.replaceChildren(el('h2', { class: 'section-title', text: 'Tickets' }));
+  if (!overview.tickets.length) {
+    s.append(emptyNote('No tickets.'));
+    return;
+  }
+  for (const t of overview.tickets) {
+    const row = el('div', { class: 'row ticket-row' + (t.parseError ? ' row-error' : '') });
+    row.append(el('span', { class: 'row-time mono', text: fmtStamp(t.date) }));
+    row.append(el('span', { class: 'row-name', text: t.title }));
+    if (t.type) row.append(el('span', { class: 'badge badge-' + t.type, text: t.type }));
+    if (t.change) {
+      row.append(el('a', {
+        class: 'ticket-change',
+        href: '#/changes/' + encodeURIComponent(t.change),
+        text: t.change,
+      }));
+    }
+    if (t.parseError) row.append(el('span', { class: 'parse-error', text: 'parse error' }));
+    else if (t.summary) row.append(el('span', { class: 'ticket-summary', text: t.summary }));
+    if (prevTicketFiles && !prevTicketFiles.has(t.file)) flash(row);
+    s.append(row);
+  }
+  prevTicketFiles = new Set(overview.tickets.map((t) => t.file));
+}
+
+function updateSpecsSection() {
+  const s = ov.specsSection;
+  s.replaceChildren(el('h2', { class: 'section-title', text: 'Specs' }));
+  if (!overview.specs.length) {
+    s.append(emptyNote('No specs.'));
+    return;
+  }
+  for (const sp of overview.specs) {
+    const row = el('a', { class: 'row spec-row', href: '#/specs/' + encodeURIComponent(sp.id) });
+    row.append(el('span', { class: 'row-name mono', text: sp.id }));
+    row.append(el('span', { class: 'row-meta', text: `requirements ${sp.requirementCount}` }));
+    s.append(row);
+  }
+}
+
+function renderArchive(body, data) {
+  const changes = data.changes || [];
+  const tickets = data.tickets || [];
+  body.replaceChildren();
+  if (!changes.length && !tickets.length) {
+    body.append(emptyNote('Nothing archived.'));
+    return;
+  }
+  if (changes.length) {
+    body.append(el('h4', { text: 'Changes' }));
+    for (const c of changes) {
+      body.append(el('div', { class: 'row archive-row' }, [
+        el('span', { class: 'row-name', text: c.name || c.dirName }),
+        el('span', { class: 'row-time mono', text: fmtStamp(c.stamp) }),
+      ]));
+    }
+  }
+  if (tickets.length) {
+    body.append(el('h4', { text: 'Tickets' }));
+    for (const t of tickets) {
+      body.append(el('div', { class: 'row archive-row' }, [
+        el('span', { class: 'row-time mono', text: fmtStamp(t.date) }),
+        el('span', { class: 'row-name', text: t.title }),
+      ]));
+    }
+  }
+}
+
+function archiveSection(count) {
+  const details = el('details', { class: 'archive' });
+  details.append(el('summary', {}, ['Archive (' + count + ')']));
+  const body = el('div', { class: 'archive-body' });
+  body.append(emptyNote('Loading...'));
+  details.append(body);
+  let loaded = false;
+  details.addEventListener('toggle', async () => {
+    if (!details.open || loaded) return;
+    loaded = true;
+    try {
+      renderArchive(body, await api('/api/archive'));
+    } catch {
+      loaded = false;
+      body.replaceChildren(emptyNote('Failed to load archive.'));
+    }
+  });
+  return details;
+}
+
+function updateOverview() {
+  const staleDays = (activity && activity.staleDays) || 14;
+
+  updateHealthStrip(staleDays);
+
+  countUp(ov.cards.changes.count, overview.counts.changes);
+  countUp(ov.cards.tickets.count, overview.counts.tickets);
+  countUp(ov.cards.specs.count, overview.counts.specs);
+  countUp(ov.cards.archived.count, overview.counts.archived);
+
+  // Activity chart (hidden with a note when git is unavailable — ADR D6).
+  if (hasChart) {
+    if (activity && activity.available) {
+      ov.activity.wrap.style.display = '';
+      ov.activity.note.style.display = 'none';
+      updateActivityChart(ov.activityChart, activity.days);
+    } else {
+      ov.activity.wrap.style.display = 'none';
+      ov.activity.note.textContent = activity
+        ? `No git activity (${activity.reason || 'unavailable'}).`
+        : 'Loading activity...';
+      ov.activity.note.style.display = '';
+    }
+
+    const done = overview.changes.reduce((n, c) => n + c.artifactSummary.done, 0);
+    const blocked = overview.changes.reduce((n, c) => n + c.artifactSummary.blocked, 0);
+    const total = overview.changes.reduce((n, c) => n + c.artifactSummary.total, 0);
+    const ready = total - done - blocked;
+    if (total > 0) {
+      ov.doughnut.wrap.style.display = '';
+      ov.doughnut.note.style.display = 'none';
+      updateStatusDoughnut(
+        ov.doughnutChart,
+        [done, ready, blocked],
+        Math.round((done / total) * 100) + '%'
+      );
+    } else {
+      ov.doughnut.wrap.style.display = 'none';
+      ov.doughnut.note.textContent = 'No artifacts.';
+      ov.doughnut.note.style.display = '';
+    }
+
+  }
+
+  updateTaskProgress();
+  updateChangesSection(staleDays);
+  updateTicketsSection();
+  updateSpecsSection();
+
+  // The archive accordion lazy-loads on expand; rebuild only when the count
+  // changes so an open accordion isn't collapsed by every SSE refresh.
+  if (ov.archiveCount !== overview.counts.archived) {
+    ov.archiveCount = overview.counts.archived;
+    ov.archiveSlot.replaceChildren(archiveSection(overview.counts.archived));
+  }
+}
+
+function renderOverview() {
+  if (!overview) {
+    view.replaceChildren(emptyNote('Loading...'));
+    return;
+  }
+  if (!ov || !view.contains(ov.health)) buildOverviewSkeleton();
+  updateOverview();
+}
+
+// --- detail views ----------------------------------------------------------
+
+function leaveOverview() {
+  ov = null;
+  destroyCharts();
+  prevChangeStamps = null;
+  prevTicketFiles = null;
+}
+
+function backLink() {
+  return el('a', { class: 'back', href: '#/', text: '← back' });
+}
+
+function metaItem(label, value) {
+  return el('span', { class: 'meta-item' }, [
+    el('span', { class: 'meta-label', text: label }),
+    el('span', { class: 'meta-value', text: value }),
+  ]);
+}
+
+/** File accordion: renders `/api/render` HTML lazily on first expand. */
+function fileAccordion(file) {
+  const details = el('details', { class: 'file' });
+  details.append(el('summary', {}, [
+    el('span', { class: 'file-path mono', text: file.path }),
+    file.artifactId ? el('span', { class: 'badge badge-artifact', text: file.artifactId }) : null,
+  ]));
+  const body = el('div', { class: 'rendered' });
+  details.append(body);
+  let loaded = false;
+  details.addEventListener('toggle', async () => {
+    if (!details.open || loaded) return;
+    loaded = true;
+    body.textContent = 'Loading...';
+    try {
+      const data = await api('/api/render?file=' + encodeURIComponent(file.path));
+      body.innerHTML = data.html; // controlled container; server-rendered markdown
+    } catch (e) {
+      loaded = false;
+      body.textContent = 'Failed to render (' + (e.status || 'error') + ').';
+    }
+  });
+  return details;
+}
+
+/** Detail-page chart block: task ring + artifact stacked bar + change activity. */
+function detailCharts(detail, name) {
+  if (!hasChart) return null;
+  const t = chartTheme();
+  const grid = el('section', { class: 'charts-grid charts-grid-3' });
+
+  // Task completion ring.
+  const task = chartPanel('Tasks', 150);
+  grid.append(task.panel);
+  const taskChart = buildStatusDoughnut(task.canvas, ['completed', 'remaining'], [t.series1, t.track]);
+  const { completed, total } = detail.taskProgress;
+  if (total > 0) {
+    updateStatusDoughnut(taskChart, [completed, total - completed], Math.round((completed / total) * 100) + '%');
+  } else {
+    task.wrap.style.display = 'none';
+    task.note.textContent = 'No tasks.';
+    task.note.style.display = '';
+  }
+
+  // Artifact status stacked bar (single row, status palette).
+  const art = chartPanel('Artifacts', 150);
+  grid.append(art.panel);
+  const counts = { done: 0, ready: 0, blocked: 0 };
+  for (const a of detail.artifacts) counts[a.status] = (counts[a.status] || 0) + 1;
+  if (detail.artifacts.length > 0) {
+    newChart(art.canvas, {
+      type: 'bar',
+      data: {
+        labels: [''],
+        datasets: [
+          { label: 'done', data: [counts.done], backgroundColor: t.done, borderRadius: 4, barThickness: 18 },
+          { label: 'ready', data: [counts.ready], backgroundColor: t.ready, borderRadius: 4, barThickness: 18 },
+          { label: 'blocked', data: [counts.blocked], backgroundColor: t.blocked, borderRadius: 4, barThickness: 18 },
+        ],
+      },
+      options: {
+        indexAxis: 'y',
+        responsive: true,
+        maintainAspectRatio: false,
+        plugins: { legend: { position: 'bottom', labels: { color: t.muted, boxWidth: 10 } } },
+        scales: {
+          x: { stacked: true, ticks: { color: t.muted, precision: 0 }, grid: { display: false } },
+          y: { stacked: true, ticks: { display: false }, grid: { display: false } },
+        },
+      },
+    });
+  } else {
+    art.wrap.style.display = 'none';
+    art.note.textContent = 'No artifacts.';
+    art.note.style.display = '';
+  }
+
+  // This change's 30-day git activity (lazy: fetched after mount).
+  const act = chartPanel('Activity (30 days)', 150);
+  grid.append(act.panel);
+  act.wrap.style.display = 'none';
+  act.note.textContent = 'Loading activity...';
+  act.note.style.display = '';
+  api('/api/activity?change=' + encodeURIComponent(name))
+    .then((data) => {
+      if (!view.contains(act.panel)) return; // user navigated away
+      if (data.available) {
+        act.note.style.display = 'none';
+        act.wrap.style.display = '';
+        updateActivityChart(buildActivityChart(act.canvas, 'this change'), data.days);
+      } else {
+        act.note.textContent = `No git activity (${data.reason || 'unavailable'}).`;
+      }
+    })
+    .catch(() => {
+      act.note.textContent = 'Failed to load activity.';
+    });
+
+  return grid;
+}
+
+async function renderChangeDetail(name) {
+  leaveOverview();
+  view.replaceChildren(backLink(), emptyNote('Loading...'));
+  let detail;
+  try {
+    detail = await api('/api/changes/' + encodeURIComponent(name));
+  } catch (e) {
+    const msg = e.status === 404 ? `Change "${name}" not found.` : 'Failed to load change.';
+    view.replaceChildren(backLink(), emptyNote(msg));
+    return;
+  }
+
+  const meta = el('div', { class: 'meta' }, [
+    metaItem('schema', detail.metadata.schema || '—'),
+    detail.metadata.type ? metaItem('type', detail.metadata.type) : null,
+    detail.metadata.created ? metaItem('created', detail.metadata.created) : null,
+    detail.metadata.goal ? metaItem('goal', detail.metadata.goal) : null,
+  ]);
+
+  const artifacts = el('section', { class: 'panel' });
+  artifacts.append(el('h3', { text: 'Artifacts' }));
+  for (const a of detail.artifacts) {
+    const row = el('div', { class: 'artifact-row' }, [
+      el('span', { class: 'dot dot-' + a.status }),
+      el('span', { class: 'artifact-id mono', text: a.id }),
+      el('span', { class: 'artifact-status', text: a.status }),
+    ]);
+    if (a.status === 'blocked' && a.missingDeps && a.missingDeps.length) {
+      row.append(el('span', { class: 'blocked-by', text: 'blocked by: ' + a.missingDeps.join(', ') }));
+    }
+    artifacts.append(row);
+  }
+
+  const files = el('section', { class: 'panel' });
+  files.append(el('h3', { text: 'Files' }));
+  if (!detail.files.length) files.append(emptyNote('No files yet.'));
+  for (const f of detail.files) files.append(fileAccordion(f));
+
+  const nodes = [
+    backLink(),
+    el('h2', { text: detail.name }),
+    meta,
+    el('p', { class: 'task-progress', text: `Tasks ${detail.taskProgress.completed}/${detail.taskProgress.total}` }),
+    detailCharts(detail, name),
+    artifacts,
+    files,
+  ].filter(Boolean);
+  view.replaceChildren(...nodes);
+}
+
+async function renderSpecDetail(id) {
+  leaveOverview();
+  view.replaceChildren(backLink(), el('h2', { text: id }), emptyNote('Loading...'));
+  const nodes = [backLink(), el('h2', { text: id })];
+
+  try {
+    const spec = await api('/api/specs/' + encodeURIComponent(id));
+    nodes.push(el('p', { class: 'muted', text: `requirements ${spec.requirements.length}` }));
+  } catch (e) {
+    if (e.status === 404) {
+      view.replaceChildren(backLink(), emptyNote(`Spec "${id}" not found.`));
+      return;
+    }
+  }
+
+  const body = el('div', { class: 'rendered' });
+  body.textContent = 'Loading...';
+  nodes.push(body);
+  view.replaceChildren(...nodes);
+
+  try {
+    const data = await api('/api/render?file=' + encodeURIComponent(`tospec/specs/${id}/spec.md`));
+    body.innerHTML = data.html; // controlled container; server-rendered markdown
+  } catch {
+    body.textContent = 'Failed to render spec.';
+  }
+}
+
+// --- routing ---------------------------------------------------------------
+
+function isOverviewRoute() {
+  const h = location.hash;
+  return h === '' || h === '#' || h === '#/';
+}
+
+function router() {
+  const h = location.hash;
+  if (h.startsWith('#/changes/')) {
+    renderChangeDetail(decodeURIComponent(h.slice('#/changes/'.length)));
+  } else if (h.startsWith('#/specs/')) {
+    renderSpecDetail(decodeURIComponent(h.slice('#/specs/'.length)));
+  } else {
+    renderOverview();
+  }
+}
+
+/** Full route rebuild (theme change): drop the skeleton so charts re-theme. */
+function rebuildRoute() {
+  if (!view) return;
+  if (isOverviewRoute()) {
+    ov = null;
+    destroyCharts();
+    if (overview) renderOverview();
+  } else {
+    router();
+  }
+}
+
+window.addEventListener('hashchange', router);
+refreshBtn.addEventListener('click', () => {
+  if (isOverviewRoute()) {
+    loadOverview();
+    loadActivity();
+  } else {
+    router();
+  }
+});
+
+// Live updates: the server pushes a `change` event on any tospec file edit, so
+// the UI refreshes itself without polling or a manual reload. EventSource
+// reconnects on its own; we only reflect the link state.
+function subscribe() {
+  const es = new EventSource('/api/events');
+  es.addEventListener('change', () => {
+    loadOverview(); // refreshes counts/lists/charts (morph + flash on overview)
+    loadActivity();
+    if (!isOverviewRoute()) router(); // refresh the open detail view too
+  });
+  es.onopen = () => setConnected(true);
+  es.onerror = () => setConnected(false);
+}
+
+router();
+loadOverview();
+loadActivity();
+subscribe();