@seanmars/tospec 0.23.0 → 0.24.0

package/assets/dashboard/app.js

@@ -1,1242 +1,280 @@
-// tospec dashboard — vanilla SPA. No framework, no build, no external resources.
-// Charts: vendored Chart.js (assets/chart.umd.js), themed via CSS variables.
+// tospec dashboard: one hub, every project drawn as a line on a shared
+// stage grid. Vanilla ES modules, no build step, no external resources.
+
+import { el, icon, paintLine } from './lib/dom.js';
+import { store, onStoreChange, loadProjects, loadAllProjects, loadDetail, subscribe, requestRefresh, projectByKey, slotOf } from './lib/store.js';
+import { parseRoute, legacyRoute, routes } from './lib/routes.js';
+import { releaseCharts } from './lib/charts.js';
+import { renderHome } from './views/home.js';
+import { renderProject } from './views/project.js';
+import { renderChange } from './views/change.js';
+import { renderSpec, renderDecisions, clearRenderCache } from './views/docs.js';
+import { renderSidebar } from './views/sidebar.js';
+import { updateSessionPanel } from './views/session.js';
+import { checkSessionAlerts, setupNotifyButton } from './views/alerts.js';
 
 const view = document.getElementById('view');
-const rootPathEl = document.getElementById('root-path');
-const connEl = document.getElementById('conn-status');
-const refreshBtn = document.getElementById('refresh-btn');
+const signbar = document.getElementById('signbar');
+const crumbs = document.getElementById('crumbs');
+const crumbBack = document.getElementById('crumb-back');
+const hubStatus = document.getElementById('hub-status');
 const themeSelect = document.getElementById('theme-select');
+const refreshBtn = document.getElementById('refresh-btn');
+const sidebar = document.getElementById('sidebar');
+const navToggle = document.getElementById('nav-toggle');
+const navScrim = document.getElementById('nav-scrim');
 
-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) -------------
+// --- 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.
+// Every colour, chart marks included, reads a theme variable, so a switch
+// needs no re-render.
 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.
+applyTheme(localStorage.getItem(THEME_KEY) || 'system');
 systemDark.addEventListener('change', () => {
-  if ((localStorage.getItem(THEME_KEY) || 'system') === 'system') {
-    applyTheme('system');
-    rebuildRoute();
-  }
+  if ((localStorage.getItem(THEME_KEY) || 'system') === 'system') applyTheme('system');
 });
 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();
-}
+// --- routing -------------------------------------------------------------------
 
-/** 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 },
-      },
-    },
-  });
-}
+const legacy = legacyRoute(location.search, location.hash);
+if (legacy) history.replaceState(null, '', location.pathname + legacy);
 
-function updateStatusDoughnut(chart, values, centerText) {
-  chart.data.datasets[0].data = values;
-  chart.options.plugins.centerText.text = centerText;
-  chart.update();
-}
+/** Views that follow live pushes; reading views keep their place instead. */
+const LIVE_VIEWS = new Set(['home', 'project', 'change']);
 
-// --- dynamics (count-up, flash) ---------------------------------------------
+let lastRoute = null;
+let viewAbort = null;
+/** A reading view that rendered before its data arrived re-renders once it lands. */
+let waitingForData = false;
 
