coursecast 0.1.0

package/src/render.mjs

@@ -0,0 +1,147 @@
+// render.mjs — turns a lesson content object into a self-contained interactive HTML page.
+// The content is engine-produced (AI or stub); the presentation lives entirely here,
+// so every lesson looks like one product regardless of who generated the content.
+
+import { progressSnippet } from './progress-client.mjs';
+import { renderWidgets } from './widgets/index.mjs';
+
+const esc = (s = '') => String(s)
+  .replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;')
+  .replace(/"/g, '&quot;');
+
+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[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}
+  body{font-family:system-ui,-apple-system,"Segoe UI",sans-serif;background:var(--page);color:var(--ink);line-height:1.6}
+  .wrap{max-width:880px;margin:0 auto;padding:0 20px 80px}
+  .topbar{position:sticky;top:0;z-index:10;background:var(--page);border-bottom:1px solid var(--grid);padding:10px 20px;display:flex;align-items:center;gap:12px}
+  .topbar .crumb{font-size:13px;color:var(--ink-2);flex:1}.topbar .crumb b{color:var(--ink)}
+  .progressbar{height:6px;width:160px;background:var(--grid);border-radius:3px;overflow:hidden}.progressbar>div{height:100%;width:0;background:var(--good);border-radius:3px;transition:width .4s}
+  .theme-btn{border:1px solid var(--border);background:var(--surface);color:var(--ink);border-radius:8px;padding:4px 10px;cursor:pointer;font-size:13px}
+  .hero{padding:56px 0 8px}.kicker{font-size:13px;letter-spacing:.12em;text-transform:uppercase;color:var(--accent);font-weight:700}
+  h1{font-size:40px;line-height:1.15;margin:8px 0 16px}.lede{font-size:19px;color:var(--ink-2);max-width:640px}
+  h2{font-size:26px;margin:64px 0 6px;scroll-margin-top:64px}p{margin:12px 0;max-width:680px}
+  .tiles{display:grid;grid-template-columns:repeat(auto-fit,minmax(180px,1fr));gap:12px;margin:28px 0}
+  .tile{background:var(--surface);border:1px solid var(--border);border-radius:12px;padding:18px 20px}
+  .tile .big{font-size:34px;font-weight:700;line-height:1.1}.tile .lbl{font-size:13px;color:var(--ink-2);margin-top:4px}.tile .note{font-size:11px;color:var(--muted);margin-top:6px}
+  .analogy{background:var(--surface);border:1px solid var(--border);border-left:4px solid var(--accent);border-radius:10px;padding:16px 20px;margin:20px 0;max-width:680px}
+  .analogy .tag{font-size:12px;font-weight:700;color:var(--accent);text-transform:uppercase;letter-spacing:.08em}
+  .simwrap{background:var(--surface);border:1px solid var(--border);border-radius:14px;padding:20px;margin:24px 0}
+  .simwrap .ctitle{font-weight:700}.simwrap .csub{font-size:12.5px;color:var(--muted);margin-bottom:8px}
+  .btn{border:1px solid var(--border);background:var(--page);color:var(--ink);border-radius:8px;padding:8px 14px;cursor:pointer;font-size:14px;font-weight:600}
+  .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: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 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}
+  .quiz-opt:hover{border-color:var(--accent)}.quiz-opt.correct{border-color:var(--good);background:color-mix(in srgb,var(--good) 12%,var(--page));font-weight:600}
+  .quiz-opt.wrong{border-color:var(--critical);background:color-mix(in srgb,var(--critical) 8%,var(--page))}.quiz-fb{font-size:13.5px;margin-top:8px;display:none;color:var(--ink-2)}
+  .quiz-score{text-align:center;padding:26px;background:var(--surface);border:1px solid var(--border);border-radius:14px;margin:20px 0;display:none}.quiz-score .big{font-size:42px;font-weight:700}
+  .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}
+`;
+
+export function renderLesson(c) {
+  const slug = c.slug;
+  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('');
+  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>` : '';
+  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>` : '';
+
+  const quizData = JSON.stringify(c.quiz || []);
+
+  return `<!DOCTYPE html>
+<html lang="en">
+<head>
+<meta charset="UTF-8">
+<meta name="viewport" content="width=device-width, initial-scale=1.0">
+<title>${esc(c.title)} — coursecast</title>
+<style>${CSS}</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>
+  <div class="progressbar"><div id="lessonProgress"></div></div>
+  <button class="theme-btn" id="themeBtn">◐ Theme</button>
+</div>
+<div class="wrap">
+  <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>` : ''}
+  </div>
+  ${tiles ? `<div class="tiles">${tiles}</div>` : ''}
+  ${analogy}
+  ${sections}
+  ${sim}
+  ${widgets}
+  ${term}
+  ${checklist ? `<h2>🛠️ Touch it for real</h2>${checklist}` : ''}
+  ${(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>
+<script>
+(function(){
+  var KEY=${JSON.stringify("cc-" + slug)}, state={};
+  try{var _s=JSON.parse(localStorage.getItem(KEY)||'{}');if(_s&&typeof _s==='object'&&!Array.isArray(_s))state=_s;}catch(e){}
+  function save(){try{localStorage.setItem(KEY,JSON.stringify(state))}catch(e){}}
+  var root=document.documentElement;
+  var tb=document.getElementById('themeBtn');
+  if(tb)tb.addEventListener('click',function(){
+    var d=matchMedia('(prefers-color-scheme: dark)').matches;
+    var cur=root.dataset.theme||(d?'dark':'light');var nx=cur==='dark'?'light':'dark';
+    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;
+  })});
+  var checks=document.querySelectorAll('.check-item input[type=checkbox]');
+  var QUIZ=${quizData};
+  function progress(){var d=0;checks.forEach(function(c){if(c.checked)d++});
+    var q=state.quizScore!=null?1:0;var tot=checks.length+(QUIZ.length?1:0);
+    var pct=tot?Math.round(((d+q)/tot)*100):0;var el=document.getElementById('lessonProgress');if(el)el.style.width=pct+'%';}
+  checks.forEach(function(c){c.checked=!!(state.checks&&state.checks[c.dataset.c]);
+    c.closest('.check-item').classList.toggle('done',c.checked);
+    c.addEventListener('change',function(){state.checks=state.checks||{};state.checks[c.dataset.c]=c.checked;
+      c.closest('.check-item').classList.toggle('done',c.checked);save();progress()})});
+  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;
+      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||'');
+        if(++answered===QUIZ.length){state.quizScore=score;save();progress();
+          var el=document.getElementById('quizScore');el.style.display='block';
+          el.querySelector('.big').textContent=score+' / '+QUIZ.length;
+          el.querySelector('.msg').textContent=score===QUIZ.length?'🏆 Perfect!':score>=Math.ceil(QUIZ.length*0.6)?'💪 Solid — review what you missed and continue.':'🌱 Good start — revisit the sections above and try again.';}
+      });card.appendChild(b)});
+    var fb=document.createElement('div');fb.className='quiz-fb';card.appendChild(fb);quizEl.appendChild(card)});
+  progress();
+})();
+</script>
+${progressSnippet(slug)}
+${c.storageSnippet || ''}
+</body>
+</html>`;
+}

