codetrail-cli 1.4.1__py3-none-any.whl

codetrail/web/static/css/print.css

@@ -0,0 +1,42 @@
+/* Printing a page: the content alone, in black on white. */
+
+.topbar,
+.sidebar,
+.sidebar-edge,
+.resize-handle,
+.outline,
+.ask-panel,
+.update-panel,
+.skip-link,
+.pager,
+.checks,
+.page-status button,
+.diagram-tools {
+  display: none !important;
+}
+
+.shell {
+  display: block;
+}
+
+.content {
+  padding: 0;
+}
+
+/* The page's card is the screen's frame: on paper there is only the page. */
+.page-area {
+  margin: 0;
+  padding: 0;
+  border-radius: 0;
+  box-shadow: none;
+}
+
+body {
+  background: #ffffff;
+  color: #000000;
+}
+
+a {
+  color: inherit;
+  text-decoration: underline;
+}

codetrail/web/static/css/tokens.css

@@ -0,0 +1,228 @@
+/* Codetrail's design tokens (design section 16.2): every color, size and space the page uses.
+   Light by default; dark follows the system unless the reader chose a theme ([data-theme] on <html>). */
+
+@font-face {
+  font-family: "Inter";
+  font-style: normal;
+  font-weight: 100 900;
+  font-display: swap;
+  src: url("/static/vendor/inter/InterVariable.woff2") format("woff2");
+}
+
+@font-face {
+  font-family: "Inter";
+  font-style: italic;
+  font-weight: 100 900;
+  font-display: swap;
+  src: url("/static/vendor/inter/InterVariable-Italic.woff2") format("woff2");
+}
+
+/* Arabic letters, which Inter doesn't have (ADR 0014); loaded only by a page that shows some. */
+@font-face {
+  font-family: "Noto Sans Arabic";
+  font-style: normal;
+  font-weight: 400 700;
+  font-display: swap;
+  src: url("/static/vendor/noto-sans-arabic/NotoSansArabic-wght.woff2") format("woff2");
+  unicode-range: U+0600-06FF, U+0750-077F, U+0870-08FF, U+200C-200F, U+2010-2011, U+204F, U+2E41, U+FB50-FDFF,
+    U+FE70-FEFF, U+10E60-10E7F;
+}
+
+:root {
+  color-scheme: light;
+  --font-sans: "Inter", "Noto Sans Arabic", ui-sans-serif, system-ui, -apple-system, "Segoe UI", sans-serif;
+  --font-mono: ui-monospace, "SF Mono", Menlo, Consolas, monospace;
+
+  --accent: #5b5bd6;
+  --accent-hover: #4b4bc4;
+  --accent-text: #4a48c0;
+  --accent-tint: #efeffd;
+  --on-accent: #ffffff;
+
+  --text: #1a1f36;
+  --text-muted: #5c6378;
+  --text-faint: #646b7f;
+
+  --page: #ffffff;
+  --sidebar: #f7f8fb;
+  --card: #f5f6fa;
+  --raised: #ffffff;
+  --hover: #eef0f6;
+
+  --line: #e3e6ee;
+  --line-strong: #cfd4e0;
+
+  --documented: #5b5bd6;
+  --documented-tint: #f3f3fe;
+  --inferred: #b26a00;
+  --inferred-tint: #fdf6ea;
+  --inferred-text: #8a5200;
+  --learned: #18774d;
+  --learned-tint: #e8f6ef;
+  --danger: #c0392b;
+  --mark: #fff1b8;
+
+  /* Charts (design section 20.3): four categorical colors checked for color-blind separation, gray for Other, and
+     one indigo ramp with the ink that reads on each step. Amber stays the inferred color only. */
+  --series-1: #5b5bd6;
+  --series-2: #e87ba4;
+  --series-3: #2a78d6;
+  --series-4: #008300;
+  --series-other: #8b92a8;
+  --heat-0: #ebecfa;
+  --heat-1: #d0d2f6;
+  --heat-2: #aeb0ee;
+  --heat-3: #7f81e1;
+  --heat-4: #4b4bc4;
+  --heat-ink-0: #1a1f36;
+  --heat-ink-1: #1a1f36;
+  --heat-ink-2: #1a1f36;
+  --heat-ink-3: #1a1f36;
+  --heat-ink-4: #ffffff;
+  --chart-band: rgb(91 91 214 / 0.07);
+
+  /* The home page's metric cards (design section 16.2): the system blue and the repository pink, from the chart
+     series, each with a darker shade for its text. Indigo is documentation's, green learned's, amber inferred's. */
+  --system: var(--series-3);
+  --system-text: #1f62b5;
+  --repository: var(--series-2);
+  --repository-text: #b23a6a;
+
+  --shadow-float: 0 12px 32px rgb(16 24 64 / 0.14), 0 2px 6px rgb(16 24 64 / 0.08);
+  --shadow-card: 0 1px 2px rgb(16 24 64 / 0.06), 0 0 0 1px var(--line); /* the page's card in the frame */
+  --shadow-pill: 0 1px 2px rgb(16 24 64 / 0.1), 0 0 0 1px var(--line); /* the sidebar's current row and tile */
+  --focus: 0 0 0 3px rgb(91 91 214 / 0.35);
+
+  --space-1: 4px;
+  --space-2: 8px;
+  --space-3: 12px;
+  --space-4: 16px;
+  --space-5: 20px;
+  --space-6: 24px;
+  --space-8: 32px;
+  --space-10: 40px;
+  --space-12: 48px;
+
+  --radius: 8px;
+  --radius-card: 12px;
+
+  --header-height: 60px;
+  --sidebar-width: 272px;
+  --outline-width: 224px;
+  --panel-width: 420px;
+  --article-width: 46rem;
+  --wide-width: 72rem;
+
+  --ease: cubic-bezier(0.2, 0.8, 0.2, 1);
+  --duration: 180ms;
+}
+
+@media (prefers-color-scheme: dark) {
+  :root:not([data-theme="light"]) {
+    color-scheme: dark;
+    --accent: #9b9bf5;
+    --accent-hover: #b1b1f8;
+    --accent-text: #b4b4f9;
+    --accent-tint: #23264a;
+    --on-accent: #0f1220;
+    --text: #e6e8f0;
+    --text-muted: #a1a8bd;
+    --text-faint: #8b92a8;
+    --page: #0f1220;
+    --sidebar: #141829;
+    --card: #191e31;
+    --raised: #1b2035;
+    --hover: #22283f;
+    --line: #262c44;
+    --line-strong: #353c58;
+    --documented: #9b9bf5;
+    --documented-tint: #1c1f3c;
+    --inferred: #f0b255;
+    --inferred-tint: #2a2213;
+    --inferred-text: #f0b255;
+    --learned: #5fd39b;
+    --learned-tint: #12291f;
+    --danger: #ff8a7a;
+    --mark: #4a3f12;
+    --shadow-float: 0 16px 40px rgb(0 0 0 / 0.5), 0 2px 8px rgb(0 0 0 / 0.4);
+    --shadow-card: 0 1px 2px rgb(0 0 0 / 0.4), 0 0 0 1px var(--line);
+    --shadow-pill: 0 1px 2px rgb(0 0 0 / 0.5), 0 0 0 1px var(--line);
+    --focus: 0 0 0 3px rgb(155 155 245 / 0.45);
+
+    --series-1: #7c7cee;
+    --series-2: #d55181;
+    --series-3: #3987e5;
+    --series-4: #2b8a2b;
+    --series-other: #646b7f;
+    --heat-0: #222842;
+    --heat-1: #2f3567;
+    --heat-2: #43479a;
+    --heat-3: #7b7de0;
+    --heat-4: #9b9bf5;
+    --heat-ink-0: #e6e8f0;
+    --heat-ink-1: #e6e8f0;
+    --heat-ink-2: #e6e8f0;
+    --heat-ink-3: #0f1220;
+    --heat-ink-4: #0f1220;
+    --chart-band: rgb(155 155 245 / 0.08);
+    --system-text: #79b0f2;
+    --repository-text: #f08cb3;
+  }
+}
+
+:root[data-theme="dark"] {
+  color-scheme: dark;
+  --accent: #9b9bf5;
+  --accent-hover: #b1b1f8;
+  --accent-text: #b4b4f9;
+  --accent-tint: #23264a;
+  --on-accent: #0f1220;
+  --text: #e6e8f0;
+  --text-muted: #a1a8bd;
+  --text-faint: #8b92a8;
+  --page: #0f1220;
+  --sidebar: #141829;
+  --card: #191e31;
+  --raised: #1b2035;
+  --hover: #22283f;
+  --line: #262c44;
+  --line-strong: #353c58;
+  --documented: #9b9bf5;
+  --documented-tint: #1c1f3c;
+  --inferred: #f0b255;
+  --inferred-tint: #2a2213;
+  --inferred-text: #f0b255;
+  --learned: #5fd39b;
+  --learned-tint: #12291f;
+  --danger: #ff8a7a;
+  --mark: #4a3f12;
+  --shadow-float: 0 16px 40px rgb(0 0 0 / 0.5), 0 2px 8px rgb(0 0 0 / 0.4);
+  --shadow-card: 0 1px 2px rgb(0 0 0 / 0.4), 0 0 0 1px var(--line);
+  --shadow-pill: 0 1px 2px rgb(0 0 0 / 0.5), 0 0 0 1px var(--line);
+  --focus: 0 0 0 3px rgb(155 155 245 / 0.45);
+
+  --series-1: #7c7cee;
+  --series-2: #d55181;
+  --series-3: #3987e5;
+  --series-4: #2b8a2b;
+  --series-other: #646b7f;
+  --heat-0: #222842;
+  --heat-1: #2f3567;
+  --heat-2: #43479a;
+  --heat-3: #7b7de0;
+  --heat-4: #9b9bf5;
+  --heat-ink-0: #e6e8f0;
+  --heat-ink-1: #e6e8f0;
+  --heat-ink-2: #e6e8f0;
+  --heat-ink-3: #0f1220;
+  --heat-ink-4: #0f1220;
+  --chart-band: rgb(155 155 245 / 0.08);
+  --system-text: #79b0f2;
+  --repository-text: #f08cb3;
+}
+
+@media (prefers-reduced-motion: reduce) {
+  :root {
+    --duration: 0ms;
+  }
+}

