Drupal Demo Recorder

---
name: drupal-demo-recorder
description: Use when asked to record demo videos or screenshots of a Drupal site (running under DDEV) to share with people — e.g. "make a demo video of <feature>", "record a walkthrough", "capture screenshots of this flow for the team", "show this working". Produces 1080p, narrated, validated, presentable captures driven through the real UI with e0ipso/ddev-playwright-cli. Do NOT use for writing automated/CI Playwright tests (use the playwright-cli skill) or for non-Drupal / non-DDEV recording.
---

# drupal-demo-recorder

Produce **demo-ready-for-a-team-meeting** videos and screenshots of a Drupal site
running under DDEV. This skill is the *methodology + quality bar* layer on top of
the `playwright-cli` skill (which documents the raw CLI: `open`, `goto`, `run-code`,
`video-start/chapter/stop`, `screenshot`, sessions). Read that skill for CLI
mechanics; read this one for **how to make the output good and prove it is**.

The bar: a colleague watching in a meeting immediately understands what is happening,
sees every click/keystroke, sees real content (not empty boxes), and never waits on
dead air. If you would be embarrassed to play it in a meeting, it is not done.

## The one rule that drives everything

**Drive the REAL UI, never shortcuts.** Use `page.mouse.move/down/up`,
`locator.click()`, `locator.dragTo()`, and type with `locator.pressSequentially()` /
`page.keyboard.type()`. Do **not** use `locator.fill()` or `page.evaluate(() => el.click())`
or firing the app's AJAX directly. Two reasons:
1. The visible-input overlay only renders a cursor/keystroke for **real** events — shortcuts show nothing on screen.
2. A demo must show the **genuine workflow** a user would perform. "It works, trust me (via AJAX)" is exactly the kind of unconvincing capture this skill exists to prevent.

If a native interaction seems hard (HTML5 drag-and-drop, a modal in an iframe), **spike it** (see Phase 2) — it is almost always drivable. `page.mouse.down/move/up` fires real `dragstart/dragover/drop`; iframes are reachable via `page.frameLocator(...)`.

## Setup — run first (auto-installs missing tooling)

From the DDEV project root, run the idempotent bootstrap. It installs anything missing
and restarts DDEV once if needed — safe to run before every recording:

```bash
bash <skill-dir>/scripts/ensure-tooling.sh
```