package/src/storage/cloud.mjs

@@ -0,0 +1,48 @@
+// cloud storage backend (opt-in, --storage cloud) — syncs progress across devices via a
+// sync-code/link, with NO accounts and NO database console: the token IS the credential.
+//
+// SCAFFOLD STATE: the client sync adapter below is real, but stays INERT until the page
+// is served with `window.__COURSECAST_API__` set (injected by the cloud deploy step, which
+// is the "cloud next" work: the /api/progress routes + auto-provisioned KV store). Without
+// it, the page behaves exactly like local mode. This is the clean seam between the two.
+
+export const name = 'cloud';
+export const needsBackend = true;
+
+export function clientSnippet(/* slug */) {
+  return `<!-- coursecast-sync -->
+<script>(function(){
+  var API=((window.__COURSECAST_API__)||'').replace(/\\/$/,'');
+  var TKEY='cc-sync-token', PKEY='cc-progress';
+  function q(k){try{return new URLSearchParams(location.search).get(k)}catch(e){return null}}
+  // Adopt a token arriving via ?sync=… (opening the sync link on a new device).
+  var incoming=q('sync'); if(incoming){try{localStorage.setItem(TKEY,incoming)}catch(e){}}
+  var token=null; try{token=localStorage.getItem(TKEY)}catch(e){}
+  function read(){var v;try{v=JSON.parse(localStorage.getItem(PKEY)||'{}')}catch(e){}return (v&&typeof v==='object'&&!Array.isArray(v))?v:{};}
+  function writeLocal(o){try{localStorage.setItem(PKEY,JSON.stringify(o))}catch(e){}}
+  function merge(remote){ // per-lesson newest-timestamp wins
+    var local=read(),out={},k;
+    for(k in local)out[k]=local[k];
+    for(k in remote){ if(!out[k]||((remote[k]&&remote[k].ts)||0)>((out[k]&&out[k].ts)||0))out[k]=remote[k]; }
+    writeLocal(out); return out;
+  }
+  // Public hooks the dashboard's "Sync across devices" UI will call (cloud-next).
+  window.coursecastSync={
+    enabled:function(){return !!API;},
+    hasToken:function(){return !!token;},
+    link:function(){return token?(location.origin+location.pathname.replace(/[^/]*$/,'')+'?sync='+encodeURIComponent(token)):null;},
+    create:function(){ if(!API)return Promise.reject(new Error('cloud API not configured'));
+      return fetch(API+'/api/progress/new',{method:'POST'}).then(function(r){return r.json()}).then(function(j){token=j.token;try{localStorage.setItem(TKEY,token)}catch(e){}push();return token;}); },
+    use:function(t){ token=t; try{localStorage.setItem(TKEY,t)}catch(e){} return pull(); }
+  };
+  function pull(){ if(!API||!token)return Promise.resolve();
+    return fetch(API+'/api/progress/'+encodeURIComponent(token)).then(function(r){return r.ok?r.json():null}).then(function(j){if(j&&j.progress)merge(j.progress);}).catch(function(){}); }
+  function push(){ if(!API||!token)return;
+    try{fetch(API+'/api/progress/'+encodeURIComponent(token),{method:'PUT',headers:{'content-type':'application/json'},body:JSON.stringify({progress:read()})})}catch(e){} }
+  if(!API)return; // not deployed in cloud mode yet -> pure local behavior
+  pull();
+  var last=null; try{last=localStorage.getItem(PKEY)}catch(e){}
+  setInterval(function(){var cur=null;try{cur=localStorage.getItem(PKEY)}catch(e){}; if(cur!==last){last=cur;push();}},1500);
+  window.addEventListener('beforeunload',push);
+})();</script>`;
+}

