stagecraft 0.1.0 → 0.2.1

package/AGENT.md

@@ -2,18 +2,104 @@
 
 You're not filling a template. You're directing a scene.
 
-If your slide is fewer than three lines, it's probably boring. The components below are anchors, not cages. Take them apart. Add particles, typewriters, glitch transitions, SVG. The Web Animations API is your friend.
+**Reach for custom JS first. Reach for the component catalog when a pattern truly fits.** The 50 components below are sugar around one tiny primitive — they are anchors, never cages. Take them apart. Write raw `render(el)` and `init(el)` functions. Use the Web Animations API. Use SVG. Use Canvas. Animation is the language of your deck — not a checkbox.
 
-## 1. The rule
+If your slide reads like a filled-in form, you wasted the moment.
 
-- A deck is a collection of `.js` files registered via `Stage.register({...})`.
-- Each slide owns its DOM, its animation, its lifecycle.
-- The engine handles navigation, the storyboard, and transitions.
-- If you copy-paste a component call and don't customize it, you've wasted the opportunity.
+## 1. What a slide actually is
 
-## 2. The toolbox (Layer-2 components)
+There is exactly one foundational API:
 
-Components have spare defaults on purpose. Adding animation is opt-in.
+```js
+Stage.register({
+  section, title,
+  render(el)       { /* set up DOM */ },
+  init(el)?        { /* run animation, return cleanup */ },
+  replay(el)?      { /* re-run on R */ },
+  steps?, onStep?  { /* internal step navigation */ }
+});
+```
+
+That's the whole contract. Everything else — every factory you'll see below — is sugar around this primitive.
+
+### A 100% custom slide (the canonical form)
+
+```js
+Stage.register({
+  section: 2,
+  title: '02 · Custom motion',
+  render(el) {
+    el.innerHTML = `
+      <h1 style="font-size: clamp(3rem, 9vw, 8rem); font-weight: 600;
+                 letter-spacing: -0.025em; text-align: center;">
+        Write <span class="accent">whatever HTML</span> you want.
+      </h1>
+      <svg id="field" viewBox="0 0 800 200"
+           style="width:min(800px,80vw); height:200px; margin-top:2rem;"></svg>
+    `;
+  },
+  init(el) {
+    // Whatever JS animation you want. Web Animations API, RAF, intervals.
+    const svg = el.querySelector('#field');
+    const id = setInterval(() => {
+      const x = Math.random() * 800;
+      Stage.emitParticle(svg, x, 200, x + (Math.random() - 0.5) * 200, -20, 2400);
+    }, 220);
+    return () => clearInterval(id);     // cleanup when slide leaves
+  }
+}, {
+  notes: 'Take this as proof: the catalog is optional. The full power lives here.'
+});
+```
+
+That's a complete, finished slide. No factory required. You can do anything CSS, SVG, Canvas, the Web Animations API, and JS can do — which is everything.
+
+### A factory call (sugar for common shapes)
+
+```js
+Stage.register(Stage.KineticText({
+  lines: [
+    { text: 'Sometimes', color: 'fg' },
+    { text: 'a list of lines', color: 'dim' },
+    { text: 'is enough.', color: 'accent' }
+  ]
+}));
+```
+
+Both forms coexist. Both accept a second `meta` arg for speaker notes (`{ notes: '...' }`).
+
+## 2. When to write custom vs. reach for a factory
+
+**Write a fully custom slide when:**
+- The animation IS the message (token streams, particle fields, terminal logs)
+- You're combining motion patterns no factory covers
+- The slide is the centerpiece of a section — it deserves the time
+- You can see the slide in your head and the catalog can't reproduce it
+
+**Extend a factory's `init` when:**
+- The shape fits (a bulleted list, a quote, a stat grid) but you want extra motion on top
+- Get a factory, then call `Object.assign(slide, { init(el) { … } })` or write a wrapping registration
+
+**Reach for the factory plain when:**
+- It is genuinely the right pattern — list, comparison, divider — and motion sugar via `reveal: 'staggered' | 'per-click'` is enough
+
+A healthy deck: roughly **20–30% bespoke from scratch**, **40% factory + customized init**, **30–40% plain factories**. If your bespoke share is 0%, the deck has gone flat. Add a centerpiece.
+
+## 3. The cookbook (start here for bespoke inspiration)
+
+Five real bespoke slides ship in `examples/` — they are not abstract demos, they are slides from a production deck. Read them before writing your own bespoke:
+
+- `examples/token-stream.js` — interleaved word-fill across a split panel with particle emit
+- `examples/orchestration-graph.js` — SVG hex-graph, particles flowing from satellites to center
+- `examples/terminal-log.js` — streaming colored log lines + a "human realization" reveal arc
+- `examples/whoami.js` — terminal prompt cycling through identity strings
+- `examples/closing-card.js` — QR + dedication + underline + presenter names
+
+These show you the bar. Don't copy them — take the *technique* (the interleaved queue, the SVG particle pattern, the streaming type) and apply it to your own content.
+
+## 4. The toolbox (Layer-2 components — reference)
+
+Components have spare defaults on purpose. Adding animation is opt-in. Treat this whole section as a *reference* — scan when you need an anchor, ignore otherwise.
 
 ### Stage.KineticText — multi-line staggered reveal (workhorse, ~50% of slides)
 ```js
@@ -635,7 +721,7 @@ Stage.register(Stage.Marquee({
 }));
 ```
 
