Showreel

Turn a URL + CSS selectors into a finished visual — annotated screenshots, flow GIFs, smooth-motion recordings and terminal captures. One command each. The agent never guesses pixels; every output is pixel-verified before it's saved.

English · Português

Showcase

One pass, one real flow — Showreel walks a deploy: read the pipeline → hit the health gate → auto-rollback → re-run → ship. Camera, marks + legend, spotlight and a rollout bar, each in service of the step, never decoration. Generated entirely by the plugin against the bundled demo page. (click to play the full MP4)

Every image in this README was generated by Showreel itself, against the bundled "Lumen" demo page. Run the same commands, get the same files.

What it is

A Claude Code plugin for visual documentation — explaining a change, a bug, a feature flow, a UI/landing-page showcase or a tutorial step with a picture instead of a paragraph. It's built to inform, not entertain: for the devs and stakeholders who need to understand how something works, so every artifact stays legible and proportional to its content: no invented drama, no filler — but as rich as clarity demands, because restraint is against noise, never against capability.

You point it at a page and name elements by CSS selector. Showreel measures the DOM, draws the annotation exactly on target, and validates the result before exit — a bad capture is an error, never a shipped file. No screenshot → eyeball → retry loop, no pixel coordinates, no tokens burned guessing.

• Self-contained — bundles its own headless Chromium; no browser MCP, no credentials, no telemetry. The only network is rendering the page URL you ask for, plus a one-time Playwright + Chromium download on first run (from npm and Microsoft's CDN; pre-warm it with preflight.sh).
• Deterministic — same selectors in, same pixels out. Placement is computed, not guessed.
• Cheap — --batch renders many captures in one browser launch.

Quick start

# install
claude plugin marketplace add HeyRenan/showreel
claude plugin install showreel@showreel

# one-time: check the machine + pre-warm the motor (~90MB Chromium, once)
bash ~/.claude/plugins/showreel/showreel/scripts/preflight.sh
node ~/.claude/plugins/showreel/showreel/scripts/ensure-deps.mjs

Restart Claude Code, then invoke /showreel and describe what to capture. Or run a script directly:

# annotate one element, self-validated
node scripts/prove.mjs https://example.com ".cards .card:first-child" out.png --label "Service card verified"

/showreel:guide opens a visual setup guide. Local-folder install and full paths in INSTALL.md.

Zero config — just a URL

Don't know the selectors? Point Showreel at a page and it finds the salient elements itself — heading, primary action, navigation, metrics, hero, cards — annotates each with a role-based note, and runs the same vcheck gate as prove. One browser launch.

node scripts/auto.mjs https://your-app.example.com

primary action — discovered + zoomed	key metric — discovered
key input form — discovered	hero image — discovered

All four shots came from one auto.mjs command against the bundled demo page — not a selector written. It prints a PASS line per element, then AUTO <k>/<n> PASS, plus an index.json manifest. A discovered element that vanishes before capture (SPA re-render, themed swap) is a soft skip, never a failure.

Share-ready frames

Wrap any capture in a browser-window or card frame — shadow, rounded corners, gradient background — and export to a social aspect ratio. A raw screenshot becomes something you can drop in a slide, a README, or a launch post.

node scripts/beautify.mjs shot.png --url "your-app.com"        # browser window (default)
node scripts/beautify.mjs shot.png --ratio 16:9 --frame card   # social card

What it can do

Every capability, one command each. All scripts live in showreel/scripts/. The agent always speaks in selectors + text, never pixels.

Recording: how steps work

rec.mjs takes JSON steps — each names an element and what to do. The script owns all the motion.

node scripts/rec.mjs <url> --steps-json '[
 {"click":"#menu","note":"Drawer opens","badge":1,"screen":"Dashboard"},
 {"scrollTo":".cards","rect":true,"glide":true,"note":"Active services","badge":2},
 {"fill":"#email","text":"dana@example.com"},
 {"camera":{"sel":".kpis","zoom":1.3},"note":"Framing the KPIs"},
 {"click":"#deploy","follow":1.6,"note":"Camera chases the cursor"}
]' out.gif

56 step keys (unknown keys rejected up front):

• actions — click, fill, text, select, option, scrollTo, scrollIn, to, hide
• annotation — note, arrow, badge, rect, circle, marks, glossary, inset, modal
• camera / motion — camera, zoom, follow, glide, speed
• emphasis — spotlight, blur, redact, highlight, pulse, ripple, shake, glow, flash
• state / data — checkmark, typeon, reveal, orbit, kenburns, progress, countdown, countup, sparkline, confetti, trail
• live — live (mutate a glossary/modal in place across steps — append/update/recolor/replace/remove)
• chrome / timing — screen, topbar, bottombar, wait, delay, fade, stagger, accent
• per-effect knobs — size, dur, count, intensity

Author fast: --dry resolves every selector against the live page in <1s ([ok]/[MISS] per step, no recording) — fix misses, record once. --pace fast trims holds ~45% for drafts. --contact-sheet writes a tile of ~24 frames so the take reviews itself.

See each one

Every feature, demonstrated — each image generated by the plugin against the demo page.

prove — annotated proof	camera — viewport move	marks — sub-badges
modal — narration	bars — top/bottom context	spotlight — dim all but target
speed — per-step slow-mo	auto-annotate — free outline	stamp — step counter
fill — typed input	select — dropdown pick	inset — magnifier loupe
glossary — badge legend panel	hide — drop an element	glide — animated scroll
compose — before/after (motion)	tape — terminal capture	compose — before/after (static)

Live elements & state — a panel that grows in place, plus the full motion/state kit:

live — append rows in place	confetti — celebrate a success	countup — roll a number up
sparkline — draw a trend	progress — rollout bar	countdown — ticking pre-action
pulse — attention ring	ripple — tap feedback	glow — active emphasis
checkmark — stage done	reveal — new content enters	flash — status blink
orbit — working spinner	trail — A→B connector	shake — blocked/error
typeon — streaming text	kenburns — slow zoom	redact — hide sensitive data
highlight — marker swipe

Annotation primitives (demo.mjs)

Eight callout styles, one concept per image — all eight from a single demo --batch launch:

rect	circle	arrow	badge
blur	zoom	callout	label

Why it's fast

Measured on this codebase (Apple Silicon, warm motor):

How it works

The agent sends selectors + text. The motor (self-contained Chromium in scripts/.deps/) measures the DOM, places every annotation deterministically (lib/autoplace.mjs), and self-validates (vcheck) before saving — so there's no guess/retry loop. Web captures run through Chromium; terminal captures through vhs. rec.mjs is modular: single-responsibility modules (rec-steps, cam-inject, rec-camera, rec-motion, rec-annotate, rec-input, rec-encode, rec-page) over one clock that makes realtime and offline two implementations of the same time contract.

Requirements

node 18+. Optional: ffmpeg (best GIF quality), vhs (terminal recordings). No git, no tokens, nothing to configure. preflight.sh prints exact setup commands for anything missing. Full matrix in INSTALL.md, version history in CHANGELOG.md.

Tests

cd showreel && node --test 'scripts/__tests__/*.test.mjs'   # no network or browser

License

MIT