codetrail/web/static/js/api.js

@@ -0,0 +1,49 @@
+// Talking to Codetrail's server: every write and every JSON read carries the session's token (design 7.4 and 16.3).
+
+const token = document.querySelector('meta[name="codetrail-token"]')?.content ?? "";
+
+export async function post(url, data) {
+  return fetch(url, {
+    method: "POST",
+    headers: { "X-Codetrail-Token": token, "Content-Type": "application/json" },
+    body: JSON.stringify(data),
+    credentials: "same-origin",
+  });
+}
+
+export async function getJSON(url, options = {}) {
+  const response = await fetch(url, {
+    headers: { "X-Codetrail-Token": token, Accept: "application/json" },
+    credentials: "same-origin",
+    cache: "no-store",
+    signal: options.signal,
+  });
+  if (!response.ok) throw new Error(`${response.status}`);
+  return response.json();
+}
+
+// What a call actually used, beside its estimate on the button (design section 15.4).
+export function usedText(labels, usage) {
+  if (!usage) return "";
+  const tokens = usage.tokens >= 1000 ? `${Math.round(usage.tokens / 1000)}k` : `${usage.tokens}`;
+  const cost = usage.cost_usd ? ` · $${usage.cost_usd.toFixed(2)}` : "";
+  return `${labels.dataset.labelUsed} ${tokens} ${labels.dataset.labelTokens}${cost}`;
+}
+
+// Session and local storage can be missing or refuse (private windows, blocked site data); the page works without.
+export function remember(storage, key, value) {
+  try {
+    if (value === null) window[storage].removeItem(key);
+    else window[storage].setItem(key, value);
+  } catch {
+    // nothing to do: the choice just isn't remembered
+  }
+}
+
+export function recall(storage, key) {
+  try {
+    return window[storage].getItem(key);
+  } catch {
+    return null;
+  }
+}