It ensures (announcing each project-modifying step):
- **`e0ipso/ddev-playwright-cli`** — the recorder CLI (also provides the `playwright-cli` skill this builds on). Installed via `ddev add-on get`; chromium is built into the web image on restart.
- **`ffmpeg`/`ffprobe`** — added persistently via `.ddev/web-build/Dockerfile.ffmpeg`.
- **`.playwright/cli.config.json`** — copied from `assets/cli.config.example.json` (1920×1080 + `ignoreHTTPSErrors` for DDEV's self-signed cert) if absent.

> It modifies `.ddev/` and triggers one `ddev restart` (brief downtime) only when the add-on
> or ffmpeg are missing; on an already-equipped project it is a no-op. If you'd rather not
> touch `.ddev/`, run the steps printed by the script by hand instead.

Then you still need to know / decide:
- **Which user/role** to record as. Log in with a one-time link: `LOGIN=$(ddev drush --uri=<site-url> uli --name=<user>)`, then `goto` it. The link is single-use — **regenerate it every recording run**.
- The overlay's container path for `addInitScript`. ddev-playwright-cli runs **inside the container** (repo mounted at `/var/www/html`), so reference this skill's overlay by its container path, e.g. `/var/www/html/.claude/skills/drupal-demo-recorder/assets/input-overlay.js`.

## Non-negotiable quality requirements

| Requirement | How |
| --- | --- |
| **1080p desktop frame** | `cli.config.json` viewport 1920×1080; also `await page.setViewportSize({width:1920,height:1080})` at the top of each script. |
| **Visible mouse + keyboard** | `await page.addInitScript({ path: '<container path>/assets/input-overlay.js' })` BEFORE the first `goto`. Drive via real events (the one rule). Move the mouse in steps between targets (`page.mouse.move(x,y,{steps:8})`) so the cursor visibly travels; nudge it once after entering a view so it is on-screen. |
| **Step narration** | Show a chapter title card per step: `await page.evaluate((t)=>window.__demoTitle(t,2600), 'Add a component')`. Also add `video-chapter "..."` markers. |
| **Scroll the subject into view** | Before acting on / capturing an element: `await locator.scrollIntoViewIfNeeded()` or `window.scrollTo({top,behavior:'smooth'})`, then a short pause. Never act on or screenshot something off-screen. |
| **Real content** | Show genuine content that renders (real images, real text), not empty placeholders or Lorem. Decide its source in Phase 0. If a component renders blank, STOP and find out why before recording (commonly a broken text format, a missing field value, or an empty reference). |
| **Natural, even pacing** | Control pacing AT RECORD TIME (see *Pacing* below): dwell after each change, type with a per-key delay, move the mouse in steps. A light post-process slow is optional polish — not the primary lever, and never `slowMo`. |
| **No dead air** | A click that triggers a navigation/heavy re-render makes Playwright auto-wait; the frame freezes. After such a click wait only ~2s then `video-stop`, and/or trim the tail. Never ship >3s of a static screen. |
| **Screenshots = viewport, scrolled** | Capture the viewport with the relevant part scrolled in — NOT `--full-page` (full-page captures overlap fixed toolbars/palettes and look broken). 1080p stills pulled from the finished video are ideal. |

## Pacing — make it readable without making it sluggish

In order of preference:

1. **Record-time pacing (primary).** Make each step readable as it happens:
   - `await page.waitForTimeout(800–1500)` after each meaningful change (the "let it land" beat).
   - Type at human cadence: `locator.pressSequentially(text, { delay: 70 })` (never `fill()`).
   - Move the mouse in visible steps: `page.mouse.move(x, y, { steps: 10 })`; for drags, many small steps with brief pauses so the motion is followable.
   This produces natural, intentional pacing and needs no post-processing.
2. **Light global slow in post (optional polish).** `scripts/process-video.sh ... 1.5`
   (ffmpeg `setpts`) uniformly slows the finished video — handy to ease fast bits like AJAX
   swaps. Caveat: it ALSO stretches unavoidable reload/auto-wait pauses into dead air, so
   keep it modest (≤1.5×) and short-wait-then-stop / trim the tail. Pass `1.0` for
   transcode-only when you already paced at record time.
3. **`slowMo` — avoid for final output.** Playwright's `slowMo` only inserts a fixed delay
   *before each action* → uneven snap-pause-snap motion; it does NOT slow page animations/AJAX
   or the cursor overlay, and it lengthens the live run (more timeout/flake risk). Debugging
   aid only.

## Workflow

Run **Setup** (above) first so the toolchain is present, then work the phases in order.

### Phase 0 — Content: use existing, or create? (ask the user first)

Demos live or die on showing *real* content. Before storyboarding, **ask the user**
(use AskUserQuestion):

1. **"Does the site already have content we should demo with, or should I create demo content?"**
   - *Use existing* → ask which specific items/pages, then resolve their concrete IDs / URLs /
     titles with drush and use those. Confirm they render with real text + images.
   - *Create it* → continue to Q2.
2. If content must be created, ask **"Should I model the demo content on the site's existing
   content, or build it around a theme you give me?"**
   - *Model on existing* → inspect real examples of the relevant content type(s) — fields,
     structure, length, tone, which images/references they use — and create content that
     mirrors them so it looks authentic and on-brand.
   - *Provide a theme* → ask for the theme/topic (plus any tone/brand notes) and generate
     fitting content for it.
3. Either way: after choosing/creating content, **render it and confirm it actually displays**
   (real text + images, no empty placeholders, no broken-format blanks) BEFORE recording.
   Created demo content is disposable — note it in the README and clean it up if the
   environment is not throwaway.

### Phase 1 — Storyboard
Write the ordered list of steps and the chapter title for each, the exact node/page/URL,
the user/role, and the *specific real content* to use (sourced in Phase 0; resolve concrete
IDs/titles with drush). Decide endings (Save vs Discard — Discard keeps a live page pristine
while still demonstrating the edit).

### Phase 2 — Spike risky interactions FIRST
Before recording a full take, prove each non-obvious interaction in isolation and
**screenshot + look at the result**: native drag-and-drop, modal/iframe flows, anything
that re-renders. Capture the working selectors and the exact event sequence. This is what
prevents recording a 90-second take that fails at second 70. (Drag pattern: `mouse.move`
to the handle → `mouse.down()` → small `mouse.move` to start the native drag → read the
drop target's rect → `mouse.move` over it and PAUSE so `dragover` fires → `mouse.up()`.)

### Phase 3 — Record
One continuous `run-code` session per video (named session, e.g. `-s=rec`). Inject the
overlay, set viewport, log in, navigate (`{waitUntil:'domcontentloaded'}` — NEVER `'load'`
on heavy/edit pages, it can hang), then perform the storyboard with real input + title
cards + scrolling. Save the raw `.webm` to the project root.

### Phase 4 — Process
Transcode to a shareable H.264 mp4: `scripts/process-video.sh <raw>.webm demos/.../<name> [speed]`.
If you paced at record time, pass `1.0` (transcode only); use `1.5` only for the optional light
slow (see *Pacing*). Never add a scale filter (you recorded at final resolution).

### Phase 5 — VALIDATE (mandatory — see below). Iterate until it passes.

## Validation loop — you MUST look at the actual output

A recording you have not watched is not done. Reports of success are not evidence.

1. `scripts/extract-frames.sh demos/.../<name>.mp4 <tmp-dir> 8` to dump evenly-spaced frames, **and** hand-grab the key moments (mid-drag, modal open, the embed/result, a keystroke instant): `ddev exec ffmpeg -ss <t> -i /var/www/html/<video> -frames:v 1 /var/www/html/<dir>/m.png`.
2. **Open every frame** (Read the PNG) and check each item:
   - [ ] Exactly **one** cursor visible (watch modals/iframes — a stray second cursor is the classic bug).
   - [ ] **Key badges** appear while typing (proves real keyboard input, not `fill()`).
   - [ ] The **subject is in view** for each step (nothing important off-screen / cut off).
   - [ ] **Real content rendered** — images load, text is genuine, no empty/placeholder boxes, no error/"Status:" noise.
   - [ ] **No dead-air** tail or >3s static stretch (AJAX re-renders that keep content on screen are fine).
   - [ ] Title card present and readable for each step.
   - [ ] Clean **1080p** layout — no overlapping chrome, no clipping, correct resolution (`ffprobe`).
3. Confirm **duration and resolution** with `ffprobe`.
4. **Re-record anything that fails.** Then re-validate. Do not hand off until every box is checked on the final files.
5. Verify the environment is left clean (any temporary config like a front-page swap, draft node, or test content is reverted; the live site still responds 200).

## Common failure modes (seen repeatedly — design them out)

- **Empty / placeholder / Lorem content** → looks broken. Use real content; verify it renders BEFORE recording. Blank field output is often a broken text format (a CKEditor format with no working filter renders empty) or an unselected entity reference.
- **Too fast** → pace at record time (dwells + keystroke `delay` + mouse `steps`); optional light ≤1.5× post-slow. Not `slowMo` (uneven snap-pause).
- **Didn't scroll** → `scrollIntoViewIfNeeded` before each action and capture.
- **Full-page screenshots** → use viewport stills scrolled to the subject (or frames from the video).
- **Dead air at the end** → the Save/submit click auto-waits for a heavy reload; short-wait then stop, or trim.
- **Invisible mouse/keyboard** → you used `fill()`/AJAX instead of real events. Drive the real UI.
- **Two cursors** → the overlay was injected into an iframe without single-cursor forwarding; use the bundled `input-overlay.js` (it forwards child-frame events to one top-frame cursor).
- **Page hangs on load / Edit surface won't open** → don't use `waitUntil:'load'`; use `domcontentloaded` and `waitForFunction` on a real readiness signal. Heavy/content-rich pages may be slow or hit limits — profile and fix, or pick a lighter representative page, but say so.
- **Recorded as the wrong user** → log in (drush uli) as the intended role; permissions change what's visible.
- **Edited PHP/templates and nothing changed** → reload the workers: `ddev exec bash -c "killall -USR2 php-fpm"`.

## Deliverables & housekeeping
- Put videos/screenshots under a `demos/<feature>/` dir with a short README: what each file shows, the demo node/URL/user, and any environment caveats.
- Keep `.mp4` (shareable) alongside `.webm`.
- Note in the README anything non-default you set up to make it work, and whether it was reverted.

## Optional — subagent orchestration for big jobs
For multi-video jobs you can delegate to subagents, but: the DDEV browser is a shared,
serial resource — **do not run two browser-driving subagents at once** (concurrent edit
renders go flaky). Spike in one agent, record serially, and always do an **independent**
validation pass yourself (open the frames) rather than trusting a subagent's self-report.