learn-loops 0.0.0-stage → 0.4.1

package/dist/prompts.js

@@ -0,0 +1,149 @@
+export function learnerBlurb(p) {
+    return [
+        `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}.`,
+        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. 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)}
+Create a map of the whole territory of "${topic}" for this learner. Their stated prior knowledge: ${prior || "none stated"}.
+Cover the field broadly: 5-9 areas, ordered so earlier areas support later ones. Each area has 3-6 concepts.
+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 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"}]`;
+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}". ${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}`;
+}
+export function outlinePrompt(p, s, area) {
+    return `${learnerBlurb(p)}
+Topic: "${s.title}". Plan a DEEP DIVE into "${area.title}" (${area.summary}); concepts: ${area.concepts.map((c) => c.name).join(", ")}.
+Design 4-7 lessons that build on each other (simple -> complex, each introduces ONE main idea), ending with a lesson that integrates everything in a realistic scenario.
+Return ONLY JSON: {"lessons":[{"id":"short-kebab-id","title":"...","objective":"By the end you can ..."}]}`;
+}
+export function deepLessonPrompt(p, s, area, lesson, doneTitles) {
+    return `${learnerBlurb(p)}
+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"} 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.
+${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 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.`;
+}
+export function gradePrompt(p, lessonTitle, prompt, keyPoints, answer) {
+    const tone = { encouraging: "warm and specific", direct: "blunt and efficient", socratic: "mostly questions that lead them to see gaps themselves" }[p.tone];
+    return `Grade a learner's own-words explanation. Lesson: "${lessonTitle}". Prompt given: "${prompt}".
+A strong answer includes: ${keyPoints.map((k) => `- ${k}`).join("\n")}
+Learner's answer: """${answer}"""
+Be ${tone}. Judge understanding, not wording; reward correct paraphrase, penalise parroting and errors. score: 0 = off/blank, 1 = fragments, 2 = mostly right with gaps, 3 = solid.
+Return ONLY JSON: {"score":0-3,"right":["what they got right"],"missing":["key ideas absent"],"misconceptions":["things they said that are wrong, with the correction"],"feedback":"2-3 sentences","followUp":"one probing question that would deepen their understanding"}`;
+}
+export function bigPicturePrompt(s) {
+    const areas = s.map.areas;
+    return {
+        prompt: `Without looking back: how do the main areas of ${s.title} (${areas.map((a) => a.title).join(", ")}) fit together? Explain it as if briefing a smart friend.`,
+        keyPoints: areas.map((a) => `${a.title}: ${a.summary}`),
+    };
+}
+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/srs.js

@@ -0,0 +1,50 @@
+const DAY = 86_400_000;
+export function newCard(front, back, source, now = new Date()) {
+    return {
+        id: Math.random().toString(36).slice(2, 10),
+        front,
+        back,
+        source,
+        ease: 2.5,
+        interval: 0,
+        reps: 0,
+        lapses: 0,
+        due: now.toISOString(),
+    };
+}
+/** Simplified SM-2: failed cards come back soon, successful ones expand the gap. */
+export function schedule(card, rating, now = new Date()) {
+    const c = { ...card };
+    if (rating === "again") {
+        c.lapses++;
+        c.reps = 0;
+        c.ease = Math.max(1.3, c.ease - 0.2);
+        c.interval = 0;
+        c.due = new Date(now.getTime() + 10 * 60_000).toISOString();
+        return c;
+    }
+    c.reps++;
+    if (rating === "hard")
+        c.ease = Math.max(1.3, c.ease - 0.15);
+    if (rating === "easy")
+        c.ease += 0.15;
+    if (c.reps === 1)
+        c.interval = rating === "easy" ? 3 : 1;
+    else if (c.reps === 2)
+        c.interval = rating === "hard" ? 2 : 4;
+    else
+        c.interval = Math.max(1, Math.round(c.interval * (rating === "hard" ? 1.2 : rating === "easy" ? c.ease * 1.3 : c.ease)));
+    c.due = new Date(now.getTime() + c.interval * DAY).toISOString();
+    return c;
+}
+export const isDue = (c, now = new Date()) => new Date(c.due).getTime() <= now.getTime();
+export function addCards(existing, fresh, source) {
+    let added = 0;
+    for (const f of fresh) {
+        if (existing.some((c) => c.front.trim().toLowerCase() === f.front.trim().toLowerCase()))
+            continue;
+        existing.push(newCard(f.front, f.back, source));
+        added++;
+    }
+    return added;
+}

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

