stagecraft 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Daniel Nögel
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

package/README.md

@@ -0,0 +1,210 @@
+# Stagecraft
+
+**Cinematic, agent-authored presentations in a single HTML file.**
+
+▶ **[Live demo](https://noegel.io/stagecraft/)** — the deck about Stagecraft, built with Stagecraft. Auto-deployed from `main` via GitHub Pages.
+
+A small JavaScript library for building animated slide decks that live in a single HTML file. Designed so an LLM can generate a deck that doesn't look like an LLM generated it.
+
+## Why
+
+Generic slide libraries produce generic decks. Stagecraft is built around a different premise: **the agent is a creative director, not a form-filler**. The library ships a catalog of building blocks (50 components across 7 families) AND five bespoke example slides — `examples/token-stream.js`, `examples/orchestration-graph.js`, `examples/terminal-log.js` — that show what the bar looks like. `AGENT.md` is the manifesto.
+
+## Quick start
+
+```bash
+mkdir my-deck && cd my-deck
+npm init -y
+npm install stagecraft
+npx stagecraft init
+```
+
+This scaffolds:
+
+```
+my-deck/
+├── index.html             # opens directly in a browser to present
+├── stagecraft.config.js   # the manifest: theme + slide order + transitions
+├── slides/
+│   └── 00-title.js
+└── AGENT.md               # the manifesto the agent reads
+```
+
+Present mode (no setup, no infrastructure):
+```bash
+open index.html
+```
+
+## Two modes, one HTML file
+
+### Presentation mode
+
+Open `index.html` directly. Use arrow keys, space, or page-up/down to navigate. `F` for fullscreen, `S` for storyboard, `1-9` to jump to a section, `R` to replay the current slide, `P` to open the presenter view.
+
+### Edit mode (dev server)
+
+```bash
+npx stagecraft serve
+```
+
+The browser detects the server and unlocks the editing affordances:
+
+- **Drag slides** in the storyboard to reorder
+- **Click transitions** between storyboard tiles to pick from 15 effects with hover preview
+- **Click any text** on a Layer-2 component to inline-edit (writes back to source via AST roundtrip)
+- **Shift+Click** any element to pin a `// @note[stage-key=...]:` comment for the agent
+- **N** in present mode opens a slide-level note dialog
+- **🎙 button** per tile in storyboard: speaker notes (shown in presenter view, hidden from audience)
+- **× button** per tile: delete slide
+- **+ tile** at the end of the grid: add a new slide from a template
+- **Theme picker** at the top of the storyboard: live-switch between Phosphor/Paper/Neon/Brand/Shopware
+- **📋 Process notes** copies a ready-made agent prompt to the clipboard
+
+When you ask the agent to "process my notes":
+1. `grep -rn '@note' slides/`
+2. Read each note + its slide
+3. Edit the slide
+4. Delete the `@note:` lines
+
+That's the whole loop.
+
+## Presenter view (multi-monitor)
+
+Press `P` during a presentation → a new window opens with the presenter view:
+
+- **Left:** current slide (live)
+- **Right:** next slide thumbnail
+- **Below:** speaker notes + elapsed timer + wall clock + reset
+
+Drag the presenter window to your laptop screen, drag the main window to the beamer (or vice versa), full-screen the main one. Both windows stay synchronized via the browser's `BroadcastChannel` API: any nav action in either window updates the other.
+
+## 50 components in 7 families
+
+| Family | Count | Examples |
+|---|---|---|
+| **Core** | 6 | KineticText, SectionCard, ActivityList, Compare, Counter, ShiftArrow |
+| **Layout** | 6 | ImageText, FullImage, Quote, BigNumber, Stats, Bento |
+| **Diagram** | 5 | Pillars, Timeline, Pyramid, Cycle, Funnel |
+| **Chart** | 5 | Matrix2x2, BarChart, Progress, ProcessFlow, Venn |
+| **Data-viz** | 10 | KPI, DonutChart, LineChart, Gauge, SparkLine, Heatmap, Roadmap, SWOT, CodeBlock, CodeDiff |
+| **Business** | 10 | Pricing, Testimonial, TeamGrid, Agenda, Checklist, Steps, CTA, Callout, Tip, BeforeAfter |
+| **Content** | 8 | Statement, QandA, Manifesto, Punchline, Definition, ImageGrid, Spotlight, Marquee |
+
+50 anchors total + 5 bespoke cookbook examples (`examples/`). See `AGENT.md` for the full catalog with code examples.
+
+## 15 transitions
+
+Set in the manifest:
+```js
+Stage.deck({
+  slides: [
+    { src: 'slides/00-title.js' },
+    { src: 'slides/01-shift.js', transition: 'glitch' }
+  ]
+});
+```
+
+Built-in: `cut · fade · slide · dissolve · glitch · wipe · zoom-in · zoom-out · flip · iris · shutter · push · typewriter · shatter` (plus the `cut`-preview-only animation).
+
+Themes override visuals. Unknown name → falls back to `fade`. Hover any transition in the picker to play it once.
+
+## 5 themes
+
+| Theme | Vibe | Typography |
+|---|---|---|
+| **Phosphor** | Cinematic, technical, dark. Phosphor-green + film grain | JetBrains Mono |
+| **Paper** | Academic, restrained, light. Navy accent, no glow | Inter + Source Serif 4 |
+| **Neon** | Cyberpunk, magenta + cyan, heavy glow | Space Grotesk + JetBrains Mono |
+| **Brand** | Corporate, schlicht. Blue accent, GitHub-dark adjacent | Inter |
+| **Shopware** | Official Shopware brand. Light, Meteor design tokens, brand-blue `#0870ff` | Inter |
+
+Switch live from the edit-mode storyboard, or set `data-theme="..."` on `<html>` plus link the matching theme CSS bundle.
+
+## Speaker notes
+
+Slides can carry notes for the presenter view:
+
+```js
+Stage.register(Stage.KineticText({
+  section: 2,
+  lines: [...]
+}), {
+  notes: 'Open by reminding them about last quarter\'s incident. Pause for ~5s after "the shift".'
+});
+```
+
+Notes are plain strings, displayed in the presenter window. Hidden from the audience. Edit them via the 🎙 button on each storyboard tile.
+
+## Export to PDF
+
+```bash
+npm install --save-dev playwright pdf-lib
+npx playwright install chromium
+npx stagecraft export pdf --out my-deck.pdf
+```
+
+Renders each slide at 1920×1080, concatenates into a single PDF. Skips transitions; respects each slide's `init()` animation timing (waits 1.2s by default; tune with `--wait`).
+
+## Visual regression tests
+
+```bash
+npm install --save-dev playwright pixelmatch pngjs
+npx playwright install chromium
+npm run test:visual:update    # one-time: capture baseline
+# ... make changes ...
+npm run test:visual           # diff against baseline
+```
+
+Catches the kind of bugs where a Venn label drifts or a Heatmap layout breaks under refactor. Diffs land in `tests/visual/diff/`.
+
+## Accessibility
+
+Stagecraft respects `prefers-reduced-motion`:
+- All CSS transitions/animations reduced to ~0ms globally
+- JS animations (typewriter, particle emission, stagger) shortcut to final state immediately
+
+The reduced-motion preference is OS-level — Stagecraft itself doesn't expose a toggle. If a component's animation is essential to the message, give it a non-animated fallback.
+
+## Architecture (4 layers + convention)
+
+```
+Layer 0  Engine        Stage.register, deck loader, navigation, steps, storyboard, transitions
+Layer 1  Primitives    staggerIn, typewriter, emitParticle, revealByDataStep, ...
+Layer 2  Components    50 building blocks across 7 families
+Layer 3  Cookbook      5 bespoke examples in examples/ — the real teachers
+Layer 4  Convention    AGENT.md — calibrates the agent's taste
+```
+
+See `docs/specs/2026-05-22-stagecraft-sdk-design.md` for the full design rationale.
+
+## Bundle vs. source
+
+- Source: `src/` (~70 files). What you read, edit, contribute against.
+- Bundle: `dist/stagecraft.bundle.js` + `dist/themes/<name>.bundle.css`. Generated by `npm run build`. One script tag instead of 60+. Consumers from npm load these directly via `node_modules/stagecraft/dist/...`.
+
+## Deploying a deck to the web
+
+Stagecraft decks are static HTML. Drop them anywhere:
+
+### gh-pages
+```bash
+# in your deck repo
+git checkout -b gh-pages
+npm run build              # if your index.html uses src/ paths, copy node_modules/stagecraft into the repo first
+git add -A
+git commit -m "deploy"
+git push origin gh-pages
+# Enable Pages in repo settings → branch: gh-pages
+```
+
+### Netlify / Vercel / S3 / anything that serves static files
+
+Same idea: the deck is just HTML + JS + CSS. No runtime dependencies for present mode.
+
+## Status
+
+v0.2 — feature-complete, multi-theme, multi-monitor, exportable. Pre-publication: dogfooding against a real production deck post-talk before tagging 1.0.
+
+## License
+
+MIT — see `LICENSE`.

package/bin/cli.js

@@ -0,0 +1,51 @@
+#!/usr/bin/env node
+'use strict';
+
+/**
+ * stagecraft — dispatcher CLI.
+ *   stagecraft init     scaffold a new project
+ *   stagecraft serve    start dev server with edit mode
+ */
+
+import { spawn } from 'node:child_process';
+import path from 'node:path';
+import url from 'node:url';
+
+const cmd = process.argv[2];
+const rest = process.argv.slice(3);
+const HERE = path.dirname(url.fileURLToPath(import.meta.url));
+
+function run(script) {
+  const child = spawn('node', [path.join(HERE, script), ...rest], { stdio: 'inherit' });
+  child.on('exit', code => process.exit(code ?? 0));
+}
+
+switch (cmd) {
+  case 'init':   run('init.js'); break;
+  case 'serve':  run('serve.js'); break;
+  case 'export':
+    if (rest[0] !== 'pdf') {
+      console.error('Only `export pdf` is supported.');
+      process.exit(1);
+    }
+    rest.shift();
+    run('export.js');
+    break;
+  case '--help':
+  case '-h':
+  case undefined:
+    console.log(`Stagecraft — cinematic, agent-authored presentations.
+
+Usage:
+  stagecraft init                                       scaffold a new project
+  stagecraft serve [--port N] [--root DIR]              dev server (edit mode)
+  stagecraft export pdf [--out deck.pdf] [--root DIR]   render deck to PDF
+                                                        (needs playwright + pdf-lib)
+
+Without the dev server, open index.html in a browser to present.
+Press P during a presentation to open the presenter view in a second window.`);
+    break;
+  default:
+    console.error(`Unknown command: ${cmd}`);
+    process.exit(1);
+}

package/bin/export.js

@@ -0,0 +1,137 @@
+#!/usr/bin/env node
+'use strict';
+
+/**
+ * stagecraft export pdf — render the deck to a PDF.
+ *
+ * Usage:
+ *   npx stagecraft export pdf [--out deck.pdf] [--root .] [--port N]
+ *
+ * Requires (peer): playwright + pdf-lib.
+ *   npm install --save-dev playwright pdf-lib
+ *   npx playwright install chromium
+ *
+ * Strategy:
+ *   1) start the local dev server (no edit-mode UI needed; just static serve)
+ *   2) launch headless chromium
+ *   3) navigate to each slide via #hash, wait for animations to settle
+ *   4) page.pdf() per slide, then concatenate via pdf-lib
+ *   5) write to --out
+ */
+
+import http from 'node:http';
+import fs from 'node:fs';
+import path from 'node:path';
+import url from 'node:url';
+import { spawn } from 'node:child_process';
+
+// --- args ---
+const args = process.argv.slice(2);
+let outPath = 'deck.pdf';
+let rootArg = '.';
+let port = 4040;
+let waitMs = 1200;
+for (let i = 0; i < args.length; i++) {
+  if (args[i] === '--out') outPath = args[++i];
+  else if (args[i] === '--root') rootArg = args[++i];
+  else if (args[i] === '--port') port = parseInt(args[++i], 10);
+  else if (args[i] === '--wait') waitMs = parseInt(args[++i], 10);
+}
+
+const ROOT = path.resolve(rootArg);
+
+// --- soft-import optional deps ---
+async function softImport(name) {
+  try { return await import(name); }
+  catch (e) {
+    console.error(`\n[stagecraft] PDF export requires ${name}.`);
+    console.error(`  Install with: npm install --save-dev playwright pdf-lib`);
+    console.error(`  Then:         npx playwright install chromium`);
+    process.exit(1);
+  }
+}
+
+const { chromium } = await softImport('playwright');
+const { PDFDocument } = await softImport('pdf-lib');
+
+// --- start the dev server as a child process (avoid port conflicts with running serve) ---
+console.log(`[stagecraft] starting server on :${port}…`);
+const HERE = path.dirname(url.fileURLToPath(import.meta.url));
+const child = spawn('node', [path.join(HERE, 'serve.js'), '--root', ROOT, '--port', String(port)], {
+  stdio: ['ignore', 'pipe', 'pipe']
+});
+
+// Wait for "http://localhost:" line in the server output
+let serverReady = false;
+child.stdout.on('data', (b) => {
+  const s = b.toString();
+  if (s.includes('http://localhost:')) serverReady = true;
+});
+child.stderr.on('data', b => process.stderr.write(b));
+
+await waitFor(() => serverReady, 5000);
+
+// --- launch headless browser ---
+const browser = await chromium.launch();
+const ctx = await browser.newContext({
+  viewport: { width: 1920, height: 1080 },
+  deviceScaleFactor: 1
+});
+const page = await ctx.newPage();
+
+const baseUrl = `http://localhost:${port}/`;
+console.log(`[stagecraft] navigating to ${baseUrl}…`);
+await page.goto(baseUrl);
+
+// Discover slide count from the runtime
+await page.waitForFunction(() => window.Stage && window.Stage.slides && window.Stage.slides.length > 0, {
+  timeout: 10000
+});
+const slideCount = await page.evaluate(() => window.Stage.slides.length);
+console.log(`[stagecraft] ${slideCount} slides to export`);
+
+// --- iterate slides, page.pdf() per slide, merge ---
+const out = await PDFDocument.create();
+
+for (let i = 0; i < slideCount; i++) {
+  process.stdout.write(`[stagecraft] slide ${String(i + 1).padStart(2, '0')}/${slideCount}…\r`);
+  await page.goto(`${baseUrl}#${i}`);
+  // Hide chrome that doesn't belong in print
+  await page.evaluate(() => {
+    document.querySelectorAll('.ui, .welcome').forEach(n => n.style.display = 'none');
+  });
+  // Wait for the slide to render + animations to settle
+  await page.waitForTimeout(waitMs);
+  const pdfBytes = await page.pdf({
+    width: '1920px',
+    height: '1080px',
+    printBackground: true,
+    pageRanges: '1',
+    preferCSSPageSize: false,
+    margin: { top: 0, bottom: 0, left: 0, right: 0 }
+  });
+  const tmp = await PDFDocument.load(pdfBytes);
+  const [copied] = await out.copyPages(tmp, [0]);
+  out.addPage(copied);
+}
+
+const finalBytes = await out.save();
+fs.writeFileSync(outPath, finalBytes);
+console.log(`\n[stagecraft] wrote ${outPath} (${finalBytes.length} bytes, ${slideCount} pages)`);
+
+await browser.close();
+child.kill();
+process.exit(0);
+
+// --- helpers ---
+function waitFor(pred, ms) {
+  return new Promise((resolve, reject) => {
+    const t0 = Date.now();
+    function tick() {
+      if (pred()) return resolve();
+      if (Date.now() - t0 > ms) return reject(new Error('timeout waiting for server'));
+      setTimeout(tick, 80);
+    }
+    tick();
+  });
+}

package/bin/init.js

@@ -0,0 +1,52 @@
+#!/usr/bin/env node
+'use strict';
+
+/**
+ * stagecraft init — scaffold a new stagecraft project in the current directory.
+ *
+ * Copies the starter/ template + AGENT.md to cwd.
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+import url from 'node:url';
+
+const HERE = path.dirname(url.fileURLToPath(import.meta.url));
+const PKG_ROOT = path.resolve(HERE, '..');
+const SRC = path.join(PKG_ROOT, 'starter');
+const TARGET = process.cwd();
+
+function copyRecursive(src, dst) {
+  const stat = fs.statSync(src);
+  if (stat.isDirectory()) {
+    if (!fs.existsSync(dst)) fs.mkdirSync(dst, { recursive: true });
+    for (const entry of fs.readdirSync(src)) {
+      copyRecursive(path.join(src, entry), path.join(dst, entry));
+    }
+  } else {
+    if (fs.existsSync(dst)) {
+      console.log(`  skip (exists): ${path.relative(TARGET, dst)}`);
+      return;
+    }
+    fs.copyFileSync(src, dst);
+    console.log(`  + ${path.relative(TARGET, dst)}`);
+  }
+}
+
+console.log(`[stagecraft] scaffold → ${TARGET}`);
+copyRecursive(SRC, TARGET);
+
+// Also copy AGENT.md to project root
+const agentMd = path.join(PKG_ROOT, 'AGENT.md');
+if (fs.existsSync(agentMd)) {
+  const dst = path.join(TARGET, 'AGENT.md');
+  if (!fs.existsSync(dst)) {
+    fs.copyFileSync(agentMd, dst);
+    console.log(`  + AGENT.md`);
+  }
+}
+
+console.log('\nDone. Next steps:');
+console.log('  npx stagecraft serve     # dev server with edit mode');
+console.log('  open index.html          # presentation only');
+console.log('  read AGENT.md            # the manifesto');