demo-reel 0.1.3 → 0.3.0

package/.claude-plugin/commands/demo-script.md

@@ -0,0 +1,200 @@
+You are helping the user create a demo video script for their web application. This is a collaborative process — you figure out the flow together, then build the script scene by scene.
+
+## Modular Video Series Pattern
+
+Demo videos are designed as **modular, standalone segments** that also work together as a guided journey. Each video:
+
+1. **Is fully independent** — has its own setup steps that create required state from scratch (login, create tenant, create template, etc.)
+2. **Opens with brief context** (~3-5 seconds narration) — "We hebben een template aangemaakt — laten we varianten toevoegen" so standalone viewers aren't lost
+3. **Covers one focused topic** — 30-90 seconds, one clear goal
+4. **Ends on the result** — the viewer sees the accomplished outcome
+
+### Example series structure:
+
+```
+01-create-template.demo.ts
+  setup: login → create tenant
+  recorded: navigate to templates → create template → open editor
+
+02-add-variants.demo.ts
+  setup: login → create tenant → create template (fast, off-screen)
+  recorded: open template → add variants → show variant list
+
+03-editor-walkthrough.demo.ts
+  setup: login → create tenant → create template (fast, off-screen)
+  recorded: open editor → drag blocks → edit text → preview
+```
+
+## Step 1: Understand the Goal
+
+Ask clarifying questions to understand:
+
+- **Who is the audience?** New users? Existing customers? Potential buyers?
+- **What's the starting point?** Where in the app does this flow begin?
+- **What's the end state?** What should the viewer see at the end?
+- **Any specifics?** Test data (emails, names, project names), things to emphasize, things to skip
+- **Tone and language?** Casual/formal, which language for narration and content
+- **Part of a series?** Does this build on previous demos? What state already exists?
+
+If the user provided $ARGUMENTS, treat it as the goal description and ask follow-up questions.
+
+## Step 2: Explore the App
+
+Before writing any script, explore the app. Use the explore command:
+
+```bash
+pnpm demo-reel explore <url>
+```
+
+For authenticated pages, write a quick inline exploration script that logs in, clicks through to the target page, and extracts elements. Always **click through the UI** rather than navigating by URL — SPAs often break with direct URL navigation.
+
+Summarize what you find for the user — page structure, available actions, selectors.
+
+## Step 3: Identify Setup vs. Recorded Steps
+
+Some steps need to happen before recording starts. These are **setup** and **auth**: they run but aren't captured in the video (they run in a separate browser).
+
+Ask the user: "Is there anything we need to do before the recording starts?"
+
+Common setup steps:
+
+- Login flow → use the `auth` block with `loginSteps`, `validate`, `storage`
+- Create a fresh tenant/workspace → keeps demos reproducible and independent
+- Create prerequisite data (templates, users, etc.) that this video builds upon
+- Navigate past landing pages to the actual starting point
+
+Also identify **cleanup** steps that should run after recording (e.g., delete tenant).
+
+## Step 4: Plan the Recorded Flow
+
+Before crawling anything, sketch the high-level flow together. Present it and ask: "Does this flow make sense?"
+
+## Step 5: Build Scenes (Page by Page)
+
+Work through the flow one page at a time.
+
+**a) Crawl it** — explore the page, extract interactive elements. Always click links in the SPA.
+
+**b) Draft scene(s):**
+
+```
+Scene 2: "Laten we een nieuw template aanmaken."
+  → hover [href: "/tenants/demo/templates"]
+  → click [href: "/tenants/demo/templates"]
+  → wait 1500ms
+```
+
+CRITICAL: Only use selectors from the crawl output. Never invent selectors. Always hover before clicking for natural cursor movement.
+
+**c) Get feedback** — "How's this? Want to adjust the narration or steps?"
+
+**d) Move to the next page** — "What happens after this?"
+
+## Step 6: Review the Full Script
+
+Show the complete script. The user can reorder, cut, merge, tighten narration, adjust pacing.
+
+## Step 7: Save
+
+Ask for a name. Write the `.demo.ts` config:
+
+```typescript
+import { demo } from 'demo-reel';
+
+export default demo({
+  video: { resolution: "FHD" },
+  cursor: "dot",
+  motion: "smooth",
+  typing: "humanlike",
+  timing: "normal",
+  outputFormat: "mp4",
+  name: "create-template",
+  outputDir: "./output",
+
+  voice: {
+    provider: "elevenlabs",
+    voice: "CwhRBWXzGAHq8TQ4Fs17",
+    pronunciation: { "template": "template" },
+  },
+
+  auth: { /* loginSteps, validate, storage */ },
+  setup: [ /* steps to run before recording */ ],
+  cleanup: [ /* steps to run after recording */ ],
+
+  scenes: [
+    { narration: "...", stepIndex: 0, isIntro: true },
+    { narration: "...", stepIndex: 3 },
+  ],
+
+  steps: [
+    // Scene 1: ...
+    { action: "hover", selector: { ... }, delayAfterMs: 800 },
+    { action: "click", selector: { ... }, delayAfterMs: 1500 },
+    // Scene 2: ...
+    { action: "type", selector: { ... }, text: "...", delayAfterMs: 300 },
+  ],
+});
+```
+
+Key points:
+
+- Use `demo()` (or `defineConfig()`) from `'demo-reel'`
+- `setup` = steps before recording (off-screen), `cleanup` = steps after recording
+- `voice` config inline — voiceover is auto-generated during recording
+- `voice` values are provider-specific:
+- `piper`: `nl_NL-mls-medium`, `en_US-amy-medium`
+- `openai`: `alloy`, `echo`, `fable`, `onyx`, `nova`, `shimmer`
+- `elevenlabs`: `21m00Tcm4TlvDq8ikWAM`, `5zhopMftSdRGaPYVcwKK`
+- for a custom Piper model, use `voicePath` instead of `voice`
+- `scenes` map narration text to step indices for subtitles + metadata
+- Always `hover` before `click` for natural cursor movement
+
+## Step 8: Record
+
+One command does everything (compile, voice, record, subtitles, cleanup):
+
+```bash
+pnpm demo-reel <name> --verbose
+```
+
+This compiles the .demo.ts, generates voiceover (if voice config + narration present), runs the recording in Docker, and outputs video + subtitles + metadata.
+
+For local debugging with a visible browser:
+
+```bash
+pnpm demo-reel-local <name> --headed --verbose
+```
+
+If it fails, check `output/debug/step-N-failure.png` for a screenshot of the page at the failed step.
+
+---
+
+## Writing Guidelines
+
+**Narration:**
+
+- Goal-oriented — explain what we're trying to accomplish, not just what we're clicking
+- Concise — 1-3 sentences per scene, 30-90 seconds total
+- Conversational — "Let's", "Notice how", "Here's where we" (or Dutch equivalents)
+- No filler — cut "As you can see" and "Now we're going to"
+- Value-focused — "This saves you from having to..." not just "Click here"
+- For series: open with brief context so standalone viewers aren't lost
+
+**Pacing:**
+
+- `delayAfterMs: 500-1500` after visual changes
+- `wait: 1500-2500` after page navigations
+- `waitFor` after clicks that trigger loading
+- Longer pauses at "aha" moments
+- Quick pace through routine steps (form filling)
+- Always `hover` before `click` — shows cursor movement
+
+**Selectors:** `data-testid` > `id` > `href` > unique `class` > `custom`
+
+**Navigation:** Always click elements in the UI. Never use `goto` for internal SPA pages — only for the initial page load after setup.
+
+**Scene structure:**
+
+- Each scene = one logical beat, not one page
+- First scene: brief context intro for standalone viewers
+- Last scene: linger on the result

