coursecast 0.2.4 → 0.3.0

package/README.md

@@ -34,21 +34,22 @@ 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)) |
+| `claude` *(default)* | your [Claude Code](https://claude.com/claude-code) CLI | `claude` on PATH |
+| `codex` | your [Codex](https://developers.openai.com/codex/cli/) CLI | `codex` on PATH |
+| `gemini-cli` | your [Gemini CLI](https://github.com/google-gemini/gemini-cli) login | `gemini` on PATH — **no API key** |
+| `gemini` | the [Gemini API](https://ai.google.dev/), search-grounded | `GEMINI_API_KEY` ([free key](https://aistudio.google.com/apikey)) + your `--model` choice |
 
 ```bash
-coursecast "learn rust" --engine gemini
+coursecast "learn rust" --engine gemini --model gemini-3.5-flash-lite
 ```
 
-Gemini extras: `GEMINI_MODEL` overrides the model (default `gemini-3.5-flash-lite`);
-`COURSECAST_RESEARCH=0` skips the web-search research pass (faster, cheaper, less current).
+The gemini engine never picks a model for you — pass `--model` (or set `GEMINI_MODEL`) with
+whatever your key has access to. `COURSECAST_RESEARCH=0` skips the web-search research pass.
 
 ## All flags
 
 ```
---engine <id>      claude-code (default) | gemini | codex
+--engine <id>      claude (default) | gemini | codex
 --model <id>       model hint passed to the engine
 --storage <id>     progress storage: local (default) | cloud
 --provider <id>    deploy target: vercel (default) | netlify

package/bin/coursecast.mjs

@@ -24,8 +24,8 @@ USAGE
   coursecast "<topic>" [options]
 
 OPTIONS
-  --engine <id>      generation engine: claude-code (default), gemini, codex, stub
-  --model <id>       model hint passed to the engine (e.g. gemini-3.5-flash-lite)
+  --engine <id>      generation engine: claude (default), gemini, gemini-cli, codex, stub
+  --model <id>       model to use (required for gemini, e.g. gemini-3.5-flash-lite)
   --storage <id>     progress storage: local (default, no setup), cloud (sync across devices)
   --provider <id>    deploy target: vercel | netlify (auto-detects what you have installed)
   --lessons <n>      target number of lessons (default ~12)
@@ -37,8 +37,9 @@ OPTIONS
   -h, --help         show this help
 
 EXAMPLES
-  coursecast "kubernetes basics"                        # default engine (claude-code)
-  coursecast "how DNS works" --engine gemini            # cheap, search-grounded
+  coursecast "kubernetes basics"                        # default engine (claude)
+  coursecast "how DNS works" --engine gemini --model gemini-3.5-flash-lite
+  coursecast "how DNS works" --engine gemini-cli                # no API key — uses your Gemini CLI login
   coursecast "intro to nuclear power" --deploy          # generate + ship to your Vercel
 `);
 }
@@ -56,7 +57,7 @@ async function main() {
     process.exit(1);
   }
 
-  const engine = getFlag('engine', 'claude-code');
+  const engine = getFlag('engine', 'claude');
   const providerFlag = getFlag('provider', undefined);
   const model = getFlag('model', undefined);
   const storage = getFlag('storage', 'local');

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "coursecast",
-  "version": "0.2.4",
+  "version": "0.3.0",
   "description": "One prompt → a full interactive course — live widgets, quizzes, a mastery dashboard — rendered to self-contained HTML and deployed live.",
   "type": "module",
   "bin": {

package/src/engines/{claude-code.mjs → claude.mjs}

@@ -1,30 +1,38 @@
-// claude-code engine — drives the Claude Code CLI headlessly to generate real lesson content.
+// claude 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'
+import {
+  buildSyllabusPrompt, buildLessonPrompt, extractJsonObject,
+  generateSyllabusWithRepair, generateLessonWithRepair,
+} from './shared-prompts.mjs'
 
-export const name = 'claude-code'
+export const name = 'claude'
 
 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
+  return generateSyllabusWithRepair({
+    call: callModel(model),
+    prompt: buildSyllabusPrompt({ topic, lessons }),
+    label: 'claude engine',
+  })
 }
 
 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)
+  return generateLessonWithRepair({
+    call: callModel(model),
+    prompt: buildLessonPrompt({ topic, slug, context }),
+    slug, context, label: 'claude engine',
+  })
+}
 
-  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)
+// One text-in/text-out call through the local CLI, unwrapped from its JSON envelope.
+function callModel(model) {
+  return async (prompt) => {
+    const args = ['-p', prompt, '--output-format', 'json']
+    if (model) args.push('--model', model)
+    return extractText(await run('claude', args))
+  }
 }
 
 function run(cmd, args) {

package/src/engines/codex.mjs

@@ -1,49 +1,41 @@
 // 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).
+// user with a Codex subscription can generate without a raw API key (mirrors the claude engine).
+// Requires `codex` on PATH. Output is a lesson/syllabus content object (see shared-prompts).
 //
 // 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.
+//
+// This engine used to carry its OWN copy of the schemas and prompts, which meant it silently
+// missed every authoring rule added to the shared contract (valid-HTML rules, labelled form
+// controls, correct quiz answer keys). It now uses shared-prompts like the other engines, so
+// improving the prompt improves every engine at once.
 
 import { spawn } from 'node:child_process';
+import {
+  buildSyllabusPrompt, buildLessonPrompt,
+  generateSyllabusWithRepair, generateLessonWithRepair,
+} from './shared-prompts.mjs';
 
 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 } ] } ]