codetrail/web/static/js/ask.js

@@ -0,0 +1,182 @@
+// The Ask panel (design section 16.4): this session's answers, a question about the page being read, and saving
+// answers to the guide. A question is sent only by the Send button, which shows its estimate; nothing else spends.
+import { getJSON, post, recall, remember, usedText } from "./api.js";
+import { drawDiagramsIn } from "./diagram.js";
+import { hideUpdatePanel } from "./update.js";
+
+const panel = document.querySelector("[data-ask]");
+const thread = panel?.querySelector("[data-ask-thread]");
+const intro = panel?.querySelector("[data-ask-intro]");
+const form = panel?.querySelector("[data-ask-form]");
+const status = panel?.querySelector("[data-ask-status]");
+let loaded = false;
+let opener = null;
+
+function item(question, answerLanguage) {
+  const article = document.createElement("article");
+  article.className = "ask-item";
+  const asked = document.createElement("p");
+  asked.className = "ask-question";
+  asked.textContent = question;
+  const answer = document.createElement("div");
+  answer.className = "ask-answer";
+  answer.lang = answerLanguage;
+  answer.dir = "auto";
+  const actions = document.createElement("div");
+  actions.className = "ask-actions";
+  article.append(asked, answer, actions);
+  intro.hidden = true;
+  thread.append(article);
+  return { article, answer, actions };
+}
+
+function addSaveButton(actions, answerId, question) {
+  const button = document.createElement("button");
+  button.type = "button";
+  button.className = "button small";
+  button.dataset.saveAnswer = "";
+  button.textContent = panel.dataset.labelSave;
+  button.addEventListener("click", async () => {
+    button.disabled = true;
+    const response = await post(`/bridge/answers/${encodeURIComponent(answerId)}/save`, {});
+    const result = await response.json().catch(() => ({}));
+    if (!response.ok) {
+      button.disabled = false;
+      const problem = document.createElement("span");
+      problem.textContent = result.error ?? panel.dataset.labelSaveFailed;
+      actions.append(problem);
+      return;
+    }
+    const link = document.createElement("a");
+    link.href = `/pages/${result.page_id}`;
+    link.textContent = panel.dataset.labelSaved;
+    button.replaceWith(link);
+    addToSidebar(result.page_id, question);
+  });
+  actions.prepend(button);
+}
+
+function addToSidebar(pageId, question) {
+  const list = document.querySelector("[data-nav-answers]");
+  if (!list) return;
+  list.querySelector("[data-nav-empty]")?.remove();
+  const entry = document.createElement("li");
+  const link = document.createElement("a");
+  link.className = "nav-link";
+  link.href = `/pages/${pageId}`;
+  const label = document.createElement("span");
+  label.className = "label";
+  label.textContent = question;
+  link.append(label);
+  entry.append(link);
+  list.prepend(entry);
+}
+
+async function loadSessionAnswers() {
+  if (loaded) return;
+  loaded = true;
+  try {
+    const { answers } = await getJSON("/bridge/answers");
+    for (const answer of answers) {
+      const { answer: body, actions } = item(answer.question, panel.dataset.language);
+      body.innerHTML = answer.html; // rendered and sanitized on the server, raw HTML disabled
+      drawDiagramsIn(body);
+      addSaveButton(actions, answer.id, answer.question);
+    }
+    thread.scrollTop = thread.scrollHeight;
+  } catch {
+    loaded = false; // try again next time the panel opens
+  }
+}
+
+export function isAskOpen() {
+  return Boolean(panel && !panel.hidden);
+}
+
+export function openAsk(question, focus = true) {
+  if (!panel) return;
+  if (focus) opener ??= document.activeElement;
+  hideUpdatePanel(); // Ask takes the side; the Update button shows a running update again
+  panel.hidden = false;
+  document.body.classList.add("ask-open");
+  remember("sessionStorage", "codetrail.ask", "open");
+  loadSessionAnswers();
+  const field = form.elements.question;
+  if (typeof question === "string" && question) field.value = question;
+  if (focus) field.focus();
+}
+
+export function closeAsk() {
+  if (!panel || panel.hidden) return;
+  panel.hidden = true;
+  document.body.classList.remove("ask-open");
+  remember("sessionStorage", "codetrail.ask", null);
+  if (opener instanceof HTMLElement) opener.focus();
+  opener = null;
+}
+
+async function send(event) {
+  event.preventDefault();
+  const question = form.elements.question.value.trim();
+  if (!question) return;
+  const button = form.querySelector("button[type=submit]");
+  button.disabled = true;
+  status.textContent = status.dataset.labelReading;
+  const { answer, actions } = item(question, panel.dataset.language);
+  thread.scrollTop = thread.scrollHeight;
+  const body = { question };
+  if (panel.dataset.pageId) body.page_id = panel.dataset.pageId;
+  try {
+    const response = await post("/bridge/questions", body);
+    if (!response.ok) {
+      const problem = await response.json().catch(() => ({}));
+      answer.textContent = problem.error ?? `The question was refused (${response.status}).`;
+      status.textContent = "";
+      return;
+    }
+    form.elements.question.value = "";
+    const reader = response.body.getReader();
+    const decoder = new TextDecoder();
+    let buffer = "";
+    for (;;) {
+      const { value, done } = await reader.read();
+      if (done) break;
+      buffer += decoder.decode(value, { stream: true });
+      let newline;
+      while ((newline = buffer.indexOf("\n")) >= 0) {
+        const line = buffer.slice(0, newline);
+        buffer = buffer.slice(newline + 1);
+        if (!line.trim()) continue;
+        const message = JSON.parse(line);
+        if (message.type === "text") {
+          answer.textContent += message.text; // plain text while it streams
+          status.textContent = "";
+        } else if (message.type === "done") {
+          answer.innerHTML = message.html; // rendered on the server with raw HTML disabled
+          drawDiagramsIn(answer); // diagrams drawn from facts, as on the guide's pages
+          addSaveButton(actions, message.answer_id, question);
+          const used = document.createElement("span");
+          used.textContent = usedText(status, message.usage);
+          actions.append(used);
+          status.textContent = "";
+        } else if (message.type === "error") {
+          answer.textContent = message.message; // nothing of a failed or withheld answer stays on the page
+          status.textContent = "";
+        }
+        thread.scrollTop = thread.scrollHeight;
+      }
+    }
+  } finally {
+    button.disabled = false;
+  }
+}
+
+export function setUpAsk() {
+  if (!panel) return;
+  form.addEventListener("submit", send);
+  for (const button of document.querySelectorAll("[data-ask-open]")) {
+    button.addEventListener("click", () => openAsk());
+  }
+  panel.querySelector("[data-ask-close]")?.addEventListener("click", closeAsk);
+  if (recall("sessionStorage", "codetrail.ask") === "open") openAsk(undefined, false); // reopened, not focused
+}