package/.claude-plugin/marketplace.json

@@ -0,0 +1,13 @@
+{
+  "plugins": [
+    {
+      "name": "demo-reel",
+      "description": "Create demo videos from web apps — interactive script building with Claude Code",
+      "source": {
+        "source": "github",
+        "repo": "whit3st/demo-reel"
+      },
+      "version": "0.1.4"
+    }
+  ]
+}

package/.claude-plugin/plugin.json

@@ -0,0 +1,8 @@
+{
+  "name": "demo-reel",
+  "description": "Create demo videos from web apps — interactive script building with Claude Code",
+  "version": "0.1.4",
+  "author": {
+    "name": "whit3st"
+  }
+}

package/README.md

@@ -1,133 +1,254 @@
 # Demo Reel
 
-Create beautiful demo videos from web apps using Playwright. Perfect for showcasing features, creating onboarding tutorials, or documenting workflows.
+![Coverage](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/whit3st/demo-reel/main/.github/badges/coverage.json)
 
-## What is Demo Reel?
+Create professional demo videos from web apps. Code your demos in TypeScript, record via Docker, with automatic voiceover and subtitles.
 
-Demo Reel is a developer-first tool for creating professional demo videos from web applications. Unlike manual screen recording, Demo Reel uses Playwright automation to create pixel-perfect, reproducible demos.
+## Quick Start
 
