learn-loops 0.1.0 → 0.4.0

package/dist/markdown.js

@@ -1,8 +1,9 @@
-import { join } from "node:path";
+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. */
-const clean = (s) => s.replace(/["'`()\[\]{}:;#<>]/g, "").replace(/\s+/g, " ").trim();
-const nodeId = (s) => "n_" + s.replace(/[^a-zA-Z0-9]/g, "_");
+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)
@@ -41,19 +42,26 @@ ${flow}
 ${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, own, missed) {
+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 ownBlock = own?.length
-        ? `\n## In my own words\n\n> ${lesson.teachBack}\n\n${own
-            .map((o, i) => `**Attempt ${i + 1}** — ${o.grade.score}/3\n\n${o.answer.split("\n").map((l) => "> " + l).join("\n")}\n\n${o.grade.feedback}${o.grade.missing.length ? `\n\nMissing: ${o.grade.missing.join("; ")}` : ""}`)
-            .join("\n\n")}\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")}
@@ -61,15 +69,26 @@ ${lesson.keyPoints.map((k) => `- ${k}`).join("\n")}
 ## Check yourself
 
 ${checks}
-${missed?.length ? `\n**Still shaky:** ${missed.join("; ")}\n` : ""}${ownBlock}
+${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)", ""];
+    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) {
@@ -83,3 +102,35 @@ export async function writeIndex(topic) {
     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)));
+}

package/dist/prompts.js

@@ -3,10 +3,23 @@ export function learnerBlurb(p) {
         `Learner: ${p.name}. Goal: ${p.goal}. Level: ${p.level}.`,
         `Likes: ${p.styles.join(", ") || "no strong preference"}. Prefers ${p.order.replace(/-/g, " ")} ordering.`,
         `Diagram appetite: ${p.diagrams}. Challenge: ${p.challenge}. Feedback tone: ${p.tone}.`,
-    ].join(" ");
+        p.context ? `They are working on / will use this for: ${p.context}.` : "",
+    ]
+        .filter(Boolean)
+        .join(" ");
+}
+/** Topic-specific personalisation: where they said they'd use it, and their own connections so far. */
+export function useBlurb(s) {
+    const bits = [s.useCase ? `For this topic they want to use it for: ${s.useCase}.` : "", s.connections?.length ? `Uses they have named so far: ${s.connections.slice(-3).join(" | ")}. Draw examples from these when natural.` : ""];
+    return bits.filter(Boolean).join(" ");
 }
 const MERMAID_RULES = `Mermaid rules (diagrams MUST render): use only flowchart TD/LR, sequenceDiagram, stateDiagram-v2, classDiagram, or mindmap.
-Always wrap flowchart node labels in double quotes, e.g. A["Label text"]. Never put parentheses, quotes or colons inside unquoted labels. Keep diagrams under 12 nodes. Fence them as \`\`\`mermaid.`;
+Always wrap flowchart node labels in double quotes, e.g. A["Label text"]. Never put parentheses, quotes or colons inside unquoted labels. Diagrams are drawn in a terminal about 100 columns wide: prefer flowchart/sequenceDiagram/stateDiagram-v2/classDiagram, keep labels to 1-4 words, and keep diagrams under 10 nodes. Fence them as \`\`\`mermaid.`;
+const STEM_RULES = `Math and science content:
+- Write equations in LaTeX: $...$ inline and $$...$$ for display. The physics, ams, mhchem and cancel packages work (\\ket{}, \\pdv{f}{x}, \\vb{E}, \\ce{2H2 + O2 -> 2H2O}). Inside the JSON, double every backslash (write \\\\frac).
+- Physical or geometric setups (free-body diagrams, circuits, ray/optics diagrams, fields, waves, geometry) go in a fenced svg block holding one complete <svg viewBox='0 0 640 360'>. Use SINGLE quotes for every attribute, include a <title>, dark strokes on a transparent background, labelled parts via <text>, arrowheads via <marker>, and no scripts, images or external references. Keep it uncluttered and physically correct.
+- Graphs of functions (waveforms, potentials, distributions, trade-off curves) go in a fenced plot block holding JSON: {"title":"...","xlabel":"...","ylabel":"...","xmin":0,"xmax":10,"series":[{"label":"...","expr":"exp(-0.3*x)*cos(3*x)"}]}. The expr is a mathjs expression in x (use *, ^, sin, cos, exp, sqrt, pi), never LaTeX.
+- Use mermaid only for processes, hierarchies and state/flow structure. Add equations or figures only where they genuinely clarify; never decorate.`;
 const diagramRule = (p) => p.diagrams === "lots" ? "Include 1-2 mermaid diagrams." : p.diagrams === "some" ? "Include one mermaid diagram if it genuinely helps." : "Only include a diagram if essential.";
 export function mapPrompt(p, topic, prior) {
     return `${learnerBlurb(p)}
@@ -16,18 +29,24 @@ Return ONLY JSON:
 {"overview":"2-3 sentence orientation: what this field is and why it matters",
  "areas":[{"id":"short-kebab-id","title":"...","summary":"1-2 sentences","prereqs":["ids of areas that should come first"],"concepts":[{"name":"...","blurb":"one line"}]}]}`;
 }
-const lessonShape = `{"primer":"one open question that makes the learner GUESS before reading (no jargon they haven't seen)",
+const lessonShapeBase = `{"primer":"one open question that makes the learner GUESS before reading (no jargon they haven't seen)",
  "markdown":"the lesson body in markdown",
  "checks":[{"q":"...","options":["A","B","C","D"],"answer":0,"explain":"why the answer is right and the best distractor is wrong"}],
  "teachBack":"a prompt asking the learner to explain the idea in their own words, ideally to a specific imagined person or via a small scenario",
  "keyPoints":["3-5 points a correct own-words explanation should contain"],
- "cards":[{"front":"recall question","back":"concise answer"}]}`;
+ "cards":[{"front":"recall question","back":"concise answer"}]`;
+const lessonShape = `${lessonShapeBase}}`;
+const deepExtras = (socratic) => `,
+ "prediction":{"scenario":"a concrete situation in 2-3 sentences, stopping just before the outcome","question":"what do you expect happens next / what would you do?","outcome":"what actually happens and why, 2-3 sentences"},
+ "deeper":{"question":"an open question that forces thinking about TRADE-OFFS, failure modes, scale, or second-order effects (not recall)","considerations":["4-5 things a thoughtful answer would raise"]}${socratic ? `,
+ "socratic":[{"q":"a leading question the learner can partly answer from what they already know","hint":"a nudge if they are stuck","idea":"the insight the question points to"}]  /* exactly 3, ordered so each builds on the last */` : ""}}`;
 export function surveyLessonPrompt(p, s, area) {
     return `${learnerBlurb(p)}
-Topic: "${s.title}". This is the BROAD SURVEY pass: give the learner the basic idea of the area "${area.title}" (${area.summary}).
+Topic: "${s.title}". ${useBlurb(s)} This is the BROAD SURVEY pass: give the learner the basic idea of the area "${area.title}" (${area.summary}).
 Concepts to touch: ${area.concepts.map((c) => c.name).join(", ")}.
 Rules: max ~250 words in markdown. ${p.order === "examples-first" ? "Open with a concrete example, then name the idea." : p.order === "theory-first" ? "State the core principle first, then illustrate." : "Open with where it fits in the whole field, then the idea, then an example."}
 Use the learner's preferred styles (${p.styles.join(", ") || "any"}). ${diagramRule(p)} ${MERMAID_RULES}
+${STEM_RULES}
 Exactly 2 multiple-choice checks (4 options each, "answer" is the 0-based index, plausible distractors based on real misconceptions; vary the position of the right answer). 2-3 flashcards.
 Return ONLY JSON of this shape:
 ${lessonShape}`;
@@ -40,17 +59,20 @@ Return ONLY JSON: {"lessons":[{"id":"short-kebab-id","title":"...","objective":"
 }
 export function deepLessonPrompt(p, s, area, lesson, doneTitles) {
     return `${learnerBlurb(p)}
-Topic: "${s.title}", area "${area.title}". DEEP lesson: "${lesson.title}" — objective: ${lesson.objective}.
+Topic: "${s.title}", area "${area.title}". ${useBlurb(s)} DEEP lesson: "${lesson.title}" — objective: ${lesson.objective}.
 Already covered in this area: ${doneTitles.join("; ") || "nothing yet"}. Build on that; connect back to it explicitly.
 Rules: 400-650 words of markdown with ## subheadings. ${p.order === "examples-first" ? "Start from a worked example, then abstract." : p.order === "theory-first" ? "Start from first principles, then apply." : "Start from the big picture, zoom in, then work an example."}
-Include a worked example, one common misconception to avoid, and ${p.diagrams === "minimal" ? "at least one" : "1-2"} mermaid diagram(s) showing the real mechanism/structure (not decoration). ${MERMAID_RULES}
+Include a worked example, one common misconception to avoid, and ${p.diagrams === "minimal" ? "at least one" : "1-2"} figure(s) (mermaid, svg or plot as fits the subject) showing the real mechanism/structure (not decoration). ${MERMAID_RULES}
+${STEM_RULES}
 Challenge level: ${p.challenge}. Exactly ${p.challenge === "tough" ? 4 : 3} multiple-choice checks that test understanding/application, not trivia (4 options, "answer" is 0-based). 3-4 flashcards phrased as recall questions.
-Return ONLY JSON of this shape:
-${lessonShape}`;
+${p.socratic ? "The learner prefers a SOCRATIC style: the markdown is the consolidation shown AFTER they work through your leading questions, so it should name and tie together the ideas those questions lead to." : ""}
+Also include the "prediction" (a situation where a wrong intuition is likely, so they learn from guessing wrong), the "deeper" trade-off question${p.socratic ? ", and exactly 3 \"socratic\" questions" : ""}.
+Return ONLY JSON of this shape (omit the /* */ comment):
+${lessonShapeBase}${deepExtras(!!p.socratic)}`;
 }
 export function reexplainPrompt(p, topic, lessonTitle, original) {
     return `${learnerBlurb(p)}
-The learner is stuck on "${lessonTitle}" (topic: ${topic}). Re-explain the SAME idea differently: new analogy, simpler words, different example. Do not repeat the original framing. Max 200 words, markdown, optionally one mermaid diagram. ${MERMAID_RULES}
+The learner is stuck on "${lessonTitle}" (topic: ${topic}). Re-explain the SAME idea differently: new analogy, simpler words, different example. Do not repeat the original framing. Max 200 words, markdown, optionally one figure or equation. ${MERMAID_RULES}\n${STEM_RULES.replace(/Inside the JSON, double every backslash \(write \\\\frac\)\./, '')}
 Original explanation for reference:
 ${original}
 Return only the markdown.`;
@@ -71,3 +93,57 @@ export function bigPicturePrompt(s) {
     };
 }
 export const gradeLabel = (g) => ["Not yet", "Getting there", "Mostly there", "Solid"][g.score];
+export const PERSONAS = [
+    { label: "a curious 12-year-old", voice: "asks 'but why?', gets lost at jargon, loves concrete pictures" },
+    { label: "a skeptical expert from a neighbouring field", voice: "challenges hand-waving, asks for precision, probes edge cases" },
+    { label: "a new teammate on their first day", voice: "practical: asks how it applies in real work and what to watch out for" },
+    { label: "a smart friend who has never heard of this", voice: "bright but zero background; spots any step that was skipped" },
+];
+export function personaPrompt(p, persona, title, keyPoints, answer) {
+    return `Role-play ${persona.label} (${persona.voice}) who just heard the learner explain "${title}". Their explanation: """${answer}"""
+A complete explanation would cover: ${keyPoints.join("; ")}.
+React in character in 1-2 sentences (say honestly what confused you or what clicked), then ask ONE follow-up question aimed at the biggest gap or shaky claim in what they said. Stay in character; never reveal the answer.
+Return ONLY JSON: {"reaction":"...","question":"..."}`;
+}
+export function diagnoseQuestionsPrompt(p, title, missed, explanation) {
+    return `${learnerBlurb(p)}
+The learner struggled with "${title}". They missed: ${missed.map((m) => `"${m}"`).join("; ") || "none (their own-words explanation was weak)"}. ${explanation ? `Feedback on their explanation: ${explanation}` : ""}
+Write exactly 2 short diagnostic questions (not quiz questions) that reveal WHAT mental model they hold, e.g. "what do you picture happens when ...?". Do not teach yet.
+Return ONLY JSON: {"questions":["...","..."]}`;
+}
+export function diagnoseResultPrompt(p, title, qa, missed) {
+    return `${learnerBlurb(p)}
+Lesson "${title}". Missed questions: ${missed.join("; ") || "n/a"}.
+Diagnostic Q&A:
+${qa.map((x) => `Q: ${x.q}\nA: ${x.a || "(no answer)"}`).join("\n")}
+Identify the single most likely misconception or gap, re-teach exactly that with a NEW angle (max 150 words, markdown, optional tiny mermaid), and write one fresh multiple-choice check that would fail if the misconception persists (4 options, "answer" 0-based index).
+Return ONLY JSON: {"misconception":"one sentence","reteach":"markdown","retest":{"q":"...","options":["","","",""],"answer":0,"explain":"..."}}`;
+}
+export const LENSES = [
+    { id: "tradeoffs", label: "Trade-offs", ask: "what is given up by this approach, and under what conditions would the alternative win?" },
+    { id: "failure", label: "What could go wrong", ask: "how could this fail or be misused, and what early warning signs would show it?" },
+    { id: "scale", label: "Scale & time", ask: "what changes if this grows 100x or has to last 10 years?" },
+    { id: "second-order", label: "Second-order effects", ask: "what knock-on effects follow that nobody planned for?" },
+    { id: "inversion", label: "Invert it", ask: "if you wanted this to fail on purpose, or the opposite assumption held, what would happen?" },
+    { id: "edge", label: "Edge cases", ask: "which unusual situations break the neat explanation?" },
+];
+export function deeperPrompt(p, s, title, lens, earlier) {
+    return `${learnerBlurb(p)} ${useBlurb(s)}
+Topic "${s.title}", lesson "${title}". Pose ONE open-ended "think deeper" question through the lens "${lens.label}": ${lens.ask}
+Make it concrete (a specific situation, not abstract). Do not repeat earlier questions: ${earlier.join(" | ") || "none"}.
+Return ONLY JSON: {"question":"...","considerations":["4-5 things a thoughtful answer would raise"]}`;
+}
+export function critiquePrompt(p, title, question, considerations, answer) {
+    const tone = { encouraging: "warm and specific", direct: "blunt and efficient", socratic: "mostly questions" }[p.tone];
+    return `The learner is thinking beyond the basics on "${title}". Question: "${question}"
+A thoughtful answer would raise: ${considerations.map((c) => `- ${c}`).join("\n")}
+Learner's answer: """${answer}"""
+Judge reasoning quality, not length: did they weigh both sides, name concrete risks, and notice second-order effects? Credit valid points that are NOT in the list. Be ${tone}.
+Return ONLY JSON: {"strong":["good points they made"],"blindSpots":["important angles they did not consider, each with one sentence of why it matters"],"pushback":"one hard follow-up that challenges their weakest assumption","feedback":"2 sentences"}`;
+}
+export function challengePrompt(p, s, area, covered) {
+    return `${learnerBlurb(p)} ${useBlurb(s)}
+The learner just finished a deep dive into "${area.title}" (topic "${s.title}"), covering: ${covered.join("; ")}.
+Write ONE realistic application challenge: a specific scenario with constraints and a decision to make, where there is no single right answer and the learner must weigh trade-offs and anticipate what could go wrong. Make it ${p.challenge === "tough" ? "hard and ambiguous" : p.challenge === "gentle" ? "approachable" : "moderately demanding"}.
+Return ONLY JSON: {"scenario":"3-5 sentences","task":"what they must decide or design, and justify","considerations":["5-6 things a strong answer weighs"]}`;
+}

package/dist/stats.js

@@ -0,0 +1,48 @@
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import { configDir } from "./store.js";
+const statsPath = () => join(configDir(), "stats.json");
+export const dayKey = (d = new Date()) => d.toLocaleDateString("en-CA");
+const yesterdayKey = (d = new Date()) => dayKey(new Date(d.getFullYear(), d.getMonth(), d.getDate() - 1));
+export async function loadStats() {
+    try {
+        return { streak: 0, longest: 0, lastDay: "", totalDays: 0, ...JSON.parse(await readFile(statsPath(), "utf8")) };
+    }
+    catch {
+        return { streak: 0, longest: 0, lastDay: "", totalDays: 0 };
+    }
+}
+export async function saveStats(s) {
+    await mkdir(configDir(), { recursive: true });
+    await writeFile(statsPath(), JSON.stringify(s, null, 2));
+}
+/** The streak you could still lose: alive if you studied today or yesterday. */
+export function currentStreak(s, now = new Date()) {
+    return s.lastDay === dayKey(now) || s.lastDay === yesterdayKey(now) ? s.streak : 0;
+}
+export const doneToday = (s, now = new Date()) => s.lastDay === dayKey(now);
+/** Pure update; returns the new stats and whether today's activity just extended the streak. */
+export function applyActivity(s, now = new Date()) {
+    const today = dayKey(now);
+    if (s.lastDay === today)
+        return { stats: s, extended: false };
+    const streak = s.lastDay === yesterdayKey(now) ? s.streak + 1 : 1;
+    return { stats: { ...s, streak, longest: Math.max(s.longest, streak), lastDay: today, totalDays: s.totalDays + 1 }, extended: true };
+}
+export async function recordActivity(now = new Date()) {
+    const { stats, extended } = applyActivity(await loadStats(), now);
+    if (extended)
+        await saveStats(stats);
+    const milestone = [3, 7, 14, 30, 60, 100].includes(stats.streak);
+    const message = extended
+        ? stats.streak === 1
+            ? "Day 1 done. Come back tomorrow to start a streak."
+            : `${stats.streak}-day streak!${milestone ? " That's a real habit forming." : ""}${stats.streak === stats.longest && stats.streak > 1 ? " Personal best." : ""}`
+        : undefined;
+    return { stats, extended, message };
+}
+export async function saveCheckin(s, energy, minutes) {
+    const next = { ...s, checkin: { day: dayKey(), energy, minutes } };
+    await saveStats(next);
+    return next;
+}

package/dist/store.js

@@ -73,8 +73,16 @@ export async function createTopic(profile, title, category, priorKnowledge) {
         progress: {},
         bigPictureDone: false,
         cards: [],
+        mistakes: [],
+        connections: [],
     };
     const topic = { dir, state };
     await saveTopic(topic);
     return topic;
 }
+export function addMistake(topic, m) {
+    const list = (topic.state.mistakes ??= []);
+    if (list.some((x) => x.lesson === m.lesson && x.what === m.what))
+        return;
+    list.push({ date: new Date().toISOString().slice(0, 10), ...m });
+}