package/src/storage/index.mjs

@@ -0,0 +1,14 @@
+// Storage backend loader — the third pluggable axis (alongside engines and providers).
+// A backend decides how a generated course persists progress:
+//   local (default) — localStorage only, zero setup, no server.
+//   cloud           — sync across devices via a sync-code/link (client adapter is inert
+//                     until the cloud API is wired at deploy time).
+
+export const BACKENDS = ['local', 'cloud'];
+
+export async function loadStorage(id = 'local') {
+  if (!BACKENDS.includes(id)) {
+    throw new Error(`Unknown storage backend "${id}". Available: ${BACKENDS.join(', ')}.`);
+  }
+  return import(`./${id}.mjs`);
+}

package/src/storage/local.mjs

@@ -0,0 +1,10 @@
+// local storage backend (default) — progress lives in the browser's localStorage only.
+// Zero setup, no server, no account. The lesson's embedded progress reporter already
+// handles localStorage, so this backend adds nothing to the page.
+
+export const name = 'local';
+export const needsBackend = false;
+
+export function clientSnippet(/* slug */) {
+  return '';
+}

package/src/widgets/flashcards.mjs

@@ -0,0 +1,51 @@
+// flashcards — spaced-recall practice. Flip a card, mark known/unknown, track progress.
+// config = { title, cards: [{ front, back }] }
+import { esc, jsonInline } from './index.mjs';
+
+export const type = 'flashcards';
+
+export function render(config, id) {
+  const cards = (Array.isArray(config.cards) ? config.cards : [])
+    .filter(c => c && (c.front || c.back))
+    .map(c => ({ front: String(c.front || ''), back: String(c.back || '') }));
+  if (!cards.length) return '';
+
+  return `<div class="widget fc" id="${id}">
+  <style>
+    #${id}.fc{background:var(--surface);border:1px solid var(--border);border-radius:14px;padding:18px 20px;margin:24px 0}
+    #${id} .fc-t{font-weight:700;margin-bottom:4px}
+    #${id} .fc-meta{font-size:12.5px;color:var(--muted);margin-bottom:12px}
+    #${id} .fc-card{border:1px solid var(--border);border-radius:12px;background:var(--page);min-height:120px;display:flex;align-items:center;justify-content:center;text-align:center;padding:22px;cursor:pointer;user-select:none;font-size:17px}
+    #${id} .fc-card .hint{position:absolute;top:8px;right:12px;font-size:11px;color:var(--muted);text-transform:uppercase;letter-spacing:.06em}
+    #${id} .fc-card{position:relative}
+    #${id} .fc-ctrls{display:flex;gap:8px;align-items:center;margin-top:12px;flex-wrap:wrap}
+    #${id} .fc-btn{border:1px solid var(--border);background:var(--page);color:var(--ink);border-radius:8px;padding:7px 12px;cursor:pointer;font-size:13.5px;font-weight:600}
+    #${id} .fc-btn.good{border-color:var(--good);color:var(--good-text)}
+    #${id} .fc-prog{margin-left:auto;font-size:12.5px;color:var(--ink-2);font-variant-numeric:tabular-nums}
+  </style>
+  ${config.title ? `<div class="fc-t">${esc(config.title)}</div>` : ''}
+  <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>
+    <span class="fc-prog" data-prog></span>
+  </div>
+  <script>(function(){
+    var root=document.getElementById(${jsonInline(id)}), CARDS=${jsonInline(cards)};
+    var i=0, flipped=false, known={};
+    var face=root.querySelector('[data-face]'), side=root.querySelector('[data-side]'), prog=root.querySelector('[data-prog]');
+    function draw(){
+      face.textContent=flipped?CARDS[i].back:CARDS[i].front;
+      side.textContent=flipped?'Back':'Front';
+      prog.textContent='Card '+(i+1)+'/'+CARDS.length+' · '+Object.keys(known).length+' known';
+    }
+    root.querySelector('[data-card]').addEventListener('click',function(){flipped=!flipped;draw();});
+    root.querySelector('[data-next]').addEventListener('click',function(){i=(i+1)%CARDS.length;flipped=false;draw();});
+    root.querySelector('[data-prev]').addEventListener('click',function(){i=(i-1+CARDS.length)%CARDS.length;flipped=false;draw();});
+    root.querySelector('[data-known]').addEventListener('click',function(){known[i]=true;i=(i+1)%CARDS.length;flipped=false;draw();});
+    draw();
+  })();</script>
+  </div>`;
+}