-**Key Benefits:**
-- **Code as Config**: Demo configurations are TypeScript files
-- **Version Controlled**: Track demo changes in git
-- **CI/CD Ready**: Generate videos in automated pipelines
-- **Human-Like**: Natural cursor movements and typing
-- **Audio Support**: Mix narration and background music
+```bash
+pnpm add -D demo-reel
+```
 
-## Installation
+```typescript
+// demos/signup.demo.ts
+import { generate } from "demo-reel";
+
+await generate(
+  {
+    name: "signup",
+    outputDir: "./output",
+    video: { resolution: "FHD" },
+    cursor: "dot",
+    motion: "smooth",
+    typing: "humanlike",
+    timing: "normal",
+    outputFormat: "mp4",
+
+    voice: {
+      provider: "elevenlabs", // or "piper" (local/free) or "openai"
+      voice: "5zhopMftSdRGaPYVcwKK",
+    },
+
+    auth: {
+      loginSteps: [
+        { action: "goto", url: "https://myapp.com/login" },
+        { action: "type", selector: { strategy: "id", value: "email" }, text: "demo@example.com" },
+        { action: "type", selector: { strategy: "id", value: "password" }, text: "password" },
+        { action: "click", selector: { strategy: "class", value: "btn-primary" } },
+      ],
+      validate: {
+        protectedUrl: "https://myapp.com/dashboard",
+        successIndicator: { strategy: "custom", value: "h1:has-text('Dashboard')" },
+      },
+      storage: { name: "demo-session", types: ["cookies"] },
+    },
+
+    setup: [
+      // Runs before recording (off-screen) — create test data, navigate
+      { action: "goto", url: "https://myapp.com/dashboard" },
+    ],
+
+    cleanup: [
+      // Runs after recording — delete test data
+    ],
+
+    scenes: [
+      { narration: "Welcome to our app. Let's create a new project.", stepIndex: 0, isIntro: true },
+      { narration: "Fill in the details and click Create.", stepIndex: 2 },
+    ],
+
+    steps: [
+      // Scene 1
+      {
+        action: "hover",
+        selector: { strategy: "testId", value: "new-project" },
+        delayAfterMs: 800,
+      },
+      {
+        action: "click",
+        selector: { strategy: "testId", value: "new-project" },
+        delayAfterMs: 1500,
+      },
+
+      // Scene 2
+      {
+        action: "type",
+        selector: { strategy: "id", value: "name" },
+        text: "My Project",
+        delayAfterMs: 500,
+      },
+      {
+        action: "hover",
+        selector: { strategy: "custom", value: "button[type='submit']" },
+        delayAfterMs: 600,
+      },
+      {
+        action: "click",
+        selector: { strategy: "custom", value: "button[type='submit']" },
+        delayAfterMs: 2000,
+      },
+    ],
+  },
+  { verbose: true },
+);
+```
 
 ```bash
-npm install -D demo-reel playwright
+npx tsx demos/signup.demo.ts
 ```
 
