@copperbox/why 1.0.0

package/ui/app.js

@@ -0,0 +1,323 @@
+// The `why serve` SPA shell: hash-routed views (file tree + blame gutter,
+// graph, doctor list) over the UI data contract payloads. Dumb renderer by
+// design — confidence, hedging, and health semantics all arrive precomputed
+// from the JSON API; nothing here re-derives them (docs/ui-contract.md).
+
+import { renderGraph, TYPE_COLORS } from "./graph.js";
+import { appendTokens, langForPath, tokenize } from "./highlight.js";
+import { renderStoryPanel } from "./story-panel.js";
+
+const doc = document;
+
+const state = {
+  files: [],
+  /** path → coverage spans (schemas/coverage.schema.json). */
+  coverage: new Map(),
+  coverageHead: "",
+  doctor: null,
+  stopGraph: null,
+};
+
+async function api(path) {
+  const res = await fetch(path);
+  if (!res.ok) {
+    const body = await res.json().catch(() => ({}));
+    throw new Error(body.error ?? `${res.status} on ${path}`);
+  }
+  return res.json();
+}
+
+function h(tag, className, text) {
+  const node = doc.createElement(tag);
+  if (className) node.className = className;
+  if (text !== undefined) node.textContent = text;
+  return node;
+}
+
+function clear(node) {
+  while (node.firstChild) node.removeChild(node.firstChild);
+}
+
+async function refreshCoverage() {
+  const coverage = await api("/api/coverage");
+  state.coverage = new Map(coverage.files.map((file) => [file.path, file.spans]));
+  state.coverageHead = coverage.head;
+}
+
+// --- Header ------------------------------------------------------------------
+
+const CHIP_SPECS = [
+  ["lostAnchors", "lost anchors"],
+  ["reviewByPastDue", "overdue reviews"],
+  ["openQuestions", "open questions"],
+];
+
+function renderChips(container) {
+  clear(container);
+  if (!state.doctor) return;
+  const sections = new Map(state.doctor.sections.map((section) => [section.key, section]));
+  for (const [key, label] of CHIP_SPECS) {
+    const section = sections.get(key);
+    if (!section) continue;
+    const tone = section.count === 0 ? "ok" : section.severity;
+    const chip = h("a", `chip chip-${tone}`, `${section.count} ${label}`);
+    chip.href = "#/doctor";
+    container.append(chip);
+  }
+}
+
+// --- File tree -----------------------------------------------------------------
+
+function buildTree(paths) {
+  const root = { dirs: new Map(), files: [] };
+  for (const path of paths) {
+    const parts = path.split("/");
+    let node = root;
+    for (const part of parts.slice(0, -1)) {
+      if (!node.dirs.has(part)) node.dirs.set(part, { dirs: new Map(), files: [] });
+      node = node.dirs.get(part);
+    }
+    node.files.push({ name: parts[parts.length - 1], path });
+  }
+  return root;
+}
+
+function renderTree(node, openDepth) {
+  const list = h("ul", "tree");
+  for (const [name, child] of [...node.dirs.entries()].sort((a, b) => a[0].localeCompare(b[0]))) {
+    const item = h("li");
+    const details = h("details");
+    if (openDepth > 0) details.open = true;
+    details.append(h("summary", "dir", name));
+    details.append(renderTree(child, openDepth - 1));
+    item.append(details);
+    list.append(item);
+  }
+  for (const file of node.files.sort((a, b) => a.name.localeCompare(b.name))) {
+    const item = h("li");
+    const link = h("a", "file", file.name);
+    link.href = `#/file/${encodeURIComponent(file.path)}`;
+    if (state.coverage.has(file.path)) link.append(h("span", "covered-dot", "●"));
+    item.append(link);
+    list.append(item);
+  }
+  return list;
+}
+
+// --- File view ------------------------------------------------------------------
+
+/** Rough age for the git column: newest-commit recency at a glance. */
+function age(dateStr) {
+  const days = Math.max(0, Math.floor((Date.now() - Date.parse(dateStr)) / 86400000));
+  if (days < 30) return `${days}d`;
+  if (days < 365) return `${Math.floor(days / 30)}mo`;
+  return `${Math.floor(days / 365)}y`;
+}
+
+function covering(spans, line) {
+  return spans.filter(
+    (span) => span.lines === undefined || (span.lines.start <= line && line <= span.lines.end),
+  );
+}
+
+/** The gutter treatment for one line: scar tissue and open questions stand
+ * apart; everything else colors by confidence (docs/ui-contract.md). */
+function stripeClass(spans) {
+  if (spans.length === 0) return "";
+  if (spans.some((span) => span.type === "constraint" && span.status === "expired")) return "why-expired";
+  if (spans.some((span) => span.type === "question")) return "why-question";
+  return `why-conf-${spans[0].confidence ?? "none"}`;
+}
+
+async function showFile(path, fileView, storyPanel) {
+  clear(fileView);
+  fileView.append(h("h2", "file-path", path));
+  let blame;
+  try {
+    blame = await api(`/api/blame?path=${encodeURIComponent(path)}`);
+  } catch (e) {
+    fileView.append(h("p", "error", e.message));
+    return;
+  }
+  // HEAD moved since the coverage snapshot — refresh rather than paint stale spans.
+  if (blame.head !== state.coverageHead) await refreshCoverage();
+  const spans = state.coverage.get(path) ?? [];
+
+  const table = h("table", "code");
+  const lang = langForPath(path);
+  let hlState = null; // threaded across lines so a block comment can span rows
+  let prevSha = "";
+  blame.lines.forEach((line, i) => {
+    const n = i + 1;
+    const row = h("tr");
+    row.append(h("td", "num", String(n)));
+    const gitCell = h("td", "git");
+    if (line.sha !== prevSha) {
+      gitCell.textContent = `${line.author} · ${age(line.date)}`;
+      gitCell.title = `${line.sha.slice(0, 10)} ${line.date} — ${line.summary}`;
+      row.classList.add("group-start");
+    }
+    prevSha = line.sha;
+    row.append(gitCell);
+    const here = covering(spans, n);
+    const why = h("td", `why ${stripeClass(here)}`);
+    if (here.length > 0) {
+      why.textContent = here[0].glyph;
+      why.title = here.map((span) => span.conceptId).join("\n");
+      row.classList.add("covered");
+    }
+    row.append(why);
+    const textCell = h("td", "text");
+    const { tokens, state } = tokenize(line.text, lang, hlState);
+    hlState = state;
+    appendTokens(doc, textCell, tokens);
+    row.append(textCell);
+    row.onclick = () => showStory(path, n, storyPanel);
+    table.append(row);
+  });
+  fileView.append(table);
+}
+
+async function showStory(path, line, storyPanel) {
+  clear(storyPanel);
+  try {
+    const story = await api(`/api/story?path=${encodeURIComponent(path)}&start=${line}&end=${line}`);
+    storyPanel.append(renderStoryPanel(doc, story));
+  } catch (e) {
+    storyPanel.append(h("p", "error", e.message));
+  }
+}
+
+// --- Views -----------------------------------------------------------------------
+
+function filesView(main, filePath) {
+  const layout = h("div", "layout");
+  const sidebar = h("aside", "sidebar");
+  sidebar.append(renderTree(buildTree(state.files), 2));
+  const fileView = h("section", "file-view");
+  const storyPanel = h("aside", "story-panel");
+  storyPanel.append(h("p", "hint", "Click a line to see the story behind it."));
+  layout.append(sidebar, fileView, storyPanel);
+  main.append(layout);
+  if (filePath) void showFile(filePath, fileView, storyPanel);
+  else fileView.append(h("p", "hint", "Pick a file — ● marks files with a recorded why."));
+}
+
+async function graphView(main) {
+  const wrap = h("section", "graph-view");
+  const legend = h("div", "legend");
+  for (const [type, color] of Object.entries(TYPE_COLORS)) {
+    const entry = h("span", "legend-entry", type);
+    const dot = h("span", "legend-dot", "●");
+    dot.style.color = color;
+    entry.prepend(dot);
+    legend.append(entry);
+  }
+  wrap.append(legend);
+  const canvas = doc.createElement("canvas");
+  wrap.append(canvas);
+  main.append(wrap);
+  canvas.width = Math.max(wrap.clientWidth - 16, 480);
+  canvas.height = Math.max(doc.documentElement.clientHeight - 180, 420);
+  try {
+    const graph = await api("/api/graph");
+    state.stopGraph = renderGraph(canvas, graph);
+  } catch (e) {
+    wrap.append(h("p", "error", e.message));
+  }
+}
+
+async function doctorView(main) {
+  const wrap = h("section", "doctor-view");
+  main.append(wrap);
+  try {
+    const doctor = await api("/api/doctor");
+    state.doctor = doctor;
+    renderChips(doc.getElementById("chips"));
+    const headline = doctor.healthy ? "healthy" : "unhealthy";
+    wrap.append(
+      h(
+        "h2",
+        `doctor-headline ${doctor.healthy ? "ok" : "red"}`,
+        `why doctor: ${doctor.concepts} concepts — ${doctor.red} red, ${doctor.yellow} yellow (${headline})`,
+      ),
+    );
+    for (const section of doctor.sections) {
+      const block = h("section", "doctor-section");
+      const tone = section.count === 0 ? "ok" : section.severity;
+      block.append(h("h3", `doctor-title tone-${tone}`, `${section.title} — ${section.count}`));
+      if (section.skipped) block.append(h("p", "hint", `not checked: ${section.skipped}`));
+      if (section.items.length > 0) {
+        const list = h("ul", "doctor-items");
+        for (const item of section.items) list.append(h("li", "doctor-item", item));
+        block.append(list);
+      }
+      wrap.append(block);
+    }
+  } catch (e) {
+    wrap.append(h("p", "error", e.message));
+  }
+}
+
+// --- Shell + routing ---------------------------------------------------------------
+
+function route() {
+  const main = doc.getElementById("main");
+  clear(main);
+  if (state.stopGraph) {
+    state.stopGraph();
+    state.stopGraph = null;
+  }
+  const hash = decodeURIComponent(location.hash);
+  const segment = hash.split("/")[1] ?? "";
+  const activeTab = segment === "file" ? "" : segment; // a file view is the Files tab
+  for (const link of doc.querySelectorAll("nav a")) {
+    link.classList.toggle("active", link.dataset.route === activeTab);
+  }
+  if (hash.startsWith("#/file/")) filesView(main, hash.slice("#/file/".length));
+  else if (hash === "#/graph") void graphView(main);
+  else if (hash === "#/doctor") void doctorView(main);
+  else filesView(main, null);
+}
+
+async function boot() {
+  const app = doc.getElementById("app");
+  const header = h("header", "topbar");
+  header.append(h("span", "brand", "why"));
+  const nav = h("nav");
+  for (const [label, href, route] of [
+    ["Files", "#/", ""],
+    ["Graph", "#/graph", "graph"],
+    ["Doctor", "#/doctor", "doctor"],
+  ]) {
+    const link = h("a", "tab", label);
+    link.href = href;
+    link.dataset.route = route;
+    nav.append(link);
+  }
+  header.append(nav);
+  const chips = h("span", "chips");
+  chips.id = "chips";
+  header.append(chips);
+  const main = h("main");
+  main.id = "main";
+  app.append(header, main);
+
+  try {
+    const [files, , doctor] = await Promise.all([
+      api("/api/files"),
+      refreshCoverage(),
+      api("/api/doctor"),
+    ]);
+    state.files = files.files;
+    state.doctor = doctor;
+  } catch (e) {
+    main.append(h("p", "error", e.message));
+    return;
+  }
+  renderChips(chips);
+  window.addEventListener("hashchange", route);
+  route();
+}
+
+void boot();