-}`;
+const call = async (prompt) => run('codex', ['exec', prompt]);
 
 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;
+  return generateSyllabusWithRepair({
+    call,
+    prompt: buildSyllabusPrompt({ topic, lessons }),
+    label: 'codex engine',
+  });
 }
 
 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;
+  return generateLessonWithRepair({
+    call,
+    prompt: buildLessonPrompt({ topic, slug, context }),
+    slug,
+    context,
+    label: 'codex engine',
+  });
 }
 
 function run(cmd, args) {
@@ -56,16 +48,3 @@ function run(cmd, args) {
     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-cli.mjs

@@ -0,0 +1,61 @@
+// gemini-cli engine — drives Google's Gemini CLI headlessly, so you can generate with your
+// signed-in Google account and NO API key (the CLI's free tier covers a lot of courses).
+// Requires `gemini` on PATH (https://github.com/google-gemini/gemini-cli, then `gemini` once
+// to sign in). This is the key-less sibling of the `gemini` engine, which calls the API.
+
+import { spawn } from 'node:child_process'
+import {
+  buildSyllabusPrompt, buildLessonPrompt, extractJsonObject,
+  generateSyllabusWithRepair, generateLessonWithRepair,
+} from './shared-prompts.mjs'
+
+export const name = 'gemini-cli'
+
+// `--output-format json` wraps the answer in an envelope; the lesson JSON is inside it.
+function extractText(raw) {
+  const env = extractJsonObject(raw)
+  if (env && typeof env.response === 'string') return env.response
+  if (env && typeof env.output === 'string') return env.output
+  return raw
+}
+
+function call(model) {
+  return async (prompt) => {
+    const args = ['-p', prompt, '--output-format', 'json']
+    if (model) args.push('-m', model)
+    return extractText(await run('gemini', args))
+  }
+}
+
+export async function generateSyllabus({ topic, lessons = 12, model }) {
+  return generateSyllabusWithRepair({
+    call: call(model),
+    prompt: buildSyllabusPrompt({ topic, lessons }),
+    label: 'gemini-cli engine',
+  })
+}
+
+export async function generateLesson({ topic, slug, model, context }) {
+  return generateLessonWithRepair({
+    call: call(model),
+    prompt: buildLessonPrompt({ topic, slug, context }),
+    slug,
+    context,
+    label: 'gemini-cli engine',
+  })
+}
+
+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 "gemini" — install Google's Gemini CLI and sign in:\n` +
+        `  npm i -g @google/gemini-cli && gemini\n(${e.message})`
+      )))
+    p.on('close', (code) => (code === 0 ? resolve(out) : reject(new Error(`gemini exited ${code}: ${err || out}`))))
+  })
+}

package/src/engines/gemini.mjs

@@ -4,25 +4,38 @@
 // 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-3.5-flash-lite"), COURSECAST_RESEARCH=0 to skip search.
+//             and a model of YOUR choice via --model or GEMINI_MODEL — the CLI never
+//             picks one for you (it's your key, your cost, your quality bar).
+//   Optional: COURSECAST_RESEARCH=0 to skip the web-search research pass.
 
-import { buildSyllabusPrompt, buildLessonPrompt, finalizeLesson, extractJsonObject } from './shared-prompts.mjs'
+import {
+  buildSyllabusPrompt, buildLessonPrompt,
+  generateSyllabusWithRepair, generateLessonWithRepair,
+} from './shared-prompts.mjs'
 
 export const name = 'gemini'
 
 const API = 'https://generativelanguage.googleapis.com/v1beta/models'
-const DEFAULT_MODEL = process.env.GEMINI_MODEL || 'gemini-3.5-flash-lite'
+const DEFAULT_MODEL = process.env.GEMINI_MODEL // no baked-in default — the user chooses
 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).')
+  if (!k) throw new Error(
+    'gemini engine: set GEMINI_API_KEY (free key at https://aistudio.google.com/apikey)\n' +
+    '  …or skip the key entirely with --engine gemini-cli, which uses your signed-in Gemini CLI.'
+  )
   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 }) {
+  if (!model) {
+    throw new Error(
+      'gemini engine: pick a model with --model (e.g. gemini-3.5-flash, gemini-3.5-flash-lite) or set GEMINI_MODEL.'
+    )
+  }
   const body = {
     contents: [{ parts: [{ text: prompt }] }],
     generationConfig: { temperature: 0.7, maxOutputTokens },
@@ -73,20 +86,20 @@ function withResearch(prompt, brief) {
 
 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
+  return generateSyllabusWithRepair({
+    call: (prompt) => callGemini({ model, prompt, json: true, maxOutputTokens: 8192 }),
+    prompt: withResearch(buildSyllabusPrompt({ topic, lessons }), brief),
+    label: 'gemini engine',
+  })
 }
 
 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)
+  return generateLessonWithRepair({
+    call: (prompt) => callGemini({ model, prompt, json: true, maxOutputTokens: 65536 }),
+    prompt: withResearch(buildLessonPrompt({ topic, slug, context }), brief),
+    slug, context, label: 'gemini engine',
+  })
 }

package/src/engines/shared-prompts.mjs

@@ -1,5 +1,5 @@
 // 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
+// Keeping these in one place means the claude, 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 = `{
@@ -59,6 +59,29 @@ Rules:
 - 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.
