diff --git a/.gitignore b/.gitignore
index 74abca3d..fe2cf8f4 100644
--- a/.gitignore
+++ b/.gitignore
@@ -55,6 +55,9 @@ screenshots/
 # Local screenshot scratch folder (capture-steam-interval.ts output)
 screenshot-review/
 
+# Raw screencast frames + intermediate encodes (capture-videos.ts scratch).
+videos/
+
 # background-agent git worktrees — never track
 .worktrees/
 
diff --git a/README.md b/README.md
index fc0051c1..87c21861 100644
--- a/README.md
+++ b/README.md
@@ -13,12 +13,22 @@ N64 classic — without leaving your game. It runs as an **in-game overlay** in
 Steam's Gaming Mode and as a **standalone app** on the desktop, detecting which
 mode you're in and adapting automatically.
 
-[**Install →**](#install) · [Featured plugins](#featured-plugins) · [All plugins](#all-plugins) · [Supported devices](#supported-devices--testing) · [Docs](#documentation)
+[**Install →**](#install) · [See it in action](#see-it-in-action) · [Featured plugins](#featured-plugins) · [All plugins](#all-plugins) · [Supported devices](#supported-devices--testing) · [Docs](#documentation)
 
 > 🚧 **Pre-launch.** Daily-driven on OneXPlayer devices and tested on Valve's
 > Steam Deck. I'm [looking for testers](#supported-devices--testing) on other
 > handhelds.
 
+## See it in action
+
+Set your power limit without leaving your game — TDP presets and a live slider,
+right in the overlay:
+
+![Loadout — TDP control in the overlay](plugins/tdp-control/assets/demo.webp)
+
+<sub>Clips are captured straight from the running overlay — see
+[docs/media-capture.md](docs/media-capture.md).</sub>
+
 ## Install
 
 One command. It downloads the prebuilt binary and overlay, verifies SHA-256,
@@ -271,6 +281,7 @@ before trusting a change). Full dev/build/test loop:
 | [Gamepad Navigation](docs/gamepad-navigation-guide.md)       | Spatial navigation, focus management                    |
 | [OS Compatibility](docs/os-compatibility.md)                 | SteamOS, Bazzite, CachyOS specifics                     |
 | [Releasing](docs/releasing.md)                               | Versioning policy + how releases are cut                |
+| [Media Capture](docs/media-capture.md)                       | Capturing overlay screenshots + video clips             |
 
 See [CHANGELOG.md](CHANGELOG.md) for the release history.
 
diff --git a/docs/media-capture.md b/docs/media-capture.md
new file mode 100644
index 00000000..b6f12224
--- /dev/null
+++ b/docs/media-capture.md
@@ -0,0 +1,177 @@
+# Media capture — screenshots & video clips
+
+Loadout's README and per-plugin pages are illustrated with media captured
+straight from the **running overlay** over its CEF DevTools endpoint
+(`http://localhost:9222` in dev). Two scripts drive the same overlay the same
+way — they share the CDP + navigation + recipe machinery in
+[`scripts/lib/overlay-cdp.ts`](../scripts/lib/overlay-cdp.ts):
+
+| Script                           | Output                            | Written to                                            |
+| -------------------------------- | --------------------------------- | ----------------------------------------------------- |
+| `scripts/capture-screenshots.ts` | PNG stills (tracked)              | `plugins/<id>/assets/screenshot*.png`, `docs/assets/` |
+| `scripts/capture-videos.ts`      | animated **WebP** clips (tracked) | `plugins/<id>/assets/demo.webp`, `docs/assets/*.webp` |
+
+## Prerequisites
+
+- The overlay running in dev with DevTools exposed: `bun run dev:overlay`
+  (DevTools is baked in via `electrobun.config.ts` → `build.linux.chromiumFlags`).
+- `ffmpeg` on `PATH` — used to encode the captured frames. It's the only extra
+  dependency; the WebP/GIF/H.264 encoders it ships with are all we need.
+
+## Capturing video clips
+
+There are two capture modes, both encoding to WebP with ffmpeg:
+
+- **Per-plugin tours** (`--tours`, the default) — captioned tours defined by
+  each plugin's `tour.json`. See [Per-plugin tours](#per-plugin-tours---tours).
+- **Steam Big Picture** (`--target=steam`) — theme-loader / Store Bridge as
+  they appear in Steam's own UI. See
+  [Steam Big Picture clips](#steam-big-picture-clips---targetsteam).
+
+```sh
+bun run capture:videos --list          # list every tour + steam clip
+bun run capture:videos --format=all    # also emit GIF + MP4 alongside the WebP
+bun run capture:videos --width=1024    # lighter than the 1280 default
+bun run capture:videos --keep-frames   # leave the raw JPEG frames in videos/
+```
+
+### How it records
+
+`Page.startScreencast` streams JPEG frames as the page changes; each frame is
+timestamped on arrival. Frames only arrive on a **visual change**, so a
+deliberate `wait` hold emits no frames — its duration is preserved as the gap
+to the next frame. ffmpeg then re-encodes the frames (with their real
+per-frame durations) to a constant-rate animated WebP. Raw frames land in the
+gitignored `videos/<clip>/` scratch dir and are deleted unless `--keep-frames`.
+
+## Steam Big Picture clips (`--target=steam`)
+
+Some of the best features — theme-loader's CSS theming and Store Bridge's Epic
+collection — render in **Steam's own Big Picture UI**, not the overlay. That's a
+different CEF surface (port `8080`, discovered via
+[`@loadout/steam-cdp`](../packages/steam-cdp)), but the same screencast → ffmpeg
+pipeline applies.
+
+**Run it from Gaming Mode with Big Picture in the foreground.** CEF only rasters
+its offscreen surface while Steam is actively painting it, so a backgrounded Big
+Picture screencasts blank — the script skips a clip that captures too few
+frames and tells you why.
+
+Two clips ship (`--target=steam --list` to see them):
+
+- **`steam-theme`** — flips theme-loader's injected `<style>` elements
+  (`style[id^="theme-loader-"]`) off/on, so Big Picture visibly recolours
+  between vanilla Steam and the active theme. It's the exact mechanism
+  theme-loader uses, driven from the capture script — deterministic. **Enable a
+  theme in theme-loader first**; a precheck skips the clip otherwise.
+- **`steam-epic`** — Steam library navigation isn't reliably scriptable over
+  CDP, so this records while **you** drive to the Epic / Store Bridge collection
+  by hand, with an on-screen countdown (the same way the Big Picture stills are
+  captured today).
+
+Steam clips reuse the small `SteamStep` vocabulary (`eval` / `theme` / `manual`
+/ `wait`) in the `STEAM_CLIPS` table — extend it the same way as the overlay
+clips.
+
+## Per-plugin tours (`--tours`)
+
+Each plugin can ship a **`plugins/<id>/tour.json`** — a little scripted tour of
+that plugin, with **captions burned into the video**. The capture script
+discovers every plugin that has a `tour.json` (opt-in), navigates to it, records
+the beats, and writes the clip to a **review folder** for you to watch before
+anything is published:
+
+```sh
+bun run capture:videos --tours                     # all plugins with a tour.json
+bun run capture:videos --tours --plugins=tdp-control
+bun run capture:videos --promote=tdp-control,fan-control
+```
+
+- **Capture in Gaming Mode.** Run tours with the overlay open in Gaming Mode:
+  gamescope renders at 1280×800, so that's the overlay's true native scale and
+  the real end-user appearance (on the desktop the surface is upscaled to
+  1920, which inflates size for no extra detail). Tours default to
+  `--width=1280` to match; override with `--width` if you want bigger.
+- **Privacy skips.** `network-info` (MAC/SSID/IP) and `playtime` (reveals your
+  game history) are never toured, via `TOUR_SKIP` **and** the opt-in model
+  (no `tour.json` → no tour). Be mindful that other plugins may still show
+  library art (e.g. TDP's per-game profiles).
+- **Review → promote.** `--tours` writes to `videos/review/<id>.webp` (the
+  `videos/` scratch dir is gitignored). After you've watched them,
+  `--promote=<id,…>` copies the approved clips into
+  `plugins/<id>/assets/demo.webp` and inserts a `## Demo` section into each
+  plugin README (idempotent). The promoted asset is a normal tracked file —
+  commit it once you're happy with the clip.
+
+### `tour.json` schema
+
+```jsonc
+{
+  "title": "TDP Control · power tuning", // optional intro caption
+  "fps": 15, // optional (per-tour)
+  "tailMs": 900, // optional final-frame hold
+  "steps": [
+    { "kind": "wait", "ms": 1300 },
+    { "kind": "text", "label": "Silent", "caption": "Quiet & cool for the couch" },
+    { "kind": "aria", "label": "Custom device settings", "caption": "Add an unlisted device" },
+    { "kind": "aria", "label": "Back to TDP Control" },
+  ],
+}
+```
+
+`steps` reuse the overlay `Step` vocabulary (`wait` / `nav` / `sidebar` /
+`tile` / `aria` / `text`); the script auto-navigates to `#/plugin/<id>` first,
+so steps describe in-plugin beats only. Any step (or the `title`) may carry a
+`caption`, which shows from when that step fires until the next caption — mapped
+onto the encoded timeline via the real frame durations, then drawn as a
+lower-third with ffmpeg `drawtext` (into every output format).
+
+## Why WebP for the README
+
+GitHub-flavoured markdown renders repo-relative images (`![](…)`) and an
+**animated WebP autoplays and loops inline**, exactly like a GIF but at a
+fraction of the size. That makes committed WebP the one format that is both
+self-contained (lives in the repo, versioned next to the code) _and_
+inline-animated. The alternatives don't fit:
+
+- **GIF** — also inline-animated, but 3–5× larger, and it balloons on
+  photographic content (game box art) where its 256-colour palette struggles.
+- **MP4 / WebM** — smallest and highest-quality, but a repo-relative
+  `<video>`/`<source>` does **not** render on github.com. Only GitHub's own
+  `user-images.githubusercontent.com` URLs (created by drag-dropping a file
+  into an issue/PR) play inline — those aren't in the repo, aren't scriptable,
+  and aren't versioned, which breaks the deterministic-assets pattern the rest
+  of the media pipeline follows.
+
+Rough format comparison for a ~5 s flat-UI clip (WebP q55):
+
+| Format      | Size                           | Inline on GitHub?         |
+| ----------- | ------------------------------ | ------------------------- |
+| WebP (q55)  | small                          | ✅ `![](…)`               |
+| GIF         | 3–5× the WebP → many MB on art | ✅ `![](…)`               |
+| MP4 (H.264) | ~10× smaller than WebP         | ❌ repo path won't render |
+
+### Resolution & file-size guidance
+
+Clips capture at the handheld's native width (`--width=1280` by default) so UI
+text stays legible; drop `--width` (e.g. `--width=960`) for lighter README
+files at the cost of sharpness. WebP encodes each frame near-independently, so
+**resolution and frame count both drive size**, and **photographic content is
+expensive**:
+
+- Flat UI (dashboards, controls, sidebar) compresses beautifully — keep those
+  for hero/tour clips.
+- Game-art grids and hero art are gorgeous but heavy; keep those clips short
+  and per-plugin rather than dwelling on them in the tour.
+- Longer / higher-res clips can drop to 12–15 fps via a per-clip `fps` (or the
+  `--fps=` flag) — the eye tolerates it for UI motion and it cuts size roughly
+  proportionally.
+
+## Embedding
+
+- **Root README** — the hand-written
+  [`See it in action`](../README.md#see-it-in-action) section embeds a hero
+  clip (currently `plugins/tdp-control/assets/demo.webp`).
+- **Per-plugin README** — `--promote` inserts a `## Demo` section, and
+  `scripts/scaffold-plugin-readmes.ts` renders one for any plugin that has an
+  `assets/demo.webp`. Either way, capture the tour and the README picks it up.
diff --git a/package.json b/package.json
index b7b66d32..c57f3a17 100644
--- a/package.json
+++ b/package.json
@@ -47,6 +47,8 @@
     "test:coverage": "bun test test.ts --isolate --coverage --coverage-dir=coverage/backend && bun test spec.tsx --preload ./test/bun-test-setup.ts --isolate --coverage --coverage-dir=coverage/ui",
     "lint": "eslint .",
     "lint:fix": "eslint . --fix",
+    "capture:screenshots": "bun run scripts/capture-screenshots.ts",
+    "capture:videos": "bun run scripts/capture-videos.ts",
     "check:specs": "sh scripts/check-plugin-specs.sh",
     "format": "prettier --write .",
     "format:check": "prettier --check ."
diff --git a/plugins/apex/README.md b/plugins/apex/README.md
index 2ad0048c..992566f5 100644
--- a/plugins/apex/README.md
+++ b/plugins/apex/README.md
@@ -2,6 +2,10 @@
 
 > OneXPlayer Apex device fixes: recover the internal gamepad when its xHCI controller dies on resume (or blacklist the hid-oxp driver to prevent the drop-out), and block the fingerprint reader from waking the device on a light touch.
 
+## Demo
+
+![Apex demo](./assets/demo.webp)
+
 ## Screenshots
 
 ![Apex](./assets/screenshot.png)
diff --git a/plugins/apex/assets/demo.webp b/plugins/apex/assets/demo.webp
new file mode 100644
index 00000000..002dab77
Binary files /dev/null and b/plugins/apex/assets/demo.webp differ
diff --git a/plugins/apex/tour.json b/plugins/apex/tour.json
new file mode 100644
index 00000000..7a556ec8
--- /dev/null
+++ b/plugins/apex/tour.json
@@ -0,0 +1,37 @@
+{
+  "title": "Apex · gamepad recovery",
+  "fps": 15,
+  "width": 1024,
+  "tailMs": 900,
+  "steps": [
+    {
+      "kind": "wait",
+      "ms": 1200
+    },
+    {
+      "kind": "wait",
+      "ms": 1400,
+      "caption": "Gamepad dies on wake?"
+    },
+    {
+      "kind": "text",
+      "label": "Recover",
+      "caption": "One tap to revive it"
+    },
+    {
+      "kind": "wait",
+      "ms": 1600,
+      "caption": "Safe if already working"
+    },
+    {
+      "kind": "wait",
+      "ms": 1400,
+      "caption": "Or auto-fix every wake"
+    },
+    {
+      "kind": "wait",
+      "ms": 1300,
+      "caption": "Block fingerprint wake too"
+    }
+  ]
+}
diff --git a/plugins/battery-tracker/README.md b/plugins/battery-tracker/README.md
index cbe5a9be..50b8833a 100644
--- a/plugins/battery-tracker/README.md
+++ b/plugins/battery-tracker/README.md
@@ -4,6 +4,10 @@
 
 Keeps an eye on your battery while you play — current charge, how fast it's draining or charging, estimated time left, and a short history of the session. On a handheld it answers the question that matters: will I reach a save point before I need the charger?
 
+## Demo
+
+![Battery Tracker demo](./assets/demo.webp)
+
 ## Screenshots
 
 ![Battery Tracker](./assets/screenshot.png)
diff --git a/plugins/battery-tracker/assets/demo.webp b/plugins/battery-tracker/assets/demo.webp
new file mode 100644
index 00000000..ed674b41
Binary files /dev/null and b/plugins/battery-tracker/assets/demo.webp differ
diff --git a/plugins/battery-tracker/tour.json b/plugins/battery-tracker/tour.json
new file mode 100644
index 00000000..a0c01f68
--- /dev/null
+++ b/plugins/battery-tracker/tour.json
@@ -0,0 +1,32 @@
+{
+  "title": "Battery · real-time power monitoring",
+  "fps": 15,
+  "tailMs": 900,
+  "steps": [
+    {
+      "kind": "wait",
+      "ms": 1300,
+      "caption": "See charge in real time"
+    },
+    {
+      "kind": "wait",
+      "ms": 1500,
+      "caption": "Watts, volts, amps live"
+    },
+    {
+      "kind": "wait",
+      "ms": 1400,
+      "caption": "Track battery wear"
+    },
+    {
+      "kind": "text",
+      "label": "Refresh",
+      "caption": "Update the readings"
+    },
+    {
+      "kind": "wait",
+      "ms": 1100,
+      "caption": "30-minute drain history"
+    }
+  ]
+}
diff --git a/plugins/disable-controller-input/README.md b/plugins/disable-controller-input/README.md
index 5a5786bf..3aad3f68 100644
--- a/plugins/disable-controller-input/README.md
+++ b/plugins/disable-controller-input/README.md
@@ -4,6 +4,10 @@
 
 Mutes a specific controller by asking InputPlumber to drop its virtual inputs — the fix for handhelds where the built-in gamepad steals player 1 from the controller you actually want to use. Toggle a pad off without unpairing or unplugging it.
 
+## Demo
+
+![Disable Controller Input demo](./assets/demo.webp)
+
 ## Screenshots
 
 ![Disable Controller Input](./assets/screenshot.png)
diff --git a/plugins/disable-controller-input/assets/demo.webp b/plugins/disable-controller-input/assets/demo.webp
new file mode 100644
index 00000000..f82cfb70
Binary files /dev/null and b/plugins/disable-controller-input/assets/demo.webp differ
diff --git a/plugins/disable-controller-input/tour.json b/plugins/disable-controller-input/tour.json
new file mode 100644
index 00000000..a966d730
--- /dev/null
+++ b/plugins/disable-controller-input/tour.json
@@ -0,0 +1,32 @@
+{
+  "title": "Disable Controller Input · silence rogue pads",
+  "fps": 15,
+  "tailMs": 900,
+  "steps": [
+    {
+      "kind": "wait",
+      "ms": 1300,
+      "caption": "Fix player-one conflicts"
+    },
+    {
+      "kind": "wait",
+      "ms": 1500,
+      "caption": "See every connected pad"
+    },
+    {
+      "kind": "text",
+      "label": "Refresh",
+      "caption": "Rescan controllers live"
+    },
+    {
+      "kind": "wait",
+      "ms": 1400,
+      "caption": "Silence with one toggle"
+    },
+    {
+      "kind": "wait",
+      "ms": 1100,
+      "caption": "Stays hidden from games"
+    }
+  ]
+}
diff --git a/plugins/fan-control/README.md b/plugins/fan-control/README.md
index aeceaa04..33a09a73 100644
--- a/plugins/fan-control/README.md
+++ b/plugins/fan-control/README.md
@@ -6,6 +6,10 @@ Monitor temperatures and fan speed and apply fan-curve presets, trading noise fo
 
 Beyond the built-in Silent / Balanced / Performance presets you can draw your own **custom fan curve**: a graph editor maps temperature (°C) to fan duty (%). Drag the points on the graph, or select a point and nudge it with the sliders — handy on a gamepad. The curve runs on the same 2 s evaluation loop as the presets, and the hardware safety floor still overrides it as temperatures climb toward thermal-trip range.
 
+## Demo
+
+![Fan Control demo](./assets/demo.webp)
+
 ## Screenshots
 
 ![Fan Control](./assets/screenshot.png)
diff --git a/plugins/fan-control/assets/demo.webp b/plugins/fan-control/assets/demo.webp
new file mode 100644
index 00000000..213af6fd
Binary files /dev/null and b/plugins/fan-control/assets/demo.webp differ
diff --git a/plugins/fan-control/tour.json b/plugins/fan-control/tour.json
new file mode 100644
index 00000000..46b11bee
--- /dev/null
+++ b/plugins/fan-control/tour.json
@@ -0,0 +1,40 @@
+{
+  "title": "Fan Control · tune your cooling",
+  "fps": 15,
+  "tailMs": 900,
+  "steps": [
+    {
+      "kind": "wait",
+      "ms": 1500,
+      "caption": "Live fan RPM & temps"
+    },
+    {
+      "kind": "text",
+      "label": "Manual",
+      "caption": "Take manual control"
+    },
+    {
+      "kind": "wait",
+      "ms": 1000
+    },
+    {
+      "kind": "text",
+      "label": "Performance",
+      "caption": "Quick cooling presets"
+    },
+    {
+      "kind": "wait",
+      "ms": 1000
+    },
+    {
+      "kind": "text",
+      "label": "Custom",
+      "caption": "Or design your own"
+    },
+    {
+      "kind": "wait",
+      "ms": 1700,
+      "caption": "Draw a fan curve"
+    }
+  ]
+}
diff --git a/plugins/flatpak-manager/README.md b/plugins/flatpak-manager/README.md
index 722356f8..1fdb434e 100644
--- a/plugins/flatpak-manager/README.md
+++ b/plugins/flatpak-manager/README.md
@@ -4,6 +4,10 @@
 
 List and update your installed Flatpak apps without dropping to the desktop, so emulators and launchers stay current from inside Gaming Mode.
 
+## Demo
+
+![Flatpak Manager demo](./assets/demo.webp)
+
 ## Screenshots
 
 ![Flatpak Manager](./assets/screenshot.png)
diff --git a/plugins/flatpak-manager/assets/demo.webp b/plugins/flatpak-manager/assets/demo.webp
new file mode 100644
index 00000000..1c2e1ebf
Binary files /dev/null and b/plugins/flatpak-manager/assets/demo.webp differ
diff --git a/plugins/flatpak-manager/tour.json b/plugins/flatpak-manager/tour.json
new file mode 100644
index 00000000..e7410ee1
--- /dev/null
+++ b/plugins/flatpak-manager/tour.json
@@ -0,0 +1,37 @@
+{
+  "title": "Flatpak · manage & update your apps",
+  "fps": 15,
+  "tailMs": 900,
+  "steps": [
+    {
+      "kind": "wait",
+      "ms": 1500,
+      "caption": "Every Flatpak app"
+    },
+    {
+      "kind": "text",
+      "label": "Updates",
+      "caption": "See what's outdated"
+    },
+    {
+      "kind": "wait",
+      "ms": 900,
+      "caption": "Updates at a glance"
+    },
+    {
+      "kind": "text",
+      "label": "Installed",
+      "caption": "Back to your apps"
+    },
+    {
+      "kind": "aria",
+      "label": "Refresh",
+      "caption": "One-tap refresh"
+    },
+    {
+      "kind": "wait",
+      "ms": 1200,
+      "caption": "Always up to date"
+    }
+  ]
+}
diff --git a/plugins/hltb/README.md b/plugins/hltb/README.md
index 7d41783c..2969d0a3 100644
--- a/plugins/hltb/README.md
+++ b/plugins/hltb/README.md
@@ -4,6 +4,10 @@
 
 Pulls HowLongToBeat completion times into Steam's library and store pages, so you can see at a glance how long a game takes to finish and pick something that fits the time you have.
 
+## Demo
+
+![HLTB demo](./assets/demo.webp)
+
 ## Screenshots
 
 ### Overview
diff --git a/plugins/hltb/assets/demo.webp b/plugins/hltb/assets/demo.webp
new file mode 100644
index 00000000..bf1d948e
Binary files /dev/null and b/plugins/hltb/assets/demo.webp differ
diff --git a/plugins/hltb/tour.json b/plugins/hltb/tour.json
new file mode 100644
index 00000000..bfc2171f
--- /dev/null
+++ b/plugins/hltb/tour.json
@@ -0,0 +1,35 @@
+{
+  "title": "How Long to Beat · completion times",
+  "fps": 10,
+  "width": 560,
+  "tailMs": 900,
+  "steps": [
+    {
+      "kind": "wait",
+      "ms": 1500,
+      "caption": "How long to beat?"
+    },
+    {
+      "kind": "wait",
+      "ms": 1500,
+      "caption": "Times across your library"
+    },
+    {
+      "kind": "tile",
+      "caption": "Open the full breakdown"
+    },
+    {
+      "kind": "wait",
+      "ms": 2000,
+      "caption": "Story, extras, 100%"
+    },
+    {
+      "kind": "aria",
+      "label": "Back to library"
+    },
+    {
+      "kind": "wait",
+      "ms": 800
+    }
+  ]
+}
diff --git a/plugins/input-plumber/README.md b/plugins/input-plumber/README.md
index b9da1072..e7fe6c2d 100644
--- a/plugins/input-plumber/README.md
+++ b/plugins/input-plumber/README.md
@@ -4,6 +4,10 @@
 
 Installs the InputPlumber input-routing daemon that other controller features rely on, and quietly does nothing if it's already present. Mostly a one-time setup helper so the rest 'just works'.
 
+## Demo
+
+![InputPlumber demo](./assets/demo.webp)
+
 ## Screenshots
 
 ![InputPlumber](./assets/screenshot.png)
diff --git a/plugins/input-plumber/assets/demo.webp b/plugins/input-plumber/assets/demo.webp
new file mode 100644
index 00000000..477d7ffa
Binary files /dev/null and b/plugins/input-plumber/assets/demo.webp differ
diff --git a/plugins/input-plumber/tour.json b/plugins/input-plumber/tour.json
new file mode 100644
index 00000000..62440b9d
--- /dev/null
+++ b/plugins/input-plumber/tour.json
@@ -0,0 +1,32 @@
+{
+  "title": "InputPlumber · controller routing",
+  "fps": 15,
+  "width": 1024,
+  "tailMs": 900,
+  "steps": [
+    {
+      "kind": "wait",
+      "ms": 1200
+    },
+    {
+      "kind": "wait",
+      "ms": 1600,
+      "caption": "Input routing for handhelds"
+    },
+    {
+      "kind": "wait",
+      "ms": 1700,
+      "caption": "Bind a physical wake button"
+    },
+    {
+      "kind": "wait",
+      "ms": 1600,
+      "caption": "Opens the overlay in-game"
+    },
+    {
+      "kind": "wait",
+      "ms": 1400,
+      "caption": "Restart to revive a pad"
+    }
+  ]
+}
diff --git a/plugins/launch-options/README.md b/plugins/launch-options/README.md
index 0317df22..40a7900d 100644
--- a/plugins/launch-options/README.md
+++ b/plugins/launch-options/README.md
@@ -4,6 +4,10 @@
 
 Edit Steam launch options per game and save reusable presets, turning common flags and environment variables into a couple of clicks instead of typed-out strings — great for applying the same tweak across many games.
 
+## Demo
+
+![Launch Options demo](./assets/demo.webp)
+
 ## Screenshots
 
 ### Overview
diff --git a/plugins/launch-options/assets/demo.webp b/plugins/launch-options/assets/demo.webp
new file mode 100644
index 00000000..27bdbfda
Binary files /dev/null and b/plugins/launch-options/assets/demo.webp differ
diff --git a/plugins/launch-options/tour.json b/plugins/launch-options/tour.json
new file mode 100644
index 00000000..6b98e1fb
--- /dev/null
+++ b/plugins/launch-options/tour.json
@@ -0,0 +1,40 @@
+{
+  "title": "Launch Options · per-game launch tweaks",
+  "fps": 13,
+  "width": 860,
+  "tailMs": 900,
+  "steps": [
+    {
+      "kind": "wait",
+      "ms": 1500,
+      "caption": "Tune game launch options"
+    },
+    {
+      "kind": "aria",
+      "label": "Manage presets",
+      "caption": "Save reusable presets"
+    },
+    {
+      "kind": "wait",
+      "ms": 1400,
+      "caption": "mangohud, gamemoderun…"
+    },
+    {
+      "kind": "aria",
+      "label": "Back to library"
+    },
+    {
+      "kind": "wait",
+      "ms": 700
+    },
+    {
+      "kind": "tile",
+      "caption": "Open any game"
+    },
+    {
+      "kind": "wait",
+      "ms": 1500,
+      "caption": "Set its launch command"
+    }
+  ]
+}
diff --git a/plugins/lsfg-vk/README.md b/plugins/lsfg-vk/README.md
index 347bd683..a731e3fa 100644
--- a/plugins/lsfg-vk/README.md
+++ b/plugins/lsfg-vk/README.md
@@ -13,6 +13,10 @@ work without it. The plugin downloads the open-source
 [`lsfg-vk`](https://github.com/PancakeTAS/lsfg-vk) Vulkan layer itself, but the
 underlying frame-gen tech is not free or bundled.
 
+## Demo
+
+![LSFG-VK demo](./assets/demo.webp)
+
 ## Screenshots
 
 ![LSFG-VK](./assets/screenshot.png)
diff --git a/plugins/lsfg-vk/assets/demo.webp b/plugins/lsfg-vk/assets/demo.webp
new file mode 100644
index 00000000..8e4a318f
Binary files /dev/null and b/plugins/lsfg-vk/assets/demo.webp differ
diff --git a/plugins/lsfg-vk/tour.json b/plugins/lsfg-vk/tour.json
new file mode 100644
index 00000000..dc20cb9c
--- /dev/null
+++ b/plugins/lsfg-vk/tour.json
@@ -0,0 +1,33 @@
+{
+  "title": "LSFG-VK · boost your frame rate",
+  "fps": 13,
+  "width": 820,
+  "tailMs": 900,
+  "steps": [
+    {
+      "kind": "wait",
+      "ms": 1400,
+      "caption": "Frame generation per game"
+    },
+    {
+      "kind": "aria",
+      "label": "Plugin preferences",
+      "caption": "Open plugin settings"
+    },
+    {
+      "kind": "wait",
+      "ms": 1500,
+      "caption": "Install and tune LSFG"
+    },
+    {
+      "kind": "aria",
+      "label": "Back to library",
+      "caption": "Back to your games"
+    },
+    {
+      "kind": "wait",
+      "ms": 1200,
+      "caption": "Apply with one tap"
+    }
+  ]
+}
diff --git a/plugins/protondb-badges/README.md b/plugins/protondb-badges/README.md
index 755363d0..3833b14b 100644
--- a/plugins/protondb-badges/README.md
+++ b/plugins/protondb-badges/README.md
@@ -4,6 +4,10 @@
 
 Adds ProtonDB compatibility ratings to your Steam library — a tier badge on every game tile plus per-game detail in the home widget — so you know whether something is likely to run well on Linux/Proton before you install it.
 
+## Demo
+
+![ProtonDB Badges demo](./assets/demo.webp)
+
 ## Screenshots
 
 ### Plugin
diff --git a/plugins/protondb-badges/assets/demo.webp b/plugins/protondb-badges/assets/demo.webp
new file mode 100644
index 00000000..95c39f33
Binary files /dev/null and b/plugins/protondb-badges/assets/demo.webp differ
diff --git a/plugins/protondb-badges/tour.json b/plugins/protondb-badges/tour.json
new file mode 100644
index 00000000..64f59d30
--- /dev/null
+++ b/plugins/protondb-badges/tour.json
@@ -0,0 +1,36 @@
+{
+  "title": "ProtonDB · Steam compatibility at a glance",
+  "fps": 10,
+  "width": 560,
+  "tailMs": 900,
+  "steps": [
+    {
+      "kind": "wait",
+      "ms": 1500,
+      "caption": "Your library, Proton-rated"
+    },
+    {
+      "kind": "wait",
+      "ms": 1400,
+      "caption": "A tier badge per game"
+    },
+    {
+      "kind": "aria",
+      "label": "Plugin preferences",
+      "caption": "See your breakdown"
+    },
+    {
+      "kind": "wait",
+      "ms": 1800,
+      "caption": "Platinum to Borked, counted"
+    },
+    {
+      "kind": "aria",
+      "label": "Back to library"
+    },
+    {
+      "kind": "wait",
+      "ms": 800
+    }
+  ]
+}
diff --git a/plugins/quick-links/README.md b/plugins/quick-links/README.md
index b270351a..337a2102 100644
--- a/plugins/quick-links/README.md
+++ b/plugins/quick-links/README.md
@@ -13,6 +13,10 @@ User-added templates and per-game pins / custom links live in
 plugin storage; built-ins ship in `DEFAULT_TEMPLATES` and re-seed
 on every `onLoad()` so version bumps add new sites for free.
 
+## Demo
+
+![Quick Links demo](./assets/demo.webp)
+
 ## Screenshots
 
 ![Quick Links](./assets/screenshot.png)
diff --git a/plugins/quick-links/assets/demo.webp b/plugins/quick-links/assets/demo.webp
new file mode 100644
index 00000000..8fea47a9
Binary files /dev/null and b/plugins/quick-links/assets/demo.webp differ
diff --git a/plugins/quick-links/tour.json b/plugins/quick-links/tour.json
new file mode 100644
index 00000000..ee65dda1
--- /dev/null
+++ b/plugins/quick-links/tour.json
@@ -0,0 +1,36 @@
+{
+  "title": "Quick Links · one launcher for every site",
+  "fps": 15,
+  "width": 1024,
+  "tailMs": 900,
+  "steps": [
+    {
+      "kind": "wait",
+      "ms": 1500,
+      "caption": "Contextual links per game"
+    },
+    {
+      "kind": "aria",
+      "label": "Quick Links settings",
+      "caption": "Open the link catalog"
+    },
+    {
+      "kind": "wait",
+      "ms": 1700,
+      "caption": "YouTube, ProtonDB, HLTB…"
+    },
+    {
+      "kind": "wait",
+      "ms": 1200,
+      "caption": "Add your own"
+    },
+    {
+      "kind": "aria",
+      "label": "Back to Quick Links"
+    },
+    {
+      "kind": "wait",
+      "ms": 800
+    }
+  ]
+}
diff --git a/plugins/rgb-control/README.md b/plugins/rgb-control/README.md
index b0645b23..fd6e6d62 100644
--- a/plugins/rgb-control/README.md
+++ b/plugins/rgb-control/README.md
@@ -4,6 +4,10 @@
 
 Control the RGB lighting on Linux handhelds via OpenRGB, sysfs LEDs, and platform-specific interfaces — set colours and effects, or kill the lights to save battery, without reaching for extra desktop tools.
 
+## Demo
+
+![RGB Control demo](./assets/demo.webp)
+
 ## Screenshots
 
 ![RGB Control](./assets/screenshot.png)
diff --git a/plugins/rgb-control/assets/demo.webp b/plugins/rgb-control/assets/demo.webp
new file mode 100644
index 00000000..9485bb60
Binary files /dev/null and b/plugins/rgb-control/assets/demo.webp differ
diff --git a/plugins/rgb-control/tour.json b/plugins/rgb-control/tour.json
new file mode 100644
index 00000000..3c274c6d
--- /dev/null
+++ b/plugins/rgb-control/tour.json
@@ -0,0 +1,37 @@
+{
+  "title": "RGB Zones · light up your handheld",
+  "fps": 15,
+  "tailMs": 900,
+  "steps": [
+    {
+      "kind": "wait",
+      "ms": 1300,
+      "caption": "Control every LED zone"
+    },
+    {
+      "kind": "text",
+      "label": "Aurora",
+      "caption": "Cycle animated effects"
+    },
+    {
+      "kind": "text",
+      "label": "Static",
+      "caption": "Lock one solid color"
+    },
+    {
+      "kind": "wait",
+      "ms": 1300,
+      "caption": "Fine-tune R, G, B"
+    },
+    {
+      "kind": "text",
+      "label": "Rescan hardware",
+      "caption": "Re-detect LED devices"
+    },
+    {
+      "kind": "wait",
+      "ms": 1100,
+      "caption": "Presets and brightness too"
+    }
+  ]
+}
diff --git a/plugins/sound-loader/README.md b/plugins/sound-loader/README.md
index 985b161b..db272ed5 100644
--- a/plugins/sound-loader/README.md
+++ b/plugins/sound-loader/README.md
@@ -4,6 +4,10 @@
 
 Browse, install, and switch community UI sound packs from deckthemes.com, giving Steam's interface sounds a personal touch from inside Gaming Mode.
 
+## Demo
+
+![Sound Loader demo](./assets/demo.webp)
+
 ## Screenshots
 
 ![Sound Loader](./assets/screenshot.png)
diff --git a/plugins/sound-loader/assets/demo.webp b/plugins/sound-loader/assets/demo.webp
new file mode 100644
index 00000000..b1fdbe49
Binary files /dev/null and b/plugins/sound-loader/assets/demo.webp differ
diff --git a/plugins/sound-loader/tour.json b/plugins/sound-loader/tour.json
new file mode 100644
index 00000000..87ca41be
--- /dev/null
+++ b/plugins/sound-loader/tour.json
@@ -0,0 +1,38 @@
+{
+  "title": "Sound Loader · custom UI sound packs",
+  "fps": 13,
+  "width": 900,
+  "tailMs": 900,
+  "steps": [
+    {
+      "kind": "wait",
+      "ms": 1500,
+      "caption": "Custom UI sounds"
+    },
+    {
+      "kind": "text",
+      "label": "Synthesized",
+      "caption": "Switch sound modes"
+    },
+    {
+      "kind": "wait",
+      "ms": 800,
+      "caption": "Instant preview"
+    },
+    {
+      "kind": "text",
+      "label": "Default",
+      "caption": "Steam or synth"
+    },
+    {
+      "kind": "text",
+      "label": "Community",
+      "caption": "Browse DeckThemes"
+    },
+    {
+      "kind": "wait",
+      "ms": 1800,
+      "caption": "Hundreds of packs"
+    }
+  ]
+}
diff --git a/plugins/steamgriddb/README.md b/plugins/steamgriddb/README.md
index fd4cceff..5114ece5 100644
--- a/plugins/steamgriddb/README.md
+++ b/plugins/steamgriddb/README.md
@@ -4,6 +4,10 @@
 
 Browse and apply custom artwork — grids, heroes, logos, icons — from SteamGridDB. The fix for non-Steam shortcuts and any title with missing or ugly library art.
 
+## Demo
+
+![SteamGridDB demo](./assets/demo.webp)
+
 ## Screenshots
 
 ### Overview
diff --git a/plugins/steamgriddb/assets/demo.webp b/plugins/steamgriddb/assets/demo.webp
new file mode 100644
index 00000000..317a5776
Binary files /dev/null and b/plugins/steamgriddb/assets/demo.webp differ
diff --git a/plugins/steamgriddb/tour.json b/plugins/steamgriddb/tour.json
new file mode 100644
index 00000000..e1eb679f
--- /dev/null
+++ b/plugins/steamgriddb/tour.json
@@ -0,0 +1,42 @@
+{
+  "title": "SteamGridDB · custom art for every game",
+  "fps": 13,
+  "width": 820,
+  "tailMs": 900,
+  "steps": [
+    {
+      "kind": "wait",
+      "ms": 1500,
+      "caption": "Your Steam library"
+    },
+    {
+      "kind": "tile",
+      "caption": "Pick any game"
+    },
+    {
+      "kind": "wait",
+      "ms": 1800,
+      "caption": "Fresh box art"
+    },
+    {
+      "kind": "text",
+      "label": "Hero",
+      "caption": "Cinematic hero banners"
+    },
+    {
+      "kind": "wait",
+      "ms": 1200,
+      "caption": "Big splash art"
+    },
+    {
+      "kind": "text",
+      "label": "Logo",
+      "caption": "Transparent logos"
+    },
+    {
+      "kind": "wait",
+      "ms": 1000,
+      "caption": "Art in seconds"
+    }
+  ]
+}
diff --git a/plugins/storage/README.md b/plugins/storage/README.md
index 1b9ffbf2..e823cd81 100644
--- a/plugins/storage/README.md
+++ b/plugins/storage/README.md
@@ -2,6 +2,10 @@
 
 > Detect and mount a game-storage drive (e.g. a second SSD holding a Steam library) that the system stopped auto-mounting after an update, and optionally pin it in /etc/fstab so it survives future updates. Works on any device.
 
+## Demo
+
+![Storage demo](./assets/demo.webp)
+
 ## Screenshots
 
 ![Storage](./assets/screenshot.png)
diff --git a/plugins/storage/assets/demo.webp b/plugins/storage/assets/demo.webp
new file mode 100644
index 00000000..d4ba2a33
Binary files /dev/null and b/plugins/storage/assets/demo.webp differ
diff --git a/plugins/storage/tour.json b/plugins/storage/tour.json
new file mode 100644
index 00000000..3eab0b89
--- /dev/null
+++ b/plugins/storage/tour.json
@@ -0,0 +1,36 @@
+{
+  "title": "Storage · mount lost game drives",
+  "fps": 15,
+  "tailMs": 900,
+  "steps": [
+    {
+      "kind": "wait",
+      "ms": 1200
+    },
+    {
+      "kind": "wait",
+      "ms": 1300,
+      "caption": "Game drive vanished?"
+    },
+    {
+      "kind": "text",
+      "label": "Detect",
+      "caption": "Scan for unmounted drives"
+    },
+    {
+      "kind": "wait",
+      "ms": 1800,
+      "caption": "Finds your Steam library"
+    },
+    {
+      "kind": "wait",
+      "ms": 1400,
+      "caption": "Mounts where Steam looks"
+    },
+    {
+      "kind": "wait",
+      "ms": 1300,
+      "caption": "Pin it so it stays"
+    }
+  ]
+}
diff --git a/plugins/store-bridge/README.md b/plugins/store-bridge/README.md
index 9dcc08ea..fc3d95a0 100644
--- a/plugins/store-bridge/README.md
+++ b/plugins/store-bridge/README.md
@@ -4,6 +4,10 @@
 
 Surfaces non-Steam storefront libraries and adds their games to Steam as shortcuts, so they install and launch right alongside everything else. **Epic Games is supported today**; GOG, Amazon, Ubisoft, and xCloud are on the roadmap.
 
+## Demo
+
+![Store Bridge demo](./assets/demo.webp)
+
 ## Screenshots
 
 ### Available games
diff --git a/plugins/store-bridge/assets/demo.webp b/plugins/store-bridge/assets/demo.webp
new file mode 100644
index 00000000..fb707099
Binary files /dev/null and b/plugins/store-bridge/assets/demo.webp differ
diff --git a/plugins/store-bridge/tour.json b/plugins/store-bridge/tour.json
new file mode 100644
index 00000000..80fed74f
--- /dev/null
+++ b/plugins/store-bridge/tour.json
@@ -0,0 +1,40 @@
+{
+  "title": "Store Bridge · Epic games in Steam",
+  "fps": 12,
+  "width": 800,
+  "tailMs": 900,
+  "steps": [
+    {
+      "kind": "wait",
+      "ms": 1500,
+      "caption": "Epic library, in Steam"
+    },
+    {
+      "kind": "text",
+      "label": "Installed",
+      "caption": "Filter to installed"
+    },
+    {
+      "kind": "wait",
+      "ms": 1100
+    },
+    {
+      "kind": "text",
+      "label": "Library",
+      "caption": "Browse the full library"
+    },
+    {
+      "kind": "wait",
+      "ms": 1000
+    },
+    {
+      "kind": "tile",
+      "caption": "Open any game"
+    },
+    {
+      "kind": "wait",
+      "ms": 1800,
+      "caption": "Install & add to Steam"
+    }
+  ]
+}
diff --git a/plugins/tdp-control/README.md b/plugins/tdp-control/README.md
index 2c1fad1d..7e548197 100644
--- a/plugins/tdp-control/README.md
+++ b/plugins/tdp-control/README.md
@@ -4,6 +4,10 @@
 
 Set your CPU/APU power limit (TDP) with quick presets and a slider, optionally per game, to balance performance against battery life and heat — the single biggest knob for tuning a handheld.
 
+## Demo
+
+![TDP Control demo](./assets/demo.webp)
+
 ## Screenshots
 
 ### Overview
diff --git a/plugins/tdp-control/assets/demo.webp b/plugins/tdp-control/assets/demo.webp
new file mode 100644
index 00000000..161bd0da
Binary files /dev/null and b/plugins/tdp-control/assets/demo.webp differ
diff --git a/plugins/tdp-control/tour.json b/plugins/tdp-control/tour.json
new file mode 100644
index 00000000..392b3d22
--- /dev/null
+++ b/plugins/tdp-control/tour.json
@@ -0,0 +1,22 @@
+{
+  "title": "TDP Control · power tuning",
+  "fps": 15,
+  "tailMs": 900,
+  "steps": [
+    { "kind": "wait", "ms": 1300 },
+    { "kind": "text", "label": "Silent", "caption": "Quiet & cool for the couch" },
+    { "kind": "wait", "ms": 1100 },
+    { "kind": "text", "label": "Balanced", "caption": "Balanced for everyday play" },
+    { "kind": "wait", "ms": 1100 },
+    { "kind": "text", "label": "Performance", "caption": "…or push for maximum performance" },
+    { "kind": "wait", "ms": 1300 },
+    {
+      "kind": "aria",
+      "label": "Custom device settings",
+      "caption": "Add limits for an unlisted device"
+    },
+    { "kind": "wait", "ms": 1700 },
+    { "kind": "aria", "label": "Back to TDP Control" },
+    { "kind": "wait", "ms": 900 }
+  ]
+}
diff --git a/plugins/theme-loader/README.md b/plugins/theme-loader/README.md
index 6af20025..96e6dc4e 100644
--- a/plugins/theme-loader/README.md
+++ b/plugins/theme-loader/README.md
@@ -4,6 +4,10 @@
 
 Browse, install, and toggle community CSS themes for Steam's Big Picture UI, restyling the interface to taste from inside Gaming Mode.
 
+## Demo
+
+![Theme Loader demo](./assets/demo.webp)
+
 ## Screenshots
 
 ### Plugin
diff --git a/plugins/theme-loader/assets/demo.webp b/plugins/theme-loader/assets/demo.webp
new file mode 100644
index 00000000..29f4675c
Binary files /dev/null and b/plugins/theme-loader/assets/demo.webp differ
diff --git a/plugins/theme-loader/tour.json b/plugins/theme-loader/tour.json
new file mode 100644
index 00000000..b2a56acc
--- /dev/null
+++ b/plugins/theme-loader/tour.json
@@ -0,0 +1,38 @@
+{
+  "title": "Theme Loader · restyle Steam Big Picture",
+  "fps": 14,
+  "width": 980,
+  "tailMs": 900,
+  "steps": [
+    {
+      "kind": "wait",
+      "ms": 1500,
+      "caption": "Your installed themes"
+    },
+    {
+      "kind": "text",
+      "label": "Community",
+      "caption": "Browse DeckThemes"
+    },
+    {
+      "kind": "wait",
+      "ms": 2000,
+      "caption": "Hundreds of themes"
+    },
+    {
+      "kind": "wait",
+      "ms": 1000,
+      "caption": "One-tap install"
+    },
+    {
+      "kind": "aria",
+      "label": "Back to themes",
+      "caption": "Back to your themes"
+    },
+    {
+      "kind": "wait",
+      "ms": 900,
+      "caption": "Reapply anytime"
+    }
+  ]
+}
diff --git a/plugins/wifi/README.md b/plugins/wifi/README.md
index 8b6a14de..2be35273 100644
--- a/plugins/wifi/README.md
+++ b/plugins/wifi/README.md
@@ -2,6 +2,10 @@
 
 > Stop WiFi dropping out by disabling the radio's power saving. Writes a NetworkManager drop-in (and an iwd quirk where iwd is installed), applies it instantly, and re-asserts it on every wake. Cross-distro: SteamOS, Bazzite, CachyOS.
 
+## Demo
+
+![WiFi demo](./assets/demo.webp)
+
 ## Screenshots
 
 ![WiFi](./assets/screenshot.png)
diff --git a/plugins/wifi/assets/demo.webp b/plugins/wifi/assets/demo.webp
new file mode 100644
index 00000000..20728925
Binary files /dev/null and b/plugins/wifi/assets/demo.webp differ
diff --git a/plugins/wifi/tour.json b/plugins/wifi/tour.json
new file mode 100644
index 00000000..12d4a4cc
--- /dev/null
+++ b/plugins/wifi/tour.json
@@ -0,0 +1,31 @@
+{
+  "title": "WiFi · stop the drops",
+  "fps": 15,
+  "tailMs": 900,
+  "steps": [
+    {
+      "kind": "wait",
+      "ms": 1300
+    },
+    {
+      "kind": "wait",
+      "ms": 1600,
+      "caption": "WiFi drops after sleep?"
+    },
+    {
+      "kind": "wait",
+      "ms": 1600,
+      "caption": "One toggle keeps it alive"
+    },
+    {
+      "kind": "wait",
+      "ms": 1500,
+      "caption": "Re-applies on every wake"
+    },
+    {
+      "kind": "wait",
+      "ms": 1300,
+      "caption": "Reversible anytime"
+    }
+  ]
+}
diff --git a/scripts/capture-screenshots.ts b/scripts/capture-screenshots.ts
index 60222515..3de63138 100644
--- a/scripts/capture-screenshots.ts
+++ b/scripts/capture-screenshots.ts
@@ -13,16 +13,21 @@
  * reached by clicking DOM elements over CDP, driven by the per-plugin
  * `PAGE_RECIPES` table below (the shared `<GameCard>` carries a stable
  * `data-game-card` hook; gears/tabs/back are matched by aria-label / text).
+ *
+ * The CDP connection + hash navigation + recipe-step machinery is shared
+ * with `capture-videos.ts` and lives in `lib/overlay-cdp.ts`.
  */
-import {
-  readdirSync,
-  existsSync,
-  mkdirSync,
-  writeFileSync,
-  copyFileSync,
-  rmSync,
-} from "node:fs";
+import { readdirSync, existsSync, mkdirSync, copyFileSync, rmSync } from "node:fs";
 import { join, resolve, relative } from "node:path";
+import {
+  CDP,
+  cdpWs,
+  navigate,
+  runSteps,
+  setSidebarCollapsed,
+  waitForIdle,
+  type Step,
+} from "./lib/overlay-cdp";
 
 // Repo root, derived from this script's location so the capture
 // script runs the same way for every contributor regardless of where
@@ -56,19 +61,11 @@ const PLUGINS = readdirSync(join(ROOT, "plugins"), { withFileTypes: true })
 
 // ── Per-plugin sub-page recipes ────────────────────────────────────────────
 //
-// A `Step` is a single CDP-driven action. `tile` clicks the first shared
-// GameCard (`[data-game-card]`) to open a detail page; `aria`/`text` click a
-// control by aria-label / visible text (gears, tabs); `wait` adds settle time.
-//
 // Each page is captured from a freshly-(re)navigated plugin landing, so steps
 // describe the path from the landing — no need to back out between pages. If a
 // step's target isn't on screen (e.g. an empty library has no tile), the page
-// is skipped rather than producing a misleading shot.
-type Step =
-  | { kind: "tile" }
-  | { kind: "aria"; label: string }
-  | { kind: "text"; label: string }
-  | { kind: "wait"; ms: number };
+// is skipped rather than producing a misleading shot. See the `Step`
+// vocabulary in `lib/overlay-cdp.ts`.
 
 interface PageShot {
   /** Suffix in the filename: `NN-<plugin>-<name>.png`. */
@@ -84,9 +81,7 @@ const PAGE_RECIPES: Record<string, PageShot[]> = {
   // The landing shot is the Library (available games) tab; only the
   // Installed tab is captured as a sub-page. Downloads/Detected/detail
   // shots were dropped — they're empty/low-signal on a fresh install.
-  "store-bridge": [
-    { name: "installed", steps: [{ kind: "text", label: "Installed" }] },
-  ],
+  "store-bridge": [{ name: "installed", steps: [{ kind: "text", label: "Installed" }] }],
   "launch-options": [
     { name: "detail", steps: [{ kind: "tile" }] },
     { name: "presets", steps: [{ kind: "aria", label: "Manage presets" }] },
@@ -95,9 +90,7 @@ const PAGE_RECIPES: Record<string, PageShot[]> = {
   // The custom-device form lives on its own sub-view behind the header gear —
   // a real feature page (define TDP limits for an unlisted handheld), not a
   // generic settings screen, so it's worth capturing.
-  "tdp-control": [
-    { name: "settings", steps: [{ kind: "aria", label: "Custom device settings" }] },
-  ],
+  "tdp-control": [{ name: "settings", steps: [{ kind: "aria", label: "Custom device settings" }] }],
   // Custom fan-curve editor only renders in Manual mode after the Custom
   // preset is selected — flip Manual (header), then pick Custom to reveal
   // the curve graph + per-point sliders.
@@ -119,130 +112,6 @@ const LANDING_SETUP: Record<string, Step[]> = {
   playtime: [{ kind: "text", label: "All" }],
 };
 
-const sleep = (ms: number) => Bun.sleep(ms);
-// Brief settle for the route swap + first paint before we poll for idle.
-const SETTLE_MS = 300;
-// Async-loading wait: many plugins fetch over the network on mount
-// (ProtonDB, HLTB, SteamGridDB, store libraries), so a fixed sleep either
-// over-waits or fires mid-spinner. Poll until no loading indicators remain.
-const IDLE_TIMEOUT_MS = 8000;
-const IDLE_POLL_MS = 200;
-// The DOM must stay idle this long before we trust it — guards the gap
-// between one fetch's spinner clearing and the next appearing.
-const IDLE_STABLE_MS = 400;
-
-async function cdpWs(): Promise<string> {
-  const res = await fetch("http://localhost:9222/json");
-  const targets = (await res.json()) as Array<{
-    title?: string;
-    webSocketDebuggerUrl: string;
-  }>;
-  const overlay = targets.find((t) => t.title === "Loadout Overlay");
-  if (!overlay) {
-    console.error("overlay target not found");
-    process.exit(1);
-  }
-  return overlay.webSocketDebuggerUrl;
-}
-
-class CDP {
-  private ws!: WebSocket;
-  private id = 0;
-  private pending = new Map<number, (msg: Record<string, unknown>) => void>();
-
-  static async connect(url: string): Promise<CDP> {
-    const cdp = new CDP();
-    cdp.ws = new WebSocket(url);
-    cdp.ws.addEventListener("message", (ev: MessageEvent) => {
-      const msg = JSON.parse(
-        typeof ev.data === "string" ? ev.data : ev.data.toString(),
-      );
-      // Responses carry an `id`; CDP events don't — ignore the latter.
-      if (typeof msg.id === "number" && cdp.pending.has(msg.id)) {
-        cdp.pending.get(msg.id)!(msg);
-        cdp.pending.delete(msg.id);
-      }
-    });
-    await new Promise<void>((res, rej) => {
-      cdp.ws.addEventListener("open", () => res(), { once: true });
-      cdp.ws.addEventListener("error", () => rej(new Error("CDP ws error")), {
-        once: true,
-      });
-    });
-    return cdp;
-  }
-
-  call(
-    method: string,
-    params: Record<string, unknown> = {},
-  ): Promise<Record<string, unknown>> {
-    const id = ++this.id;
-    return new Promise((res) => {
-      this.pending.set(id, res);
-      this.ws.send(JSON.stringify({ id, method, params }));
-    });
-  }
-
-  async eval(expr: string, awaitPromise = false): Promise<unknown> {
-    const r = (await this.call("Runtime.evaluate", {
-      expression: expr,
-      returnByValue: true,
-      awaitPromise,
-    })) as { result?: { result?: { value?: unknown } } };
-    return r.result?.result?.value;
-  }
-
-  async screenshot(path: string): Promise<void> {
-    const r = (await this.call("Page.captureScreenshot", {
-      format: "png",
-      captureBeyondViewport: false,
-    })) as { result?: { data?: string } };
-    const data = r.result?.data;
-    if (!data) throw new Error(`no data: ${JSON.stringify(r)}`);
-    mkdirSync(join(path, ".."), { recursive: true });
-    writeFileSync(path, Buffer.from(data, "base64"));
-    console.log(`  → ${rel(path)}`);
-  }
-}
-
-// "Busy" if any DaisyUI `.loading` spinner / `animate-spin` icon is
-// present, OR any *in-viewport* image hasn't finished decoding. The image
-// check is what stops us shooting game/detail art before it paints —
-// spinners alone don't cover lazy <img> loads. Off-screen lazy images are
-// ignored (they never load until scrolled to, so they'd never settle).
-const BUSY_EXPR = `(() => {
-  if (document.querySelectorAll('.loading, [class*="animate-spin"]').length) return true;
-  const vw = innerWidth, vh = innerHeight;
-  for (const img of document.images) {
-    const r = img.getBoundingClientRect();
-    const inView = r.bottom > 0 && r.top < vh && r.right > 0 && r.left < vw && r.width > 0 && r.height > 0;
-    if (inView && (!img.complete || img.naturalWidth === 0)) return true;
-  }
-  return false;
-})()`;
-
-/**
- * Wait until the overlay has no visible loading state — no spinners and
- * no in-viewport image still decoding — staying clear for `IDLE_STABLE_MS`
- * so we don't fire in the gap between two sequential fetches. Falls
- * through after `IDLE_TIMEOUT_MS` so a perpetually-loading view still gets
- * captured.
- */
-async function waitForIdle(cdp: CDP): Promise<void> {
-  const start = Date.now();
-  let idleSince: number | null = null;
-  while (Date.now() - start < IDLE_TIMEOUT_MS) {
-    const busy = (await cdp.eval(BUSY_EXPR)) === true;
-    if (busy) {
-      idleSince = null;
-    } else {
-      idleSince ??= Date.now();
-      if (Date.now() - idleSince >= IDLE_STABLE_MS) return;
-    }
-    await sleep(IDLE_POLL_MS);
-  }
-}
-
 /**
  * Scroll the plugin's main scroll container to a random position so the
  * game grids don't show the identical first row in every shot. No-op when
@@ -276,103 +145,11 @@ const NO_SCROLL = new Set(["recomp", "tdp-control", "playtime"]);
  */
 async function varyGridView(cdp: CDP, pluginId: string): Promise<void> {
   if (NO_SCROLL.has(pluginId)) return;
-  const tiles = (await cdp.eval(
-    `document.querySelectorAll('[data-game-card]').length`,
-  )) as number;
+  const tiles = (await cdp.eval(`document.querySelectorAll('[data-game-card]').length`)) as number;
   if (tiles < GRID_TILE_THRESHOLD) return;
   if (await scrollRandom(cdp)) await waitForIdle(cdp);
 }
 
-async function navigate(cdp: CDP, hashPath: string): Promise<void> {
-  await cdp.eval(`location.hash='${hashPath}'; void 0`);
-  await sleep(SETTLE_MS); // let the route swap + mount begin
-  await waitForIdle(cdp); // then wait out any async loading
-}
-
-async function setSidebarCollapsed(cdp: CDP, collapsed: boolean): Promise<void> {
-  // The toggle is a Focusable button; flipping the checkbox directly
-  // updates the drawer classes but not React state. Instead click the
-  // actual button so React's onClick runs.
-  const expr = `
-  (function(){
-    const input = document.getElementById('sl-drawer');
-    if (input.checked === ${collapsed ? "false" : "true"}) return 'already';
-    const btn = document.querySelector('[aria-label="Toggle sidebar"]');
-    btn && btn.click();
-    return 'clicked';
-  })()
-  `;
-  await cdp.eval(expr);
-  await sleep(250);
-}
-
-// ── Recipe step execution ──────────────────────────────────────────────────
-
-/** Click the first element matching `selector`. Returns whether it existed. */
-async function clickSelector(cdp: CDP, selector: string): Promise<boolean> {
-  const expr = `(() => {
-    const el = document.querySelector(${JSON.stringify(selector)});
-    if (!el) return false;
-    el.click();
-    return true;
-  })()`;
-  return (await cdp.eval(expr)) === true;
-}
-
-/** Click the first button/[role=button] whose text starts with `label`. */
-async function clickText(cdp: CDP, label: string): Promise<boolean> {
-  const expr = `(() => {
-    const els = [...document.querySelectorAll('button, [role="button"]')];
-    const el = els.find((e) => (e.textContent || "").trim().startsWith(${JSON.stringify(label)}));
-    if (!el) return false;
-    el.click();
-    return true;
-  })()`;
-  return (await cdp.eval(expr)) === true;
-}
-
-// A click target may not exist yet — plugin headers/grids that fetch data
-// (recomp, hltb, steamgriddb, launch-options) render their gear/tiles only
-// after the load resolves. Poll for the element before giving up so a slow
-// fetch doesn't read as "page absent".
-const CLICK_TRIES = 6;
-const CLICK_RETRY_MS = 500;
-
-async function clickWithRetry(
-  cdp: CDP,
-  fn: () => Promise<boolean>,
-): Promise<boolean> {
-  for (let i = 0; i < CLICK_TRIES; i++) {
-    if (await fn()) return true;
-    await sleep(CLICK_RETRY_MS);
-  }
-  return false;
-}
-
-/** Run a page recipe's steps. Returns false (page unreachable) if any
- *  click target never appears. */
-async function runSteps(cdp: CDP, steps: Step[]): Promise<boolean> {
-  for (const step of steps) {
-    if (step.kind === "wait") {
-      await sleep(step.ms);
-      continue;
-    }
-    let ok = false;
-    if (step.kind === "tile")
-      ok = await clickWithRetry(cdp, () => clickSelector(cdp, "[data-game-card]"));
-    else if (step.kind === "aria")
-      ok = await clickWithRetry(cdp, () =>
-        clickSelector(cdp, `[aria-label="${step.label}"]`),
-      );
-    else if (step.kind === "text")
-      ok = await clickWithRetry(cdp, () => clickText(cdp, step.label));
-    if (!ok) return false;
-    await sleep(SETTLE_MS);
-    await waitForIdle(cdp); // sub-page may fetch on open (detail pages)
-  }
-  return true;
-}
-
 // ── Post-processing: copy to plugin assets + cull stale shots ──────────────
 
 function copyToPluginAssets(theme: string, only?: Set<string>): void {
@@ -459,9 +236,7 @@ async function main(): Promise<void> {
   // theme — pass `--theme=<name>` (default `midnight`) to pick the source
   // theme dir for the asset copy.
   const args = new Set(process.argv.slice(2));
-  const themeArg = [...args]
-    .find((a) => a.startsWith("--theme="))
-    ?.split("=")[1];
+  const themeArg = [...args].find((a) => a.startsWith("--theme="))?.split("=")[1];
 
   // `--plugins=a,b,c` (or `--plugin=a`) limits capture to a subset. When set,
   // the global home shots are skipped and stale-culling is disabled, so a
@@ -472,7 +247,10 @@ async function main(): Promise<void> {
     ?.split("=")[1];
   let only: Set<string> | null = null;
   if (onlyArg) {
-    const requested = onlyArg.split(",").map((s) => s.trim()).filter(Boolean);
+    const requested = onlyArg
+      .split(",")
+      .map((s) => s.trim())
+      .filter(Boolean);
     const unknown = requested.filter((p) => !PLUGINS.includes(p));
     if (unknown.length) {
       console.error(`[capture] unknown plugin(s): ${unknown.join(", ")}`);
@@ -493,9 +271,8 @@ async function main(): Promise<void> {
 
   // Capture whatever theme the overlay is currently in — never change it.
   const theme =
-    ((await cdp.eval(
-      `document.documentElement.getAttribute('data-theme')`,
-    )) as string | null) ?? "midnight";
+    ((await cdp.eval(`document.documentElement.getAttribute('data-theme')`)) as string | null) ??
+    "midnight";
   console.log(`[theme] capturing current theme: ${theme}`);
 
   // Global surfaces (home only — the settings page isn't a useful shot).
@@ -503,10 +280,12 @@ async function main(): Promise<void> {
   if (!only) {
     await setSidebarCollapsed(cdp, false);
     await navigate(cdp, "#/");
-    await cdp.screenshot(join(OUT, theme, "00-home.png"));
+    const home = join(OUT, theme, "00-home.png");
+    await cdp.screenshot(home, rel(home));
     await navigate(cdp, "#/");
     await setSidebarCollapsed(cdp, true);
-    await cdp.screenshot(join(OUT, theme, "02-home-sidebar-collapsed.png"));
+    const collapsed = join(OUT, theme, "02-home-sidebar-collapsed.png");
+    await cdp.screenshot(collapsed, rel(collapsed));
     await setSidebarCollapsed(cdp, false);
   }
 
@@ -518,7 +297,8 @@ async function main(): Promise<void> {
     await navigate(cdp, `#/plugin/${pid}`);
     if (LANDING_SETUP[pid]) await runSteps(cdp, LANDING_SETUP[pid]);
     await varyGridView(cdp, pid);
-    await cdp.screenshot(join(OUT, theme, `${nn}-${pid}.png`));
+    const landing = join(OUT, theme, `${nn}-${pid}.png`);
+    await cdp.screenshot(landing, rel(landing));
 
     for (const page of PAGE_RECIPES[pid] ?? []) {
       // Reset to the plugin landing so each page starts from a clean base.
@@ -533,7 +313,8 @@ async function main(): Promise<void> {
         continue;
       }
       await varyGridView(cdp, pid); // grid sub-pages (e.g. store tabs) vary too
-      await cdp.screenshot(join(OUT, theme, `${nn}-${pid}-${page.name}.png`));
+      const sub = join(OUT, theme, `${nn}-${pid}-${page.name}.png`);
+      await cdp.screenshot(sub, rel(sub));
     }
   }
 
diff --git a/scripts/capture-videos.ts b/scripts/capture-videos.ts
new file mode 100644
index 00000000..5b9c39d3
--- /dev/null
+++ b/scripts/capture-videos.ts
@@ -0,0 +1,851 @@
+#!/usr/bin/env bun
+/**
+ * Capture short feature clips of the running overlay and encode them to
+ * animated WebP (the README-embeddable format), with per-step captions burned
+ * into the video — plus optional GIF / MP4.
+ *
+ * Why WebP: GitHub markdown renders repo-relative `![](…)` images, and an
+ * animated WebP autoplays + loops inline like a GIF but at a fraction of the
+ * size. Repo-relative `<video>`/MP4 does NOT render on GitHub, so committed
+ * WebP is the one format that is both self-contained *and* inline-animated.
+ * See docs/media-capture.md.
+ *
+ * Two capture surfaces:
+ *
+ *   Per-plugin TOURS (default) — each plugin may ship `plugins/<id>/tour.json`
+ *     (opt-in): a scripted tour with captions. `--tours` discovers every plugin
+ *     that has one, navigates to it, records the beats, burns the captions in,
+ *     and writes to a review folder (`videos/review/<id>.webp`) for you to watch
+ *     before `--promote=<id,…>` copies it to `plugins/<id>/assets/demo.webp`
+ *     and inserts a `## Demo` section into that plugin's README.
+ *
+ *   STEAM Big Picture (`--target=steam`) — records Steam's own CEF (:8080),
+ *     where theme-loader CSS and Store Bridge's Epic collection live. Run it
+ *     from Gaming Mode with Big Picture in the foreground.
+ *
+ * The CDP connection + hash-navigation + recipe-step vocabulary is shared with
+ * `capture-screenshots.ts` via `lib/overlay-cdp.ts`.
+ *
+ * Usage:
+ *   bun run capture:videos                          # capture every plugin tour
+ *   bun run capture:videos --tours --plugins=tdp-control
+ *   bun run capture:videos --promote=tdp-control    # review clip → tracked asset + README
+ *   bun run capture:videos --list                   # list tours + steam clips
+ *   bun run capture:videos --format=all             # WebP + GIF + MP4
+ *   bun run capture:videos --width=960 --fps=15
+ *   bun run capture:videos --keep-frames            # leave raw JPEG frames
+ *   bun run capture:videos --target=steam           # Big Picture clips
+ *
+ * Requires: ffmpeg (encode) and a sans font via fontconfig (captions).
+ */
+import {
+  mkdirSync,
+  writeFileSync,
+  readFileSync,
+  readdirSync,
+  copyFileSync,
+  rmSync,
+  existsSync,
+} from "node:fs";
+import { join, resolve, relative } from "node:path";
+import { listCefTabs } from "@loadout/steam-cdp";
+import {
+  CDP,
+  cdpWs,
+  navigate,
+  setSidebarCollapsed,
+  waitForIdle,
+  clickSelector,
+  clickText,
+  clickWithRetry,
+  sleep,
+  SETTLE_MS,
+  type Step,
+} from "./lib/overlay-cdp";
+
+const ROOT = resolve(import.meta.dir, "..");
+// Scratch tree for raw frames + intermediate encodes, and the review folder
+// where freshly-captured tours land. Gitignored — `--promote` copies the
+// approved clip into the plugin's tracked `assets/` dir.
+const OUT = join(ROOT, "videos");
+const REVIEW = join(OUT, "review");
+const rel = (p: string) => relative(ROOT, p);
+
+type Format = "webp" | "gif" | "mp4";
+
+// Plugins never toured — either they render identifying / personal data that
+// must not be committed, or they're poor tour material. Enforced two ways:
+// tours are opt-in (no `tour.json` → no tour) AND these are hard-skipped even
+// if a `tour.json` exists.
+//   network-info      — MAC / SSID / IP
+//   playtime          — personal play history
+//   bluetooth         — paired device names
+//   storage-cleaner   — excluded per maintainer request
+//   display-settings  — excluded per maintainer request
+//   recomp            — excluded per maintainer request (heavy game-art clip)
+const TOUR_SKIP = new Set([
+  "network-info",
+  "playtime",
+  "bluetooth",
+  "storage-cleaner",
+  "display-settings",
+  "recomp",
+]);
+
+// ── Per-plugin tour recipes (plugins/<id>/tour.json) ────────────────────────
+//
+// A tour reuses the overlay `Step` vocabulary (`wait` / `nav` / `sidebar` /
+// `tile` / `aria` / `text`); the script auto-navigates to `#/plugin/<id>`
+// first, so steps describe in-plugin beats only. Any step — or the `title` —
+// may carry a `caption`, shown from when that step fires until the next
+// caption, burned in as a lower-third.
+type TourStep = Step & { caption?: string };
+
+interface Tour {
+  /** Optional intro caption, shown from the first frame. */
+  title?: string;
+  /** Output frame rate for this tour (default `DEFAULT_FPS`). */
+  fps?: number;
+  /**
+   * Output width in px for this tour (default `--width` / `DEFAULT_WIDTH`).
+   * Art-heavy library grids don't compress in WebP, so those tours drop to a
+   * smaller width to keep the file reasonable while the caption stays legible.
+   */
+  width?: number;
+  /** Hold time on the final frame, ms (default 600). */
+  tailMs?: number;
+  steps: TourStep[];
+}
+
+// ── Steam (Big Picture) clips ───────────────────────────────────────────────
+//
+// These record Steam's OWN CEF UI (:8080), not the overlay. Steam's Big
+// Picture has no hash routes and its GamepadUI selectors are version-fragile,
+// so the vocabulary is deliberately small:
+//   eval   — run JS in the Big Picture tab (used for the theme toggle)
+//   theme  — flip every theme-loader-injected <style> on/off, which is exactly
+//            what theme-loader does; a real, deterministic recolor
+//   manual — pause with a countdown so YOU navigate Big Picture by hand while
+//            recording continues (the honest path for library/collection nav)
+//   wait   — hold
+type SteamStep =
+  | { kind: "wait"; ms: number }
+  | { kind: "eval"; js: string }
+  | { kind: "theme"; on: boolean }
+  | { kind: "manual"; ms: number; prompt: string };
+
+// Selector for every <style> theme-loader injects (id `theme-loader-<id>`,
+// see safeStyleId() in plugins/theme-loader/backend.ts).
+const THEME_STYLE_SELECTOR = 'style[id^="theme-loader-"]';
+
+// Where a Steam clip's encoded file lands:
+//   plugin → plugins/<id>/assets/demo.<ext>
+//   docs   → docs/assets/<file>.<ext>
+type Dest = { kind: "plugin"; id: string } | { kind: "docs"; file: string };
+
+interface SteamClip {
+  name: string;
+  title: string;
+  dest: Dest;
+  setup?: SteamStep[];
+  steps: SteamStep[];
+  tailMs?: number;
+  fps?: number;
+  /** Guard run before recording; false skips the clip. */
+  precheck?: (cdp: CDP) => Promise<boolean>;
+}
+
+const STEAM_CLIPS: SteamClip[] = [
+  {
+    name: "steam-theme",
+    title: "Theme Loader — live Big Picture recolor",
+    dest: { kind: "docs", file: "steam-theme" },
+    precheck: async (cdp) => {
+      const n = (await cdp.eval(
+        `document.querySelectorAll('${THEME_STYLE_SELECTOR}').length`,
+      )) as number;
+      if (!n) {
+        console.log("  ↷ no active theme found in Big Picture — enable one in theme-loader first");
+        return false;
+      }
+      return true;
+    },
+    steps: [
+      { kind: "wait", ms: 900 },
+      { kind: "theme", on: false },
+      { kind: "wait", ms: 1200 },
+      { kind: "theme", on: true },
+      { kind: "wait", ms: 1200 },
+      { kind: "theme", on: false },
+      { kind: "wait", ms: 1000 },
+      { kind: "theme", on: true },
+      { kind: "wait", ms: 800 },
+    ],
+  },
+  {
+    name: "steam-epic",
+    title: "Store Bridge — Epic games as a Steam collection",
+    dest: { kind: "plugin", id: "store-bridge" },
+    steps: [
+      {
+        kind: "manual",
+        ms: 9000,
+        prompt:
+          "Open your Store Bridge / Epic collection in Big Picture now — panning the grid reads best.",
+      },
+    ],
+  },
+];
+
+// ── Encoding knobs (overridable via flags) ──────────────────────────────────
+const DEFAULT_WIDTH = 1280; // native handheld width so UI text stays legible
+const DEFAULT_FPS = 20; // normalize the (variable-rate) screencast to CFR
+// A hold with no visual change emits no screencast frames, so its duration is
+// the gap to the NEXT frame. Cap that gap so a long idle never freezes the
+// clip; floor it so timestamp jitter can't produce a zero-length frame.
+const MIN_FRAME_SEC = 1 / 120;
+const MAX_FRAME_SEC = 2.0;
+// Fewer captured frames than this means the surface never really repainted
+// (e.g. a backgrounded Big Picture) — treat it as a failed capture.
+const MIN_USABLE_FRAMES = 4;
+
+interface RunOpts {
+  formats: Format[];
+  width: number;
+  fpsOverride: number | null;
+  keepFrames: boolean;
+}
+
+// ── Screencast recording ────────────────────────────────────────────────────
+
+interface Frame {
+  data: Buffer;
+  /** Arrival time, ms (monotonic). */
+  t: number;
+}
+
+/**
+ * Record a CDP screencast for the duration of `run()`. Returns the frames in
+ * arrival order. Frames are JPEG (small, fast to ack); ffmpeg re-encodes them.
+ */
+async function record(cdp: CDP, run: () => Promise<void>): Promise<Frame[]> {
+  const frames: Frame[] = [];
+  const off = cdp.on("Page.screencastFrame", (p) => {
+    const data = p["data"];
+    const sessionId = p["sessionId"];
+    if (typeof data === "string") {
+      frames.push({ data: Buffer.from(data, "base64"), t: performance.now() });
+    }
+    // Must ack or the browser stops sending frames after a few in flight.
+    if (sessionId !== undefined) {
+      void cdp.call("Page.screencastFrameAck", { sessionId });
+    }
+  });
+  await cdp.call("Page.enable");
+  await cdp.call("Page.startScreencast", {
+    format: "jpeg",
+    quality: 90,
+    everyNthFrame: 1,
+  });
+  try {
+    await run();
+  } finally {
+    await cdp.call("Page.stopScreencast");
+    off();
+  }
+  return frames;
+}
+
+// ── ffmpeg encoding ─────────────────────────────────────────────────────────
+
+function run(cmd: string[]): void {
+  const r = Bun.spawnSync(cmd, { stdout: "pipe", stderr: "pipe" });
+  if (r.exitCode !== 0) {
+    console.error(new TextDecoder().decode(r.stderr));
+    throw new Error(`${cmd[0]} exited ${r.exitCode}`);
+  }
+}
+
+/**
+ * Write frames to disk and build an ffmpeg concat list that carries each
+ * frame's real duration, so deliberate holds and animation pacing survive into
+ * the encode. Returns the list path and the clip's total duration (seconds) —
+ * the latter anchors caption timing.
+ */
+function writeFrames(
+  dir: string,
+  frames: Frame[],
+  tailSec: number,
+): { list: string; totalSec: number } {
+  mkdirSync(dir, { recursive: true });
+  const lines: string[] = [];
+  let totalSec = 0;
+  frames.forEach((f, i) => {
+    const file = join(dir, `frame-${String(i).padStart(5, "0")}.jpg`);
+    writeFileSync(file, f.data);
+    const next = frames[i + 1];
+    const raw = next ? (next.t - f.t) / 1000 : tailSec;
+    const dur = Math.min(MAX_FRAME_SEC, Math.max(MIN_FRAME_SEC, raw));
+    totalSec += dur;
+    lines.push(`file '${file}'`, `duration ${dur.toFixed(3)}`);
+  });
+  // The concat demuxer ignores the final entry's `duration` unless the last
+  // file is repeated, so repeat it to honour the tail hold.
+  const last = frames[frames.length - 1];
+  if (last) {
+    lines.push(`file '${join(dir, `frame-${String(frames.length - 1).padStart(5, "0")}.jpg`)}'`);
+  }
+  const listPath = join(dir, "frames.txt");
+  writeFileSync(listPath, lines.join("\n") + "\n");
+  return { list: listPath, totalSec };
+}
+
+interface TimedCaption {
+  text: string;
+  start: number;
+  end: number;
+}
+
+/** Resolve raw (text, arrival-time) caption events into on-timeline windows:
+ *  each caption shows until the next one fires (last runs to the clip end). */
+function resolveCaptions(
+  raw: { text: string; t: number }[],
+  t0: number,
+  totalSec: number,
+): TimedCaption[] {
+  const sorted = raw
+    .map((c) => ({ text: c.text, start: Math.max(0, (c.t - t0) / 1000) }))
+    .sort((a, b) => a.start - b.start);
+  return sorted.map((c, i) => ({
+    ...c,
+    end: i + 1 < sorted.length ? sorted[i + 1]!.start : totalSec,
+  }));
+}
+
+/** Locate a sans-serif font file for drawtext. Empty string if none found
+ *  (captions are then skipped rather than failing the whole encode). */
+function findFont(): string {
+  const r = Bun.spawnSync(["fc-match", "-f", "%{file}", "sans-serif"]);
+  if (r.exitCode === 0) {
+    const f = new TextDecoder().decode(r.stdout).trim();
+    if (f && existsSync(f)) return f;
+  }
+  for (const p of [
+    "/usr/share/fonts/TTF/DejaVuSans.ttf",
+    "/usr/share/fonts/dejavu/DejaVuSans.ttf",
+    "/usr/share/fonts/truetype/dejavu/DejaVuSans.ttf",
+    "/usr/share/fonts/noto/NotoSans-Regular.ttf",
+  ]) {
+    if (existsSync(p)) return p;
+  }
+  return "";
+}
+
+/** Build the `,drawtext=…` filter chain that burns captions in as a
+ *  lower-third. Caption text goes through a textfile to avoid escaping. */
+function captionFilters(caps: TimedCaption[], font: string, dir: string, width: number): string {
+  const size = Math.max(18, Math.round(width / 34));
+  return caps
+    .map((c, i) => {
+      const tf = join(dir, `cap-${i}.txt`);
+      writeFileSync(tf, c.text + "\n");
+      // Single-quoted option values keep commas/colons literal inside the
+      // filtergraph; textfile/font paths under the repo have no special chars.
+      return (
+        `,drawtext=fontfile='${font}':textfile='${tf}'` +
+        `:fontsize=${size}:fontcolor=white:box=1:boxcolor=black@0.55:boxborderw=18` +
+        `:line_spacing=6:x=(w-text_w)/2:y=h-text_h-48` +
+        `:enable='between(t,${c.start.toFixed(2)},${c.end.toFixed(2)})'`
+      );
+    })
+    .join("");
+}
+
+const baseVf = (width: number, fps: number) => `fps=${fps},scale=${width}:-1:flags=lanczos`;
+
+function encodeWebp(list: string, out: string, width: number, fps: number, caps: string): void {
+  run([
+    "ffmpeg",
+    "-y",
+    "-f",
+    "concat",
+    "-safe",
+    "0",
+    "-i",
+    list,
+    "-vf",
+    `${baseVf(width, fps)}${caps}`,
+    "-c:v",
+    "libwebp",
+    "-loop",
+    "0",
+    "-lossless",
+    "0",
+    "-q:v",
+    "55",
+    "-compression_level",
+    "6",
+    "-an",
+    out,
+  ]);
+}
+
+function encodeGif(
+  dir: string,
+  list: string,
+  out: string,
+  width: number,
+  fps: number,
+  caps: string,
+): void {
+  // Two-pass palette for a clean GIF: generate an optimized palette, then map.
+  const palette = join(dir, "palette.png");
+  run([
+    "ffmpeg",
+    "-y",
+    "-f",
+    "concat",
+    "-safe",
+    "0",
+    "-i",
+    list,
+    "-vf",
+    `${baseVf(width, fps)}${caps},palettegen=stats_mode=diff`,
+    palette,
+  ]);
+  run([
+    "ffmpeg",
+    "-y",
+    "-f",
+    "concat",
+    "-safe",
+    "0",
+    "-i",
+    list,
+    "-i",
+    palette,
+    "-lavfi",
+    `${baseVf(width, fps)}${caps} [x]; [x][1:v] paletteuse=dither=bayer:bayer_scale=5:diff_mode=rectangle`,
+    "-loop",
+    "0",
+    out,
+  ]);
+}
+
+function encodeMp4(list: string, out: string, width: number, fps: number, caps: string): void {
+  run([
+    "ffmpeg",
+    "-y",
+    "-f",
+    "concat",
+    "-safe",
+    "0",
+    "-i",
+    list,
+    // yuv420p + even dimensions are required for broad H.264 playback.
+    "-vf",
+    `${baseVf(width, fps)}${caps},pad=ceil(iw/2)*2:ceil(ih/2)*2`,
+    "-c:v",
+    "libx264",
+    "-pix_fmt",
+    "yuv420p",
+    "-movflags",
+    "+faststart",
+    "-an",
+    out,
+  ]);
+}
+
+/** Encode a clip into every requested format, deriving gif/mp4 paths from the
+ *  webp path. `caps` is the (possibly empty) burned-in caption filter chain. */
+function encodeAll(
+  outWebp: string,
+  list: string,
+  dir: string,
+  caps: string,
+  formats: Format[],
+  width: number,
+  fps: number,
+): void {
+  for (const fmt of formats) {
+    const out = outWebp.replace(/\.webp$/, `.${fmt}`);
+    mkdirSync(join(out, ".."), { recursive: true });
+    if (fmt === "webp") encodeWebp(list, out, width, fps, caps);
+    else if (fmt === "gif") encodeGif(dir, list, out, width, fps, caps);
+    else encodeMp4(list, out, width, fps, caps);
+    const kb = Math.round(Bun.file(out).size / 1024);
+    console.log(`  → ${rel(out)} (${kb} KB)`);
+  }
+}
+
+// ── Per-plugin tours ────────────────────────────────────────────────────────
+
+/** Discover every `plugins/<id>/tour.json` (opt-in), minus the privacy
+ *  blacklist. Sorted for stable ordering. */
+function discoverTours(): { id: string; tour: Tour }[] {
+  const out: { id: string; tour: Tour }[] = [];
+  for (const d of readdirSync(join(ROOT, "plugins"), { withFileTypes: true })) {
+    if (!d.isDirectory()) continue;
+    const p = join(ROOT, "plugins", d.name, "tour.json");
+    if (!existsSync(p)) continue;
+    if (TOUR_SKIP.has(d.name)) {
+      console.warn(`[tours] refusing privacy-blacklisted plugin with a tour.json: ${d.name}`);
+      continue;
+    }
+    let tour: Tour;
+    try {
+      tour = JSON.parse(readFileSync(p, "utf8")) as Tour;
+    } catch (err) {
+      console.error(`[tours] ${d.name}/tour.json is not valid JSON: ${err}`);
+      process.exit(1);
+    }
+    if (!Array.isArray(tour.steps) || tour.steps.length === 0) {
+      console.error(`[tours] ${d.name}/tour.json has no steps`);
+      process.exit(1);
+    }
+    out.push({ id: d.name, tour });
+  }
+  return out.sort((a, b) => a.id.localeCompare(b.id));
+}
+
+async function captureTour(
+  cdp: CDP,
+  id: string,
+  tour: Tour,
+  font: string,
+  opts: RunOpts,
+): Promise<void> {
+  console.log(`\n[tour] ${id}${tour.title ? ` — ${tour.title}` : ""}`);
+  await navigate(cdp, `#/plugin/${id}`);
+  await waitForIdle(cdp);
+
+  const raw: { text: string; t: number }[] = [];
+  if (tour.title) raw.push({ text: tour.title, t: performance.now() });
+  const frames = await record(cdp, async () => {
+    for (const step of tour.steps) {
+      if (step.caption) raw.push({ text: step.caption, t: performance.now() });
+      await runOverlayStep(cdp, step);
+    }
+  });
+  console.log(`  captured ${frames.length} frame(s)`);
+  if (frames.length < MIN_USABLE_FRAMES) {
+    console.warn(`  ↷ only ${frames.length} frame(s) — nothing repainted; skipping ${id}`);
+    return;
+  }
+
+  const dir = join(OUT, `tour-${id}`);
+  if (existsSync(dir)) rmSync(dir, { recursive: true, force: true });
+  const { list, totalSec } = writeFrames(dir, frames, (tour.tailMs ?? 600) / 1000);
+  const fps = opts.fpsOverride ?? tour.fps ?? DEFAULT_FPS;
+  const width = tour.width ?? opts.width;
+  const caps =
+    font && raw.length
+      ? captionFilters(resolveCaptions(raw, frames[0]!.t, totalSec), font, dir, width)
+      : "";
+  if (!font && raw.length) {
+    console.warn("  ↷ no sans font found (install fontconfig/dejavu) — encoding without captions");
+  }
+
+  mkdirSync(REVIEW, { recursive: true });
+  encodeAll(join(REVIEW, `${id}.webp`), list, dir, caps, opts.formats, width, fps);
+  console.log(`  review: ${rel(join(REVIEW, `${id}.webp`))} — promote with --promote=${id}`);
+  if (!opts.keepFrames) rmSync(dir, { recursive: true, force: true });
+}
+
+/** Copy an approved review clip into the plugin's tracked assets and insert a
+ *  `## Demo` section into its README (idempotent). */
+function promote(ids: string[]): void {
+  for (const id of ids) {
+    const src = join(REVIEW, `${id}.webp`);
+    if (!existsSync(src)) {
+      console.error(`[promote] no review clip for "${id}" at ${rel(src)} — run --tours first`);
+      continue;
+    }
+    const dest = join(ROOT, "plugins", id, "assets", "demo.webp");
+    mkdirSync(join(dest, ".."), { recursive: true });
+    copyFileSync(src, dest);
+    console.log(`[promote] ${id}: ${rel(src)} → ${rel(dest)}`);
+    insertDemoSection(id);
+  }
+}
+
+/** Add a `## Demo` block (matching the scaffold template) above the plugin
+ *  README's `## Screenshots`. No-op if a demo embed is already present. */
+function insertDemoSection(id: string): void {
+  const readme = join(ROOT, "plugins", id, "README.md");
+  if (!existsSync(readme)) {
+    console.warn(`[promote] ${id}: no README.md to edit`);
+    return;
+  }
+  let text = readFileSync(readme, "utf8");
+  if (text.includes("./assets/demo.webp")) return; // already embedded
+  const name = /^#\s+(.+)$/m.exec(text)?.[1]?.trim() ?? id;
+  const block = `## Demo\n\n![${name} demo](./assets/demo.webp)\n\n`;
+  text = text.includes("## Screenshots")
+    ? text.replace("## Screenshots", `${block}## Screenshots`)
+    : `${text.trimEnd()}\n\n${block}`;
+  writeFileSync(readme, text);
+  console.log(`[promote] ${id}: inserted ## Demo section`);
+}
+
+// ── Steam capture ───────────────────────────────────────────────────────────
+
+function destPath(dest: Dest, ext: Format): string {
+  if (dest.kind === "plugin") {
+    return join(ROOT, "plugins", dest.id, "assets", `demo.${ext}`);
+  }
+  return join(ROOT, "docs", "assets", `${dest.file}.${ext}`);
+}
+
+async function captureSteamClips(cdp: CDP, clips: SteamClip[], opts: RunOpts): Promise<void> {
+  for (const clip of clips) {
+    console.log(`\n[clip] ${clip.name} — ${clip.title}`);
+    for (const step of clip.setup ?? []) await runSteamStep(cdp, step);
+    await sleep(SETTLE_MS);
+    if (clip.precheck && !(await clip.precheck(cdp))) continue;
+
+    const frames = await record(cdp, async () => {
+      for (const step of clip.steps) await runSteamStep(cdp, step);
+    });
+    console.log(`  captured ${frames.length} frame(s)`);
+    if (frames.length < MIN_USABLE_FRAMES) {
+      console.warn(
+        `  ↷ only ${frames.length} frame(s) — nothing repainted; skipping ${clip.name}.` +
+          ` (Steam clips must run with Big Picture in the foreground.)`,
+      );
+      continue;
+    }
+
+    const dir = join(OUT, clip.name);
+    if (existsSync(dir)) rmSync(dir, { recursive: true, force: true });
+    const { list } = writeFrames(dir, frames, (clip.tailMs ?? 600) / 1000);
+    const fps = opts.fpsOverride ?? clip.fps ?? DEFAULT_FPS;
+    encodeAll(destPath(clip.dest, "webp"), list, dir, "", opts.formats, opts.width, fps);
+    if (!opts.keepFrames) rmSync(dir, { recursive: true, force: true });
+  }
+}
+
+/** Resolve the WebSocket URL of Steam's Big Picture CEF tab (port 8080). */
+async function steamBigPictureWs(port: number): Promise<string> {
+  let tabs;
+  try {
+    tabs = await listCefTabs({ debugPort: port });
+  } catch (err) {
+    console.error(
+      `[video] couldn't reach Steam's CEF on localhost:${port}/json — is Steam ` +
+        `running with remote debugging enabled?\n  ${err instanceof Error ? err.message : err}`,
+    );
+    process.exit(1);
+  }
+  const bp =
+    tabs.find((t) => t.type === "page" && t.title === "Steam Big Picture Mode") ??
+    tabs.find((t) => t.type === "page" && /big picture/i.test(t.title));
+  if (!bp) {
+    console.error(
+      "[video] no 'Steam Big Picture Mode' tab found — open Big Picture / Gaming Mode first.\n" +
+        `[video] tabs seen: ${tabs.map((t) => t.title).join(", ")}`,
+    );
+    process.exit(1);
+  }
+  return bp.webSocketDebuggerUrl;
+}
+
+// ── Step runners ────────────────────────────────────────────────────────────
+
+/**
+ * Run one overlay beat. Unlike the screenshot runner, a missing click target
+ * is logged and skipped rather than aborting — a video tolerates a dropped
+ * beat, and hard-failing mid-record would waste the whole clip.
+ */
+async function runOverlayStep(cdp: CDP, step: Step): Promise<void> {
+  switch (step.kind) {
+    case "wait":
+      await sleep(step.ms);
+      return;
+    case "nav":
+      await navigate(cdp, step.hash);
+      return;
+    case "sidebar":
+      await setSidebarCollapsed(cdp, step.collapsed);
+      return;
+    case "tile": {
+      const ok = await clickWithRetry(() => clickSelector(cdp, "[data-game-card]"));
+      if (!ok) console.log("  ↷ no [data-game-card] on screen — skipping beat");
+      else {
+        await sleep(SETTLE_MS);
+        await waitForIdle(cdp);
+      }
+      return;
+    }
+    case "aria": {
+      const ok = await clickWithRetry(() => clickSelector(cdp, `[aria-label="${step.label}"]`));
+      if (!ok) console.log(`  ↷ no [aria-label="${step.label}"] — skipping beat`);
+      else {
+        await sleep(SETTLE_MS);
+        await waitForIdle(cdp);
+      }
+      return;
+    }
+    case "text": {
+      const ok = await clickWithRetry(() => clickText(cdp, step.label));
+      if (!ok) console.log(`  ↷ no "${step.label}" control — skipping beat`);
+      else {
+        await sleep(SETTLE_MS);
+        await waitForIdle(cdp);
+      }
+      return;
+    }
+  }
+}
+
+/**
+ * Run one Steam (Big Picture) beat. `theme` flips theme-loader's injected CSS;
+ * `manual` pauses with a countdown so you navigate Steam by hand while the
+ * screencast keeps rolling.
+ */
+async function runSteamStep(cdp: CDP, step: SteamStep): Promise<void> {
+  switch (step.kind) {
+    case "wait":
+      await sleep(step.ms);
+      return;
+    case "eval":
+      await cdp.eval(step.js);
+      return;
+    case "theme": {
+      const n = (await cdp.eval(
+        `(() => { const els = [...document.querySelectorAll('${THEME_STYLE_SELECTOR}')];` +
+          ` els.forEach((e) => { e.disabled = ${step.on ? "false" : "true"}; }); return els.length; })()`,
+      )) as number;
+      if (!n) console.log("  ↷ no theme-loader styles present — enable a theme first");
+      return;
+    }
+    case "manual": {
+      console.log(`  ⏵ ${step.prompt}`);
+      for (let s = Math.ceil(step.ms / 1000); s > 0; s--) {
+        console.log(`    recording… ${s}s`);
+        await sleep(1000);
+      }
+      return;
+    }
+  }
+}
+
+// ── Main ────────────────────────────────────────────────────────────────────
+
+function parseFormats(arg: string | undefined): Format[] {
+  if (!arg || arg === "webp") return ["webp"];
+  if (arg === "all") return ["webp", "gif", "mp4"];
+  const parts = arg.split(",").map((s) => s.trim());
+  const ok: Format[] = ["webp", "gif", "mp4"];
+  const bad = parts.filter((p) => !ok.includes(p as Format));
+  if (bad.length) {
+    console.error(`[video] unknown format(s): ${bad.join(", ")} (webp|gif|mp4|all)`);
+    process.exit(1);
+  }
+  return parts as Format[];
+}
+
+async function main(): Promise<void> {
+  const argv = process.argv.slice(2);
+  const flag = (name: string) => argv.find((a) => a.startsWith(`--${name}=`))?.split("=")[1];
+  const has = (name: string) => argv.includes(`--${name}`);
+
+  // Promote is a pure file op — no capture, no CDP.
+  const promoteArg = flag("promote");
+  if (promoteArg) {
+    promote(
+      promoteArg
+        .split(",")
+        .map((s) => s.trim())
+        .filter(Boolean),
+    );
+    return;
+  }
+
+  const target = flag("target") ?? "overlay";
+  if (target !== "overlay" && target !== "steam") {
+    console.error(`[video] unknown --target=${target} (overlay|steam)`);
+    process.exit(1);
+  }
+
+  if (has("list")) {
+    for (const { id, tour } of discoverTours()) {
+      console.log(
+        `  [tour]  ${id.padEnd(16)} ${tour.title ?? id}  →  plugins/${id}/assets/demo.webp`,
+      );
+    }
+    for (const c of STEAM_CLIPS) {
+      const d =
+        c.dest.kind === "plugin"
+          ? `plugins/${c.dest.id}/assets/demo`
+          : `docs/assets/${c.dest.file}`;
+      console.log(`  [steam] ${c.name.padEnd(16)} ${c.title}  →  ${d}.webp`);
+    }
+    return;
+  }
+
+  if (!Bun.which("ffmpeg")) {
+    console.error("[video] ffmpeg not found on PATH — required to encode clips.");
+    process.exit(1);
+  }
+
+  const fpsFlag = flag("fps");
+  const opts: RunOpts = {
+    formats: parseFormats(flag("format")),
+    width: Number(flag("width") ?? DEFAULT_WIDTH),
+    fpsOverride: fpsFlag ? Number(fpsFlag) : null,
+    keepFrames: has("keep-frames"),
+  };
+
+  if (target === "steam") {
+    const port = Number(flag("port") ?? 8080);
+    let clips = STEAM_CLIPS;
+    const only = flag("clips") ?? flag("clip");
+    if (only) {
+      const want = new Set(only.split(",").map((s) => s.trim()));
+      clips = STEAM_CLIPS.filter((c) => want.has(c.name));
+    }
+    console.log(
+      `[video] steam · ${clips.length} clip(s) · ${opts.width}px · ${opts.formats.join("+")}`,
+    );
+    const cdp = await CDP.connect(await steamBigPictureWs(port));
+    await captureSteamClips(cdp, clips, opts);
+    cdp.close();
+    process.exit(0);
+  }
+
+  // Default: per-plugin tours.
+  let tours = discoverTours();
+  const only = flag("plugins") ?? flag("plugin");
+  if (only) {
+    const want = only
+      .split(",")
+      .map((s) => s.trim())
+      .filter(Boolean);
+    const known = new Set(tours.map((t) => t.id));
+    const unknown = want.filter((w) => !known.has(w));
+    if (unknown.length) {
+      console.error(`[video] no tour.json for: ${unknown.join(", ")}`);
+      console.error(`[video] tours available: ${tours.map((t) => t.id).join(", ") || "(none)"}`);
+      process.exit(1);
+    }
+    tours = tours.filter((t) => want.includes(t.id));
+  }
+  if (tours.length === 0) {
+    console.error(
+      "[video] no plugin tours found — add a plugins/<id>/tour.json (see docs/media-capture.md).",
+    );
+    process.exit(1);
+  }
+
+  const font = findFont();
+  console.log(
+    `[video] tours · ${tours.length} plugin(s) · ${opts.width}px · ${fpsFlag ? `${fpsFlag}fps` : "per-tour fps"} · ${opts.formats.join("+")}${font ? "" : " · captions OFF (no font)"}`,
+  );
+  const cdp = await CDP.connect(await cdpWs());
+  for (const { id, tour } of tours) await captureTour(cdp, id, tour, font, opts);
+  cdp.close();
+  process.exit(0);
+}
+
+main();
diff --git a/scripts/lib/overlay-cdp.ts b/scripts/lib/overlay-cdp.ts
new file mode 100644
index 00000000..98feb836
--- /dev/null
+++ b/scripts/lib/overlay-cdp.ts
@@ -0,0 +1,273 @@
+/**
+ * Shared Chrome DevTools Protocol (CDP) machinery for driving the running
+ * Loadout overlay over its CEF DevTools endpoint (http://localhost:9222 in
+ * dev — baked in via electrobun.config.ts → build.linux.chromiumFlags).
+ *
+ * Both the screenshot capture (`capture-screenshots.ts`) and the video
+ * capture (`capture-videos.ts`) drive the overlay the same way: connect to
+ * the "Loadout Overlay" target, navigate the shell's hash routes, wait for
+ * the DOM to go idle, and click DOM elements to reach a plugin's internal
+ * sub-pages (which have no URL of their own). That common surface lives
+ * here so the two capture scripts stay in lock-step.
+ *
+ * The overlay shell only routes `#/`, `#/settings`, `#/plugin/<id>`; a
+ * plugin's sub-pages are internal React state reached by clicking, driven
+ * by the per-plugin recipe tables in each capture script.
+ */
+import { mkdirSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+
+// Brief settle for the route swap + first paint before we poll for idle.
+export const SETTLE_MS = 300;
+// Async-loading wait: many plugins fetch over the network on mount
+// (ProtonDB, HLTB, SteamGridDB, store libraries), so a fixed sleep either
+// over-waits or fires mid-spinner. Poll until no loading indicators remain.
+export const IDLE_TIMEOUT_MS = 8000;
+export const IDLE_POLL_MS = 200;
+// The DOM must stay idle this long before we trust it — guards the gap
+// between one fetch's spinner clearing and the next appearing.
+export const IDLE_STABLE_MS = 400;
+
+// A click target may not exist yet — plugin headers/grids that fetch data
+// (recomp, hltb, steamgriddb, launch-options) render their gear/tiles only
+// after the load resolves. Poll for the element before giving up so a slow
+// fetch doesn't read as "page absent".
+export const CLICK_TRIES = 6;
+export const CLICK_RETRY_MS = 500;
+
+export const sleep = (ms: number): Promise<void> => Bun.sleep(ms);
+
+/** Resolve the WebSocket debugger URL for the running overlay target. */
+export async function cdpWs(): Promise<string> {
+  const res = await fetch("http://localhost:9222/json");
+  const targets = (await res.json()) as Array<{
+    title?: string;
+    webSocketDebuggerUrl: string;
+  }>;
+  const overlay = targets.find((t) => t.title === "Loadout Overlay");
+  if (!overlay) {
+    console.error("overlay target not found");
+    process.exit(1);
+  }
+  return overlay.webSocketDebuggerUrl;
+}
+
+type EventHandler = (params: Record<string, unknown>) => void;
+
+export class CDP {
+  private ws!: WebSocket;
+  private id = 0;
+  private pending = new Map<number, (msg: Record<string, unknown>) => void>();
+  // CDP *events* (messages with a `method` and no `id`) are dispatched to
+  // handlers registered here. Screencast recording needs this; the
+  // request/response `pending` map above can't see events.
+  private handlers = new Map<string, Set<EventHandler>>();
+
+  static async connect(url: string): Promise<CDP> {
+    const cdp = new CDP();
+    cdp.ws = new WebSocket(url);
+    cdp.ws.addEventListener("message", (ev: MessageEvent) => {
+      const msg = JSON.parse(typeof ev.data === "string" ? ev.data : ev.data.toString());
+      // Responses carry an `id`; CDP events carry a `method` instead.
+      if (typeof msg.id === "number" && cdp.pending.has(msg.id)) {
+        cdp.pending.get(msg.id)!(msg);
+        cdp.pending.delete(msg.id);
+      } else if (typeof msg.method === "string") {
+        const hs = cdp.handlers.get(msg.method);
+        if (hs) for (const h of hs) h(msg.params ?? {});
+      }
+    });
+    await new Promise<void>((res, rej) => {
+      cdp.ws.addEventListener("open", () => res(), { once: true });
+      cdp.ws.addEventListener("error", () => rej(new Error("CDP ws error")), {
+        once: true,
+      });
+    });
+    return cdp;
+  }
+
+  call(method: string, params: Record<string, unknown> = {}): Promise<Record<string, unknown>> {
+    const id = ++this.id;
+    return new Promise((res) => {
+      this.pending.set(id, res);
+      this.ws.send(JSON.stringify({ id, method, params }));
+    });
+  }
+
+  /** Subscribe to a CDP event. Returns an unsubscribe function. */
+  on(method: string, handler: EventHandler): () => void {
+    let set = this.handlers.get(method);
+    if (!set) {
+      set = new Set();
+      this.handlers.set(method, set);
+    }
+    set.add(handler);
+    return () => set!.delete(handler);
+  }
+
+  async eval(expr: string, awaitPromise = false): Promise<unknown> {
+    const r = (await this.call("Runtime.evaluate", {
+      expression: expr,
+      returnByValue: true,
+      awaitPromise,
+    })) as { result?: { result?: { value?: unknown } } };
+    return r.result?.result?.value;
+  }
+
+  async screenshot(path: string, label?: string): Promise<void> {
+    const r = (await this.call("Page.captureScreenshot", {
+      format: "png",
+      captureBeyondViewport: false,
+    })) as { result?: { data?: string } };
+    const data = r.result?.data;
+    if (!data) throw new Error(`no data: ${JSON.stringify(r)}`);
+    mkdirSync(join(path, ".."), { recursive: true });
+    writeFileSync(path, Buffer.from(data, "base64"));
+    console.log(`  → ${label ?? path}`);
+  }
+
+  close(): void {
+    this.ws.close();
+  }
+}
+
+// ── Recipe step vocabulary ─────────────────────────────────────────────────
+//
+// A `Step` is a single CDP-driven action shared by both capture scripts.
+// `tile` clicks the first shared GameCard (`[data-game-card]`) to open a
+// detail page; `aria`/`text` click a control by aria-label / visible text
+// (gears, tabs); `wait` adds settle time; `nav` sets a shell hash route;
+// `sidebar` toggles the drawer (its expand/collapse animates, so it's a
+// useful video beat).
+export type Step =
+  | { kind: "tile" }
+  | { kind: "aria"; label: string }
+  | { kind: "text"; label: string }
+  | { kind: "wait"; ms: number }
+  | { kind: "nav"; hash: string }
+  | { kind: "sidebar"; collapsed: boolean };
+
+// "Busy" if any DaisyUI `.loading` spinner / `animate-spin` icon is
+// present, OR any *in-viewport* image hasn't finished decoding. The image
+// check is what stops us shooting game/detail art before it paints —
+// spinners alone don't cover lazy <img> loads. Off-screen lazy images are
+// ignored (they never load until scrolled to, so they'd never settle).
+export const BUSY_EXPR = `(() => {
+  if (document.querySelectorAll('.loading, [class*="animate-spin"]').length) return true;
+  const vw = innerWidth, vh = innerHeight;
+  for (const img of document.images) {
+    const r = img.getBoundingClientRect();
+    const inView = r.bottom > 0 && r.top < vh && r.right > 0 && r.left < vw && r.width > 0 && r.height > 0;
+    if (inView && (!img.complete || img.naturalWidth === 0)) return true;
+  }
+  return false;
+})()`;
+
+/**
+ * Wait until the overlay has no visible loading state — no spinners and
+ * no in-viewport image still decoding — staying clear for `IDLE_STABLE_MS`
+ * so we don't fire in the gap between two sequential fetches. Falls
+ * through after `IDLE_TIMEOUT_MS` so a perpetually-loading view still gets
+ * captured.
+ */
+export async function waitForIdle(cdp: CDP): Promise<void> {
+  const start = Date.now();
+  let idleSince: number | null = null;
+  while (Date.now() - start < IDLE_TIMEOUT_MS) {
+    const busy = (await cdp.eval(BUSY_EXPR)) === true;
+    if (busy) {
+      idleSince = null;
+    } else {
+      idleSince ??= Date.now();
+      if (Date.now() - idleSince >= IDLE_STABLE_MS) return;
+    }
+    await sleep(IDLE_POLL_MS);
+  }
+}
+
+export async function navigate(cdp: CDP, hashPath: string): Promise<void> {
+  await cdp.eval(`location.hash='${hashPath}'; void 0`);
+  await sleep(SETTLE_MS); // let the route swap + mount begin
+  await waitForIdle(cdp); // then wait out any async loading
+}
+
+export async function setSidebarCollapsed(cdp: CDP, collapsed: boolean): Promise<void> {
+  // The toggle is a Focusable button; flipping the checkbox directly
+  // updates the drawer classes but not React state. Instead click the
+  // actual button so React's onClick runs.
+  const expr = `
+  (function(){
+    const input = document.getElementById('sl-drawer');
+    if (input.checked === ${collapsed ? "false" : "true"}) return 'already';
+    const btn = document.querySelector('[aria-label="Toggle sidebar"]');
+    btn && btn.click();
+    return 'clicked';
+  })()
+  `;
+  await cdp.eval(expr);
+  await sleep(250);
+}
+
+// ── Recipe step execution ──────────────────────────────────────────────────
+
+/** Click the first element matching `selector`. Returns whether it existed. */
+export async function clickSelector(cdp: CDP, selector: string): Promise<boolean> {
+  const expr = `(() => {
+    const el = document.querySelector(${JSON.stringify(selector)});
+    if (!el) return false;
+    el.click();
+    return true;
+  })()`;
+  return (await cdp.eval(expr)) === true;
+}
+
+/** Click the first button/[role=button] whose text starts with `label`. */
+export async function clickText(cdp: CDP, label: string): Promise<boolean> {
+  const expr = `(() => {
+    const els = [...document.querySelectorAll('button, [role="button"]')];
+    const el = els.find((e) => (e.textContent || "").trim().startsWith(${JSON.stringify(label)}));
+    if (!el) return false;
+    el.click();
+    return true;
+  })()`;
+  return (await cdp.eval(expr)) === true;
+}
+
+export async function clickWithRetry(fn: () => Promise<boolean>): Promise<boolean> {
+  for (let i = 0; i < CLICK_TRIES; i++) {
+    if (await fn()) return true;
+    await sleep(CLICK_RETRY_MS);
+  }
+  return false;
+}
+
+/**
+ * Run a recipe's steps. Returns false (page unreachable) if any click
+ * target never appears. `nav`/`sidebar`/`wait` steps always succeed.
+ */
+export async function runSteps(cdp: CDP, steps: Step[]): Promise<boolean> {
+  for (const step of steps) {
+    if (step.kind === "wait") {
+      await sleep(step.ms);
+      continue;
+    }
+    if (step.kind === "nav") {
+      await navigate(cdp, step.hash);
+      continue;
+    }
+    if (step.kind === "sidebar") {
+      await setSidebarCollapsed(cdp, step.collapsed);
+      continue;
+    }
+    let ok = false;
+    if (step.kind === "tile")
+      ok = await clickWithRetry(() => clickSelector(cdp, "[data-game-card]"));
+    else if (step.kind === "aria")
+      ok = await clickWithRetry(() => clickSelector(cdp, `[aria-label="${step.label}"]`));
+    else if (step.kind === "text") ok = await clickWithRetry(() => clickText(cdp, step.label));
+    if (!ok) return false;
+    await sleep(SETTLE_MS);
+    await waitForIdle(cdp); // sub-page may fetch on open (detail pages)
+  }
+  return true;
+}
diff --git a/scripts/scaffold-plugin-readmes.ts b/scripts/scaffold-plugin-readmes.ts
index 54cdba80..e30c87af 100644
--- a/scripts/scaffold-plugin-readmes.ts
+++ b/scripts/scaffold-plugin-readmes.ts
@@ -139,9 +139,7 @@ function loadPluginMeta(id: string): PluginMeta | null {
   // `pkg.name` — that's the npm-style "@loadout/plugin-<id>"
   // which would render as ugly user-facing text.
   const name =
-    DISPLAY_NAME_OVERRIDES[id] ??
-    pickString(manifest.name, pkgPlugin.name) ??
-    toDisplayName(id);
+    DISPLAY_NAME_OVERRIDES[id] ?? pickString(manifest.name, pkgPlugin.name) ?? toDisplayName(id);
   const description =
     pickString(manifest.description, pkgPlugin.description, pkg.description) ??
     "(No description yet — add one to plugin.json or package.json:plugin.description.)";
@@ -256,8 +254,15 @@ const PLUGIN_ABOUT: Record<string, string> = {
     "Browse, install, and toggle community CSS themes for Steam's Big Picture UI, restyling the interface to taste from inside Gaming Mode.",
 };
 
+/** An animated demo clip (`assets/demo.webp`) produced by
+ *  `scripts/capture-videos.ts`, if the plugin has one. */
+function pluginDemo(id: string): string | null {
+  return existsSync(join(PLUGINS_DIR, id, "assets", "demo.webp")) ? "demo.webp" : null;
+}
+
 function templateFor(meta: PluginMeta): string {
   const shots = pluginScreenshots(meta.id);
+  const demo = pluginDemo(meta.id);
   const about = PLUGIN_ABOUT[meta.id];
   // One screenshot → show it untitled (a heading would be noise). More
   // than one → title each so the reader knows which view they're seeing.
@@ -269,16 +274,16 @@ function templateFor(meta: PluginMeta): string {
           `![${meta.name} — ${s.title}](./assets/${s.file})`,
           "",
         ])
-      : [
-          `![${meta.name}](./assets/${shots[0]?.file ?? "screenshot.png"})`,
-          "",
-        ];
+      : [`![${meta.name}](./assets/${shots[0]?.file ?? "screenshot.png"})`, ""];
   return [
     `# ${meta.name}`,
     "",
     `> ${meta.description}`,
     "",
     ...(about ? [about, ""] : []),
+    // A short animated demo (WebP) leads the media, if one was captured —
+    // it shows the plugin in motion in a way a still can't.
+    ...(demo ? ["## Demo", "", `![${meta.name} demo](./assets/${demo})`, ""] : []),
     "## Screenshots",
     "",
     ...shotBlock,
@@ -361,24 +366,12 @@ function replaceBetween(
   return { text: next, status: next === text ? "unchanged" : "updated" };
 }
 
-function updateRootGallery(
-  metas: PluginMeta[],
-): "updated" | "unchanged" | "no-markers" {
+function updateRootGallery(metas: PluginMeta[]): "updated" | "unchanged" | "no-markers" {
   const readmePath = join(ROOT, "README.md");
   let text = readFileSync(readmePath, "utf8");
-  const featured = replaceBetween(
-    text,
-    FEATURED_START,
-    FEATURED_END,
-    buildFeaturedMarkdown(metas),
-  );
+  const featured = replaceBetween(text, FEATURED_START, FEATURED_END, buildFeaturedMarkdown(metas));
   text = featured.text;
-  const gallery = replaceBetween(
-    text,
-    GALLERY_START,
-    GALLERY_END,
-    buildGalleryMarkdown(metas),
-  );
+  const gallery = replaceBetween(text, GALLERY_START, GALLERY_END, buildGalleryMarkdown(metas));
   text = gallery.text;
   if (featured.status === "no-markers" || gallery.status === "no-markers") {
     return "no-markers";