@@ -0,0 +1,88 @@
+import { mkdir, readFile, writeFile, readdir } from "node:fs/promises";
+import { existsSync } from "node:fs";
+import { homedir } from "node:os";
+import { join, dirname } from "node:path";
+export const configDir = () => process.env.LOOPS_HOME ?? join(homedir(), ".config", "loops");
+const profilePath = () => join(configDir(), "profile.json");
+export const slugify = (s) => s
+    .toLowerCase()
+    .normalize("NFKD")
+    .replace(/[^a-z0-9]+/g, "-")
+    .replace(/^-+|-+$/g, "")
+    .slice(0, 48) || "untitled";
+export const expandHome = (p) => (p.startsWith("~") ? join(homedir(), p.slice(1)) : p);
+export async function loadProfile() {
+    try {
+        return JSON.parse(await readFile(profilePath(), "utf8"));
+    }
+    catch {
+        return null;
+    }
+}
+export async function saveProfile(profile) {
+    await mkdir(configDir(), { recursive: true });
+    await writeFile(profilePath(), JSON.stringify(profile, null, 2));
+}
+export async function writeText(path, content) {
+    await mkdir(dirname(path), { recursive: true });
+    await writeFile(path, content);
+}
+export async function saveTopic(topic) {
+    await writeText(join(topic.dir, "topic.json"), JSON.stringify(topic.state, null, 2));
+}
+/** Topics live at <root>/<category>/<slug>/topic.json. */
+export async function listTopics(profile) {
+    const root = expandHome(profile.rootDir);
+    if (!existsSync(root))
+        return [];
+    const topics = [];
+    for (const cat of await readdir(root, { withFileTypes: true })) {
+        if (!cat.isDirectory())
+            continue;
+        for (const sub of await readdir(join(root, cat.name), { withFileTypes: true })) {
+            const file = join(root, cat.name, sub.name, "topic.json");
+            if (!sub.isDirectory() || !existsSync(file))
+                continue;
+            try {
+                topics.push({ dir: join(root, cat.name, sub.name), state: JSON.parse(await readFile(file, "utf8")) });
+            }
+            catch {
+                /* skip unreadable topic */
+            }
+        }
+    }
+    return topics.sort((a, b) => lastTouched(b).localeCompare(lastTouched(a)));
+}
+const lastTouched = (t) => t.state.cards.map((c) => c.due).sort().pop() ?? t.state.createdAt;
+export async function listCategories(profile) {
+    const root = expandHome(profile.rootDir);
+    if (!existsSync(root))
+        return [];
+    return (await readdir(root, { withFileTypes: true })).filter((d) => d.isDirectory()).map((d) => d.name);
+}
+export async function createTopic(profile, title, category, priorKnowledge) {
+    const slug = slugify(title);
+    const dir = join(expandHome(profile.rootDir), slugify(category), slug);
+    const state = {
+        title,
+        slug,
+        category: slugify(category),
+        createdAt: new Date().toISOString(),
+        priorKnowledge,
+        phase: "map",
+        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 });
+}

package/dist/termimg.js

@@ -0,0 +1,27 @@
+export function imageProtocol(env = process.env, isTTY = !!process.stdout.isTTY) {
+    if (env.LOOPS_IMAGES === "off")
+        return null;
+    if (env.LOOPS_IMAGES === "iterm" || env.LOOPS_IMAGES === "kitty")
+        return env.LOOPS_IMAGES; // forced
+    if (!isTTY)
+        return null;
+    if (env.TMUX)
+        return null; // needs passthrough; not worth the risk of garbage output
+    if (env.KITTY_WINDOW_ID || env.TERM === "xterm-kitty" || env.TERM_PROGRAM === "ghostty")
+        return "kitty";
+    if (["iTerm.app", "WezTerm", "vscode"].includes(env.TERM_PROGRAM ?? ""))
+        return "iterm";
+    return null;
+}
+/** Escape sequence that draws `png` about `cells` columns wide. */
+export function drawImage(png, cells, protocol) {
+    const b64 = png.toString("base64");
+    if (protocol === "iterm")
+        return `\x1b]1337;File=inline=1;width=${cells};preserveAspectRatio=1:${b64}\x07`;
+    const chunks = [];
+    for (let i = 0; i < b64.length; i += 4096) {
+        const more = i + 4096 < b64.length ? 1 : 0;
+        chunks.push(`\x1b_G${i === 0 ? `a=T,f=100,c=${cells},` : ""}m=${more};${b64.slice(i, i + 4096)}\x1b\\`);
+    }
+    return chunks.join("");
+}

package/dist/types.js

@@ -0,0 +1 @@
+export {};

package/dist/ui.js