+- The quiz answer index "a" must be the genuinely correct option — a learner is graded on it.
+- Only include "terminal" when the topic really involves a command line; for non-technical
+  subjects omit it rather than inventing shell commands.
+
+HTML rules for every "html" field you write (sections[].html, simulation.html) — these are
+injected into a page as-is, so malformed markup breaks the lesson:
+- Write valid, self-contained HTML fragments only. NEVER include <style>, <script>, <html>,
+  <head> or <body> tags — style with inline style="" attributes or the shared CSS classes.
+- Never put a block element (<div>, <p>, <table>, <ul>) inside an inline element (<span>, <b>, <a>).
+- Escape ampersands as &amp; (and < as &lt;) in text; a raw "&" is invalid.
+- Every <button> needs type="button".
+- Every form control (<input>, <select>, <textarea>) needs an accessible name: either a
+  <label for="id"> pointing at it, or an aria-label. Sliders and toggles included.
+- Don't use heading tags inside sections[].html — the section's "h2" is already the heading;
+  use <b>/<strong> for sub-emphasis so the page's heading order stays valid.
+
+Math and symbols — there is NO LaTeX/MathJax renderer on the page:
+- NEVER write $...$, \(...\), \[...\] or backslash macros (\frac, \sum, \Delta, \mathbf,
+  \text). They ship to the learner as literal, broken-looking text.
+- Express maths in plain Unicode: superscripts ²³ⁿ, subscripts ₀₁ₙ, Δ α β θ λ π Σ ∫ √ ≈ ≤ ≥ ×
+  · → ∞ ∇, and chemistry as CO₂ / H₂O. Write "dA/dt = h/2", not "$\frac{dA}{dt}=\frac{h}{2}$".
+- quiz "opts", flashcard "front"/"back" and tiles "big" are inserted as TEXT, not HTML — put no
+  tags in them at all. Inside sections[].html you may also use <sub>, <sup> and <code>.
 - Output must be valid JSON and nothing else.`
 }
 
@@ -86,3 +109,96 @@ export function extractJsonObject(text) {
     catch { return null }
   }
 }
+
+// ---------------------------------------------------------------- validate + repair
+//
+// Models drop a required field or mis-index a quiz answer often enough that a silent
+// half-broken lesson is a real quality problem — and a wrong quiz answer key actively
+// mis-teaches. So every engine validates the parsed JSON against the schema and, on a
+// miss, gets ONE repair attempt that shows the model its own output and the exact errors.
+// One extra call on the minority of generations that need it; no cost on the ones that don't.
+
+export function validateLesson(obj) {
+  const e = []
+  if (!obj || typeof obj !== 'object') return ['the output was not a JSON object']
+  if (!obj.title) e.push('"title" is missing')
+  if (!Array.isArray(obj.sections) || !obj.sections.length) e.push('"sections" must be a non-empty array of {h2, html}')
+  else obj.sections.forEach((s, i) => {
+    if (!s || !s.h2) e.push(`sections[${i}] is missing "h2"`)
+    if (!s || !s.html) e.push(`sections[${i}] is missing "html"`)
+  })
+  if (obj.quiz !== undefined) {
+    if (!Array.isArray(obj.quiz)) e.push('"quiz" must be an array')
+    else obj.quiz.forEach((q, i) => {
+      if (!q || !q.q) e.push(`quiz[${i}] is missing the question "q"`)
+      if (!q || !Array.isArray(q.opts) || q.opts.length < 2) e.push(`quiz[${i}] needs at least 2 "opts"`)
+      else if (typeof q.a !== 'number' || !Number.isInteger(q.a) || q.a < 0 || q.a >= q.opts.length)
+        e.push(`quiz[${i}].a must be the 0-based index of the CORRECT option (0..${q.opts.length - 1}), got ${JSON.stringify(q && q.a)}`)
+    })
+  }
+  if (obj.checklist !== undefined && !Array.isArray(obj.checklist)) e.push('"checklist" must be an array')
+  if (obj.tiles !== undefined && !Array.isArray(obj.tiles)) e.push('"tiles" must be an array')
+  if (obj.simulation) {
+    if (!obj.simulation.html) e.push('"simulation" is missing "html"')
+    if (!obj.simulation.js) e.push('"simulation" is missing "js"')
+  }
+  return e
+}
+
+export function validateSyllabus(obj) {
+  const e = []
+  if (!obj || typeof obj !== 'object') return ['the output was not a JSON object']
+  if (!obj.courseTitle) e.push('"courseTitle" is missing')
+  if (!Array.isArray(obj.phases) || !obj.phases.length) e.push('"phases" must be a non-empty array')
+  else obj.phases.forEach((p, i) => {
+    if (!p || !p.name) e.push(`phases[${i}] is missing "name"`)
+    if (!p || !Array.isArray(p.lessons) || !p.lessons.length) e.push(`phases[${i}].lessons must be a non-empty array`)
+    else p.lessons.forEach((l, k) => { if (!l || !l.title) e.push(`phases[${i}].lessons[${k}] is missing "title"`) })
+  })
+  return e
+}
+
+function repairPrompt(original, output, errors) {
+  return `Your previous response did not match the required schema.
+
+ERRORS:
+${errors.map((x) => `- ${x}`).join('\n')}
+
+YOUR PREVIOUS OUTPUT:
+${String(output).slice(0, 12000)}
+
+Fix ONLY those errors and return the COMPLETE corrected JSON object — all the original
+content, with the problems above resolved. Output ONLY the JSON, no prose, no fences.
+
+The original request, for reference:
+${original}`
+}
+
+// Run `call(prompt)` -> text, parse, validate, and retry once with the errors if needed.
+// Keeps whichever attempt validates better, so a repair can never make things worse.
+async function withRepair({ call, prompt, validate, label, what }) {
+  const raw = await call(prompt)
+  let obj = extractJsonObject(raw)
+  let errs = validate(obj)
+  if (errs.length) {
+    try {
+      const raw2 = await call(repairPrompt(prompt, raw, errs))
+      const obj2 = extractJsonObject(raw2)
+      const errs2 = validate(obj2)
+      if (errs2.length < errs.length) { obj = obj2; errs = errs2 }
+    } catch { /* keep the first attempt if the repair call itself fails */ }
+  }
+  if (!obj || errs.length) {
+    throw new Error(`${label}: could not produce a valid ${what} (${errs.slice(0, 3).join('; ') || 'unparseable output'})`)
+  }
+  return obj
+}
+
+export async function generateSyllabusWithRepair({ call, prompt, label = 'engine' }) {
+  return withRepair({ call, prompt, validate: validateSyllabus, label, what: 'syllabus' })
+}
+
+export async function generateLessonWithRepair({ call, prompt, slug, context, label = 'engine' }) {
+  const obj = await withRepair({ call, prompt, validate: validateLesson, label, what: 'lesson' })
+  return finalizeLesson(obj, slug, context)
+}

package/src/index.mjs

@@ -15,9 +15,13 @@ export function slugify(s) {
   return slug;
 }
 
+// "claude-code" was the id before 0.2.6 — keep it working so existing scripts don't break.
+const ENGINE_ALIASES = { 'claude-code': 'claude' };
+
 async function loadEngine(id) {
-  try { return await import(`./engines/${id}.mjs`); }
-  catch { throw new Error(`Unknown engine "${id}". Available: claude-code, gemini, codex, stub.`); }
+  const resolved = ENGINE_ALIASES[id] || id;
+  try { return await import(`./engines/${resolved}.mjs`); }
+  catch { throw new Error(`Unknown engine "${id}". Available: claude, gemini, gemini-cli, codex, stub.`); }
 }
 // Pick a deploy provider by what's actually installed: vercel first, then netlify.
 // Auto-detection beats a silent default (which pretended netlify didn't exist) and
@@ -40,7 +44,7 @@ async function loadProvider(id) {
   catch { throw new Error(`Unknown provider "${id}". Available: vercel, netlify.`); }
 }
 
-export async function createLesson({ topic, engine = 'claude-code', model, storage = 'local', outDir, log = () => {} }) {
+export async function createLesson({ topic, engine = 'claude', model, storage = 'local', outDir, log = () => {} }) {
   const slug = slugify(topic);
   const eng = await loadEngine(engine);
   log(`🧠  Generating lesson with the "${eng.name}" engine…`);
@@ -64,7 +68,7 @@ export async function createLesson({ topic, engine = 'claude-code', model, stora
 
 // Generate a whole multi-lesson course from one topic: syllabus -> lessons (parallel,
 // with retry) -> mastery dashboard. Returns { dir, slug, manifest, lessons, failed }.
-export async function createCourse({ topic, engine = 'claude-code', model, storage = 'local', outDir, lessons, concurrency = 4, log = () => {} }) {
+export async function createCourse({ topic, engine = 'claude', model, storage = 'local', outDir, lessons, concurrency = 4, log = () => {} }) {
   concurrency = Math.max(1, concurrency || 4);
   lessons = lessons ? Math.max(1, lessons) : undefined;
   const slug = slugify(topic);

package/src/render-dashboard.mjs

@@ -14,8 +14,8 @@ const esc = (s = '') => String(s)
 const jsonEmbed = v => JSON.stringify(v).replace(/</g, '\\u003c');
 
 const CSS = `
