cert-coach-web 0.1.1 → 0.1.2

package/web/public/spa-api.js

@@ -0,0 +1,33 @@
+/**
+ * JSON-over-HTTP helper for the console.
+ *
+ * The page is same-origin and cookie-authenticated, so this only has to handle
+ * the three statuses the server actually uses: 401 (expired token), 409 (state
+ * moved on, so reload) and everything else.
+ */
+import { showNotice } from "./spa-ui.js";
+
+export async function api(path, body) {
+  const res = await fetch(path, {
+    method: body === undefined ? "GET" : "POST",
+    credentials: "same-origin",
+    headers: body === undefined ? {} : { "content-type": "application/json" },
+    body: body === undefined ? undefined : JSON.stringify(body),
+  });
+  let data = {};
+  try { data = await res.json(); } catch { /* non-json */ }
+  if (!res.ok) {
+    if (res.status === 401) showNotice("Session expired. Reopen the token URL printed by the server.");
+    throw new HttpError(data.error || `HTTP ${res.status}`, res.status);
+  }
+  return data;
+}
+
+/** Error carrying the HTTP status so callers can react to 409 specifically. */
+export class HttpError extends Error {
+  constructor(message, status) {
+    super(message);
+    this.name = "HttpError";
+    this.status = status;
+  }
+}

package/web/public/spa-chat.js

