coursecast 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Tomas Sestak
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,87 @@
+# coursecast
+
+**One prompt → a full interactive course.** Real multi-lesson content with live widgets,
+quizzes, a custom simulation per lesson, and a mastery dashboard — rendered to
+self-contained HTML you can open from disk or deploy anywhere with one command.
+
+> Prefer zero setup? The hosted version lives at **[trycoursecast.com](https://trycoursecast.com)** —
+> type a topic in the browser and it generates and hosts the course for you.
+
+## Install
+
+```bash
+npm i -g coursecast     # or: npx coursecast …
+```
+
+Requires Node 18+.
+
+## Use
+
+```bash
+# one interactive lesson
+coursecast new "how DNS works"
+
+# a whole course (~12 lessons + dashboard), deployed live
+coursecast course "intro to nuclear power" --deploy
+```
+
+Open the printed `index.html` — that's the whole product: no server, no build step,
+works offline, progress saved in the browser.
+
+## Engines
+
+The engine is what writes the content. Pick with `--engine`:
+
+| Engine | Runs on | Needs |
+|---|---|---|
+| `claude-code` *(default)* | your [Claude Code](https://claude.com/claude-code) CLI | `claude` on PATH |
+| `codex` | your Codex CLI | `codex` on PATH |
+| `gemini` | Google Gemini API, search-grounded | `GEMINI_API_KEY` ([free key](https://aistudio.google.com/apikey)) |
+| `stub` | nothing — offline placeholder content | nothing |
+
+```bash
+coursecast course "learn rust" --engine gemini
+```
+
+Gemini extras: `GEMINI_MODEL` overrides the model (default `gemini-2.5-flash`);
+`COURSECAST_RESEARCH=0` skips the web-search research pass (faster, cheaper, less current).
+
+## All flags
+
+```
+--engine <id>      claude-code (default) | gemini | codex | stub
+--model <id>       model hint passed to the engine
+--storage <id>     progress storage: local (default) | cloud
+--provider <id>    deploy target: vercel (default) | netlify
+--lessons <n>      (course) target number of lessons (default ~12)
+--concurrency <n>  (course) parallel lesson generation (default 4)
+--deploy           deploy after generating
+--dry-run          with --deploy, print the deploy command without running it
+--preview          deploy as a preview instead of production
+--out <dir>        output directory (default ./out/<slug>)
+```
+
+## Deploy providers
+
+`--deploy` ships the output directory with your own `vercel` or `netlify` CLI —
+your account, your URL, no middleman. Or skip it and host the files anywhere that
+serves static HTML. Add a provider via `src/providers/<id>.mjs` exporting `name`,
+`isAvailable()`, and `async deploy({ dir, prod, dryRun })`.
+
+## Architecture
+
+`engine` produces a **content object** (data) → `render.mjs` turns it into polished
+interactive HTML (presentation) → `provider` deploys the folder. Content and
+presentation are separated, so every lesson looks like one product no matter which
+engine wrote it. Progress (checklist, quiz, theme) saves per-device in `localStorage`.
+
+## Writing an engine
+
+An engine module exports `name`, `async generateLesson({ topic, slug, model, context })`,
+and — required for whole courses — `async generateSyllabus({ topic, lessons, model })`.
+Drop it in `src/engines/<id>.mjs` and pass `--engine <id>`. See `src/engines/stub.mjs`
+for the minimal shape and `src/engines/shared-prompts.mjs` for the content contract.
+
+## License
+
+MIT © Tomas Sestak

package/bin/coursecast.mjs

@@ -0,0 +1,93 @@
+#!/usr/bin/env node
+// coursecast — one prompt → an interactive lesson → deployed live.
+
+import { createLesson, createCourse, deployDir, slugify } from '../src/index.mjs';
+
+const argv = process.argv.slice(2);
+
+// Value-taking flags: return the following token, or `def` if the flag is bare/last
+// (never a bare `true`, which would crash string-typed consumers like spawn/resolve).
+function getFlag(name, def) {
+  const i = argv.indexOf(`--${name}`);
+  if (i === -1) return def;
+  const v = argv[i + 1];
+  return (v && !v.startsWith('--')) ? v : def;
+}
+const has = name => argv.includes(`--${name}`);
+const log = (...a) => console.log(...a);
+
+function usage() {
+  log(`
+coursecast — generate an interactive lesson from one prompt, and deploy it.
+
+USAGE
+  coursecast new    "<topic>" [options]     generate ONE interactive lesson
+  coursecast course "<topic>" [options]     generate a whole multi-lesson course + dashboard
+
+OPTIONS
+  --engine <id>      generation engine: claude-code (default), gemini, codex, stub
+  --model <id>       model hint passed to the engine (e.g. gemini-2.5-flash)
+  --storage <id>     progress storage: local (default, no setup), cloud (sync across devices)
+  --provider <id>    deploy target: vercel (default), netlify
+  --lessons <n>      (course) target number of lessons (default ~12)
+  --concurrency <n>  (course) how many lessons to generate at once (default 4)
+  --deploy           deploy after generating (otherwise generate only)
+  --dry-run          with --deploy, print the deploy command without running it
+  --preview          deploy as a preview instead of production
+  --out <dir>        output directory (default ./out/<slug>)
+  -h, --help         show this help
+
+EXAMPLES
+  coursecast new "kubernetes basics" --engine stub
+  coursecast course "how DNS works" --engine gemini      # cheap, search-grounded
+  GEMINI_API_KEY=... coursecast course "learn rust" --engine gemini
+  coursecast course "intro to nuclear power" --deploy --provider netlify
+`);
+}
+
+async function main() {
+  const cmd = argv[0];
+  if (!cmd || has('help') || argv.includes('-h')) { usage(); process.exit(cmd ? 0 : 1); }
+
+  if (cmd !== 'new' && cmd !== 'course') { log(`Unknown command "${cmd}".`); usage(); process.exit(1); }
+
+  const topic = argv[1] && !argv[1].startsWith('--') ? argv[1] : null;
+  if (!topic) { log(`❌  Provide a topic:  coursecast ${cmd} "your topic"`); process.exit(1); }
+
+  const engine = getFlag('engine', 'claude-code');
+  const provider = getFlag('provider', 'vercel');
+  const model = getFlag('model', undefined);
+  const storage = getFlag('storage', 'local');
+  const out = getFlag('out', undefined);
+  const lessons = parseInt(getFlag('lessons', ''), 10) || undefined;
+  const concurrency = parseInt(getFlag('concurrency', ''), 10) || undefined;
+
+  try {
+    let dir, entry;
+    if (cmd === 'course') {
+      const res = await createCourse({ topic, engine, model, storage, outDir: out, lessons, concurrency, log });
+      dir = res.dir; entry = `${res.dir}/index.html`;
+      log(`✅  Course ready: ${res.lessons.length} lessons${res.failed.length ? ` (${res.failed.length} failed: ${res.failed.join(', ')})` : ''}`);
+    } else {
+      const res = await createLesson({ topic, engine, model, storage, outDir: out, log });
+      dir = res.dir; entry = res.file;
+      log(`✅  Lesson ready: ${res.file}`);
+    }
+
+    if (has('deploy')) {
+      const res = await deployDir({
+        dir, provider, prod: !has('preview'), dryRun: has('dry-run'), log,
+      });
+      if (res.dryRun) log(`ℹ️  Dry run — would run:  ${res.command}`);
+      else log(`\n🎉  Live at: ${res.url}`);
+    } else {
+      log(`\nPreview locally:  npx serve "${dir}"   (or open ${entry})`);
+      log(`Deploy:           coursecast ${cmd} "${topic}" --deploy --provider ${provider}`);
+    }
+  } catch (e) {
+    log(`\n❌  ${e.message}`);
+    process.exit(1);
+  }
+}
+
+main();

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "coursecast",
+  "version": "0.1.0",
+  "description": "One prompt → an interactive lesson or a full multi-lesson course with a mastery dashboard — rendered to self-contained HTML and deployed live.",
+  "type": "module",
+  "bin": {
+    "coursecast": "bin/coursecast.mjs"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "files": [
+    "bin",
+    "src"
+  ],
+  "keywords": [
+    "learning",
+    "education",
+    "ai",
+    "generator",
+    "vercel",
+    "cli",
+    "lessons",
+    "courses",
+    "course-generator",
+    "interactive",
+    "gemini",
+    "claude",
+    "codex",
+    "netlify",
+    "static-site"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/TomasSestak/coursecast.git",
+    "directory": "cli"
+  },
+  "homepage": "https://trycoursecast.com",
+  "bugs": "https://github.com/TomasSestak/coursecast/issues",
+  "author": "Tomas Sestak"
+}

package/src/engines/claude-code.mjs

@@ -0,0 +1,49 @@
+// claude-code engine — drives the Claude Code CLI headlessly to generate real lesson content.
+// Requires `claude` on PATH (https://claude.ai/code). Highest quality; reuses the same
+// research+authoring the /learn skill uses. Output is a lesson content object (see shared-prompts).
+
+import { spawn } from 'node:child_process'
+import { buildSyllabusPrompt, buildLessonPrompt, finalizeLesson, extractJsonObject } from './shared-prompts.mjs'
+
+export const name = 'claude-code'
+
+export async function generateSyllabus({ topic, lessons = 12, model }) {
+  const prompt = buildSyllabusPrompt({ topic, lessons })
+  const raw = await run('claude', model ? ['-p', prompt, '--output-format', 'json', '--model', model] : ['-p', prompt, '--output-format', 'json'])
+  const obj = extractJsonObject(extractText(raw))
+  if (!obj || !Array.isArray(obj.phases)) throw new Error('claude-code engine: could not parse a syllabus object')
+  return obj
+}
+
+export async function generateLesson({ topic, slug, model, context }) {
+  const prompt = buildLessonPrompt({ topic, slug, context })
+  const args = ['-p', prompt, '--output-format', 'json']
+  if (model) args.push('--model', model)
+
+  const raw = await run('claude', args)
+  // Claude Code --output-format json wraps the result; find the lesson JSON inside.
+  const obj = extractJsonObject(extractText(raw))
+  if (!obj || !obj.title) throw new Error('claude-code engine: could not parse a lesson object from output')
+  return finalizeLesson(obj, slug, context)
+}
+
+function run(cmd, args) {
+  return new Promise((resolve, reject) => {
+    const p = spawn(cmd, args, { stdio: ['ignore', 'pipe', 'pipe'] })
+    let out = '', err = ''
+    p.stdout.on('data', (d) => (out += d))
+    p.stderr.on('data', (d) => (err += d))
+    p.on('error', (e) => reject(new Error(`Cannot run "${cmd}" — is it installed and on PATH? (${e.message})`)))
+    p.on('close', (code) => (code === 0 ? resolve(out) : reject(new Error(`${cmd} exited ${code}: ${err || out}`))))
+  })
+}
+
+function extractText(raw) {
+  try {
+    const j = JSON.parse(raw)
+    if (typeof j === 'string') return j
+    if (j.result) return j.result
+    if (Array.isArray(j)) { const last = j[j.length - 1]; return last?.result || raw }
+  } catch { /* not json-wrapped; use as-is */ }
+  return raw
+}

package/src/engines/codex.mjs

@@ -0,0 +1,71 @@
+// codex engine — drives the OpenAI Codex CLI headlessly to generate real content, so a
+// user with a Codex subscription can generate without a raw API key (mirrors claude-code).
+// Requires `codex` on PATH. Output is a lesson/syllabus content object (see schemas).
+//
+// Codex CLI non-interactive mode: `codex exec "<prompt>"` prints the model's final answer
+// to stdout. We ask for a bare JSON object and extract it.
+
+import { spawn } from 'node:child_process';
+
+export const name = 'codex';
+
+const LESSON_SCHEMA = `{
+  "slug": string (kebab-case), "title": string, "courseTitle": string, "lessonLabel": string,
+  "kicker": string, "lede": string (HTML ok), "tiles": [{ "big": string, "lbl": string, "note"?: string }],
+  "analogy": { "tag": "Analogy", "text": string }, "sections": [{ "h2": string, "html": string }],
+  "simulation": { "title": string, "sub": string, "html": string, "js": string },
+  "widgets": [{ "type": "what-if"|"flashcards"|"reveal-diagram", "config": object }],
+  "terminal": [{ "cmd": string, "explain": string }], "checklist": [{ "title": string, "desc": string, "hint"?: string }],
+  "quiz": [{ "q": string, "opts": [string], "a": number, "fb": string }], "next": null, "footer": string
+}`;
+
+const SYLLABUS_SCHEMA = `{
+  "courseTitle": string, "courseSubtitle": string,
+  "phases": [ { "name": string, "lessons": [ { "stem": string (kebab-case, unique), "title": string, "desc": string } ] } ]
+}`;
+
+export async function generateSyllabus({ topic, lessons = 12 }) {
+  const prompt = `Design a course syllabus for someone learning "${topic}". Output ONLY one JSON object, no prose, no fences, matching:\n${SYLLABUS_SCHEMA}\nAim for about ${lessons} lessons in 3-6 phases (foundations -> core -> advanced -> practice). Unique kebab-case stems.`;
+  const obj = extractJsonObject(await run('codex', ['exec', prompt]));
+  if (!obj || !Array.isArray(obj.phases)) throw new Error('codex engine: could not parse a syllabus object');
+  return obj;
+}
+
+export async function generateLesson({ topic, slug, context }) {
+  const ctx = context || {};
+  const position = ctx.lessonLabel ? ` It is ${ctx.lessonLabel} of "${ctx.courseTitle}" in the "${ctx.kicker}" section.` : '';
+  const prompt = `Generate ONE interactive lesson for a learner of "${topic}".${position}\nOutput ONLY one JSON object, no prose, no fences, matching:\n${LESSON_SCHEMA}\nRules: slug must be "${slug}"; beginner-friendly with analogies; the simulation and any widgets must be genuinely interactive, vanilla JS, no external libraries; all facts current and correct.`;
+  const obj = extractJsonObject(await run('codex', ['exec', prompt]));
+  if (!obj || !obj.title) throw new Error('codex engine: could not parse a lesson object');
+  obj.slug = slug;
+  if (ctx.courseTitle) obj.courseTitle = ctx.courseTitle;
+  if (ctx.title) obj.title = ctx.title;
+  if (ctx.lessonLabel) obj.lessonLabel = ctx.lessonLabel;
+  if (ctx.kicker) obj.kicker = ctx.kicker;
+  if (ctx.next !== undefined) obj.next = ctx.next;
+  return obj;
+}
+
+function run(cmd, args) {
+  return new Promise((resolve, reject) => {
+    const p = spawn(cmd, args, { stdio: ['ignore', 'pipe', 'pipe'] });
+    let out = '', err = '';
+    p.stdout.on('data', d => (out += d));
+    p.stderr.on('data', d => (err += d));
+    p.on('error', e => reject(new Error(`Cannot run "${cmd}" — is the Codex CLI installed and on PATH? (${e.message})`)));
+    p.on('close', code => code === 0 ? resolve(out) : reject(new Error(`${cmd} exited ${code}: ${err || out}`)));
+  });
+}
+
+// Tolerant JSON extraction: strip ``` fences, then take the outermost {...}. (json-repair-lite)
+function extractJsonObject(text) {
+  let t = String(text).replace(/```(?:json)?/gi, '');
+  const s = t.indexOf('{'), e = t.lastIndexOf('}');
+  if (s === -1 || e === -1) return null;
+  const slice = t.slice(s, e + 1);
+  try { return JSON.parse(slice); }
+  catch {
+    try { return JSON.parse(slice.replace(/,\s*([}\]])/g, '$1')); } // drop trailing commas
+    catch { return null; }
+  }
+}

package/src/engines/gemini.mjs

@@ -0,0 +1,92 @@
+// gemini engine — generates lessons via the Google Gemini API over plain HTTPS (no SDK).
+// Designed so a CHEAP model still produces good courses: every generation is preceded by a
+// Google-Search-grounded research pass, so the model formats *current, correct* facts into our
+// schema rather than inventing them from stale training data.
+//
+//   Requires: GEMINI_API_KEY   (free tier works — https://aistudio.google.com/apikey)
+//   Optional: GEMINI_MODEL     (default "gemini-2.5-flash"), COURSECAST_RESEARCH=0 to skip search.
+
+import { buildSyllabusPrompt, buildLessonPrompt, finalizeLesson, extractJsonObject } from './shared-prompts.mjs'
+
+export const name = 'gemini'
+
+const API = 'https://generativelanguage.googleapis.com/v1beta/models'
+const DEFAULT_MODEL = process.env.GEMINI_MODEL || 'gemini-2.5-flash'
+const RESEARCH_ON = process.env.COURSECAST_RESEARCH !== '0'
+
+function apiKey() {
+  const k = process.env.GEMINI_API_KEY || process.env.GOOGLE_API_KEY
+  if (!k) throw new Error('gemini engine: set GEMINI_API_KEY (free key at https://aistudio.google.com/apikey).')
+  return k
+}
+
+// One Gemini call. `json:true` forces a JSON body; `search:true` enables Google Search grounding.
+// (Gemini disallows forced-JSON + grounding together, so a call is one or the other.)
+async function callGemini({ model = DEFAULT_MODEL, prompt, json = false, search = false, maxOutputTokens = 8192 }) {
+  const body = {
+    contents: [{ parts: [{ text: prompt }] }],
+    generationConfig: { temperature: 0.7, maxOutputTokens },
+  }
+  if (json) body.generationConfig.responseMimeType = 'application/json'
+  if (search) body.tools = [{ google_search: {} }]
+
+  const key = apiKey() // resolve first so a missing key reports cleanly, not as a "network error"
+  let res
+  try {
+    res = await fetch(`${API}/${model}:generateContent`, {
+      method: 'POST',
+      headers: { 'content-type': 'application/json', 'x-goog-api-key': key },
+      body: JSON.stringify(body),
+    })
+  } catch (e) {
+    throw new Error(`gemini engine: network error calling the API (${e.message})`)
+  }
+  if (!res.ok) {
+    const detail = await res.text().catch(() => '')
+    throw new Error(`gemini engine: API ${res.status} — ${detail.slice(0, 300)}`)
+  }
+  const data = await res.json()
+  const parts = data?.candidates?.[0]?.content?.parts
+  const text = Array.isArray(parts) ? parts.map((p) => p.text || '').join('') : ''
+  if (!text) throw new Error('gemini engine: empty response from the model')
+  return text
+}
+
+// Search-grounded research pass — a compact brief of current, correct facts to ground generation.
+async function research({ topic, focus, model }) {
+  if (!RESEARCH_ON) return ''
+  const prompt = `Research "${topic}"${focus ? ` — specifically: ${focus}` : ''} using web search.
+Return a concise factual brief (bullet points, max ~250 words) capturing the most important,
+CURRENT facts: key concepts, real tool/library names and versions, real commands, common
+pitfalls, and any 2024-2026 changes. Facts only — no preamble, no course structure.`
+  try {
+    return await callGemini({ model, prompt, search: true, maxOutputTokens: 2048 })
+  } catch {
+    return '' // research is best-effort; never block generation on a failed search pass
+  }
+}
+
+function withResearch(prompt, brief) {
+  if (!brief) return prompt
+  return `Use these researched, current facts as your source of truth (prefer them over prior knowledge):\n<research>\n${brief}\n</research>\n\n${prompt}`
+}
+
+export async function generateSyllabus({ topic, lessons = 12, model }) {
+  const brief = await research({ topic, focus: 'the full scope a learner must cover, in learning order', model })
+  const prompt = withResearch(buildSyllabusPrompt({ topic, lessons }), brief)
+  const raw = await callGemini({ model, prompt, json: true, maxOutputTokens: 8192 })
+  const obj = extractJsonObject(raw)
+  if (!obj || !Array.isArray(obj.phases)) throw new Error('gemini engine: could not parse a syllabus object')
+  return obj
+}
+
+export async function generateLesson({ topic, slug, model, context }) {
+  const focus = context?.title ? `the lesson "${context.title}" (${context.kicker || ''})` : slug
+  const brief = await research({ topic, focus, model })
+  const prompt = withResearch(buildLessonPrompt({ topic, slug, context }), brief)
+  // Lessons are large (sections + a simulation + quiz), so allow plenty of output room.
+  const raw = await callGemini({ model, prompt, json: true, maxOutputTokens: 65536 })
+  const obj = extractJsonObject(raw)
+  if (!obj || !obj.title) throw new Error('gemini engine: could not parse a lesson object from output')
+  return finalizeLesson(obj, slug, context)
+}

package/src/engines/shared-prompts.mjs

@@ -0,0 +1,88 @@
+// Shared generation contract — the schemas, prompts, and post-processing every engine uses.
+// Keeping these in one place means the claude-code, gemini, and any future engine all produce
+// the exact same lesson shape and are held to the same authoring bar; only the transport differs.
+
+export const LESSON_SCHEMA = `{
+  "slug": string (kebab-case),
+  "title": string,
+  "courseTitle": string,
+  "lessonLabel": string (e.g. "Lesson 1"),
+  "kicker": string (short category label),
+  "lede": string (HTML ok; a 2-sentence standalone summary of why this matters),
+  "tiles": [{ "big": string, "lbl": string, "note"?: string }]  (2-4 calibrating stat tiles),
+  "analogy": { "tag": "Analogy", "text": string (HTML ok) },
+  "sections": [{ "h2": string (emoji + title), "html": string (2-4 short paragraphs; visual-first) }] (3-5),
+  "simulation": { "title": string, "sub": string, "html": string, "js": string }  (ONE bespoke interactive toy that teaches the single most important idea; vanilla JS; may use the shared CSS classes .btn/.btn.primary and CSS vars),
+  "widgets": [ ... ]  (0-3 pre-built interactive widgets; prefer these over hand-writing sim code. Each is { "type", "config" }. Types:
+     - "what-if": config { title, sub, variables:[{name(JS identifier),label,min,max,default,step,unit}], expression(arithmetic over the variable names, Math.* allowed), output:{label,unit,decimals,max} } — a live calculator/sim with sliders.
+     - "flashcards": config { title, cards:[{front,back}] } — recall practice.
+     - "reveal-diagram": config { title, nodes:[{label,detail}] } — a process/flow revealed step by step.),
+  "terminal": [{ "cmd": string, "explain": string }] (3-5 real, current commands),
+  "checklist": [{ "title": string, "desc": string, "hint"?: string }] (4-6 free hands-on steps),
+  "quiz": [{ "q": string, "opts": [string,...], "a": number (index), "fb": string }] (5),
+  "next": null,
+  "footer": string
+}`
+
+export const SYLLABUS_SCHEMA = `{
+  "courseTitle": string,
+  "courseSubtitle": string (one sentence),
+  "phases": [ { "name": string, "lessons": [ { "stem": string (kebab-case, unique), "title": string, "desc": string (one line) } ] } ]
+}`
+
+export function buildSyllabusPrompt({ topic, lessons = 12 }) {
+  return `Design a course syllabus for someone who wants to learn: "${topic}".
+
+Research the topic if needed, then output ONLY a single JSON object matching this schema — no prose, no markdown fences:
+
+${SYLLABUS_SCHEMA}
+
+Rules:
+- Aim for about ${lessons} lessons total, grouped into 3-6 phases that follow a natural learning progression (foundations -> core -> advanced -> practice/next steps).
+- Every "stem" must be unique, kebab-case, and filename-safe.
+- Output valid JSON and nothing else.`
+}
+
+export function buildLessonPrompt({ topic, slug, context }) {
+  const ctx = context || {}
+  const position = ctx.lessonLabel
+    ? `\nThis is ${ctx.lessonLabel} of the course "${ctx.courseTitle}", in the "${ctx.kicker}" section.${ctx.next ? ` The next lesson is "${ctx.next.title}".` : ''}`
+    : ''
+  return `You are generating ONE interactive lesson for a learner who wants to learn: "${topic}".${position}
+
+Research the topic as needed (use web search for current facts, versions, prices), then output ONLY a single JSON object matching this schema — no prose, no markdown fences:
+
+${LESSON_SCHEMA}
+
+Rules:
+- slug must be "${slug}".
+- Playful but not childish; a total beginner must be able to follow. Analogies for abstract ideas.
+- The simulation must be genuinely interactive and teach the lesson's deepest idea (e.g. a slider, a toggle, a click-through). Vanilla JS only; no external libraries. Give its elements unique ids.
+- All facts must be current and correct. Commands must actually work.
+- Output must be valid JSON and nothing else.`
+}
+
+// Course context wins for positioning fields so links/labels stay consistent across engines.
+export function finalizeLesson(obj, slug, context) {
+  const ctx = context || {}
+  obj.slug = slug
+  if (ctx.courseTitle) obj.courseTitle = ctx.courseTitle
+  if (ctx.title) obj.title = ctx.title
+  if (ctx.lessonLabel) obj.lessonLabel = ctx.lessonLabel
+  if (ctx.kicker) obj.kicker = ctx.kicker
+  if (ctx.next !== undefined) obj.next = ctx.next
+  return obj
+}
+
+// Pull the first {...} JSON object out of a model's text, tolerating fences and trailing commas.
+export function extractJsonObject(text) {
+  const t = String(text).replace(/```(?:json)?/gi, '')
+  const s = t.indexOf('{'), e = t.lastIndexOf('}')
+  if (s === -1 || e === -1) return null
+  const slice = t.slice(s, e + 1)
+  try { return JSON.parse(slice) }
+  catch {
+    try { return JSON.parse(slice.replace(/,\s*([}\]])/g, '$1')) } // tolerate trailing commas
+    catch { return null }
+  }
+}

package/src/engines/stub.mjs

@@ -0,0 +1,98 @@
+// stub engine — deterministic, no AI. Produces valid syllabus + lesson content objects
+// from a topic so the whole generate->render->deploy pipeline can be tested offline.
+
+export const name = 'stub';
+
+function titleCase(s) { return s.replace(/\b\w/g, m => m.toUpperCase()); }
+
+// A small but real multi-phase syllabus so the course pipeline is exercised end-to-end.
+export async function generateSyllabus({ topic }) {
+  const t = topic.trim();
+  const T = titleCase(t);
+  return {
+    courseTitle: T,
+    courseSubtitle: `A hands-on introduction to ${t}, generated end-to-end by the offline stub engine. Swap in an AI engine for real content.`,
+    phases: [
+      { name: 'Foundations', lessons: [
+        { stem: 'intro', title: `Intro to ${T}`, desc: 'What it is and why it matters' },
+        { stem: 'core-concepts', title: 'Core Concepts', desc: 'The ideas everything builds on' },
+        { stem: 'getting-started', title: 'Getting Started', desc: 'Your first hands-on steps' },
+      ]},
+      { name: 'Going Further', lessons: [
+        { stem: 'common-patterns', title: 'Common Patterns', desc: 'How it is used in practice' },
+        { stem: 'pitfalls', title: 'Pitfalls & Gotchas', desc: 'What trips people up' },
+        { stem: 'next-steps', title: 'Next Steps', desc: 'Where to go from here' },
+      ]},
+    ],
+  };
+}
+
+// context (optional) carries course position: { courseTitle, lessonLabel, kicker, next }
+export async function generateLesson({ topic, slug, context }) {
+  const t = topic.trim();
+  const c = context || {};
+  return {
+    slug,
+    title: c.title || titleCase(t),
+    courseTitle: c.courseTitle || titleCase(t),
+    lessonLabel: c.lessonLabel || 'Lesson 1',
+    kicker: c.kicker || 'Getting Started',
+    lede: `A hands-on introduction to <b>${t}</b>. This placeholder lesson was produced by the offline <code>stub</code> engine to verify the pipeline — swap in an AI engine for real content.`,
+    tiles: [
+      { big: '1', lbl: 'lesson generated end-to-end' },
+      { big: '0', lbl: 'dependencies — works offline' },
+      { big: '~5', lbl: 'min to read (when real)' },
+    ],
+    analogy: { tag: 'Note', text: `This is a stub. The AI engine replaces this body with a researched, interactive lesson on <b>${t}</b> — diagrams, a simulation, labs, and a quiz.` },
+    sections: [
+      { h2: '📘 What you will learn', html: `<p>The real generator produces several sections here, each explaining a core idea of <b>${t}</b> with a visual before prose.</p>` },
+    ],
+    simulation: {
+      title: '🎛️ Interactive simulation slot',
+      sub: 'Each real lesson ships one custom simulation here.',
+      html: `<button class="btn primary" id="stubBtn">Click me</button> <span id="stubOut" style="margin-left:10px;color:var(--ink-2)"></span>`,
+      js: `document.getElementById('stubBtn').addEventListener('click',function(){document.getElementById('stubOut').textContent='✅ Pipeline works — this is where a real simulation lives.';});`,
+    },
+    terminal: [
+      { cmd: `coursecast new "${t}"`, explain: 'Generates this lesson from a single prompt.' },
+      { cmd: `coursecast course "${t}" --deploy`, explain: 'Generates a whole course and deploys it live.' },
+    ],
+    checklist: [
+      { title: 'Confirm the page renders', desc: 'You are reading it — the render step works.', hint: 'If styles are missing, the CSS did not inline correctly.' },
+      { title: 'Try the theme toggle', desc: 'Top-right button; the choice persists across lessons.' },
+      { title: 'Take the quiz below', desc: 'Score saves to this device.' },
+    ],
+    quiz: [
+      { q: 'What produced this particular lesson body?', opts: ['A real AI engine', 'The offline stub engine', 'A human author'], a: 1, fb: 'The stub proves the pipeline without calling any AI.' },
+      { q: 'Where is progress saved?', opts: ['A cloud database', "The browser's localStorage", 'Nowhere'], a: 1, fb: 'Per-device localStorage, keyed per lesson.' },
+    ],
+    widgets: [
+      { type: 'what-if', config: {
+        title: 'What-if: compound growth', sub: 'Drag the sliders — the result updates live.',
+        variables: [
+          { name: 'p', label: 'Principal', min: 100, max: 10000, default: 1000, step: 100, unit: '$' },
+          { name: 'r', label: 'Rate', min: 1, max: 20, default: 7, step: 1, unit: '%' },
+          { name: 'y', label: 'Years', min: 1, max: 40, default: 10, step: 1 },
+        ],
+        expression: 'p * Math.pow(1 + r/100, y)',
+        output: { label: 'Future value', unit: '$', decimals: 0, max: 50000 },
+      } },
+      { type: 'flashcards', config: {
+        title: 'Quick recall',
+        cards: [
+          { front: `What is ${t}?`, back: 'The stub leaves this blank — a real engine fills it in.' },
+          { front: 'Why does it matter?', back: 'Because the concept is foundational.' },
+        ],
+      } },
+      { type: 'reveal-diagram', config: {
+        title: 'The flow', nodes: [
+          { label: 'Input', detail: 'Where it starts.' },
+          { label: 'Process', detail: 'What happens in the middle.' },
+          { label: 'Output', detail: 'What you get.' },
+        ],
+      } },
+    ],
+    next: c.next || null,
+    footer: 'stub engine · replace with an AI engine for real content',
+  };
+}