-  :root{color-scheme:light;--page:#f9f9f7;--surface:#fcfcfb;--ink:#0b0b0b;--ink-2:#52514e;--muted:#898781;--grid:#e1e0d9;--border:rgba(11,11,11,0.10);--accent:#2a78d6;
-    --mastered:#0ca30c;--progress:#2a78d6;--needs:#eda100;--visited:#898781;--untouched:#c3c2b7;}
+  :root{color-scheme:light;--page:#f9f9f7;--surface:#fcfcfb;--ink:#0b0b0b;--ink-2:#52514e;--muted:#67665f;--grid:#e1e0d9;--border:rgba(11,11,11,0.10);--accent:#2a78d6;
+    --mastered:#0ca30c;--progress:#2a78d6;--needs:#9a6400;--visited:#898781;--untouched:#c3c2b7;}
   :root[data-theme="dark"]{color-scheme:dark;--page:#0d0d0d;--surface:#1a1a19;--ink:#fff;--ink-2:#c3c2b7;--muted:#898781;--grid:#2c2c2a;--border:rgba(255,255,255,0.10);--accent:#3987e5;
     --mastered:#0ca30c;--progress:#3987e5;--needs:#c98500;--visited:#898781;--untouched:#3a3a38;}
   @media (prefers-color-scheme:dark){:root:not([data-theme="light"]){color-scheme:dark;--page:#0d0d0d;--surface:#1a1a19;--ink:#fff;--ink-2:#c3c2b7;--muted:#898781;--grid:#2c2c2a;--border:rgba(255,255,255,0.10);--accent:#3987e5;--needs:#c98500;--visited:#898781;--untouched:#3a3a38;}}
@@ -49,6 +49,7 @@ const CSS = `
   .badge{font-size:11px;font-weight:700;padding:2px 8px;border-radius:999px;border:1px solid var(--border);white-space:nowrap}
   .phase-lessons a{border:1px solid var(--border);background:var(--surface);border-radius:11px;margin:8px 0}
   .foot{margin-top:44px;font-size:13px;color:var(--muted);border-top:1px solid var(--grid);padding-top:16px;display:flex;justify-content:space-between;gap:12px;flex-wrap:wrap}
+  :focus-visible{outline:2px solid var(--accent);outline-offset:2px;border-radius:4px}
   .reset{border:1px solid var(--border);background:none;color:var(--muted);border-radius:8px;padding:4px 10px;cursor:pointer;font-size:12px}
   .empty{color:var(--muted);font-size:14px;padding:10px 16px}
 `;
@@ -72,8 +73,8 @@ export function renderDashboard(manifest) {
 <script>try{var t=localStorage.getItem("cc-theme");if(t)document.documentElement.dataset.theme=t;}catch(e){}</script>
 </head>
 <body>
-<div class="wrap">
-  <button class="theme-btn" id="themeBtn">◐ Theme</button>
+<main class="wrap">
+  <button type="button" class="theme-btn" id="themeBtn">◐ Theme</button>
   <div class="kicker">coursecast · Interactive Course</div>
   <h1>${esc(m.courseTitle)}</h1>
   <p class="lede">${esc(m.courseSubtitle || '')}</p>
@@ -98,9 +99,9 @@ export function renderDashboard(manifest) {
 
   <div class="foot">
     <span>Progress saves on this device. Generated by <b>coursecast</b>.</span>
-    <button class="reset" id="reset">Reset progress</button>
+    <button type="button" class="reset" id="reset">Reset progress</button>
   </div>
-</div>
+</main>
 <script>
 (function(){
   var LESSONS=${LDATA}, PHASES=${PHASES};

package/src/render.mjs

@@ -9,8 +9,87 @@ const esc = (s = '') => String(s)
   .replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;')
   .replace(/"/g, '&quot;');
 
+// Model-authored HTML (sections[].html, simulation.html) is injected as-is, so the prompt
+// asks for well-formed fragments — but a generator that ignores the rules must not be able
+// to break the page or its accessibility. This is a safety net, not a parser.
+//
+// Styles are HOISTED rather than dropped: a <style> inside a <div> is invalid markup, but
+// deleting it would silently break the look of an AI-authored simulation. Collected CSS is
+// emitted in <head>, which is valid and visually identical (each lesson is its own page, so
+// there is nothing for it to leak into). <script> is left alone — it is valid flow content,
+// and simulations legitimately inline their JS.
+const INPUT_TYPES = new Set(['button', 'checkbox', 'color', 'date', 'datetime-local', 'email', 'file',
+  'hidden', 'image', 'month', 'number', 'password', 'radio', 'range', 'reset', 'search', 'submit',
+  'tel', 'text', 'time', 'url', 'week']);
+
+function tidyFragment(html = '', sink) {
+  return String(html)
+    // Entity-encoded attribute quotes: a model that emits id=&quot;x&quot; produces an
+    // attribute whose value is literally &quot;x&quot;, so the simulation's own
+    // getElementById('x') finds nothing and throws. Only rewritten inside a tag, so prose
+    // that legitimately contains &quot; is untouched.
+    .replace(/<[a-z][^>]*>/gi, (tag) =>
+      tag.includes('=&quot;') ? tag.replace(/=&quot;(.*?)&quot;/g, '="$1"') : tag)
+    .replace(/<style\b[^>]*>([\s\S]*?)<\/style>/gi, (_m, css) => { if (sink) sink.push(css); return ''; })
+    // A <button> with no type submits enclosing forms and trips validation.
+    .replace(/<button(?![^>]*\btype=)/gi, '<button type="button"')
+    // Repair broken <input type>. Two failure modes seen in real output, both of which
+    // silently turn a working slider into a text box:
+    //   - duplicated type= (the browser honours the FIRST, which may be the bogus one)
+    //   - a single type= whose value isn't an input type at all (e.g. type="id")
+    // A tag carrying min/max/step was clearly meant to be a range.
+    .replace(/<input\b[^>]*>/gi, (tag) => {
+      const types = [...tag.matchAll(/\stype\s*=\s*(["'])(.*?)\1/gi)];
+      if (!types.length) return tag;
+      const valid = types.find((t) => INPUT_TYPES.has(t[2].toLowerCase()));
+      const guess = /\s(?:min|max|step)\s*=/i.test(tag) ? 'range' : 'text';
+      const keep = valid ? valid[0] : ` type="${guess}"`;
+      let placed = false;
+      return tag.replace(/\stype\s*=\s*(["'])(.*?)\1/gi, () => {
+        if (placed) return '';
+        placed = true;
+        return keep;
+      });
+    })
+    // An id with surrounding whitespace is invalid AND breaks the simulation's own
+    // getElementById lookups, which then throw on a null element.
+    .replace(/\s(id|for)\s*=\s*(["'])\s*(.*?)\s*\2/gi, (_m, attr, q, val) => ` ${attr}=${q}${val}${q}`)
+    // Headings inside a fragment break the page's heading order (the section already owns
+    // its <h2>). Demote them to bold text, which is what they were being used for visually.
+    // Any style= the model already set is preserved rather than duplicated.
+    .replace(/<h[1-6]\b([^>]*)>/gi, (_m, attrs) =>
+      /\bstyle\s*=/i.test(attrs)
+        ? `<strong${attrs.replace(/\bstyle\s*=\s*(["'])/i, 'style=$1display:block;font-size:1.05em;')}>`
+        : `<strong${attrs} style="display:block;font-size:1.05em">`)
+    .replace(/<\/h[1-6]>/gi, '</strong>')
+    // Bare "&" that isn't already an entity is invalid markup.
+    .replace(/&(?!#?[a-z0-9]{1,8};)/gi, '&amp;');
+}
+
+// Model-authored simulation JS, repaired the same way its HTML is.
+//
+// The failure this catches: a model double-escapes its newlines, so `simulation.js` arrives
+// as one line containing literal backslash-n sequences. That is a hard SyntaxError, and the
+// lesson's whole interactive simulation silently does nothing. Repair is only attempted in
+// the unambiguous case (escapes present, no real newlines at all) so a script that
+// legitimately contains "\n" inside a string is never touched.
+function tidyScript(js = '') {
+  let src = String(js);
+  if (!src.trim()) return '';
+  if (!/\r?\n/.test(src) && /\\n/.test(src)) {
+    src = src.replace(/\\r\\n|\\n/g, '\n').replace(/\\t/g, '\t').replace(/\\(["'`])/g, '$1');
+  }
+  // Generation runs in Node, so we can actually check it parses before shipping it.
+  try {
+    new Function(src);
+  } catch (e) {
+    return `/* coursecast: simulation script omitted — it does not parse (${String(e.message).slice(0, 80)}) */`;
+  }
+  return src;
+}
+
 const CSS = `
-  :root{color-scheme:light;--page:#f9f9f7;--surface:#fcfcfb;--ink:#0b0b0b;--ink-2:#52514e;--muted:#898781;--grid:#e1e0d9;--baseline:#c3c2b7;--border:rgba(11,11,11,0.10);--accent:#2a78d6;--s1:#2a78d6;--s2:#eb6834;--s3:#1baf7a;--good:#0ca30c;--good-text:#006300;--critical:#d03b3b;--warning:#fab219;}
+  :root{color-scheme:light;--page:#f9f9f7;--surface:#fcfcfb;--ink:#0b0b0b;--ink-2:#52514e;--muted:#67665f;--grid:#e1e0d9;--baseline:#c3c2b7;--border:rgba(11,11,11,0.10);--accent:#2a78d6;--s1:#2a78d6;--s2:#eb6834;--s3:#1baf7a;--good:#0ca30c;--good-text:#006300;--critical:#d03b3b;--warning:#fab219;}
   :root[data-theme="dark"]{color-scheme:dark;--page:#0d0d0d;--surface:#1a1a19;--ink:#fff;--ink-2:#c3c2b7;--muted:#898781;--grid:#2c2c2a;--baseline:#383835;--border:rgba(255,255,255,0.10);--accent:#3987e5;--s1:#3987e5;--s2:#d95926;--s3:#199e70;--good:#0ca30c;--good-text:#0ca30c;--critical:#d03b3b;--warning:#fab219;}
   @media (prefers-color-scheme:dark){:root:not([data-theme="light"]){color-scheme:dark;--page:#0d0d0d;--surface:#1a1a19;--ink:#fff;--ink-2:#c3c2b7;--muted:#898781;--grid:#2c2c2a;--baseline:#383835;--border:rgba(255,255,255,0.10);--accent:#3987e5;--s1:#3987e5;--s2:#d95926;--s3:#199e70;--good:#0ca30c;--good-text:#0ca30c;--critical:#d03b3b;--warning:#fab219;}}
   *{margin:0;padding:0;box-sizing:border-box}
@@ -34,12 +113,12 @@ const CSS = `
   .btn.primary{background:var(--accent);border-color:var(--accent);color:#fff}
   .term{background:#16161a;color:#e6e6ec;border-radius:12px;padding:4px 0 10px;margin:20px 0;overflow-x:auto;border:1px solid var(--border)}
   .term .thead{display:flex;gap:6px;padding:10px 14px 8px;border-bottom:1px solid #2a2a30;margin-bottom:6px}.term .dot{width:11px;height:11px;border-radius:50%;background:#3a3a42}
-  .tline{font-family:ui-monospace,"SF Mono",Menlo,monospace;font-size:13.5px;padding:5px 14px;cursor:pointer;white-space:pre;border-left:3px solid transparent}
+  .tline{display:block;width:100%;text-align:left;background:none;border:0;color:inherit;font-family:ui-monospace,"SF Mono",Menlo,monospace;font-size:13.5px;padding:5px 14px;cursor:pointer;white-space:pre;border-left:3px solid transparent}
   .tline:hover,.tline.active{background:#1f1f26;border-left-color:var(--accent)}.tline .prompt{color:#5fb85f}
   .term-explain{background:var(--surface);border:1px solid var(--border);border-radius:10px;padding:12px 16px;font-size:14px;color:var(--ink-2);min-height:52px;margin:-8px 0 20px}.term-explain b{color:var(--ink)}
   .check-item{background:var(--surface);border:1px solid var(--border);border-radius:12px;padding:14px 16px;margin:10px 0}
   .check-item label{display:flex;gap:12px;align-items:flex-start;cursor:pointer;font-weight:600}.check-item input{width:18px;height:18px;margin-top:3px;accent-color:var(--good)}
-  .check-item .desc{font-size:14px;color:var(--ink-2);font-weight:400;margin-top:2px}.check-item details{margin:8px 0 0 30px;font-size:13.5px;color:var(--ink-2)}
+  .check-item .desc{display:block;font-size:14px;color:var(--ink-2);font-weight:400;margin-top:2px}.check-item details{margin:8px 0 0 30px;font-size:13.5px;color:var(--ink-2)}
   .check-item summary{cursor:pointer;color:var(--accent);font-weight:600;font-size:13px}.check-item.done label{text-decoration:line-through;color:var(--muted)}
   .quiz-q{background:var(--surface);border:1px solid var(--border);border-radius:14px;padding:18px 20px;margin:14px 0}.quiz-q .qt{font-weight:700;margin-bottom:10px}
   .quiz-opt{display:block;width:100%;text-align:left;margin:6px 0;padding:10px 14px;border-radius:9px;border:1px solid var(--border);background:var(--page);color:var(--ink);cursor:pointer;font-size:14.5px}
@@ -49,21 +128,34 @@ const CSS = `
   .nextcard{display:flex;justify-content:space-between;align-items:center;gap:16px;background:var(--surface);border:1px solid var(--border);border-radius:14px;padding:20px;margin-top:48px;text-decoration:none;color:inherit;cursor:pointer}
   .nextcard:hover{border-color:var(--accent)}.nextcard .nk{font-size:12px;text-transform:uppercase;letter-spacing:.08em;color:var(--muted);font-weight:700}.nextcard .nt{font-size:18px;font-weight:700}
   .foot{font-size:12.5px;color:var(--muted);margin-top:40px}
+  /* Keyboard users must be able to see where they are — every interactive element. */
+  :focus-visible{outline:2px solid var(--accent);outline-offset:2px;border-radius:4px}
+  .skip{position:absolute;left:-9999px;top:0;background:var(--accent);color:#fff;padding:10px 16px;border-radius:0 0 8px 0;z-index:20;text-decoration:none;font-weight:600}
+  .skip:focus{left:0}
+  @media (prefers-reduced-motion:reduce){*,*::before,*::after{animation-duration:.001ms!important;animation-iteration-count:1!important;transition-duration:.001ms!important;scroll-behavior:auto!important}}
 `;
 
 export function renderLesson(c) {
   const slug = c.slug;
+  const hoistedCss = []; // CSS lifted out of model-authored fragments (see tidyFragment)
+  const lede = c.lede ? `<p class="lede">${tidyFragment(c.lede, hoistedCss)}</p>` : '';
   const tiles = (c.tiles || []).map(t =>
-    `<div class="tile"><div class="big">${esc(t.big)}</div><div class="lbl">${t.lbl || ''}</div>${t.note ? `<div class="note">${t.note}</div>` : ''}</div>`).join('');
+    `<div class="tile"><div class="big">${esc(t.big)}</div><div class="lbl">${tidyFragment(t.lbl, hoistedCss)}</div>${t.note ? `<div class="note">${tidyFragment(t.note, hoistedCss)}</div>` : ''}</div>`).join('');
   const sections = (c.sections || []).map(s =>
-    `<h2>${esc(s.h2)}</h2>${s.html || ''}`).join('\n');
-  const analogy = c.analogy ? `<div class="analogy"><span class="tag">${esc(c.analogy.tag || 'Analogy')}</span><p>${c.analogy.text || ''}</p></div>` : '';
-  const sim = c.simulation ? `<div class="simwrap"><div class="ctitle">${esc(c.simulation.title || '')}</div><div class="csub">${esc(c.simulation.sub || '')}</div>${c.simulation.html || ''}</div>${c.simulation.js ? `<script>${c.simulation.js}</script>` : ''}` : '';
-  const widgets = renderWidgets(c.widgets);
-  const term = (c.terminal && c.terminal.length) ? `<div class="term"><div class="thead"><div class="dot"></div><div class="dot"></div><div class="dot"></div></div>${c.terminal.map(t => `<div class="tline" data-x="${esc(t.explain)}"><span class="prompt">$</span> ${esc(t.cmd)}</div>`).join('')}</div><div class="term-explain" id="termExplain">👆 <b>Click a command</b> to decode it.</div>` : '';
+    `<h2>${esc(s.h2)}</h2>${tidyFragment(s.html, hoistedCss)}`).join('\n');
+  const analogy = c.analogy ? `<div class="analogy"><span class="tag">${esc(c.analogy.tag || 'Analogy')}</span><p>${tidyFragment(c.analogy.text, hoistedCss)}</p></div>` : '';
+  const sim = c.simulation ? `<div class="simwrap"><div class="ctitle">${esc(c.simulation.title || '')}</div><div class="csub">${esc(c.simulation.sub || '')}</div>${tidyFragment(c.simulation.html, hoistedCss)}</div>${c.simulation.js ? `<script>${tidyScript(c.simulation.js)}</script>` : ''}` : '';
+  const widgets = renderWidgets(c.widgets, hoistedCss);
+  const term = (c.terminal && c.terminal.length) ? `<div class="term"><div class="thead"><div class="dot"></div><div class="dot"></div><div class="dot"></div></div>${c.terminal.map(t => `<button type="button" class="tline" aria-pressed="false" data-x="${esc(t.explain)}"><span class="prompt" aria-hidden="true">$</span> ${esc(t.cmd)}</button>`).join('')}</div><div class="term-explain" id="termExplain" role="status" aria-live="polite">👆 <b>Click a command</b> to decode it.</div>` : '';
   const checklist = (c.checklist || []).map((it, i) =>
-    `<div class="check-item"><label><input type="checkbox" data-c="${i}"><span>${esc(it.title)}<div class="desc">${it.desc || ''}</div></span></label>${it.hint ? `<details><summary>Stuck? Hint</summary>${esc(it.hint)}</details>` : ''}</div>`).join('');
-  const next = c.next ? `<a class="nextcard" href="${esc(c.next.stem)}.html"><div><div class="nk">Up next</div><div class="nt">${esc(c.next.title)}</div><div style="font-size:14px;color:var(--ink-2)">${esc(c.next.desc || '')}</div></div><div style="font-size:28px">→</div></a>` : '';
+    `<div class="check-item"><label><input type="checkbox" data-c="${i}"><span>${esc(it.title)}<span class="desc">${tidyFragment(it.desc, hoistedCss)}</span></span></label>${it.hint ? `<details><summary>Stuck? Hint</summary>${esc(it.hint)}</details>` : ''}</div>`).join('');
+  // `next: null` means "last lesson of a course" (the course builder sets it explicitly);
+  // `undefined` means a standalone lesson, which has no dashboard to return to.
+  const next = c.next
+    ? `<a class="nextcard" href="${esc(c.next.stem)}.html"><div><div class="nk">Up next</div><div class="nt">${esc(c.next.title)}</div><div style="font-size:14px;color:var(--ink-2)">${esc(c.next.desc || '')}</div></div><div style="font-size:28px">→</div></a>`
+    : c.next === null
+      ? `<a class="nextcard" href="index.html"><div><div class="nk">Course complete</div><div class="nt">Back to ${esc(c.courseTitle || 'the dashboard')}</div><div style="font-size:14px;color:var(--ink-2)">Review your mastery map and revisit anything shaky.</div></div><div style="font-size:28px">🎓</div></a>`
+      : '';
 
   const quizData = JSON.stringify(c.quiz || []);
 
@@ -74,19 +166,21 @@ export function renderLesson(c) {
 <meta name="viewport" content="width=device-width, initial-scale=1.0">
 <title>${esc(c.title)} — coursecast</title>
 <style>${CSS}</style>
+${hoistedCss.length ? `<style>${hoistedCss.join("\n")}</style>` : ''}
 <script>try{var t=localStorage.getItem("cc-theme");if(t)document.documentElement.dataset.theme=t;}catch(e){}</script>
 </head>
 <body>
-<div class="topbar">
-  <div class="crumb">🎓 ${esc(c.courseTitle || 'coursecast')} · <b>${esc(c.lessonLabel || '')} — ${esc(c.title)}</b></div>
+<a class="skip" href="#lesson-main">Skip to content</a>
+<header class="topbar">
+  <div class="crumb">${c.courseTitle ? `<a class="crumb-home" href="index.html">🎓 ${esc(c.courseTitle)}</a>` : '🎓 coursecast'} · <b>${esc(c.lessonLabel || '')} — ${esc(c.title)}</b></div>
   <div class="progressbar"><div id="lessonProgress"></div></div>
-  <button class="theme-btn" id="themeBtn">◐ Theme</button>
-</div>
-<div class="wrap">
+  <button type="button" class="theme-btn" id="themeBtn">◐ Theme</button>
+</header>
+<main class="wrap" id="lesson-main">
   <div class="hero">
     ${c.kicker ? `<div class="kicker">${esc(c.kicker)}</div>` : ''}
     <h1>${esc(c.title)}</h1>
-    ${c.lede ? `<p class="lede">${c.lede}</p>` : ''}
+    ${lede}
   </div>
   ${tiles ? `<div class="tiles">${tiles}</div>` : ''}
   ${analogy}
@@ -98,7 +192,7 @@ export function renderLesson(c) {
   ${(c.quiz && c.quiz.length) ? `<h2>🧠 Prove it</h2><div id="quiz"></div><div class="quiz-score" id="quizScore"><div class="big"></div><div class="msg" style="color:var(--ink-2)"></div></div>` : ''}
   ${next}
   <p class="foot">Generated by the <b>coursecast</b> CLI · ${esc(c.footer || '')}</p>
-</div>
+</main>
 <script>
 (function(){
   var KEY=${JSON.stringify("cc-" + slug)}, state={};
@@ -112,8 +206,8 @@ export function renderLesson(c) {
     root.dataset.theme=nx;try{localStorage.setItem('cc-theme',nx)}catch(e){}
   });
   document.querySelectorAll('.tline').forEach(function(l){l.addEventListener('click',function(){
-    document.querySelectorAll('.tline').forEach(function(x){x.classList.remove('active')});
-    l.classList.add('active');document.getElementById('termExplain').innerHTML='<b>What this does:</b> '+l.dataset.x;
+    document.querySelectorAll('.tline').forEach(function(x){x.classList.remove('active');x.setAttribute('aria-pressed','false')});
+    l.classList.add('active');l.setAttribute('aria-pressed','true');document.getElementById('termExplain').innerHTML='<b>What this does:</b> '+l.dataset.x;
   })});
   var checks=document.querySelectorAll('.check-item input[type=checkbox]');
   var QUIZ=${quizData};
@@ -127,7 +221,7 @@ export function renderLesson(c) {
   var quizEl=document.getElementById('quiz'),answered=0,score=0;
   if(quizEl)QUIZ.forEach(function(item,qi){var card=document.createElement('div');card.className='quiz-q';
     card.innerHTML='<div class="qt">'+(qi+1)+'. '+item.q+'</div>';
-    item.opts.forEach(function(opt,oi){var b=document.createElement('button');b.className='quiz-opt';b.textContent=opt;
+    item.opts.forEach(function(opt,oi){var b=document.createElement('button');b.type='button';b.className='quiz-opt';b.textContent=opt;
       b.addEventListener('click',function(){if(card.dataset.done)return;card.dataset.done='1';
         var right=oi===item.a;if(right){score++;b.classList.add('correct')}else{b.classList.add('wrong');card.querySelectorAll('.quiz-opt')[item.a].classList.add('correct')}
         var fb=card.querySelector('.quiz-fb');fb.style.display='block';fb.innerHTML=(right?'✅ <b>Nailed it.</b> ':'❌ <b>Not quite.</b> ')+(item.fb||'');

package/src/widgets/flashcards.mjs

@@ -27,9 +27,9 @@ export function render(config, id) {
   <div class="fc-meta">${cards.length} cards · click the card to flip</div>
   <div class="fc-card" data-card><span class="hint" data-side>Front</span><span data-face></span></div>
   <div class="fc-ctrls">
-    <button class="fc-btn" data-prev>‹ Prev</button>
-    <button class="fc-btn" data-next>Next ›</button>
-    <button class="fc-btn good" data-known>✓ I knew it</button>
+    <button type="button" class="fc-btn" data-prev>‹ Prev</button>
+    <button type="button" class="fc-btn" data-next>Next ›</button>
+    <button type="button" class="fc-btn good" data-known>✓ I knew it</button>
     <span class="fc-prog" data-prog></span>
   </div>
   <script>(function(){

package/src/widgets/index.mjs

@@ -6,8 +6,11 @@
 // self-contained HTML. Every widget is vanilla JS, no CDNs, no build step — so a lesson
 // stays one offline file with no asset inliner needed.
 //
-// A widget module exports: `type` (string) and `render(config, id) -> htmlString`.
-// `id` is a unique per-instance prefix so multiple widgets can share a page safely.
+// A widget module exports: `type` (string) and `render(config, id)`, returning either an
+// HTML string or `{ html, css }`. `id` is a unique per-instance prefix so multiple widgets
+// can share a page safely. CSS is returned separately (not inside a <style> in the markup)
+// because a <style> element inside a <div> is invalid HTML — the page renderer collects it
+// and emits it in <head>.
 
 import * as whatIf from './what-if.mjs';
 import * as flashcards from './flashcards.mjs';
@@ -31,12 +34,25 @@ export const jsonInline = (v) => JSON.stringify(v)
 
 // Render a lesson's widgets array to a single HTML string. Unknown/invalid widgets are
 // skipped (never crash a whole lesson over one bad widget).
-export function renderWidgets(widgets) {
+//
+// Each widget writes its own id-scoped CSS next to its markup, which keeps the widget
+// modules self-contained and readable — but a <style> element inside a <div> is invalid
+// HTML. So the style blocks are lifted out here and handed to `cssSink` for the page
+// renderer to emit in <head>. Doing it centrally means widget authors keep writing their
+// CSS inline and never have to think about it. The CSS is already `#id`-scoped, so moving
+// it changes nothing visually.
+export function renderWidgets(widgets, cssSink) {
   if (!Array.isArray(widgets) || !widgets.length) return '';
   return widgets.map((w, i) => {
     const mod = w && REGISTRY[w.type];
     if (!mod) return '';
-    try { return mod.render(w.config || {}, `w${i}`); }
-    catch { return ''; }
+    try {
+      const html = mod.render(w.config || {}, `w${i}`);
+      if (!cssSink) return html;
+      return String(html).replace(/<style>([\s\S]*?)<\/style>/gi, (_m, css) => {
+        cssSink.push(css);
+        return '';
+      });
+    } catch { return ''; }
   }).filter(Boolean).join('\n');
 }

package/src/widgets/reveal-diagram.mjs

@@ -37,9 +37,9 @@ export function render(config, id) {
   <div class="rd-meta">Reveal the flow step by step</div>
   <div data-nodes>${items}</div>
   <div class="rd-ctrls">
-    <button class="rd-btn primary" data-next>Reveal next ↓</button>
-    <button class="rd-btn" data-all>Show all</button>
-    <button class="rd-btn" data-reset>Reset</button>
+    <button type="button" class="rd-btn primary" data-next>Reveal next ↓</button>
+    <button type="button" class="rd-btn" data-all>Show all</button>
+    <button type="button" class="rd-btn" data-reset>Reset</button>
     <span class="rd-prog" data-prog></span>
   </div>
   <script>(function(){