@seanmars/tospec 0.22.0 → 0.24.0

package/assets/dashboard/views/alerts.js

@@ -0,0 +1,170 @@
+// Tells the person when a session needs them (it waits on a question) or has
+// finished (its turn ended and it idles): a toast in the page, and a browser
+// notification when the page is not in front. Either one, clicked, opens the
+// project and that session's panel.
+
+import { el, icon, activityDot, lineBadge } from '../lib/dom.js';
+import { sessionAlerts, askSummary } from '../lib/derive.js';
+import { store, slotOf } from '../lib/store.js';
+import { routes, parseRoute } from '../lib/routes.js';
+import { openSessionPanel, isSessionPanelOpen } from './session.js';
+
+const NOTIFY_KEY = 'tospec-notify';
+/** A finished turn is passing news; a question stays until it is answered or dismissed. */
+const IDLE_TOAST_MS = 10_000;
+const TOAST_LIMIT = 4;
+
+/**
+ * State last seen per session; null until the first project list arrives, so
+ * whatever was already true when the page opened is not announced as news.
+ */
+let seen = null;
+/** `<key>/<session>` -> { node, kind, timer } */
+const toasts = new Map();
+
+function toastHost() {
+  return document.getElementById('toasts');
+}
+
+/** Run after every store change: announces what changed since the last run. */
+export function checkSessionAlerts() {
+  if (!store.projectsLoaded) return;
+  const first = seen === null;
+  const result = sessionAlerts(seen || new Map(), store.projects);
+  seen = result.seen;
+  // A question no longer open (answered, here or in the terminal) takes its toast with it.
+  for (const [id, toast] of toasts) {
+    if (toast.kind === 'wait' && !String(seen.get(id) || '').startsWith('waiting')) dismiss(id);
+  }
+  if (first) return;
+  for (const alert of result.alerts) raise(alert);
+}
+
+function idOf(alert) {
+  return alert.project.key + '/' + alert.session.id;
+}
+
+function raise(alert) {
+  const { project, session } = alert;
+  // Already looking at this very session: the panel shows it as it happens.
+  if (isSessionPanelOpen(project.key, session.id) && document.hasFocus()) return;
+  const title = alert.kind === 'wait' ? '等你回覆' : '已閒置';
+  const text = alert.kind === 'wait'
+    ? askSummary(session.ask)
+    : `session ${session.id.slice(0, 8)} 的回合結束了.`;
+  showToast(alert, title, text);
+  notify(alert, title, text);
+}
+
+/** Opens the project's page with the session's panel beside it. */
+function go(alert) {
+  const { project, session } = alert;
+  const open = () => openSessionPanel(project.key, session.id);
+  const target = routes.project(project.key);
+  const here = parseRoute(location.hash);
+  if (here.view === 'project' && here.key === project.key) {
+    open();
+    return;
+  }
+  // After the router's own hashchange handler, which moves focus to the page:
+  // the panel opens last, so the keyboard lands in it.
+  window.addEventListener('hashchange', open, { once: true });
+  location.hash = target;
+}
+
+function showToast(alert, title, text) {
+  const id = idOf(alert);
+  dismiss(id);
+  const main = el('button', { type: 'button', class: 'toast-main', title: '開啟這個 session' }, [
+    el('span', { class: 'toast-head' }, [
+      activityDot(alert.kind === 'wait' ? 'waiting' : 'idle'),
+      lineBadge(alert.project.name, slotOf(alert.project.key)),
+      el('strong', { text: title }),
+    ]),
+    text ? el('span', { class: 'toast-text', text }) : null,
+  ]);
+  main.addEventListener('click', () => {
+    dismiss(id);
+    go(alert);
+  });
+  const close = el('button', { type: 'button', class: 'toast-close', title: '關閉' }, [icon('close', 12), el('span', { class: 'sr-only', text: '關閉通知' })]);
+  close.addEventListener('click', () => dismiss(id));
+  const node = el('div', { class: 'toast toast-' + alert.kind }, [main, close]);
+  const host = toastHost();
+  host.append(node);
+  const timer = alert.kind === 'idle' ? setTimeout(() => dismiss(id), IDLE_TOAST_MS) : null;
+  toasts.set(id, { node, kind: alert.kind, timer });
+  // The oldest leaves first; an unanswered question outlives a passing idle.
+  while (toasts.size > TOAST_LIMIT) {
+    const oldest = [...toasts.entries()].find(([, t]) => t.kind === 'idle') || [...toasts.entries()][0];
+    dismiss(oldest[0]);
+  }
+}
+
+function dismiss(id) {
+  const toast = toasts.get(id);
+  if (!toast) return;
+  clearTimeout(toast.timer);
+  toast.node.remove();
+  toasts.delete(id);
+}
+
+// --- browser notifications ----------------------------------------------------------------
+
+function notificationsOn() {
+  return 'Notification' in window && Notification.permission === 'granted' && localStorage.getItem(NOTIFY_KEY) !== 'off';
+}
+
+/**
+ * Only while the page is not in front: in front, the toast already says it,
+ * and a system notification on top would say it twice.
+ */
+function notify(alert, title, text) {
+  if (!notificationsOn() || (!document.hidden && document.hasFocus())) return;
+  const id = idOf(alert);
+  const notification = new Notification(`${alert.project.name}: ${title}`, {
+    body: text,
+    // One per session: a newer state replaces the older notification.
+    tag: 'tospec-' + id,
+    requireInteraction: alert.kind === 'wait',
+  });
+  notification.onclick = () => {
+    window.focus();
+    notification.close();
+    dismiss(id);
+    go(alert);
+  };
+}
+
+/**
+ * The sign bar's notification switch. Permission is asked on the first click,
+ * as browsers require a gesture for it; after that the click turns the
+ * notifications on and off. Hidden where the browser has no notifications.
+ */
+export function setupNotifyButton(button) {
+  if (!('Notification' in window)) {
+    button.hidden = true;
+    return;
+  }
+  const draw = () => {
+    const on = notificationsOn();
+    const denied = Notification.permission === 'denied';
+    button.setAttribute('aria-pressed', String(on));
+    button.title = denied
+      ? '瀏覽器封鎖了這個網站的通知; 請在瀏覽器的網站設定中允許.'
+      : on
+        ? '瀏覽器通知已開啟: session 等你回覆或閒置時, 頁面不在前景就通知. 點一下關閉.'
+        : '瀏覽器通知已關閉. 點一下開啟.';
+    button.replaceChildren(icon(on ? 'bell' : 'bell-off', 16), el('span', { class: 'btn-text', text: on ? '通知開' : '通知關' }));
+  };
+  button.addEventListener('click', async () => {
+    if (Notification.permission === 'default') {
+      const result = await Notification.requestPermission();
+      if (result === 'granted') localStorage.setItem(NOTIFY_KEY, 'on');
+    } else if (Notification.permission === 'granted') {
+      localStorage.setItem(NOTIFY_KEY, notificationsOn() ? 'off' : 'on');
+    }
+    draw();
+  });
+  draw();
+}