-/** 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);
+function render({ live = false } = {}) {
+  const route = parseRoute(location.hash);
+  const id = JSON.stringify(route);
+  const navigation = id !== lastRoute;
+  if (live && !navigation && !LIVE_VIEWS.has(route.view) && !waitingForData) {
+    renderChrome(route);
     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 });
-}
+  lastRoute = id;
+  const trains = navigation ? null : captureTrains();
+  releaseCharts();
+  if (viewAbort) viewAbort.abort();
+  viewAbort = new AbortController();
+  const ctx = { signal: viewAbort.signal };
 
-// Previous snapshots keyed for change detection (what to flash after updates).
-let prevChangeStamps = null; // Map<name, lastModified>
-let prevTicketFiles = null; // Set<file>
+  let page;
+  if (route.view === 'project') page = renderProject(route, ctx);
+  else if (route.view === 'change') page = renderChange(route, ctx);
+  else if (route.view === 'spec') page = renderSpec(route, ctx);
+  else if (route.view === 'decisions') page = renderDecisions(route, ctx);
+  else page = renderHome(ctx);
+  waitingForData = !LIVE_VIEWS.has(route.view) && Boolean(ctx.waiting);
+  view.replaceChildren(page);
+  renderChrome(route);
 
-// --- 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 }));
-    }
+  if (navigation) {
+    arrivals.clear();
+    window.scrollTo(0, 0);
+    view.focus({ preventScroll: true });
+  } else if (trains) {
+    animateTrains(trains);
   }
 }
 
-async function loadActivity() {
-  try {
-    activity = await api('/api/activity?days=' + activityRange);
-  } catch {
-    activity = null; // health strip and charts degrade below
-  }
-  if (isOverviewRoute()) renderOverview();
-}
+// --- signature move: a train slides to its new station -----------------------------
 
-// --- 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 };
-}
+const TRAVEL_MS = 900;
+const ARRIVAL_MS = 2600;
+/**
+ * Trains still travelling or glowing, keyed by `<project>/<change>`. One push
+ * sets off several renders (overview, then activity, archive, details as they
+ * land), and each replaces the DOM: without this, the second render would cut
+ * the journey off a few milliseconds after it began.
+ */
+const arrivals = new Map();
 
-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 };
+function captureTrains() {
+  const seen = new Map();
+  for (const node of view.querySelectorAll('[data-train]')) {
+    seen.set(node.dataset.train, { station: node.dataset.station, rect: node.getBoundingClientRect() });
+  }
+  return seen;
 }
 
-// --- 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.
+ * FLIP: the new render puts the train at its new station; it is drawn back at
+ * its old position and released, so it travels along the line. Under reduced
+ * motion it only marks its arrival.
  */