@@ -0,0 +1,181 @@
+/**
+ * Teaching-chat panel: message log, streaming answer, tool cards, and the
+ * lifecycle events the server emits while a pi session answers.
+ *
+ * The server may compact a long session (chat.rotated); that surfaces here as a
+ * dashed "session compacted" line so a context reset is never invisible.
+ */
+import { el } from "./spa-dom.js";
+import { store } from "./spa-store.js";
+import { showNotice } from "./spa-ui.js";
+import { renderMarkdownInto } from "./spa-mermaid.js";
+import { api } from "./spa-api.js";
+
+function chatScroll(force = false) {
+  if (!el.chatLog) return;
+  const near = el.chatLog.scrollHeight - el.chatLog.scrollTop - el.chatLog.clientHeight < 80;
+  if (force || near) el.chatLog.scrollTop = el.chatLog.scrollHeight;
+}
+
+export function appendChatMessage(role, text) {
+  const div = document.createElement("div");
+  div.className = "chat-msg " + (role === "user" ? "user" : role === "system" ? "system" : "assistant");
+  if (role === "assistant") renderMarkdownInto(div, text);
+  else div.textContent = text;
+  el.chatLog.append(div);
+  chatScroll();
+  return div;
+}
+
+function setChatStatus(kind, text) {
+  el.chatStatus.className = "chat-status" + (kind === "live" ? " live" : kind === "busy" ? " busy" : "");
+  el.chatStatus.textContent = text;
+}
+
+/** Reflect the stored chat readiness into the composer controls. */
+export function syncChatControls() {
+  const { enabled, reason, busy } = store.chat;
+  el.chatInput.disabled = !enabled;
+  el.chatSend.disabled = !enabled || busy;
+  el.chatStop.hidden = !busy;
+  el.chatSend.textContent = enabled ? "Send" : "Chat off";
+  setChatStatus(busy ? "busy" : enabled ? "live" : "off", busy ? "thinking" : enabled ? "ready" : "offline");
+  el.chatStatus.title = enabled ? "Teaching chat ready" : (reason || "Teaching chat disabled");
+}
+
+export function renderChatHistory(messages) {
+  el.chatLog.replaceChildren();
+  for (const m of messages || []) {
+    if (m.role === "user" || m.role === "assistant") appendChatMessage(m.role, m.text);
+  }
+  if (!el.chatLog.children.length) {
+    const empty = document.createElement("div");
+    empty.className = "chat-empty";
+    empty.textContent = store.chat.enabled
+      ? "Ask about the current question, a concept, or why an answer is right. The coach teaches; the quiz card grades."
+      : (store.chat.reason || "Teaching chat is disabled. Start the server with --pi <pi|path> or set PI_BIN.");
+    el.chatLog.append(empty);
+  }
+}
+
+function renderTool(event) {
+  let card = store.toolCards.get(event.id);
+  if (event.status === "start" || !card) {
+    card = document.createElement("div");
+    card.className = "chat-tool";
+    const head = document.createElement("div");
+    head.className = "tool-head";
+    const name = document.createElement("span");
+    name.textContent = event.name || "tool";
+    const state = document.createElement("span");
+    state.className = "muted";
+    head.append(name, state);
+    const body = document.createElement("pre");
+    body.className = "tool-body";
+    card.append(head, body);
+    el.chatLog.append(card);
+    store.toolCards.set(event.id, card);
+  }
+  const state = card.querySelector(".tool-head .muted");
+  const body = card.querySelector(".tool-body");
+  if (event.status === "end") {
+    state.textContent = event.isError ? "error" : "done";
+    if (event.isError) card.classList.add("error");
+    body.textContent = (event.text || "").slice(0, 3000);
+  } else {
+    state.textContent = event.status === "start" ? "running" : "…";
+    if (event.partial) body.textContent = JSON.stringify(event.partial).slice(0, 1000);
+    else if (event.args) body.textContent = JSON.stringify(event.args).slice(0, 1000);
+  }
+  chatScroll();
+}
+
+export function handleChatEvent(event) {
+  const chat = store.chat;
+  switch (event.type) {
+    case "chat.user": {
+      if (chat.pendingUser && chat.pendingUser === event.text) chat.pendingUser = "";
+      else appendChatMessage("user", event.text);
+      break;
+    }
+    case "chat.start": {
+      chat.busy = true;
+      syncChatControls();
+      chat.stream = { div: appendChatMessage("assistant", ""), text: "" };
+      break;
+    }
+    case "chat.delta": {
+      if (!chat.stream) chat.stream = { div: appendChatMessage("assistant", ""), text: "" };
+      chat.stream.text += event.text || "";
+      chat.stream.div.textContent = chat.stream.text;
+      chatScroll();
+      break;
+    }
+    case "chat.message": {
+      if (!chat.stream) chat.stream = { div: appendChatMessage("assistant", ""), text: "" };
+      renderMarkdownInto(chat.stream.div, event.text || "");
+      chat.stream = null;
+      chatScroll();
+      break;
+    }
+    case "chat.tool": {
+      renderTool(event);
+      break;
+    }
+    case "chat.done": {
+      chat.busy = false;
+      syncChatControls();
+      chat.stream = null;
+      break;
+    }
+    case "chat.error": {
+      chat.busy = false;
+      chat.stream = null;
+      syncChatControls();
+      showNotice(event.error || "Chat failed.");
+      break;
+    }
+    case "chat.rotated": {
+      // The server compacted the session before it ran out of context.
+      appendChatMessage(
+        "system",
+        event.reason === "context-overflow"
+          ? "Context limit reached - earlier turns were summarised. Keep going."
+          : "Long session - starting a fresh context with a recap of earlier turns."
+      );
+      break;
+    }
+    default:
+      break;
+  }
+}
+
+export async function sendChat() {
+  const text = el.chatInput.value.trim();
+  if (!text || !store.chat.enabled || store.chat.busy) return;
+  el.chatInput.value = "";
+  store.chat.pendingUser = text;
+  appendChatMessage("user", text);
+  store.chat.busy = true;
+  syncChatControls();
+  try {
+    const res = await api("/api/prompt", { text });
+    if (res.disposition === "handled") {
+      store.chat.busy = false;
+      syncChatControls();
+    }
+  } catch (e) {
+    store.chat.busy = false;
+    store.chat.pendingUser = "";
+    syncChatControls();
+    showNotice(e.message);
+  }
+}
+
+export async function abortChat() {
+  try {
+    await api("/api/abort", {});
+  } catch (e) {
+    showNotice(e.message);
+  }
+}

package/web/public/spa-dom.js

