explainer-video 0.0.0-stage → 0.4.0

package/skills/explainer-video-from-coursework/scenes/_pt-chart.js

@@ -0,0 +1,12 @@
+window.SCENE_CONFIG = { renderAt: function (t, svg) {
+  SceneCore.primitives.chart(svg, { type: 'pie', x: 520, y: 560, radius: 210, at: 0, dur: 1.2,
+    title: 'Read share',
+    data: [ { label: 'Linearizable', value: 3, color: 'ok' },
+            { label: 'Causal', value: 3, color: 'client' },
+            { label: 'Eventual', value: 2, color: 'hub' } ] }, t);
+  SceneCore.primitives.chart(svg, { type: 'bar', x: 1080, y: 400, w: 700, h: 340, at: 0, dur: 1.0,
+    title: 'Write latency (ms)',
+    data: [ { label: 'LWW', value: 5, color: 'client' },
+            { label: 'Vector', value: 22, color: 'hub' },
+            { label: 'CRDT', value: 9, color: 'ok' } ] }, t);
+} };

package/skills/explainer-video-from-coursework/scenes/_pt-equation.js

@@ -0,0 +1,10 @@
+window.SCENE_CONFIG = { renderAt: function (t, svg) {
+  SceneCore.primitives.equation(svg, { tex: 'P(k) = \\frac{(\\lambda t)^k e^{-\\lambda t}}{k!}',
+    y: 300, size: 52, at: 0 }, t);
+  SceneCore.primitives.equation(svg, { tex: 'a \\to b \\iff V[a] < V[b]',
+    y: 470, size: 48, at: 0.2 }, t);
+  SceneCore.primitives.equation(svg, { tex: 'V = \\sqrt{x^2 + y_{i}^{2}} \\ge \\lceil z \\rceil',
+    y: 640, size: 48, at: 0.4 }, t);
+  SceneCore.primitives.equation(svg, { tex: 'merged[i] = \\max(A[i], B[i])',
+    y: 800, size: 44, at: 0.6 }, t);
+} };

package/skills/explainer-video-from-coursework/scenes/_pt-hubspoke.js

@@ -0,0 +1,7 @@
+window.SCENE_CONFIG = { renderAt: function (t, svg) {
+  SceneCore.primitives.hubSpoke(svg, { x: 960, y: 540, radius: 330, at: 0, stagger: 0.3,
+    label: 'Event Bus', sub: 'one broker, many consumers',
+    spokes: [ { label: 'CQRS', color: 'client' }, { label: 'Event Sourcing', color: 'ok' },
+              { label: 'CDC', color: 'hub' }, { label: 'Sagas', color: 'client' },
+              { label: 'Streams', color: 'ok' } ] }, t);
+} };

package/skills/explainer-video-from-coursework/scenes/_pt-loopflow.js

@@ -0,0 +1,7 @@
+window.SCENE_CONFIG = { renderAt: function (t, svg) {
+  SceneCore.primitives.loopFlow(svg, { at: 0, lap: 6, packetCount: 4, bow: 0.22,
+    nodes: [ { x: 960, y: 300, label: 'Command' },
+             { x: 1400, y: 540, label: 'Event Store' },
+             { x: 960, y: 780, label: 'Projection' },
+             { x: 520, y: 540, label: 'Query' } ] }, t);
+} };

package/skills/explainer-video-from-coursework/scenes/_pt-sequence.js

@@ -0,0 +1,12 @@
+window.SCENE_CONFIG = { renderAt: function (t, svg) {
+  SceneCore.primitives.sequence(svg, { x: 220, y: 200, w: 1480, h: 720, at: 0, stagger: 0.5,
+    participants: [ { id: 'client', label: 'POST /orders', sub: 'HTTP request' },
+                    { id: 'api', label: 'api.orders' },
+                    { id: 'queue', label: 'worker.tasks' },
+                    { id: 'db', label: 'store.orders' } ],
+    messages: [ { from: 'client', to: 'api', label: 'create_order', kind: 'http' },
+                { from: 'api', to: 'api', label: 'validate' },
+                { from: 'api', to: 'queue', label: 'charge_card', kind: 'queue' },
+                { from: 'queue', to: 'db', label: 'save' },
+                { from: 'api', to: 'client', label: '202 Accepted', kind: 'return' } ] }, t);
+} };

