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
Original file line number Diff line number Diff line change
@@ -0,0 +1,20 @@
---
name: demo
description: Rerun, fix or start a saved web UI demo (a Playwright script per page, kept in the code repo) to get stills with a walkthrough, or an MP4 with chapters, for a PR. Use when a PR or ticket should show a UI change, a demo step breaks, or a page needs its first demo.
---

It needs an app that runs in a browser (a web app, or a browser build of one). A demo is `<name>.demo.js` in the code repo, next to the app it shows, so a UI change updates its demo in the same diff. It is a list of named steps, and its first line, `// covers: <path fragment>…`, names the source it shows. `scripts/template.demo.js` documents the format and the helpers a step gets.

A demo lives on the branch with the UI change it shows. To demo the default branch as it is, make a branch off it (the project's new-worktree skill, named by its convention for work without a ticket) and commit the demo there.

Start the branch's app in local development first, then load the data its demos show: a seed script from one of the project's skills where it has one, else whatever the user names. Then use the app's URL:

1. **Which demos:** `bash scripts/affected.sh <repo> <branch> [<base>]` lists the demos whose covered source, or whose own file, the branch changed since `<base>` (default `origin/HEAD`).
2. **Stills, the quick check:** `bash scripts/run.sh <repo> <branch> <url> [<demo>…]` (every demo if none is named) writes a 2× PNG per step and `walkthrough.md`, each step's caption over its still, to `pictures/<branch>/demo/<demo>/`. Dwells are skipped; waits for data are kept. Open the stills and judge them. Stills and video each replace only their own files, so both can sit in the folder for the PR.
3. **Video:** add `--video` for `<demo>.mp4` at real pacing, with a cursor and no burned-in captions, and `chapters.md`, a timestamp per step for the PR body. GitHub attachments must be under 10 MB: the run says when it's over, and `DEMO_CRF=28` (default 20) makes it smaller.

A failed step stops its demo with the step's name and `failed-<step>.png`: look at it, fix that step in the demo file, and rerun from it with `--from "<step>"` (earlier steps run unpaced and unrecorded; their stills from the last run stay in the walkthrough). Console errors are listed after each demo; report them.

**New demo:** `bash scripts/new.sh <repo> <branch> <name> <route> [<app-folder>]` copies the template next to the repo's other demos and prints its path; the repo's first demo needs `<app-folder>`, the folder of the app it shows, and goes in its `demos/`. Fill in its steps by hand with `npx playwright codegen <url><route>` (no model needed), or from the page's accessibility snapshot. Group the actions into named steps with captions, add dwells where a viewer should look, and check it with a stills run. Set `covers:` (it starts as `TODO`) to fragments only this page's source has, its page and component folders, not a word other pages share. Find data by what the page shows, never by an id that changes with each seed. Helpers only one app needs (a tree item, say) go in a `lib.js` next to its demos.

Commit demo changes on the branch with the UI change. Attach the MP4 or the stills to the PR, with `chapters.md` or the walkthrough's captions in its body.
Original file line number Diff line number Diff line change
@@ -0,0 +1,16 @@
#!/usr/bin/env bash
# affected.sh <repo> <branch> [<base>]: print the demos to rerun in <branch>'s worktree of <repo>: each
# *.demo.js that changed since its merge base with <base> (default origin/HEAD), or whose `// covers:` line
# names a path fragment found in a changed file's path. Uncommitted and new files count as changed.
set -euo pipefail
usage='usage: affected.sh <repo> <branch> [<base>]'
repo=${1:?$usage}; branch=${2:?$usage}; base=${3:-origin/HEAD}
# shellcheck source=/dev/null
. "${DELPHI_ROOT:?unset: start the session at the workspace root}/.delphi/paths.sh"
wt=$DELPHI_WORKTREES/$repo/$branch
[ -d "$wt" ] || { echo "affected: no worktree at worktrees/$repo/$branch (make it with new-worktree.sh)" >&2; exit 1; }
changed=$(git -C "$wt" diff --name-only "$(git -C "$wt" merge-base "$base" HEAD)" && git -C "$wt" ls-files -o --exclude-standard)
git -C "$wt" ls-files -co --exclude-standard -- '*.demo.js' | while IFS= read -r demo; do
patterns=$(echo "$demo" && sed -n 's|^// covers:||p' "$wt/$demo" | tr -s '[:blank:]' '\n' | grep -v '^$' || true)
! grep -qF -- "$patterns" <<<"$changed" || { name=${demo##*/} && echo "${name%.demo.js}"; }
done
Original file line number Diff line number Diff line change
@@ -0,0 +1,185 @@
// engine.js <out> <url> stills|video <from-step> <demo.js>...: run.sh's engine. Opens each demo's route in
// Chromium at 2x and runs its named steps. Stills skip dwells and write NN-<step>.png plus walkthrough.md
// (a caption per step). Video keeps real pacing with an in-page cursor, records a CDP screencast and
// encodes <demo>.mp4 (constant 30 fps, with ffmpeg) plus chapters.md (a timestamp per step). Steps before
// <from-step> run unpaced and unrecorded, and their stills stay in walkthrough.md. Each mode replaces only its
// own files. A failed step stops its demo with its name and failed-<step>.png.
'use strict';
const { chromium } = require('playwright');
const fs = require('fs');
const path = require('path');
const { execFileSync } = require('child_process');

const [out, url, mode, from, ...demos] = process.argv.slice(2);
const video = mode === 'video';
const slug = (s) => s.toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-|-$/g, '');
const clock = (s) => `${Math.floor(s / 60)}:${String(Math.floor(s % 60)).padStart(2, '0')}`;

/** Headless video has no pointer: draw one as a manual popover, re-raised whenever another popover opens,
* so overlays in the top layer (CDK's are popovers) never cover it. */
function cursor() {
const add = () => {
const c = document.createElement('div');
c.setAttribute('popover', 'manual');
c.style.cssText = 'position:fixed;inset:auto;left:0;top:0;width:22px;height:22px;margin:-11px 0 0 -11px;padding:0;' +
'border-radius:50%;background:rgba(255,255,255,.35);border:2px solid #fff;box-shadow:0 0 0 1px rgba(0,0,0,.6);' +
'pointer-events:none;transition:transform .12s;transform:translate(-100px,-100px)';
document.documentElement.appendChild(c);
c.showPopover();
addEventListener('toggle', (e) => { if (e.target !== c && e.newState === 'open') { c.hidePopover(); c.showPopover(); } }, true);
let at = 'translate(-100px,-100px)';
addEventListener('mousemove', (e) => { at = `translate(${e.clientX}px,${e.clientY}px)`; c.style.transform = at; }, true);
addEventListener('mousedown', () => { c.style.transform = at + ' scale(.7)'; c.style.background = 'rgba(239,68,68,.6)'; }, true);
addEventListener('mouseup', () => { c.style.transform = at; c.style.background = 'rgba(255,255,255,.35)'; }, true);
};
if (document.readyState === 'loading') document.addEventListener('DOMContentLoaded', add);
else add();
}

/** What a step gets. Paced (video): human-speed moves, and dwells hold the frame; unpaced: both instant.
* wait() is for data and always waits. */
function harness(page, paced) {
const h = {
page,
wait: (ms) => page.waitForTimeout(ms),
dwell: async (ms) => { if (paced) await page.waitForTimeout(ms); },
async moveTo(loc, { dx = 0, dy = 0, steps = 20 } = {}) {
await loc.waitFor({ state: 'visible', timeout: 10000 });
await loc.scrollIntoViewIfNeeded({ timeout: 3000 }).catch(() => {});
const b = await loc.boundingBox();
if (!b) throw new Error(`no box for ${loc}`);
await page.mouse.move(b.x + b.width / 2 + dx, b.y + b.height / 2 + dy, { steps: paced ? steps : 1 });
await h.dwell(180);
},
async click(loc, opts) {
await h.moveTo(loc, opts);
await page.mouse.down();
await h.dwell(70);
await page.mouse.up();
await h.dwell(350);
},
async drag(loc, x, y) {
await h.moveTo(loc);
await page.mouse.down();
await page.mouse.move(x, y, { steps: paced ? 30 : 5 });
await page.mouse.up();
await h.dwell(300);
},
async key(k) { await page.keyboard.press(k); await h.dwell(400); },
type: (text) => page.keyboard.type(text, { delay: paced ? 120 : 0 }),
park: (x, y) => page.mouse.move(x, y, { steps: paced ? 15 : 1 }),
async pick(combobox, option) {
await h.click(combobox);
await h.click(page.getByRole('option', { name: option }).first());
},
};
return h;
}

/** Starts a 2x JPEG screencast into dir; stop() resolves to [{ file, t }], t in epoch seconds. */
async function screencast(ctx, page, dir) {
fs.mkdirSync(dir, { recursive: true });
const cdp = await ctx.newCDPSession(page);
const frames = [], writes = [];
cdp.on('Page.screencastFrame', (f) => {
cdp.send('Page.screencastFrameAck', { sessionId: f.sessionId }).catch(() => {});
const file = `${String(frames.length).padStart(6, '0')}.jpg`;
frames.push({ file, t: f.metadata.timestamp });
writes.push(fs.promises.writeFile(path.join(dir, file), Buffer.from(f.data, 'base64')));
});
const { width, height } = page.viewportSize();
await cdp.send('Page.startScreencast', { format: 'jpeg', quality: 95, maxWidth: width * 2, maxHeight: height * 2 });
return async () => {
await cdp.send('Page.stopScreencast');
await Promise.all(writes);
return frames;
};
}

/** Each frame lasts until the next one's timestamp; ffmpeg resamples that to 30 fps, at most 1440 wide. */
function encode(dir, frames, end, mp4) {
const list = ['ffconcat version 1.0'];
frames.forEach((f, i) => list.push(`file '${f.file}'`, `duration ${((frames[i + 1] ? frames[i + 1].t : end) - f.t).toFixed(4)}`));
list.push(`file '${frames[frames.length - 1].file}'`);
fs.writeFileSync(path.join(dir, 'frames.txt'), list.join('\n') + '\n');
execFileSync('ffmpeg', ['-y', '-v', 'error', '-f', 'concat', '-safe', '0', '-i', path.join(dir, 'frames.txt'),
'-vf', "fps=30,scale='min(1440,iw)':-2:flags=lanczos,format=yuv420p", '-c:v', 'libx264', '-preset', 'slow',
'-tune', 'stillimage', '-crf', process.env.DEMO_CRF || '20', '-movflags', '+faststart', mp4]);
}

async function run(browser, file) {
const name = path.basename(file, '.demo.js');
const dir = path.join(out, name), framesDir = path.join(dir, 'frames');
const demo = require(path.resolve(file));
const first = from ? demo.steps.findIndex((s) => s.name === from) : 0;
fs.mkdirSync(dir, { recursive: true });
// Clear only this mode's output (stills from the replayed step on), so stills and video keep each other's.
if (first >= 0) for (const f of fs.readdirSync(dir)) {
const mine = video ? f === `${name}.mp4` || f === 'chapters.md'
: f === 'walkthrough.md' || (/^\d+-.*\.png$/.test(f) && parseInt(f, 10) > first);
if (mine || f.startsWith('failed-') || f === 'frames') fs.rmSync(path.join(dir, f), { recursive: true, force: true });
}
const ctx = await browser.newContext({ viewport: demo.viewport || { width: 1440, height: 900 }, deviceScaleFactor: 2 });
if (video) await ctx.addInitScript(cursor);
const page = await ctx.newPage();
const errors = [];
page.on('pageerror', (e) => errors.push(e.message));
page.on('console', (m) => { if (m.type() === 'error') errors.push(m.text()); });
const chapters = [], doc = [`# ${demo.title || name}`, ''];
let stop, step, ok = true;
try {
if (first < 0) throw new Error(`no step named "${from}"`);
await page.goto(url + (demo.route || ''));
if (demo.ready) await demo.ready(harness(page, false)); // warm-up, never recorded
for (const [i, s] of demo.steps.entries()) {
step = s;
const live = i >= first;
if (live && video && !stop) stop = await screencast(ctx, page, framesDir);
if (live && video) chapters.push({ t: Date.now() / 1000, name: s.name });
await s.run(harness(page, live && video));
if (video) continue;
const png = `${String(i + 1).padStart(2, '0')}-${slug(s.name)}.png`;
const entry = [`## ${i + 1}. ${s.name}`, '', ...(s.caption ? [s.caption, ''] : []), `![${s.name}](${png})`, ''];
if (!live) { if (fs.existsSync(path.join(dir, png))) doc.push(...entry); continue; } // kept from an earlier run
await page.waitForTimeout(300); // let the last click's transition settle
await page.screenshot({ path: path.join(dir, png) });
doc.push(...entry);
}
step = undefined;
if (video) {
const end = Date.now() / 1000, frames = await stop();
stop = undefined;
const mp4 = path.join(dir, `${name}.mp4`), t0 = frames[0].t;
encode(framesDir, frames, end, mp4);
fs.writeFileSync(path.join(dir, 'chapters.md'), chapters.map((c) => `${clock(Math.max(0, c.t - t0))} ${c.name}`).join('\n') + '\n');
const mb = fs.statSync(mp4).size / 1e6;
console.log(`${name}: ${mp4} (${mb.toFixed(1)} MB, ${clock(end - t0)}), chapters in ${path.join(dir, 'chapters.md')}`);
if (mb >= 10) console.log(`${name}: over GitHub's 10 MB attachment limit; rerun with DEMO_CRF=28 (default 20)`);
} else {
fs.writeFileSync(path.join(dir, 'walkthrough.md'), doc.join('\n'));
console.log(`${name}: ${path.join(dir, 'walkthrough.md')} (${demo.steps.length - first} new stills)`);
}
} catch (e) {
ok = false;
const shot = path.join(dir, `failed-${step ? slug(step.name) : 'start'}.png`);
await page.screenshot({ path: shot }).catch(() => {});
console.log(`${name}: FAILED at ${step ? `step "${step.name}"` : 'start'}: ${String(e.message).split('\n')[0]}\n screenshot: ${shot}`);
}
if (stop) await stop().catch(() => {});
fs.rmSync(framesDir, { recursive: true, force: true });
if (errors.length) console.log(`${name}: ${errors.length} console errors, first: ${errors[0].split('\n')[0].slice(0, 160)}`);
await ctx.close();
return ok;
}

(async () => {
// Chromium gives 2x screencast frames only when launched with this flag.
const browser = await chromium.launch({ args: ['--force-device-scale-factor=2'] });
let ok = true;
try {
for (const file of demos) ok = (await run(browser, file)) && ok;
} finally {
await browser.close();
}
process.exit(ok ? 0 : 1);
})();
Original file line number Diff line number Diff line change
@@ -0,0 +1,26 @@
#!/usr/bin/env bash
# new.sh <repo> <branch> <name> <route> [<app-folder>]: start demo <name> of the page at <route> from
# template.demo.js, in the demos folder of <branch>'s worktree of <repo>, and print its path. The repo's first
# demo makes <app-folder>/demos/ (the folder of the app it shows; `.` for the root). Each goes in
# demos/v<version>/scripts/, <version> being the template's format below, so a demo's format shows in its path.
set -euo pipefail
version=1 # bump when template.demo.js or engine.js changes what a demo file must contain
usage='usage: new.sh <repo> <branch> <name> <route> [<app-folder>]'
repo=${1:?$usage}; branch=${2:?$usage}; name=${3:?$usage}; route=${4:?$usage}; app=${5:-}
case $name in *[!a-z0-9-]*) echo "new: <name> takes lower-case letters, digits and dashes" >&2; exit 1 ;; esac
case $route in /*) ;; *) echo "new: <route> starts with /" >&2; exit 1 ;; esac
case $route in *[!A-Za-z0-9/_.?=-]*) echo "new: <route> takes letters, digits and / _ . ? = -" >&2; exit 1 ;; esac
# shellcheck source=/dev/null
. "${DELPHI_ROOT:?unset: start the session at the workspace root}/.delphi/paths.sh"
wt=$DELPHI_WORKTREES/$repo/$branch
[ -d "$wt" ] || { echo "new: no worktree at worktrees/$repo/$branch (make it with new-worktree.sh)" >&2; exit 1; }
other=$(git -C "$wt" ls-files -co --exclude-standard -- '*.demo.js' | awk 'NR == 1')
if [ -n "$other" ]; then dir=$(dirname "$other" | sed 's|/v[0-9][0-9]*/scripts$||')
elif [ -n "$app" ] && [ -d "$wt/$app" ]; then dir=${app%/}/demos; dir=${dir#./}
else echo "new: the first demo needs <app-folder>, the folder in $repo of the app it shows" >&2; exit 1; fi
dir=$dir/v$version/scripts
file=$wt/$dir/$name.demo.js
[ ! -e "$file" ] || { echo "new: $file already exists" >&2; exit 1; }
mkdir -p "$wt/$dir"
sed -e "s|{{name}}|$name|g" -e "s|{{route}}|$route|g" "$(dirname "$0")/template.demo.js" >"$file"
echo "$file"
Original file line number Diff line number Diff line change
@@ -0,0 +1,37 @@
#!/usr/bin/env bash
# run.sh <repo> <branch> <url> [--video] [--from <step>] [<demo>...]: run the demos (each *.demo.js, or the
# named ones) in <branch>'s worktree of <repo> against the app at <url>, with engine.js: stills by default,
# --video for an MP4 per demo; --from replays from that step. Output goes to pictures/<branch>/demo/<demo>/.
# Exits 1 if a step failed.
set -euo pipefail
usage='usage: run.sh <repo> <branch> <url> [--video] [--from <step>] [<demo>...]'
repo=${1:?$usage}; branch=${2:?$usage}; url=${3:?$usage}; shift 3
# shellcheck source=/dev/null
. "${DELPHI_ROOT:?unset: start the session at the workspace root}/.delphi/paths.sh"
here=$(cd "$(dirname "$0")" && pwd)
wt=$DELPHI_WORKTREES/$repo/$branch
[ -d "$wt" ] || { echo "run: no worktree at worktrees/$repo/$branch (make it with new-worktree.sh)" >&2; exit 1; }
mode=stills from=
while [ $# -gt 0 ]; do
case $1 in --video) mode=video ;; --from) from=${2:?$usage}; shift ;; *) break ;; esac
shift
done
all=$(git -C "$wt" ls-files -co --exclude-standard -- '*.demo.js')
files=()
if [ $# -eq 0 ]; then
while IFS= read -r f; do [ -z "$f" ] || files+=("$wt/$f"); done <<<"$all"
fi
for name in "$@"; do
f=$(awk -v n="$name.demo.js" '{ b = $0; sub(/.*\//, "", b) } b == n { print; exit }' <<<"$all")
[ -n "$f" ] || { echo "run: no $name.demo.js in worktrees/$repo/$branch" >&2; exit 1; }
files+=("$wt/$f")
done
[ ${#files[@]} -gt 0 ] || { echo "run: no *.demo.js in worktrees/$repo/$branch (start one with new.sh)" >&2; exit 1; }
for f in "${files[@]}"; do
! grep -q '^// covers: TODO' "$f" || echo "run: set the covers: line in ${f#"$wt"/} (see its comment)" >&2
done
NODE_PATH=$(npm root -g 2>/dev/null || true)${NODE_PATH:+:$NODE_PATH}; export NODE_PATH
node -e "require('playwright')" 2>/dev/null ||
{ echo "run: needs Playwright for node: npm i -g playwright && npx playwright install chromium" >&2; exit 1; }
[ $mode = stills ] || command -v ffmpeg >/dev/null || { echo "run: --video needs ffmpeg on PATH" >&2; exit 1; }
node "$here/engine.js" "$DELPHI_ROOT/pictures/$branch/demo" "${url%/}" "$mode" "$from" "${files[@]}"
Original file line number Diff line number Diff line change
@@ -0,0 +1,28 @@
// covers: TODO
// {{name}}: a demo of {{route}}, run by the demo skill. The covers line above lists path fragments of the source
// this page shows, specific enough that other pages don't match (its page and component folders, like
// pages/graph-page/ components/graph/, not a word like graph), so a branch that changes them reruns this demo.
// Find data by what the page shows (a name, a topic), never by an id that changes each time data is seeded.
// Steps run in order. Each one's name is a video chapter and a stills heading, and --from <name> replays from it.
// A step gets h: h.page (the Playwright page); h.moveTo, h.click (locator, { dx, dy }), h.drag (locator, x, y),
// h.key, h.type, h.pick (combobox, option name) and h.park (x, y: rest the cursor off hover targets).
// h.dwell(ms) holds the video for viewers and is skipped in stills; h.wait(ms) and locator waits hold for data in both.
// Helpers only this app needs go in a lib.js next to its demos: const lib = require('./lib');
module.exports = {
title: '{{name}}',
route: '{{route}}',
viewport: { width: 1440, height: 900 },
// Warm-up before the first step, never recorded: wait until the page shows real data.
ready: async (h) => {
await h.page.locator('body').waitFor();
},
steps: [
{
name: 'Overview',
caption: 'What the page shows when it opens.',
run: async (h) => {
await h.dwell(2500);
},
},
],
};
Loading
Loading