package/assets/dashboard/views/change.js

@@ -0,0 +1,232 @@
+// One change: where it stands, its artifacts as stops on an inner line, its
+// tasks (the dashboard's only write), and its files rendered on demand.
+
+import { el, note, marker, paintLine, icon } from '../lib/dom.js';
+import { STATIONS, SIGNAL_LABEL, stationOf, stationIndex, stationLabel, signalOf, lineSignal, gapOf, unreadableInfo, staleDaysOf, relTime, formatDate, parseLooseDate } from '../lib/derive.js';
+import { dataOf, slotOf, projectByKey, postTask, loadProject, loadDetail } from '../lib/store.js';
+import { routes } from '../lib/routes.js';
+import { renderMarkdown, openFiles } from './docs.js';
+
+const ARTIFACT_STATUS = { done: '完成', ready: '可寫', blocked: '等待相依', stub: '待補完' };
+
+export function renderChange(route) {
+  const project = projectByKey(route.key);
+  const data = dataOf(route.key);
+  const page = el('div', { class: 'page page-change' });
+  if (!project) {
+    page.append(el('h1', { class: 'page-title', text: route.name }), note('找不到這個 project.'));
+    return page;
+  }
+  if (!data.overview) {
+    page.append(el('h1', { class: 'page-title', text: route.name }), note(data.error ? '快照讀取失敗: ' + data.error : '正在讀取快照.'));
+    return page;
+  }
+  const change = data.overview.changes.find((c) => c.name === route.name);
+  const detail = data.details.get(route.name);
+  if (!change) {
+    page.append(
+      el('h1', { class: 'page-title', text: route.name }),
+      note('這個 change 不在進行中的清單裡. 它可能已經歸檔, 或已被刪除.'),
+      el('p', {}, [el('a', { href: routes.project(route.key), text: '回到 ' + project.name })])
+    );
+    return page;
+  }
+
+  const now = Date.now();
+  const rawSignal = signalOf(change, staleDaysOf(data), now);
+  const signal = lineSignal(rawSignal, project.online);
+  const station = stationOf(change);
+  paintLine(page, slotOf(route.key));
+
+  page.append(
+    el('header', { class: 'change-head' }, [
+      el('h1', { class: 'page-title change-title', text: change.name }),
+      el('p', { class: 'change-signal signal-' + signal }, [
+        marker(signal, 16),
+        el('strong', { text: SIGNAL_LABEL[signal] }),
+        el('span', { text: ` · ${stationLabel(station)} · ${gapOf(change, detail)}` + (rawSignal === 'running' ? ' · 10 分鐘內有更新' : '') }),
+      ]),
+      project.online
+        ? null
+        : el('p', { class: 'lock-note' }, [icon('lock', 14), `這個 project 沒有 session 連線, 畫面是 ${relTime(project.updatedAt, now)}的快照.`]),
+      metaList(route.key, change, detail, now),
+      change.goal ? el('p', { class: 'change-goal', text: change.goal }) : null,
+      change.unreadable ? stopNote(change) : null,
+    ])
+  );
+
+  page.append(stationStrip(station));
+  const detailError = data.detailErrors && data.detailErrors.get(route.name);
+  if (!detail && !detailError) loadDetail(route.key, route.name);
+  const detailNote = detailError ? note('change detail 讀取失敗: ' + detailError) : note('正在讀取 artifact 與檔案.');
+  page.append(detail ? artifactRoute(detail) : detailNote);
+  page.append(taskSection(project, change));
+  if (detail) page.append(fileSection(route.key, project, detail));
+  return page;
+}
+
+/** What cannot be parsed, then how to fix it: two lines, never one run-on sentence. */
+function stopNote(change) {
+  const info = unreadableInfo(change);
+  return el('div', { class: 'change-unreadable signal-stop' }, [
+    el('p', {}, [el('span', { class: 'badge-unreadable', text: '無法解析' }), ' ', el('span', { class: 'keep', text: info.summary })]),
+    el('p', { class: 'stop-reason', text: change.unreadable }),
+    el('p', { class: 'stop-fix' }, ['修正 ', el('code', { text: info.file }), ' 後, 下一次快照就會恢復.']),
+  ]);
+}
+
+function metaList(key, change, detail, now) {
+  const meta = detail ? detail.metadata : {};
+  const created = parseLooseDate(meta.created || change.created);
+  const items = [
+    ['schema', meta.schema || change.schema || '未知'],
+    meta.type || change.type ? ['type', meta.type || change.type] : null,
+    created ? ['created', formatDate(created)] : null,
+    ['更新', relTime(change.lastModified, now)],
+  ].filter(Boolean);
+  const list = el('dl', { class: 'meta' }, items.flatMap(([k, v]) => [el('dt', { text: k }), el('dd', { text: v })]));
+  const decisions = (meta.decisions || []);
+  if (decisions.length) {
+    list.append(
+      el('dt', { text: 'decisions' }),
+      el('dd', {}, decisions.flatMap((f, i) => [i ? ', ' : null, el('a', { href: routes.decisions(key, f), text: f })]))
+    );
+  }
+  return list;
+}
+
+/** The change's place on its project line, with the stations it has passed; none is marked when unknown. */
+function stationStrip(station) {
+  const at = stationIndex(station);
+  return el('ol', { class: 'station-strip', 'aria-label': '目前階段' }, STATIONS.map((s, i) =>
+    el('li', { class: 'strip-stop' + (i === at ? ' is-here' : at >= 0 && i < at ? ' is-passed' : ''), 'aria-current': i === at ? 'step' : null }, [
+      el('span', { class: 'strip-dot', 'aria-hidden': 'true' }),
+      el('span', { class: 'strip-label', text: s.label }),
+    ])
+  ));
+}
+
+/**
+ * Artifacts in schema declaration order. The inner line is drawn straight on
+ * purpose: the detail payload names unmet dependencies only, not the full
+ * `requires` graph, so a branch drawn here would be a guess.
+ */
+function artifactRoute(detail) {
+  if (!detail.artifacts.length) return el('section', { class: 'detail-section' }, [el('h2', { class: 'section-title', text: 'Artifacts' }), note('schema 無法解析, 沒有 artifact 狀態.')]);
+  return el('section', { class: 'detail-section' }, [
+    el('h2', { class: 'section-title', text: 'Artifacts' }),
+    el('ol', { class: 'artifact-route' }, detail.artifacts.map((a) =>
+      el('li', { class: 'artifact-stop status-' + a.status }, [
+        el('span', { class: 'artifact-dot', 'aria-hidden': 'true' }),
+        el('span', { class: 'artifact-id', text: a.id }),
+        el('span', { class: 'artifact-state', text: a.status === 'blocked' && a.missingDeps ? '等 ' + a.missingDeps.join(', ') : ARTIFACT_STATUS[a.status] || a.status }),
+      ])
+    )),
+  ]);
+}
+
+// --- tasks ---------------------------------------------------------------------
+
+function taskSection(project, change) {
+  const { completed, total } = change.taskProgress;
+  const section = el('section', { class: 'detail-section tasks' });
+  const meter = el('span', { class: 'meter meter-wide', 'aria-hidden': 'true' }, [el('span', { class: 'meter-fill' })]);
+  meter.firstChild.style.setProperty('width', total ? Math.round((completed / total) * 100) + '%' : '0%');
+  section.append(el('div', { class: 'section-head' }, [
+    el('h2', { class: 'section-title' }, ['Task', el('span', { class: 'count', text: `${completed}/${total}` })]),
+    total ? meter : null,
+  ]));
+  if (!total) {
+    section.append(note('這個 change 還沒有 task.'));
+    return section;
+  }
+  // The server enforces both locks too; the page only mirrors them so a click
+  // is not offered that would be refused.
+  const locked = change.phase === 'archiving';
+  const offline = !project.online;
+  if (locked) section.append(el('p', { class: 'lock-note' }, [icon('lock', 14), 'sync 已通過, 正在等 archive; task 已凍結.']));
+  else if (offline) section.append(el('p', { class: 'lock-note' }, [icon('lock', 14), '沒有 session 連線, 勾選要由 session 寫回檔案, 現在只能閱讀.']));
+
+  const files = [...new Set(change.tasks.map((t) => t.file))];
+  for (const file of files) {
+    if (files.length > 1) section.append(el('p', { class: 'task-file mono', text: file }));
+    const list = el('ul', { class: 'task-list' });
+    for (const task of change.tasks) {
+      if (task.file === file) list.append(taskItem(project.key, task, locked || offline));
+    }
+    section.append(list);
+  }
+  return section;
+}
+
+/**
+ * One checkbox that writes back to its markdown file through a live session.
+ * The file is the source of truth: a failed write reverts the box instead of
+ * leaving the page claiming what the file does not say.
+ */
+function taskItem(key, task, disabled) {
+  const box = el('input', { type: 'checkbox', class: 'task-box' });
+  box.checked = task.done;
+  box.disabled = disabled;
+  const item = el('li', { class: 'task-item' + (task.done ? ' is-done' : '') + (disabled ? ' is-locked' : '') }, [
+    el('label', { class: 'task-label' }, [box, el('span', { class: 'task-text', text: task.text })]),
+  ]);
+  // Mirrors the file's nesting; two spaces of markdown indent read as one step.
+  if (task.indent) item.style.setProperty('margin-left', task.indent * 10 + 'px');
+  box.addEventListener('change', async () => {
+    const want = box.checked;
+    box.disabled = true;
+    item.classList.add('is-saving');
+    item.querySelectorAll('.task-error').forEach((n) => n.remove());
+    try {
+      await postTask(key, task.file, task.line, want);
+      item.classList.toggle('is-done', want);
+      await loadProject(key);
+    } catch (e) {
+      box.checked = !want;
+      item.append(el('span', { class: 'task-error', text: '寫入失敗: ' + e.message + '. 檔案沒有變更.' }));
+    } finally {
+      box.disabled = false;
+      item.classList.remove('is-saving');
+    }
+  });
+  return item;
+}
+
+// --- files ---------------------------------------------------------------------
+
+function fileSection(key, project, detail) {
+  const section = el('section', { class: 'detail-section files' }, [el('h2', { class: 'section-title' }, ['檔案', el('span', { class: 'count', text: String(detail.files.length) })])]);
+  if (!detail.files.length) {
+    section.append(note('還沒有檔案.'));
+    return section;
+  }
+  for (const file of detail.files) {
+    const details = el('details', { class: 'file' });
+    const body = el('div', { class: 'rendered' });
+    details.append(
+      el('summary', { class: 'file-summary' }, [
+        icon('chevron', 14),
+        el('span', { class: 'file-path mono', text: file.path }),
+        file.artifactId ? el('span', { class: 'tag', text: file.artifactId }) : null,
+      ]),
+      body
+    );
+    const openKey = key + '|' + file.path;
+    const load = () => renderMarkdown(key, project, file.path, body);
+    if (openFiles.has(openKey)) {
+      details.open = true;
+      load();
+    }
+    details.addEventListener('toggle', () => {
+      if (details.open) {
+        openFiles.add(openKey);
+        load();
+      } else {
+        openFiles.delete(openKey);
+      }
+    });
+    section.append(details);
+  }
+  return section;
+}

