stagecraft 0.1.0

package/examples/closing-card.js

@@ -0,0 +1,74 @@
+'use strict';
+
+/**
+ * Cookbook · Closing Card
+ * -----------------------
+ * Technique: a staggered-reveal closing slide with a live-rendered QR
+ * code, theme-matched, with a graceful URL-text fallback if the CDN
+ * dependency fails to load.
+ *
+ * Dependency:
+ *  This slide expects `qrcode-generator` (global `qrcode` function) to be
+ *  loaded ahead of it. Add to your index.html:
+ *    <script src="https://cdn.jsdelivr.net/npm/qrcode-generator@1.4.4/qrcode.min.js"></script>
+ *  The slide expects a URL at `Stage.CLOSING_URL` (set it from your config
+ *  or inline before the deck boots).
+ *
+ * What to copy:
+ *  - The fallback-first DOM: the markup ships with the URL rendered as
+ *    text inside `#qrFrame`. If the QR library loads, `renderQR` replaces
+ *    that content with an inline SVG. If not, the text remains — no
+ *    "broken image" state, no error UI.
+ *  - String-rewriting the QR library's SVG (`fill="black"` → theme color)
+ *    instead of restyling via CSS — `qrcode-generator` emits raw SVG, so
+ *    a regex replace is the most direct path to a theme-matched code.
+ *  - `Stage.staggerIn(el.querySelectorAll('.stagger > *'), 180)` for a
+ *    soft sequential reveal. Pair with `.stagger > *` CSS in your theme
+ *    (initial opacity 0; `.in` class triggers transition).
+ *  - The `<div class="thanks-underline">` is intentionally empty — pure
+ *    CSS decoration to ground the headline.
+ */
+
+function renderQR(el) {
+  const frame = el.querySelector('#qrFrame');
+  if (!frame) return;
+  if (typeof qrcode !== 'function') return; // CDN failed — fallback stays
+  try {
+    const qr = qrcode(0, 'M');
+    qr.addData(Stage.CLOSING_URL);
+    qr.make();
+    const svg = qr.createSvgTag({ cellSize: 6, margin: 2, scalable: true });
+    const themed = svg
+      .replace(/fill="black"/g, 'fill="#E6E6E6"')
+      .replace(/fill="white"/g, 'fill="#0d0d0d"')
+      .replace(/<svg /, '<svg style="width:240px;height:240px;display:block;" ');
+    frame.innerHTML = themed;
+  } catch (e) {
+    console.warn('QR render failed', e);
+  }
+}
+
+Stage.register({
+  section: 5,
+  title: 'Example · Closing Card',
+  render(el) {
+    el.innerHTML = `
+      <div class="closing-wrap stagger">
+        <div class="pre-label blue"><span class="dot"></span>Continue the conversation</div>
+        <div class="qr-frame" id="qrFrame">
+          <div class="qr-fallback">${Stage.CLOSING_URL}</div>
+        </div>
+        <div class="thanks">Thank you.</div>
+        <div class="thanks-underline"></div>
+        <div class="thanks-names">
+          <strong>Presenter One</strong>&nbsp;&nbsp;·&nbsp;&nbsp;<strong>Presenter Two</strong>
+        </div>
+        <div class="thanks-url"><span class="accent-blue">→</span>&nbsp;&nbsp;${Stage.CLOSING_URL}</div>
+      </div>
+    `;
+  },
+  init(el) {
+    Stage.staggerIn(el.querySelectorAll('.stagger > *'), 180);
+    renderQR(el);
+  }
+});

package/examples/orchestration-graph.js

