demo-video-creator

name: demo-video-creator description: Record a polished 4K screencast/demo video of Daintree by driving the in-app demo engine (window.electron.demo — animated cursor, spotlight, captions) from a Playwright spec. Use whenever the user wants to make a demo video, screencast, product/marketing clip, or feature walkthrough of Daintree — either from a standard fixture or from a specific existing project folder they point at ("create a video from this folder").

Demo Video Creator

This skill produces a real recorded video (.webm master + .mp4) of Daintree in action. It does NOT mock anything — it launches the actual app with the demo engine enabled and choreographs a fake cursor, spotlight, and captions over a real project while MediaRecorder captures the frame to disk.

How it works (architecture)

Two halves:

1. The in-app demo engine (already built, demo-mode only):
   • src/components/Demo/DemoCursor.tsx — animated cursor: auto-generated Bézier arcs, Fitts's-law timing, ballistic→settle, click ripples. You give it destinations; the realism is automatic.
   • src/components/Demo/DemoOverlay.tsx — spotlight (blur + dim, masked cutout, 300ms fades) and captions (placement presets, size tiers, 200ms fades).
   • src/components/Demo/DemoCaptureBridge.tsx — getDisplayMedia + MediaRecorder → streams chunks to the main process.
   • electron/ipc/handlers/demo.ts + electron/preload.cts — the window.electron.demo API.
2. The Playwright driver (the "scene"): e2e/screenshots/demo-reel.spec.ts is the canonical template. It boots a project with --demo-mode, then awaits window.electron.demo.* calls wrapped in startCapture/stopCapture.

Read e2e/screenshots/demo-reel.spec.ts first — copy/adapt it for each new video rather than starting from scratch.

Two modes

Mode A — standard fixture. Reuse the marketing fixtures in e2e/helpers/screenshotFixtures.ts (createBrushCmsRepo = worktree dashboard, createSurgeCheckoutRepo = agent at work, createOrbitalSyncRepo = multi-agent, etc.). Each returns { dir, cleanup }. This is the default — no setup, deterministic, no API key needed for the non-agent fixtures.

Mode B — a specific project folder. The user sets up a real project folder ("I created a whole project, now make a video from this folder") and gives you its absolute path. Open THAT path instead of a fixture: skip createBrushCmsRepo() and pass the user's path as the dir to mockOpenDialog. First inspect the folder (its worktrees, files, what's interesting) and choreograph the scene around its actual content — generic captions on unknown content look hollow.

The boot flow is identical for both; only the folder dir differs.

Workflow

1. Build the e2e bundle (demo mode is stripped from prod but present in the test build): npm run build:e2e
2. Author the scene — copy demo-reel.spec.ts to e2e/screenshots/<name>.spec.ts (or edit in place for iteration) and write the beats (see API below). Wrap the visible beats in startCapture(...) / stopCapture(), inside a try/finally so capture always finalizes; make each beat best-effort (safe() wrapper) so one missing selector doesn't abort the recording.
3. Record: npx playwright test e2e/screenshots/<name>.spec.ts --project=screenshots --reporter=line (The screenshots Playwright project has a 30-min timeout. A transient macOS launch flake auto-retries.)
4. Post-process (output lands in artifacts/demo/, which is gitignored):
   • Fix the WebM duration (MediaRecorder omits it during live muxing): ffmpeg -i in.webm -c copy fixed.webm
   • Optional QuickTime-friendly copy: ffmpeg -i fixed.webm -c:v libx264 -preset slow -crf 18 -pix_fmt yuv420p -movflags +faststart out.mp4
5. Verify before claiming done — extract frames with ffmpeg -ss <t> -i out.webm -frames:v 1 frame.png and actually look at them (a tiled montage -vf "fps=15,scale=300:-1,tile=7x3" shows fades ramping). Confirm the feature is on screen, the cursor moves, and captions are legible.

The window.electron.demo API (call via page.evaluate)

All calls return promises that resolve when the command's renderer round-trip completes, so await them. The cursor/overlay components must be mounted first — gate on await page.waitForFunction(() => !!window.electron?.demo).