@@ -0,0 +1,89 @@
+/**
+ * DOM handles for the study console.
+ *
+ * One lookup table so no module has to know element ids. Modules are loaded as
+ * ES modules from a deferred <script type="module">, so the document is parsed
+ * by the time this runs.
+ */
+export const $ = (id) => document.getElementById(id);
+
+export const el = {
+  app: $("app"),
+  certLine: $("cert-line"),
+  certSelect: $("cert-select"),
+  certNew: $("cert-new"),
+  phasePill: $("phase-pill"),
+  readiness: $("readiness"),
+  connection: $("connection"),
+  notice: $("notice"),
+  loading: $("loading"),
+  idle: $("idle-card"),
+  idleNote: $("idle-note"),
+  start: $("start"),
+  startMock: $("start-mock"),
+  startProbe: $("start-probe"),
+  mockSize: $("mock-size"),
+  mockMinutes: $("mock-minutes"),
+  question: $("question-card"),
+  qmeta: $("qmeta"),
+  timer: $("timer"),
+  stem: $("stem"),
+  questionNote: $("question-note"),
+  images: $("images"),
+  options: $("options"),
+  confidenceButtons: $("confidence-buttons"),
+  submit: $("submit"),
+  feedback: $("feedback-card"),
+  verdict: $("verdict"),
+  feedbackMeta: $("feedback-meta"),
+  feedbackTitle: $("feedback-title"),
+  answerLine: $("answer-line"),
+  explanation: $("explanation"),
+  source: $("source"),
+  next: $("next"),
+  teach: $("teach-card"),
+  teachMeta: $("teach-meta"),
+  teachTitle: $("teach-title"),
+  teachSummary: $("teach-summary"),
+  teachSection: $("teach-section"),
+  teachDoc: $("teach-doc"),
+  teachNext: $("teach-next"),
+  mock: $("mock-card"),
+  mockMeta: $("mock-meta"),
+  mockTitle: $("mock-title"),
+  mockNote: $("mock-note"),
+  mockResults: $("mock-results"),
+  mockNew: $("mock-new"),
+  mockPractice: $("mock-practice"),
+  statusLog: $("status-log"),
+  chatLog: $("chat-log"),
+  chatForm: $("chat-form"),
+  chatInput: $("chat-input"),
+  chatSend: $("chat-send"),
+  chatStop: $("chat-stop"),
+  chatStatus: $("chat-status"),
+  nav: document.querySelector(".nav"),
+  sideNav: document.querySelector(".side-nav"),
+  layoutButtons: [...document.querySelectorAll("[data-app-layout]")],
+  cmdReadiness: $("cmd-readiness"),
+  cmdCoverage: $("cmd-coverage"),
+  cmdDue: $("cmd-due"),
+  cmdWeak: $("cmd-weak"),
+  cmdWeakNote: $("cmd-weak-note"),
+  cmdReadinessBar: $("cmd-readiness-bar"),
+  cmdCoverageBar: $("cmd-coverage-bar"),
+  cmdDomains: $("cmd-domains"),
+  studyView: $("study-view"),
+  pathView: $("path-view"),
+  pathMeta: $("path-meta"),
+  pathRoute: $("path-route"),
+  pathDetail: $("path-detail"),
+  dashboardView: $("dashboard-view"),
+  theoryView: $("theory-view"),
+  logsView: $("logs-view"),
+  dashboardBody: $("dashboard-body"),
+  dashboardMeta: $("dashboard-meta"),
+  theoryNodes: $("theory-nodes"),
+  theoryBody: $("theory-body"),
+  logsBody: $("logs-body"),
+};

package/web/public/spa-mermaid.js

@@ -0,0 +1,54 @@
+/**
+ * Markdown + Mermaid rendering.
+ *
+ * Mermaid is a ~1 MB vendor bundle, so it is injected on first use rather than
+ * shipped in the page. Failures degrade to plain text: the code block stays
+ * readable, it just does not become a diagram.
+ */
+import { markdownFragment } from "./spa-render.js";
+
+let mermaidSeq = 0;
+let mermaidLoading = null;
+
+export function ensureMermaid() {
+  if (window.mermaid) return Promise.resolve(window.mermaid);
+  if (!mermaidLoading) {
+    mermaidLoading = new Promise((resolve, reject) => {
+      const script = document.createElement("script");
+      script.src = "/vendor/mermaid.min.js";
+      script.async = true;
+      script.onload = () => {
+        if (!window.mermaid) return reject(new Error("Mermaid failed to initialize"));
+        window.mermaid.initialize({ startOnLoad: false, securityLevel: "strict", theme: "dark" });
+        resolve(window.mermaid);
+      };
+      script.onerror = () => reject(new Error("Mermaid failed to load"));
+      document.head.append(script);
+    });
+  }
+  return mermaidLoading;
+}
+
+export async function renderMermaidInto(container) {
+  if (!container || !container.querySelector("pre.diagram")) return;
+  try { await ensureMermaid(); } catch { return; }
+  for (const pre of container.querySelectorAll("pre.diagram")) {
+    if (pre.dataset.rendered === "1") continue;
+    const code = pre.textContent || "";
+    if (!code.trim()) continue;
+    try {
+      const { svg } = await window.mermaid.render("mmd" + (++mermaidSeq), code);
+      pre.innerHTML = svg;
+      pre.dataset.rendered = "1";
+      pre.classList.add("rendered");
+    } catch {
+      pre.classList.add("mermaid-error");
+    }
+  }
+}
+
+/** Render markdown into a node, then upgrade any mermaid blocks. */
+export function renderMarkdownInto(node, text) {
+  node.replaceChildren(markdownFragment(document, text));
+  void renderMermaidInto(node);
+}