package/src/widgets/index.mjs

@@ -0,0 +1,42 @@
+// Widget typology catalog — the "generative UI, flavor 2" layer.
+//
+// Instead of the AI emitting raw simulation code (flexible but inconsistent), a lesson can
+// carry a `widgets: [{ type, config }]` array. The engine just picks a proven type and
+// fills in its config; these renderers turn that data into interactive, dependency-free,
+// 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.
+
+import * as whatIf from './what-if.mjs';
+import * as flashcards from './flashcards.mjs';
+import * as revealDiagram from './reveal-diagram.mjs';
+
+const REGISTRY = Object.fromEntries(
+  [whatIf, flashcards, revealDiagram].map(w => [w.type, w])
+);
+
+export const WIDGET_TYPES = Object.keys(REGISTRY);
+
+export const esc = (s = '') => String(s)
+  .replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;')
+  .replace(/"/g, '&quot;').replace(/'/g, '&#39;');
+
+// Serialize a value for embedding inside an inline <script>. JSON.stringify does NOT escape
+// "<", so a "</script>" in any string would break out of the script element — escape the
+// angle brackets so no embedded string can terminate the script tag.
+export const jsonInline = (v) => JSON.stringify(v)
+  .replace(/</g, "\\u003c").replace(/>/g, "\\u003e");
+
+// 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) {
+  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 ''; }
+  }).filter(Boolean).join('\n');
+}

