learn-loops 0.0.0-stage → 0.4.0

package/README.md

@@ -1,3 +1,64 @@
-# Temporary Holding Version
+# loops
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+A colorful, interactive CLI that turns **Claude Code** or **Codex** into a personal tutor. It maps a topic, surveys it broadly, then takes you deep one area at a time, and it builds a folder of markdown notes with diagrams, equations and figures as you go.
+
+```bash
+npm i -g learn-loops
+loops
+```
+
+Requires Node 20+ and either the `claude` or `codex` CLI installed and logged in. If `loops` isn't found after install, add npm's global bin folder to your `PATH` (`npm prefix -g`, then `<that>/bin`).
+
+## How it teaches
+
+1. **Profile first**: the first run asks how you learn (examples vs. theory, diagrams, tone, quiz difficulty, Socratic or not, session length) and tailors every prompt.
+2. **Launch screen**: each time you start, a quick energy/time check-in, then reopen a topic you've started or begin something new.
+3. **Brain dump**: you write what you already know, which activates prior knowledge and sets the starting level.
+4. **Map**: the whole territory as areas, concepts and a prerequisite graph (`map.md`, mermaid mindmap + flowchart, also drawn in the terminal).
+5. **Survey**: a short lesson per area, so you get the basic idea of everything before depth.
+6. **Deep dive**: you pick an area; it plans 4-7 lessons that build on each other, each with worked examples and figures.
+7. **Every lesson**: guess first, read a small chunk, "explain it differently" on demand, predict-then-reveal, quiz with confidence ratings, then an **explain-it-in-your-own-words** teach-back to a persona (a curious 12-year-old, a skeptical expert...) who asks a follow-up.
+8. **Think deeper**: trade-offs, failure modes, scale and second-order effects, with push-back, rotating through different lenses; an end-of-area **application challenge** with no single right answer.
+9. **When you're stuck**: a short diagnosis finds the mental model that's wrong, re-teaches that, and re-tests it.
+10. **Remembering**: SM-2 spaced repetition, a warm-up before each session, interleaved mixed quizzes (weakest first, confident mistakes first), a **mistake journal**, and a **streak**.
+
+## Equations, physics diagrams and plots
+
+Technical lessons use real typesetting, not ASCII approximations:
+
+- **Equations** are written in LaTeX and rendered with [MathJax](https://www.mathjax.org) (physics, ams, mhchem and cancel packages: `\ket{}`, `\pdv{}{}`, `\vb{}`, `\ce{}`), then rasterised with [resvg](https://github.com/RazrFalcon/resvg). No browser or LaTeX install needed.
+- **Physical diagrams** (free-body, circuits, optics, fields) are drawn as SVG by the tutor, validated and sanitised, then shown inline.
+- **Function plots** are exact: the tutor supplies expressions, [mathjs](https://mathjs.org) evaluates them, and `loops` draws the chart.
+- **Inline display** works in iTerm2, WezTerm, Kitty, Ghostty and VS Code's terminal. Elsewhere you get a Unicode fallback: stacked fractions, roots, sums and bra-kets for equations, braille line art for plots. SVG diagrams need an image-capable terminal or the saved file.
+- Saved notes keep `$$TeX$$` (rendered by GitHub, VS Code and Obsidian) and write each figure to `figures/*.svg` with a normal image link.
+- Flowcharts, sequence, state and class diagrams (mermaid) are drawn in the terminal with [beautiful-mermaid](https://github.com/lukilabs/beautiful-mermaid).
+
+Override detection with `LOOPS_IMAGES=iterm|kitty|off`.
+
+## Commands
+
+```
+loops               interactive menu (check-in, then reopen or start new)
+loops new [topic]   start a new topic
+loops continue      resume
+loops review        review due flashcards
+loops quiz          interleaved mixed quiz
+loops mistakes      your mistake journal
+loops streak        your streak
+loops map           a topic's map and prerequisite diagram
+loops topics        progress overview
+loops profile       edit your learner profile
+```
+
+## Where things live
+
+```
+~/Learning/<folder>/<topic>/
+  README.md  map.md  mistakes.md  topic.json
+  survey/<area>.md
+  deep/<area>/01-<lesson>.md  challenge.md
+  figures/*.svg
+```
+
+Your profile and streak live in `~/.config/loops/`.
+Env: `LOOPS_HOME`, `LOOPS_PROVIDER=claude|codex`, `LOOPS_IMAGES`, `NO_COLOR`.

package/dist/cli.js

@@ -0,0 +1,250 @@
+#!/usr/bin/env node
+import * as p from "@clack/prompts";
+import { listTopics, loadProfile, configDir } from "./store.js";
+import { isDue } from "./srs.js";
+import { currentStreak, doneToday, loadStats, recordActivity, saveCheckin } from "./stats.js";
+import { banner, bar, must, t } from "./ui.js";
+import { onboard } from "./flows/onboard.js";
+import { continueTopic, newTopic, printMap } from "./flows/learn.js";
+import { reviewCards } from "./flows/quiz.js";
+const HELP = `${t.bold("loops")} — learn anything with Claude Code or Codex as your tutor
+
+  loops                 interactive menu
+  loops new [topic]     start learning something new
+  loops continue        pick up where you left off
+  loops review          spaced-repetition review of due flashcards
+  loops quiz            interleaved mixed quiz across everything you've learned
+  loops mistakes        your mistake journal
+  loops streak          your streak
+  loops map             show a topic's map and prerequisite diagram
+  loops topics          list your topics and progress
+  loops profile         edit how you like to learn
+  loops --help          this help
+
+Env: LOOPS_HOME (config dir), LOOPS_PROVIDER=claude|codex, NO_COLOR`;
+const dueCount = (topics) => topics.reduce((n, tp) => n + tp.state.cards.filter((c) => isDue(c)).length, 0);
+function progressOf(tp) {
+    const areas = tp.state.map?.areas ?? [];
+    const lessons = areas.reduce((n, a) => n + (tp.state.progress[a.id]?.done.length ?? 0), 0);
+    return { areas: areas.length, surveyed: areas.filter((a) => tp.state.progress[a.id]?.surveyed).length, lessons };
+}
+async function chooseTopic(topics, message) {
+    const idx = must(await p.select({
+        message,
+        options: topics.map((tp, i) => {
+            const pr = progressOf(tp);
+            return { value: i, label: `${tp.state.title}`, hint: `${tp.state.category} · ${pr.surveyed}/${pr.areas} surveyed · ${pr.lessons} deep lessons` };
+        }),
+    }));
+    return topics[idx];
+}
+const streakLine = (st) => {
+    const n = currentStreak(st);
+    const today = doneToday(st) ? t.ok("today ✓") : n ? t.warn("study today to keep it") : t.dim("start one today");
+    return `${n ? t.warn("🔥 " + n + "-day streak") : t.dim("no streak yet")} ${t.dim("· best " + st.longest + " ·")} ${today}`;
+};
+/** Once a day: ask about energy and time, then recommend what to do. Also sets today's session length. */
+async function checkin(profile, st, topics) {
+    const cardCount = topics.reduce((n, tp) => n + tp.state.cards.length, 0);
+    const due = dueCount(topics);
+    let energy = "medium";
+    let minutes = profile.minutesPerSession;
+    if (st.checkin?.day === new Date().toLocaleDateString("en-CA")) {
+        energy = st.checkin.energy;
+        minutes = st.checkin.minutes;
+    }
+    else {
+        p.log.message(streakLine(st));
+        energy = must(await p.select({
+            message: "Quick check-in: how's your energy today?",
+            initialValue: "medium",
+            options: [
+                { value: "low", label: "Low", hint: "keep it light" },
+                { value: "medium", label: "Okay" },
+                { value: "high", label: "Sharp", hint: "good day for hard stuff" },
+            ],
+        }));
+        minutes = must(await p.select({
+            message: "How much time do you have?",
+            initialValue: profile.minutesPerSession,
+            options: [10, 15, 25, 45, 60].map((m) => ({ value: m, label: `${m} min` })),
+        }));
+        st = await saveCheckin(st, energy, minutes);
+    }
+    profile.minutesPerSession = minutes; // today only; not saved
+    let rec = "continue";
+    if (!topics.length)
+        rec = "new";
+    else if (due > 0 && (energy === "low" || minutes <= 10))
+        rec = "review";
+    else if (energy === "low" && cardCount >= 4)
+        rec = "quiz";
+    else if (due >= 8)
+        rec = "review";
+    return { stats: st, rec };
+}
+/** On launch: reopen something you've started, or begin something new. Returns once that session ends. */
+async function startScreen(profile, topics, rec) {
+    if (!topics.length) {
+        p.log.message(t.dim("Nothing started yet — let's pick your first topic."));
+        return dispatch("new", profile);
+    }
+    const recent = topics.slice(0, 5);
+    const choice = must(await p.select({
+        message: "Pick up where you left off, or start something new?",
+        initialValue: rec === "new" ? "__new" : "0",
+        options: [
+            ...recent.map((tp, i) => {
+                const pr = progressOf(tp);
+                const where = tp.state.phase === "survey" ? `surveying ${pr.surveyed}/${pr.areas}` : `deep dive · ${pr.lessons} lessons done`;
+                return { value: String(i), label: tp.state.title, hint: `${tp.state.category} · ${where}` };
+            }),
+            { value: "__new", label: t.accent("+ Start something new") },
+            { value: "__menu", label: t.dim("Go to the main menu") },
+        ],
+    }));
+    if (choice === "__menu")
+        return;
+    if (choice === "__new")
+        return dispatch("new", profile);
+    const tp = recent[Number(choice)];
+    if (tp.state.map && tp.state.phase === "survey" && !tp.state.progress[tp.state.map.areas[0].id]?.surveyed)
+        printMap(tp);
+    await continueTopic(profile, tp);
+}
+async function menu(profile) {
+    let first = true;
+    let rec = "continue";
+    while (true) {
+        const topics = await listTopics(profile);
+        const due = dueCount(topics);
+        let stats = await loadStats();
+        if (first) {
+            ({ stats, rec } = await checkin(profile, stats, topics));
+            first = false;
+            await startScreen(profile, topics, rec);
+            continue; // reload topics and stats after the session
+        }
+        const cards = topics.reduce((n, tp) => n + tp.state.cards.length, 0);
+        const star = (v) => (rec === v ? t.accent(" ★ recommended for today") : "");
+        const opts = [
+            ...(topics.length ? [{ value: "continue", label: "Continue learning", hint: topics[0].state.title + star("continue") }] : []),
+            { value: "new", label: "Start a new topic", hint: star("new").trim() || undefined },
+            ...(due ? [{ value: "review", label: "Review flashcards", hint: `${due} due${star("review")}` }] : []),
+            ...(cards >= 4 ? [{ value: "quiz", label: "Mixed quiz", hint: `interleaved, weakest first${star("quiz")}` }] : []),
+            ...(topics.some((tp) => tp.state.mistakes?.length) ? [{ value: "mistakes", label: "Mistake journal" }] : []),
+            ...(topics.length ? [{ value: "topics", label: "My topics" }] : []),
+        ];
+        // put the recommendation first
+        opts.sort((a, b) => Number(b.value === rec) - Number(a.value === rec));
+        p.log.message(streakLine(stats));
+        const action = must(await p.select({
+            message: `Hi ${profile.name}, what now?`,
+            options: [
+                ...opts,
+                { value: "profile", label: "Edit my learner profile" },
+                { value: "quit", label: "Quit" },
+            ],
+        }));
+        if (action === "quit")
+            return p.outro(t.dim("Keep the loop going ✦"));
+        await dispatch(action, profile);
+    }
+}
+async function dispatch(action, profile, arg) {
+    const topics = await listTopics(profile);
+    switch (action) {
+        case "new": {
+            const tp = await newTopic(profile, arg);
+            if (tp && must(await p.select({ message: "Start the broad survey now?", options: [{ value: true, label: "Yes, let's go" }, { value: false, label: "Later" }] })))
+                await continueTopic(profile, tp);
+            break;
+        }
+        case "continue": {
+            if (!topics.length)
+                return p.log.warn("No topics yet — try `loops new`.");
+            const tp = topics.length === 1 ? topics[0] : await chooseTopic(topics, "Which topic?");
+            if (tp.state.map && tp.state.phase === "survey" && !tp.state.progress[tp.state.map.areas[0].id]?.surveyed)
+                printMap(tp);
+            await continueTopic(profile, tp);
+            break;
+        }
+        case "review":
+        case "quiz": {
+            const mixed = action === "quiz";
+            const n = await reviewCards(topics, mixed ? 10 : 20, mixed ? "mixed" : "due");
+            p.log.success(n ? t.ok(`Reviewed ${n} card${n > 1 ? "s" : ""}.`) : mixed ? "No cards yet — finish a lesson first." : "Nothing due right now. Come back tomorrow — that's the point.");
+            if (n) {
+                const r = await recordActivity();
+                if (r.message)
+                    p.log.success(t.warn("🔥 ") + t.bold(r.message));
+            }
+            break;
+        }
+        case "mistakes": {
+            const withM = topics.filter((tp) => tp.state.mistakes?.length);
+            if (!withM.length)
+                return p.log.info("No mistakes logged yet — they're how you learn fastest, so they'll show up.");
+            for (const tp of withM) {
+                const recent = (tp.state.mistakes ?? []).slice(-6);
+                p.note(recent.map((m) => `${t.warn(m.kind === "overconfident" ? "sure, but wrong" : m.kind)} ${t.dim("· " + m.lesson)}\n  ${m.what}\n  ${t.ok("→")} ${m.correction}${m.inMyWords ? `\n  ${t.dim("in my words: " + m.inMyWords)}` : ""}`).join("\n\n"), `${tp.state.title} — recent mistakes`);
+                p.log.info(t.dim(`Full journal: ${tp.dir}/mistakes.md`));
+            }
+            break;
+        }
+        case "streak": {
+            const st = await loadStats();
+            p.note(`${streakLine(st)}\n${t.dim(`${st.totalDays} day${st.totalDays === 1 ? "" : "s"} studied in total`)}`, "Streak");
+            break;
+        }
+        case "topics": {
+            if (!topics.length)
+                return p.log.warn("No topics yet.");
+            const lines = topics.map((tp) => {
+                const pr = progressOf(tp);
+                return `${t.bold(tp.state.title)} ${t.dim(`(${tp.state.category})`)}\n  survey ${bar(pr.surveyed, pr.areas, 12)}  ${t.dim(`${pr.lessons} deep lessons · ${tp.state.cards.length} cards`)}\n  ${t.dim(tp.dir)}`;
+            });
+            p.note(lines.join("\n\n"), "Your topics");
+            break;
+        }
+        case "map": {
+            if (!topics.length)
+                return p.log.warn("No topics yet.");
+            const tp = topics.length === 1 ? topics[0] : await chooseTopic(topics, "Which topic?");
+            if (tp.state.map)
+                printMap(tp);
+            break;
+        }
+        case "profile":
+            await onboard(profile);
+            break;
+    }
+}
+async function main() {
+    const [cmd, ...rest] = process.argv.slice(2);
+    if (cmd === "--help" || cmd === "-h" || cmd === "help")
+        return console.log(HELP);
+    if (cmd === "--version" || cmd === "-v")
+        return console.log("0.4.0");
+    if (!process.stdin.isTTY) {
+        console.error("loops needs an interactive terminal.");
+        process.exit(1);
+    }
+    banner();
+    let profile = await loadProfile();
+    if (!profile)
+        profile = await onboard();
+    if (process.env.LOOPS_PROVIDER === "claude" || process.env.LOOPS_PROVIDER === "codex")
+        profile.provider = process.env.LOOPS_PROVIDER;
+    if (!cmd)
+        return menu(profile);
+    if (["new", "continue", "review", "quiz", "mistakes", "streak", "topics", "profile", "map"].includes(cmd))
+        return dispatch(cmd, profile, rest.join(" ") || undefined);
+    console.log(HELP);
+    process.exit(1);
+}
+main().catch((e) => {
+    p.log.error(t.bad(e.message));
+    console.error(t.dim(`(config: ${configDir()})`));
+    process.exit(1);
+});

package/dist/diagram.js

@@ -0,0 +1,49 @@
+import { renderMermaidASCII } from "beautiful-mermaid";
+const color = !!process.stdout.isTTY && !process.env.NO_COLOR;
+const widest = (s) => Math.max(...s.split("\n").map((l) => l.replace(/\x1b\[[0-9;]*m/g, "").length));
+/** mindmap isn't supported by beautiful-mermaid, so draw it as an indented tree. */
+function mindmapTree(src) {
+    const rows = src.split("\n").slice(1).filter((l) => l.trim());
+    const label = (s) => s.trim().replace(/^[\w-]*\(\((.*)\)\)$/, "$1").replace(/^[\w-]*[(\[{]+(.*?)[)\]}]+$/, "$1");
+    const base = rows[0]?.search(/\S/) ?? 0;
+    const nodes = rows.map((r) => ({ depth: Math.round((r.search(/\S/) - base) / 2), text: label(r) }));
+    return nodes
+        .map((n, i) => {
+        if (n.depth === 0)
+            return n.text;
+        let prefix = "";
+        for (let d = 1; d < n.depth; d++)
+            prefix += hasLaterSibling(nodes, i, d) ? "│  " : "   ";
+        return prefix + (hasLaterSibling(nodes, i, n.depth) ? "├─ " : "└─ ") + n.text;
+    })
+        .join("\n");
+}
+function hasLaterSibling(nodes, i, depth) {
+    for (let j = i + 1; j < nodes.length; j++) {
+        if (nodes[j].depth < depth)
+            return false;
+        if (nodes[j].depth === depth)
+            return true;
+    }
+    return false;
+}
+/** Returns terminal art for a mermaid source, or null if it can't be drawn. */
+export function renderDiagram(src, cols = process.stdout.columns ?? 100) {
+    const text = src.trim();
+    if (/^mindmap\b/.test(text))
+        return mindmapTree(text);
+    const attempt = (s) => {
+        try {
+            return renderMermaidASCII(s, { colorMode: color ? "ansi256" : "none", paddingY: 2, paddingX: 4 });
+        }
+        catch {
+            return null;
+        }
+    };
+    let out = attempt(text);
+    // Too wide for this terminal? Flow top-down instead.
+    if (out && widest(out) > cols - 4 && /^(flowchart|graph)\s+(LR|RL)/.test(text)) {
+        out = attempt(text.replace(/^(flowchart|graph)\s+(LR|RL)/, "$1 TD")) ?? out;
+    }
+    return out && widest(out) <= cols - 4 ? out : null;
+}

package/dist/figures.js

@@ -0,0 +1,200 @@
+import { compile } from "mathjs";
+import { svgToPng } from "./math.js";
+const esc = (s) => s.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;");
+/**
+ * Model-drawn diagrams (free-body, ray, circuit, field, wave...) arrive as raw SVG. Keep only static
+ * vector content: no scripts, event handlers, foreign objects or external references. Returns null
+ * if it isn't usable SVG or resvg can't render it.
+ */
+export function sanitizeSvg(src) {
+    let svg = src.trim();
+    const start = svg.indexOf("<svg");
+    const end = svg.lastIndexOf("</svg>");
+    if (start === -1 || end === -1)
+        return null;
+    svg = svg.slice(start, end + 6);
+    svg = svg
+        .replace(/<script[\s\S]*?<\/script>/gi, "")
+        .replace(/<foreignObject[\s\S]*?<\/foreignObject>/gi, "")
+        .replace(/\son\w+\s*=\s*("[^"]*"|'[^']*')/gi, "")
+        .replace(/\s(?:xlink:)?href\s*=\s*("(?!#)[^"]*"|'(?!#)[^']*')/gi, "");
+    if (!/xmlns=/.test(svg))
+        svg = svg.replace("<svg", '<svg xmlns="http://www.w3.org/2000/svg"');
+    if (!/viewBox=/.test(svg) && !/width=/.test(svg))
+        svg = svg.replace("<svg", '<svg viewBox="0 0 640 360"');
+    // A white page behind it, so line art is legible in light and dark viewers alike.
+    svg = svg.replace(/(<svg[^>]*>)/, '$1<rect width="100%" height="100%" fill="#ffffff"/>');
+    try {
+        svgToPng(svg, 1);
+    }
+    catch {
+        return null;
+    }
+    return svg;
+}
+export const svgCaption = (svg) => svg.match(/<title>([\s\S]*?)<\/title>/)?.[1]?.trim() ?? "";
+export function parsePlot(src) {
+    try {
+        const x = JSON.parse(src);
+        if (!Number.isFinite(x.xmin) || !Number.isFinite(x.xmax) || x.xmax <= x.xmin || !Array.isArray(x.series) || !x.series.length)
+            return null;
+        return x;
+    }
+    catch {
+        return null;
+    }
+}
+const COLORS = ["#4c78a8", "#e45756", "#54a24b", "#b279a2", "#f58518"];
+const niceStep = (range, target = 6) => {
+    const raw = range / target;
+    const pow = 10 ** Math.floor(Math.log10(raw));
+    const f = raw / pow;
+    return (f < 1.5 ? 1 : f < 3 ? 2 : f < 7 ? 5 : 10) * pow;
+};
+const fmt = (v) => (Math.abs(v) < 1e-9 ? "0" : String(Number(v.toPrecision(3))));
+/** Exact function plot: the model supplies expressions, mathjs evaluates them, we draw the SVG. */
+export function plotToSvg(spec) {
+    const W = 640, H = 360, L = 62, R = 24, T = spec.title ? 44 : 24, B = 56;
+    const N = 480;
+    const xs = Array.from({ length: N + 1 }, (_, i) => spec.xmin + ((spec.xmax - spec.xmin) * i) / N);
+    const curves = [];
+    for (const s of spec.series.slice(0, 5)) {
+        let f;
+        try {
+            f = compile(s.expr.replace(/^\s*(?:y|f\(x\))\s*=\s*/, ""));
+        }
+        catch {
+            return null;
+        }
+        curves.push({
+            label: s.label ?? s.expr,
+            pts: xs.map((x) => {
+                try {
+                    const v = f.evaluate({ x, pi: Math.PI, e: Math.E });
+                    return typeof v === "number" && Number.isFinite(v) ? v : null;
+                }
+                catch {
+                    return null;
+                }
+            }),
+        });
+    }
+    const vals = curves.flatMap((c) => c.pts.filter((v) => v !== null));
+    if (!vals.length)
+        return null;
+    let ymin = spec.ymin ?? Math.min(...vals);
+    let ymax = spec.ymax ?? Math.max(...vals);
+    if (ymax - ymin < 1e-9)
+        (ymin -= 1), (ymax += 1);
+    if (spec.ymin === undefined)
+        ymin -= (ymax - ymin) * 0.06;
+    if (spec.ymax === undefined)
+        ymax += (ymax - ymin) * 0.06;
+    const px = (x) => L + ((x - spec.xmin) / (spec.xmax - spec.xmin)) * (W - L - R);
+    const py = (y) => H - B - ((y - ymin) / (ymax - ymin)) * (H - T - B);
+    const out = [`<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 ${W} ${H}" font-family="Helvetica, Arial, sans-serif" font-size="12">`, '<rect width="100%" height="100%" fill="#ffffff"/>'];
+    const xstep = niceStep(spec.xmax - spec.xmin);
+    for (let v = Math.ceil(spec.xmin / xstep) * xstep; v <= spec.xmax + 1e-9; v += xstep)
+        out.push(`<line x1="${px(v)}" y1="${T}" x2="${px(v)}" y2="${H - B}" stroke="#e6e6ee"/><text x="${px(v)}" y="${H - B + 16}" text-anchor="middle" fill="#555">${fmt(v)}</text>`);
+    const ystep = niceStep(ymax - ymin);
+    for (let v = Math.ceil(ymin / ystep) * ystep; v <= ymax + 1e-9; v += ystep)
+        out.push(`<line x1="${L}" y1="${py(v)}" x2="${W - R}" y2="${py(v)}" stroke="#e6e6ee"/><text x="${L - 8}" y="${py(v) + 4}" text-anchor="end" fill="#555">${fmt(v)}</text>`);
+    if (ymin < 0 && ymax > 0)
+        out.push(`<line x1="${L}" y1="${py(0)}" x2="${W - R}" y2="${py(0)}" stroke="#888"/>`);
+    if (spec.xmin < 0 && spec.xmax > 0)
+        out.push(`<line x1="${px(0)}" y1="${T}" x2="${px(0)}" y2="${H - B}" stroke="#888"/>`);
+    out.push(`<rect x="${L}" y="${T}" width="${W - L - R}" height="${H - T - B}" fill="none" stroke="#999"/>`);
+    curves.forEach((c, k) => {
+        let d = "";
+        let pen = false;
+        c.pts.forEach((v, i) => {
+            if (v === null || v < ymin - (ymax - ymin) || v > ymax + (ymax - ymin))
+                return void (pen = false);
+            d += `${pen ? "L" : "M"}${px(xs[i]).toFixed(1)},${py(v).toFixed(1)}`;
+            pen = true;
+        });
+        out.push(`<path d="${d}" fill="none" stroke="${COLORS[k % COLORS.length]}" stroke-width="2.4" stroke-linejoin="round"/>`);
+    });
+    if (spec.title)
+        out.push(`<text x="${W / 2}" y="24" text-anchor="middle" font-size="15" font-weight="bold" fill="#222">${esc(spec.title)}</text>`);
+    if (spec.xlabel)
+        out.push(`<text x="${(L + W - R) / 2}" y="${H - 12}" text-anchor="middle" fill="#333">${esc(spec.xlabel)}</text>`);
+    if (spec.ylabel)
+        out.push(`<text transform="translate(16 ${(T + H - B) / 2}) rotate(-90)" text-anchor="middle" fill="#333">${esc(spec.ylabel)}</text>`);
+    if (curves.length > 1 || spec.series[0].label)
+        curves.forEach((c, k) => out.push(`<rect x="${W - R - 150}" y="${T + 8 + k * 18}" width="12" height="4" fill="${COLORS[k % COLORS.length]}"/><text x="${W - R - 132}" y="${T + 14 + k * 18}" fill="#333">${esc(c.label)}</text>`));
+    out.push("</svg>");
+    return out.join("");
+}
+export function renderPlot(src) {
+    const spec = parsePlot(src);
+    const svg = spec && plotToSvg(spec);
+    if (!spec || !svg)
+        return null;
+    return { svg, raster: svgToPng(svg, 2), caption: spec.title ?? "plot" };
+}
+const BRAILLE = [[0x01, 0x08], [0x02, 0x10], [0x04, 0x20], [0x40, 0x80]];
+const CURVE_ANSI = [75, 203, 114, 176, 208];
+/** Plot as braille dots (2x4 per cell): decent line art in any Unicode terminal. */
+export function plotToBraille(spec, cols = 64, rows = 14, color = true) {
+    const Wd = cols * 2, Hd = rows * 4;
+    const curves = spec.series.slice(0, 5).map((s) => {
+        try {
+            const f = compile(s.expr.replace(/^\s*(?:y|f\(x\))\s*=\s*/, ""));
+            return Array.from({ length: Wd }, (_, i) => {
+                const v = f.evaluate({ x: spec.xmin + ((spec.xmax - spec.xmin) * i) / (Wd - 1), pi: Math.PI, e: Math.E });
+                return typeof v === "number" && Number.isFinite(v) ? v : null;
+            });
+        }
+        catch {
+            return null;
+        }
+    });
+    if (curves.some((c) => c === null))
+        return null;
+    const vals = curves.flat().filter((v) => v !== null);
+    if (!vals.length)
+        return null;
+    let ymin = spec.ymin ?? Math.min(...vals), ymax = spec.ymax ?? Math.max(...vals);
+    if (ymax - ymin < 1e-9)
+        (ymin -= 1), (ymax += 1);
+    const dots = new Map();
+    const plot = (x, y, k) => {
+        if (x < 0 || x >= Wd || y < 0 || y >= Hd)
+            return;
+        const key = Math.floor(y / 4) * cols + Math.floor(x / 2);
+        const cur = dots.get(key) ?? { mask: 0, series: k };
+        cur.mask |= BRAILLE[y % 4][x % 2];
+        dots.set(key, cur);
+    };
+    curves.forEach((c, k) => {
+        let prev = null;
+        c.forEach((v, x) => {
+            if (v === null)
+                return void (prev = null);
+            const y = Math.round((1 - (v - ymin) / (ymax - ymin)) * (Hd - 1));
+            const from = prev ?? y;
+            for (let yy = Math.min(from, y); yy <= Math.max(from, y); yy++)
+                plot(x, yy, k);
+            prev = y;
+        });
+    });
+    const paint = (s, k) => (color ? `\x1b[38;5;${CURVE_ANSI[k % CURVE_ANSI.length]}m${s}\x1b[39m` : s);
+    const lab = (v) => fmt(v).padStart(7);
+    const lines = [];
+    if (spec.title)
+        lines.push(" ".repeat(8) + spec.title);
+    for (let r = 0; r < rows; r++) {
+        let row = "";
+        for (let c = 0; c < cols; c++) {
+            const d = dots.get(r * cols + c);
+            row += d ? paint(String.fromCharCode(0x2800 + d.mask), d.series) : " ";
+        }
+        lines.push((r === 0 ? lab(ymax) : r === rows - 1 ? lab(ymin) : r === Math.floor(rows / 2) ? lab((ymin + ymax) / 2) : " ".repeat(7)) + " │" + row);
+    }
+    lines.push(" ".repeat(8) + "└" + "─".repeat(cols));
+    lines.push(" ".repeat(9) + fmt(spec.xmin) + " ".repeat(Math.max(1, cols - fmt(spec.xmin).length - fmt(spec.xmax).length)) + fmt(spec.xmax) + (spec.xlabel ? `   ${spec.xlabel}` : ""));
+    if (spec.series.length > 1 || spec.series[0].label)
+        lines.push(" ".repeat(9) + spec.series.slice(0, 5).map((s, k) => paint("━ " + (s.label ?? s.expr), k)).join("   "));
+    return lines;
+}