package/ui/graph.js

@@ -0,0 +1,164 @@
+// Graph tab: the bundle graph payload (schemas/graph.schema.json) drawn with
+// a hand-rolled canvas force simulation — the okf-mcp `graph html` approach
+// (embedded, zero dependencies), reimplemented here against the contract's
+// nodes/edges shape. Type-colored nodes, relation-labeled edges, drag to pin.
+
+export const TYPE_COLORS = {
+  decision: "#5b9cf5",
+  constraint: "#e2a336",
+  attempt: "#8d97a5",
+  incident: "#e05d5d",
+  question: "#b57edc",
+};
+
+const RADIUS = 9;
+
+function initNodes(graph, width, height) {
+  // Deterministic ring seeding — stable layouts across reloads beat jitter.
+  return graph.nodes.map((node, i) => {
+    const angle = (2 * Math.PI * i) / graph.nodes.length;
+    const ring = Math.min(width, height) / 4;
+    return {
+      ...node,
+      x: width / 2 + ring * Math.cos(angle),
+      y: height / 2 + ring * Math.sin(angle),
+      vx: 0,
+      vy: 0,
+      pinned: false,
+    };
+  });
+}
+
+function tick(nodes, edges, width, height) {
+  for (let i = 0; i < nodes.length; i++) {
+    const a = nodes[i];
+    // Pairwise repulsion.
+    for (let j = i + 1; j < nodes.length; j++) {
+      const b = nodes[j];
+      const dx = a.x - b.x;
+      const dy = a.y - b.y;
+      const d2 = Math.max(dx * dx + dy * dy, 25);
+      const force = 2600 / d2;
+      const d = Math.sqrt(d2);
+      a.vx += (dx / d) * force;
+      a.vy += (dy / d) * force;
+      b.vx -= (dx / d) * force;
+      b.vy -= (dy / d) * force;
+    }
+    // Gravity toward the center.
+    a.vx += (width / 2 - a.x) * 0.005;
+    a.vy += (height / 2 - a.y) * 0.005;
+  }
+  // Edge springs.
+  for (const edge of edges) {
+    const dx = edge.to.x - edge.from.x;
+    const dy = edge.to.y - edge.from.y;
+    const d = Math.max(Math.sqrt(dx * dx + dy * dy), 1);
+    const force = (d - 130) * 0.02;
+    edge.from.vx += (dx / d) * force;
+    edge.from.vy += (dy / d) * force;
+    edge.to.vx -= (dx / d) * force;
+    edge.to.vy -= (dy / d) * force;
+  }
+  for (const node of nodes) {
+    if (node.pinned) {
+      node.vx = 0;
+      node.vy = 0;
+      continue;
+    }
+    node.vx *= 0.85;
+    node.vy *= 0.85;
+    node.x = Math.min(Math.max(node.x + node.vx, RADIUS * 2), width - RADIUS * 2);
+    node.y = Math.min(Math.max(node.y + node.vy, RADIUS * 2), height - RADIUS * 2);
+  }
+}
+
+function draw(ctx, nodes, edges, width, height) {
+  ctx.clearRect(0, 0, width, height);
+  ctx.font = "11px system-ui, sans-serif";
+  for (const edge of edges) {
+    ctx.strokeStyle = "#5a6472";
+    ctx.lineWidth = 1;
+    ctx.beginPath();
+    ctx.moveTo(edge.from.x, edge.from.y);
+    ctx.lineTo(edge.to.x, edge.to.y);
+    ctx.stroke();
+    // Arrowhead toward the target.
+    const dx = edge.to.x - edge.from.x;
+    const dy = edge.to.y - edge.from.y;
+    const d = Math.max(Math.sqrt(dx * dx + dy * dy), 1);
+    const tipX = edge.to.x - (dx / d) * (RADIUS + 3);
+    const tipY = edge.to.y - (dy / d) * (RADIUS + 3);
+    ctx.fillStyle = "#5a6472";
+    ctx.beginPath();
+    ctx.moveTo(tipX, tipY);
+    ctx.lineTo(tipX - (dx / d) * 7 - (dy / d) * 3.5, tipY - (dy / d) * 7 + (dx / d) * 3.5);
+    ctx.lineTo(tipX - (dx / d) * 7 + (dy / d) * 3.5, tipY - (dy / d) * 7 - (dx / d) * 3.5);
+    ctx.fill();
+    // Relation label at the midpoint.
+    ctx.fillStyle = "#8b95a5";
+    ctx.textAlign = "center";
+    ctx.fillText(edge.relation, (edge.from.x + edge.to.x) / 2, (edge.from.y + edge.to.y) / 2 - 4);
+  }
+  for (const node of nodes) {
+    ctx.beginPath();
+    ctx.arc(node.x, node.y, RADIUS, 0, 2 * Math.PI);
+    ctx.fillStyle = TYPE_COLORS[node.type] ?? "#8d97a5";
+    ctx.fill();
+    if (node.status === "expired" || node.status === "superseded") {
+      ctx.strokeStyle = "#ff6b6b";
+      ctx.lineWidth = 2.5;
+      ctx.stroke();
+    }
+    ctx.fillStyle = "#dde3ec";
+    ctx.textAlign = "center";
+    ctx.fillText(node.title, node.x, node.y + RADIUS + 13);
+  }
+}
+
+/** Run the simulation on `canvas`; returns a stop() for teardown. */
+export function renderGraph(canvas, graph) {
+  const ctx = canvas.getContext("2d");
+  const width = canvas.width;
+  const height = canvas.height;
+  const nodes = initNodes(graph, width, height);
+  const byId = new Map(nodes.map((node) => [node.id, node]));
+  const edges = graph.edges.map((edge) => ({
+    from: byId.get(edge.from),
+    to: byId.get(edge.to),
+    relation: edge.relation,
+  }));
+
+  let dragging = null;
+  const pos = (event) => {
+    const rect = canvas.getBoundingClientRect();
+    return { x: event.clientX - rect.left, y: event.clientY - rect.top };
+  };
+  canvas.onmousedown = (event) => {
+    const { x, y } = pos(event);
+    dragging = nodes.find((n) => (n.x - x) ** 2 + (n.y - y) ** 2 <= (RADIUS + 4) ** 2) ?? null;
+    if (dragging) dragging.pinned = true;
+  };
+  canvas.onmousemove = (event) => {
+    if (!dragging) return;
+    const { x, y } = pos(event);
+    dragging.x = x;
+    dragging.y = y;
+  };
+  canvas.onmouseup = () => {
+    if (dragging) dragging.pinned = false;
+    dragging = null;
+  };
+
+  let running = true;
+  const frame = () => {
+    if (!running) return;
+    tick(nodes, edges, width, height);
+    draw(ctx, nodes, edges, width, height);
+    requestAnimationFrame(frame);
+  };
+  requestAnimationFrame(frame);
+  return () => {
+    running = false;
+  };
+}