package/web/public/spa-question.js

@@ -0,0 +1,206 @@
+/**
+ * Study cards: question, feedback, teach, mock summary, idle.
+ *
+ * Owns everything about *showing* a state snapshot, including the answer timer
+ * and selection UI. It never calls the server; the wiring layer does that.
+ */
+import { el } from "./spa-dom.js";
+import { store, toggleSelection, timerLabel, stemClass, mockSummary, phaseCard, isMultiSelect } from "./spa-store.js";
+import { only, setPhase } from "./spa-ui.js";
+import { renderMarkdownInto } from "./spa-mermaid.js";
+import { safeHttpUrl, imageSrc } from "./spa-logic.js";
+import { updateCommandStrip } from "./spa-views.js";
+
+function renderImages(images) {
+  el.images.replaceChildren();
+  for (const im of images || []) {
+    const src = imageSrc(im);
+    if (!src) continue;
+    const fig = document.createElement("figure");
+    fig.className = "exhibit";
+    const img = document.createElement("img");
+    img.src = src;
+    img.alt = im.label || "exhibit";
+    img.loading = "lazy";
+    img.addEventListener("click", () => window.open(img.src, "_blank", "noopener"));
+    const cap = document.createElement("figcaption");
+    cap.textContent = im.label || "exhibit";
+    fig.append(img, cap);
+    el.images.append(fig);
+  }
+  el.images.hidden = !el.images.children.length;
+}
+
+function renderOptions(q, readOnly) {
+  el.options.replaceChildren();
+  for (const opt of q.options || []) {
+    const b = document.createElement("button");
+    b.type = "button";
+    b.className = "option";
+    b.dataset.value = opt.value;
+    b.disabled = readOnly;
+    b.setAttribute("aria-pressed", store.selected.has(opt.value) ? "true" : "false");
+    if (store.selected.has(opt.value)) b.classList.add("selected");
+    const key = document.createElement("span");
+    key.className = "key";
+    key.textContent = opt.value;
+    const text = document.createElement("span");
+    text.textContent = opt.text || "(image option)";
+    b.append(key, text);
+    b.addEventListener("click", () => toggleOption(opt.value));
+    el.options.append(b);
+  }
+}
+
+export function toggleOption(value) {
+  if (!store.state || store.state.phase !== "question" || !store.state.q) return;
+  store.selected = toggleSelection(store.selected, value, isMultiSelect(store.state));
+  updateSelectionUI();
+}
+
+export function updateSelectionUI() {
+  const multi = isMultiSelect(store.state);
+  for (const b of el.options.querySelectorAll(".option")) {
+    const on = store.selected.has(b.dataset.value);
+    b.classList.toggle("selected", on);
+    b.setAttribute("aria-pressed", on ? "true" : "false");
+  }
+  for (const b of el.confidenceButtons.querySelectorAll("button")) {
+    b.classList.toggle("active", Number(b.dataset.confidence) === store.confidence);
+  }
+  el.submit.disabled = !(store.state?.phase === "question" && store.selected.size > 0);
+  el.submit.textContent = multi ? "Submit selection" : "Submit answer";
+}
+
+function startTimer(key) {
+  if (store.timerHandle) clearInterval(store.timerHandle);
+  store.timerHandle = null;
+  if (key !== store.questionKey) {
+    store.questionKey = key;
+    store.startedAt = Date.now();
+    store.confidence = 2;
+    store.selected = new Set();
+  }
+  const tick = () => {
+    if (!store.state || store.state.phase !== "question") return;
+    el.timer.textContent = timerLabel({
+      deadline: Number(store.state.meta?.mock?.deadline) || 0,
+      startedAt: store.startedAt,
+    });
+  };
+  tick();
+  store.timerHandle = setInterval(tick, 1000);
+}
+
+function stopTimer() {
+  if (store.timerHandle) clearInterval(store.timerHandle);
+  store.timerHandle = null;
+  if (store.state) el.timer.textContent = "";
+}
+
+function setStemSize(node, text) {
+  node.classList.remove("stem-long", "stem-xlong");
+  const cls = stemClass(text);
+  if (cls) node.classList.add(cls);
+}
+
+function renderQuestion(s, readOnly) {
+  only(el.question);
+  const q = s.q || {};
+  setPhase(s.phase);
+  const mockMeta = s.meta?.mock ? `mock ${(s.meta.mock.answered || 0) + 1}/${s.meta.mock.total || "?"}` : "";
+  const probeMeta = s.meta?.probe ? `probe ${s.meta.probe.answered || 1}/${s.meta.probe.total || 20}` : "";
+  el.qmeta.textContent = [q.domain, q.node, q.index ? `#${q.index}` : "", mockMeta || probeMeta].filter(Boolean).join(" · ");
+  el.stem.textContent = q.stem || "";
+  setStemSize(el.stem, q.stem || "");
+  el.questionNote.hidden = !readOnly;
+  el.questionNote.textContent = readOnly ? "Submitted; grading..." : "";
+  renderImages(q.images);
+  renderOptions(q, readOnly);
+  updateSelectionUI();
+  if (!readOnly) startTimer(`${q.id}:${s.rev}`);
+  else stopTimer();
+}
+
+function renderFeedback(s) {
+  only(el.feedback);
+  setPhase(s.phase);
+  stopTimer();
+  const f = s.feedback || {};
+  el.verdict.textContent = f.correct ? "Correct" : "Incorrect";
+  el.verdict.className = "verdict " + (f.correct ? "good" : "bad");
+  el.feedbackMeta.textContent = [f.box != null ? `box ${f.box}` : "", f.due ? `due ${String(f.due).slice(0, 10)}` : "", s.meta?.readiness || ""].filter(Boolean).join(" · ");
+  el.feedbackTitle.textContent = s.q?.stem || "Feedback";
+  setStemSize(el.feedbackTitle, s.q?.stem || "Feedback");
+  el.answerLine.textContent = `Answer: ${(f.answer || []).join(", ") || "?"} · you: ${(f.selected || []).join(", ") || "?"}`;
+  el.explanation.textContent = f.explanation || "";
+  const src = safeHttpUrl(f.source || "");
+  el.source.hidden = !src;
+  el.source.href = src || "#";
+  el.source.textContent = src || "";
+}
+
+function renderTeach(s) {
+  only(el.teach);
+  setPhase(s.phase);
+  stopTimer();
+  const t = s.teach || {};
+  el.teachMeta.textContent = [t.domain, t.reason].filter(Boolean).join(" · ");
+  el.teachTitle.textContent = t.title || t.node || "Teach";
+  el.teachSummary.textContent = t.summary || "";
+  el.teachTitle.classList.remove("stem-long", "stem-xlong");
+  el.teachSection.replaceChildren();
+  renderMarkdownInto(el.teachSection, t.section || "");
+  const doc = safeHttpUrl(t.docUrl || "");
+  el.teachDoc.hidden = !doc;
+  el.teachDoc.href = doc || "#";
+  el.teachDoc.textContent = doc || "";
+}
+
+function renderMock(s) {
+  only(el.mock);
+  setPhase("mock_summary");
+  stopTimer();
+  const m = s.mock || {};
+  const text = mockSummary(m);
+  el.mockMeta.textContent = text.meta;
+  el.mockTitle.textContent = text.title;
+  el.mockNote.textContent = text.note;
+  el.mockResults.replaceChildren();
+  for (const a of m.answers || []) {
+    const row = document.createElement("div");
+    row.className = "mock-row";
+    const mark = document.createElement("span");
+    mark.className = a.correct ? "ok" : "bad";
+    mark.textContent = a.correct ? "OK" : "MISS";
+    const q = document.createElement("span");
+    q.className = "q";
+    q.textContent = `${a.qid} · ${a.domain || ""}/${a.node || ""} · you ${(a.selected || []).join(",")} · answer ${(a.answer || []).join(",")}`;
+    const secs = document.createElement("span");
+    secs.className = "muted";
+    secs.textContent = a.seconds != null ? `${a.seconds}s` : "";
+    row.append(mark, q, secs);
+    el.mockResults.append(row);
+  }
+}
+
+function renderIdle(s) {
+  only(el.idle);
+  setPhase("idle");
+  stopTimer();
+  el.idleNote.textContent = s.meta?.note || "Start a practice run when you are ready.";
+}
+
+/** Render a state snapshot into the study column. */
+export function renderState(s) {
+  store.state = s;
+  el.certLine.textContent = `${s.cert || "cert"} · ${s.mode || "practice"}`;
+  el.readiness.textContent = s.meta?.readiness ? `readiness ${s.meta.readiness}` : "";
+  const card = phaseCard(s.phase);
+  if (card === "question") renderQuestion(s, s.phase === "submitted");
+  else if (card === "feedback") renderFeedback(s);
+  else if (card === "teach") renderTeach(s);
+  else if (card === "mock") renderMock(s);
+  else renderIdle(s);
+  if (store.activeLayout === "command") void updateCommandStrip();
+}