@@ -0,0 +1,185 @@
+import * as p from "@clack/prompts";
+import pc from "picocolors";
+import { renderDiagram } from "./diagram.js";
+import { parsePlot, plotToBraille, renderPlot, sanitizeSvg, svgCaption } from "./figures.js";
+import { mathToText, svgToPng, texToLines, texToPng } from "./math.js";
+import { drawImage, imageProtocol } from "./termimg.js";
+const useColor = !!process.stdout.isTTY && !process.env.NO_COLOR;
+const c256 = (n) => (s) => (useColor ? `\x1b[38;5;${n}m${s}\x1b[39m` : s);
+export const t = {
+    accent: c256(141),
+    pink: c256(213),
+    cyan: c256(87),
+    ok: c256(78),
+    warn: c256(215),
+    bad: c256(203),
+    dim: pc.dim,
+    bold: pc.bold,
+    italic: pc.italic,
+};
+const LOGO = [
+    "  ██╗      ██████╗  ██████╗ ██████╗ ███████╗",
+    "  ██║     ██╔═══██╗██╔═══██╗██╔══██╗██╔════╝",
+    "  ██║     ██║   ██║██║   ██║██████╔╝███████╗",
+    "  ██║     ██║   ██║██║   ██║██╔═══╝ ╚════██║",
+    "  ███████╗╚██████╔╝╚██████╔╝██║     ███████║",
+    "  ╚══════╝ ╚═════╝  ╚═════╝ ╚═╝     ╚══════╝",
+];
+const GRADIENT = [93, 99, 105, 141, 177, 213];
+export function banner(subtitle = "learn anything, properly") {
+    console.log();
+    LOGO.forEach((line, i) => console.log(c256(GRADIENT[i])(line)));
+    console.log(t.dim(`  ${subtitle}\n`));
+}
+/** Unwrap a clack prompt result; exit cleanly on Ctrl+C. */
+export function must(value) {
+    if (p.isCancel(value)) {
+        p.cancel("Progress saved. See you next time ✦");
+        process.exit(0);
+    }
+    return value;
+}
+export async function withSpinner(label, fn) {
+    const s = p.spinner();
+    s.start(label);
+    try {
+        const r = await fn();
+        s.stop(t.ok("✓ ") + label.replace(/\.\.\.$/, ""));
+        return r;
+    }
+    catch (e) {
+        s.stop(t.bad("✗ ") + label);
+        throw e;
+    }
+}
+export function bar(done, total, width = 20) {
+    const filled = total === 0 ? 0 : Math.round((done / total) * width);
+    return t.accent("█".repeat(filled)) + t.dim("░".repeat(width - filled)) + t.dim(` ${done}/${total}`);
+}
+let tipShown = false;
+/** Draw a raster inline if the terminal can; returns null otherwise. */
+function inlineImage(r, maxCells) {
+    const proto = imageProtocol();
+    if (!proto)
+        return null;
+    const cols = process.stdout.columns ?? 100;
+    const cells = Math.max(8, Math.min(Math.ceil(r.width / 8), maxCells, cols - 4));
+    return "  " + drawImage(r.png, cells, proto);
+}
+function figureNote(what, caption) {
+    const lines = ["  " + t.pink(`◆ ${what}`) + (caption ? t.dim(` — ${caption}`) : "") + t.dim("  (saved in the lesson's markdown file)")];
+    if (!tipShown) {
+        tipShown = true;
+        lines.push("  " + t.dim("tip: iTerm2, WezTerm, Kitty and Ghostty draw figures inline; elsewhere open the .md file"));
+    }
+    return lines;
+}
+function renderEquation(tex) {
+    try {
+        const img = imageProtocol() ? inlineImage(texToPng(tex, true), 60) : null;
+        if (img)
+            return ["", img, ""];
+        return ["", ...texToLines(tex).map((l) => "    " + t.cyan(l)), ""];
+    }
+    catch {
+        return ["", "    " + t.dim(tex.trim()), ""];
+    }
+}
+function renderFigure(kind, src) {
+    if (kind === "plot") {
+        const p = renderPlot(src);
+        if (!p)
+            return figureNote("plot", "couldn't be drawn");
+        const img = imageProtocol() ? inlineImage(p.raster, 70) : null;
+        if (img)
+            return ["", img, ""];
+        const braille = plotToBraille(parsePlot(src), Math.min(64, (process.stdout.columns ?? 100) - 14), 14, useColor);
+        return braille ? ["", ...braille.map((l) => "  " + l), ""] : figureNote("plot", p.caption);
+    }
+    const svg = sanitizeSvg(src);
+    if (!svg)
+        return figureNote("figure", "couldn't be drawn");
+    const img = imageProtocol() ? inlineImage(svgToPng(svg, 2), 70) : null;
+    return ["", img ?? figureNote("figure", svgCaption(svg)).join("\n"), ""];
+}
+/** Terminal markdown renderer: styling, mermaid, TeX equations, SVG figures and plots. */
+export function renderMd(md) {
+    const out = [];
+    let fence = null;
+    let buf = [];
+    let math = null;
+    const inline = (s) => mathToText(s)
+        .replace(/\*\*(.+?)\*\*/g, (_, x) => t.bold(x))
+        .replace(/`([^`]+)`/g, (_, x) => t.cyan(x))
+        .replace(/(?<![*\w])\*([^*]+)\*(?!\w)/g, (_, x) => t.italic(x));
+    for (const raw of md.split("\n")) {
+        // display math: $$ … $$ (one or many lines) and \[ … \]
+        if (math) {
+            const close = raw.match(/^(.*?)(\$\$|\\\])\s*$/);
+            if (close) {
+                math.push(close[1]);
+                out.push(...renderEquation(math.join("\n")));
+                math = null;
+            }
+            else
+                math.push(raw);
+            continue;
+        }
+        if (fence === null) {
+            const one = raw.match(/^\s*(?:\$\$|\\\[)(.+?)(?:\$\$|\\\])\s*$/);
+            if (one) {
+                out.push(...renderEquation(one[1]));
+                continue;
+            }
+            const open = raw.match(/^\s*(\$\$|\\\[)(.*)$/);
+            if (open) {
+                math = open[2].trim() ? [open[2]] : [];
+                continue;
+            }
+        }
+        const fm = raw.match(/^```(\w*)/);
+        if (fm) {
+            if (fence === null) {
+                fence = fm[1] || "code";
+                buf = [];
+            }
+            else {
+                if (fence === "mermaid") {
+                    const art = renderDiagram(buf.join("\n"));
+                    out.push("", ...(art ? art.split("\n").map((l) => "  " + l) : ["  " + t.pink("◆ diagram ") + t.dim("(too wide for this terminal — open the markdown file)")]), "");
+                }
+                else if (fence === "svg" || fence === "plot")
+                    out.push(...renderFigure(fence, buf.join("\n")));
+                fence = null;
+            }
+            continue;
+        }
+        if (fence === "mermaid" || fence === "svg" || fence === "plot") {
+            buf.push(raw);
+            continue;
+        }
+        if (fence !== null) {
+            out.push("  " + t.dim("│ ") + t.cyan(raw));
+            continue;
+        }
+        const h = raw.match(/^(#{1,4})\s+(.*)/);
+        if (h) {
+            out.push("", "  " + (h[1].length <= 2 ? t.bold(t.accent(inline(h[2]))) : t.bold(inline(h[2]))));
+            continue;
+        }
+        const li = raw.match(/^(\s*)[-*]\s+(.*)/);
+        if (li) {
+            out.push("  " + li[1] + t.accent("• ") + inline(li[2]));
+            continue;
+        }
+        const q = raw.match(/^>\s?(.*)/);
+        if (q) {
+            out.push("  " + t.warn("▌ ") + t.italic(inline(q[1])));
+            continue;
+        }
+        out.push(raw.trim() ? "  " + inline(raw) : "");
+    }
+    return out.join("\n");
+}
+/** Plain-text math for prompts, options and flashcards. */
+export const m = mathToText;

