demo-dev 0.0.1-alpha.0

package/README.md

@@ -0,0 +1,174 @@
+<div align="center">
+
+# demo-dev
+
+### Generate polished product demo videos with one command.
+
+Give a URL and a prompt. Get a narrated, Screen Studio-style video.
+
+```bash
+npx demo-dev demo --base-url https://your-app.com --prompt "Show the dashboard and create a new project" --frame
+```
+
+</div>
+
+---
+
+## What it does
+
+`demo-dev` opens your web app in a headless browser, navigates it like a human, records everything, adds AI narration, and renders a polished mp4.
+
+- AI plans the demo from a natural language prompt
+- Ghost-cursor moves the mouse with human-like Bezier curves
+- Playwright screencast records continuously at 60fps
+- CSS zoom animates smoothly into click targets (Screen Studio style)
+- ElevenLabs / OpenAI / local TTS generates narration per scene
+- FFmpeg composes the final video with speed ramps, browser frame, and audio
+
+---
+
+## Quick start
+
+```bash
+npm install -g demo-dev
+npx playwright install chromium
+```
+
+Generate a demo:
+
+```bash
+demo-dev demo \
+  --base-url https://your-app.com \
+  --prompt "Show the onboarding flow and invite a teammate" \
+  --frame
+```
+
+### Authenticated apps
+
+```bash
+demo-dev auth --base-url https://your-app.com --email you@example.com --password 'your-password'
+demo-dev demo --base-url https://your-app.com --prompt "..." --frame
+```
+
+---
+
+## Commands
+
+```bash
+demo-dev demo        # Full pipeline: prompt -> capture -> voice -> render
+demo-dev auth        # Login and save browser session
+demo-dev capture     # Record only (no voice/render)
+demo-dev voice       # Generate TTS narration only
+demo-dev render      # Capture + voice + compose video
+demo-dev plan        # Generate demo plan from git diff
+demo-dev probe       # Plan + probe pages for element discovery
+demo-dev init        # Create config file in your project
+demo-dev doctor      # Check environment (ffmpeg, playwright, etc.)
+demo-dev config      # Show resolved config
+demo-dev providers   # List available AI/TTS providers
+demo-dev comment     # Post demo as a PR comment
+```
+
+Run `demo-dev <command> --help` for detailed options.
+
+---
+
+## Key flags
+
+| Flag | Description |
+|------|-------------|
+| `--prompt "..."` | Natural language description of the demo to create |
+| `--frame` | Wrap video in a browser window with gradient background |
+| `--quality draft\|standard\|high` | Video quality preset |
+| `--base-url` | URL of the app to demo |
+| `--base-ref` | Git base ref for diff-based planning (default: origin/main) |
+| `--output-dir` | Where to write artifacts (default: artifacts) |
+
+---
+
+## AI & voice providers
+
+Set via environment variables:
+
+```bash
+# AI planning (pick one)
+DEMO_AI_PROVIDER=claude          # Uses local Claude CLI
+DEMO_AI_PROVIDER=openai          # Uses OpenAI API
+DEMO_OPENAI_API_KEY=sk-...
+
+# Voice narration (pick one)
+DEMO_TTS_PROVIDER=elevenlabs     # Best quality
+DEMO_ELEVENLABS_API_KEY=sk_...
+DEMO_ELEVENLABS_VOICE_ID=...
+
+DEMO_TTS_PROVIDER=openai         # Good quality
+DEMO_OPENAI_API_KEY=sk-...
+
+DEMO_TTS_PROVIDER=local          # Free, uses macOS `say` command
+```
+
+---
+
+## Config file
+
+Create a `demo.dev.config.json` in your project:
+
+```json
+{
+  "projectName": "My App",
+  "baseUrl": "http://localhost:3000",
+  "baseRef": "origin/main",
+  "outputDir": "artifacts",
+  "preferredRoutes": ["/", "/dashboard"],
+  "featureHints": ["dashboard", "settings"],
+  "auth": {
+    "loginPath": "/login",
+    "emailTarget": { "strategy": "css", "value": "#email" },
+    "passwordTarget": { "strategy": "css", "value": "#password" },
+    "submitTarget": { "strategy": "role", "role": "button", "name": "Login" }
+  }
+}
+```
+
+---
+
+## How it works
+
+```
+prompt + URL
+     |
+     v
+Playwright explores the site (screenshots + interactive elements)
+     |
+     v
+AI generates a demo plan (scenes, actions, narration text)
+     |
+     v
+ghost-cursor executes actions with human-like mouse movement
+     |
+     v
+page.screencast records continuous video + CSS zoom on interactions
+     |
+     v
+ElevenLabs/OpenAI generates narration audio per scene
+     |
+     v
+FFmpeg composes: speed ramps + browser frame + audio sync
+     |
+     v
+polished mp4
+```
+
+---
+
+## Requirements
+
+- Node.js >= 20
+- FFmpeg (install via `brew install ffmpeg` or equivalent)
+- Chromium (installed via `npx playwright install chromium`)
+
+---
+
+## License
+
+MIT

