2 -description: Create or refine an interactive Pi demo driver and GIF recording workflow
3 -argument-hint: "<
extension-or-demo-name>"
6 -#
Create or refine an interactive Pi demo driver and GIF recording workflow 8 -Create/refine demo driver for `$ARGUMENTS`.
13 -Use asciinema + expect + agg.
17 -- Manual workflow only; never run from check/release gates.
18 -- Driver files live in `drivers/*.mjs`; readable, small, commentable.
19 -- Driver names are focused extension names.
20 - No `*_suite` drivers.
21 -- `scripts/demo.mjs` is engine; drivers contain data/steps only.
22 -- `mise run demo -- ...` is the public interface; it delegates to `node
23 - scripts/demo.mjs ...`.
24 -- Batch/all/changed/list actions live under `mise run demo --` args.
25 -- README missing → fail.
26 - Do not create README silently.
27 -- Assets land in each target extension:
28 - `extensions/<target>/assets/<demo>.gif`.
29 -- `targets` are README/asset owners, usually exactly one primary extension.
30 -- `extensions` may include support extensions when needed for visible UX.
31 -- README demo block is generated after the H1 title:
32 - `<!-- demo:<readme_id-or-name>:start -->` … `<!-- demo:<readme_id-or-name>:end
34 -- Side-by-side before/after demos use the same user prompt; only loaded
35 - extensions/support state may differ.
36 -- Side-by-side demos use shared `readme_id` + identical `readme_items =
37 - [(caption, gif), ...]` across paired drivers.
38 -- Existing generated demo blocks and `## Demo\n\nNone.` placeholders are
41 - GIF is source of truth for visual QA.
50 - Pi default; do not force `--theme dark`.
52 - choose demo-friendly extension/project dir.
53 -- Pi isolation flags:
54 - `--no-session --no-context-files --no-skills --no-prompt-templates
56 -- Load exact extensions with `-e ./extensions/<name>`.
57 -- For footer demos, load footer + client extensions together, but target only
59 -- For footer-client demos, load `footer` as support only when it improves
60 - visibility; target the client.
61 -- Terminal-only extensions need no demo unless they have a stable visible
63 -- Real LLM/quota calls OK for manual demos.
67 -- Spawn real interactive `pi` in PTY with fixed dimensions.
68 -- Actively pump child output to stdout; sleeping alone records empty casts.
69 -- Type commands/prompts char-by-char with deliberate delay so GIF shows typing.
70 -- Pause before Enter.
71 -- Use longer holds for human readability.
72 -- With `--capture-input`, `expect(...)` can match typed prompt text; do not
73 - expect strings that appear in the prompt.
74 -- Modifiers/key overlays:
75 - skip unless Pi visibly reacts; asciinema has no native modifier overlay here.
77 -Good pacing baseline:
81 -- command typing delay:
83 -- prompt typing delay:
87 -- post `/footer` hide:
89 -- post `/footer` show:
92 - 14–18s or until clear final output if reliable
98 -- record with `--headless --overwrite --capture-input --window-size 100x28 -i
100 -- output `.demo/<name>.cast`
104 -- render GIF from cast:
105 - `agg --cols 100 --rows 28 --theme asciinema --text-font-family "JetBrains
106 - Mono" --font-size 14 --line-height 1.25 --idle-time-limit 4.0
107 - --last-frame-duration 5 --fps-cap 24 <cast> <gif>`
111 -- Inspect GIF manually as source of visual truth.
112 -- Use `.txt` only for semantic sanity:
113 - `asciinema convert -f txt <cast> <txt> --overwrite`
114 -- `.txt` may show duplicate lines/artifacts from terminal control sequences;
115 - acceptable if GIF looks good.
116 -- Extract representative PNG frames for assistant-side visual checks:
117 - `convert '<gif>[80]' /tmp/<demo>-80.png` or `magick '<gif>[80]'
118 - /tmp/<demo>-80.png`.
119 -- Prefer final/mid frames over first frame; first frame is often blank startup.
120 -- `understand_image` on animated GIFs is unreliable; it may hallucinate
121 - unrelated terminal content.
122 -- If using vision, run it on extracted PNG frames, not GIFs.
123 -- Avoid `asciinema play` in main terminal; it can disturb visible scrollback due
124 - recorded control sequences.
130 -extensions
= [
"footer",
"context-size",
"cost",
"vcs-status",
"runtime",
"quota"]
131 -targets
= [
"footer"]
137 - (
"command",
"/quota",
0),
138 - (
"expect",
r"quota|usage|provider",
15000,
2000),
139 - (
"prompt",
"Count from one to ten, then finish with: footer clients updated.",
0),
140 - (
"expect",
r"footer clients updated",
30000,
3000),
141 - (
"command",
"/footer",
4000),
142 - (
"command",
"/footer",
5000),
147 -Supported step ops should stay tiny:
150 -- `type(text[, delay_ms])`
151 -- `send(text[, after_ms])`
152 -- `command(text[, after_ms])` — type text slowly, pause, Enter, wait
153 -- `prompt(text[, after_ms])` — type prompt slowly, pause, Enter, wait
154 -- `expect(regex, timeout_ms[, hold_ms])` — semantic readiness check; use after
155 - `command(..., 0)`/`prompt(..., 0)` when needed
156 -- `ready([timeout_ms])` — broad prompt readiness check
162 -- Use `mise run demo -- changed` for demo drivers needing refresh.
163 -- It selects drivers whose driver file, target extension, or loaded extension
164 - changed since latest release tag.
165 -- It skips unchanged demos and prints `OK demo <name> skipped (unchanged since
167 -- Use `mise run demo -- all` only when explicitly refreshing everything.
168 -- Use `mise run demo -- <driver>` for one focused demo.
169 -- Use `mise run demo -- <driver> --out /tmp/<driver>.gif --no-install` for
170 - disposable smoke renders.
171 -- Do not force rerender unchanged demos just to satisfy release/readme checks.
172 -- If no release tag exists, current behavior applies:
173 - treat all relevant demos as changed.
175 -When asked to create a driver:
177 -1. Pick focused primary extension/story:
178 - what user sees, why ext matters.
179 -2. Pick exact support extensions; keep `targets` to README/asset owner(s),
181 -3. Do not create suite demos that target multiple unrelated extensions.
182 -4. Add/read driver in `drivers/`.
184 - `mise run demo -- <demo> --out /tmp/<demo>.gif --no-install`.
185 -6. Ask user to inspect GIF before committing assets/README changes.
187 -When asked to refresh demos:
189 -1. For one driver, run `mise run demo -- <name>`.
190 -2. For all changed drivers, run `mise run demo -- changed`.
191 -3. Inspect changed GIFs, not txt, before claiming ready.