package/package.json

@@ -1,6 +1,47 @@
 {
   "name": "learn-loops",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.4.1",
+  "description": "A learning CLI that uses Claude Code / Codex as your tutor",
+  "type": "module",
+  "bin": {
+    "loops": "dist/cli.js"
+  },
+  "scripts": {
+    "build": "rm -rf dist && tsc && chmod +x dist/cli.js",
+    "dev": "tsx src/cli.ts",
+    "typecheck": "tsc --noEmit",
+    "test": "tsx --test test/*.test.ts",
+    "prepublishOnly": "npm run typecheck && npm test && npm run build"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "license": "MIT",
+  "dependencies": {
+    "@clack/prompts": "^1.8.1",
+    "@resvg/resvg-js": "^2.6.2",
+    "beautiful-mermaid": "^1.1.3",
+    "mathjax-full": "^3.2.1",
+    "mathjs": "^15.2.0",
+    "picocolors": "^1.1.1",
+    "unicodeit": "^0.7.5"
+  },
+  "devDependencies": {
+    "@types/node": "^26.6.5",
+    "tsx": "^4.23.15",
+    "typescript": "^7.0.2"
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "keywords": [
+    "learning",
+    "cli",
+    "claude-code",
+    "codex",
+    "mermaid",
+    "spaced-repetition",
+    "tutor"
+  ]
+}