package/src/widgets/reveal-diagram.mjs

@@ -0,0 +1,61 @@
+// reveal-diagram — a step-by-step flow/process the learner reveals one node at a time,
+// so a sequence (pipeline, lifecycle, decision path) unfolds instead of dumping all at once.
+// config = { title, nodes: [{ label, detail }] }
+import { esc } from './index.mjs';
+
+export const type = 'reveal-diagram';
+
+export function render(config, id) {
+  const nodes = (Array.isArray(config.nodes) ? config.nodes : [])
+    .filter(n => n && n.label)
+    .map(n => ({ label: String(n.label), detail: String(n.detail || '') }));
+  if (!nodes.length) return '';
+
+  const items = nodes.map((n, k) => `<div class="rd-node" data-k="${k}" hidden>
+      <div class="rd-box"><span class="rd-num">${k + 1}</span><span class="rd-label">${esc(n.label)}</span></div>
+      ${n.detail ? `<div class="rd-detail">${esc(n.detail)}</div>` : ''}
+      ${k < nodes.length - 1 ? '<div class="rd-arrow">↓</div>' : ''}
+    </div>`).join('');
+
+  return `<div class="widget rd" id="${id}">
+  <style>
+    #${id}.rd{background:var(--surface);border:1px solid var(--border);border-radius:14px;padding:18px 20px;margin:24px 0}
+    #${id} .rd-t{font-weight:700;margin-bottom:4px}
+    #${id} .rd-meta{font-size:12.5px;color:var(--muted);margin-bottom:12px}
+    #${id} .rd-node[hidden]{display:none}
+    #${id} .rd-box{display:flex;align-items:center;gap:10px;border:1px solid var(--border);background:var(--page);border-radius:10px;padding:10px 14px}
+    #${id} .rd-num{flex:0 0 24px;height:24px;border-radius:6px;background:color-mix(in srgb,var(--accent) 14%,var(--surface));color:var(--accent);font-weight:700;display:flex;align-items:center;justify-content:center;font-size:12px}
+    #${id} .rd-label{font-weight:600}
+    #${id} .rd-detail{font-size:13.5px;color:var(--ink-2);margin:6px 0 0 34px}
+    #${id} .rd-arrow{text-align:center;color:var(--muted);margin:4px 0}
+    #${id} .rd-ctrls{display:flex;gap:8px;align-items:center;margin-top:12px}
+    #${id} .rd-btn{border:1px solid var(--border);background:var(--page);color:var(--ink);border-radius:8px;padding:7px 12px;cursor:pointer;font-size:13.5px;font-weight:600}
+    #${id} .rd-btn.primary{background:var(--accent);border-color:var(--accent);color:#fff}
+    #${id} .rd-prog{margin-left:auto;font-size:12.5px;color:var(--ink-2)}
+  </style>
+  ${config.title ? `<div class="rd-t">${esc(config.title)}</div>` : ''}
+  <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>
+    <span class="rd-prog" data-prog></span>
+  </div>
+  <script>(function(){
+    var root=document.getElementById(${JSON.stringify(id)});
+    var nodes=root.querySelectorAll('.rd-node'), shown=0;
+    var next=root.querySelector('[data-next]'), prog=root.querySelector('[data-prog]');
+    function draw(){
+      nodes.forEach(function(n,k){n.hidden=k>=shown;});
+      prog.textContent=shown+'/'+nodes.length;
+      next.disabled=shown>=nodes.length;
+      next.style.opacity=next.disabled?0.5:1;
+    }
+    next.addEventListener('click',function(){if(shown<nodes.length){shown++;draw();}});
+    root.querySelector('[data-all]').addEventListener('click',function(){shown=nodes.length;draw();});
+    root.querySelector('[data-reset]').addEventListener('click',function(){shown=0;draw();});
+    draw();
+  })();</script>
+  </div>`;
+}