-## 3. The toolbox (Layer-1 primitives)
+## 5. The toolbox (Layer-1 primitives)
 
 Available globally as `Stage.<name>`. Use them in any slide's `init()` to build bespoke motion.
 
@@ -649,19 +735,7 @@ Available globally as `Stage.<name>`. Use them in any slide's `init()` to build
 | `sessionElapsedClock` | `({start}) → {el, stop}` | Live MM:SS clock element. |
 | `assignStageKeys` | `(root)` | Auto-assigns `data-stage-key` for edit-mode pins (engine calls this). |
 
-## 4. The cookbook
-
-When you need motion that the components don't cover, **read these first** — they're the ceiling, not the floor. All in `examples/`:
-
-- `examples/token-stream.js` — interleaved word-fill across a split panel, particle emit.
-- `examples/orchestration-graph.js` — SVG hex-graph with particles flowing from satellites to center.
-- `examples/terminal-log.js` — streaming colored log lines with a human realization reveal.
-- `examples/whoami.js` — terminal prompt cycling through identity strings.
-- `examples/closing-card.js` — QR + dedication + underline.
-
-Don't copy them verbatim. Take the technique (the interleaved queue, the SVG particle pattern, the streaming type) and apply it to your own content.
-
-## 5. The step model
+## 6. The step model
 
 A slide may declare `steps: N`. The engine:
 