-## Quick Start
+Output: `output/signup.mp4` + `.srt` + `.vtt` + `.meta.json`
 
-### 1. Create a Config File
+## How It Works
 
-Create `demo-reel.config.ts` in your project root:
+1. **You write a `.demo.ts`** — TypeScript config with steps, scenes, and narration
+2. **`generate()` handles everything** — compiles config, generates voiceover (via Docker), records the video (via Docker), outputs subtitles and metadata
+3. **Docker runs the heavy stuff** — Chromium, FFmpeg, Piper TTS are in the Docker image, not on your machine
 
-```typescript
-import { defineConfig } from 'demo-reel';
-
-export default defineConfig({
-  viewport: { width: 1920, height: 1080 },
-  video: { enabled: true, size: { width: 1920, height: 1080 } },
-  name: 'my-demo',
-  steps: [
-    { action: 'goto', url: 'https://example.com' },
-    { action: 'wait', ms: 2000 },
-  ],
-});
-```
+### Requirements
 
-### 2. Run the Demo
+- **Docker** — for recording and voice generation
+- **Node.js 18+** — for running your demo scripts
+- **API keys** (optional) — `ELEVENLABS_KEY` or `OPENAI_API_KEY` for cloud TTS
+
+## Claude Code Integration
+
+Build demo scripts interactively with Claude Code:
 
 ```bash
-npx demo-reel
+pnpm demo-reel setup   # shows how to install the /demo-script plugin
 ```
 
-Output: `videos/my-demo.mp4`
+Then use `/demo-script` in Claude Code:
 
-## CLI Usage
-
-```bash
-# Run default config
-npx demo-reel
+```
+/demo-script https://myapp.com show the signup flow
+```
 
-# Run specific scenario
-npx demo-reel onboarding
+Claude crawls your app, builds the script with you scene by scene, and generates the `.demo.ts`.
 
-# Run all scenarios
-npx demo-reel --all
+## Configuration
 
-# Validate config without recording
-npx demo-reel --dry-run
+### Voice / TTS
 
-# Verbose output
-npx demo-reel --verbose
+```typescript
+voice: {
+  provider: "elevenlabs",           // "piper" | "openai" | "elevenlabs"
+  voice: "5zhopMftSdRGaPYVcwKK",     // provider-specific autocomplete
+  speed: 1.0,
+  pronunciation: {                  // word replacements before TTS
+    "template": "template",         // prevent Dutch pronunciation of English words
+  },
+},
 ```
 
-## Configuration
+Built-in voice values:
 
-### Config File Discovery
+- `piper`: `"nl_NL-mls-medium"`, `"en_US-amy-medium"`
+- `openai`: `"alloy"`, `"echo"`, `"fable"`, `"onyx"`, `"nova"`, `"shimmer"`
+- `elevenlabs`: `"21m00Tcm4TlvDq8ikWAM"`, `"5zhopMftSdRGaPYVcwKK"`, `CwhRBWXzGAHq8TQ4Fs17`
 
-The CLI looks for configs in this order:
-1. `demo-reel.config.ts` (default)
-2. `<scenario>.demo.ts` (when specifying scenario name)
-3. All `*.demo.ts` files (with `--all` flag)
+For a custom Piper `.onnx` model, use `voicePath` instead of `voice`:
 
-### Available Steps
+```typescript
+voice: {
+  provider: "piper",
+  voicePath: "/models/custom-voice.onnx",
+  speed: 1.0,
+}
+```
 
-- `goto` - Navigate to URL
-- `click` - Click an element
-- `hover` - Hover over element
-- `type` - Type text into input
-- `press` - Press a key
-- `scroll` - Scroll element
-- `wait` - Wait for duration
-- `waitFor` - Wait for condition
+Voiceover is auto-generated when `scenes` have `narration` text and `voice` is configured. Cached by content hash — only regenerates when narration changes.
 
-### Selector Strategies
+### Setup & Cleanup
 
 ```typescript