package/ui/highlight.js

@@ -0,0 +1,202 @@
+// Hand-rolled, dependency-free syntax highlighting for the file view — the same
+// self-contained/zero-CDN philosophy as the graph's canvas force sim (ui/graph.js).
+// Highlighting is pure presentation: it colors the code text the blame payload
+// already carries and asserts nothing about the *why*, so it lives in the client
+// renderer rather than in the UI data contract.
+//
+// `tokenize` is a small, stateless-per-call lexer that a caller drives line by
+// line, threading the returned `state` back in so a block comment can span rows
+// (blame gives us one line at a time). It is deliberately best-effort: unknown
+// languages, multi-line strings, and Rust lifetimes vs char literals are handled
+// gracefully but not perfectly. Every character of the input is emitted in some
+// token, so joining the token texts always reproduces the line verbatim.
+
+/** Extensions → a language key in LANGS, or null for "render as plain text". */
+const LANG_BY_EXTENSION = {
+  ".ts": "ts", ".mts": "ts", ".cts": "ts", ".tsx": "ts",
+  ".js": "ts", ".mjs": "ts", ".cjs": "ts", ".jsx": "ts",
+  ".rs": "rust",
+  ".py": "python", ".pyi": "python",
+  ".go": "go",
+  ".c": "c", ".h": "c", ".cc": "c", ".cpp": "c", ".hpp": "c", ".cxx": "c",
+  ".java": "c", ".cs": "c",
+  ".json": "json",
+};
+
+const words = (s) => new Set(s.split(/\s+/).filter(Boolean));
+
+// A language is a lexer config, not a grammar: comment/string delimiters plus a
+// keyword set. `char` enables Rust-style char-literal detection so lifetimes
+// (`'a`) are not mistaken for an unterminated string.
+const LANGS = {
+  ts: {
+    line: "//", block: ["/*", "*/"], quotes: ["\"", "'", "`"],
+    keywords: words(`abstract any as async await boolean break case catch class const continue
+      debugger declare default delete do else enum export extends false finally for from function
+      get if implements import in infer instanceof interface is keyof let module namespace never new
+      null number object of override private protected public readonly return satisfies set static
+      string super switch symbol this throw true try type typeof undefined unknown var void while
+      with yield`),
+  },
+  rust: {
+    line: "//", block: ["/*", "*/"], quotes: ["\""], char: true,
+    keywords: words(`as async await bool break char const continue crate dyn else enum extern false
+      fn for i8 i16 i32 i64 i128 if impl in isize let loop match mod move mut pub ref return self
+      Self static str struct super trait true type u8 u16 u32 u64 u128 union unsafe use usize where
+      while f32 f64`),
+  },
+  python: {
+    line: "#", block: null, quotes: ["\"", "'"],
+    keywords: words(`and as assert async await break class continue def del elif else except False
+      finally for from global if import in is lambda None nonlocal not or pass raise return True try
+      while with yield self`),
+  },
+  go: {
+    line: "//", block: ["/*", "*/"], quotes: ["\"", "`", "'"], char: true,
+    keywords: words(`break case chan const continue default defer else fallthrough for func go goto
+      if import interface map package range return select struct switch type var bool byte error
+      false float32 float64 int int8 int16 int32 int64 nil rune string true uint uintptr`),
+  },
+  c: {
+    line: "//", block: ["/*", "*/"], quotes: ["\"", "'"],
+    keywords: words(`auto bool break case catch char class const constexpr continue default delete
+      do double else enum extern false final float for friend goto if inline int long namespace new
+      nullptr operator override private protected public register return short signed sizeof static
+      struct switch template this throw true try typedef typename union unsigned using virtual void
+      volatile while`),
+  },
+  json: { line: null, block: null, quotes: ["\""], keywords: words("true false null") },
+};
+
+const isIdentStart = (ch) => /[A-Za-z_$]/.test(ch);
+const isIdent = (ch) => /[A-Za-z0-9_$]/.test(ch);
+const isDigit = (ch) => ch >= "0" && ch <= "9";
+
+/** File extension of a repo-relative path, lowercased, including the dot. */
+function extname(path) {
+  const base = path.slice(path.lastIndexOf("/") + 1);
+  const dot = base.lastIndexOf(".");
+  return dot <= 0 ? "" : base.slice(dot).toLowerCase();
+}
+
+/** The language key for a path, or null when we have no lexer for it. */
+export function langForPath(path) {
+  return LANG_BY_EXTENSION[extname(path)] ?? null;
+}
+
+/**
+ * Lex one line into `{ text, cls }` runs. `cls` is a token class ("kw", "str",
+ * "com", "num", "type", "fn") or null for plain text. `state` carries a pending
+ * block comment across lines; pass the returned `state` into the next line.
+ */
+export function tokenize(text, lang, state) {
+  const spec = lang && LANGS[lang];
+  if (!spec) return { tokens: text === "" ? [] : [{ text, cls: null }], state: null };
+
+  const tokens = [];
+  let plain = "";
+  const flush = () => {
+    if (plain !== "") tokens.push({ text: plain, cls: null });
+    plain = "";
+  };
+  const push = (t, cls) => {
+    flush();
+    tokens.push({ text: t, cls });
+  };
+
+  let i = 0;
+  // Resume an open block comment from the previous line.
+  if (state && state.block && spec.block) {
+    const close = text.indexOf(spec.block[1]);
+    if (close === -1) {
+      return { tokens: [{ text, cls: "com" }], state: { block: true } };
+    }
+    push(text.slice(0, close + spec.block[1].length), "com");
+    i = close + spec.block[1].length;
+  }
+
+  while (i < text.length) {
+    const ch = text[i];
+    const rest = text.slice(i);
+
+    if (spec.line && rest.startsWith(spec.line)) {
+      push(rest, "com");
+      i = text.length;
+      break;
+    }
+    if (spec.block && rest.startsWith(spec.block[0])) {
+      const close = text.indexOf(spec.block[1], i + spec.block[0].length);
+      if (close === -1) {
+        push(rest, "com");
+        return { tokens, state: { block: true } };
+      }
+      const end = close + spec.block[1].length;
+      push(text.slice(i, end), "com");
+      i = end;
+      continue;
+    }
+    // Rust/Go char vs lifetime: only lex `'` as a string when it looks like a
+    // char literal; otherwise it is a lifetime/label and stays plain.
+    if (spec.char && ch === "'") {
+      const m = /^'(\\.|[^'\\])'/.exec(rest);
+      if (m) {
+        push(m[0], "str");
+        i += m[0].length;
+        continue;
+      }
+      plain += ch;
+      i++;
+      continue;
+    }
+    if (spec.quotes.includes(ch)) {
+      let j = i + 1;
+      while (j < text.length) {
+        if (text[j] === "\\") { j += 2; continue; }
+        if (text[j] === ch) { j++; break; }
+        j++;
+      }
+      push(text.slice(i, j), "str");
+      i = j;
+      continue;
+    }
+    if (isDigit(ch) || (ch === "." && isDigit(text[i + 1] ?? ""))) {
+      let j = i;
+      while (j < text.length && /[0-9a-fA-FxXoObB._]/.test(text[j])) j++;
+      push(text.slice(i, j), "num");
+      i = j;
+      continue;
+    }
+    if (isIdentStart(ch)) {
+      let j = i;
+      while (j < text.length && isIdent(text[j])) j++;
+      const word = text.slice(i, j);
+      let k = j;
+      while (k < text.length && (text[k] === " " || text[k] === "\t")) k++;
+      let cls = null;
+      if (spec.keywords.has(word)) cls = "kw";
+      else if (/^[A-Z]/.test(word)) cls = "type";
+      else if (text[k] === "(") cls = "fn";
+      push(word, cls);
+      i = j;
+      continue;
+    }
+    plain += ch;
+    i++;
+  }
+  flush();
+  return { tokens, state: null };
+}
+
+/** Append `tokenize` output into `cell`; classed runs become spans, plain text
+ * stays a text node so `white-space: pre` preserves it exactly. */
+export function appendTokens(doc, cell, tokens) {
+  for (const { text, cls } of tokens) {
+    if (cls === null) cell.append(doc.createTextNode(text));
+    else {
+      const span = doc.createElement("span");
+      span.className = `tok-${cls}`;
+      span.textContent = text;
+      cell.append(span);
+    }
+  }
+}

package/ui/story-panel.d.ts

@@ -0,0 +1,9 @@
+// Types for the story-panel renderer, so the DOM smoke test type-checks
+// without enabling allowJs for the whole UI. The story parameter is the
+// payload of schemas/story.schema.json (`why blame --json`).
+
+import type { BlameReport } from "../src/blame.ts";
+
+export function glyphFor(type: string, status: string | undefined): "●" | "⚠" | "?";
+export function formatTarget(target: BlameReport["target"]): string;
+export function renderStoryPanel(doc: Document, story: BlameReport): HTMLElement;