Loading plugin...

showreel · Flowy

README

1

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

a capture wrapped in a browser-window frame

What it can do

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

Capability	Script	What you get
Auto (URL only)	`auto.mjs`	Discovers the salient elements itself — heading, primary action, nav, hero, metrics, cards — role-based notes, same `vcheck` gate. One launch; writes PNGs + `index.json`. No selectors. `--max N`.
Annotated proof	`prove.mjs`	DOM-exact rectangle + callout + arrow, pixel-verified (`vcheck`) — exits 0 only on PASS. Flags: `--circle`, `--blur "<sel>"`, `--zoom`, `--batch jobs.json`.
Annotation primitives	`demo.mjs`	One concept per image: `rect`, `circle`, `arrow`, `badge`, `blur`, `zoom`, `callout`, `label`. `--batch` = 8 captures in one launch.
Flow recording	`rec.mjs`	Narrated GIF/MP4 from JSON steps — cursor motion, ripples, scrolling, narration modals, step stamps. The hero GIF above is one call.
Viewport camera	`rec.mjs`	Real viewport move that keeps a longer flow legible: page glides + scales under an animated transform. `camera` frames an element, `follow` chases the cursor, `inset` is a magnifier loupe.
Spotlight / slow-mo / auto-annotate	`rec.mjs`	`spotlight` dims all but the target; per-step `speed` slows an animation; `--auto-annotate` outlines a bare `click`/`fill` for free.
Live elements	`rec.mjs`	A `glossary`/`modal` with an `id` becomes live — later `live` steps append/update/recolor/replace/remove rows in place, no rebuild, no blink. Per-item colors, theme-matched text.
Offline render	`rec.mjs --offline`	Renders on the page's virtual clock — reading dwells collapse, text-heavy takes finish in a fraction of the time. Best for static/text takes; motion bursts (, ) require a realtime take.

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

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

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):

	Naive	Showreel
8 annotated captures	8 browser launches ≈ 60 s	`demo --batch` ≈ 6 s, one launch
Annotation placement	read PNG → guess pixels → retry	deterministic `autoplace`, 0 retries
Contrast on dark/light pages	manual color picking	adaptive from page luminance
Overlapping annotations	manual nudging	collision-aware, never covers the target

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

File tree

160

HeyRenan/showreelView on GitHub ↗

.claude-plugin/
  marketplace.json
.github/
  workflows/
    ci.yml
.gitignore
assets/
assets-src/
  build-assets.mjs
  build-composites.sh
  build-showcase.sh
  demo/
    index.html
    overview.html
    theme.css
  primitives-jobs.json
  roster.json
  showcase-steps.json
  auto-action.png
  auto-annotate.gif
  auto-form.png
  auto-hero.png
  auto-metric.png
  bars.gif
  beautify.png
  camera.gif
  checkmark.gif
  compose-motion.gif
  compose.png
  confetti.gif
  countdown.gif
  countup.gif
  fill.gif
  flash.gif
  glide.gif
  glossary.gif
  glow.gif
  hide.gif
  highlight.gif
  inset.gif
  kenburns.gif
  live.gif
  marks.gif
  modal.gif
  orbit.gif
  primitives/
    p1-rect.png
    p2-circle.png
    p3-arrow.png
    p4-badge.png
    p5-blur.png
    p6-zoom.png
    p7-callout.png
    p8-label.png
  progress.gif
  prove.png
  pulse.gif
  redact.gif
  reveal.gif
  ripple.gif
  select.gif
  shake.gif
  showcase.gif
  showcase.mp4
  sparkline.gif
  speed.gif
  spotlight.gif
  stamp.gif
  terminal.gif
  trail.gif
  typeon.gif
CHANGELOG.md
INSTALL.md
LICENSE
README.md
README.pt-BR.md
showreel/
  .claude-plugin/
    plugin.json
  GUIDE.html
  lib/
    autoplace.mjs
    browser.mjs
  scripts/
    __tests__/
      annotate-core.test.mjs
      annotate-edge.test.mjs
      auto.test.mjs
      autoplace.test.mjs
      beautify.test.mjs
      build-inject.test.mjs
      cli-args.test.mjs
      cli-circle-dry.test.mjs
      cli-parse.test.mjs
      clock.test.mjs
      compose-edge.test.mjs
      compose-gif.test.mjs
      compose-video.test.mjs
      dataurl-to-png.test.mjs
      demo-camera-edge.test.mjs
      demo-parse.test.mjs
      edge-cases.test.mjs
      emit-modules-edge.test.mjs
      ensure-deps-edge.test.mjs
      halo-no-bleed.test.mjs
      highlight-no-bleed.test.mjs
      integration-render.test.mjs
      live-validate.test.mjs
      pngread.test.mjs
      presets.test.mjs
      progress-lane.test.mjs
      progress-renders.test.mjs
      prove-annotations.test.mjs
      prove-circle-dominance.test.mjs
      prove-summary.test.mjs
      prove-verdict.test.mjs
      prove.test.mjs
      rec-live.test.mjs
      rec-page-edge.test.mjs
      rec-steps.test.mjs
      shrink.test.mjs
      spotlight-note-contrast.test.mjs
      tape.test.mjs
    annotate-canvas.js
    annotate.mjs
    audit-roster.mjs
    auto-rank.mjs
    auto.mjs
    beautify-frame.mjs
    beautify.mjs
    before-after.mjs
    build-inject.mjs
    cam-inject.js
    capture.mjs
    cli-args.mjs
    clock.mjs
    compose-video.mjs
    compose.mjs
    cursor-inject.mjs
    dataurl-to-png.mjs
    demo.mjs
    drive-recipe.md
    end-card-inject.mjs
    ensure-deps.mjs
    gif.sh
    lh-ba.sh
    pngread.mjs
    preflight.sh
    presets/
      dashboard.json
      form-flow.json
      nav-flow.json
      README.md
    prove.mjs
    rec-annotate.mjs
    rec-camera.mjs
    rec-encode.mjs
    rec-input.mjs
    rec-live.mjs
    rec-motion.mjs
    rec-page.mjs
    rec-steps.mjs
    rec.mjs
    shot.mjs
    shrink.mjs
    tape.mjs
    webm-to-gif.sh
  skills/
    guide/
      SKILL.md
    showreel/
      references/
        cinematic-grammar.md
        motion-design.md
        rec-cookbook.md
        visual-system.md
      SKILL.md