-// By test ID (data-testid attribute)
-{ strategy: 'testId', value: 'submit-button' }
+setup: [
+  // Runs in a separate browser BEFORE recording (not visible in video)
+  { action: "goto", url: "https://myapp.com/" },
+  { action: "click", selector: { strategy: "id", value: "create-workspace" } },
+],
+
+cleanup: [
+  // Runs AFTER recording (even on failure) — delete test data
+  { action: "goto", url: "https://myapp.com/admin" },
+  { action: "click", selector: { strategy: "custom", value: "button.delete" } },
+],
+```
 
-// By ID (without #)
-{ strategy: 'id', value: 'username' }
+Setup and cleanup run in tolerant mode — failed steps are skipped.
 
-// By class (without .)
-{ strategy: 'class', value: 'btn-primary' }
+### Scenes & Subtitles
 
-// By href
-{ strategy: 'href', value: '/dashboard' }
+```typescript
+scenes: [
+  { narration: "Welcome to our app.", stepIndex: 0, isIntro: true },
+  { narration: "Let's create something.", stepIndex: 3 },
+],
 ```
 
-## Features
+- `narration` — voiceover text (also used for subtitles)
+- `stepIndex` — which step starts this scene
+- `isIntro` — marks the intro scene (used by presentation systems to skip context)
 
-### Human-Like Cursor Movement
+Generates `.srt`, `.vtt` (subtitles) and `.meta.json` (scene timestamps for interactive players).
 
-Smooth Bezier curve paths with configurable speed and easing.
+### Steps
 
-### Natural Typing
+| Action    | Description                                                          |
+| --------- | -------------------------------------------------------------------- |
+| `goto`    | Navigate to URL                                                      |
+| `click`   | Click an element                                                     |
+| `hover`   | Hover over element                                                   |
+| `type`    | Type text into input                                                 |
+| `press`   | Press a key                                                          |
+| `scroll`  | Scroll element                                                       |
+| `select`  | Select dropdown option(s)                                            |
+| `check`   | Check/uncheck checkbox                                               |
+| `upload`  | Upload files                                                         |
+| `drag`    | Drag and drop                                                        |
+| `wait`    | Wait for duration                                                    |
+| `waitFor` | Wait for condition (selector, URL, load state, network, JS function) |
 
-Variable delays based on character type (spaces, punctuation, etc.)
+### Selectors
 
-### Audio Support
+```typescript
+{ strategy: "testId", value: "submit-button" }     // data-testid
+{ strategy: "id", value: "username" }               // id (no #)
+{ strategy: "class", value: "btn-primary" }         // class (no .)
+{ strategy: "href", value: "/dashboard" }           // link href
+{ strategy: "custom", value: "button:has-text('Save')" }  // any CSS selector
+{ strategy: "class", value: "card", index: 2 }      // nth match
+```
 
-Mix narration and background music:
+### Presets
 
 ```typescript