-function taskItem(task, locked) {
-  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;
-  // A disabled input never fires `change`, so the listener below stays inert.
-  if (locked) {
-    box.disabled = true;
-    item.classList.add('task-item-locked');
-    item.title = 'archiving: sync 已通過, task 已凍結';
-  }
-  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;
+function animateTrains(before) {
+  const now = performance.now();
+  for (const node of view.querySelectorAll('[data-train]')) {
+    const prev = before.get(node.dataset.train);
+    if (!prev || prev.station === node.dataset.station) continue;
+    const rect = node.getBoundingClientRect();
+    arrivals.set(node.dataset.train, { dx: prev.rect.left - rect.left, dy: prev.rect.top - rect.top, start: now });
+  }
+  const reduce = window.matchMedia('(prefers-reduced-motion: reduce)').matches;
+  for (const node of view.querySelectorAll('[data-train]')) {
+    const arrival = arrivals.get(node.dataset.train);
+    if (!arrival) continue;
+    const elapsed = now - arrival.start;
+    if (elapsed >= ARRIVAL_MS) {
+      arrivals.delete(node.dataset.train);
+      continue;
     }
-  });
-  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 locked = change.phase === 'archiving';
-  if (locked) {
-    body.append(
-      el('p', {
-        class: 'task-locked-note',
-        text: '此 change 已通過 sync, 正在歸檔中, task 暫停編輯',
-      })
+    node.style.setProperty('animation-delay', `-${Math.round(elapsed)}ms`);
+    node.classList.add('just-arrived');
+    if (reduce || elapsed >= TRAVEL_MS || typeof node.animate !== 'function') continue;
+    const journey = node.animate(
+      [{ transform: `translate(${arrival.dx}px, ${arrival.dy}px)` }, { transform: 'none' }],
+      { duration: TRAVEL_MS, easing: 'cubic-bezier(0.16, 1, 0.3, 1)' }
     );
-  }
-  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, locked));
+    journey.currentTime = elapsed;
+  }
+}
+
+// --- chrome: breadcrumbs, hub status, title --------------------------------------
+
+function renderChrome(route) {
+  renderSidebar(sidebar, route);
+  updateSessionPanel();
+  const project = route.key ? projectByKey(route.key) : null;
+  const items = [route.view === 'home'
+    ? el('li', {}, [el('span', { 'aria-current': 'page', text: '總覽' })])
+    : el('li', {}, [el('a', { href: routes.home(), text: '總覽' })])];
+  const titleParts = ['總覽'];
+  if (route.key) {
+    const name = project ? project.name : route.key;
+    titleParts.push(name);
+    const crumb = paintLine(el('li', { class: 'crumb-project' }), slotOf(route.key));
+    const swatch = el('span', { class: 'line-swatch', 'aria-hidden': 'true' });
+    const label = el('span', { class: 'crumb-text', text: name });
+    crumb.append(route.view === 'project'
+      ? el('span', { 'aria-current': 'page' }, [swatch, label])
+      : el('a', { href: routes.project(route.key) }, [swatch, label]));
+    items.push(crumb);
+    const leaf = route.view === 'change' ? route.name : route.view === 'spec' ? route.id : route.view === 'decisions' ? 'Decisions' : null;
+    if (leaf) {
+      titleParts.push(leaf);
+      items.push(el('li', {}, [el('span', { class: 'crumb-text', 'aria-current': 'page', text: leaf })]));
     }
   }
-  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,
-      c.phase === 'archiving'
-        ? el('span', { class: 'badge badge-archiving', text: 'archiving' })
-        : null,
-      c.phase === 'ready'
-        ? el('span', { class: 'badge badge-ready', text: 'ready' })
-        : 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,
-    ov.changesSection,
-    ov.taskSection,
-    ov.ticketsSection,
-    chartsGrid,
-    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]
+  crumbs.replaceChildren(...items);
+  document.title = route.view === 'home' ? '總覽 · tospec' : titleParts.slice(1).reverse().concat('tospec').join(' · ');
+
+  // Narrow bars show one step up instead of a trail cut to "n…": the page
+  // title already names where you are.
+  crumbBack.hidden = route.view === 'home';
+  if (route.view === 'project') {
+    crumbBack.href = routes.home();
+    crumbBack.replaceChildren(icon('back', 14), el('span', { class: 'crumb-text', text: '總覽' }));
+  } else if (route.key) {
+    crumbBack.href = routes.project(route.key);
+    paintLine(crumbBack, slotOf(route.key));
+    crumbBack.replaceChildren(
+      icon('back', 14),
+      el('span', { class: 'line-swatch', 'aria-hidden': 'true' }),
+      el('span', { class: 'crumb-text', text: project ? project.name : route.key })
     );
-  } 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'));
-  }
-  const unreadable = overview.changes.filter((c) => c.unreadable).length;
-  if (unreadable) {
-    items.push(healthItem(`${unreadable} change(s) with unreadable metadata`, 'changes-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.phase === 'applying') {
-    row.classList.add('row-applying');
-    row.append(el('span', { class: 'badge badge-applying', text: 'applying' }));
-  } else if (c.phase === 'archiving') {
-    row.classList.add('row-archiving');
-    row.append(el('span', { class: 'badge badge-archiving', text: 'archiving' }));
-  } else if (c.phase === 'ready') {
-    row.classList.add('row-ready');
-    row.append(el('span', { class: 'badge badge-ready', text: 'ready' }));
-  }
-  if (c.unreadable) {
-    // Ahead of every other badge: the counts beside it were all computed from
-    // metadata that would not parse, so they are zeros, not measurements.
-    const badge = el('span', { class: 'badge badge-unreadable', text: 'unreadable' });
-    badge.title = c.unreadable;
-    row.append(badge);
-  }
-  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; // sanitized by core/markdown-render.ts - raw HTML is escaped there, not here
-    } 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.';
-    });
+  if (route.key) paintLine(signbar, slotOf(route.key));
+  signbar.classList.toggle('has-line', Boolean(route.key));
 