@@ -0,0 +1,156 @@
+'use strict';
+
+/**
+ * Cookbook · Orchestration Graph
+ * ------------------------------
+ * Technique: SVG hex graph with a center node and N satellites,
+ * pulses + particles flowing inward.
+ *
+ * What to copy:
+ *  - Polar-to-cartesian satellite layout: place N items on a circle
+ *    by mapping each `angle` (degrees) to (cos, sin) * R.
+ *  - The `document.createElementNS('http://www.w3.org/2000/svg', ...)`
+ *    pattern — needed for SVG nodes; plain createElement won't render.
+ *  - Staggered fade-in with per-item `setTimeout` offsets — gives
+ *    the graph a "build itself" feel rather than popping in.
+ *  - `Stage.emitParticle(parent, x1, y1, x2, y2, dur)` flowing
+ *    satellite → center; combine with a transient `.active` class on
+ *    the source node for a synchronized pulse.
+ *  - Combined cleanup: track both setInterval AND setTimeout in one
+ *    `intervals` array — `clearTimeout`/`clearInterval` are interchangeable
+ *    in browsers for IDs from either, so a single cleanup loop works.
+ */
+
+function playOrchestrationGraph(el) {
+  const nodesG = el.querySelector('#nodes');
+  const edgesG = el.querySelector('#edges');
+  const particlesG = el.querySelector('#particles');
+  if (!nodesG) return () => {};
+  nodesG.innerHTML = '';
+  edgesG.innerHTML = '';
+  particlesG.innerHTML = '';
+
+  const satellites = [
+    { id: 'n1', label: 'Node 1', angle: -90 },
+    { id: 'n2', label: 'Node 2', angle: -30 },
+    { id: 'n3', label: 'Node 3', angle:  30 },
+    { id: 'n4', label: 'Node 4', angle:  90 },
+    { id: 'n5', label: 'Node 5', angle: 150 },
+    { id: 'n6', label: 'Node 6', angle: -150 },
+  ];
+  const R = 150;
+  const nodeR = 40;
+
+  const positions = { center: { x: 0, y: 0 } };
+  satellites.forEach(s => {
+    const rad = s.angle * Math.PI / 180;
+    positions[s.id] = { x: Math.cos(rad) * R, y: Math.sin(rad) * R };
+  });
+
+  // edges
+  satellites.forEach(s => {
+    const p = positions[s.id];
+    const line = document.createElementNS('http://www.w3.org/2000/svg', 'line');
+    line.setAttribute('class', 'edge');
+    line.setAttribute('x1', 0);
+    line.setAttribute('y1', 0);
+    line.setAttribute('x2', p.x);
+    line.setAttribute('y2', p.y);
+    edgesG.appendChild(line);
+  });
+
+  // satellites
+  satellites.forEach(s => {
+    const p = positions[s.id];
+    const g = document.createElementNS('http://www.w3.org/2000/svg', 'g');
+    g.setAttribute('transform', `translate(${p.x}, ${p.y})`);
+    g.setAttribute('data-id', s.id);
+
+    const c = document.createElementNS('http://www.w3.org/2000/svg', 'circle');
+    c.setAttribute('class', 'node-circle');
+    c.setAttribute('r', nodeR);
+    g.appendChild(c);
+
+    const t = document.createElementNS('http://www.w3.org/2000/svg', 'text');
+    t.setAttribute('class', 'node-label');
+    t.textContent = s.label;
+    g.appendChild(t);
+
+    nodesG.appendChild(g);
+  });
+
+  // center node
+  {
+    const g = document.createElementNS('http://www.w3.org/2000/svg', 'g');
+    const c = document.createElementNS('http://www.w3.org/2000/svg', 'circle');
+    c.setAttribute('class', 'node-circle center');
+    c.setAttribute('r', 52);
+    g.appendChild(c);
+    const t = document.createElementNS('http://www.w3.org/2000/svg', 'text');
+    t.setAttribute('class', 'node-label center');
+    t.textContent = 'CORE';
+    g.appendChild(t);
+    nodesG.appendChild(g);
+  }
+
+  let cancelled = false;
+  const intervals = [];
+
+  // fade-in nodes + edges
+  nodesG.querySelectorAll('g').forEach((n, i) => {
+    n.style.opacity = '0';
+    n.style.transition = 'opacity 500ms ease-out';
+    setTimeout(() => { if (!cancelled) n.style.opacity = '1'; }, 200 + i * 120);
+  });
+  edgesG.querySelectorAll('line').forEach((e, i) => {
+    e.style.opacity = '0';
+    e.style.transition = 'opacity 700ms ease-out';
+    setTimeout(() => { if (!cancelled) e.style.opacity = '1'; }, 600 + i * 80);
+  });
+
+  // particles flow inward (satellite → center)
+  let pulseIdx = 0;
+  const pulse = () => {
+    if (cancelled) return;
+    const s = satellites[pulseIdx % satellites.length];
+    const nodeG = nodesG.querySelector(`[data-id="${s.id}"]`);
+    const circle = nodeG?.querySelector('.node-circle');
+    if (circle) {
+      circle.classList.add('active');
+      setTimeout(() => circle.classList.remove('active'), 700);
+    }
+    const p = positions[s.id];
+    Stage.emitParticle(particlesG, p.x, p.y, 0, 0, 1100);
+    pulseIdx++;
+  };
+  const startT = setTimeout(() => {
+    pulse();
+    intervals.push(setInterval(pulse, 900));
+  }, 1400);
+  intervals.push(startT);
+
+  return () => {
+    cancelled = true;
+    intervals.forEach(clearTimeout);
+    intervals.forEach(clearInterval);
+  };
+}
+
+Stage.register({
+  section: 2,
+  title: 'Example · Orchestration Graph',
+  render(el) {
+    el.innerHTML = `
+      <div class="graph-wrap">
+        <svg class="graph-svg" viewBox="-200 -200 400 400">
+          <g class="edges" id="edges"></g>
+          <g class="particles" id="particles"></g>
+          <g class="nodes" id="nodes"></g>
+        </svg>
+        <div class="graph-caption">The core coordinates <span style="color:var(--accent)">node 1 · node 2 · node 3 · …</span></div>
+      </div>
+    `;
+  },
+  init(el) { return playOrchestrationGraph(el); },
+  replay(el) { return playOrchestrationGraph(el); }
+});