• Cursor: moveTo(xPct, yPct, durationMs?) (x/y are 0–100 % of viewport), moveToSelector(selector, durationMs?, offsetX?, offsetY?), click() (clicks at the cursor's current spot — move first), drag(fromSel, toSel, durationMs?), scroll(selector), pressKey(key, code?, modifiers?, selector?), type(selector, text, cps?).
• Terminals: typeInTerminal(selector, text, cps?) types text into an xterm.js terminal panel char-by-char with humanized timing, and sendKeyToTerminal(selector, key) sends a named special key. These route through the PTY (window.electron.terminal.write), unlike type/pressKey which target CodeMirror/HTML inputs and do not work on terminals. The selector resolves to (or to any element inside) a terminal panel's [data-panel-id]. Supported keys: up, down, left, right, enter, tab, escape, backspace, ctrl-c, ctrl-d, ctrl-u, home, end, pageup, pagedown (arrow keys auto-honor the terminal's application-cursor mode). Example: await d.typeInTerminal('[data-panel-id="…"]', 'echo hi'); await d.sendKeyToTerminal('[data-panel-id="…"]', 'enter');.
• Spotlight: spotlight(selector, padding?) (blur + dim everything else, 300ms fade-in), dismissSpotlight().
• Captions: annotate(selector, text, placement?, size?, id?) → returns { id }. dismissAnnotation(id?) (omit id = clear all; 200ms fades both ways).
  • placement: element-anchored top|bottom|left|right; viewport screen-bottom (subtitle — the default for narration), screen-top, screen-center, lower-third-left|right, top-left|top-right|bottom-left|bottom-right; cursor above-cursor|below-cursor. For viewport/cursor placements pass "" as the selector.
  • size: sm|md|lg|xl (resolved as % of frame height so it scales 1080p↔4K). Default md; subtitles read well at lg.
• Timing/util: sleep(ms), waitForSelector(selector, timeoutMs?), waitForIdle(settleMs?, timeoutMs?), pause()/resume(), screenshot(). waitForIdle settles only once all activity channels are simultaneously quiet for settleMs — CSS/WAAPI animations, DOM mutations, xterm terminal output (subscribed via each live terminal's onWriteParsed), and <video> playback (a playing video blocks idle until it pauses/ends). It returns early at timeoutMs regardless. Safe to use right after typeInTerminal to wait for a command's output to drain. The main-process watchdog is command-aware: it derives its budget from each command's own durationMs/timeoutMs (or text length for type/typeInTerminal) plus a buffer, so a long sleep, waitFor*, or type beat above 30s is honored rather than silently timed out. Unbounded commands (click, scroll, pressKey, …) keep a 30s default.
• Capture: startCapture({ outputPath, fps?, videoBitsPerSecond?, width?, height? }), stopCapture() → { outputPath, frameCount }, getCaptureStatus(). outputPath is a main-process filesystem path; the main process mkdirs its dirname.

Quality / resolution knobs (env, read by the spec)

Defaults give a 4K master at the app's true desktop density (the industry sweet spot — Screen Studio / Stripe / Linear all target logical 1920×1080 @ 2× → 4K). Do NOT zoom the interface by default: zooming reduces the effective layout and hides panels, and setZoomFactor literally magnifies fonts so little fits.

Scene-authoring lessons (hard-won — follow these)

• Tell one story. Intro subtitle → 2–4 focused beats → outro subtitle. Don't narrate every pixel.
• Captions are optional and most users want few of them. When used: keep ≤2 lines, sentence case, and hold them long enough to read — ~15–17 characters/second (a 36-char line ≈ 2.2s minimum on screen).
• Show the feature within the first ~0.5s — open on the real UI, not a title card.
• Cursor + click reads as intent. moveToSelector then click() plays the press/ripple and (for worktree cards etc.) performs the real action — capture the resulting state change.
• Spotlight to focus, then dismiss before moving on. On Daintree's dark theme the blur (not the dim) is what makes the focus read.
• Reading-friendly pacing: sleep generously between beats; IPC round-trips already add latency, so the recording runs a touch longer than the sum of sleeps.

Gotchas / why things are the way they are

• Demo mode must reach the renderer. It's gated on the renderer's process.argv; --demo-mode is forwarded into additionalArguments in electron/window/createWindow.ts and ProjectViewManager.ts. Launch via launchApp({ extraArgs: ["--demo-mode"], windowSize, screenshotScale }).
• getDisplayMedia needs a relaxed Permissions-Policy. display-capture is denied by default; electron/setup/protocols.ts relaxes it to (self) only in demo mode (gated on !app.isPackaged).
• Page handle goes stale on open. The project view reloads once during hydration. Re-acquire with refreshActiveWindow after opening the folder (the template does this twice) before driving the demo.
• Capture file is small even at 4K — that's efficient VBR on a static dark UI, not low quality. Judge sharpness from a native-res crop, not the byte count.
• Animated camera zoom was removed (webFrame.setZoomFactor thrashed xterm's WebGL atlas every frame). Z-axis "camera moves" belong in post (e.g. a CSS transform in Remotion), not at capture time.

Output

Videos go to artifacts/demo/ (gitignored). Commit only the code (engine + spec changes), never the rendered media.