codetrail/web/static/js/d2-worker.js

@@ -0,0 +1,34 @@
+// D2's WebAssembly build, in a worker of its own (ADR 0016). Its ELK layout evaluates JavaScript from strings, so
+// this file is served with its own policy: eval is allowed here, but there is no DOM and no network but d2.wasm.
+// It gets D2 text Codetrail wrote from facts and answers with an SVG, which the page shows only as an image.
+// Diagrams are laid out by ELK (ADR 0018): D2 calls the elkLayoutSync that elk.js defines, which needs an ELK
+// instance to exist first. D2.js also runs a setup.js, which isn't loaded here: it would replace setTimeout.
+importScripts("/static/vendor/d2/wasm_exec.js", "/static/vendor/d2/elk.js");
+new ELK();
+
+const ready = (async () => {
+  const go = new Go();
+  const { instance } = await WebAssembly.instantiateStreaming(fetch("/static/vendor/d2/d2.wasm"), go.importObject);
+  go.run(instance); // D2's main keeps running and sets self.d2
+  return self.d2;
+})();
+
+function data(response) {
+  const parsed = JSON.parse(response);
+  if (parsed.error) throw new Error(parsed.error.message);
+  return parsed.data;
+}
+
+self.onmessage = async ({ data: { id, source, dark } }) => {
+  try {
+    const d2 = await ready;
+    const compiled = data(await d2.compile(JSON.stringify({ fs: { index: source }, options: { layout: "elk" } })));
+    // At its natural size (scale 1): the page's CSS shrinks a wide diagram to fit, and a small one isn't blown up.
+    const options = { ...compiled.renderOptions, themeID: dark ? 200 : 0, pad: 16, scale: 1, noXMLTag: true };
+    const encoded = data(await d2.render(JSON.stringify({ diagram: compiled.diagram, options })));
+    const svg = new TextDecoder().decode(Uint8Array.from(atob(encoded), (character) => character.charCodeAt(0)));
+    self.postMessage({ id, svg });
+  } catch (error) {
+    self.postMessage({ id, error: String(error?.message ?? error) });
+  }
+};

