demo-dev 0.0.1-alpha.0 → 0.0.2-alpha.0

package/dist/index.js

@@ -161,6 +161,29 @@ var ZOOM_INJECT_SCRIPT = `
   };
 })();
 `;
+var SCENE_TRANSITION_SCRIPT = `
+(() => {
+  if (document.getElementById('__scene-fade')) return;
+  const overlay = document.createElement('div');
+  overlay.id = '__scene-fade';
+  Object.assign(overlay.style, {
+    position: 'fixed', top: '0', left: '0', width: '100vw', height: '100vh',
+    zIndex: '999997', pointerEvents: 'none',
+    background: 'white', opacity: '0',
+    transition: 'opacity 0.4s ease-in-out',
+  });
+  document.body.appendChild(overlay);
+  window.__fadeOut = () => { overlay.style.opacity = '1'; };
+  window.__fadeIn = () => { overlay.style.opacity = '0'; };
+})();
+`;
+var fadeTransition = async (page) => {
+  await page.evaluate(SCENE_TRANSITION_SCRIPT).catch(() => void 0);
+  await page.evaluate(() => window.__fadeOut?.()).catch(() => void 0);
+  await page.waitForTimeout(450);
+  await page.evaluate(() => window.__fadeIn?.()).catch(() => void 0);
+  await page.waitForTimeout(450);
+};
 var zoomToPoint = async (page, x, y, scale = 1.5) => {
   await page.evaluate(ZOOM_INJECT_SCRIPT).catch(() => void 0);
   await page.evaluate(
@@ -195,13 +218,13 @@ var CURSOR_OVERLAY_SCRIPT = `
   cursor.id = '__ghost-cursor';
   Object.assign(cursor.style, {
     position: 'fixed', zIndex: '999999', pointerEvents: 'none',
-    left: '0px', top: '0px', width: '22px', height: '32px',
-    transition: 'left 0.04s cubic-bezier(.2,.8,.3,1), top 0.04s cubic-bezier(.2,.8,.3,1)',
-    filter: 'drop-shadow(0 2px 3px rgba(0,0,0,0.4))',
+    left: '0px', top: '0px', width: '20px', height: '28px',
+    transition: 'left 0.03s linear, top 0.03s linear',
   });
-  /* Standard macOS cursor: white fill, black outline, clean geometry */
-  cursor.innerHTML = '<svg width="22" height="32" viewBox="0 0 22 32" xmlns="http://www.w3.org/2000/svg">' +
-    '<path d="M1.5 0.5L1.5 24.5L7 18.5L11.5 28.5L14.5 27L10 17.5L18 17.5Z" fill="white" stroke="black" stroke-width="1.2" stroke-linejoin="round"/>' +
+  /* Precise macOS default cursor \u2014 traced from Apple's actual cursor spec */
+  cursor.innerHTML = '<svg xmlns="http://www.w3.org/2000/svg" width="20" height="28" viewBox="0 0 20 28">' +
+    '<defs><filter id="cs" x="-20%" y="-20%" width="140%" height="140%"><feDropShadow dx="0.5" dy="1.5" stdDeviation="0.8" flood-opacity="0.45"/></filter></defs>' +
+    '<path filter="url(#cs)" d="M2.2 0L2.2 21.4L6.8 16.4L10.6 24.8L13.2 23.6L9.4 15.6L16 15.6Z" fill="white" stroke="black" stroke-width="1.1" stroke-linejoin="round"/>' +
     '</svg>';
   document.body.appendChild(cursor);
 
@@ -263,6 +286,7 @@ var runActionWithCursor = async (page, action, baseUrl, cursor) => {
       await page.evaluate(CURSOR_OVERLAY_SCRIPT).catch(() => void 0);
       await page.evaluate(CURSOR_TRACKER_SCRIPT).catch(() => void 0);
       await page.evaluate(ZOOM_INJECT_SCRIPT).catch(() => void 0);
+      await page.evaluate(SCENE_TRANSITION_SCRIPT).catch(() => void 0);
       await page.waitForTimeout(humanDelay(400));
       break;
     }
@@ -497,7 +521,7 @@ var capturePlanContinuous = async (plan, options) => {
         endMs: sceneEnd,
         url: page.url()
       });
-      await page.waitForTimeout(humanDelay(400));
+      await fadeTransition(page);
     }
     await drainCursorSamples(page, cursorLog, cursorTrackingOffset);
     const totalDurationMs = elapsed();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "demo-dev",
-  "version": "0.0.1-alpha.0",
+  "version": "0.0.2-alpha.0",
   "description": "Generate polished product demo videos with one command. Just give a URL and a prompt.",
   "type": "module",
   "main": "./dist/index.js",

package/skills/demo-dev/SKILL.md

@@ -1,153 +1,109 @@
 ---
 name: demo-dev
-description: Generate PR demo videos for any web app repo using demo.dev. Use when a user wants an agent to turn a PR, diff, feature branch, or live app flow into a product demo video, especially for authenticated SaaS flows, launch-style walkthroughs, or PR review artifacts.
+description: Generate product demo videos for any web app. Give a URL and a prompt, get a narrated Screen Studio-style video. Supports authenticated SaaS, prompt-driven or diff-driven planning, and AI narration.
 allowed-tools: Bash Read Edit Write
 ---
 
 # demo-dev
 
-Use this skill when the user wants an agent to create or update a demo video with the `demo.dev` pipeline.
+Use this skill when the user wants to generate a demo video of a web app.
 
 ## What this skill does
 
-- Reads project config from `demo.dev.config.json`
-- Runs the pipeline from diff -> plan -> probe -> capture -> render
-- Supports authenticated products via storage state
-- Can also create manual plans for feature-specific demos
-- Produces artifacts like mp4, manifest, captures, and PR comments
+- Opens a web app in a headless browser
+- AI plans the demo from a natural language prompt (or git diff)
+- Ghost-cursor navigates with human-like mouse movement
+- Records continuously with Playwright screencast + CSS zoom
+- Generates narration per scene with ElevenLabs / OpenAI / local TTS
+- Composes a polished mp4 with FFmpeg (speed ramps, browser frame, audio)
 
-## Default workflow
+## Quick start
 
-### 1. Inspect config
+### 1. Check environment
 
 ```bash
-demo-dev config
-demo-dev config --field baseUrl
 demo-dev doctor
 ```
 
-If config is missing, run `demo-dev init` or create one from [`../../demo.dev.config.example.json`](../../demo.dev.config.example.json).
+Requires: Node.js >= 20, FFmpeg, Chromium (`npx playwright install chromium`).
 
-See [references/configuration.md](references/configuration.md).
-
-### 2. If auth is required, bootstrap login
+### 2. If auth is required
 
 ```bash
-demo-dev auth:bootstrap \
+demo-dev auth \
+  --base-url https://app.example.com \
   --email you@example.com \
   --password 'your-password'
 ```
 
-This writes storage state using the configured path or `artifacts/storage-state.json`.
-
-### 3. Run the full pipeline
+### 3. Generate a demo
 
 ```bash
-demo-dev pr-demo
+demo-dev demo \
+  --base-url https://app.example.com \
+  --prompt "Show the dashboard, create a new project, invite a teammate" \
+  --frame
 ```
 
-Or explicitly:
+This single command will: explore the site → AI plan scenes → record → narrate → compose → mp4.
 
-```bash
-demo-dev pr-demo --base-url http://localhost:3000 --base-ref origin/main
-```
-
-### 4. Re-render only when capture and manifest already exist
+### Diff-driven mode (from a PR branch)
 
 ```bash
-demo-dev render --manifest artifacts/render-manifest.json --out artifacts/pr-demo.mp4
+demo-dev demo --base-url http://localhost:3000
 ```
 
-## When to use manual plans
-
-Use a manual plan when:
-- the feature is behind auth or deep navigation
-- the planner cannot infer the correct route from diff
-- the user wants a specific product moment, such as AI editing, onboarding, settings, inbox, or dashboards
-- the user wants a more launch-style product film rather than raw replay
-
-Place plans in an artifacts folder such as:
-
-```bash
-artifacts/manual-plan.json
-```
-
-Then run capture / manifest / render around that plan.
-
-See [references/recipes.md](references/recipes.md).
-
-## Recommended agent behavior
+No `--prompt` = auto-detect changes from git diff.
 
-1. Prefer stable, product-facing flows over exhaustive QA coverage.
-2. For the same route, keep one screen object and move the camera instead of cutting to a new screen.
-3. Prefer stable states over loading transitions.
-4. If auth is required, verify storage state early.
-5. If planner output is weak, create a tighter manual plan instead of forcing bad automation.
-6. Keep copy concise and product-first.
+## Key flags
 
-## Core commands
+| Flag | Description |
+|------|-------------|
+| `--prompt "..."` | Describe the demo in natural language |
+| `--frame` | Add Screen Studio-style browser frame with gradient background |
+| `--quality draft\|standard\|high` | Video quality preset |
+| `--base-url` | URL of the app |
+| `--output-dir` | Where to write output (default: artifacts) |
 
-Preferred first-class CLI:
+## All commands
 
 ```bash
-demo-dev config
-demo-dev providers
-demo-dev plan
-demo-dev probe
-demo-dev auth:bootstrap --email you@example.com --password 'your-password'
-demo-dev capture
-demo-dev voice
-demo-dev manifest
-demo-dev render --manifest artifacts/render-manifest.json --out artifacts/pr-demo.mp4
-demo-dev comment --output-dir artifacts --pr-number 123
-demo-dev pr-demo
+demo-dev demo        # Full pipeline
+demo-dev auth        # Login and save session
+demo-dev capture     # Record only
+demo-dev voice       # Generate narration only
+demo-dev render      # Record + narrate + compose
+demo-dev plan        # Generate plan from git diff
+demo-dev probe       # Plan + probe pages
+demo-dev init        # Create config file
+demo-dev doctor      # Check environment
+demo-dev config      # Show config
+demo-dev providers   # List AI/TTS providers
+demo-dev comment     # Post as PR comment
 ```
 
-Repo-local fallback:
-
-```bash
-npm run config
-npm run providers
-npm run plan
-npm run probe
-npm run auth:bootstrap
-npm run capture
-npm run voice
-npm run manifest
-npm run render -- --manifest artifacts/render-manifest.json --out artifacts/pr-demo.mp4
-npm run comment -- --output-dir artifacts --pr-number 123
-npm run pr-demo
-```
-
-## Outputs to check
-
-- `artifacts/demo-context.json`
-- `artifacts/demo-plan.initial.json`
-- `artifacts/page-probes.json`
-- `artifacts/demo-plan.json`
-- `artifacts/captures.json`
-- `artifacts/render-manifest.json`
-- `artifacts/pr-demo.mp4`
-
-## Troubleshooting
+## When to use prompt vs diff mode
 
-- If the app requires auth, run `auth:bootstrap` first.
-- If the video is wrong, inspect `captures.json` and `render-manifest.json` before changing renderer code.
-- If the planner misses the feature, create a manual plan.
-- If the route is unstable, add project hints in config.
+| Mode | When to use |
+|------|-------------|
+| `--prompt "..."` | Feature demos, product tours, any app you can reach via URL |
+| No prompt (diff) | PR walkthroughs, auto-detected from code changes |
 
-## Share this skill
-
-Other users can install this repo as a pi package or point pi at this repo's `skills/` directory.
+## Recommended agent behavior
 
-Example:
+1. Prefer prompt-driven mode — it works with any web app, no git repo needed.
+2. Use `--frame` for polished output.
+3. If auth is required, run `demo-dev auth` first.
+4. If AI-generated selectors fail, the system auto-retries with fuzzy matching.
+5. Keep narration conversational and product-focused.
+6. For best voice quality, set `DEMO_TTS_PROVIDER=elevenlabs`.
 
-```bash
-pi install /absolute/path/to/demo.dev
-```
+## Outputs
 
-or
+- `artifacts/pr-demo.mp4` — the final video
+- `artifacts/demo-plan.json` — AI-generated scene plan
+- `artifacts/visual-plan.json` — zoom keyframes + speed ramps
+- `artifacts/voice-script.json` — narration text + audio paths
+- `artifacts/continuous-capture.json` — recording metadata
 
-```bash
-pi install git:github.com/your-org/demo.dev
-```
+See [references/configuration.md](references/configuration.md) and [references/recipes.md](references/recipes.md).

package/skills/demo-dev/references/configuration.md

@@ -1,45 +1,19 @@
-# demo.dev skill configuration
+# demo-dev configuration
 
-## Quick bootstrap
+## Config file (optional)
 
-A fast way to bootstrap a repo is:
+Config is **optional for prompt-driven mode**. Just pass `--base-url` and `--prompt` directly.
 
-```bash
-demo-dev init
-```
-
-That writes a starter config plus the workflow template.
-
-## Minimal config
-
-Create `demo.dev.config.json` in the target repo:
+For project-level defaults, create `demo.dev.config.json`:
 
 ```json
 {
   "projectName": "My App",
-  "baseUrl": "http://localhost:3000",
-  "readyUrl": "http://localhost:3000",
-  "devCommand": "npm run dev",
-  "baseRef": "origin/main",
-  "outputDir": "artifacts",
-  "preferredRoutes": ["/", "/dashboard"],
-  "featureHints": ["home", "dashboard"]
-}
-```
-
-## Auth-enabled config
-
-```json
-{
-  "projectName": "My SaaS",
   "baseUrl": "https://app.example.com",
-  "readyUrl": "https://app.example.com",
   "baseRef": "origin/main",
   "outputDir": "artifacts",
-  "storageStatePath": "artifacts/storage-state.json",
-  "saveStorageStatePath": "artifacts/storage-state.json",
-  "preferredRoutes": ["/dashboard", "/settings"],
-  "featureHints": ["dashboard", "settings"],
+  "preferredRoutes": ["/", "/dashboard", "/settings"],
+  "featureHints": ["dashboard", "onboarding", "settings"],
   "authRequiredRoutes": ["/dashboard", "/settings"],
   "auth": {
     "loginPath": "/login",
@@ -51,52 +25,70 @@ Create `demo.dev.config.json` in the target repo:
 }
 ```
 
-## Useful overrides
+Or bootstrap with `demo-dev init`.
 
-You can override config through:
+## Config fields
 
-- CLI flags like `--base-url`, `--output-dir`, `--base-ref`
-- env vars like `DEMO_STORAGE_STATE`, `DEMO_SAVE_STORAGE_STATE`, `DEMO_CONFIG`
-- GitHub Variables in workflow:
-  - `DEMO_BASE_URL`
-  - `DEMO_READY_URL`
-  - `DEMO_DEV_COMMAND`
-  - `DEMO_OUTPUT_DIR`
+| Field | Description |
+|-------|-------------|
+| `projectName` | Display name for the project |
+| `baseUrl` | Default URL of the web app |
+| `baseRef` | Git base ref for diff-based planning (default: origin/main) |
+| `outputDir` | Where to write artifacts (default: artifacts) |
+| `preferredRoutes` | Routes the AI planner should explore and prioritize |
+| `featureHints` | Feature names to help the AI planner |
+| `authRequiredRoutes` | Routes that need login |
+| `auth.*` | Login flow configuration |
 
-## AI and TTS environment variables
+## Environment variables
 
-`demo.dev` uses explicit `DEMO_*` env vars for provider credentials.
-It does not fall back to generic provider keys such as `OPENAI_API_KEY` or `ELEVENLABS_API_KEY`.
+### AI providers
 
-Common values:
+```bash
+DEMO_AI_PROVIDER=auto           # auto, claude, cursor, codex, openai
+DEMO_OPENAI_API_KEY=sk-...      # Required for openai provider
+DEMO_OPENAI_BASE_URL=...        # Optional
+DEMO_OPENAI_MODEL=...           # Optional model override
+```
 
-- `DEMO_OPENAI_API_KEY`
-- `DEMO_OPENAI_BASE_URL`
-- `DEMO_OPENAI_MODEL`
-- `DEMO_AI_PROVIDER`
-- `DEMO_AI_MODEL`
-- `DEMO_TTS_PROVIDER`
-- `DEMO_TTS_MODEL`
-- `DEMO_TTS_VOICE`
-- `DEMO_ELEVENLABS_API_KEY`
-- `DEMO_ELEVENLABS_VOICE_ID`
+### TTS providers
+
+```bash
+DEMO_TTS_PROVIDER=auto          # auto, elevenlabs, openai, local
 
-Example:
+# ElevenLabs (best quality)
+DEMO_ELEVENLABS_API_KEY=sk_...
+DEMO_ELEVENLABS_VOICE_ID=...
+
+# OpenAI TTS
+DEMO_OPENAI_API_KEY=sk-...
+
+# Local (macOS only, free)
+DEMO_LOCAL_TTS_VOICE=Samantha
+```
+
+### Auth
+
+```bash
+DEMO_STORAGE_STATE=path/to/storage-state.json
+DEMO_LOGIN_EMAIL=you@example.com
+DEMO_LOGIN_PASSWORD=your-password
+```
+
+### Background music
 
 ```bash
-DEMO_OPENAI_API_KEY=your_openai_key
-DEMO_AI_PROVIDER=openai
-DEMO_TTS_PROVIDER=openai
+DEMO_BGM_PATH=./assets/music/bed.mp3
+DEMO_BGM_VOLUME=0.16
 ```
 
-## Suggested setup for other repos
+## Precedence
+
+CLI flags > Environment variables > Config file > Defaults
 
-1. Copy `demo.dev.config.example.json` into the target repo.
-2. Adjust `baseUrl`, `devCommand`, and `auth`.
-3. Validate the repo:
+## Verify setup
 
 ```bash
 demo-dev doctor
 demo-dev config
-demo-dev pr-demo
 ```

package/skills/demo-dev/references/recipes.md

@@ -1,83 +1,100 @@
-# demo.dev skill recipes
+# demo-dev recipes
 
-## Recipe: run on a simple local app
+## Recipe: prompt-driven demo (recommended)
 
 ```bash
-npm install
-npx playwright install chromium
-demo-dev doctor
-demo-dev pr-demo
+demo-dev demo \
+  --base-url https://app.example.com \
+  --prompt "Show the onboarding flow, create a workspace, invite a teammate" \
+  --frame
+```
+
+## Recipe: prompt-driven with premium voice
+
+```bash
+DEMO_ELEVENLABS_API_KEY=sk_... \
+DEMO_ELEVENLABS_VOICE_ID=... \
+DEMO_TTS_PROVIDER=elevenlabs \
+demo-dev demo \
+  --base-url https://app.example.com \
+  --prompt "Show the dashboard and settings page" \
+  --frame
 ```
 
 ## Recipe: authenticated SaaS
 
 ```bash
-demo-dev auth:bootstrap \
+demo-dev auth \
+  --base-url https://app.example.com \
   --email you@example.com \
   --password 'your-password'
 
-demo-dev pr-demo
+demo-dev demo \
+  --base-url https://app.example.com \
+  --prompt "Show the inbox and open a conversation" \
+  --frame
 ```
 
-## Recipe: OpenAI for planning and TTS
+## Recipe: diff-driven PR demo
 
 ```bash
-DEMO_OPENAI_API_KEY=your_openai_key \
-DEMO_AI_PROVIDER=openai \
-DEMO_TTS_PROVIDER=openai \
-demo-dev pr-demo
+demo-dev demo --base-url http://localhost:3000
 ```
 
-This repo only reads `DEMO_*` provider keys for AI and TTS credentials.
+No `--prompt` means it reads the git diff and auto-plans scenes.
 
-## Recipe: inspect plan quality first
+## Recipe: high quality render
 
 ```bash
-demo-dev plan
-demo-dev probe
+demo-dev demo \
+  --base-url https://app.example.com \
+  --prompt "..." \
+  --frame \
+  --quality high
 ```
 
-Use this when the feature is not obvious from the diff.
-
-## Recipe: re-render without recapturing
+## Recipe: fast draft for iteration
 
 ```bash
-demo-dev render --manifest artifacts/render-manifest.json --out artifacts/pr-demo.mp4
+demo-dev demo \
+  --base-url https://app.example.com \
+  --prompt "..." \
+  --quality draft
 ```
 
-## Recipe: add background music
+## Recipe: with background music
 
 ```bash
 DEMO_BGM_PATH=./assets/music/bed.mp3 \
 DEMO_BGM_VOLUME=0.14 \
-DEMO_BGM_DUCKING=0.28 \
-demo-dev pr-demo
+demo-dev demo \
+  --base-url https://app.example.com \
+  --prompt "..." \
+  --frame
 ```
 
-This will loop the music bed across the full video, fade it in and out, and lower it automatically while narration is playing.
-
-## Recipe: manual feature film
-
-Use a manual plan when you need a specific flow like:
-- AI editing
-- inbox triage
-- onboarding
-- dashboard walkthrough
+## Recipe: OpenAI for planning and TTS
 
-Suggested flow:
+```bash
+DEMO_OPENAI_API_KEY=sk-... \
+DEMO_AI_PROVIDER=openai \
+DEMO_TTS_PROVIDER=openai \
+demo-dev demo \
+  --base-url https://app.example.com \
+  --prompt "..." \
+  --frame
+```
 
-1. Create `artifacts/manual-plan.json`
-2. Run capture against that plan
-3. Build manifest
-4. Render mp4
+## Recipe: inspect plan before recording
 
-## Recipe: PR automation
+```bash
+demo-dev plan
+cat artifacts/demo-plan.json
+```
 
-In CI, run:
+## Recipe: PR automation in CI
 
 ```bash
-demo-dev pr-demo
+demo-dev demo --base-url http://localhost:3000
 demo-dev comment --output-dir artifacts
 ```
-
-If the app needs a server, set `devCommand` and `readyUrl` in config or GitHub Variables.

package/src/capture/continuous-capture.ts

@@ -257,6 +257,32 @@ const ZOOM_INJECT_SCRIPT = `
 })();
 `;
 
+const SCENE_TRANSITION_SCRIPT = `
+(() => {
+  if (document.getElementById('__scene-fade')) return;
+  const overlay = document.createElement('div');
+  overlay.id = '__scene-fade';
+  Object.assign(overlay.style, {
+    position: 'fixed', top: '0', left: '0', width: '100vw', height: '100vh',
+    zIndex: '999997', pointerEvents: 'none',
+    background: 'white', opacity: '0',
+    transition: 'opacity 0.4s ease-in-out',
+  });
+  document.body.appendChild(overlay);
+  window.__fadeOut = () => { overlay.style.opacity = '1'; };
+  window.__fadeIn = () => { overlay.style.opacity = '0'; };
+})();
+`;
+
+/** Fade to white and back — used between scenes. */
+const fadeTransition = async (page: Page) => {
+  await page.evaluate(SCENE_TRANSITION_SCRIPT).catch(() => undefined);
+  await page.evaluate(() => (window as any).__fadeOut?.()).catch(() => undefined);
+  await page.waitForTimeout(450);
+  await page.evaluate(() => (window as any).__fadeIn?.()).catch(() => undefined);
+  await page.waitForTimeout(450);
+};
+
 /** Smoothly zoom into a point on the page (captured by screencast at 60fps). */
 const zoomToPoint = async (page: Page, x: number, y: number, scale = 1.5) => {
   await page.evaluate(ZOOM_INJECT_SCRIPT).catch(() => undefined);
@@ -307,13 +333,13 @@ const CURSOR_OVERLAY_SCRIPT = `
   cursor.id = '__ghost-cursor';
   Object.assign(cursor.style, {
     position: 'fixed', zIndex: '999999', pointerEvents: 'none',
-    left: '0px', top: '0px', width: '22px', height: '32px',
-    transition: 'left 0.04s cubic-bezier(.2,.8,.3,1), top 0.04s cubic-bezier(.2,.8,.3,1)',
-    filter: 'drop-shadow(0 2px 3px rgba(0,0,0,0.4))',
+    left: '0px', top: '0px', width: '20px', height: '28px',
+    transition: 'left 0.03s linear, top 0.03s linear',
   });
-  /* Standard macOS cursor: white fill, black outline, clean geometry */
-  cursor.innerHTML = '<svg width="22" height="32" viewBox="0 0 22 32" xmlns="http://www.w3.org/2000/svg">' +
-    '<path d="M1.5 0.5L1.5 24.5L7 18.5L11.5 28.5L14.5 27L10 17.5L18 17.5Z" fill="white" stroke="black" stroke-width="1.2" stroke-linejoin="round"/>' +
+  /* Precise macOS default cursor — traced from Apple's actual cursor spec */
+  cursor.innerHTML = '<svg xmlns="http://www.w3.org/2000/svg" width="20" height="28" viewBox="0 0 20 28">' +
+    '<defs><filter id="cs" x="-20%" y="-20%" width="140%" height="140%"><feDropShadow dx="0.5" dy="1.5" stdDeviation="0.8" flood-opacity="0.45"/></filter></defs>' +
+    '<path filter="url(#cs)" d="M2.2 0L2.2 21.4L6.8 16.4L10.6 24.8L13.2 23.6L9.4 15.6L16 15.6Z" fill="white" stroke="black" stroke-width="1.1" stroke-linejoin="round"/>' +
     '</svg>';
   document.body.appendChild(cursor);
 
@@ -391,6 +417,7 @@ const runActionWithCursor = async (
       await page.evaluate(CURSOR_OVERLAY_SCRIPT).catch(() => undefined);
       await page.evaluate(CURSOR_TRACKER_SCRIPT).catch(() => undefined);
       await page.evaluate(ZOOM_INJECT_SCRIPT).catch(() => undefined);
+      await page.evaluate(SCENE_TRANSITION_SCRIPT).catch(() => undefined);
       await page.waitForTimeout(humanDelay(400));
       break;
     }
@@ -711,8 +738,8 @@ export const capturePlanContinuous = async (
         url: page.url(),
       });
 