package/assets/dashboard/views/docs.js

@@ -0,0 +1,214 @@
+// Reading views: a spec, the decision index and reader, and the rendered
+// markdown behind change files. Rendering is the one read a snapshot cannot
+// pre-answer, so it needs a live session and is cached until the project's
+// next push.
+
+import { el, note, icon, paintLine } from '../lib/dom.js';
+import { formatStamp } from '../lib/derive.js';
+import { projectApi, dataOf, slotOf, projectByKey, loadDecisions } from '../lib/store.js';
+import { routes } from '../lib/routes.js';
+import { projectHeader } from './project.js';
+
+/** `<key>|<path>` -> { html, stale }. Marked stale, not dropped, when the project pushes. */
+const renderCache = new Map();
+/** Change files the user has open, kept across live re-renders. */
+export const openFiles = new Set();
+/** Decision search text, kept while moving between decisions. */
+let decisionQuery = '';
+
+export function clearRenderCache(key) {
+  for (const [cacheKey, entry] of renderCache) {
+    if (cacheKey.startsWith(key + '|')) entry.stale = true;
+  }
+}
+
+/**
+ * Renders a project file into `body` and calls `after` each time HTML lands.
+ * A stale copy is shown at once and swapped when the fresh one arrives: an
+ * agent editing a file pushes often, and a blank "rendering" flash on every
+ * push would throw the reader's place away.
+ */
+export async function renderMarkdown(key, project, path, body, after = () => {}) {
+  const cacheKey = key + '|' + path;
+  const cached = renderCache.get(cacheKey);
+  if (cached) {
+    body.innerHTML = cached.html; // sanitized by core/markdown-render.ts - raw HTML is escaped there, not here
+    after();
+    if (!cached.stale) return;
+  } else {
+    body.replaceChildren(note('正在渲染.'));
+  }
+  try {
+    const data = await projectApi(key, '/render?file=' + encodeURIComponent(path));
+    renderCache.set(cacheKey, { html: data.html, stale: false });
+    if (cached && cached.html === data.html) return;
+    if (!body.isConnected && cached) return;
+    body.innerHTML = data.html; // sanitized by core/markdown-render.ts - raw HTML is escaped there, not here
+    after();
+  } catch (e) {
+    if (cached) return; // keep the last good render rather than replace it with an error
+    const offline = e.status === 503 || (project && !project.online);
+    body.replaceChildren(note(offline
+      ? '文件內容由 session 即時渲染, 這個 project 目前沒有 session 連線. 在該 project 開啟 Claude Code 後就能閱讀.'
+      : '渲染失敗: ' + e.message));
+  }
+}
+
+/**
+ * Names the section the reader is in, recomputed on scroll: long specs and
+ * ADRs lose their heading off the top of the screen within a page or two.
+ */
+function runningHead(container, signal) {
+  const head = el('div', { class: 'running-head', 'aria-hidden': 'true' }, [el('span', { class: 'running-text' })]);
+  const update = () => {
+    const headings = container.querySelectorAll('h2, h3');
+    const offset = 120;
+    let current = null;
+    for (const h of headings) {
+      if (h.getBoundingClientRect().top <= offset) current = h;
+      else break;
+    }
+    head.firstChild.textContent = current ? current.textContent : '';
+    head.classList.toggle('is-empty', !current);
+  };
+  window.addEventListener('scroll', update, { passive: true, signal });
+  head.classList.add('is-empty');
+  return { head, update };
+}
+
+// --- spec ----------------------------------------------------------------------
+
+export function renderSpec(route, ctx) {
+  const project = projectByKey(route.key);
+  const data = dataOf(route.key);
+  const spec = data.overview && data.overview.specs.find((s) => s.id === route.id);
+  const page = paintLine(el('div', { class: 'page page-doc' }), slotOf(route.key));
+  page.append(
+    el('header', { class: 'doc-head' }, [
+      el('h1', { class: 'page-title', text: route.id }),
+      spec ? el('p', { class: 'page-sub', text: `${spec.requirementCount} 條 requirement · tospec/specs/${route.id}/spec.md` }) : null,
+    ])
+  );
+  const body = el('article', { class: 'rendered doc-body' });
+  const toc = el('nav', { class: 'doc-toc', 'aria-label': 'requirement 目錄' });
+  const { head, update } = runningHead(body, ctx.signal);
+  page.append(head, el('div', { class: 'doc-layout' }, [toc, body]));
+  if (!data.overview) ctx.waiting = true;
+  renderMarkdown(route.key, project, `tospec/specs/${route.id}/spec.md`, body, () => {
+    buildToc(toc, body);
+    update();
+  });
+  return page;
+}
+
+/** Requirement headings as buttons: hash links would fight the hash router. */
+function buildToc(toc, body) {
+  const headings = [...body.querySelectorAll('h3')];
+  toc.replaceChildren();
+  toc.hidden = headings.length < 2;
+  if (toc.hidden) return;
+  toc.append(el('p', { class: 'toc-title', text: 'Requirement' }));
+  const list = el('ol', { class: 'toc-list' });
+  for (const h of headings) {
+    const button = el('button', { type: 'button', class: 'toc-link', text: h.textContent.replace(/^Requirement:\s*/i, '') });
+    button.addEventListener('click', () => h.scrollIntoView({ behavior: matchMedia('(prefers-reduced-motion: reduce)').matches ? 'auto' : 'smooth', block: 'start' }));
+    list.append(el('li', {}, [button]));
+  }
+  toc.append(list);
+}
+
+// --- decisions -------------------------------------------------------------------
+
+export function renderDecisions(route, ctx) {
+  const project = projectByKey(route.key);
+  const page = paintLine(el('div', { class: 'page page-decisions' }), slotOf(route.key));
+  if (!project) {
+    ctx.waiting = true;
+    page.append(el('h1', { class: 'page-title', text: 'Decisions' }), note('找不到這個 project.'));
+    return page;
+  }
+  const data = dataOf(route.key);
+  page.append(projectHeader(project, 'decisions'));
+  if (!data.decisions) {
+    ctx.waiting = true;
+    if (!data.decisionsError) loadDecisions(route.key);
+    page.append(note(data.decisionsError ? '決策讀取失敗: ' + data.decisionsError : '正在讀取決策.'));
+    return page;
+  }
+  const decisions = data.decisions;
+  if (!decisions.length) {
+    page.append(note('還沒有決策記錄. 用 tospec-decision skill 或 tospec decision new <topic> 建立第一筆.'));
+    return page;
+  }
+  const active = decisions.find((d) => d.file === route.file) || decisions[0];
+
+  const search = el('input', { type: 'search', class: 'search', placeholder: '搜尋標題, status, 內文', 'aria-label': '搜尋決策' });
+  search.value = decisionQuery;
+  const list = el('ul', { class: 'decision-list' });
+  const fill = () => {
+    decisionQuery = search.value;
+    const q = decisionQuery.trim().toLowerCase();
+    const matches = decisions.filter((d) => !q || (d.title + ' ' + d.topic + ' ' + d.status + ' ' + d.content).toLowerCase().includes(q));
+    list.replaceChildren(...(matches.length
+      ? matches.map((d) => el('li', {}, [
+          el('a', { class: 'decision-link', href: routes.decisions(route.key, d.file), 'aria-current': d === active ? 'page' : null }, [
+            el('span', { class: 'decision-title', text: d.title }),
+            el('span', { class: 'decision-meta' }, [el('span', { class: 'mono', text: formatStamp(d.date) }), el('span', { class: 'tag status-' + d.status, text: d.status })]),
+          ]),
+        ]))
+      : [el('li', {}, [note('沒有符合的決策.')])]));
+  };
+  search.addEventListener('input', fill);
+  fill();
+  const index = el('aside', { class: 'decision-index' }, [el('label', { class: 'search-wrap' }, [icon('search', 14), search]), list]);
+
+  const body = el('div', { class: 'rendered doc-body' });
+  const { head, update } = runningHead(body, ctx.signal);
+  const reader = el('article', { class: 'decision-reader' }, [
+    el('h2', { class: 'reader-title', text: active.title }),
+    el('dl', { class: 'meta' }, [el('dt', { text: 'date' }), el('dd', { text: formatStamp(active.date) }), el('dt', { text: 'status' }), el('dd', { text: active.status }), el('dt', { text: 'file' }), el('dd', { class: 'mono', text: active.file })]),
+    head,
+    body,
+  ]);
+  renderMarkdown(route.key, project, active.path, body, () => {
+    // The reader already heads the page with the title the record's H1 repeats.
+    const h1 = body.querySelector('h1');
+    if (h1 && h1.textContent.trim() === active.title.trim()) h1.remove();
+    enhanceDecisionQA(body, active.content);
+    update();
+  });
+  page.append(el('div', { class: 'decision-layout' }, [index, reader]));
+  return page;
+}
+
+/**
+ * `{ q, a }` pairs from the `## 決策過程` section of raw markdown: a `**Q:**`
+ * line, then the answer until the next `**Q:**` or `## ` heading. Old-format or
+ * empty sections yield `[]`, which leaves the rendered markdown as it is.
+ */
+export 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);
+  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 pairs, 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();
+  heading.after(el('dl', { class: 'qa-list' }, pairs.flatMap((p) => [el('dt', { class: 'qa-q', text: p.q }), el('dd', { class: 'qa-a', text: p.a })])));
+}