codetrail/web/static/js/d2.js

@@ -0,0 +1,28 @@
+// Draws D2 text as an SVG in d2-worker.js, whose own policy allows the eval D2's layout needs; the page's never does
+// (ADR 0016). One worker serves every diagram on the page.
+let worker;
+let next = 0;
+const waiting = new Map();
+
+function start() {
+  worker = new Worker("/static/js/d2-worker.js");
+  worker.onmessage = ({ data }) => {
+    const request = waiting.get(data.id);
+    waiting.delete(data.id);
+    if (data.error === undefined) request?.resolve(data.svg);
+    else request?.reject(new Error(data.error));
+  };
+  worker.onerror = () => {
+    for (const request of waiting.values()) request.reject(new Error("D2's worker failed"));
+    waiting.clear();
+  };
+}
+
+export function renderD2(source, dark) {
+  if (!worker) start();
+  return new Promise((resolve, reject) => {
+    const id = next++;
+    waiting.set(id, { resolve, reject });
+    worker.postMessage({ id, source, dark });
+  });
+}

codetrail/web/static/js/diagram.js

@@ -0,0 +1,52 @@
+// Diagrams drawn from facts, written in D2 and drawn by D2's WebAssembly build in its own worker (ADR 0016), in the
+// page's light or dark theme. Pages draw theirs on load; the Ask panel draws an answer's when it arrives.
+import { renderD2 } from "./d2.js";
+import { isDark } from "./theme.js";
+
+const figures = [];
+
+// D2's SVG is shown as an image, where it can't run script or follow links, whatever the worker sent.
+async function draw(figure) {
+  const source = figure.dataset.source;
+  const target = figure.querySelector("[data-diagram-target]");
+  if (!source || !target) return;
+  try {
+    const image = document.createElement("img");
+    image.src = `data:image/svg+xml;charset=utf-8,${encodeURIComponent(await renderD2(source, isDark()))}`;
+    image.alt = figure.dataset.alt ?? "";
+    target.replaceChildren(image);
+    target.hidden = false;
+    figure.querySelector("pre.diagram")?.setAttribute("hidden", "");
+  } catch {
+    figure.classList.add("diagram-failed");
+  }
+}
+
+function prepare(figure) {
+  const block = figure.querySelector("pre.diagram");
+  if (!block || figure.dataset.source !== undefined) return false;
+  figure.dataset.source = block.textContent;
+  const target = document.createElement("div");
+  target.className = "diagram-svg";
+  target.dataset.diagramTarget = "";
+  target.hidden = true;
+  block.after(target);
+  figure.querySelector("[data-diagram-enlarge]")?.addEventListener("click", (event) => {
+    const enlarged = figure.classList.toggle("enlarged");
+    event.currentTarget.setAttribute("aria-pressed", String(enlarged));
+  });
+  figures.push(figure);
+  return true;
+}
+
+export async function drawDiagramsIn(root) {
+  const found = [...root.querySelectorAll("figure.diagram-block")].filter(prepare);
+  for (const figure of found) await draw(figure);
+}
+
+export function setUpDiagrams() {
+  drawDiagramsIn(document);
+  document.addEventListener("codetrail:theme", async () => {
+    for (const figure of figures.filter((each) => each.isConnected)) await draw(figure);
+  });
+}

