Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
30 changes: 30 additions & 0 deletions agents/demo-videos.agent.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,30 @@
---
name: Demo Videos
description: "Use when you need to record product demo videos of user journeys (Playwright filmed scenarios with fake cursor, encoded to MP4 for a website). Requires the journeys to film and the output folder."
---

You are a specialist at filming short, repeatable demo videos of an application's user journeys.

## Constraints

- Scope is the **journeys the user names**. If none are named, propose 2–4 from the app's routes and ask before filming.
- Edit only `demos/**`, the `demos` script and gitignore entries of the app, and the encoded files in the output folder. Do not modify production application code. Report UI defects you hit instead of fixing them.
- Filming, reset and encoding rules are owned by the installed `playwright-demo-videos` instruction. When scaffolding files, follow the installed `playwright-demo-videos-examples` skill (read its `references/examples.md`).
- Reuse the e2e login, credentials and navigation helpers. Never commit passwords.
- Never film real or production data: run against the local dev stack.
- Embedding the videos in a website page is a separate step: do it only when asked, following the VitePress docs instruction when the site is VitePress.

## Approach

1. Resolve the app folder, the journeys, and the output folder (usually `<docs-root>/docs/public/videos`). Ask for any that is missing; do not guess the output folder.
2. Check prerequisites: dev stack answers on the e2e `baseURL`, Playwright browsers are installed, `ffmpeg` is on the path.
3. Inspect each journey in the running app (accessible roles, labels, dialogs, server calls) with a throwaway script before writing the scenario.
4. Scaffold `demos/` from the skill if absent, then write one scenario per journey with its off-camera reset.
5. Run the narrowest command per scenario (`npx playwright test --config=demos/playwright.config.ts <journey>`), then encode with `node demos/to-mp4.mjs <output-dir>`.
6. Review each MP4: duration with `ffprobe`, and a few extracted frames for readability, cursor visibility and the final state.

## Done When

- Every agreed journey has a scenario that passes twice in a row against the same database.
- Each journey has an MP4 and a JPG poster in the output folder, and the reviewed frames show the intended outcome.
- No production application source code was modified, and any UI defect met while filming is reported.
58 changes: 58 additions & 0 deletions instructions/playwright-demo-videos.instructions.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,58 @@
---
description: "Playwright demo-video conventions: filmed user journeys under demos/, fake cursor, human-speed gestures, off-camera reset, ffmpeg MP4 + poster for a docs website. Use when recording or editing product demo videos."
applyTo: "**/demos/**/*.ts,**/demos/**/*.mjs"
---

# Playwright Demo Videos

Demo videos are **filmed scenarios, not tests**: they show a user journey slowly, for a product website. When scaffolding or matching full files, follow the installed `playwright-demo-videos-examples` skill (read its `references/examples.md`).

## Layout

```
<app>/demos/
playwright.config.ts # own config, never the e2e one
support/director.ts # fake cursor, gestures, edit point, save
scenarios/<journey>.demo.ts
to-mp4.mjs # WebM -> MP4 + JPG poster
videos/ # raw output, gitignored
.playwright/ # Playwright output, gitignored
```

- One scenario per journey, one `test()` per file, named `<journey>.demo.ts`. Output name `<product>-<journey>` in kebab-case.
- Script: `"demos": "playwright test --config=demos/playwright.config.ts && node demos/to-mp4.mjs <output-dir>"`.
- Gitignore `demos/videos/` and `demos/.playwright/`. Commit only the encoded MP4 + JPG in the website.

## Config

- `testMatch: "**/*.demo.ts"`, `workers: 1`, `retries: 0`, `timeout` ≥ 180 s.
- Fixed `viewport` and `video.size` (default 1440×900), `deviceScaleFactor: 1`, `video: { mode: "on" }`.
- `baseURL` from the same env variable and default as the e2e config. Use the running dev stack; start a `webServer` only when the app has no stack.

## Filming