@@ -688,7 +762,7 @@ Stage.register({
 
 For trivial cases use `Stage.revealByDataStep`. For anything richer (glow transitions, particle emit, typewriter on each step) write `onStep` yourself — that's the point.
 
-## 6. The transition library
+## 7. The transition library
 
 In `stagecraft.config.js`, the `transition` on each slide controls how it enters:
 
@@ -715,7 +789,7 @@ Built-in (14):
 
 Themes override visuals. Unknown → falls back to `fade`.
 
-## 7. Edit mode (you-might-not-see-it, but: it exists)
+## 8. Edit mode (you-might-not-see-it, but: it exists)
 
 When the human runs `npx stagecraft serve`, they get a browser-based editor that writes back to source. They might leave notes in slides:
 
@@ -733,19 +807,6 @@ When they say "process my notes":
 
 Notes don't get a "resolved" state. Deleting them is how you mark them done.
 
-## 8. When to register a custom slide vs. use a component
-
-Use a component when:
-- It's truly a list of bullets / a comparison / a section divider — boring is fine for these.
-- The visual you want is achievable with one component + minor styling.
-
-Write a custom slide (just `Stage.register({section, title, render, init, ...})`) when:
-- The animation is core to the message (token-stream, orchestration graph, terminal log).
-- You're combining motion patterns no component covers.
-- The slide is the centerpiece of a section — it deserves the attention.
-
-The split should be roughly: ~40% workhorse components (KineticText, SectionCard, Quote, BigNumber), ~30% structural (ImageText, Bento, Compare, Pillars, Timeline), ~15% chart/diagram for data-heavy moments (BarChart, Matrix2x2, Pyramid, Funnel, Venn, ProcessFlow, Cycle), ~15% bespoke. If the bespoke share goes below 10%, the deck has gone flat.
-
 ## 9. The full component catalog at a glance
 
 | Family | Components |

package/CHANGELOG.md

@@ -0,0 +1,54 @@
+# Changelog
+
+## 0.2.0 — 2026-05-23
+
+### Themes
+- Added **Shopware** theme — fifth official theme, sourced from the Meteor design system (`@shopware-ag/meteor-tokens` v1.4.0). Light, Inter, brand-blue `#0870ff`, semantic palette piped through. Full overrides for all 50 components and all transitions.
+- Polished **Paper**, **Neon**, and **Brand** themes with per-family component overrides (each had been mostly inheriting Phosphor before — now they have distinct visual personalities).
+- **Theme picker** in the storyboard toolbar lets you switch live across all 5 themes.
+- Demo loads all 5 themes' CSS so switching is instant (no reload). Production starter loads a single theme bundle and reloads on switch.
+
+### Editor
+- New **'E' keypress** toggles edit-mode affordances on/off without disconnecting the dev server — present cleanly even with the server running.
+- New **Speaker notes** field (`Stage.register(slide, {notes: '…'})`) with 🎙 button per storyboard tile. AST-aware roundtrip preserves all other slide fields.
+- New **CRUD** in storyboard: ➕ add slide (with template choice), 🗑 delete slide.
+- New **Process notes** button copies a ready-made agent prompt to the clipboard.
+- New **Pin markers** on annotated elements during edit mode (yellow pulsing dots, hover for note text).
+- Element click for inline editing changed from double-click to single click.
+
+### Presenter view
+- Press **P** to open a second window with the presenter view: current slide, next-slide thumbnail, speaker notes, elapsed timer, wall clock. Multi-monitor via `BroadcastChannel` sync. Laptop sees notes, beamer sees clean slide.
+
+### Components (50 total)
+- Phase 3 added: ImageText, FullImage, Quote, BigNumber, Stats, Bento, Pillars, Timeline, Pyramid, Cycle, Funnel, Matrix2x2, BarChart, Progress, ProcessFlow, Venn, KPI, DonutChart, LineChart, Gauge, SparkLine, Heatmap, Roadmap, SWOT, CodeBlock, CodeDiff, Pricing, Testimonial, TeamGrid, Agenda, Checklist, Steps, CTA, Callout, Tip, BeforeAfter, Statement, QandA, Manifesto, Punchline, Definition, ImageGrid, Spotlight, Marquee.
+
+### Transitions (15 total)
+- Added zoom-in, zoom-out, flip (3D rotateY), iris (clip-path), shutter, push, typewriter, shatter.
+- Hover-to-play-once preview in the picker.
+
+### Tooling
+- **Bundle script** (`npm run build`): concatenates everything into `dist/stagecraft.bundle.{js,css}` + per-theme CSS bundles.
+- **PDF export** (`npx stagecraft export pdf`): renders deck to PDF via Playwright + pdf-lib (optional deps).
+- **Visual regression** harness (`tests/visual/run.js`): Playwright snapshots with optional pixelmatch diffing.
+- **GitHub Pages CI**: `npm run build` + `scripts/deploy-build.js` produce a `deploy/` directory; `.github/workflows/deploy-pages.yml` ships it on every push to main.
+- **Verify CI**: `.github/workflows/verify.yml` runs `npm run verify` (AST tests), syntax-checks every JS file, builds bundles, and assembles the deploy directory on every PR.
+
+### Accessibility
+- `prefers-reduced-motion: reduce` shortcuts the typewriter, particles, and stagger animations to their final state.
+
+### Bug fixes
+- CodeBlock/CodeDiff: removed redundant `<pre>` wrapper that was preserving template-string whitespace as huge inter-line gaps.
+- Venn diagram: geometry now expressed in SVG viewBox units; labels converted to container-% on render, so they align with the circles regardless of container aspect ratio.
+- Heatmap: x-labels wrapped in a `.hm-x-row` grid container so they run horizontally instead of stacking.
+- Drag-to-reorder in storyboard: the synthetic click after drop no longer closes the storyboard.
+- Click-to-advance no longer fires in edit mode (previously prevented inline editing on the first click of any potential double-click).
+- Storyboard state persists across the file-watcher reload after a drag-drop reorder.
+- 'cut' transition now has a picker-only preview animation (was invisible before).
+
+## 0.1.0 — 2026-05-22
+
+Initial release.
+
+- Engine, primitives, 6 core components, 4 themes, 5 cookbook examples.
+- Edit mode with slide-level notes, element-pin notes, transition picker, inline text editing.
+- Dev server with WebSocket + AST roundtrip.

package/README.md

@@ -1,10 +1,10 @@
 # Stagecraft
 
-**Cinematic, agent-authored presentations in a single HTML file.**
+**Cinematic, agent-authored presentations. No build step.**
 
 ▶ **[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.
+A small JavaScript library for animated slide decks. Source is plain JS files loaded by `<script>` tags — no bundler, no framework, opens directly in any browser. Designed so an LLM can generate a deck that doesn't look like an LLM generated it.
 
 ## Why
 

package/package.json

@@ -1,12 +1,21 @@
 {
   "name": "stagecraft",
-  "version": "0.1.0",
-  "description": "Cinematic, agent-authored presentations in a single HTML file.",
+  "version": "0.2.1",
+  "description": "Cinematic, agent-authored presentations. No build step.",
   "type": "module",
   "main": "src/engine.js",
   "bin": {
     "stagecraft": "bin/cli.js"
   },
+  "homepage": "https://noegel.io/stagecraft/",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/dnoegel/stagecraft.git"
+  },
+  "bugs": {
+    "url": "https://github.com/dnoegel/stagecraft/issues"
+  },
+  "author": "Daniel Nögel",
   "files": [
     "src",
     "themes",
@@ -15,7 +24,9 @@
     "bin",
     "starter",
     "AGENT.md",
-    "README.md"
+    "README.md",
+    "LICENSE",
+    "CHANGELOG.md"
   ],
   "scripts": {
     "serve": "node bin/serve.js",
@@ -25,7 +36,8 @@
     "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"
+    "export": "node bin/export.js",
+    "prepublishOnly": "npm run build"
   },
   "dependencies": {
     "@babel/generator": "^7.24.0",
@@ -36,6 +48,17 @@
     "mime-types": "^2.1.35",
     "ws": "^8.16.0"
   },
-  "keywords": ["slides", "presentation", "reveal", "agent", "llm"],
-  "license": "MIT"
+  "keywords": [
+    "slides",
+    "presentation",
+    "agent",
+    "llm",
+    "stagecraft",
+    "deck",
+    "keynote"
+  ],
+  "license": "MIT",
+  "engines": {
+    "node": ">=18"
+  }
 }