learn-loops 0.0.0-stage → 0.4.1

package/dist/flows/think.js

@@ -0,0 +1,120 @@
+import * as p from "@clack/prompts";
+import { askJson } from "../llm.js";
+import { LENSES, challengePrompt, critiquePrompt, deeperPrompt, diagnoseQuestionsPrompt, diagnoseResultPrompt } from "../prompts.js";
+import { m, must, renderMd, t, withSpinner } from "../ui.js";
+import { runChecks } from "./quiz.js";
+const arr = (v) => (Array.isArray(v) ? v.map(String) : []);
+const validateCritique = (x) => ({ strong: arr(x.strong), blindSpots: arr(x.blindSpots), pushback: String(x.pushback ?? ""), feedback: String(x.feedback ?? "") });
+function showCritique(c) {
+    p.note([m(c.feedback), "", ...c.strong.map((s) => `${t.ok("✓")} ${m(s)}`), ...c.blindSpots.map((s) => `${t.warn("△ overlooked:")} ${m(s)}`), ...(c.pushback ? ["", `${t.pink("Push back:")} ${m(c.pushback)}`] : [])].join("\n"), "Thinking check");
+}
+/**
+ * Trade-offs, failure modes, scale and second-order effects. Round one uses the lesson's own question;
+ * further rounds rotate through different lenses so the learner practises seeing a topic from many sides.
+ */
+export async function thinkDeeper(profile, s, title, seed, maxRounds = 3) {
+    const rounds = [];
+    let lensIdx = Math.floor(Math.random() * LENSES.length);
+    let current = seed ? { lens: "Think deeper", ...seed } : undefined;
+    for (let r = 0; r < maxRounds; r++) {
+        if (!current) {
+            const lens = LENSES[lensIdx % LENSES.length];
+            const q = await withSpinner(`Finding a new angle (${lens.label.toLowerCase()})...`, () => askJson(profile, deeperPrompt(profile, s, title, lens, rounds.map((x) => x.question)), (x) => ({ question: String(x.question), considerations: arr(x.considerations) })));
+            current = { lens: lens.label, ...q };
+        }
+        p.log.step(t.bold(t.accent(`Think deeper · ${current.lens}`)));
+        const answer = must(await p.text({ message: m(current.question), placeholder: "no single right answer: weigh both sides, name what could go wrong (blank to skip)" })).trim();
+        if (!answer)
+            break;
+        const c = await withSpinner("Weighing your reasoning...", () => askJson(profile, critiquePrompt(profile, title, current.question, current.considerations, answer), validateCritique));
+        showCritique(c);
+        rounds.push({ lens: current.lens, question: current.question, answer, feedback: c.feedback, blindSpots: c.blindSpots });
+        // Let them answer the pushback, which is the real second-order step.
+        if (c.pushback) {
+            const reply = must(await p.text({ message: `${t.pink("Your response to the push back?")}`, placeholder: "optional (blank to skip)" })).trim();
+            if (reply)
+                rounds[rounds.length - 1].answer += `\n\n[Push back: ${c.pushback}]\n${reply}`;
+        }
+        if (r === maxRounds - 1)
+            break;
+        lensIdx++;
+        const next = LENSES[lensIdx % LENSES.length];
+        const more = must(await p.select({
+            message: "Keep stretching your thinking?",
+            options: [
+                { value: true, label: `Another angle: ${next.label}` },
+                { value: false, label: "That's enough" },
+            ],
+        }));
+        if (!more)
+            break;
+        current = undefined;
+    }
+    return rounds;
+}
+/** End-of-area scenario with no single right answer: apply what you learned and weigh trade-offs. */
+export async function applicationChallenge(profile, s, area, covered) {
+    const ch = await withSpinner("Designing a real-world challenge...", () => askJson(profile, challengePrompt(profile, s, area, covered), (x) => ({ scenario: String(x.scenario), task: String(x.task), considerations: arr(x.considerations) })));
+    p.note(`${m(ch.scenario)}\n\n${t.bold("Your task:")} ${m(ch.task)}`, `Challenge · ${area.title}`);
+    const answer = must(await p.text({ message: "What would you do, and why? What could go wrong?", placeholder: "reason it through (blank to skip)" })).trim();
+    if (!answer)
+        return null;
+    const c = await withSpinner("Reviewing your reasoning...", () => askJson(profile, critiquePrompt(profile, area.title, ch.task, ch.considerations, answer), validateCritique));
+    showCritique(c);
+    return { ...ch, answer, critique: c };
+}
+/**
+ * When a learner keeps missing, find the mental model that's wrong instead of repeating the lesson.
+ * Returns the logged mistake (with the learner's corrected idea in their own words).
+ */
+export async function diagnose(profile, title, missed, explanationFeedback) {
+    const questions = await withSpinner("Working out where the confusion is...", () => askJson(profile, diagnoseQuestionsPrompt(profile, title, missed.map((m) => m.q), explanationFeedback), (x) => arr(x.questions).slice(0, 2)));
+    const qa = [];
+    for (const q of questions) {
+        const a = must(await p.text({ message: `${t.pink("Quick question")} — ${m(q)}`, placeholder: "just say what you picture or believe (blank to skip)" })).trim();
+        qa.push({ q, a });
+    }
+    const res = await withSpinner("Finding the misconception...", () => askJson(profile, diagnoseResultPrompt(profile, title, qa, missed.map((m) => m.q)), (x) => {
+        const rt = x.retest;
+        if (!rt || !Array.isArray(rt.options) || !Number.isInteger(rt.answer) || rt.answer < 0 || rt.answer >= rt.options.length)
+            throw new Error("bad retest");
+        return {
+            misconception: String(x.misconception),
+            reteach: String(x.reteach),
+            retest: { q: String(rt.q), options: rt.options.map(String), answer: rt.answer, explain: String(rt.explain ?? "") },
+        };
+    }));
+    p.note(`${t.warn("Likely snag:")} ${m(res.misconception)}`, "Diagnosis");
+    console.log(renderMd(res.reteach) + "\n");
+    await runChecks([res.retest]);
+    const inMyWords = must(await p.text({ message: `${t.pink("Say the corrected idea in your own words")}`, placeholder: "one or two sentences (blank to skip)" })).trim();
+    return {
+        lesson: title,
+        kind: "diagnosis",
+        what: res.misconception,
+        correction: res.reteach.split("\n").find((l) => l.trim() && !l.startsWith("#") && !l.startsWith("`")) ?? res.misconception,
+        inMyWords: inMyWords || undefined,
+    };
+}
+/** Socratic opener: leading questions the learner works through before the explanation. */
+export async function socraticWarmup(items) {
+    p.log.message(t.dim("Socratic mode: work toward the idea yourself first. Answers needn't be right."));
+    const out = [];
+    for (const [i, item] of items.entries()) {
+        let answer = must(await p.text({ message: `${t.pink(`${i + 1}/${items.length}`)}  ${m(item.q)}`, placeholder: "think out loud (type ? for a hint, blank to skip)" })).trim();
+        if (answer === "?") {
+            p.log.info(`${t.warn("Hint:")} ${m(item.hint)}`);
+            answer = must(await p.text({ message: item.q, placeholder: "try again with the hint (blank to skip)" })).trim();
+        }
+        p.log.message(`${t.accent("→")} ${m(item.idea)}`);
+        out.push({ q: item.q, answer });
+    }
+    return out;
+}
+/** Predict-then-reveal: a wrong guess followed by the truth is memorable. */
+export async function predictThenReveal(pred) {
+    p.note(m(pred.scenario), t.pink("Predict"));
+    const guess = must(await p.text({ message: m(pred.question), placeholder: "commit to a guess before the reveal (blank to skip)" })).trim();
+    p.log.message(`${t.accent("Reveal:")} ${m(pred.outcome)}`);
+    return guess;
+}

