decklight 0.1.0

package/cli/bundle.mjs

@@ -0,0 +1,388 @@
+#!/usr/bin/env node
+/**
+ * decklight bundle — flatten Decklight decks into ONE self-contained HTML file
+ * (send it to anyone; opens from disk, no server, no sibling files).
+ *
+ *   decklight bundle <deck.html> [-o out.html] [--themes …]              single deck
+ *   decklight bundle <deck.html> --all [-o out.html] [--title "…"]       whole playlist, merged
+ *   decklight bundle <a.html> <b.html> … [-o out.html] [--title "…"]     explicit list, merged
+ *
+ * What gets inlined:
+ *   - the runtime  : <script src=…decklight.js>  → <script>…</script>
+ *   - structure css: <link …decklight.css>       → <style>…</style>
+ *   - themes       : the theme <link> is replaced by <style data-theme="name">
+ *                    blocks (inactive ones carry media="not all"; the engine's
+ *                    inline-theme mode toggles them — picker/?theme= work).
+ *   - terminals    : data-cast="url" casts are embedded and switched to
+ *                    data-cast-inline (fetch is blocked on file://).
+ *   - images       : <img src> → data: URIs.
+ *
+ * MERGE mode (--all or several inputs): every module's <section>s are
+ * concatenated into one deck, in order. Each module's first section gets
+ * data-module="<title>" — the engine's module menu (M) and chrome tag then
+ * navigate in-file instead of across files, and the per-module playlist
+ * config is stripped (it has no meaning inside a single file).
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+
+function fail(msg) {
+  process.stderr.write(`decklight bundle: ${msg}\n`);
+  process.exit(1);
+}
+
+// Inline <script> content must never contain "</script" (terminates the tag)
+// NOR "<!--" (flips the HTML tokenizer into script-data-escaped mode, after
+// which closers mis-parse — marked's comment regexes contain it). "\/" is an
+// identity escape everywhere. "<!--" is broken by rewriting the bang as a
+// backslash-u0021 unicode escape, NOT as backslash-bang: the latter is fine
+// in strings and flagless regexes but an INVALID escape inside u-flagged
+// regexes — highlight.js composes its XML grammar's comment regex with /imu
+// the first time a deck highlights language-html, which turned the old
+// escape into a lazy SyntaxError. The unicode escape is valid in strings,
+// templates, JSON, and regexes with or without the u flag.
+const scriptSafe = (s) => s.replace(/<\/script/gi, '<\\/script').replace(/<!--/g, '<\\u0021--');
+const jsonSafe = (s) => s.replace(/<\/script/gi, '<\\/script').replace(/<!--/g, '<\\u0021--');
+
+const escAttr = (s) => s.replace(/&/g, '&amp;').replace(/"/g, '&quot;').replace(/</g, '&lt;');
+
+// Unescape a single-quoted JS string body ('·', '’', \' …).
+function unescapeJs(raw) {
+  try {
+    return JSON.parse('"' + raw.replace(/\\'/g, "'").replace(/"/g, '\\"') + '"');
+  } catch {
+    return raw;
+  }
+}
+
+/** Locate the .decklight container and its content bounds (div-depth aware —
+ *  sections contain nested divs, so a lazy regex would close too early). */
+function containerBounds(html) {
+  const openM = html.match(/<div\b[^>]*class=["'][^"']*\bdecklight\b[^"']*["'][^>]*>/i);
+  if (!openM) return null;
+  const contentStart = openM.index + openM[0].length;
+  const re = /<div\b[^>]*>|<\/div>/gi;
+  re.lastIndex = contentStart;
+  let depth = 1, m;
+  while ((m = re.exec(html))) {
+    depth += m[0][1] === '/' ? -1 : 1;
+    if (depth === 0) {
+      return { start: openM.index, contentStart, contentEnd: m.index, end: m.index + m[0].length };
+    }
+  }
+  return null;
+}
+
+/** Cut `const PLAYLIST = {…};` (brace-matched) and the `playlist: X` init
+ *  property out of a merged deck — cross-file navigation has no meaning
+ *  inside one file; in-file data-module markers replace it. */
+function stripPlaylist(html) {
+  const declM = html.match(/const\s+PLAYLIST\s*=\s*/);
+  if (declM) {
+    let i = declM.index + declM[0].length, depth = 0, end = -1;
+    for (; i < html.length; i++) {
+      const c = html[i];
+      if (c === '{') depth++;
+      else if (c === '}') { depth--; if (depth === 0) { end = i + 1; break; } }
+    }
+    if (end !== -1) {
+      if (html[end] === ';') end++;
+      html = html.slice(0, declM.index) + html.slice(end);
+    }
+  }
+  html = html.replace(/,\s*playlist\s*:\s*(?:[A-Za-z_$][\w$]*|\{[^{}]*\})/, '');
+  html = html.replace(/playlist\s*:\s*(?:[A-Za-z_$][\w$]*|\{[^{}]*\})\s*,\s*/, '');
+  return html;
+}
+
+/** Parse the playlist modules ({title, href} pairs) out of a deck's source. */
+function parsePlaylist(html) {
+  const out = [];
+  const re = /\{\s*title:\s*'((?:[^'\\]|\\.)*)'\s*,\s*href:\s*'((?:[^'\\]|\\.)*)'\s*\}/g;
+  let m;
+  while ((m = re.exec(html))) out.push({ title: unescapeJs(m[1]), href: unescapeJs(m[2]) });
+  return out;
+}
+
+function titleOf(html, fallback) {
+  const m = html.match(/<title>([^<]*)<\/title>/i);
+  return m ? m[1].replace(/\s*\([^)]*port\)\s*$/i, '').trim() : fallback;
+}
+
+// ------------------------------------------------------------------- merge
+
+/**
+ * Merge module decks into the first one: concatenated sections, per-module
+ * data-module markers on each first section, cast <script type=json> blocks
+ * carried along with per-module id prefixes, relative asset refs rebased
+ * onto the first deck's directory.
+ */
+function mergeDecks(jobs, baseDir, notices) {
+  const base = fs.readFileSync(jobs[0].path, 'utf8');
+  const baseBounds = containerBounds(base);
+  if (!baseBounds) fail(`no .decklight container in ${jobs[0].path}`);
+
+  const markSections = (inner, title) =>
+    inner.replace(/<section\b/, `<section data-module="${escAttr(title)}"`);
+
+  const castScriptRe = /<script\b[^>]*type=["']application\/json["'][^>]*id=["']([^"']+)["'][^>]*>[\s\S]*?<\/script>/gi;
+
+  let mergedInner = markSections(
+    base.slice(baseBounds.contentStart, baseBounds.contentEnd), jobs[0].title);
+  const carried = [];
+  const seenIds = new Set([...base.matchAll(castScriptRe)].map((m) => m[1]));
+
+  for (let k = 1; k < jobs.length; k++) {
+    const { path: modPath, title } = jobs[k];
+    let mod = fs.readFileSync(modPath, 'utf8');
+    const modDir = path.dirname(modPath);
+    const prefix = `m${k + 1}-`;
+
+    // Pull the module's embedded cast blocks out (they live outside the
+    // container) and prefix their ids so merged ids stay unique.
+    const blocks = [];
+    mod = mod.replace(castScriptRe, (tag, id) => {
+      blocks.push(tag.replace(`id="${id}"`, `id="${prefix}${id}"`)
+                     .replace(`id='${id}'`, `id='${prefix}${id}'`));
+      return '';
+    });
+
+    const bounds = containerBounds(mod);
+    if (!bounds) fail(`no .decklight container in ${modPath}`);
+    let inner = mod.slice(bounds.contentStart, bounds.contentEnd);
+
+    // Rewire inline-cast refs to the prefixed ids.
+    inner = inner.replace(/data-cast-inline=["']#([^"']+)["']/g,
+      (t, id) => `data-cast-inline="#${prefix}${id}"`);
+
+    // Rebase relative asset urls onto the first deck's directory.
+    if (path.resolve(modDir) !== path.resolve(baseDir)) {
+      const rebase = (rel) => path.relative(baseDir, path.resolve(modDir, rel)).split(path.sep).join('/');
+      inner = inner.replace(/\b(data-cast|src)=["'](?!#|data:|https?:|\/\/)([^"']+)["']/g,
+        (t, attr, rel) => `${attr}="${rebase(rel)}"`);
+    }
+
+    for (const b of blocks) {
+      const id = b.match(/id=["']([^"']+)["']/)[1];
+      if (seenIds.has(id)) fail(`duplicate embedded cast id after merge: ${id}`);
+      seenIds.add(id);
+      carried.push(b);
+    }
+    mergedInner += '\n\n    <!-- ==================== module: ' + title.replace(/--/g, '—') + ' ==================== -->\n'
+      + markSections(inner, title);
+  }
+
+  // Carried cast blocks must land BEFORE the runtime/init scripts: classic
+  // scripts execute while the parser is mid-document, so anything inserted
+  // after them is not yet in the DOM when the player looks its id up.
+  // Right after the container's closing </div> matches the layout of decks
+  // that author their casts inline (which is why single-deck bundles worked).
+  const tail = base.slice(baseBounds.contentEnd); // begins with the container's </div>
+  const closeLen = tail.match(/^<\/div>/i)[0].length;
+  let html = base.slice(0, baseBounds.contentStart) + mergedInner
+    + tail.slice(0, closeLen)
+    + (carried.length ? '\n' + carried.join('\n') : '')
+    + tail.slice(closeLen);
+  html = stripPlaylist(html);
+  notices.push(`merged ${jobs.length} modules: ${jobs.map((j) => j.title).join(' · ')}`);
+  return html;
+}
+
+// ---------------------------------------------------------------- arguments
+
+export async function bundleMain(argv = process.argv.slice(2)) {
+
+if (!argv.length || argv.includes('--help') || argv.includes('-h')) {
+  process.stdout.write(`decklight bundle — flatten deck(s) into one self-contained HTML file
+
+Usage:
+  decklight bundle <deck.html> [-o out.html] [--themes current|all|name,name,…]
+  decklight bundle <deck.html> --all [-o out.html] [--title "…"] [--themes …]
+  decklight bundle <a.html> <b.html> … [-o out.html] [--title "…"] [--themes …]
+
+Options:
+  -o <file>        output path (default: <deck>-standalone.html, or
+                   <deck>-course.html when merging)
+  --all            follow the deck's playlist and merge EVERY module into
+                   one single-file presentation (in-file module menu via
+                   data-module markers)
+  --title <t>      <title> for a merged presentation
+  --themes <sel>   which themes to embed:
+                     current       just the deck's linked theme (default)
+                     all           every theme in the deck's themes/ directory
+                     name,name,…   an explicit list (the deck's linked theme
+                                   stays active when included, else the first)
+`);
+  process.exit(0);
+}
+
+const inputs = [];
+let outPath = null, themesSel = 'current', all = false, mergedTitle = null;
+for (let i = 0; i < argv.length; i++) {
+  const a = argv[i];
+  if (a === '-o') outPath = argv[++i];
+  else if (a === '--themes') themesSel = argv[++i];
+  else if (a === '--all') all = true;
+  else if (a === '--title') mergedTitle = argv[++i];
+  else if (!a.startsWith('-')) inputs.push(a);
+  else fail(`unknown argument: ${a}`);
+}
+if (!inputs.length) fail('no deck given');
+if (all && inputs.length > 1) fail('--all takes a single deck (it follows that deck’s playlist)');
+
+const firstPath = path.resolve(inputs[0]);
+if (!fs.existsSync(firstPath)) fail(`deck not found: ${firstPath}`);
+const deckDir = path.dirname(firstPath);
+const notices = [];
+
+// Build the job list (merge mode when --all or several inputs).
+let jobs = null;
+if (all) {
+  const src = fs.readFileSync(firstPath, 'utf8');
+  const modules = parsePlaylist(src);
+  if (!modules.length) fail('--all: the deck has no parseable playlist ({ title, href } modules)');
+  jobs = modules.map((m) => {
+    const p = path.resolve(deckDir, m.href);
+    if (!fs.existsSync(p)) fail(`playlist module not found: ${m.href} (${p})`);
+    return { path: p, title: m.title };
+  });
+} else if (inputs.length > 1) {
+  jobs = inputs.map((rel, i) => {
+    const p = path.resolve(rel);
+    if (!fs.existsSync(p)) fail(`deck not found: ${p}`);
+    return { path: p, title: titleOf(fs.readFileSync(p, 'utf8'), `Module ${i + 1}`) };
+  });
+}
+
+let html;
+if (jobs) {
+  html = mergeDecks(jobs, deckDir, notices);
+  const t = mergedTitle ||
+    (jobs[0].title || '').replace(/^\d+\s*[·.:-]\s*/, '') || 'Presentation';
+  html = html.replace(/<title>[^<]*<\/title>/i, `<title>${escAttr(t)}</title>`);
+  outPath = path.resolve(outPath ||
+    path.join(deckDir, path.basename(firstPath, '.html') + '-course.html'));
+} else {
+  html = fs.readFileSync(firstPath, 'utf8');
+  outPath = path.resolve(outPath ||
+    path.join(deckDir, path.basename(firstPath, '.html') + '-standalone.html'));
+}
+
+const read = (rel) => {
+  const p = path.resolve(deckDir, rel);
+  if (!fs.existsSync(p)) fail(`referenced file not found: ${rel} (${p})`);
+  return fs.readFileSync(p, 'utf8');
+};
+
+// ---------------------------------------------------------- theme selection
+
+const themeLinkRe = /<link\b[^>]*rel=["']stylesheet["'][^>]*href=["']([^"']*themes\/([\w-]+)\.css)["'][^>]*>/i;
+const themeLinkM = html.match(themeLinkRe);
+if (!themeLinkM) fail('no theme <link> (href matching themes/<name>.css) found in the deck');
+const [themeLinkTag, themeHref, linkedTheme] = themeLinkM;
+const themesDir = path.resolve(deckDir, path.dirname(themeHref));
+
+let themeNames;
+if (themesSel === 'current') {
+  themeNames = [linkedTheme];
+} else if (themesSel === 'all') {
+  themeNames = fs.readdirSync(themesDir).filter((f) => f.endsWith('.css'))
+    .map((f) => f.replace(/\.css$/, '')).sort();
+} else {
+  themeNames = themesSel.split(',').map((s) => s.trim()).filter(Boolean);
+}
+if (!themeNames.length) fail('no themes selected');
+const activeTheme = themeNames.includes(linkedTheme) ? linkedTheme : themeNames[0];
+if (activeTheme !== linkedTheme) {
+  notices.push(`linked theme "${linkedTheme}" not in --themes list; "${activeTheme}" is active`);
+}
+
+const themeBlocks = themeNames.map((name) => {
+  const cssPath = path.join(themesDir, name + '.css');
+  if (!fs.existsSync(cssPath)) fail(`theme not found: ${name} (${cssPath})`);
+  const css = fs.readFileSync(cssPath, 'utf8');
+  const media = name === activeTheme ? '' : ' media="not all"';
+  return `<style data-theme="${name}"${media}>\n${css}\n</style>`;
+}).join('\n');
+html = html.replace(themeLinkTag, themeBlocks);
+
+// ------------------------------------------------- structure stylesheet(s)
+
+html = html.replace(
+  /<link\b[^>]*rel=["']stylesheet["'][^>]*href=["']([^"']+)["'][^>]*>/gi,
+  (tag, href) => {
+    if (/^(https?:)?\/\//.test(href)) { notices.push(`external stylesheet kept as link: ${href}`); return tag; }
+    if (/themes\/[\w-]+\.css/.test(href)) return tag; // already handled
+    return `<style>\n${read(href)}\n</style>`;
+  });
+
+// -------------------------------------------------------------------- images
+
+html = html.replace(
+  /<img\b([^>]*)\bsrc=["']([^"']+)["']/gi,
+  (tag, pre, src) => {
+    if (/^(data:|https?:|\/\/)/.test(src)) return tag;
+    const p = path.resolve(deckDir, src);
+    if (!fs.existsSync(p)) { notices.push(`image not found, left as-is: ${src}`); return tag; }
+    const ext = path.extname(p).slice(1).toLowerCase();
+    const mime = { svg: 'image/svg+xml', png: 'image/png', jpg: 'image/jpeg', jpeg: 'image/jpeg', gif: 'image/gif', webp: 'image/webp' }[ext] || 'application/octet-stream';
+    const b64 = fs.readFileSync(p).toString('base64');
+    return `<img${pre}src="data:${mime};base64,${b64}"`;
+  });
+
+// ------------------------------------------------------------ runtime script
+
+html = html.replace(
+  /<script\b[^>]*src=["']([^"']+)["'][^>]*>\s*<\/script>/gi,
+  (tag, src) => {
+    if (/^(https?:)?\/\//.test(src)) { notices.push(`external script kept as src: ${src}`); return tag; }
+    const js = read(src).replace(/\/\/# sourceMappingURL=.*$/m, '');
+    return `<script>\n${scriptSafe(js)}\n</script>`;
+  });
+
+// ------------------------------------------------------------------- casts
+
+const embeds = [];
+let castN = 0;
+html = html.replace(
+  /<div\b([^>]*class=["'][^"']*\bterminal\b[^"']*["'][^>]*)>/gi,
+  (tag, attrs) => {
+    const m = attrs.match(/\bdata-cast=["']([^"']+)["']/);
+    if (!m) return tag; // data-cast-inline (or no cast) passes through
+    const id = `bundled-cast-${++castN}`;
+    const json = jsonSafe(read(m[1]));
+    embeds.push(`<script type="application/json" id="${id}">\n${json}\n</script>`);
+    return tag.replace(m[0], `data-cast-inline="#${id}"`);
+  });
+
+// -------------------------------------------------------------- assemble
+
+// Anchor to the LAST </body>: the inlined runtime contains the speaker-view
+// popup template, whose "</body></html>" string would match a first-occurrence
+// search and corrupt the JS mid-payload.
+if (embeds.length) {
+  const at = html.toLowerCase().lastIndexOf('</body>');
+  if (at === -1) fail('deck has no </body>');
+  html = html.slice(0, at) + embeds.join('\n') + '\n' + html.slice(at);
+}
+
+if (!jobs) {
+  const playlistM = html.match(/playlist\s*:/);
+  if (playlistM) {
+    const hrefs = [...html.matchAll(/href:\s*['"]([^'"]+\.html)['"]/g)].map((m) => m[1]);
+    notices.push('deck has a playlist — cross-file module links cannot resolve inside a single file:' +
+      (hrefs.length ? '\n    ' + [...new Set(hrefs)].join('\n    ') : ''));
+  }
+}
+
+fs.writeFileSync(outPath, html);
+const kb = (fs.statSync(outPath).size / 1024).toFixed(1);
+const what = jobs ? `${jobs.length} modules` : path.basename(firstPath);
+process.stdout.write(`bundled ${what} → ${outPath} (${kb} KB, themes: ${themeNames.join(', ')}; active: ${activeTheme})\n`);
+for (const n of notices) process.stdout.write(`note: ${n}\n`);
+}
+
+import { fileURLToPath } from 'node:url';
+const isMain = process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url);
+if (isMain) bundleMain().catch((e) => fail(e.message));

package/cli/decklight.mjs

@@ -0,0 +1,95 @@
+#!/usr/bin/env node
+/**
+ * decklight — the Decklight command line.
+ *
+ *   decklight rec      record a terminal cast from a YAML script
+ *   decklight refresh  re-run embedded scripts, rewrite drifted casts
+ *   decklight export   convert a cast to asciicast v2
+ *   decklight bundle   flatten a deck into one self-contained HTML file
+ *   decklight tts      serve the live voice bridge (on-the-fly Gemini narration)
+ *
+ * The subcommand implementations live in rec.mjs and
+ * bundle.mjs (importable modules; direct execution still works but
+ * this dispatcher is the documented entry point).
+ */
+
+const GLOBAL_HELP = `decklight — author, record, and package Decklight presentations
+
+Usage:
+  decklight <command> [options]        (decklight <command> --help for full flags)
+
+Commands:
+  init     scaffold a starter deck, plus an agent skill (.claude/skills/decklight/, AGENTS.md)
+           EXAMPLE: decklight init "My Deck"
+  rec      record a truthful terminal cast by running a YAML command script in a real PTY
+           EXAMPLE: decklight rec deck.term.yaml -o deck.cast.json
+  refresh  re-execute the script embedded in each cast; rewrite the ones whose output drifted
+           EXAMPLE: decklight refresh casts/
+  export   flatten a cast to asciicast v2 (markers per step) for the asciinema ecosystem
+           EXAMPLE: decklight export demo.cast.json && agg demo.cast demo.gif
+  bundle   flatten a deck into ONE self-contained HTML file (runtime, themes, casts, images inlined)
+           EXAMPLE: decklight bundle demo/showcase.html --themes midnight,graphite
+           EXAMPLE: decklight bundle deck.html --all --title "My Course"   (merge the whole playlist into one file)
+  tts      serve the live voice bridge — the player synthesizes narration on the fly through it
+           EXAMPLE: decklight tts        (then pick "Live voice…" in the deck's / palette)
+  edit     serve the deck with live reload; E in the player edits speaker notes back into the file
+           EXAMPLE: decklight edit demo/showcase.html   (then open the printed URL)
+  help     show this help, or a command's help: decklight help bundle
+`;
+
+function globalHelp(exitCode = 0) {
+  process.stdout.write(GLOBAL_HELP);
+  process.exit(exitCode);
+}
+
+const argv = process.argv.slice(2);
+let cmd = argv[0];
+let rest = argv.slice(1);
+
+if (!cmd || cmd === '--help' || cmd === '-h') globalHelp();
+if (cmd === 'help') {
+  if (!rest[0]) globalHelp();
+  cmd = rest[0];
+  rest = ['--help'];
+}
+
+switch (cmd) {
+  case 'init': {
+    const { initMain } = await import('./init.mjs');
+    await initMain(rest);
+    break;
+  }
+  case 'rec': {
+    const { recMain } = await import('./rec.mjs');
+    await recMain(rest);
+    break;
+  }
+  case 'refresh': {
+    const { recMain } = await import('./rec.mjs');
+    await recMain(rest.includes('--help') ? ['--help'] : ['refresh', ...rest]);
+    break;
+  }
+  case 'export': {
+    const { recMain } = await import('./rec.mjs');
+    await recMain(rest.includes('--help') ? ['--help'] : ['export', ...rest]);
+    break;
+  }
+  case 'bundle': {
+    const { bundleMain } = await import('./bundle.mjs');
+    await bundleMain(rest);
+    break;
+  }
+  case 'tts': {
+    const { ttsMain } = await import('../tools/voiceover-server.mjs');
+    await ttsMain(rest);
+    break;
+  }
+  case 'edit': {
+    const { editMain } = await import('./edit.mjs');
+    await editMain(rest);
+    break;
+  }
+  default:
+    process.stderr.write(`decklight: unknown command "${cmd}"\n\n`);
+    globalHelp(1);
+}

package/cli/edit.mjs

@@ -0,0 +1,142 @@
+#!/usr/bin/env node
+// decklight edit — the live-editing dev server (SPEC §8 edit mode).
+//
+//   decklight edit <deck.html> [--port 8788]
+//
+// Serves the current working directory over localhost (so decks that
+// reference ../dist and ../themes just work), watches the deck file, and:
+//
+//   GET  /edit/ping    → { ok, deck }              (player probes availability)
+//   GET  /edit/events  → SSE; a `reload` event fires when the deck changes
+//   POST /edit/notes   → { slide, text }           rewrite that slide's notes
+//
+// The player's E editor posts ⟨CLICK⟩-separated plain text; the server
+// rebuilds the <aside class="notes"> (one <p> per segment, escaped) and
+// writes the file — the watcher then tells every connected browser to
+// reload, and the #/slide/step hash restores the position.
+
+import { createServer } from 'node:http';
+import { readFileSync, writeFileSync, watch, existsSync, statSync } from 'node:fs';
+import { resolve, extname, sep, basename } from 'node:path';
+
+// file://-opened decks probe http://127.0.0.1:8788 directly (origin "null"),
+// exactly like the tts bridge — so the endpoints are CORS-open. The server
+// still binds 127.0.0.1 only.
+const CORS = {
+  'access-control-allow-origin': '*',
+  'access-control-allow-methods': 'GET, POST, OPTIONS',
+  'access-control-allow-headers': 'content-type',
+};
+
+const MIME = {
+  '.html': 'text/html; charset=utf-8',
+  '.js': 'text/javascript', '.mjs': 'text/javascript',
+  '.css': 'text/css', '.json': 'application/json',
+  '.svg': 'image/svg+xml', '.png': 'image/png', '.jpg': 'image/jpeg',
+  '.gif': 'image/gif', '.ico': 'image/x-icon', '.webp': 'image/webp',
+  '.wav': 'audio/wav', '.m4a': 'audio/mp4', '.mp3': 'audio/mpeg',
+  '.woff': 'font/woff', '.woff2': 'font/woff2', '.map': 'application/json',
+};
+
+const escapeHtml = (s) => s.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;');
+
+/** ⟨CLICK⟩-separated plain text → the aside's inner HTML (one <p> per segment). */
+export function notesTextToAside(text) {
+  const segs = text.split(/\s*⟨CLICK⟩\s*/).map((s) => s.replace(/\s+/g, ' ').trim());
+  const ps = [];
+  segs.forEach((seg, i) => {
+    if (i > 0) ps.push('<p>⟨CLICK⟩</p>');
+    if (seg) ps.push(`<p>${escapeHtml(seg)}</p>`);
+  });
+  return ps.join('\n        ');
+}
+
+/** Replace (or insert) slide N's <aside class="notes"> in the deck html. */
+export function setSlideNotes(html, slide, asideInner) {
+  // top-level sections can't nest, so splitting on the open tag is exact
+  const parts = html.split(/(<section\b)/);
+  const idx = 2 * slide; // parts[0] preamble, then [tag, content] pairs
+  if (!parts[idx]) throw new Error(`no slide ${slide} (deck has ${(parts.length - 1) / 2})`);
+  const aside = `<aside class="notes">\n        ${asideInner}\n      </aside>`;
+  const seg = parts[idx];
+  parts[idx] = /<aside class="notes">[\s\S]*?<\/aside>/.test(seg)
+    ? seg.replace(/<aside class="notes">[\s\S]*?<\/aside>/, aside)
+    : seg.replace(/<\/section>/, `  ${aside}\n    </section>`);
+  return parts.join('');
+}
+
+export async function editMain(args) {
+  if (args.includes('--help') || args.includes('-h') || !args.filter((a) => !a.startsWith('-')).length) {
+    console.log('usage: decklight edit <deck.html> [--port 8788]\n  serves the cwd, live-reloads the deck on change, and accepts notes edits from the player (E)');
+    return;
+  }
+  const opt = (flag, dflt) => { const i = args.indexOf(flag); return i >= 0 ? args[i + 1] : dflt; };
+  const port = Number(opt('--port', 8788));
+  const root = process.cwd();
+  const deckPath = resolve(root, args.find((a) => !a.startsWith('-')));
+  if (!existsSync(deckPath)) { console.error(`deck not found: ${deckPath}`); process.exitCode = 1; return; }
+  if (!deckPath.startsWith(root + sep)) { console.error('deck must live under the current directory'); process.exitCode = 1; return; }
+  const deckUrl = '/' + deckPath.slice(root.length + 1).split(sep).join('/');
+
+  // ── live reload: watch the deck, broadcast SSE (debounced — editors fire
+  // multiple fs events per save) ─────────────────────────────────────────
+  const clients = new Set();
+  let pending = null;
+  watch(deckPath, () => {
+    clearTimeout(pending);
+    pending = setTimeout(() => {
+      for (const res of clients) res.write('data: reload\n\n');
+      console.log(`  changed → reload × ${clients.size}`);
+    }, 150);
+  });
+
+  const server = createServer(async (req, res) => {
+    try {
+      const url = new URL(req.url, 'http://x');
+      if (req.method === 'OPTIONS') { res.writeHead(204, CORS); return res.end(); }
+      if (req.method === 'GET' && url.pathname === '/edit/ping') {
+        res.writeHead(200, { ...CORS, 'content-type': 'application/json' });
+        return res.end(JSON.stringify({ ok: true, deck: deckUrl, name: basename(deckPath) }));
+      }
+      if (req.method === 'GET' && url.pathname === '/edit/events') {
+        res.writeHead(200, { ...CORS, 'content-type': 'text/event-stream', 'cache-control': 'no-cache', connection: 'keep-alive' });
+        res.write(': connected\n\n');
+        clients.add(res);
+        req.on('close', () => clients.delete(res));
+        return;
+      }
+      if (req.method === 'POST' && url.pathname === '/edit/notes') {
+        let body = '';
+        for await (const chunk of req) { body += chunk; if (body.length > 1e6) throw new Error('too large'); }
+        const { slide, text } = JSON.parse(body);
+        if (!Number.isInteger(slide) || slide < 1 || typeof text !== 'string') throw new Error('bad payload');
+        const html = readFileSync(deckPath, 'utf8');
+        writeFileSync(deckPath, setSlideNotes(html, slide, notesTextToAside(text)));
+        console.log(`  notes saved: slide ${slide} (${text.length} chars)`);
+        res.writeHead(200, { ...CORS, 'content-type': 'application/json' });
+        return res.end(JSON.stringify({ ok: true }));
+      }
+      // ── static files from the cwd ────────────────────────────────────
+      if (req.method === 'GET') {
+        const rel = url.pathname === '/' ? deckUrl : decodeURIComponent(url.pathname);
+        const file = resolve(root, '.' + rel);
+        if (!file.startsWith(root + sep) && file !== root) { res.writeHead(403); return res.end('forbidden'); }
+        if (!existsSync(file) || !statSync(file).isFile()) { res.writeHead(404); return res.end('not found'); }
+        res.writeHead(200, { 'content-type': MIME[extname(file).toLowerCase()] ?? 'application/octet-stream', 'cache-control': 'no-cache' });
+        return res.end(readFileSync(file));
+      }
+      res.writeHead(405);
+      res.end();
+    } catch (e) {
+      console.error(`  edit error: ${String(e).slice(0, 120)}`);
+      if (!res.headersSent) res.writeHead(400, CORS);
+      res.end(String(e.message || e));
+    }
+  });
+
+  server.listen(port, '127.0.0.1', () => {
+    console.log(`decklight edit on http://127.0.0.1:${port}${deckUrl} — E edits notes, saves reload the deck. Ctrl-C stops`);
+  });
+}
+
+if (import.meta.url === `file://${process.argv[1]}`) editMain(process.argv.slice(2));