package/examples/terminal-log.js

@@ -0,0 +1,109 @@
+'use strict';
+
+/**
+ * Cookbook · Terminal Log
+ * -----------------------
+ * Technique: streaming colored log lines that build a small narrative —
+ * a stream of "successful" output, a long pause, then a contrasting
+ * realization line and a final highlighted reveal.
+ *
+ * What to copy:
+ *  - The data-driven log model: an array of `{lvl, src, msg}` rows
+ *    rendered by a single `renderLine(line, delay)` helper. Keeps
+ *    the timing logic separate from the content.
+ *  - Linear schedule with `200 + i * 280` — predictable cadence
+ *    that still reads as "live". Pair with a longer gap (1400ms)
+ *    before the punchline so the audience has time to catch up.
+ *  - The three "phases": (1) loop of normal lines, (2) interjection
+ *    in a different color/class, (3) final emphasis line with a caret.
+ *  - The `node.style.opacity = '1'` inside `requestAnimationFrame`
+ *    after appending — guarantees the transition runs from 0 → 1.
+ *  - The terminal chrome (3 dots + title bar) is just static HTML —
+ *    the only animated region is `#termBody`.
+ */
+
+function playTerminalLog(el) {
+  const body = el.querySelector('#termBody');
+  body.innerHTML = '';
+  let cancelled = false;
+  const timers = [];
+
+  const lines = [
+    { lvl: 'INFO', src: 'agent.run',       msg: 'task=do_thing start' },
+    { lvl: 'INFO', src: 'tool.step.one',   msg: 'OK — step one finished' },
+    { lvl: 'INFO', src: 'tool.step.two',   msg: 'OK — step two finished (id=abc123)' },
+    { lvl: 'INFO', src: 'agent.observe',   msg: 'no errors detected' },
+    { lvl: 'INFO', src: 'tool.step.three', msg: 'OK — step three finished' },
+    { lvl: 'INFO', src: 'agent.check',     msg: 'OK — 0 / 0 checks failed' },
+    { lvl: 'INFO', src: 'agent.run',       msg: 'task=do_thing complete' },
+    { lvl: 'INFO', src: 'agent.run',       msg: 'task=announce start' },
+    { lvl: 'WARN', src: 'tool.notify',     msg: 'OK — posted notification "all good"' },
+  ];
+
+  const renderLine = (line, delay) => {
+    timers.push(setTimeout(() => {
+      if (cancelled) return;
+      const ts = new Date(Date.now() - (lines.length - timers.length) * 1700);
+      const tstr = ts.toISOString().slice(11, 19);
+      const node = document.createElement('span');
+      node.className = `log-line ${line.lvl.toLowerCase()}`;
+      node.innerHTML = `<span class="ts">${tstr}</span><span class="lvl">${line.lvl}</span>[<span class="src">${line.src}</span>] ${line.msg}`;
+      body.appendChild(node);
+      requestAnimationFrame(() => {
+        node.style.transition = 'opacity 250ms ease-out';
+        node.style.opacity = '1';
+      });
+    }, delay));
+  };
+
+  lines.forEach((l, i) => renderLine(l, 200 + i * 280));
+
+  // long pause… then human-style realization in a contrasting color
+  timers.push(setTimeout(() => {
+    if (cancelled) return;
+    const node = document.createElement('span');
+    node.className = 'log-line human';
+    node.innerHTML = `<br>// wait — "0 / 0 checks failed" because 0 checks exist.`;
+    body.appendChild(node);
+    requestAnimationFrame(() => {
+      node.style.transition = 'opacity 600ms ease-out';
+      node.style.opacity = '1';
+    });
+  }, 200 + lines.length * 280 + 1400));
+
+  // final emphasized reveal
+  timers.push(setTimeout(() => {
+    if (cancelled) return;
+    const node = document.createElement('span');
+    node.className = 'log-line error';
+    node.innerHTML = `<span class="ts">··:··:··</span><span class="lvl">ERROR</span>[<span class="src">coverage</span>] no checks for src/feature/ — agent never wrote any<span class="caret" style="margin-left:0.3em"></span>`;
+    body.appendChild(node);
+    requestAnimationFrame(() => {
+      node.style.transition = 'opacity 400ms ease-out';
+      node.style.opacity = '1';
+    });
+  }, 200 + lines.length * 280 + 2700));
+
+  return () => {
+    cancelled = true;
+    timers.forEach(clearTimeout);
+  };
+}
+
+Stage.register({
+  section: 3,
+  title: 'Example · Terminal Log',
+  render(el) {
+    el.innerHTML = `
+      <div class="terminal">
+        <div class="terminal-head">
+          <span class="tdot"></span><span class="tdot"></span><span class="tdot"></span>
+          <span class="ttitle">user@host ~/project — agent.do_thing()</span>
+        </div>
+        <div class="terminal-body" id="termBody"></div>
+      </div>
+    `;
+  },
+  init(el) { return playTerminalLog(el); },
+  replay(el) { return playTerminalLog(el); }
+});