package/dist/llm.js

@@ -0,0 +1,87 @@
+import { spawn } from "node:child_process";
+import { mkdtemp, readFile, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+export const TUTOR_SYSTEM = [
+    "You are an exceptional tutor grounded in learning science: you activate prior knowledge,",
+    "teach in small chunks, use concrete examples and diagrams, test retrieval rather than recognition,",
+    "and correct misconceptions precisely. You never pad. You are accurate: if unsure, say so.",
+    "You output exactly what is asked for, in the requested format, with no preamble.",
+].join(" ");
+function run(cmd, args, input, timeoutMs) {
+    return new Promise((resolve, reject) => {
+        const child = spawn(cmd, args, { cwd: tmpdir(), stdio: ["pipe", "pipe", "pipe"] });
+        let out = "";
+        let err = "";
+        const timer = setTimeout(() => {
+            child.kill("SIGKILL");
+            reject(new Error(`${cmd} timed out after ${timeoutMs / 1000}s`));
+        }, timeoutMs);
+        child.stdout.on("data", (d) => (out += d));
+        child.stderr.on("data", (d) => (err += d));
+        child.on("error", (e) => {
+            clearTimeout(timer);
+            reject(new Error(`Could not run "${cmd}" — is it installed and on your PATH? (${e.message})`));
+        });
+        child.on("close", (code) => {
+            clearTimeout(timer);
+            if (code === 0)
+                resolve(out);
+            else
+                reject(new Error(`${cmd} exited with ${code}: ${err.trim().split("\n").slice(-4).join("\n")}`));
+        });
+        child.stdin.end(input);
+    });
+}
+export async function complete(provider, prompt, timeoutMs = 240_000) {
+    if (provider === "claude") {
+        return run("claude", ["-p", "--tools", "", "--no-session-persistence", "--output-format", "text", "--system-prompt", TUTOR_SYSTEM], prompt, timeoutMs);
+    }
+    const dir = await mkdtemp(join(tmpdir(), "loops-"));
+    const outFile = join(dir, "last.txt");
+    try {
+        await run("codex", ["exec", "--skip-git-repo-check", "--ephemeral", "-s", "read-only", "-o", outFile, "-"], `${TUTOR_SYSTEM}\n\n${prompt}`, timeoutMs);
+        return await readFile(outFile, "utf8");
+    }
+    finally {
+        await rm(dir, { recursive: true, force: true });
+    }
+}
+/**
+ * Models often forget to double LaTeX backslashes inside JSON strings. `\theta` would silently parse as a
+ * tab + "heta", `\nabla` as newline + "abla", `\frac` as form feed + "rac". Double the backslash of any
+ * known command that collides with a JSON escape, and any lone backslash that isn't a valid escape at all.
+ */
+const COLLIDING = "theta|tau|times|text|textbf|textit|textrm|tan|tanh|tilde|to|top|triangle|therefore|tfrac|thinspace|frac|forall|flat|beta|bar|begin|boldsymbol|bot|binom|big|bigg|Big|Bigg|bmod|bullet|bigcup|bigcap|bigoplus|bf|rho|right|rightarrow|rangle|rbrace|rceil|rfloor|rm|nabla|neq|nu|ne|not|notin|newcommand|ni|neg|nleq|ngeq|nmid|nearrow";
+export function repairLatexEscapes(json) {
+    const re = new RegExp(`\\\\\\\\|\\\\(?:(?=(?:${COLLIDING})(?![a-zA-Z]))|u(?![0-9a-fA-F]{4})|(?![\\\\"/bfnrtu]))`, "g");
+    return json.replace(re, (m) => (m === "\\\\" ? m : "\\\\" + m.slice(1)));
+}
+export function extractJson(text) {
+    // Slice between the outermost braces; an outer ```json fence falls outside them. Don't strip
+    // backticks globally: lesson markdown inside the JSON contains ```mermaid fences.
+    const start = text.indexOf("{");
+    const end = text.lastIndexOf("}");
+    if (start === -1 || end <= start)
+        throw new Error("no JSON object in model output");
+    return JSON.parse(repairLatexEscapes(text.slice(start, end + 1)));
+}
+/** Ask for JSON, validate it, and retry once telling the model what was wrong. */
+export async function askJson(profile, prompt, validate) {
+    let lastError = "";
+    for (let attempt = 0; attempt < 2; attempt++) {
+        const full = attempt === 0 ? prompt : `${prompt}\n\nYour previous reply was rejected: ${lastError}\nReturn ONLY valid JSON this time.`;
+        try {
+            return validate(extractJson(await complete(profile.provider, full)));
+        }
+        catch (e) {
+            lastError = e.message;
+            if (attempt === 1 || /not installed|PATH|timed out/.test(lastError))
+                throw new Error(lastError);
+        }
+    }
+    throw new Error(lastError);
+}
+export async function askText(profile, prompt) {
+    return (await complete(profile.provider, prompt)).trim();
+}

package/dist/markdown.js

@@ -0,0 +1,136 @@
+import { dirname, join, relative } from "node:path";
+import { writeText } from "./store.js";
+import { parsePlot, plotToSvg, sanitizeSvg, svgCaption } from "./figures.js";
+/** Strip characters that break mermaid mindmap / quoted labels. */
+export const clean = (s) => s.replace(/["'`()\[\]{}:;#<>]/g, "").replace(/\s+/g, " ").trim();
+export const nodeId = (s) => "n_" + s.replace(/[^a-zA-Z0-9]/g, "_");
+export function mapMarkdown(topic) {
+    const { title, map } = topic.state;
+    if (!map)
+        return "";
+    const mind = [
+        "```mermaid",
+        "mindmap",
+        `  root((${clean(title)}))`,
+        ...map.areas.flatMap((a) => [`    ${clean(a.title)}`, ...a.concepts.map((c) => `      ${clean(c.name)}`)]),
+        "```",
+    ].join("\n");
+    const edges = map.areas.flatMap((a) => a.prereqs.filter((p) => map.areas.some((x) => x.id === p)).map((p) => `  ${nodeId(p)} --> ${nodeId(a.id)}`));
+    const flow = [
+        "```mermaid",
+        "flowchart LR",
+        ...map.areas.map((a) => `  ${nodeId(a.id)}["${clean(a.title)}"]`),
+        ...edges,
+        "```",
+    ].join("\n");
+    return `# ${title} — map
+
+${map.overview}
+
+## The territory
+
+${mind}
+
+## Suggested order
+
+Arrows mean "understand this first".
+
+${flow}
+
+## Areas
+
+${map.areas.map((a) => `### ${a.title}\n${a.summary}\n\n${a.concepts.map((c) => `- **${c.name}** — ${c.blurb}`).join("\n")}`).join("\n\n")}
+`;
+}
+export function lessonMarkdown(title, lesson, x = {}) {
+    const quote = (s) => s.split("\n").map((l) => "> " + l).join("\n");
+    const checks = lesson.checks
+        .map((c, i) => `${i + 1}. ${c.q}\n${c.options.map((o, j) => `   - ${j === c.answer ? "✅" : "▫️"} ${o}`).join("\n")}\n   - *${c.explain}*`)
+        .join("\n");
+    const section = (heading, body) => (body.trim() ? `\n## ${heading}\n\n${body}\n` : "");
+    const socratic = x.socratic?.length ? section("Questions I worked through first", x.socratic.map((s) => `**${s.q}**\n\n${quote(s.answer || "(skipped)")}`).join("\n\n")) : "";
+    const prediction = lesson.prediction ? section("Predict, then reveal", `**${lesson.prediction.scenario}**\n\n${lesson.prediction.question}\n\n${quote(x.prediction || "(skipped)")}\n\n**What happened:** ${lesson.prediction.outcome}`) : "";
+    const own = x.attempts?.length
+        ? section("In my own words", `> ${lesson.teachBack}\n\n` +
+            x.attempts.map((o, i) => `**Attempt ${i + 1}** — ${o.grade.score}/3\n\n${quote(o.answer)}\n\n${o.grade.feedback}${o.grade.missing.length ? `\n\nMissing: ${o.grade.missing.join("; ")}` : ""}`).join("\n\n"))
+        : "";
+    const deeper = x.deeper?.length
+        ? section("Thinking deeper", x.deeper.map((d) => `**${d.lens}: ${d.question}**\n\n${quote(d.answer)}\n\n${d.feedback}${d.blindSpots.length ? `\n\nBlind spots to revisit:\n${d.blindSpots.map((b) => `- ${b}`).join("\n")}` : ""}`).join("\n\n---\n\n"))
+        : "";
+    const connection = x.connection ? section("Where I could use this", quote(x.connection)) : "";
+    return `# ${title}
+
+${lesson.markdown}
+${socratic}${prediction}
+## Key points
+
+${lesson.keyPoints.map((k) => `- ${k}`).join("\n")}
+
+## Check yourself
+
+${checks}
+${x.missed?.length ? `\n**Still shaky:** ${x.missed.join("; ")}\n` : ""}${own}${deeper}${connection}
+## Flashcards
+
+${lesson.cards.map((c) => `- **${c.front}** → ${c.back}`).join("\n")}
+`;
+}
+export function mistakesMarkdown(topic) {
+    const list = topic.state.mistakes ?? [];
+    const kind = { quiz: "Missed a question", overconfident: "Sure, but wrong", explanation: "Gap in my explanation", diagnosis: "Misconception" };
+    const byLesson = new Map();
+    for (const m of list)
+        byLesson.set(m.lesson, [...(byLesson.get(m.lesson) ?? []), m]);
+    const body = [...byLesson.entries()]
+        .map(([lesson, ms]) => `## ${lesson}\n\n${ms.map((m) => `- **${kind[m.kind]}** (${m.date}): ${m.what}\n  - Correct idea: ${m.correction}${m.inMyWords ? `\n  - In my words: *${m.inMyWords}*` : ""}`).join("\n")}`)
+        .join("\n\n");
+    return `# Mistake journal — ${topic.state.title}\n\nThe fastest way to improve is to understand exactly what you got wrong.\n\n${body || "_Nothing yet._"}\n`;
+}
+export async function writeIndex(topic) {
+    const { state } = topic;
+    const lines = [`# ${state.title}`, "", state.map?.overview ?? "", "", "- [Map of the territory](map.md)", ...(state.mistakes?.length ? ["- [Mistake journal](mistakes.md)"] : []), ""];
+    if (state.map) {
+        lines.push("## Progress", "");
+        for (const a of state.map.areas) {
+            const pr = state.progress[a.id];
+            const done = pr?.done.length ?? 0;
+            const total = pr?.outline?.length ?? 0;
+            const surveyed = pr?.surveyed ? "✅" : "⬜";
+            lines.push(`- ${surveyed} **${a.title}** — survey: [overview](survey/${a.id}.md)${total ? ` · deep dive ${done}/${total}: ${(pr.outline ?? []).map((l, i) => (pr.done.includes(l.id) ? `[${l.title}](deep/${a.id}/${String(i + 1).padStart(2, "0")}-${l.id}.md)` : l.title)).join(", ")}` : ""}`);
+        }
+    }
+    lines.push("", `_${state.cards.length} flashcards tracked in topic.json_`, "");
+    await writeText(join(topic.dir, "README.md"), lines.join("\n"));
+}
+/**
+ * Lessons embed ```svg and ```plot blocks. In the saved markdown they become real .svg files under
+ * figures/ and standard image links, which GitHub, VS Code and Obsidian all display. Equations stay as
+ * $$ TeX $$ (rendered by those viewers); mermaid stays fenced.
+ */
+export async function materializeFigures(md, topicDir, lessonFile) {
+    const base = lessonFile.replace(/\.md$/, "").replace(/[^a-z0-9]+/gi, "-");
+    const jobs = [];
+    let n = 0;
+    const out = md.replace(/```(svg|plot)\n([\s\S]*?)```/g, (_, kind, src) => {
+        let svg = null;
+        let caption = "";
+        if (kind === "svg") {
+            svg = sanitizeSvg(src);
+            caption = svg ? svgCaption(svg) : "";
+        }
+        else {
+            const spec = parsePlot(src);
+            svg = spec && plotToSvg(spec);
+            caption = spec?.title ?? "";
+        }
+        if (!svg)
+            return "> *(a figure here could not be rendered)*";
+        const file = `figures/${base}-${++n}.svg`;
+        jobs.push({ token: file, file, svg, caption });
+        const rel = relative(dirname(join(topicDir, lessonFile)), join(topicDir, file));
+        return `![${caption || "Figure " + n}](${rel})`;
+    });
+    for (const j of jobs)
+        await writeText(join(topicDir, j.file), j.svg);
+    return out;
+}

package/dist/math.js

@@ -0,0 +1,307 @@
+import { createRequire } from "node:module";
+import { Resvg } from "@resvg/resvg-js";
+const require = createRequire(import.meta.url);
+let converter;
+/** MathJax in pure Node (no DOM, no browser): TeX with physics, mhchem, ams, cancel. */
+function mathjax() {
+    if (converter)
+        return converter;
+    const { mathjax } = require("mathjax-full/js/mathjax.js");
+    const { TeX } = require("mathjax-full/js/input/tex.js");
+    const { SVG } = require("mathjax-full/js/output/svg.js");
+    const { liteAdaptor } = require("mathjax-full/js/adaptors/liteAdaptor.js");
+    const { RegisterHTMLHandler } = require("mathjax-full/js/handlers/html.js");
+    // Each TeX package must be loaded (registered) before the TeX input jax can use it.
+    for (const cfg of ["ams/AmsConfiguration", "newcommand/NewcommandConfiguration", "physics/PhysicsConfiguration", "mhchem/MhchemConfiguration", "cancel/CancelConfiguration", "boldsymbol/BoldsymbolConfiguration", "noundefined/NoUndefinedConfiguration"]) {
+        require(`mathjax-full/js/input/tex/${cfg}.js`);
+    }
+    const adaptor = liteAdaptor();
+    RegisterHTMLHandler(adaptor);
+    const doc = mathjax.document("", {
+        InputJax: new TeX({ packages: ["base", "ams", "newcommand", "physics", "mhchem", "cancel", "boldsymbol", "noundefined"] }),
+        OutputJax: new SVG({ fontCache: "none" }),
+    });
+    converter = (tex, display) => {
+        const html = adaptor.innerHTML(doc.convert(tex, { display }));
+        if (/data-mjx-error|<merror/.test(html))
+            throw new Error("TeX error");
+        return html.replace(/^<mjx-container[^>]*>/, "").replace(/<\/mjx-container>$/, "");
+    };
+    return converter;
+}
+const PX_PER_EX = 9;
+/** TeX → standalone SVG with pixel sizes (resvg doesn't understand ex), padded on white. */
+export function texToSvg(tex, display = true) {
+    const inner = mathjax()(tex, display);
+    const w = parseFloat(inner.match(/width="([\d.]+)ex"/)?.[1] ?? "10") * PX_PER_EX;
+    const h = parseFloat(inner.match(/height="([\d.]+)ex"/)?.[1] ?? "2") * PX_PER_EX;
+    const body = inner
+        .replace(/ style="[^"]*"/, "")
+        .replace(/width="[\d.]+ex"/, `width="${w}"`)
+        .replace(/height="[\d.]+ex"/, `height="${h}"`)
+        .replace("<svg ", '<svg color="#1a1a2e" ');
+    const pad = 10;
+    return `<svg xmlns="http://www.w3.org/2000/svg" width="${w + 2 * pad}" height="${h + 2 * pad}" viewBox="0 0 ${w + 2 * pad} ${h + 2 * pad}"><rect width="100%" height="100%" rx="8" fill="#ffffff"/><g transform="translate(${pad} ${pad})">${body}</g></svg>`;
+}
+export function svgToPng(svg, zoom = 2.5) {
+    const r = new Resvg(svg, {
+        background: "#ffffff",
+        fitTo: { mode: "zoom", value: zoom },
+        font: { loadSystemFonts: true, defaultFontFamily: "Helvetica" },
+    });
+    const out = r.render();
+    return { png: Buffer.from(out.asPng()), width: Math.round(out.width / zoom) };
+}
+export const texToPng = (tex, display = true) => svgToPng(texToSvg(tex, display), 3);
+// ---------------------------------------------------------------------------------------------
+// Unicode fallback: a small TeX layout engine for terminals without image support.
+// ---------------------------------------------------------------------------------------------
+const unicodeit = require("unicodeit");
+const width = (s) => [...s.replace(/\p{M}/gu, "")].length;
+const pad = (s, n, side = "r") => {
+    const gap = Math.max(0, n - width(s));
+    return side === "r" ? s + " ".repeat(gap) : side === "l" ? " ".repeat(gap) + s : " ".repeat(Math.floor(gap / 2)) + s + " ".repeat(Math.ceil(gap / 2));
+};
+const txt = (s) => ({ l: [s], b: 0 });
+const boxW = (b) => Math.max(...b.l.map(width));
+function hcat(boxes) {
+    const live = boxes.filter((b) => b.l.length);
+    if (!live.length)
+        return txt("");
+    const above = Math.max(...live.map((b) => b.b));
+    const below = Math.max(...live.map((b) => b.l.length - b.b - 1));
+    const rows = [];
+    for (let r = 0; r < above + below + 1; r++) {
+        rows.push(live.map((b) => pad(b.l[r - (above - b.b)] ?? "", boxW(b))).join(""));
+    }
+    return { l: rows, b: above };
+}
+function frac(n, d) {
+    const w = Math.max(boxW(n), boxW(d)) + 2;
+    return { l: [...n.l.map((s) => pad(s, w, "c")), "─".repeat(w), ...d.l.map((s) => pad(s, w, "c"))], b: n.l.length };
+}
+function sqrtBox(x) {
+    const w = boxW(x);
+    const rows = x.l.map((s, i) => (i === 0 ? "√" : " ") + pad(s, w));
+    return { l: [" " + "‾".repeat(w), ...rows.map((r, i) => (i === 0 ? "√" + r.slice(1) : r))], b: x.b + 1 };
+}
+const SUP = "⁰¹²³⁴⁵⁶⁷⁸⁹⁺⁻⁼⁽⁾ⁿⁱ";
+const SUB = "₀₁₂₃₄₅₆₇₈₉₊₋₌₍₎ₐₑₒₓᵢⱼₙₖₗₘₚₛₜ";
+const RELATIONS = new Set(["=", "≈", "≠", "≤", "≥", "→", "←", "↔", "⇒", "∝", "∼", "≡", "∈", "⊂", "⊆"]);
+const BIG_OPS = { sum: "∑", prod: "∏", int: "∫", oint: "∮", lim: "lim" };
+/** Try to write `s` entirely as unicode super/subscript characters. */
+function script(kind, s) {
+    const out = unicodeit.replace(`${kind}{${s}}`);
+    return out && !/[\^_{}\\]/.test(out) ? out : null;
+}
+class Parser {
+    s;
+    inline;
+    i = 0;
+    constructor(s, inline) {
+        this.s = s;
+        this.inline = inline;
+    }
+    group() {
+        // consumes one TeX argument: {…} or a single token
+        this.ws();
+        if (this.s[this.i] === "{") {
+            this.i++;
+            const b = this.seq("}");
+            this.i++;
+            return b;
+        }
+        if (this.s[this.i] === "\\")
+            return this.token();
+        return txt(this.s[this.i++] ?? "");
+    }
+    raw() {
+        // raw text of one argument (for \text, \mathrm, accents …)
+        this.ws();
+        if (this.s[this.i] !== "{")
+            return this.s[this.i++] ?? "";
+        let depth = 0;
+        const start = this.i + 1;
+        for (; this.i < this.s.length; this.i++) {
+            if (this.s[this.i] === "{")
+                depth++;
+            else if (this.s[this.i] === "}" && --depth === 0)
+                break;
+        }
+        return this.s.slice(start, this.i++);
+    }
+    /** Raw TeX of one argument: {balanced}, a \\command, or a single character. */
+    rawArg() {
+        this.ws();
+        if (this.s[this.i] === "{")
+            return this.raw();
+        const m = this.s.slice(this.i).match(/^\\(?:[a-zA-Z]+|.)/);
+        if (m) {
+            this.i += m[0].length;
+            return m[0];
+        }
+        return this.s[this.i++] ?? "";
+    }
+    sub(tex) {
+        return new Parser(tex, this.inline).seq();
+    }
+    ws() {
+        while (/\s/.test(this.s[this.i] ?? ""))
+            this.i++;
+    }
+    token() {
+        const m = this.s.slice(this.i).match(/^\\([a-zA-Z]+|.)/);
+        if (!m)
+            return txt(this.s[this.i++]);
+        this.i += m[0].length;
+        const name = m[1];
+        if (name === "frac" || name === "dfrac" || name === "tfrac") {
+            const n = this.group();
+            const d = this.group();
+            return this.inline ? txt(`${flat(n)}/${flat(d)}`.replace(/^(.{2,})\/(.+)$/, (_, a, b) => `${a.length > 1 && /[+\-−]/.test(a) ? `(${a})` : a}/${/[+\-−]/.test(b) ? `(${b})` : b}`)) : frac(n, d);
+        }
+        if (name === "sqrt") {
+            const x = this.group();
+            return this.inline ? txt(`√(${flat(x)})`) : sqrtBox(x);
+        }
+        if (name === "left" || name === "right") {
+            const ch = this.s[this.i++];
+            return txt(ch === "." ? "" : ch === "\\" ? this.s[this.i++] : ch);
+        }
+        if (["text", "mathrm", "operatorname", "textbf", "mathbf", "boldsymbol", "mathbb", "mathcal", "vec", "hat", "bar", "dot", "ddot", "tilde", "overline", "mathit", "mathsf", "mathscr", "mathfrak"].includes(name)) {
+            return txt(unicodeit.replace(`\\${name}{${this.raw()}}`).replace(/^\\(?:text|mathrm|operatorname|overline)\{(.*)\}$/, "$1").replace(/^\\\w+\{(.*)\}$/, "$1"));
+        }
+        const phys = this.physics(name);
+        if (phys)
+            return phys;
+        if (name in BIG_OPS)
+            return this.bigOp(BIG_OPS[name], name);
+        if (name === "\\" || name === "," || name === ";" || name === ":" || name === "!" || name === "quad" || name === "qquad")
+            return txt(name === "quad" ? "  " : name === "qquad" ? "    " : name === "," || name === ";" || name === ":" ? " " : "");
+        if (name === "begin" || name === "end") {
+            this.raw();
+            return txt(name === "begin" ? "" : "");
+        }
+        if (name === "&")
+            return txt("  ");
+        const u = unicodeit.replace(`\\${name}`);
+        return txt(u.startsWith("\\") ? name : u);
+    }
+    physics(name) {
+        const bold = (x) => unicodeit.replace(`\\mathbf{${x}}`);
+        switch (name) {
+            case "ket": return txt(`|${flat(this.sub(this.rawArg()))}⟩`);
+            case "bra": return txt(`⟨${flat(this.sub(this.rawArg()))}|`);
+            case "braket": {
+                const a = flat(this.sub(this.rawArg()));
+                const b = flat(this.sub(this.rawArg()));
+                return txt(`⟨${a}|${b}⟩`);
+            }
+            case "expval": return txt(`⟨${flat(this.sub(this.rawArg()))}⟩`);
+            case "abs": return txt(`|${flat(this.sub(this.rawArg()))}|`);
+            case "norm": return txt(`‖${flat(this.sub(this.rawArg()))}‖`);
+            case "vb":
+            case "vu": return txt(name === "vb" ? bold(this.rawArg()) : unicodeit.replace(`\\hat{${this.rawArg()}}`));
+            case "grad": return txt("∇");
+            case "curl": return txt("∇×");
+            case "div": return txt("∇·");
+            case "laplacian": return txt("∇²");
+            case "qty": return txt("");
+            case "pdv":
+            case "dv": {
+                const d = name === "pdv" ? "∂" : "d";
+                const f = this.rawArg();
+                this.ws();
+                const g = this.s[this.i] === "{" || this.s[this.i] === "\\" ? this.rawArg() : "";
+                return this.inline ? txt(g ? `${d}${flat(this.sub(f))}/${d}${flat(this.sub(g))}` : `${d}/${d}${flat(this.sub(f))}`) : g ? frac(txt(`${d}${flat(this.sub(f))}`), txt(`${d}${flat(this.sub(g))}`)) : frac(txt(d), txt(`${d}${flat(this.sub(f))}`));
+            }
+            case "ce": return txt(chem(this.raw()));
+        }
+        return null;
+    }
+    bigOp(sym, name) {
+        let lo;
+        let hi;
+        for (let k = 0; k < 2; k++) {
+            this.ws();
+            const c = this.s[this.i];
+            if (c === "_" && !lo)
+                (this.i++, (lo = this.group()));
+            else if (c === "^" && !hi)
+                (this.i++, (hi = this.group()));
+        }
+        if (this.inline) {
+            const lim = lo || hi ? `[${lo ? flat(lo) : ""}${hi ? `→${flat(hi)}` : ""}]` : "";
+            return txt(sym + lim);
+        }
+        const w = Math.max(width(sym), lo ? boxW(lo) : 0, hi ? boxW(hi) : 0);
+        const rows = [...(hi ? hi.l.map((s) => pad(s, w, "c")) : []), pad(sym, w, "c"), ...(lo ? lo.l.map((s) => pad(s, w, "c")) : [])];
+        return { l: rows, b: hi ? hi.l.length : 0 };
+    }
+    seq(stop) {
+        const parts = [];
+        while (this.i < this.s.length && this.s[this.i] !== stop) {
+            const c = this.s[this.i];
+            if (/\s/.test(c)) {
+                this.i++;
+            }
+            else if (c === "{") {
+                parts.push(this.group());
+            }
+            else if (c === "^" || c === "_") {
+                this.i++;
+                const rawTex = this.rawArg();
+                const mapped = script(c, rawTex);
+                const inner = flat(this.sub(rawTex));
+                parts.push(txt(mapped ?? (/^[A-Za-z0-9]+$/.test(inner) ? `${c}${inner}` : `${c}(${inner})`)));
+            }
+            else if (c === "\\") {
+                parts.push(this.token());
+            }
+            else {
+                this.i++;
+                const prev = parts[parts.length - 1];
+                const before = prev ? flat(prev) : "";
+                const binary = (c === "+" || c === "-") && before !== "" && !/[=≈≠≤≥→←(,\[]$/.test(before);
+                const rel = RELATIONS.has(c);
+                parts.push(txt(rel || binary ? ` ${c === "-" ? "−" : c} ` : c === "," ? ", " : c));
+            }
+        }
+        // relations produced by commands (\approx, \to …) also get spacing
+        const spaced = parts.map((p) => (p.l.length === 1 && RELATIONS.has(p.l[0]) ? txt(` ${p.l[0]} `) : p));
+        return hcat(spaced);
+    }
+}
+/** \\ce{2H2 + O2 -> 2H2O} → 2H₂ + O₂ → 2H₂O */
+const chem = (s) => s
+    .replace(/<->|<=>/g, "⇌")
+    .replace(/->/g, "→")
+    .replace(/<-/g, "←")
+    .replace(/([A-Za-z)])(\d+)/g, (_, a, n) => a + [...n].map((d) => SUB[+d]).join(""))
+    .replace(/\^\{?([+-]?\d*[+-]?)\}?/g, (_, c) => script("^", c) ?? c);
+const flat = (b) => b.l.join(" ").replace(/\s+/g, " ").trim();
+/** Display equation as multi-line Unicode art. */
+export function texToLines(tex) {
+    const clean = tex.replace(/\\(?:label|tag)\{[^}]*\}/g, "").trim();
+    const box = new Parser(clean, false).seq();
+    return box.l.map((l) => l.replace(/\s+$/, ""));
+}
+/** Inline equation as one line of Unicode. */
+export function texToInline(tex) {
+    return flat(new Parser(tex.trim(), true).seq());
+}
+/** Replace $…$, $$…$$, \(…\) in a plain string with Unicode (for prompts, options, flashcards). */
+export function mathToText(s) {
+    const conv = (tex) => {
+        try {
+            return texToInline(tex);
+        }
+        catch {
+            return tex;
+        }
+    };
+    return s
+        .replace(/\$\$([\s\S]+?)\$\$/g, (_, t) => conv(t))
+        .replace(/\\\(([\s\S]+?)\\\)/g, (_, t) => conv(t))
+        .replace(/\$(?!\s)([^$\n]+?)(?<!\s)\$(?!\d)/g, (m, t) => (/^\d/.test(t) && !/[\\^_{}]/.test(t) ? m : conv(t)));
+}