codetrail/web/static/js/documentation.js

@@ -0,0 +1,24 @@
+// The Documentation page's filter chips (design section 21.2): each shows one kind of item, in its list and in the
+// list's folded rest. The server writes every count and label; this sets only hidden, aria-pressed and the live
+// region's words, copied from the chip. Without it, every item shows.
+export function setUpDocumentation() {
+  for (const area of document.querySelectorAll("[data-filterable]")) {
+    const group = area.querySelector("[data-filter]");
+    if (!group) continue;
+    const status = area.querySelector("[data-filter-status]");
+    const buttons = [...group.querySelectorAll("[data-show]")];
+    group.hidden = false;
+    for (const button of buttons) {
+      button.addEventListener("click", () => {
+        const kind = button.dataset.show;
+        for (const other of buttons) other.setAttribute("aria-pressed", String(other === button));
+        for (const item of area.querySelectorAll("li[data-kind]")) item.hidden = kind !== "all" && item.dataset.kind !== kind;
+        for (const more of area.querySelectorAll("[data-more]")) {
+          more.hidden = more.dataset.more !== kind;
+          if (!more.hidden) more.closest("details").hidden = more.dataset.count === "0";
+        }
+        if (status) status.textContent = button.textContent;
+      });
+    }
+  }
+}