package/examples/token-stream.js

@@ -0,0 +1,96 @@
+'use strict';
+
+/**
+ * Cookbook · Token Stream
+ * -----------------------
+ * Technique: interleaved word-fill across a split panel.
+ *
+ * Two columns ("Side A" / "Side B") fill with words, alternating
+ * A → B → A → B. When one side runs out, the other continues alone.
+ * Only the final landing column gets a caret.
+ *
+ * What to copy:
+ *  - The interleaved queue construction (the for-loop that zips two arrays).
+ *  - The per-item randomized delay (320 + Math.random() * 280) for an
+ *    organic, non-mechanical streaming feel.
+ *  - The inline <style> element pattern — slide-scoped CSS injected by
+ *    the slide itself, decoupled from the global theme.
+ *  - The cancellation pattern: a `cancelled` flag plus a tracked `timers`
+ *    array, returned from `init`/`replay` so the engine can clean up
+ *    when the slide unmounts.
+ */
+
+function playTokenStream(el) {
+  const sideA = ['task A', 'task B', 'task C', 'task D', 'task E', 'task F', 'task G'];
+  const sideB = ['skill 1', 'skill 2', 'skill 3', 'skill 4', 'skill 5', 'skill 6', 'skill 7', 'skill 8'];
+
+  const aEl = el.querySelector('#side-a');
+  const bEl = el.querySelector('#side-b');
+  aEl.innerHTML = '';
+  bEl.innerHTML = '';
+
+  // build interleaved queue: a[0], b[0], a[1], b[1], ...
+  // when one side exhausts, only the other contributes.
+  const queue = [];
+  const max = Math.max(sideA.length, sideB.length);
+  for (let i = 0; i < max; i++) {
+    if (i < sideA.length) queue.push({ container: aEl, word: sideA[i] });
+    if (i < sideB.length) queue.push({ container: bEl, word: sideB[i] });
+  }
+
+  const style = document.createElement('style');
+  style.textContent = `.stream-text .item { transition: opacity 200ms ease-out; }`;
+  el.appendChild(style);
+
+  let idx = 0;
+  let cancelled = false;
+  const timers = [];
+
+  function nextOne() {
+    if (cancelled) return;
+    if (idx >= queue.length) {
+      // landed on side B — attach caret there
+      const c = document.createElement('span');
+      c.className = 'caret';
+      bEl.appendChild(c);
+      return;
+    }
+    const { container, word } = queue[idx++];
+    const item = document.createElement('span');
+    item.className = 'item';
+    item.textContent = word;
+    container.appendChild(item);
+    requestAnimationFrame(() => item.style.opacity = '1');
+    const delay = 320 + Math.random() * 280;
+    timers.push(setTimeout(nextOne, delay));
+  }
+
+  timers.push(setTimeout(nextOne, 400));
+
+  return () => {
+    cancelled = true;
+    timers.forEach(clearTimeout);
+  };
+}
+
+Stage.register({
+  section: 1,
+  title: 'Example · Token Stream',
+  render(el) {
+    el.innerHTML = `
+      <div class="split">
+        <div class="split-col">
+          <div class="split-label cheap"><span class="dot"></span>Side A</div>
+          <div class="stream-text" id="side-a"></div>
+        </div>
+        <div class="split-divider"></div>
+        <div class="split-col">
+          <div class="split-label expensive"><span class="dot"></span>Side B</div>
+          <div class="stream-text" id="side-b"></div>
+        </div>
+      </div>
+    `;
+  },
+  init(el) { return playTokenStream(el); },
+  replay(el) { return playTokenStream(el); }
+});

