/showreel

name: showreel
description: Use when the user wants to explain or document something visually — annotated screenshots, feature demos, flow GIFs, terminal recordings, before/after comparisons — or says "take a screenshot", "record this flow", "make a gif of", "show how this works", "annotate this page", "demo this feature", "grava um gif", "tira um print anotado". Covers web pages (self-contained Chromium) and terminal sessions (vhs).

Showreel

Overview

Turn "explain this" into professional visual artifacts in one command each: annotated screenshots, isolated feature demos, animated flow recordings (gif or mp4), terminal session GIFs, and before/after composites. **You speak in CSS selector + text. Never in pixels, never in seconds.** The motor (self-contained Chromium in `scripts/.deps/`, auto-installed on first use) measures the DOM, places annotations deterministically (`lib/autoplace.mjs`), draws, and gates the result — the verdict covers dominance, collision, contrast, and target-text-present. Any agent with Bash can run it, no browser MCP needed.

Scripts live in this plugin's `scripts/` dir. Run `scripts/preflight.sh` once on a new machine (node required; ffmpeg + vhs optional).

Default output dir: `./showreel-out/` in the current project (create it; respect the user's choice if they name another).

One command per artifact

| Need | Command | Output | |---|---|---| | Annotated screenshot (marker + callout, self-validated) | `node scripts/prove.mjs <url> "<selector>" out.png --label "menu opens"` | `PASS out.png kb=<n>` | | Quick auto-annotate — URL only, no selectors (discovers salient elements: heading, primary action, nav, hero, cards; role-based notes; same gate) | `node scripts/auto.mjs <url> [--max N] [--out-dir DIR]` | `PASS <out> kb=<n>` per element, then `AUTO <k>/<n> PASS`; writes `index.json` | | N annotated shots, ONE browser launch (DEFAULT for 2+) | `node scripts/prove.mjs <url> --batch jobs.json` — jobs: `[{selector,out,label,circle,blur,zoom}]` | `PASS <out> kb=<n>` / `FAIL <out> reason=<short>` per job, then `PROVE <k>/<n> PASS` | | Desktop layout (defaults are 900x1400 portrait = mobile breakpoint!) | add `--width 1440 --height 900` to prove/shot/demo | | | Per-shot options | `circle` (ring hugging target), `blur "<sel>"` (pixelate region), `zoom` (magnified inset) | | | Raw tight crop of one element | `node scripts/shot.mjs <url> "<selector>" out.png` | `OK out.png` | | Flow gif (cursor, ripples, per-step notes) | `node scripts/rec.mjs <url> --steps steps.json out.gif` | `OK out.gif` | | Flow mp4 (smooth-motion / over gif limits) | `node scripts/rec.mjs <url> --steps steps.json out.gif --mp4 out.mp4` (`--keep-webm` keeps the intermediate) | `OK out.mp4` | | N takes, ONE browser (pool of 3) | `node scripts/rec.mjs --batch takes.json` | `OK` per take | | Terminal session gif (needs `vhs`) | `node scripts/tape.mjs --steps steps.json out.gif` | `OK out.gif` | | Side-by-side of two PNGs or two GIFs | `node scripts/compose.mjs a.png b.png pair.png --labels "Before,After"` (gifs: `a.gif b.gif pair.gif [--height N]`) | `OK pair.png` | | Side-by-side VIDEO | `node scripts/compose-video.mjs a.webm b.webm out.mp4 [--labels "Before,After"] [--sync-trim]` — `--sync-trim` reads the `.timeline.json` sidecars from `rec --keep-webm` and aligns both takes | `OK out.mp4` | | Shrink a gif/png without visible quality loss | `node scripts/shrink.mjs in.gif [out.gif] [--target-kb N]` | `OK out (X KB -> Y KB, -N%)`; may print `RECOMMEND-MP4 <reason>` | | Wrap a PNG in a share-ready frame (browser window / card, shadow, social aspect) | `node scripts/beautify.mjs in.png [out.png] [--frame window\|card\|minimal] [--ratio 16:9\|9:16\|1:1] [--url "..."] [--bg "c1,c2"]` | `OK out.png (WxH) kb=<n>` | | One isolated annotation primitive | `node scripts/demo.mjs <url> "<sel>" out.png --kind <k>` — k: rect, circle, arrow, badge, blur, label, zoom, callout | `OK out.png` | | N captures, ONE browser launch | `node scripts/demo.mjs <url> --batch jobs.json` — jobs: `[{selector,out,kind,text}]` | `OK` per job | | Lighthouse before/after across branches | `bash scripts/lh-ba.sh <url> showreel-out [audit] [base-branch]` then `shot.mjs` each audit card + `compose.mjs` | real reports, never hand-built |

Picking the right tool

• **Don't know the selectors / want a fast overview of a page** → `auto` (URL only; it picks the salient elements). For precise control of WHICH element + WHAT note → `prove`.
• **Static UI state** → `prove` (annotated) or `shot` (clean crop).
• **Motion / multi-step flow in a browser** → `rec`.
• **CLI / terminal behavior** → `tape` (vhs). Browser things never go through vhs; terminal things never through rec.
• **Comparison** → capture both states, then `compose` (stills) or `compose-video` (takes).
• **Doc page needing one concept per image** → `demo --batch`.
• **Make a capture share-ready (slides, social, marketing)** → `beautify` — frames any PNG with window chrome, shadow and social aspect presets.

Fidelity — match the artifact to the subject

**Effort — the user's dial (default `rich`).** The user can ask for a level in any language ("quick", "rich", "capricha", "cinematic") — honor it. Absent a request, default to **`rich`**: someone trying showreel for the first time should get a result that makes them go *wow*, with zero configuration. Effort scales the CRAFT poured into the RIGHT artifact — it never forces a bigger artifact than the subject needs (one element → a gorgeous annotated still, not a movie).

| Effort | Pour in | Use when | |---|---|---| | `quick` | The lightest artifact that still EXPLAINS — minimal annotation, no camera. | user asks for fast / light | | `standard` | The right artifact, well annotated; light camera on flows. | user asks to keep it lean | | **`rich` — default** | Full capability on the right artifact: camera motion, spotlight, marks/glossary, multi-beat flows, mp4 for a hero, polish. | **default** | | `cinematic` |