codetrail/web/static/js/learning.js

@@ -0,0 +1,47 @@
+// Marking pages read and grading checks (design section 8). Grading feedback is shown as text, never as HTML.
+import { post, usedText } from "./api.js";
+
+export async function toggleRead() {
+  const read = document.querySelector("[data-mark-read]");
+  const unread = document.querySelector("[data-mark-unread]");
+  const target = read ?? unread;
+  if (!target) return;
+  const url = read ? "/learn/read" : "/learn/unread";
+  const response = await post(url, { page_id: (read ?? unread).dataset[read ? "markRead" : "markUnread"] });
+  if (response.ok) window.location.reload();
+}
+
+export function setUpLearning() {
+  for (const button of document.querySelectorAll("[data-mark-read], [data-mark-unread]")) {
+    button.addEventListener("click", toggleRead);
+  }
+  for (const form of document.querySelectorAll("form[data-check]")) {
+    const feedback = form.querySelector("[data-feedback]");
+    const labels = form.closest("[data-label-pass]").dataset; // the verdicts in the reader's language
+    form.addEventListener("submit", async (event) => {
+      event.preventDefault();
+      const button = form.querySelector("button");
+      button.disabled = true;
+      feedback.textContent = "…";
+      try {
+        const response = await post("/learn/checks", {
+          page_id: form.dataset.page,
+          check_id: form.dataset.check,
+          answer: form.elements.answer.value,
+        });
+        const result = await response.json().catch(() => ({}));
+        if (!response.ok) {
+          feedback.textContent = result.error ?? labels.labelUngraded;
+          return;
+        }
+        const verdict = { pass: labels.labelPass, partial: labels.labelPartial, fail: labels.labelFail }[result.verdict];
+        feedback.textContent = `${verdict}: ${result.feedback}`;
+        const usage = document.querySelector("[data-ask-status]");
+        if (usage && result.usage) feedback.textContent += ` (${usedText(usage, result.usage)})`;
+        if (result.state === "learned") window.setTimeout(() => window.location.reload(), 1500);
+      } finally {
+        button.disabled = false;
+      }
+    });
+  }
+}