package/examples/whoami.js

@@ -0,0 +1,90 @@
+'use strict';
+
+/**
+ * Cookbook · whoami
+ * -----------------
+ * Technique: terminal prompt cycling through a list of strings,
+ * landing on a final one.
+ *
+ * What to copy:
+ *  - The replace-in-place pattern: each tick wipes `out.innerHTML`
+ *    and renders one new span. Simpler (and less fiddly) than
+ *    cross-fading between two layered elements.
+ *  - The `isFinal` branch — the last identity gets a different
+ *    class (.final) and a caret appended; the cycle stops there.
+ *  - Cumulative-delay scheduling (`t += 2000`) — easier to reason
+ *    about than computing each delay from the start.
+ *  - The static prompt (`~/path $ whoami`) is plain HTML — only
+ *    the output area animates. Cheap separation of layout vs motion.
+ */
+
+function playWhoami(el) {
+  const out = el.querySelector('#whoami-out');
+  if (!out) return () => {};
+  out.innerHTML = '';
+
+  const identities = [
+    'role_one',
+    'role_two',
+    'role_three',
+    'role_four',
+    'role_five',
+    'role_six',
+    '¯\\_(ツ)_/¯',
+  ];
+
+  let cancelled = false;
+  const timers = [];
+
+  const show = (text, delay, isFinal) => {
+    timers.push(setTimeout(() => {
+      if (cancelled) return;
+      out.innerHTML = '';
+      const span = document.createElement('span');
+      span.className = isFinal ? 'wm-id final' : 'wm-id';
+      span.textContent = text;
+      out.appendChild(span);
+      if (isFinal) {
+        const c = document.createElement('span');
+        c.className = 'caret';
+        out.appendChild(c);
+      }
+      // small fade-in
+      span.style.opacity = '0';
+      span.style.transition = 'opacity 180ms ease-out';
+      requestAnimationFrame(() => { span.style.opacity = '1'; });
+    }, delay));
+  };
+
+  // initial prompt typed already — start cycling — ~2s per identity
+  let t = 700; // initial pause after prompt
+  identities.forEach((id, i) => {
+    const isFinal = i === identities.length - 1;
+    show(id, t, isFinal);
+    t += isFinal ? 0 : 2000;
+  });
+
+  return () => {
+    cancelled = true;
+    timers.forEach(clearTimeout);
+  };
+}
+
+Stage.register({
+  section: 4,
+  title: 'Example · whoami',
+  render(el) {
+    el.innerHTML = `
+      <div class="whoami">
+        <div class="wm-prompt">
+          <span class="wm-path accent">~/example</span>
+          <span class="wm-sigil">$</span>
+          <span class="wm-cmd">whoami</span>
+        </div>
+        <div class="wm-out" id="whoami-out"></div>
+      </div>
+    `;
+  },
+  init(el) { return playWhoami(el); },
+  replay(el) { return playWhoami(el); }
+});