-      // Brief pause between scenes (feels like a human taking a breath)
-      await page.waitForTimeout(humanDelay(400));
+      // Smooth fade transition between scenes
+      await fadeTransition(page);
     }
 
     // Final drain of cursor samples

package/src/planner/llm.ts

@@ -6,13 +6,13 @@ import { demoPlanSchema } from "./schema.js";
 
 const buildPlannerPrompt = (context: DiffContext, projectConfig?: ProjectConfig) => {
   return [
-    "You are a product demo director, not a QA engineer.",
+    "You are a product demo director creating a polished product walkthrough video.",
     "Goal: turn a git diff into a concise, recordable, voice-friendly demo plan.",
     "Requirements:",
     "1. Pick only 2-4 scenes that best represent visible user-facing changes.",
     "2. Keep actions stable and executable. Prefer navigate / click / fill / waitForText / waitForUrl / scroll.",
     "3. If the diff does not reveal specific elements, do not invent complex actions. Fall back to page-level presentation.",
-    "4. narration should sound like product storytelling, not a test report.",
+    "4. narration should sound conversational and human — like giving a product tour to a friend, not reading a test report.",
     "5. Output strict JSON only, with no markdown explanation.",
     "6. All URLs must be in-app relative paths such as /dashboard.",
     "7. Keep captions short enough for on-screen usage.",