package/skills/explainer-video-from-coursework/scenes/_pt-timeline.js

@@ -0,0 +1,11 @@
+window.SCENE_CONFIG = { renderAt: function (t, svg) {
+  SceneCore.primitives.timeline(svg, { x: 420, y: 330, w: 1180, laneH: 150, at: 0,
+    axisLabel: 'real time',
+    tracks: [ { label: 'R1', color: 'client' }, { label: 'R2', color: 'ok' } ],
+    events: [ { track: 0, at: 0.10, label: 'write(1)', color: 'client' },
+              { track: 1, at: 0.35, label: 'read()', color: 'bad' },
+              { track: 0, at: 0.60, label: 'write(2)', color: 'client' },
+              { track: 1, at: 0.85, label: 'read()', color: 'ok' } ],
+    arrows: [ { from: 0, to: 1, label: 'happens-before' },
+              { from: 2, to: 3 } ] }, t);
+} };

package/skills/explainer-video-from-coursework/src/scene-code.html

@@ -0,0 +1,127 @@
+<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<title>Code / Refactor scene host</title>
+<style>
+  html, body {
+    margin: 0; padding: 0; width: 1920px; height: 1080px;
+    overflow: hidden; background: #080e1a;
+    font-family: "Helvetica Neue", Helvetica, Arial, sans-serif;
+  }
+  #stage { position: relative; width: 1920px; height: 1080px; }
+  .panel-wrap, .note-wrap { position: absolute; inset: 0; }
+  .note-wrap { pointer-events: none; }
+
+  /* ---- chrome ---- */
+  .chrome { position: absolute; inset: 0; pointer-events: none; }
+  .hdr {
+    position: absolute; left: 74px; top: 48px; display: flex; align-items: center; gap: 14px;
+    color: #e8eefc; font-size: 25px; font-weight: 700;
+  }
+  .hdr-dot { width: 18px; height: 18px; border-radius: 50%; background: #fbbf24; display: inline-block; }
+  .stage-badge {
+    position: absolute; right: 74px; top: 38px; padding: 13px 34px; border-radius: 25px;
+    background: #0f1c31; border: 1.5px solid #22334f; color: #fbbf24;
+    font-size: 22px; font-weight: 700; letter-spacing: 0.8px; opacity: 0;
+  }
+  .prog { position: absolute; left: 0; bottom: 0; width: 1920px; height: 6px; background: #0d1728; }
+  .prog-fill { height: 6px; background: #fbbf24; opacity: .85; }
+
+  /* ---- code panel ---- */
+  .panel { position: absolute; left: 0; top: 0; transform-origin: 0 0; will-change: transform, opacity; }
+  .card {
+    background: #0d1728; border: 2px solid #22334f; border-radius: 16px;
+    overflow: hidden; box-shadow: 0 24px 70px rgba(0,0,0,.55);
+  }
+  .accent-bad .card  { border-color: rgba(251,113,133,.55); }
+  .accent-ok  .card  { border-color: rgba(52,211,153,.55); }
+
+  .tab {
+    display: flex; align-items: center; gap: 12px;
+    padding: 14px 24px; background: #0f1c31; border-bottom: 1px solid #22334f;
+  }
+  .dot { width: 11px; height: 11px; border-radius: 50%; background: #34d399; flex: none; }
+  .accent-bad .dot { background: #fb7185; }
+  .accent-ok  .dot { background: #34d399; }
+  .fname { font-family: "SF Mono", Menlo, Consolas, monospace; font-size: 20px; font-weight: 500; color: #93a7c8; }
+  .badge {
+    margin-left: auto; font-size: 15px; font-weight: 800; letter-spacing: 1.2px;
+    padding: 5px 14px; border-radius: 14px;
+  }
+  .accent-bad .badge { color: #fb7185; background: rgba(251,113,133,.12); border: 1px solid rgba(251,113,133,.4); }
+  .accent-ok  .badge { color: #34d399; background: rgba(52,211,153,.12); border: 1px solid rgba(52,211,153,.4); }
+
+  .code {
+    padding: 20px 26px 24px 18px;
+    font-family: "SF Mono", Menlo, Consolas, monospace;
+    font-size: 22px; line-height: 34px;
+  }
+  .ln { display: flex; gap: 18px; white-space: pre; border-radius: 5px; }
+  .ln .num { width: 38px; flex: none; text-align: right; color: #3d4c66; user-select: none; }
+  .ln .txt { color: #d6deeb; }
+  .ln.focused { background: rgba(251,113,133,.10); box-shadow: -3px 0 0 rgba(251,113,133,.85); }
+  .accent-ok .ln.focused { background: rgba(52,211,153,.10); box-shadow: -3px 0 0 rgba(52,211,153,.85); }
+  /* an elision marker stands for unnarrated lines of a repo excerpt */
+  .ln.elided .txt { color: #55688a; font-style: italic; letter-spacing: 1px; }
+
+  /* ---- pause badge: only on a segment whose narration asks the viewer to pause ---- */
+  .pause-badge {
+    position: absolute; left: 50%; top: 40px; transform: translateX(-50%); opacity: 0;
+    display: flex; align-items: center; gap: 14px; padding: 12px 30px; border-radius: 25px;
+    background: #2a1e07; border: 1.5px solid rgba(251,191,36,.6); color: #fbbf24;
+    font-size: 22px; font-weight: 800; letter-spacing: 1.2px; white-space: nowrap; pointer-events: none;
+  }
+  .pause-icon { display: inline-flex; gap: 5px; }
+  .pause-icon i { display: block; width: 6px; height: 20px; border-radius: 2px; background: #fbbf24; }
+
+  /* ---- tokens ---- */
+  .t-k { color: #c792ea; }   /* keyword  */
+  .t-t { color: #82aaff; }   /* type     */
+  .t-f { color: #82aaff; }   /* function */
+  .t-s { color: #c3e88d; }   /* string   */
+  .t-c { color: #55688a; font-style: italic; }
+  .t-n { color: #f78c6c; }   /* number   */
+  .t-u { color: #89ddff; }   /* punct    */
+  .t-p { color: #d6deeb; }
+
+  /* ---- annotation notes ---- */
+  .note {
+    position: absolute; transform: translate(-50%, 0); opacity: 0;
+    padding: 14px 26px; border-radius: 14px; font-size: 24px; font-weight: 600;
+    background: #101d33; border: 1.5px solid #2b3d5c; color: #e8eefc; white-space: nowrap;
+    box-shadow: 0 12px 34px rgba(0,0,0,.45);
+  }
+  .note-bad { border-color: rgba(251,113,133,.5); color: #ffd9df; }
+  .note-ok  { border-color: rgba(52,211,153,.5); color: #d6fff0; }
+</style>
+</head>
+<body>
+<div id="stage"></div>
+<script src="scene-code.js"></script>
+<script>
+  // config name comes from ?scene=<name>, ?work=<dir> scopes the scene path per-video
+  var Q = new URLSearchParams(location.search);
+  var NAME = Q.get('scene') || 'ocp-refactor';
+  var WORK = Q.get('work') || '';
+  // the measured timeline, when there is one: a scene naming its `segment` is timed from that window
+  function loadScene() {
+    var s = document.createElement('script');
+    s.src = WORK ? WORK + '/scenes/' + NAME + '.js' : '../scenes/' + NAME + '.js';
+    s.onload = function () {
+      var cfg = window.SCENE_CONFIG;
+      var clock = window.CodeScenes.clockOf(cfg, window.TIMELINE);
+      var scene = window.CodeScenes.create({ root: document.getElementById('stage'), config: cfg });
+      window.renderAt = function (t) { scene.renderAt(t - clock.offset); return true; };
+      window.VIDEO_META = { width: 1920, height: 1080, fps: cfg.fps || 30, total: clock.total };
+    };
+    document.head.appendChild(s);
+  }
+  var tlEl = document.createElement('script');
+  tlEl.src = WORK ? WORK + '/timeline.js' : 'timeline.js';
+  tlEl.onload = loadScene;
+  tlEl.onerror = loadScene;
+  document.head.appendChild(tlEl);
+</script>
+</body>
+</html>

package/skills/explainer-video-from-coursework/src/scene-code.js

@@ -0,0 +1,379 @@
+/* =============================================================================
+   scene-code.js — code + refactor renderers.
+
+   Two renderers, one core:
+     • CODE      a single file on screen, revealed line by line, with line focus
+     • REFACTOR  the same panel splitting into BEFORE / AFTER, so a transformation
+                 is shown rather than described
+
+   They share everything except the number of panels, which is why they live in
+   one module: the "refactor" view is a code view that happens to have two panels
+   and a layout that moves them apart.
+
+   Like the diagram renderer, renderAt(t) is a PURE FUNCTION of time.
+
+   Code excerpted from a repo (explainer-video-from-codebase's excerpt.mjs) adds,
+   all optional, defaults unchanged:
+     • numbers[]   the real line number of each line (null on an elision marker)
+     • elided[]    the indices of elision-marker lines, styled apart from code
+     • several `focus` acts per panel, one per narrated sentence
+     • a `pause` act: an on-screen badge while the narration asks the viewer to
+       pause and read a whole block
+     • `segment: <key>`: the acts are timed from that segment's window (scene time
+       = line time + lead, as lines.json and excerpt-check measure it), so the host
+       subtracts the window's start from the video time render passes; such a scene
+       draws no progress bar
+
+   Contract: window.CodeScenes.create({ root, config }) -> { renderAt(t) }
+   ========================================================================== */
+(function () {
+  'use strict';
+
+  /* ---------------- math ---------------- */
+  const clamp01 = v => (v < 0 ? 0 : v > 1 ? 1 : v);
+  const lerp = (a, b, p) => a + (b - a) * p;
+  const seg = (t, a, b) => clamp01((t - a) / (b - a || 1e-6));
+  const easeOut = p => 1 - Math.pow(1 - p, 3);
+  const easeIO = p => (p < 0.5 ? 4 * p * p * p : 1 - Math.pow(-2 * p + 2, 3) / 2);
+  const fadeIn = (t, a, b) => easeOut(seg(t, a, b));
+  const fadeOut = (t, a, b) => 1 - easeIO(seg(t, a, b));
+  const inWin = (t, a, b) => t >= a && t < (b == null ? Infinity : b);
+
+  /* ---------------- syntax highlighting ----------------
+     A deliberately small Java/C-like tokenizer. No dependency, and it only has
+     to handle the curated snippets we author — not arbitrary source. A language
+     may override the string rule (Go raw strings, JS template literals) and mark
+     preprocessor directives (C, C++). */
+  const C_KW = ['auto','break','case','const','continue','default','do','else','enum','extern','for','goto','if','inline','register','restrict','return','sizeof','static','struct','switch','typedef','union','volatile','while','NULL','true','false'];
+  const C_TYPES = ['int','char','short','long','float','double','void','unsigned','signed','bool','size_t','ssize_t','int8_t','int16_t','int32_t','int64_t','uint8_t','uint16_t','uint32_t','uint64_t'];
+  const TS_KW = ['abstract','as','async','await','break','case','catch','class','const','continue','debugger','declare','default','delete','do','else','enum','export','extends','false','finally','for','from','function','if','implements','import','in','instanceof','interface','keyof','let','namespace','new','null','of','private','protected','public','readonly','return','static','super','switch','this','throw','true','try','type','typeof','undefined','var','void','while','yield'];
+  const TS_TYPES = ['string','number','boolean','any','unknown','never','object','bigint','symbol'];
+  const C_COMMENT = /^\/\/.*|^\/\*[\s\S]*?\*\//;
+  const LANGS = {
+    java: {
+      keywords: new Set(['class','interface','implements','extends','public','private','protected','static','final','void','new','if','else','return','this','abstract','package','import','throws','throw','enum','super']),
+      types: new Set(['String','double','int','boolean','long','float','Object','List','Map']),
+      comment: /^\/\/.*|^\/\*[\s\S]*?\*\//,
+    },
+    python: {
+      keywords: new Set(['def','class','return','if','elif','else','for','while','import','from','as','with','try','except','raise','lambda','None','True','False','self','yield','pass','in','not','and','or']),
+      types: new Set(['int','str','float','bool','list','dict','set','tuple']),
+      comment: /^#.*/,
+    },
+    go: {
+      keywords: new Set(['break','case','chan','const','continue','default','defer','else','fallthrough','for','func','go','goto','if','import','interface','map','package','range','return','select','struct','switch','type','var','nil','true','false','iota']),
+      types: new Set(['string','int','int8','int16','int32','int64','uint','uint8','uint16','uint32','uint64','uintptr','float32','float64','complex64','complex128','bool','byte','rune','error','any']),
+      comment: C_COMMENT,
+      string: /^"(?:[^"\\]|\\.)*"|^'(?:[^'\\]|\\.)*'|^`[^`]*`/,
+    },
+    ts: {
+      keywords: new Set(TS_KW),
+      types: new Set(TS_TYPES),
+      comment: C_COMMENT,
+      string: /^"(?:[^"\\]|\\.)*"|^'(?:[^'\\]|\\.)*'|^`(?:[^`\\]|\\.)*`/,
+    },
+    c: {
+      keywords: new Set(C_KW),
+      types: new Set(C_TYPES),
+      comment: C_COMMENT,
+      directive: /^#\s*[a-z]+/,
+    },
+    cpp: {
+      keywords: new Set(C_KW.concat(['class','namespace','template','typename','public','private','protected','virtual','override','final','new','delete','this','nullptr','using','try','catch','throw','operator','friend','explicit','constexpr','noexcept','static_cast','dynamic_cast','reinterpret_cast','const_cast','decltype','mutable'])),
+      types: new Set(C_TYPES.concat(['std','string','vector','wchar_t','char16_t','char32_t'])),
+      comment: C_COMMENT,
+      directive: /^#\s*[a-z]+/,
+    },
+  };
+  LANGS.js = LANGS.typescript = LANGS.tsx = LANGS.javascript = LANGS.ts;
+  const STRING = /^"(?:[^"\\]|\\.)*"|^'(?:[^'\\]|\\.)*'/;
+
+  function tokenize(line, lang) {
+    const L = LANGS[lang] || LANGS.java;
+    const out = [];
+    let i = 0;
+    while (i < line.length) {
+      const rest = line.slice(i);
+      let m;
+      if ((m = L.comment.exec(rest))) { out.push(['c', m[0]]); i += m[0].length; continue; }
+      if (L.directive && (m = L.directive.exec(rest))) { out.push(['k', m[0]]); i += m[0].length; continue; }
+      if ((m = (L.string || STRING).exec(rest))) { out.push(['s', m[0]]); i += m[0].length; continue; }
+      if ((m = /^[A-Za-z_$][\w$]*/.exec(rest))) {
+        const w = m[0];
+        const kind = L.keywords.has(w) ? 'k' : L.types.has(w) ? 't' : (/^[A-Z]/.test(w) ? 't' : (rest[w.length] === '(' ? 'f' : 'p'));
+        out.push([kind, w]); i += w.length; continue;
+      }
+      if ((m = /^\d+(?:\.\d+)?/.exec(rest))) { out.push(['n', m[0]]); i += m[0].length; continue; }
+      if ((m = /^[{}()[\];,.]/.exec(rest))) { out.push(['u', m[0]]); i += 1; continue; }
+      out.push(['p', rest[0]]); i += 1;
+    }
+    return out;
+  }
+
+  const esc = s => s.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;');
+
+  function highlight(line, lang) {
+    return tokenize(line, lang).map(([k, txt]) => `<span class="t-${k}">${esc(txt)}</span>`).join('');
+  }
+
+  /* One panel's lines as markup. The number column shows numbers[i] when the panel
+     carries real line numbers (blank on an elision marker), else counts from 1. */
+  function panelLinesHtml(p) {
+    const elided = new Set((p.elided || []).map(e => (typeof e === 'number' ? e : e.at)));
+    return p.lines.map((ln, i) => {
+      const num = p.numbers ? p.numbers[i] : i + 1;
+      return elided.has(i)
+        ? `<div class="ln elided" data-i="${i}"><span class="num">${num == null ? '' : num}</span><span class="txt">${esc(ln)}</span></div>`
+        : `<div class="ln" data-i="${i}"><span class="num">${num == null ? '' : num}</span><span class="txt">${highlight(ln, p.lang || 'java')}</span></div>`;
+    }).join('');
+  }
+
+  /* The focus window in force at t, and how far its dim has faded in. A panel with
+     real line numbers (an excerpt) has one window per narrated sentence; a window
+     that starts as the previous one ends keeps the dim instead of flashing back.
+     A coursework panel (no numbers[]) keeps its one, first focus act. */
+  function focusState(acts, panel, numbered, t) {
+    const all = acts.filter(a => a.op === 'focus' && a.panel === panel);
+    const wins = numbered ? all : all.slice(0, 1);
+    if (!wins.length) return null;
+    const live = wins.filter(f => inWin(t, f.from, f.to));
+    const foc = live.length ? live[live.length - 1] : wins[0];
+    const active = live.length > 0;
+    const chained = wins.some(w => w !== foc && w.to != null && Math.abs(w.to - foc.from) < 0.05);
+    const k = active ? (chained ? 1 : fadeIn(t, foc.from, foc.from + 0.5)) : 0;
+    return { foc, active, k };
+  }
+
+  /* The clock a scene plays on. A coursework scene is timed on the video clock and
+     spans its own `total`; a scene naming its `segment` is timed from that window's
+     start, read from the measured timeline, and spans the whole timeline like the
+     diagram and svg hosts. A named segment with no window is an error, never t + 0. */
+  function clockOf(cfg, timeline) {
+    if (cfg.segment == null) return { offset: 0, total: cfg.total };
+    const w = timeline && timeline.windows && timeline.windows[cfg.segment];
+    if (!w) throw new Error(`scene names segment "${cfg.segment}" but the timeline has no window for it (run build-audio, and open the host with ?work=)`);
+    return { offset: w.start, total: timeline.total };
+  }
+
+  /* ---------------- factory ---------------- */
+  function create(opts) {
+    const root = opts.root;
+    const cfg = opts.config;
+    const W = (cfg.meta && cfg.meta.width) || 1920;
+    const H = (cfg.meta && cfg.meta.height) || 1080;
+    const TOTAL = cfg.total;
+    const PROGRESS = cfg.segment == null;
+
+    root.innerHTML = '';
+
+    /* --- background grid --- */
+    const NS = 'http://www.w3.org/2000/svg';
+    const svg = document.createElementNS(NS, 'svg');
+    svg.setAttribute('width', W); svg.setAttribute('height', H);
+    svg.style.position = 'absolute'; svg.style.inset = '0';
+    const grid = document.createElementNS(NS, 'g');
+    grid.setAttribute('opacity', '0.5');
+    for (let x = 0; x <= W; x += 60) {
+      const l = document.createElementNS(NS, 'line');
+      l.setAttribute('x1', x); l.setAttribute('y1', 0); l.setAttribute('x2', x); l.setAttribute('y2', H);
+      l.setAttribute('stroke', x % 300 === 0 ? '#182742' : '#111d33'); l.setAttribute('stroke-width', 1);
+      grid.appendChild(l);
+    }
+    for (let y = 0; y <= H; y += 60) {
+      const l = document.createElementNS(NS, 'line');
+      l.setAttribute('x1', 0); l.setAttribute('y1', y); l.setAttribute('x2', W); l.setAttribute('y2', y);
+      l.setAttribute('stroke', y % 300 === 0 ? '#182742' : '#111d33'); l.setAttribute('stroke-width', 1);
+      grid.appendChild(l);
+    }
+    svg.appendChild(grid);
+    root.appendChild(svg);
+
+    /* --- chrome --- */
+    const chrome = document.createElement('div');
+    chrome.className = 'chrome';
+    chrome.innerHTML =
+      `<div class="hdr"><span class="hdr-dot"></span><span>${esc((cfg.chrome && cfg.chrome.header) || '')}</span></div>` +
+      `<div class="stage-badge" id="stageBadge"></div>` +
+      (PROGRESS ? `<div class="prog"><div class="prog-fill" id="progFill"></div></div>` : '');
+    root.appendChild(chrome);
+
+    /* --- panels --- */
+    const panelWrap = document.createElement('div');
+    panelWrap.className = 'panel-wrap';
+    root.appendChild(panelWrap);
+
+    const panels = {};
+    (cfg.panels || []).forEach(p => {
+      const el = document.createElement('div');
+      el.className = `panel accent-${p.accent || 'ok'}`;
+      const lines = panelLinesHtml(p);
+      el.innerHTML =
+        `<div class="card">` +
+        `<div class="tab"><span class="dot"></span><span class="fname">${esc(p.file || '')}</span>` +
+        (p.badge ? `<span class="badge">${esc(p.badge)}</span>` : '') + `</div>` +
+        `<div class="code">${lines}</div></div>`;
+      panelWrap.appendChild(el);
+      panels[p.id] = { spec: p, el, lineEls: Array.from(el.querySelectorAll('.ln')), w: 0, h: 0 };
+    });
+
+    // natural size, measured once so layouts can centre panels exactly
+    Object.values(panels).forEach(p => {
+      p.el.style.transform = 'none';
+      const r = p.el.getBoundingClientRect();
+      p.w = r.width; p.h = r.height;
+    });
+
+    /* --- annotation notes --- */
+    const noteWrap = document.createElement('div');
+    noteWrap.className = 'note-wrap';
+    root.appendChild(noteWrap);
+    const notes = {};
+    (cfg.notes || []).forEach(n => {
+      const el = document.createElement('div');
+      el.className = `note note-${n.accent || 'hub'}`;
+      el.innerHTML = esc(n.text);
+      el.style.left = n.at[0] + 'px';
+      el.style.top = n.at[1] + 'px';
+      noteWrap.appendChild(el);
+      notes[n.id] = { spec: n, el };
+    });
+
+    // line text lengths, measured once — used for weighted reveal timing
+    Object.values(panels).forEach(p => {
+      p.lineLens = p.lineEls.map(el => {
+        const t = el.querySelector('.txt');
+        return t ? t.textContent.length : 0;
+      });
+    });
+
+    /* --- acts, normalised --- */
+    const acts = cfg.acts || [];
+
+    /* --- pause badge: built only when a `pause` act asks for it --- */
+    const pauses = acts.filter(a => a.op === 'pause');
+    let pauseEl = null;
+    if (pauses.length) {
+      pauseEl = document.createElement('div');
+      pauseEl.className = 'pause-badge';
+      pauseEl.innerHTML = '<span class="pause-icon"><i></i><i></i></span><span class="pause-text"></span>';
+      root.appendChild(pauseEl);
+    }
+    const actOf = (op, panel) => acts.filter(a => a.op === op && (!panel || a.panel === panel));
+
+    /**
+     * Per-line reveal offsets.
+     *
+     * A uniform stagger gives a blank line the same screen time as a 60-character
+     * statement, which reads as a race. Real dwell is proportional to what is on
+     * the line: a base cost for the eye to land, plus a cost per character.
+     */
+    function revealOffsets(p, rev) {
+      if (rev.stagger != null) {
+        return { starts: p.lineEls.map((_, i) => i * rev.stagger), natural: (p.lineEls.length - 1) * rev.stagger };
+      }
+      const base = rev.dwell && rev.dwell.base != null ? rev.dwell.base : 0.28;
+      const perChar = rev.dwell && rev.dwell.perChar != null ? rev.dwell.perChar : 0.038;
+      const speed = rev.speed || 1;
+      const starts = [];
+      let acc = 0;
+      p.lineLens.forEach(len => { starts.push(acc); acc += (base + len * perChar) / speed; });
+      return { starts, natural: acc };
+    }
+
+    const initOf = id => (cfg.initLayout && cfg.initLayout[id]) || { cx: W / 2, cy: H / 2, scale: 1 };
+
+    /** Pure: interpolate through the ordered layout acts. No mutation between frames. */
+    const layoutAt = (panelId, t) => {
+      const ls = acts.filter(a => a.op === 'layout' && a.panel === panelId);
+      const init = initOf(panelId);
+      let cur = init;
+      for (let i = 0; i < ls.length; i++) {
+        const a = ls[i];
+        if (t < a.from) break;
+        const from = i === 0 ? init : ls[i - 1].to;
+        const k = easeIO(seg(t, a.from, a.to));
+        cur = {
+          cx: lerp(from.cx, a.to.cx, k),
+          cy: lerp(from.cy, a.to.cy, k),
+          scale: lerp(from.scale, a.to.scale, k),
+        };
+      }
+      return cur;
+    };
+
+    /* ---------------- render(t) ---------------- */
+    let prevStage = null;
+
+    function render(t) {
+      /* panels */
+      Object.entries(panels).forEach(([id, p]) => {
+        const show = acts.find(a => a.op === 'show' && a.panel === id);
+        const hide = acts.find(a => a.op === 'hide' && a.panel === id);
+        let op = 1;
+        if (show) op = fadeIn(t, show.from, show.to);
+        if (hide) op *= fadeOut(t, hide.from, hide.to);
+
+        const lay = layoutAt(id, t);
+        const x = lay.cx - (p.w * lay.scale) / 2;
+        const y = lay.cy - (p.h * lay.scale) / 2;
+        p.el.style.opacity = op.toFixed(3);
+        p.el.style.transform = `translate(${x.toFixed(1)}px, ${y.toFixed(1)}px) scale(${lay.scale.toFixed(4)})`;
+
+        /* line reveal + focus */
+        const rev = acts.find(a => a.op === 'reveal' && a.panel === id);
+        const fs = focusState(acts, id, !!p.spec.numbers, t);
+        const off = rev ? revealOffsets(p, rev) : null;
+
+        p.lineEls.forEach((ln, i) => {
+          let lineOp = 1;
+          if (rev) lineOp = fadeIn(t, rev.from + off.starts[i], rev.from + off.starts[i] + 0.30);
+
+          let dim = 1;
+          if (fs) {
+            const inFocus = fs.foc.lines.includes(i + 1);
+            dim = inFocus ? 1 : lerp(1, 0.28, fs.k);
+          }
+          ln.style.opacity = (lineOp * dim).toFixed(3);
+          ln.classList.toggle('focused', !!fs && fs.foc.lines.includes(i + 1) && fs.active);
+        });
+      });
+
+      /* notes */
+      Object.values(notes).forEach(n => {
+        const o = fadeIn(t, n.spec.from, n.spec.from + 0.5) * fadeOut(t, n.spec.to - 0.5, n.spec.to);
+        n.el.style.opacity = o.toFixed(3);
+        n.el.style.transform = `translate(-50%, ${((1 - fadeIn(t, n.spec.from, n.spec.from + 0.5)) * 14).toFixed(1)}px)`;
+      });
+
+      /* stage badge driven by a `phase` list */
+      const phases = cfg.phases || [];
+      let cur = null;
+      for (const ph of phases) if (t >= ph.from) cur = ph;
+      const badge = root.querySelector('#stageBadge');
+      if (cur) {
+        if (cur.name !== prevStage) { badge.textContent = cur.name; prevStage = cur.name; }
+        const local = t - cur.from;
+        const dur = (cur.to == null ? TOTAL : cur.to) - cur.from;
+        badge.style.opacity = (clamp01(local / 0.3) * clamp01((dur - local) / 0.3) * 0.98).toFixed(3);
+      } else {
+        badge.style.opacity = '0';
+      }
+
+      /* pause badge: up while the narration asks the viewer to pause and read */
+      if (pauseEl) {
+        const live = pauses.filter(a => inWin(t, a.from, a.to));
+        const a = live.length ? live[live.length - 1] : null;
+        pauseEl.style.opacity = a ? (fadeIn(t, a.from, a.from + 0.3) * fadeOut(t, a.to - 0.3, a.to)).toFixed(3) : '0';
+        if (a) pauseEl.querySelector('.pause-text').textContent = a.text || 'PAUSE · READ THE WHOLE BLOCK';
+      }
+
+      /* progress */
+      if (PROGRESS) root.querySelector('#progFill').style.width = (W * clamp01(t / TOTAL)).toFixed(1) + 'px';
+    }
+
+    render(0);
+    return { renderAt: render };
+  }
+
+  window.CodeScenes = { create, clockOf, highlight, panelLinesHtml, focusState };
+})();