package/src/widgets/what-if.mjs

@@ -0,0 +1,99 @@
+// what-if — a parametric "calculator / mini-simulation": sliders for each variable, a live
+// computed output (author-supplied expression over the variables), and an optional bar.
+// config = {
+//   title, sub,
+//   variables: [{ name, label, min, max, default, step, unit }],   // name must be a JS identifier
+//   expression: "a * b / 100"     // arithmetic over the variable names + Math.* (validated)
+//   output: { label, unit, decimals, max }   // max => draw a bar scaled to it
+// }
+import { esc, jsonInline } from './index.mjs';
+
+export const type = 'what-if';
+const IDENT = /^[A-Za-z_$][\w$]*$/;
+
+export function render(config, id) {
+  // Only keep variables with a valid JS identifier name — an invalid name would break both
+  // the Function it feeds and the DOM selectors that reference it.
+  const vars = (Array.isArray(config.variables) ? config.variables : [])
+    .filter(v => v && IDENT.test(String(v.name || '')));
+  const out = config.output || {};
+  const decimals = clampInt(out.decimals, 0, 100, 2);
+
+  const rows = vars.map(v => {
+    let min = num(v.min, 0), max = num(v.max, 100);
+    if (max <= min) max = min + 1;
+    const def = clamp(num(v.default, min), min, max);
+    const step = Math.abs(num(v.step, (max - min) / 100)) || 1;
+    return `<div class="wi-row">
+      <label for="${id}-${esc(v.name)}">${esc(v.label || v.name)}</label>
+      <input type="range" id="${id}-${esc(v.name)}" data-v="${esc(v.name)}" min="${min}" max="${max}" step="${step}" value="${def}">
+      <span class="wi-val" data-for="${esc(v.name)}">${def}${v.unit ? ' ' + esc(v.unit) : ''}</span>
+    </div>`;
+  }).join('');
+
+  const meta = {
+    vars: vars.map(v => ({ name: v.name, unit: v.unit || '' })),
+    expr: String(config.expression || '0'),
+    out: { unit: out.unit || '', decimals, max: num(out.max, 0) },
+  };
+
+  return `<div class="widget wi" id="${id}">
+  <style>
+    #${id}.wi{background:var(--surface);border:1px solid var(--border);border-radius:14px;padding:18px 20px;margin:24px 0}
+    #${id} .wi-t{font-weight:700}#${id} .wi-s{font-size:12.5px;color:var(--muted);margin-bottom:10px}
+    #${id} .wi-row{display:grid;grid-template-columns:minmax(90px,1fr) 2fr auto;gap:12px;align-items:center;margin:8px 0}
+    #${id} .wi-row label{font-size:13.5px}#${id} input[type=range]{width:100%;accent-color:var(--accent);min-height:24px}
+    #${id} .wi-val{font-size:13px;color:var(--ink-2);font-variant-numeric:tabular-nums;min-width:56px;text-align:right}
+    #${id} .wi-out{margin-top:14px;padding-top:12px;border-top:1px solid var(--grid);display:flex;align-items:baseline;gap:8px;flex-wrap:wrap}
+    #${id} .wi-out .lbl{font-size:13px;color:var(--ink-2)}#${id} .wi-out .big{font-size:26px;font-weight:700;font-variant-numeric:tabular-nums}
+    #${id} .wi-bar{height:10px;background:var(--grid);border-radius:5px;overflow:hidden;margin-top:10px}
+    #${id} .wi-bar>div{height:100%;background:var(--accent);width:0;transition:width .15s}
+  </style>
+  ${config.title ? `<div class="wi-t">${esc(config.title)}</div>` : ''}
+  ${config.sub ? `<div class="wi-s">${esc(config.sub)}</div>` : ''}
+  ${rows}
+  <div class="wi-out"><span class="lbl">${esc(out.label || 'Result')}:</span><span class="big" data-out>—</span></div>
+  ${meta.out.max ? `<div class="wi-bar"><div data-bar></div></div>` : ''}
+  <script>(function(){
+    var root=document.getElementById(${jsonInline(id)}), M=${jsonInline(meta)};
+    var names=M.vars.map(function(v){return v.name});
+    // Validate the expression: numbers, operators, parens, the variable names, and Math.* only.
+    // Anything else (window, document, fetch, constructor, quotes, brackets…) is rejected, so
+    // an AI-authored expression can never execute arbitrary JS in the reader's browser.
+    function safe(expr){
+      if(typeof expr!=='string'||!/^[\\s0-9.+\\-*/%(),A-Za-z_$]*$/.test(expr))return null;
+      var allow={Math:1,abs:1,pow:1,sqrt:1,cbrt:1,min:1,max:1,round:1,floor:1,ceil:1,trunc:1,sign:1,log:1,log2:1,log10:1,exp:1,sin:1,cos:1,tan:1,atan:1,asin:1,acos:1,hypot:1,PI:1,E:1};
+      names.forEach(function(n){allow[n]=1});
+      var ids=expr.match(/[A-Za-z_$][\\w$]*/g)||[];
+      for(var i=0;i<ids.length;i++){if(!allow[ids[i]])return null;}
+      return expr;
+    }
+    var s=safe(M.expr), fn;
+    try{ fn=s?new Function(names.join(','),'"use strict";return ('+s+')'):function(){return NaN}; }
+    catch(e){ fn=function(){return NaN}; }
+    function sel(n){ return (window.CSS&&CSS.escape)?CSS.escape(n):n; }
+    function recompute(){
+      var r;
+      try{
+        var vals=names.map(function(n){var el=root.querySelector('[data-v="'+sel(n)+'"]');return el?parseFloat(el.value):0;});
+        r=fn.apply(null,vals);
+      }catch(e){ r=NaN; }
+      var o=root.querySelector('[data-out]');
+      o.textContent=(typeof r==='number'&&isFinite(r))?(r.toFixed(M.out.decimals)+(M.out.unit?' '+M.out.unit:'')):'—';
+      if(M.out.max){var b=root.querySelector('[data-bar]');var pct=Math.max(0,Math.min(100,(r/M.out.max)*100));b.style.width=(isFinite(pct)?pct:0)+'%';}
+    }
+    root.querySelectorAll('input[type=range]').forEach(function(el){
+      el.addEventListener('input',function(){
+        var s2=root.querySelector('.wi-val[data-for="'+sel(el.dataset.v)+'"]');
+        if(s2){var u=(M.vars.find(function(v){return v.name===el.dataset.v})||{}).unit;s2.textContent=el.value+(u?' '+u:'');}
+        recompute();
+      });
+    });
+    recompute();
+  })();</script>
+  </div>`;
+}
+
+function num(v, d) { const n = parseFloat(v); return Number.isFinite(n) ? n : d; }
+function clamp(v, lo, hi) { return Math.max(lo, Math.min(hi, v)); }
+function clampInt(v, lo, hi, d) { const n = parseInt(v, 10); return Number.isFinite(n) ? Math.max(lo, Math.min(hi, n)) : d; }