package/bin/demo-cli.js

@@ -0,0 +1,26 @@
+#!/usr/bin/env node
+import { spawn } from "node:child_process";
+import { createRequire } from "node:module";
+import { dirname, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const require = createRequire(import.meta.url);
+const here = dirname(fileURLToPath(import.meta.url));
+const root = resolve(here, "..");
+const cliPath = resolve(root, "src", "cli.ts");
+const tsxPackagePath = require.resolve("tsx/package.json");
+const tsxCliPath = resolve(dirname(tsxPackagePath), "dist", "cli.mjs");
+
+const child = spawn(process.execPath, [tsxCliPath, cliPath, ...process.argv.slice(2)], {
+  stdio: "inherit",
+  cwd: process.cwd(),
+  env: process.env,
+});
+
+child.on("exit", (code, signal) => {
+  if (signal) {
+    process.kill(process.pid, signal);
+    return;
+  }
+  process.exit(code ?? 0);
+});

package/bin/demo-dev.js

@@ -0,0 +1,26 @@
+#!/usr/bin/env node
+import { spawn } from "node:child_process";
+import { createRequire } from "node:module";
+import { dirname, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const require = createRequire(import.meta.url);
+const here = dirname(fileURLToPath(import.meta.url));
+const root = resolve(here, "..");
+const cliPath = resolve(root, "src", "cli.ts");
+const tsxPackagePath = require.resolve("tsx/package.json");
+const tsxCliPath = resolve(dirname(tsxPackagePath), "dist", "cli.mjs");
+
+const child = spawn(process.execPath, [tsxCliPath, cliPath, ...process.argv.slice(2)], {
+  stdio: "inherit",
+  cwd: process.cwd(),
+  env: process.env,
+});
+
+child.on("exit", (code, signal) => {
+  if (signal) {
+    process.kill(process.pid, signal);
+    return;
+  }
+  process.exit(code ?? 0);
+});

package/demo.dev.config.example.json

@@ -0,0 +1,20 @@
+{
+  "projectName": "My App",
+  "baseUrl": "http://localhost:3000",
+  "readyUrl": "http://localhost:3000",
+  "devCommand": "npm run dev",
+  "baseRef": "origin/main",
+  "outputDir": "artifacts",
+  "storageStatePath": "artifacts/storage-state.json",
+  "saveStorageStatePath": "artifacts/storage-state.json",
+  "preferredRoutes": ["/", "/dashboard"],
+  "featureHints": ["home", "dashboard"],
+  "authRequiredRoutes": ["/dashboard"],
+  "auth": {
+    "loginPath": "/login",
+    "emailTarget": { "strategy": "css", "value": "#email" },
+    "passwordTarget": { "strategy": "css", "value": "#password" },
+    "submitTarget": { "strategy": "role", "role": "button", "name": "Login" },
+    "postSubmitWaitMs": 1500
+  }
+}

package/dist/index.d.ts

@@ -0,0 +1,392 @@
+type ActionTarget = {
+    strategy: "label";
+    value: string;
+    exact?: boolean;
+} | {
+    strategy: "text";
+    value: string;
+    exact?: boolean;
+} | {
+    strategy: "placeholder";
+    value: string;
+    exact?: boolean;
+} | {
+    strategy: "testId";
+    value: string;
+} | {
+    strategy: "css";
+    value: string;
+} | {
+    strategy: "role";
+    role: string;
+    name?: string;
+    exact?: boolean;
+};
+type SceneAction = {
+    type: "navigate";
+    url: string;
+} | {
+    type: "wait";
+    ms: number;
+} | {
+    type: "scroll";
+    y: number;
+} | {
+    type: "scrollIntoView";
+    target: ActionTarget;
+} | {
+    type: "click";
+    target: ActionTarget;
+} | {
+    type: "hover";
+    target: ActionTarget;
+} | {
+    type: "fill";
+    target: ActionTarget;
+    value: string;
+} | {
+    type: "press";
+    key: string;
+} | {
+    type: "select";
+    target: ActionTarget;
+    value: string;
+} | {
+    type: "dragSelect";
+    target: ActionTarget;
+    startX?: number;
+    startY?: number;
+    endX?: number;
+    endY?: number;
+} | {
+    type: "waitForText";
+    value: string;
+    exact?: boolean;
+    timeoutMs?: number;
+} | {
+    type: "waitForUrl";
+    value: string;
+    timeoutMs?: number;
+};
+interface DiffContext {
+    currentBranch: string;
+    baseRef: string;
+    changedFiles: string[];
+    diffPreview: string;
+}
+interface DemoScene {
+    id: string;
+    title: string;
+    goal: string;
+    url: string;
+    viewport: {
+        width: number;
+        height: number;
+    };
+    actions: SceneAction[];
+    narration: string;
+    caption: string;
+    durationMs: number;
+    evidenceHints: string[];
+}
+interface DemoPlan {
+    title: string;
+    summary: string;
+    branch: string;
+    generatedAt: string;
+    scenes: DemoScene[];
+}
+interface ProbeElement {
+    tag: string;
+    role: string;
+    name: string;
+    text?: string;
+    label?: string;
+    placeholder?: string;
+    type?: string;
+    href?: string;
+    testId?: string;
+}
+interface ProbeSnapshot {
+    resolvedUrl?: string;
+    pageTitle?: string;
+    headings: string[];
+    textPreview: string;
+    interactiveElements: ProbeElement[];
+    error?: string;
+}
+interface PageProbe {
+    sceneId: string;
+    sceneTitle: string;
+    requestedUrl: string;
+    initial: ProbeSnapshot;
+    followUpAction?: SceneAction;
+    followUp?: ProbeSnapshot;
+}
+interface VoiceToken {
+    text: string;
+    startMs: number;
+    endMs: number;
+}
+interface VoiceLine {
+    sceneId: string;
+    text: string;
+    estimatedMs: number;
+    audioDurationMs?: number;
+    tokens: VoiceToken[];
+    audioPath?: string;
+    audioSrc?: string;
+}
+
+/**
+ * Continuous capture module.
+ *
+ * Instead of recording each scene as a separate browser context (which produces
+ * choppy, slideshow-like output), this module runs ALL scenes in a single
+ * continuous Playwright session while:
+ *
+ *   1. Using the Playwright 1.59 `page.screencast` API for a single unbroken
+ *      WebM recording.
+ *   2. Using `ghost-cursor-playwright` for human-like Bézier-curve mouse
+ *      movement (Fitts's Law, overshoot, random landing points inside elements).
+ *   3. Logging high-frequency cursor positions + interaction events as metadata
+ *      so post-processing can generate intelligent zoom keyframes à la Screen
+ *      Studio.
+ *
+ * The entire module is headless-capable and CI-friendly.
+ */
+
+/** A single logged cursor position sample. */
+interface CursorSample {
+    /** Milliseconds since capture start */
+    atMs: number;
+    x: number;
+    y: number;
+}
+/** A logged interaction event with screen coordinates + timing. */
+interface CaptureInteraction {
+    type: SceneAction["type"] | "scene-start" | "scene-end" | "stable";
+    sceneId: string;
+    atMs: number;
+    x?: number;
+    y?: number;
+    width?: number;
+    height?: number;
+    /** For fill actions – the value typed. */
+    fillValue?: string;
+}
+/** Scene timing marker within the continuous recording. */
+interface SceneMarker {
+    sceneId: string;
+    sceneTitle: string;
+    startMs: number;
+    endMs: number;
+    url: string;
+}
+/** Full output of a continuous capture session. */
+interface ContinuousCaptureResult {
+    /** Path to the single continuous WebM recording. */
+    videoPath: string;
+    /** High-frequency cursor position log. */
+    cursorLog: CursorSample[];
+    /** Interaction events (clicks, fills, navigations, etc.). */
+    interactions: CaptureInteraction[];
+    /** Per-scene timing markers. */
+    sceneMarkers: SceneMarker[];
+    /** Total duration in milliseconds. */
+    totalDurationMs: number;
+    /** Viewport size used for the recording. */
+    viewport: {
+        width: number;
+        height: number;
+    };
+}
+interface ContinuousCaptureOptions {
+    baseUrl: string;
+    outputDir: string;
+    viewport?: {
+        width: number;
+        height: number;
+    };
+}
+declare const capturePlanContinuous: (plan: DemoPlan, options: ContinuousCaptureOptions) => Promise<ContinuousCaptureResult>;
+
+interface ProjectAuthConfig {
+    loginPath?: string;
+    emailTarget?: ActionTarget;
+    passwordTarget?: ActionTarget;
+    submitTarget?: ActionTarget;
+    successUrlPattern?: string;
+    postSubmitWaitMs?: number;
+}
+interface ProjectConfig {
+    projectName?: string;
+    baseUrl?: string;
+    readyUrl?: string;
+    devCommand?: string;
+    baseRef?: string;
+    outputDir?: string;
+    storageStatePath?: string;
+    saveStorageStatePath?: string;
+    preferredRoutes?: string[];
+    featureHints?: string[];
+    authRequiredRoutes?: string[];
+    auth?: ProjectAuthConfig;
+}
+declare const loadProjectConfig: (configPath?: string) => Promise<{
+    path?: string;
+    config: ProjectConfig;
+}>;
+declare const applyProjectEnvironment: (config: ProjectConfig) => void;
+
+/**
+ * Prompt-driven demo planner.
+ *
+ * Instead of starting from a git diff, this planner takes a natural language
+ * prompt ("show the Magic Inbox, filter by positive replies, open a thread")
+ * and generates a DemoPlan by:
+ *
+ *   1. Launching Playwright to explore the target site
+ *   2. Taking screenshots + collecting interactive elements from key pages
+ *   3. Sending the screenshots + element inventory + user prompt to an LLM
+ *   4. Parsing the LLM response into a validated DemoPlan
+ *
+ * This gives users a zero-config, one-shot way to create demos.
+ */
+
+declare const buildPromptPlan: (options: {
+    prompt: string;
+    baseUrl: string;
+    outputDir: string;
+    projectConfig?: ProjectConfig;
+}) => Promise<DemoPlan>;
+
+/**
+ * Post-processing intelligence layer.
+ *
+ * Analyzes the metadata from a continuous capture session (cursor positions,
+ * interaction events, scene markers) and generates a "visual plan" — a timeline
+ * of zoom keyframes, speed ramps, and cursor smoothing parameters that can be
+ * consumed by the FFmpeg composition pipeline.
+ *
+ * The goal is to replicate Screen Studio's approach: raw recording + metadata
+ * → intelligent post-processing that makes the video feel cinematic.
+ */
+
+interface ZoomKeyframe {
+    /** Time offset in the raw recording (ms). */
+    atMs: number;
+    /** Zoom center X as fraction of viewport width (0–1). */
+    centerX: number;
+    /** Zoom center Y as fraction of viewport height (0–1). */
+    centerY: number;
+    /** Zoom scale (1.0 = no zoom, 2.0 = 2x zoom). */
+    scale: number;
+    /** Duration to hold this zoom (ms) before transitioning. */
+    holdMs: number;
+    /** Easing for transitioning INTO this keyframe. */
+    easing: "ease-in-out" | "ease-out" | "spring";
+    /** Transition duration from previous keyframe (ms). */
+    transitionMs: number;
+}
+interface SpeedSegment {
+    /** Start time in raw recording (ms). */
+    startMs: number;
+    /** End time in raw recording (ms). */
+    endMs: number;
+    /** Playback speed (1.0 = normal, 2.0 = 2x, 0.5 = slow). */
+    speed: number;
+    /** Reason for this speed change. */
+    reason: "normal" | "loading" | "idle" | "transition";
+}
+interface SmoothedCursorPoint {
+    /** Time in output video timeline (ms). */
+    atMs: number;
+    x: number;
+    y: number;
+}
+interface VisualPlanResult {
+    zoomKeyframes: ZoomKeyframe[];
+    speedSegments: SpeedSegment[];
+    smoothedCursor: SmoothedCursorPoint[];
+    /** Total duration after speed adjustments (ms). */
+    adjustedDurationMs: number;
+}
+declare const buildVisualPlan: (capture: ContinuousCaptureResult) => VisualPlanResult;
+
+/**
+ * Screen Studio–style browser frame compositing.
+ *
+ * Wraps raw screen recordings in a macOS browser window shell with:
+ *   - Gradient background (configurable colors)
+ *   - macOS-style browser chrome (traffic lights, URL bar)
+ *   - Rounded corners + drop shadow
+ *   - Padding/margin around the window
+ *
+ * Implemented as an FFmpeg filter chain that composites a pre-rendered
+ * browser chrome PNG on top of the recording, positioned within a
+ * gradient background canvas.
+ */
+interface BrowserFrameOptions {
+    /** Gradient start color (top-left). Default: "#f97316" (orange) */
+    gradientFrom?: string;
+    /** Gradient end color (bottom-right). Default: "#a855f7" (purple) */
+    gradientTo?: string;
+    /** Padding around the browser window in pixels. Default: 48 */
+    padding?: number;
+    /** URL to display in the address bar. Default: inferred from capture */
+    displayUrl?: string;
+}
+
+/**
+ * FFmpeg-based video composition pipeline.
+ *
+ * Takes the raw continuous recording + visual plan and produces the final
+ * polished mp4 with:
+ *   - Smooth zoom/pan following interaction targets
+ *   - Variable playback speed (compress loading, normal for interactions)
+ *   - Narration audio overlay with proper sync
+ *   - Background music with ducking
+ *   - Intro/outro title cards
+ */
+
+type VideoQuality = "draft" | "standard" | "high";
+interface ComposeOptions {
+    /** Path to the continuous WebM recording. */
+    videoPath: string;
+    /** Output mp4 path. */
+    outputPath: string;
+    /** Visual plan with zoom keyframes and speed segments. */
+    visualPlan: VisualPlanResult;
+    /** Capture result for viewport info and scene markers. */
+    capture: ContinuousCaptureResult;
+    /** Voice lines (narration audio files). */
+    voiceLines?: VoiceLine[];
+    /** Background music. */
+    bgm?: {
+        path: string;
+        volume?: number;
+        ducking?: number;
+    };
+    /** Video title for intro card. */
+    title?: string;
+    /** Output resolution. */
+    width?: number;
+    height?: number;
+    fps?: number;
+    /** Video quality: "draft" (fast, low), "standard" (default), "high" (slow, best). */
+    quality?: VideoQuality;
+    /** Wrap video in a Screen Studio–style browser frame with gradient background. */
+    frame?: BrowserFrameOptions | boolean;
+}
+declare const composeVideo: (options: ComposeOptions) => Promise<string>;
+
+declare const writeJson: (path: string, value: unknown) => Promise<void>;
+
+declare const buildVoiceScript: (plan: DemoPlan) => VoiceLine[];
+
+declare const synthesizeVoice: (lines: VoiceLine[], options?: {
+    outputDir?: string;
+}) => Promise<VoiceLine[]>;
+
+export { type ActionTarget, type DemoPlan, type DemoScene, type DiffContext, type PageProbe, type ProbeElement, type ProbeSnapshot, type SceneAction, type VoiceLine, type VoiceToken, applyProjectEnvironment, buildPromptPlan, buildVisualPlan, buildVoiceScript, capturePlanContinuous, composeVideo, loadProjectConfig, synthesizeVoice, writeJson };