package/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "stagecraft",
+  "version": "0.1.0",
+  "description": "Cinematic, agent-authored presentations in a single HTML file.",
+  "type": "module",
+  "main": "src/engine.js",
+  "bin": {
+    "stagecraft": "bin/cli.js"
+  },
+  "files": [
+    "src",
+    "themes",
+    "dist",
+    "examples",
+    "bin",
+    "starter",
+    "AGENT.md",
+    "README.md"
+  ],
+  "scripts": {
+    "serve": "node bin/serve.js",
+    "init": "node bin/init.js",
+    "demo": "node bin/serve.js --root demo",
+    "verify": "node scripts/verify.js",
+    "build": "node scripts/bundle.js",
+    "test:visual": "node tests/visual/run.js",
+    "test:visual:update": "node tests/visual/run.js --update-baseline",
+    "export": "node bin/export.js"
+  },
+  "dependencies": {
+    "@babel/generator": "^7.24.0",
+    "@babel/parser": "^7.24.0",
+    "@babel/traverse": "^7.24.0",
+    "@babel/types": "^7.24.0",
+    "chokidar": "^3.6.0",
+    "mime-types": "^2.1.35",
+    "ws": "^8.16.0"
+  },
+  "keywords": ["slides", "presentation", "reveal", "agent", "llm"],
+  "license": "MIT"
+}

package/src/components/activity-list.js

@@ -0,0 +1,75 @@
+'use strict';
+
+/**
+ * Stage.ActivityList — numbered items (num · name · description).
+ *
+ * Usage:
+ *   Stage.register(Stage.ActivityList({
+ *     section: 3,
+ *     title: 'Where the work goes',
+ *     items: [
+ *       { num: '01', name: 'Problem framing', desc: 'understand the actual ask' },
+ *       { num: '02', name: 'Architecture',    desc: 'pick the shape' }
+ *     ],
+ *     reveal: 'staggered' // | 'per-click' | 'instant'
+ *   }));
+ *
+ * Spare defaults: passing nothing for `reveal` gives instant.
+ * Use 'staggered' for entrance animation, 'per-click' for step-by-step.
+ */
+
+(function (root) {
+  const Stage = root.Stage = root.Stage || {};
+
+  Stage.ActivityList = function (opts) {
+    const items = opts.items || [];
+    const reveal = opts.reveal || 'instant';
+
+    const slide = {
+      section: opts.section,
+      title: opts.title,
+      transition: opts.transition,
+      render(el) {
+        el.innerHTML = `
+          <div class="activities" data-stage-key="ActivityList">
+            ${items.map((it, i) => `
+              <div class="activity" data-step="${i + 1}" data-stage-key="ActivityList/item[${i}]">
+                <div class="num" data-stage-edit="items[${i}].num">${escape(it.num)}</div>
+                <div class="body">
+                  <div class="name" data-stage-edit="items[${i}].name">${it.name || ''}</div>
+                  ${it.desc ? `<div class="desc" data-stage-edit="items[${i}].desc">${escape(it.desc)}</div>` : ''}
+                </div>
+              </div>
+            `).join('')}
+          </div>
+        `;
+        if (reveal === 'instant') {
+          el.querySelectorAll('.activity').forEach(n => n.classList.add('in'));
+        }
+      }
+    };
+
+    if (reveal === 'staggered') {
+      slide.init = function (el) {
+        return Stage.staggerIn(el.querySelectorAll('.activity'), 300, 200);
+      };
+      slide.replay = function (el) {
+        el.querySelectorAll('.activity').forEach(n => n.classList.remove('in'));
+        return this.init(el);
+      };
+    } else if (reveal === 'per-click') {
+      slide.steps = items.length;
+      slide.onStep = function (el, step) {
+        el.querySelectorAll('.activity').forEach(n => {
+          n.classList.toggle('in', Number(n.dataset.step) <= step);
+        });
+      };
+    }
+
+    return slide;
+  };
+
+  function escape(s) {
+    return String(s).replace(/[&<>"']/g, c => ({'&':'&amp;','<':'&lt;','>':'&gt;','"':'&quot;',"'":'&#39;'}[c]));
+  }
+})(typeof window !== 'undefined' ? window : globalThis);