package/web/public/spa-store.js

@@ -0,0 +1,100 @@
+/**
+ * Console session store: the mutable bits that used to be module-level `let`s.
+ *
+ * Everything lives on one exported object so other modules can mutate fields
+ * (`store.state = s`). A module cannot reassign an imported binding, so plain
+ * named exports would not work here.
+ *
+ * The small pure helpers at the bottom are unit-tested in tests/spa-store.test.mjs
+ * because they carry the fiddly rules (multi-select toggling, timer labels,
+ * which card a phase maps to).
+ */
+
+export const store = {
+  /** Latest state snapshot from the server. Null until bootstrap. */
+  state: null,
+  /** Currently selected option values. */
+  selected: new Set(),
+  /** 1 = guess, 2 = unsure, 3 = confident. */
+  confidence: 2,
+  /** Epoch ms the current question was first shown. */
+  startedAt: 0,
+  /** `${qid}:${rev}` of the question the timer belongs to. */
+  questionKey: "",
+  timerHandle: null,
+
+  eventSource: null,
+  theoryNodes: null,
+  activeTheoryNode: "",
+  activeView: "study",
+  activeLayout: "triptych",
+
+  chat: {
+    enabled: false,
+    reason: "",
+    busy: false,
+    /** { div, text } while an assistant answer streams. */
+    stream: null,
+    /** Echo suppression: the message we already rendered optimistically. */
+    pendingUser: "",
+  },
+  toolCards: new Map(),
+};
+
+/** New selection set for a single- or multi-select question. */
+export function toggleSelection(selected, value, multi) {
+  const next = new Set(selected || []);
+  if (!multi) return new Set([value]);
+  if (next.has(value)) next.delete(value);
+  else next.add(value);
+  return next;
+}
+
+/** `m:ss` for a non-negative number of seconds. */
+export function formatTimer(totalSeconds) {
+  const s = Math.max(0, Math.floor(Number(totalSeconds) || 0));
+  return `${Math.floor(s / 60)}:${String(s % 60).padStart(2, "0")}`;
+}
+
+/**
+ * Timer text for a question. A timed mock counts down to its deadline;
+ * otherwise the timer counts up from when the question appeared.
+ */
+export function timerLabel({ deadline = 0, startedAt = 0 }, now = Date.now()) {
+  if (deadline) return `${formatTimer((deadline - now) / 1000)} left`;
+  return formatTimer((now - startedAt) / 1000);
+}
+
+/** Stem length drives a CSS class so long question text gets a smaller font. */
+export function stemClass(text) {
+  const len = String(text || "").length;
+  if (len > 420) return "stem-xlong";
+  if (len > 220) return "stem-long";
+  return "";
+}
+
+/** Human-readable mock summary, built from the loop's mock payload. */
+export function mockSummary(m = {}) {
+  const completed = m.completed ?? m.total ?? 0;
+  const requested = m.requested ?? m.total ?? 0;
+  const score = m.correct || 0;
+  return {
+    meta: `${score}/${completed} correct · ${completed}/${requested} completed`,
+    title: m.score != null ? `Mock score: ${Math.round(m.score * 100)}%` : "Mock complete",
+    note: `${m.timedOut ? "Time expired. " : ""}Requested ${m.requested ?? "?"} questions; completed ${completed}. Feedback is shown now that the run is over. progress.json was not modified.`,
+  };
+}
+
+/** Which card a server phase maps to (`loading` means nothing to show yet). */
+export function phaseCard(phase) {
+  if (phase === "question" || phase === "submitted") return "question";
+  if (phase === "feedback") return "feedback";
+  if (phase === "teach") return "teach";
+  if (phase === "mock_summary") return "mock";
+  return "idle";
+}
+
+/** True when the server says the current question takes multiple answers. */
+export function isMultiSelect(state) {
+  return state?.q?.multi === true;
+}