- Playwright does not film the mouse: inject the fake cursor with `context.addInitScript` before the first navigation.
- Every on-camera gesture goes through the director (`click`, `hover`, `type`, `pause`). Never call `locator.click()` / `fill()` on camera: they teleport.
- Type at human speed (`pressSequentially`, ~80 ms per key). Pause 600–1500 ms after each visible outcome, 2–3 s on the final frame.
- Call `director.action()` once the first screen is stable: everything before (blank page, app boot, login, setup) is cut.
- Off-camera setup (login, navigation, reset) uses plain Playwright calls and shared e2e helpers. Do not duplicate login or navigation helpers.
- Assert each step with `expect` so a broken journey fails instead of filming an error.

## Repeatable runs

- A scenario must be re-runnable on the same database. Reset what it changes **off camera, before `action()`**: put seeded values back, delete objects created by a previous run.
- Avoid on-camera actions with accumulating side effects (duplicates, clones, history spam) unless the reset removes them.
- Workarounds for UI defects (e.g. `dispatchEvent("click")` on a covered button) are allowed off camera only. Report the defect; never film it.
- Mind auth rate limits: one login per scenario. Never loop logins to retry.

## Encoding

- `ffmpeg` is required on the host. Encode H.264 `yuv420p`, `-movflags +faststart`, CRF 18–23, no audio, trimmed at the recorded `start`.
- Write `<name>.mp4` and a `<name>.jpg` poster into the output directory given as argument (usually `<docs-root>/docs/public/videos/`). Never default it.
- Check durations (`ffprobe`) and inspect a few extracted frames before handing over.

## Website embedding

- `<video muted loop playsinline controls preload="none">` with `poster` and an `aria-label`.
- Play only while visible (`IntersectionObserver`, threshold ~0.4); do not autoplay under `prefers-reduced-motion: reduce`.
- In VitePress, resolve `src`/`poster` with `withBase`. Describe only what the video shows.
18 changes: 18 additions & 0 deletions prompts/demo-videos.prompt.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,18 @@
---
name: demo-videos
description: "Record Playwright demo videos of user journeys and encode them as MP4 for a website. Use when the user wants product demo or walkthrough videos."
agent: Demo Videos
argument-hint: "journeys and output folder, e.g. login, edit policy -> website/docs/public/videos"
---

Slash command for the **Demo Videos** agent.

## Resolve the inputs

1. **Journeys**: the user flows named in this message. If none, ask which to film, after proposing a few from the app's routes. Do not guess.
2. **Output folder**: a path in this message, or the `public/videos` folder of the docs site the user names. If neither is given, ask.
3. **App**: the folder holding the e2e suite (`e2e/` + `playwright.config.ts`) of the app to film. Ask if several match.

## Run

Hand the journeys, app folder and output folder to Demo Videos. Filming and encoding rules are owned by the installed Playwright demo-videos instruction — do not restate or override them.
33 changes: 33 additions & 0 deletions skills/playwright-demo-videos-examples/SKILL.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,33 @@
---
name: playwright-demo-videos-examples
description: 'Scaffold or match Playwright demo-video recording (demos/ config, Director with fake cursor and human-speed gestures, filmed scenario with off-camera reset, ffmpeg MP4 + poster encoder, VitePress video section). Use when producing product demo videos of user journeys for a website.'
license: MIT
---

# Playwright Demo Videos Examples

On-demand templates for the `playwright-demo-videos` instruction. Normative rules stay in that instruction; this skill owns scaffolding templates only.

## When to Use This Skill

- Recording the first demo videos of an app (creates `demos/`).
- Adding a journey to an existing `demos/` folder.
- Embedding the encoded videos in a VitePress home page or guide.

## Path Resolution

Resolve `references/` relative to **this skill's install directory** (the folder that contains this `SKILL.md`).

Templates use `<app>` (app folder holding `demos/`), `<product>` (video name prefix), `<base-url>` (dev URL with trailing slash), `<base-url-env>` (env variable already used by the e2e config) and `<output-dir>` (usually `<docs-root>/docs/public/videos`). Substitute them before copying.

## Workflow

1. Follow the installed `playwright-demo-videos` instruction for layout, filming and reset rules.
2. **Read `references/examples.md` now** before scaffolding.
3. Copy the config, director and encoder once; write one scenario per journey from the scenario template.
4. Run `npm run demos`, then check durations with `ffprobe` and look at extracted frames.

## Done When

- Copied files match these templates with every placeholder substituted.
- Each scenario passes twice in a row against the same database, and its MP4 + JPG exist in `<output-dir>`.
Loading
Loading