-  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 linkedDecisions = detail.metadata.decisions || [];
-  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,
-    // Linked ADRs (metadata `decisions`) — each links into the decisions view.
-    linkedDecisions.length
-      ? el('span', { class: 'meta-item' }, [
-          el('span', { class: 'meta-label', text: 'decisions' }),
-          el('span', { class: 'meta-value' }, linkedDecisions.map((f, i) => el('span', {}, [
-            i > 0 ? ', ' : null,
-            el('a', { href: '#/decisions/' + encodeURIComponent(f), text: f }),
-          ]))),
-        ])
-      : 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; // sanitized by core/markdown-render.ts - raw HTML is escaped there, not here
-  } catch {
-    body.textContent = 'Failed to render spec.';
-  }
-}
-
-// --- decisions ---------------------------------------------------------------
-
-let decisions = []; // cached /api/decisions payload (refetched on every visit)
-let decisionsQuery = ''; // search box text, kept across re-renders of this route
-
-/** Full-text match: title, topic, status, and the raw markdown body. */
-function decisionMatches(d, q) {
-  if (!q) return true;
-  return (d.title + ' ' + d.topic + ' ' + d.status + ' ' + d.content).toLowerCase().includes(q);
-}
-
-function decisionIndexRow(d, active) {
-  const row = el('a', {
-    class: 'decision-row' + (active ? ' decision-row-active' : ''),
-    href: '#/decisions/' + encodeURIComponent(d.file),
-  });
-  row.append(el('span', { class: 'decision-title', text: d.title }));
-  row.append(el('div', { class: 'decision-meta' }, [
-    el('span', { class: 'mono', text: fmtStamp(d.date) }),
-    el('span', { class: 'badge badge-' + d.status, text: d.status }),
-  ]));
-  return row;
-}
-
-function renderDecisionIndexList(container, list, activeFile) {
-  container.replaceChildren();
-  if (!list.length) {
-    container.append(emptyNote('No matching decisions.'));
-    return;
-  }
-  for (const d of list) container.append(decisionIndexRow(d, d.file === activeFile));
-}
-
-/** Renders one decision's rendered markdown into the content pane. */
-async function renderDecisionContent(pane, file) {
-  const d = decisions.find((x) => x.file === file);
-  if (!d) {
-    pane.replaceChildren(emptyNote('Decision not found.'));
-    return;
-  }
-  const body = el('div', { class: 'rendered' });
-  body.textContent = 'Loading...';
-  pane.replaceChildren(
-    el('h2', { text: d.title }),
-    el('div', { class: 'meta' }, [metaItem('date', fmtStamp(d.date)), metaItem('status', d.status)]),
-    body
-  );
-  try {
-    const data = await api('/api/render?file=' + encodeURIComponent(d.path));
-    body.innerHTML = data.html; // sanitized by core/markdown-render.ts - raw HTML is escaped there, not here
-    enhanceDecisionQA(body, d.content); // 決策過程 → Q/A cards (client-side, graceful fallback)
-  } catch {
-    body.textContent = 'Failed to render decision.';
-  }
-}
-
-/** Extracts `{ q, a }` pairs from the `## 決策過程` section of raw markdown.
- *  Canonical shape: a `**Q:**` line, then the answer in the following
- *  paragraph(s), until the next `**Q:**` or the next `## ` heading. Old-format
- *  or empty sections yield `[]`, so the caller leaves marked's output as-is. */
-function parseDecisionQA(markdown) {
-  if (!markdown) return [];
-  const start = markdown.search(/^##\s+決策過程\s*$/m);
-  if (start < 0) return [];
-  const rest = markdown.slice(start).replace(/^##\s+決策過程\s*$/m, '');
-  const next = rest.search(/^##\s/m); // stop at the following section, if any
-  const section = next >= 0 ? rest.slice(0, next) : rest;
-  const pairs = [];
-  for (const block of section.split(/^\*\*Q:\*\*/m).slice(1)) {
-    const nl = block.indexOf('\n');
-    const q = (nl < 0 ? block : block.slice(0, nl)).trim();
-    const a = (nl < 0 ? '' : block.slice(nl + 1)).trim();
-    if (q) pairs.push({ q, a });
-  }
-  return pairs;
-}
-
-/** Swaps the rendered 決策過程 body (always the last section) for Q/A cards, keeping its heading. */
-function enhanceDecisionQA(body, markdown) {
-  const pairs = parseDecisionQA(markdown);
-  if (!pairs.length) return;
-  const heading = [...body.querySelectorAll('h2')].find((h) => h.textContent.trim() === '決策過程');
-  if (!heading) return;
-  while (heading.nextSibling) heading.nextSibling.remove(); // drop marked's raw Q&A, keep the heading
-  heading.after(
-    el(
-      'section',
-      { class: 'qa-cards' },
-      pairs.map((p) =>
-        el('div', { class: 'qa-card' }, [
-          el('div', { class: 'qa-q', text: p.q }),
-          el('div', { class: 'qa-a', text: p.a }),
-        ])
-      )
-    )
+  // A live region: rewrite it only when the link state flips, or every push
+  // would announce "connected" again.
+  const state = store.hubConnected ? 'up' : 'down';
+  if (hubStatus.dataset.state === state) return;
+  hubStatus.dataset.state = state;
+  hubStatus.replaceChildren(
+    el('span', { class: 'hub-dot', 'aria-hidden': 'true' }),
+    // Always names the hub: a bare "connected" read as the project's session
+    // on an offline project's page, which says the opposite.
+    el('span', { class: 'hub-text', text: store.hubConnected ? 'hub 已連線' : 'hub 中斷' })
   );
+  hubStatus.classList.toggle('is-down', !store.hubConnected);
+  hubStatus.title = store.hubConnected
+    ? '即時更新中: session 推送快照時畫面會跟著更新.'
+    : '與 dashboard hub 的連線中斷. 畫面停在最後收到的資料, 連線恢復後會自動更新.';
 }
 
-/**
- * Decisions tab: a floating, always-visible index (search + list) on the left
- * and the selected decision's rendered content on the right. Selecting an
- * entry navigates to `#/decisions/<file>` so it's linkable and survives
- * refresh; the index itself never leaves the viewport.
- */
-async function renderDecisionsList(activeFile) {
-  leaveOverview();
-  view.replaceChildren(emptyNote('Loading...'));
-  try {
-    decisions = await api('/api/decisions');
-  } catch {
-    view.replaceChildren(el('p', { class: 'error', text: 'Failed to load decisions.' }));
-    return;
-  }
+// --- the sidebar as a drawer (below 960px) ------------------------------------------
 
-  const search = el('input', {
-    type: 'search',
-    class: 'decisions-search',
-    placeholder: 'Search decisions (title, status, content)...',
-  });
-  search.value = decisionsQuery;
-  const list = el('div', { class: 'decisions-list' });
-  const index = el('div', { class: 'decisions-index' }, [search, list]);
-  const content = el('div', { class: 'decisions-content panel' });
-
-  function refreshList() {
-    decisionsQuery = search.value;
-    const q = decisionsQuery.trim().toLowerCase();
-    renderDecisionIndexList(list, decisions.filter((d) => decisionMatches(d, q)), activeFile);
+function setNavOpen(open) {
+  sidebar.classList.toggle('is-open', open);
+  navScrim.hidden = !open;
+  navToggle.setAttribute('aria-expanded', String(open));
+  if (open) {
+    const current = sidebar.querySelector('[aria-current="page"]') || sidebar.querySelector('a');
+    if (current) current.focus({ preventScroll: true });
   }
-  search.addEventListener('input', refreshList);
-  refreshList();
-
-  view.replaceChildren(index, content);
+}
 
-  if (activeFile) {
-    await renderDecisionContent(content, activeFile);
-  } else if (decisions.length) {
-    content.append(emptyNote('Select a decision from the index on the left.'));
-  } else {
-    content.append(emptyNote('No decisions yet. Create one with: tospec decision new <topic>'));
+navToggle.replaceChildren(icon('menu', 16), el('span', { class: 'sr-only', text: 'Projects' }));
+navToggle.addEventListener('click', () => setNavOpen(!sidebar.classList.contains('is-open')));
+navScrim.addEventListener('click', () => setNavOpen(false));
+window.addEventListener('keydown', (event) => {
+  if (event.key === 'Escape' && sidebar.classList.contains('is-open')) {
+    setNavOpen(false);
+    navToggle.focus();
   }
-}
+});
 
-// --- routing ---------------------------------------------------------------
+// --- wiring ----------------------------------------------------------------------
 
-/** Highlights the active top-level tab based on the current hash. */
-function updateActiveTab(hash) {
-  const isDecisions = hash.startsWith('#/decisions');
-  document.querySelectorAll('.tab').forEach((t) => {
-    t.classList.toggle('tab-active', (t.dataset.tab === 'decisions') === isDecisions);
-  });
-}
+onStoreChange(() => {
+  render({ live: true });
+  checkSessionAlerts();
+});
+setupNotifyButton(document.getElementById('notify-btn'));
+window.addEventListener('hashchange', () => {
+  // A link in the drawer was followed: the page it opened is what to show.
+  setNavOpen(false);
+  render();
+});
 
-function isOverviewRoute() {
-  const h = location.hash;
-  return h === '' || h === '#' || h === '#/';
-}
+refreshBtn.replaceChildren(icon('refresh', 16), el('span', { class: 'btn-text', text: '重新整理' }));
+refreshBtn.addEventListener('click', async () => {
+  refreshBtn.disabled = true;
+  const route = parseRoute(location.hash);
+  // Live sessions push fresh snapshots (arriving as `change` events); the
+  // reload below re-reads what the hub already holds, offline projects included.
+  requestRefresh(route.key ? [route.key] : store.projects.map((p) => p.key));
+  await loadProjects();
+  await loadAllProjects();
+  refreshBtn.disabled = false;
+});
 
-function router() {
-  const h = location.hash;
-  updateActiveTab(h);
-  view.classList.toggle('view-decisions', h.startsWith('#/decisions'));
-  if (h.startsWith('#/changes/')) {
-    renderChangeDetail(decodeURIComponent(h.slice('#/changes/'.length)));
-  } else if (h.startsWith('#/specs/')) {
-    renderSpecDetail(decodeURIComponent(h.slice('#/specs/'.length)));
-  } else if (h.startsWith('#/decisions/')) {
-    renderDecisionsList(decodeURIComponent(h.slice('#/decisions/'.length)));
-  } else if (h === '#/decisions') {
-    renderDecisionsList(null);
-  } else {
-    renderOverview();
-  }
-}
+// Relative times and the idle threshold move with the clock, not with pushes.
+setInterval(() => {
+  if (LIVE_VIEWS.has(parseRoute(location.hash).view)) render({ live: true });
+}, 60000);
 
-/** 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();
-  }
+/** A push from `key`: rendered files go stale, and an open change page re-reads its detail. */
+function onProjectPush(key) {
+  clearRenderCache(key);
+  const route = parseRoute(location.hash);
+  if (route.view === 'change' && route.key === key) loadDetail(key, route.name, true);
 }
 
-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);
+async function start() {
+  subscribe(onProjectPush);
+  render();
+  await loadProjects();
+  await loadAllProjects();
 }
 
-router();
-loadOverview();
-loadActivity();
-subscribe();
+start();