-audio: {
-  narration: './voiceover.mp3',
-  narrationDelay: 2000,  // Delay before narration starts
-  background: './music.mp3',
-  backgroundVolume: 0.3,
+cursor: "dot" | "arrow" | "none";
+motion: "smooth" | "snappy" | "instant";
+typing: "humanlike" | "fast" | "instant";
+timing: "normal" | "fast" | "instant";
+video: {
+  resolution: "HD" | "FHD" | "2K" | "4K";
 }
 ```
 
-## CI/CD Integration
+## Modular Video Series
+
+Demo videos are designed as standalone segments that also work as a series:
+
+```
+demos/
+└── my-app/
+    ├── 01-signup/signup.demo.ts          # setup: create workspace
+    ├── 02-create-project/project.demo.ts # setup: create workspace + template
+    └── 03-editor/editor.demo.ts          # setup: create workspace + template + project
+```
+
+Each video has its own `setup` that recreates the required state. Later videos have heavier setup. Every video is independently recordable.
 
-Example GitHub Actions workflow:
+## CI/CD
 
 ```yaml
 name: Generate Demo Videos
@@ -138,13 +259,15 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v4
-      - run: npm ci
-      - run: npx playwright install chromium
-      - run: npx demo-reel --all
+      - uses: pnpm/action-setup@v4
+      - run: pnpm install
+      - run: npx tsx demos/01-signup/signup.demo.ts
+        env:
+          ELEVENLABS_KEY: ${{ secrets.ELEVENLABS_KEY }}
       - uses: actions/upload-artifact@v4
         with:
           name: demo-videos
-          path: ./videos/*.mp4
+          path: ./output/*.mp4
 ```
 
 ## License

package/bin/demo-reel.mjs

@@ -0,0 +1,98 @@
+#!/usr/bin/env node
+import { execSync, spawn } from "child_process";
+import { dirname, resolve } from "path";
+import { fileURLToPath } from "url";
+
+const SKILL_URL =
+  "https://raw.githubusercontent.com/whit3st/demo-reel/main/.claude-plugin/commands/demo-script.md";
+const DEFAULT_IMAGE = "ghcr.io/whit3st/demo-reel:latest";
+const LOCAL_IMAGE = "demo-reel:latest";
+
+const args = process.argv.slice(2);
+
+if (args[0] === "setup") {
+  console.log(`demo-reel setup
+
+Install the /demo-script Claude Code plugin to build demo scripts interactively.
+
+Option 1 — Claude Code plugin (recommended):
+  /plugin marketplace add whit3st/demo-reel
+  /plugin install demo-reel@whit3st-demo-reel
+
+Option 2 — Manual copy:
+  mkdir -p .claude/commands
+  curl -sL ${SKILL_URL} -o .claude/commands/demo-script.md
+
+Then use /demo-script in Claude Code to create demo videos collaboratively.`);
+} else if (args[0] === "explore") {
+  const image = getImage();
+  const dockerArgs = [
+    "run",
+    "--rm",
+    "-v",
+    `${process.cwd()}:/work:z`,
+    "-w",
+    "/work",
+    "--entrypoint",
+    "node",
+    image,
+    "/app/dist/script/crawl-cli.js",
+    ...args.slice(1),
+  ];
+  const proc = spawn("docker", dockerArgs, { stdio: "inherit" });
+  forwardSignals(proc);
+  proc.on("close", (code) => process.exit(code ?? 1));
+} else if (args.length > 0) {
+  const cliPath = resolve(dirname(fileURLToPath(import.meta.url)), "../dist/cli.js");
+  const proc = spawn(process.execPath, ["--import", "tsx/esm", cliPath, ...args], {
+    stdio: "inherit",
+  });
+  forwardSignals(proc);
+  proc.on("close", (code) => process.exit(code ?? 1));
+} else {
+  console.log(`demo-reel — Create demo videos from web apps
+
+Usage in your code:
+  import { generate } from "demo-reel";
+  await generate({ steps: [...], scenes: [...] }, { verbose: true });
+
+CLI commands:
+  demo-reel setup              Install the Claude Code plugin
+  demo-reel explore <url>      Crawl a page and show selectors`);
+}
+
+function getImage() {
+  try {
+    execSync(`docker image inspect ${LOCAL_IMAGE}`, { stdio: "ignore" });
+    return LOCAL_IMAGE;
+  } catch {
+    /* no local image */
+  }
+  try {
+    execSync(`docker image inspect ${DEFAULT_IMAGE}`, { stdio: "ignore" });
+    return DEFAULT_IMAGE;
+  } catch {
+    console.log(`Pulling ${DEFAULT_IMAGE}...`);
+    execSync(`docker pull ${DEFAULT_IMAGE}`, { stdio: "inherit" });
+    return DEFAULT_IMAGE;
+  }
+}
+
+function forwardSignals(child) {
+  const signals = ["SIGINT", "SIGTERM"];
+  const forward = (signal) => {
+    if (!child.killed) {
+      child.kill(signal);
+    }
+  };
+
+  for (const signal of signals) {
+    process.on(signal, () => forward(signal));
+  }
+
+  process.on("exit", () => {
+    if (!child.killed) {
+      child.kill("SIGTERM");
+    }
+  });
+}