From ff56501b2590cfb732b303e116e18ae9bea9ea04 Mon Sep 17 00:00:00 2001 From: Claude Date: Wed, 18 Nov 2026 22:13:15 +0000 Subject: [PATCH 1/6] #90 - add a demo skill that reruns saved UI demo scripts Spike for #90: the Argos #961 walkthrough kit as a shared engine. Demos are .demo.js files of named steps in the code repo; run.sh plays them as 2x stills with a walkthrough.md, or (--video) a 30 fps MP4 with chapters.md, from one source. A failed step stops with its name and a screenshot, --from replays from a step, affected.sh lists the demos whose `// covers:` paths a branch changed, and new.sh starts one from the template. tests/e2e.sh covers them. Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_013vbA3iKVfvhFrgVECq2K4Z --- .../.claude/skills/demo/SKILL.md | 18 ++ .../.claude/skills/demo/scripts/affected.sh | 16 ++ .../.claude/skills/demo/scripts/engine.js | 177 ++++++++++++++++++ .../.claude/skills/demo/scripts/new.sh | 20 ++ .../.claude/skills/demo/scripts/run.sh | 34 ++++ .../skills/demo/scripts/template.demo.js | 26 +++ tests/e2e.sh | 47 +++++ 7 files changed, 338 insertions(+) create mode 100644 software/application-software/workspace-inherit/.claude/skills/demo/SKILL.md create mode 100755 software/application-software/workspace-inherit/.claude/skills/demo/scripts/affected.sh create mode 100644 software/application-software/workspace-inherit/.claude/skills/demo/scripts/engine.js create mode 100755 software/application-software/workspace-inherit/.claude/skills/demo/scripts/new.sh create mode 100755 software/application-software/workspace-inherit/.claude/skills/demo/scripts/run.sh create mode 100644 software/application-software/workspace-inherit/.claude/skills/demo/scripts/template.demo.js diff --git a/software/application-software/workspace-inherit/.claude/skills/demo/SKILL.md b/software/application-software/workspace-inherit/.claude/skills/demo/SKILL.md new file mode 100644 index 0000000..945795b --- /dev/null +++ b/software/application-software/workspace-inherit/.claude/skills/demo/SKILL.md @@ -0,0 +1,18 @@ +--- +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. +--- + +A demo is `.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: …`, names the source it shows. `scripts/template.demo.js` documents the format and the helpers a step gets. + +Start the branch's app first (the project's run-local skill), with any data its demos need, then use its URL: + +1. **Which demos:** `bash scripts/affected.sh []` lists the demos whose covered source, or whose own file, the branch changed since `` (default `origin/HEAD`). +2. **Stills, the quick check:** `bash scripts/run.sh […]` (every demo if none is named) writes a 2× PNG per step and `walkthrough.md`, each step's caption over its still, to `pictures//demo//`. Dwells are skipped; waits for data are kept. Open the stills and judge them. +3. **Video:** add `--video` for `.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-.png`: look at it, fix that step in the demo file, and rerun from it with `--from ""` (earlier steps run unpaced and unrecorded). Console errors are listed after each demo; report them. + +**New demo:** `bash scripts/new.sh ` copies the template next to the repo's other demos and prints its path. Fill in its steps by hand with `npx playwright codegen ` (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, set `covers:`, and check it with a stills run. 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. diff --git a/software/application-software/workspace-inherit/.claude/skills/demo/scripts/affected.sh b/software/application-software/workspace-inherit/.claude/skills/demo/scripts/affected.sh new file mode 100755 index 0000000..ab6df1f --- /dev/null +++ b/software/application-software/workspace-inherit/.claude/skills/demo/scripts/affected.sh @@ -0,0 +1,16 @@ +#!/usr/bin/env bash +# affected.sh []: print the demos to rerun in 's worktree of : each +# *.demo.js that changed since its merge base with (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=${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 diff --git a/software/application-software/workspace-inherit/.claude/skills/demo/scripts/engine.js b/software/application-software/workspace-inherit/.claude/skills/demo/scripts/engine.js new file mode 100644 index 0000000..ee7973f --- /dev/null +++ b/software/application-software/workspace-inherit/.claude/skills/demo/scripts/engine.js @@ -0,0 +1,177 @@ +// engine.js stills|video ...: run.sh's engine. Opens each demo's route in +// Chromium at 2x and runs its named steps. Stills skip dwells and write NN-.png plus walkthrough.md +// (a caption per step). Video keeps real pacing with an in-page cursor, records a CDP screencast and +// encodes .mp4 (constant 30 fps, with ffmpeg) plus chapters.md (a timestamp per step). Steps before +// run unpaced and unrecorded. A failed step stops its demo with its name and failed-.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'); + fs.rmSync(dir, { recursive: true, force: true }); + fs.mkdirSync(dir, { recursive: true }); + const demo = require(path.resolve(file)); + 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 first = from ? demo.steps.findIndex((s) => s.name === from) : 0; + 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 (!live || video) continue; + await page.waitForTimeout(300); // let the last click's transition settle + const png = `${String(i + 1).padStart(2, '0')}-${slug(s.name)}.png`; + await page.screenshot({ path: path.join(dir, png) }); + doc.push(`## ${i + 1}. ${s.name}`, '', ...(s.caption ? [s.caption, ''] : []), `![${s.name}](${png})`, ''); + } + 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} 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); +})(); diff --git a/software/application-software/workspace-inherit/.claude/skills/demo/scripts/new.sh b/software/application-software/workspace-inherit/.claude/skills/demo/scripts/new.sh new file mode 100755 index 0000000..e6b1034 --- /dev/null +++ b/software/application-software/workspace-inherit/.claude/skills/demo/scripts/new.sh @@ -0,0 +1,20 @@ +#!/usr/bin/env bash +# new.sh : start demo of the page at from template.demo.js, next +# to the other demos in 's worktree of (or in demos/ at its root), and print its path. +set -euo pipefail +usage='usage: new.sh ' +repo=${1:?$usage}; branch=${2:?$usage}; name=${3:?$usage}; route=${4:?$usage} +case $name in *[!a-z0-9-]*) echo "new: takes lower-case letters, digits and dashes" >&2; exit 1 ;; esac +case $route in /*) ;; *) echo "new: starts with /" >&2; exit 1 ;; esac +case $route in *[!A-Za-z0-9/_.?=-]*) echo "new: 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') +dir=demos; [ -z "$other" ] || dir=$(dirname "$other") +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" diff --git a/software/application-software/workspace-inherit/.claude/skills/demo/scripts/run.sh b/software/application-software/workspace-inherit/.claude/skills/demo/scripts/run.sh new file mode 100755 index 0000000..a20841c --- /dev/null +++ b/software/application-software/workspace-inherit/.claude/skills/demo/scripts/run.sh @@ -0,0 +1,34 @@ +#!/usr/bin/env bash +# run.sh [--video] [--from ] [...]: run the demos (each *.demo.js, or the +# named ones) in 's worktree of against the app at , with engine.js: stills by default, +# --video for an MP4 per demo; --from replays from that step. Output goes to pictures//demo//. +# Exits 1 if a step failed. +set -euo pipefail +usage='usage: run.sh [--video] [--from ] [...]' +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; } +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[@]}" diff --git a/software/application-software/workspace-inherit/.claude/skills/demo/scripts/template.demo.js b/software/application-software/workspace-inherit/.claude/skills/demo/scripts/template.demo.js new file mode 100644 index 0000000..905497a --- /dev/null +++ b/software/application-software/workspace-inherit/.claude/skills/demo/scripts/template.demo.js @@ -0,0 +1,26 @@ +// covers: {{name}} +// {{name}}: a demo of {{route}}, run by the demo skill. The covers line above lists path fragments of the source +// this page shows (component folders, tags), so a branch that changes them reruns this demo. +// Steps run in order. Each one's name is a video chapter and a stills heading, and --from 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); + }, + }, + ], +}; diff --git a/tests/e2e.sh b/tests/e2e.sh index f2751e4..e0160a3 100644 --- a/tests/e2e.sh +++ b/tests/e2e.sh @@ -1299,6 +1299,53 @@ else echo "skip - the delphi mod's browser view: no python3 or curl" fi +# --- 12e. the demo skill (application-software's workspace-inherit): new.sh starts a demo from the template next to +# the others, affected.sh lists the demos whose covered paths a branch changed, and run.sh (when Playwright can +# launch Chromium) writes stills or a video per demo, stopping a broken one at its step with a screenshot +ds=$src/software/application-software/workspace-inherit/.claude/skills/demo/scripts dr=$t/demo da=$t/demo/worktrees/app/feat +mkdir -p "$dr/.delphi" "$da/src/tile" "$da/src/graph" +cp "$src/.delphi/paths.sh" "$dr/.delphi/" +echo "app" >"$da/index.html" +touch "$da/src/tile/tile.ts" "$da/src/graph/graph.ts" +git -C "$da" init -q && git -C "$da" add . && git -C "$da" commit -qm app +demo() { DELPHI_ROOT=$dr bash "$ds/$1" app feat "${@:2}"; } +{ [ "$(demo new.sh tile /index.html)" = "$da/demos/tile.demo.js" ] && ! demo new.sh tile /index.html 2>/dev/null && + ! demo new.sh graph 'x|y' 2>/dev/null && demo new.sh graph /index.html >/dev/null && grep -qx '// covers: graph' "$da/demos/graph.demo.js"; } || + fail "new.sh: a demo from the template, once, with a plain route" +git -C "$da" add . && git -C "$da" commit -qm demos && git -C "$da" branch base +[ -z "$(demo affected.sh base)" ] || fail "affected.sh listed demos with nothing changed: $(demo affected.sh base)" +echo edit >>"$da/src/tile/tile.ts" +[ "$(demo affected.sh base)" = tile ] || fail "affected.sh for an uncommitted edit under tile: $(demo affected.sh base)" +git -C "$da" commit -qam tile && touch "$da/src/graph/new.ts" +[ "$(demo affected.sh base | tr '\n' ' ')" = "graph tile " ] || fail "affected.sh for a commit and a new file: $(demo affected.sh base)" +ok "demo skill: new.sh starts a demo from the template; affected.sh lists the demos whose covered paths changed" +if command -v node >/dev/null && NODE_PATH=$(npm root -g 2>/dev/null) node -e "require('playwright').chromium.launch().then((b) => b.close())" 2>/dev/null; then + cat >"$da/demos/tile.demo.js" <<'EOF' +module.exports = { route: '/index.html', steps: [ + { name: 'Opens', caption: 'The page.', run: async (h) => { await h.dwell(300); } }, + { name: 'Press it', caption: 'Pressed.', run: async (h) => { + await h.click(h.page.getByRole('button', { name: 'Press' })); + await h.page.getByText('Pressed').waitFor({ timeout: 2000 }); + } }, +] }; +EOF + echo "module.exports = { steps: [{ name: 'Breaks here', run: async () => { throw new Error('gone'); } }] };" >"$da/demos/graph.demo.js" + out=$dr/pictures/feat/demo + ! demo run.sh "file://$da" >"$t/out" 2>&1 || fail "run.sh passed a broken demo" + { [ -f "$out/tile/01-opens.png" ] && [ -f "$out/tile/02-press-it.png" ] && grep -qx 'Pressed\.' "$out/tile/walkthrough.md" && + grep -q 'graph: FAILED at step "Breaks here": gone' "$t/out" && [ -f "$out/graph/failed-breaks-here.png" ]; } || fail "run.sh stills: $(cat "$t/out")" + { demo run.sh "file://$da" --from 'Press it' tile >"$t/out" 2>&1 && [ ! -e "$out/tile/01-opens.png" ] && [ -f "$out/tile/02-press-it.png" ]; } || + fail "run.sh --from: $(cat "$t/out")" + if command -v ffmpeg >/dev/null; then + { demo run.sh "file://$da" --video tile >"$t/out" 2>&1 && [ "$(cut -d' ' -f2- "$out/tile/chapters.md" | tr '\n' ,)" = "Opens,Press it," ] && + [ "$(ffprobe -v error -show_entries stream=width,r_frame_rate -of csv=p=0 "$out/tile/tile.mp4")" = 1440,30/1 ] && [ ! -e "$out/tile/frames" ]; } || + fail "run.sh --video: $(cat "$t/out")" + fi + ok "demo skill: run.sh writes stills and a walkthrough, replays --from a step, records a 30 fps video with chapters, and stops a broken step with its name and a screenshot" +else + echo "skip - the demo skill's run.sh: Playwright can't launch Chromium" +fi + # --- 14. dotted names: a workspace's old path-named ws/ branch carries over into ws/ (pushed to both once); # moving a clone between the old and new names moves nothing; 0.8.0 renames what a clone keeps under old names C=software/electrical/workspaces/vcu-dev CN=s.electrical.vcu-dev CO=software/electrical/vcu-dev From 127497afb793bcc5f9709f3a1c342641fe0d2d3a Mon Sep 17 00:00:00 2001 From: Claude Date: Wed, 18 Nov 2026 23:03:08 +0000 Subject: [PATCH 2/6] #90 - demo: keep each mode's output, place the first demo, guide covers, data and branch From a trial on Argos develop's Graph page: stills and --video each replace only their own files, and --from keeps earlier stills in the walkthrough; new.sh puts the repo's first demo in /demos/; the template's covers: starts as TODO and run.sh warns until it's set; SKILL.md says how to load demo data and which branch a demo of the default branch lives on. Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_013vbA3iKVfvhFrgVECq2K4Z --- .../.claude/skills/demo/SKILL.md | 10 ++++---- .../.claude/skills/demo/scripts/engine.js | 24 ++++++++++++------- .../.claude/skills/demo/scripts/new.sh | 13 ++++++---- .../.claude/skills/demo/scripts/run.sh | 3 +++ .../skills/demo/scripts/template.demo.js | 6 +++-- tests/e2e.sh | 19 +++++++++------ 6 files changed, 49 insertions(+), 26 deletions(-) diff --git a/software/application-software/workspace-inherit/.claude/skills/demo/SKILL.md b/software/application-software/workspace-inherit/.claude/skills/demo/SKILL.md index 945795b..f69aa08 100644 --- a/software/application-software/workspace-inherit/.claude/skills/demo/SKILL.md +++ b/software/application-software/workspace-inherit/.claude/skills/demo/SKILL.md @@ -5,14 +5,16 @@ description: Rerun, fix or start a saved web UI demo (a Playwright script per pa A demo is `.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: …`, names the source it shows. `scripts/template.demo.js` documents the format and the helpers a step gets. -Start the branch's app first (the project's run-local skill), with any data its demos need, then use its URL: +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 first (the project's run-local skill), 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 []` lists the demos whose covered source, or whose own file, the branch changed since `` (default `origin/HEAD`). -2. **Stills, the quick check:** `bash scripts/run.sh […]` (every demo if none is named) writes a 2× PNG per step and `walkthrough.md`, each step's caption over its still, to `pictures//demo//`. Dwells are skipped; waits for data are kept. Open the stills and judge them. +2. **Stills, the quick check:** `bash scripts/run.sh […]` (every demo if none is named) writes a 2× PNG per step and `walkthrough.md`, each step's caption over its still, to `pictures//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 `.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-.png`: look at it, fix that step in the demo file, and rerun from it with `--from ""` (earlier steps run unpaced and unrecorded). Console errors are listed after each demo; report them. +A failed step stops its demo with the step's name and `failed-.png`: look at it, fix that step in the demo file, and rerun from it with `--from ""` (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 ` copies the template next to the repo's other demos and prints its path. Fill in its steps by hand with `npx playwright codegen ` (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, set `covers:`, and check it with a stills run. Helpers only one app needs (a tree item, say) go in a `lib.js` next to its demos. +**New demo:** `bash scripts/new.sh []` copies the template next to the repo's other demos and prints its path; the repo's first demo needs ``, the folder of the app it shows, and goes in its `demos/`. Fill in its steps by hand with `npx playwright codegen ` (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. diff --git a/software/application-software/workspace-inherit/.claude/skills/demo/scripts/engine.js b/software/application-software/workspace-inherit/.claude/skills/demo/scripts/engine.js index ee7973f..1dad03f 100644 --- a/software/application-software/workspace-inherit/.claude/skills/demo/scripts/engine.js +++ b/software/application-software/workspace-inherit/.claude/skills/demo/scripts/engine.js @@ -2,7 +2,8 @@ // Chromium at 2x and runs its named steps. Stills skip dwells and write NN-.png plus walkthrough.md // (a caption per step). Video keeps real pacing with an in-page cursor, records a CDP screencast and // encodes .mp4 (constant 30 fps, with ffmpeg) plus chapters.md (a timestamp per step). Steps before -// run unpaced and unrecorded. A failed step stops its demo with its name and failed-.png. +// 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-.png. 'use strict'; const { chromium } = require('playwright'); const fs = require('fs'); @@ -109,16 +110,21 @@ function encode(dir, frames, end, mp4) { async function run(browser, file) { const name = path.basename(file, '.demo.js'); const dir = path.join(out, name), framesDir = path.join(dir, 'frames'); - fs.rmSync(dir, { recursive: true, force: true }); - fs.mkdirSync(dir, { recursive: true }); 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 first = from ? demo.steps.findIndex((s) => s.name === from) : 0; const chapters = [], doc = [`# ${demo.title || name}`, '']; let stop, step, ok = true; try { @@ -131,11 +137,13 @@ async function run(browser, file) { 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 (!live || video) continue; - await page.waitForTimeout(300); // let the last click's transition settle + 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(`## ${i + 1}. ${s.name}`, '', ...(s.caption ? [s.caption, ''] : []), `![${s.name}](${png})`, ''); + doc.push(...entry); } step = undefined; if (video) { @@ -149,7 +157,7 @@ async function run(browser, file) { 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} stills)`); + console.log(`${name}: ${path.join(dir, 'walkthrough.md')} (${demo.steps.length - first} new stills)`); } } catch (e) { ok = false; diff --git a/software/application-software/workspace-inherit/.claude/skills/demo/scripts/new.sh b/software/application-software/workspace-inherit/.claude/skills/demo/scripts/new.sh index e6b1034..0d1c1ca 100755 --- a/software/application-software/workspace-inherit/.claude/skills/demo/scripts/new.sh +++ b/software/application-software/workspace-inherit/.claude/skills/demo/scripts/new.sh @@ -1,9 +1,10 @@ #!/usr/bin/env bash -# new.sh : start demo of the page at from template.demo.js, next -# to the other demos in 's worktree of (or in demos/ at its root), and print its path. +# new.sh []: start demo of the page at from +# template.demo.js, next to the other demos in 's worktree of , and print its path. The repo's +# first demo goes in /demos/ (the folder of the app it shows; `.` for the root). set -euo pipefail -usage='usage: new.sh ' -repo=${1:?$usage}; branch=${2:?$usage}; name=${3:?$usage}; route=${4:?$usage} +usage='usage: new.sh []' +repo=${1:?$usage}; branch=${2:?$usage}; name=${3:?$usage}; route=${4:?$usage}; app=${5:-} case $name in *[!a-z0-9-]*) echo "new: takes lower-case letters, digits and dashes" >&2; exit 1 ;; esac case $route in /*) ;; *) echo "new: starts with /" >&2; exit 1 ;; esac case $route in *[!A-Za-z0-9/_.?=-]*) echo "new: takes letters, digits and / _ . ? = -" >&2; exit 1 ;; esac @@ -12,7 +13,9 @@ case $route in *[!A-Za-z0-9/_.?=-]*) echo "new: takes letters, digits an 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') -dir=demos; [ -z "$other" ] || dir=$(dirname "$other") +if [ -n "$other" ]; then dir=$(dirname "$other") +elif [ -n "$app" ] && [ -d "$wt/$app" ]; then dir=${app%/}/demos; dir=${dir#./} +else echo "new: the first demo needs , the folder in $repo of the app it shows" >&2; exit 1; fi file=$wt/$dir/$name.demo.js [ ! -e "$file" ] || { echo "new: $file already exists" >&2; exit 1; } mkdir -p "$wt/$dir" diff --git a/software/application-software/workspace-inherit/.claude/skills/demo/scripts/run.sh b/software/application-software/workspace-inherit/.claude/skills/demo/scripts/run.sh index a20841c..45cb979 100755 --- a/software/application-software/workspace-inherit/.claude/skills/demo/scripts/run.sh +++ b/software/application-software/workspace-inherit/.claude/skills/demo/scripts/run.sh @@ -27,6 +27,9 @@ for name in "$@"; do 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; } diff --git a/software/application-software/workspace-inherit/.claude/skills/demo/scripts/template.demo.js b/software/application-software/workspace-inherit/.claude/skills/demo/scripts/template.demo.js index 905497a..4f02d63 100644 --- a/software/application-software/workspace-inherit/.claude/skills/demo/scripts/template.demo.js +++ b/software/application-software/workspace-inherit/.claude/skills/demo/scripts/template.demo.js @@ -1,6 +1,8 @@ -// covers: {{name}} +// 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 (component folders, tags), so a branch that changes them reruns this demo. +// 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 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). diff --git a/tests/e2e.sh b/tests/e2e.sh index e0160a3..e4dad55 100644 --- a/tests/e2e.sh +++ b/tests/e2e.sh @@ -1309,16 +1309,19 @@ echo "app" >"$da/index.html" -touch "$da/src/tile/tile.ts" "$da/src/graph/graph.ts" -git -C "$da" init -q && git -C "$da" add . && git -C "$da" commit -qm app -demo() { DELPHI_ROOT=$dr bash "$ds/$1" app feat "${@:2}"; } -{ ! demo new.sh tile /index.html 2>/dev/null && [ "$(demo new.sh tile /index.html .)" = "$da/demos/tile.demo.js" ] && - ! demo new.sh tile /index.html 2>/dev/null && ! demo new.sh graph 'x|y' 2>/dev/null && demo new.sh graph /index.html >/dev/null && - grep -qx '// covers: TODO' "$da/demos/graph.demo.js"; } || - fail "new.sh: the first demo in its app folder, the rest beside it, from the template, once, with a plain route" -sed -i.bak 's|^// covers: TODO|// covers: src/tile/|' "$da/demos/tile.demo.js" && sed -i.bak 's|^// covers: TODO|// covers: src/graph/|' "$da/demos/graph.demo.js" -rm "$da"/demos/*.bak -git -C "$da" add . && git -C "$da" commit -qm demos && git -C "$da" branch base -[ -z "$(demo affected.sh base)" ] || fail "affected.sh listed demos with nothing changed: $(demo affected.sh base)" -echo edit >>"$da/src/tile/tile.ts" -[ "$(demo affected.sh base)" = tile ] || fail "affected.sh for an uncommitted edit under tile: $(demo affected.sh base)" -git -C "$da" commit -qam tile && touch "$da/src/graph/new.ts" -[ "$(demo affected.sh base | tr '\n' ' ')" = "graph tile " ] || fail "affected.sh for a commit and a new file: $(demo affected.sh base)" -ok "demo skill: new.sh starts the first demo in its app folder and the rest beside it; affected.sh lists the demos whose covered paths changed" -if command -v node >/dev/null && NODE_PATH=$(npm root -g 2>/dev/null) node -e "require('playwright').chromium.launch().then((b) => b.close())" 2>/dev/null; then - cat >"$da/demos/tile.demo.js" <<'EOF' -module.exports = { route: '/index.html', steps: [ - { name: 'Opens', caption: 'The page.', run: async (h) => { await h.dwell(300); } }, - { name: 'Press it', caption: 'Pressed.', run: async (h) => { - await h.click(h.page.getByRole('button', { name: 'Press' })); - await h.page.getByText('Pressed').waitFor({ timeout: 2000 }); - } }, -] }; -EOF - echo "module.exports = { steps: [{ name: 'Breaks here', run: async () => { throw new Error('gone'); } }] };" >"$da/demos/graph.demo.js" - out=$dr/pictures/feat/demo - ! demo run.sh "file://$da" >"$t/out" 2>&1 || fail "run.sh passed a broken demo" - { [ -f "$out/tile/01-opens.png" ] && [ -f "$out/tile/02-press-it.png" ] && grep -qx 'Pressed\.' "$out/tile/walkthrough.md" && - grep -q 'graph: FAILED at step "Breaks here": gone' "$t/out" && [ -f "$out/graph/failed-breaks-here.png" ]; } || fail "run.sh stills: $(cat "$t/out")" - { demo run.sh "file://$da" --from 'Press it' tile >"$t/out" 2>&1 && [ -f "$out/tile/01-opens.png" ] && [ -f "$out/tile/02-press-it.png" ] && - grep -qx '## 1. Opens' "$out/tile/walkthrough.md" && grep -qx '## 2. Press it' "$out/tile/walkthrough.md"; } || - fail "run.sh --from: $(cat "$t/out")" - if command -v ffmpeg >/dev/null; then - { demo run.sh "file://$da" --video tile >"$t/out" 2>&1 && [ "$(cut -d' ' -f2- "$out/tile/chapters.md" | tr '\n' ,)" = "Opens,Press it," ] && - [ "$(ffprobe -v error -show_entries stream=width,r_frame_rate -of csv=p=0 "$out/tile/tile.mp4")" = 1440,30/1 ] && [ ! -e "$out/tile/frames" ] && - [ -f "$out/tile/01-opens.png" ] && [ -f "$out/tile/walkthrough.md" ] && demo run.sh "file://$da" tile >"$t/out" 2>&1 && [ -f "$out/tile/tile.mp4" ]; } || - fail "run.sh --video: $(cat "$t/out")" - fi - ok "demo skill: run.sh writes stills and a walkthrough, replays --from a step keeping earlier stills, records a 30 fps video with chapters without clearing the stills, and stops a broken step with its name and a screenshot" -else - echo "skip - the demo skill's run.sh: Playwright can't launch Chromium" -fi - # --- 14. dotted names: a workspace's old path-named ws/ branch carries over into ws/ (pushed to both once); # moving a clone between the old and new names moves nothing; 0.8.0 renames what a clone keeps under old names C=software/electrical/workspaces/vcu-dev CN=s.electrical.vcu-dev CO=software/electrical/vcu-dev From 46b5374eab49d4cf734798b99085fd4459d51855 Mon Sep 17 00:00:00 2001 From: Claude Date: Thu, 19 Nov 2026 15:44:45 +0000 Subject: [PATCH 4/6] #90 - restore the demo e2e test Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_013vbA3iKVfvhFrgVECq2K4Z --- tests/e2e.sh | 52 ++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 52 insertions(+) diff --git a/tests/e2e.sh b/tests/e2e.sh index f2751e4..e4dad55 100644 --- a/tests/e2e.sh +++ b/tests/e2e.sh @@ -1299,6 +1299,58 @@ else echo "skip - the delphi mod's browser view: no python3 or curl" fi +# --- 12e. the demo skill (application-software's workspace-inherit): new.sh starts a demo from the template next to +# the others, affected.sh lists the demos whose covered paths a branch changed, and run.sh (when Playwright can +# launch Chromium) writes stills or a video per demo, stopping a broken one at its step with a screenshot +ds=$src/software/application-software/workspace-inherit/.claude/skills/demo/scripts dr=$t/demo da=$t/demo/worktrees/app/feat +mkdir -p "$dr/.delphi" "$da/src/tile" "$da/src/graph" +cp "$src/.delphi/paths.sh" "$dr/.delphi/" +echo "app" >"$da/index.html" +touch "$da/src/tile/tile.ts" "$da/src/graph/graph.ts" +git -C "$da" init -q && git -C "$da" add . && git -C "$da" commit -qm app +demo() { DELPHI_ROOT=$dr bash "$ds/$1" app feat "${@:2}"; } +{ ! demo new.sh tile /index.html 2>/dev/null && [ "$(demo new.sh tile /index.html .)" = "$da/demos/tile.demo.js" ] && + ! demo new.sh tile /index.html 2>/dev/null && ! demo new.sh graph 'x|y' 2>/dev/null && demo new.sh graph /index.html >/dev/null && + grep -qx '// covers: TODO' "$da/demos/graph.demo.js"; } || + fail "new.sh: the first demo in its app folder, the rest beside it, from the template, once, with a plain route" +sed -i.bak 's|^// covers: TODO|// covers: src/tile/|' "$da/demos/tile.demo.js" && sed -i.bak 's|^// covers: TODO|// covers: src/graph/|' "$da/demos/graph.demo.js" +rm "$da"/demos/*.bak +git -C "$da" add . && git -C "$da" commit -qm demos && git -C "$da" branch base +[ -z "$(demo affected.sh base)" ] || fail "affected.sh listed demos with nothing changed: $(demo affected.sh base)" +echo edit >>"$da/src/tile/tile.ts" +[ "$(demo affected.sh base)" = tile ] || fail "affected.sh for an uncommitted edit under tile: $(demo affected.sh base)" +git -C "$da" commit -qam tile && touch "$da/src/graph/new.ts" +[ "$(demo affected.sh base | tr '\n' ' ')" = "graph tile " ] || fail "affected.sh for a commit and a new file: $(demo affected.sh base)" +ok "demo skill: new.sh starts the first demo in its app folder and the rest beside it; affected.sh lists the demos whose covered paths changed" +if command -v node >/dev/null && NODE_PATH=$(npm root -g 2>/dev/null) node -e "require('playwright').chromium.launch().then((b) => b.close())" 2>/dev/null; then + cat >"$da/demos/tile.demo.js" <<'EOF' +module.exports = { route: '/index.html', steps: [ + { name: 'Opens', caption: 'The page.', run: async (h) => { await h.dwell(300); } }, + { name: 'Press it', caption: 'Pressed.', run: async (h) => { + await h.click(h.page.getByRole('button', { name: 'Press' })); + await h.page.getByText('Pressed').waitFor({ timeout: 2000 }); + } }, +] }; +EOF + echo "module.exports = { steps: [{ name: 'Breaks here', run: async () => { throw new Error('gone'); } }] };" >"$da/demos/graph.demo.js" + out=$dr/pictures/feat/demo + ! demo run.sh "file://$da" >"$t/out" 2>&1 || fail "run.sh passed a broken demo" + { [ -f "$out/tile/01-opens.png" ] && [ -f "$out/tile/02-press-it.png" ] && grep -qx 'Pressed\.' "$out/tile/walkthrough.md" && + grep -q 'graph: FAILED at step "Breaks here": gone' "$t/out" && [ -f "$out/graph/failed-breaks-here.png" ]; } || fail "run.sh stills: $(cat "$t/out")" + { demo run.sh "file://$da" --from 'Press it' tile >"$t/out" 2>&1 && [ -f "$out/tile/01-opens.png" ] && [ -f "$out/tile/02-press-it.png" ] && + grep -qx '## 1. Opens' "$out/tile/walkthrough.md" && grep -qx '## 2. Press it' "$out/tile/walkthrough.md"; } || + fail "run.sh --from: $(cat "$t/out")" + if command -v ffmpeg >/dev/null; then + { demo run.sh "file://$da" --video tile >"$t/out" 2>&1 && [ "$(cut -d' ' -f2- "$out/tile/chapters.md" | tr '\n' ,)" = "Opens,Press it," ] && + [ "$(ffprobe -v error -show_entries stream=width,r_frame_rate -of csv=p=0 "$out/tile/tile.mp4")" = 1440,30/1 ] && [ ! -e "$out/tile/frames" ] && + [ -f "$out/tile/01-opens.png" ] && [ -f "$out/tile/walkthrough.md" ] && demo run.sh "file://$da" tile >"$t/out" 2>&1 && [ -f "$out/tile/tile.mp4" ]; } || + fail "run.sh --video: $(cat "$t/out")" + fi + ok "demo skill: run.sh writes stills and a walkthrough, replays --from a step keeping earlier stills, records a 30 fps video with chapters without clearing the stills, and stops a broken step with its name and a screenshot" +else + echo "skip - the demo skill's run.sh: Playwright can't launch Chromium" +fi + # --- 14. dotted names: a workspace's old path-named ws/ branch carries over into ws/ (pushed to both once); # moving a clone between the old and new names moves nothing; 0.8.0 renames what a clone keeps under old names C=software/electrical/workspaces/vcu-dev CN=s.electrical.vcu-dev CO=software/electrical/vcu-dev From 7e1033a4e9e47f081cbb2fc5fea4bbe00a872cd0 Mon Sep 17 00:00:00 2001 From: Claude Date: Thu, 19 Nov 2026 22:42:26 +0000 Subject: [PATCH 5/6] #90 - demo: start the app in local development, needs a browser app Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_013vbA3iKVfvhFrgVECq2K4Z --- .../workspace-inherit/.claude/skills/demo/SKILL.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/software/application-software/workspace-inherit/.claude/skills/demo/SKILL.md b/software/application-software/workspace-inherit/.claude/skills/demo/SKILL.md index f69aa08..52206fb 100644 --- a/software/application-software/workspace-inherit/.claude/skills/demo/SKILL.md +++ b/software/application-software/workspace-inherit/.claude/skills/demo/SKILL.md @@ -3,11 +3,11 @@ 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. --- -A demo is `.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: …`, names the source it shows. `scripts/template.demo.js` documents the format and the helpers a step gets. +It needs an app that runs in a browser (a web app, or a browser build of one). A demo is `.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: …`, 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 first (the project's run-local skill), 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: +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 []` lists the demos whose covered source, or whose own file, the branch changed since `` (default `origin/HEAD`). 2. **Stills, the quick check:** `bash scripts/run.sh […]` (every demo if none is named) writes a 2× PNG per step and `walkthrough.md`, each step's caption over its still, to `pictures//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. From bd70bcca07de315ca4b28edc9d9c97a4bd6d8ed8 Mon Sep 17 00:00:00 2001 From: Claude Date: Thu, 19 Nov 2026 23:02:13 +0000 Subject: [PATCH 6/6] #90 - demo: new demos go in demos/v/scripts Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_013vbA3iKVfvhFrgVECq2K4Z --- .../.claude/skills/demo/scripts/new.sh | 9 ++++++--- tests/e2e.sh | 12 ++++++------ 2 files changed, 12 insertions(+), 9 deletions(-) diff --git a/software/application-software/workspace-inherit/.claude/skills/demo/scripts/new.sh b/software/application-software/workspace-inherit/.claude/skills/demo/scripts/new.sh index 0d1c1ca..2df06f5 100755 --- a/software/application-software/workspace-inherit/.claude/skills/demo/scripts/new.sh +++ b/software/application-software/workspace-inherit/.claude/skills/demo/scripts/new.sh @@ -1,8 +1,10 @@ #!/usr/bin/env bash # new.sh []: start demo of the page at from -# template.demo.js, next to the other demos in 's worktree of , and print its path. The repo's -# first demo goes in /demos/ (the folder of the app it shows; `.` for the root). +# template.demo.js, in the demos folder of 's worktree of , and print its path. The repo's first +# demo makes /demos/ (the folder of the app it shows; `.` for the root). Each goes in +# demos/v/scripts/, 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=${1:?$usage}; branch=${2:?$usage}; name=${3:?$usage}; route=${4:?$usage}; app=${5:-} case $name in *[!a-z0-9-]*) echo "new: takes lower-case letters, digits and dashes" >&2; exit 1 ;; esac @@ -13,9 +15,10 @@ case $route in *[!A-Za-z0-9/_.?=-]*) echo "new: takes letters, digits an 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") +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 , 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" diff --git a/tests/e2e.sh b/tests/e2e.sh index e4dad55..9cc9922 100644 --- a/tests/e2e.sh +++ b/tests/e2e.sh @@ -1309,12 +1309,12 @@ echo "app