diff --git a/CLAUDE.md b/CLAUDE.md
index ac25301..eafeca5 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -65,9 +65,9 @@ Both the primary export path and blur-fill format variants (1:1, 9:16) are encod
 
 Pre-rendered WebGL shader transitions. At export time, a pre-pass extracts two boundary frames per scene boundary (last frame of outgoing, first frame of incoming) via ffmpeg, then Playwright Chromium renders the GLSL shader at each of `N = D × fps` progress values, producing a PNG sequence. `buildShaderSpliceFilter` generates a filter_complex three-segment concat (`scene_a + PNG_seq + scene_b`) that replaces the fade window.
 
-Cache key: `sha256(shader, durationMs, fps, width, height, sha256(aPng), sha256(bPng))`. Cached at `.argo/<demo>/shaders/<hash>/`. Second export with unchanged boundaries hits cache with no browser launch.
+Cache key: `sha256(shader, durationMs, fps, width, height, sha256(aPng), sha256(bPng), accent)`. Cached at `.argo/<demo>/shaders/<hash>/`. Second export with unchanged boundaries hits cache with no browser launch.
 
-Shaders live in `src/transitions/shaders/*.glsl`. Build step copies `.glsl` files to `dist/` (tsc does not). v1 ships: `crosswarp`, `swirl`, `ripple`, `luma-mask`, `light-leak` — adapted from gl-transitions.com (MIT).
+Shaders live in `src/transitions/shaders/*.glsl`. Build step copies `.glsl` files to `dist/` (tsc does not). v1 ships: `crosswarp`, `swirl`, `ripple`, `luma-mask`, `light-leak` — adapted from gl-transitions.com (MIT), plus 11 hyperframes ports (Apache-2.0): `domain-warp`, `ridged-burn`, `thermal-distortion`, `swirl-vortex`, `whip-pan`, `gravitational-lens`, `cinematic-zoom`, `chromatic-split`, `flash-through-white`, `sdf-iris`, `ripple-waves`. `export.transition.accent` (default `'#0ea5e9'`) tints accent-aware shaders: `domain-warp`, `ridged-burn`, `thermal-distortion`, `sdf-iris`, `ripple-waves`.
 
 Per-boundary shader selection is NOT supported in v1 — `export.transition.shader` applies to all boundaries. Future work: a sidecar for per-boundary overrides.
 
@@ -111,7 +111,27 @@ Static v1 blocks: `x-post`, `macos-notification`, `yt-lower-third`, `data-chart`
 
 Animated blocks (ship with `defaultMotion` using GSAP): `instagram-follow` (pulsing Follow button), `tiktok-follow` (rotating avatar ring + side slide), `reddit-post` (upvote card, simple entrance), `logo-outro` (scale-in end-card), `flowchart` (stacked nodes + arrows revealed with stagger), `app-showcase` (hero card with floating icon loop), `ui-3d-reveal` (perspective tilt-to-flat reveal of a screenshot). These use `BlockDefinition.defaultMotion` — a cue-level `motion` still overrides. Inspired by hyperframes blocks of the same names (Apache-2.0); implementations are original. Selector hooks used by motion loops/staggers: `.argo-ig-follow-btn`, `.argo-tt-ring`, `.argo-app-hero`, `.argo-3d-image`, `.argo-flow-node, .argo-flow-arrow`.
 
-Folder format is designed for a future `argo add <block>` command (not shipped yet).
+These built-in blocks ship inside the package (`src/blocks/`) — distinct from the hyperframes registry items installed into `blocksDir` by `argo add` (see HyperFrames Catalog below).
+
+### HyperFrames Catalog (`src/hf/`)
+
+`argo add <name>` installs blocks/components from the hyperframes registry (default `https://raw.githubusercontent.com/heygen-com/hyperframes/main/registry`, override via `--registry <url>` or config `registry.url`) into `blocksDir` (config, default `blocks/`, git-tracked). `argo add --list` (+ `--json`) browses the registry. Registry examples (`hyperframes:example`) are not installable. Item files are stored verbatim in native hyperframes format at `blocks/<name>/` plus a `registry-item.json` sidecar. Modules: `registry-client.ts` (fetch-injectable client — unit tests never touch the network), `add.ts` (`installItem`/`listItems`, path-traversal guards on item names and file paths), `component.ts` (snippet parser + CSS param validators), `apply-component.ts` (page injection).
+
+Overlay cue: `{ "type": "hf-component", "name": "vignette", "params": { "--vignette-size": "40%" } }` — full-frame injection (fixed, pointer-events none, high z-index) that bypasses the zone/theme/template machinery; duration comes from `showOverlay`. Script API: `applyComponent(page, name, { params?, blocksDir? })` / `removeComponent(page, name)` exported from the package — persists until removed. `params` are validated CSS custom properties (`--kebab-case` names, conservative value allowlist — no `url()`, `;{}<>`, control chars). Injection uses the same no-op `page.evaluate()` render fence as overlays and the same disposal-error-swallowing pattern as `showConfetti`.
+
+Trust model: components are trusted-at-install (user ran `argo add`, files are git-reviewable); only runtime `params` are validated. Component `<script>`s run via `new Function()` and may be blocked by strict CSP on the recorded page — logged as a warning, not a failure. Caveat: `caption-*` components install fine but word-level timing support is future work (STT alignment).
+
+`argo validate` checks that referenced hf-components are installed (`blocks/<name>/<name>.html` exists) and validates `export.transition.accent` as a 6-digit hex color.
+
+**`hf-block` cutaway cue** (`src/hf/block-render.ts`, `src/hf/block-filter.ts`): `{ type: 'hf-block', name, params?, durationMs?, fit?: 'cover' | {x,y,scale}, holdLastFrame? }`. Unlike `hf-component` (live DOM injection), `hf-block` is a no-op at recording time — it only paces the wait, nothing is injected into the page. The block's paused GSAP timeline is rendered later, at export time, by a dedicated headless Chromium pre-pass (`renderBlockFrames`) that loads the installed `blocks/<name>/<name>.html`, waits for the hyperframes convention `window.__timelines[<id>] = { duration(), pause(), seek(t) }` to register, then seeks it frame-by-frame and screenshots each frame with `omitBackground: true` for an alpha PNG sequence. `holdLastFrame` pins the timeline at its native duration instead of linearly retiming the whole animation into the window; sampling is edge-inclusive (last frame lands exactly at the window end) with an N=1 midpoint fallback.
+
+Content-addressed cache at `.argo/<demo>/hf-blocks/<hash>/` — `computeBlockHash(blockHtml, params, durationMs, fps, width, height)` — a cache hit skips the Chromium launch entirely (`renderHfBlocks` in `block-render.ts` shares one browser instance lazily across cache misses in a batch, mirroring the shader-render pre-pass pattern).
+
+`resolveHfBlockCues(rawManifest, placements)` anchors each cue to its scene's placement window: `endMs = startMs + (durationMs ?? windowMs)`, capped at the placement's own `endMs` unless the requested duration overshoots — in which case it's allowed to run into the gap after the scene, capped at the next placement's `startMs` (uncapped on the last scene; ffmpeg's `enable=between(t,...)` window is naturally clipped by the video's total duration regardless). Scenes with no matching placement are skipped with a warning, same as overlays/subtitles.
+
+Compositing (`buildHfBlockFilters`) adds one `-framerate`/`image2` input per cue and an `enable`-gated `overlay` with `eof_action=pass` — applied immediately after camera moves and overlay PNGs, before the frame effect/watermark (same layer priority as overlay PNGs). It's a pure cutaway: `-shortest` and total output duration are unaffected.
+
+Wired at all four export paths: pipeline primary, pipeline variants, CLI `argo export`, and `argo preview` export (`PreviewExportConfig` gained `blocksDir`). Blocks need network access at export time — real registry blocks load GSAP + Google Fonts from CDNs during the pre-render pass, so offline exports of demos with `hf-block` cues will fail at that step. **Known limitation:** `hf-block` + `export.speedRamp` is untested and can misalign windows — `resolveHfBlockCues` anchors windows to post-ramp scene placements (the same ones subtitles/chapters use), but the ramp's dead-time compression (`computeSegments` in `src/speed-ramp.ts`) is computed independently in source-timeline coordinates before cues are resolved. Avoid combining the two until this is verified end-to-end.
 
 ### Effects (`src/effects.ts`)
 
@@ -191,8 +211,9 @@ Custom `test` fixture extends Playwright's `test` with a `narration` fixture tha
 - `argo record/export/pipeline/validate` take bare demo names (e.g., `argo pipeline example`)
 - `argo pipeline --all` runs the full pipeline for every demo discovered in `demosDir` (finds all `.scenes.json` files)
 - `argo pipeline [demo]` — demo argument is optional when `--all` is used
-- `argo validate <demo>` checks scene name consistency between script and scenes manifest, validates overlay fields (no TTS/recording)
+- `argo validate <demo>` checks scene name consistency between script and scenes manifest, validates overlay fields, checks hf-component installs, and validates `export.transition.accent` hex (no TTS/recording)
 - `argo clip <demo> <scene>` extracts a scene clip from an exported MP4 using chapter markers. `--format gif` produces a palette-optimized GIF. Clips go to `videos/clips/`. Useful for release notes and docs.
+- `argo add <name>` installs a hyperframes registry item into `blocksDir`; `argo add --list` (+ `--json`) browses; `--registry <url>` overrides the registry (also config `registry.url`). Item names share the demo-name validation regex (path-traversal guard).
 - `--base-url <url>` flag on `record` and `pipeline` overrides `config.baseURL`
 - `--headed` flag on `record` and `pipeline` runs the browser in visible mode
 - `--all` flag on `pipeline` runs all demos in batch (sequential execution, continues on failure)
@@ -245,6 +266,7 @@ Custom `test` fixture extends Playwright's `test` with a `narration` fixture tha
 - `ARGO_SCENE_DURATIONS_PATH` — path to `.scene-durations.json` (loaded by narration fixture)
 - `ARGO_OVERLAYS_PATH` — path to `.scenes.json` manifest (loaded by overlay functions for manifest-based resolution)
 - `ARGO_AUTO_BACKGROUND` — set to `'1'` when config `overlays.autoBackground` is true
+- `ARGO_BLOCKS_DIR` — blocks directory for installed hyperframes items (loaded by `applyComponent`/hf-component cues). Set by `record()` from `config.blocksDir` at all three call sites: pipeline primary, pipeline variants, and CLI `argo record`.
 - `ARGO_ALLOW_RAW_GSAP` — set to `'1'` when config `overlays.allowRawGsap` is true. Re-checked by the runtime before executing `motion.raw` (defense in depth against inline cues that skip the validator).
 - `ARGO_OUTPUT_DIR` — output directory for timing JSON
 - `DEBUG` — when set (e.g., `DEBUG=pw:api`), Playwright debug output is forwarded to stderr even on success
@@ -319,6 +341,7 @@ Custom `test` fixture extends Playwright's `test` with a `narration` fixture tha
 - ffmpeg `gradients` source filter rejects negative `x0/y0/x1/y1` values — angle-to-coordinate conversion can produce negatives for certain angles. Always clamp.
 - `narration.mark()` does sync `appendFileSync` which can trigger app re-renders on the same event loop tick — overlay injection fence mitigates but apps with very aggressive DOM updates may still need manual `waitForTimeout()` after `mark()`.
 - `-shortest` must be skipped when frame PNG overlay is present — PNG has 0 duration and truncates the entire output.
+- `hf-block` cutaway cues are not validated in combination with `export.speedRamp` — cue windows are resolved from post-ramp placements while the ramp's gap-compression segments are computed independently in source-timeline coordinates, which can misalign the block window against the retimed video. Don't combine them until this is revisited.
 
 ## Security Invariants
 
diff --git a/README.md b/README.md
index dc6b704..3751e9a 100644
--- a/README.md
+++ b/README.md
@@ -126,6 +126,8 @@ export default defineConfig({
   baseURL: 'http://localhost:3000',
   demosDir: 'demos',
   outputDir: 'videos',
+  blocksDir: 'blocks',              // where `argo add` installs hyperframes registry items (git-tracked)
+  // registry: { url: 'https://raw.githubusercontent.com/heygen-com/hyperframes/main/registry' },
   tts: { defaultVoice: 'af_heart', defaultSpeed: 1.0 },
   video: {
     width: 1920, height: 1080, fps: 30,
@@ -219,12 +221,14 @@ argo tts generate <manifest>       Generate TTS clips from manifest
 argo export <demo>                 Merge video + audio to MP4
 argo pipeline <demo>               Run all steps end-to-end
 argo pipeline --all                Run pipeline for every demo in demosDir
-argo validate <demo>               Check scene name consistency (no TTS/recording)
+argo validate <demo>               Check scenes, overlays, installed components (no TTS/recording)
 argo preview <demo>                Browser-based editor for voiceover, overlays, timing
 argo preview                       Multi-demo dashboard (lists all demos with status)
 argo clip <demo> <scene>            Extract a scene clip from exported video
 argo clip <demo> <scene> --format gif  Extract as palette-optimized GIF
 argo import <video-file>           Import external video for post-production
+argo add <name>                    Install a block/component from the hyperframes registry into blocksDir
+argo add --list                    Browse available registry items (add --json for machine-readable)
 argo doctor                        Check environment (ffmpeg, Playwright, config)
 argo --config <path> <command>     Use a custom config file
 
@@ -234,6 +238,8 @@ Options:
   --headed                         Run browser in visible mode
   --all                            Run pipeline for all demos
   --port <number>                  Preview server port (default: auto)
+  --registry <url>                 Override the registry URL for `argo add`
+  --json                           Machine-readable output for `argo add --list`
 ```
 
 ### Overlay Blocks
@@ -279,6 +285,59 @@ Argo ships 12 curated overlay blocks for demo narratives. Reference them from `.
 | `app-showcase` | Back-eased hero entrance + slow floating icon loop |
 | `ui-3d-reveal` | Perspective tilt-to-flat reveal with a subtle wobble loop |
 
+### Catalog (`argo add`)
+
+Install ready-made overlays and components from the [hyperframes](https://github.com/heygen-com/hyperframes) registry:
+
+```bash
+argo add --list                     # browse available items
+argo add --list --json              # machine-readable
+argo add vignette                   # install into blocksDir (default: blocks/)
+argo add vignette --registry <url>  # use a different registry for one install
+```
+
+Installed items land in `blocksDir` (default `blocks/`, git-tracked — review before committing) as `blocks/<name>/<file>` plus a `registry-item.json` sidecar recording what was fetched. Registry examples aren't installable via `argo add` — install those with the hyperframes CLI instead.
+
+Use an installed component full-frame via the `hf-component` overlay cue:
+
+```json
+{ "scene": "intro", "text": "…", "overlay": { "type": "hf-component", "name": "vignette", "params": { "--vignette-size": "40%" } } }
+```
+
+`params` are CSS custom properties applied to the injected component (validated — not arbitrary CSS). The component is shown for `showOverlay`'s duration and bypasses the zone/placement system (it's full-frame, not a templated overlay).
+
+Or drive it manually from the script for effects that should persist across scenes:
+
+```ts
+import { applyComponent, removeComponent } from '@argo-video/cli';
+await applyComponent(page, 'grain-overlay');   // persists until removed
+await removeComponent(page, 'grain-overlay');
+```
+
+> **Note:** `caption-*` components install like any other item but don't yet support word-level timing (future work). Components can ship a `<script>`, but strict CSP on the recorded page may block it — a warning is logged, the recording still succeeds.
+
+Use an installed **block** as an export-time cutaway with the `hf-block` overlay cue:
+
+```json
+{
+  "scene": "outro",
+  "overlay": {
+    "type": "hf-block",
+    "name": "logo-outro",
+    "params": { "--brand-color": "#6366f1" },
+    "durationMs": 2000,
+    "fit": "cover",
+    "holdLastFrame": false
+  }
+}
+```
+
+`hf-block` is fundamentally different from `hf-component`: during recording it's a no-op (just paces the wait, nothing is injected into the page), and the block's GSAP timeline is rendered afterward — at export time — in a separate headless Chromium pass that seeks the block's `window.__timelines` entry frame-by-frame and screenshots it with a transparent background. The resulting PNG sequence is composited over the recording as a cutaway overlay (an `enable`-gated ffmpeg `overlay`), so it never changes the video's total duration. Frames are cached by content hash at `.argo/<demo>/hf-blocks/<hash>/` — an unchanged block/params/duration/fps/size combo skips the browser launch entirely on the next export.
+
+The window the block plays over defaults to the scene's placement (from mark to the next mark); `durationMs` can shrink that window or extend it into the dead time after the scene (capped at the next scene's start, or left open on the last scene). `fit` is `'cover'` (scaled to fill the frame, the default) or `{ x, y, scale }` for a positioned/scaled placement. `holdLastFrame: true` pins the block's final frame instead of linearly retiming its whole timeline into the window — useful when the window is much shorter than the block's natural animation length.
+
+Because the pre-render pass loads the real block HTML, it needs network access at export time for blocks that pull in GSAP or Google Fonts from a CDN — plan for that in CI/offline export environments. `hf-block` is also not currently compatible with `export.speedRamp`: the cutaway's window is resolved from post-ramp scene placements but the ramp's own dead-time compression is computed independently, so combining the two can misalign the block window against the retimed video. Avoid pairing them until this is revisited.
+
 ### GSAP motion (advanced)
 
 Every overlay supports two kinds of `motion`: a named CSS preset (`none`, `fade-in`, `slide-in`) or a declarative GSAP motion object with `in`, `out`, and `loop` phases. `showOverlay(page, scene, durationMs)` auto-times the exit so the visible window matches `durationMs`:
@@ -314,6 +373,7 @@ import { showConfetti } from '@argo-video/cli';
 import { spotlight, focusRing, dimAround, zoomTo, resetCamera } from '@argo-video/cli';
 import { cursorHighlight, resetCursor } from '@argo-video/cli';
 import { showCaption, hideCaption, withCaption } from '@argo-video/cli';
+import { applyComponent, removeComponent } from '@argo-video/cli';
 import { defineConfig, demosProject, engines } from '@argo-video/cli';
 ```
 
@@ -338,6 +398,8 @@ import { defineConfig, demosProject, engines } from '@argo-video/cli';
 | `showCaption(page, scene, text, durationMs)` | Show a simple text caption |
 | `withCaption(page, scene, text, action)` | Show caption during an async action |
 | `hideCaption(page)` | Remove caption |
+| `applyComponent(page, name, opts?)` | Inject an installed hyperframes component (`argo add`) full-frame; persists until removed. `opts: { params?, blocksDir? }` |
+| `removeComponent(page, name)` | Remove a component applied via `applyComponent` |
 | `narration.mark(scene)` | Record a scene timestamp |
 | `narration.durationFor(scene, opts?)` | Compute hold duration from TTS clip length (remaining time from now) |
 | `narration.sceneDuration(scene, opts?)` | Full scene duration — stable, non-decreasing (for overlay display) |
@@ -440,16 +502,23 @@ Transition types: `fade-through-black`, `dissolve` (quicker dip-to-black, not a
 Pre-rendered WebGL shader transitions between scenes, cached by content hash.
 
 ```js
-export: {
-  transition: {
-    type: 'shader',
-    shader: 'crosswarp',   // crosswarp | swirl | ripple | luma-mask | light-leak
-    durationMs: 800,
+export default defineConfig({
+  export: {
+    transition: {
+      type: 'shader',
+      shader: 'ridged-burn',
+      durationMs: 2000,
+      accent: '#0ea5e9', // tints edge glow/burn in accent-aware shaders
+    },
   },
-}
+});
 ```
 
-Shaders are adapted from [gl-transitions.com](https://gl-transitions.com) (MIT). First export launches headless Chromium to pre-render shader frames; cached at `.argo/<demo>/shaders/<hash>/` so subsequent exports skip the browser launch.
+16 shaders are available: `crosswarp`, `swirl`, `ripple`, `luma-mask`, `light-leak`, `domain-warp`, `ridged-burn`, `thermal-distortion`, `swirl-vortex`, `whip-pan`, `gravitational-lens`, `cinematic-zoom`, `chromatic-split`, `flash-through-white`, `sdf-iris`, `ripple-waves`.
+
+The first five are adapted from [gl-transitions.com](https://gl-transitions.com) (MIT); the remaining 11 are ported from [hyperframes](https://github.com/heygen-com/hyperframes) (Apache-2.0). First export launches headless Chromium to pre-render shader frames; cached at `.argo/<demo>/shaders/<hash>/` so subsequent exports skip the browser launch.
+
+`export.transition.accent` (default `'#0ea5e9'`) tints edge glow/burn in accent-aware shaders: `domain-warp`, `ridged-burn`, `thermal-distortion`, `sdf-iris`, `ripple-waves`.
 
 See `demos/shaders-showcase.demo.ts` for a complete example.
 
diff --git a/blocks/data-chart/data-chart.html b/blocks/data-chart/data-chart.html
new file mode 100644
index 0000000..3285766
--- /dev/null
+++ b/blocks/data-chart/data-chart.html
@@ -0,0 +1,457 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=1920, height=1080" />
+    <title>Data Chart</title>
+    <link rel="preconnect" href="https://fonts.googleapis.com" />
+    <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin />
+    <link
+      href="https://fonts.googleapis.com/css2?family=Libre+Baskerville:wght@400;700&family=Libre+Franklin:wght@300;400;600&display=block"
+      rel="stylesheet"
+    />
+    <script src="https://cdn.jsdelivr.net/npm/gsap@3.14.2/dist/gsap.min.js"></script>
+    <style>
+      * {
+        margin: 0;
+        padding: 0;
+        box-sizing: border-box;
+      }
+      html,
+      body {
+        margin: 0;
+        width: 1920px;
+        height: 1080px;
+        overflow: hidden;
+        background-color: #faf9f6;
+      }
+    </style>
+  </head>
+  <body>
+    <div
+      id="data-chart"
+      data-composition-id="data-chart"
+      data-width="1920"
+      data-height="1080"
+      data-start="0"
+      data-duration="15"
+    >
+      <div class="chart-container">
+        <!-- Header Section -->
+        <div class="header">
+          <h1 class="headline">Monthly Revenue vs. Conversion Rate</h1>
+          <p class="subtitle">Jan–Jun 2024, in thousands</p>
+          <div class="key">
+            <div class="key-item">
+              <div class="key-box revenue-box"></div>
+              <span class="key-text">Revenue</span>
+            </div>
+            <div class="key-item">
+              <div class="key-line conversion-line"></div>
+              <span class="key-text">Conversion Rate</span>
+            </div>
+          </div>
+        </div>
+
+        <!-- SVG Chart Area -->
+        <svg class="chart-svg" viewBox="0 0 1600 700" preserveAspectRatio="xMidYMid meet">
+          <!-- Gridlines Group -->
+          <g class="gridlines"></g>
+
+          <!-- X-Axis Labels -->
+          <g class="x-axis-labels"></g>
+
+          <!-- Bars Group (Revenue) -->
+          <g class="bars-group"></g>
+
+          <!-- Bar Labels Group -->
+          <g class="bar-labels-group"></g>
+
+          <!-- Line Group (Conversion Rate) -->
+          <g class="line-group">
+            <path class="conversion-path" fill="none" stroke="#326FA8" stroke-width="1.5" />
+            <circle class="line-dot" r="5" fill="#326FA8" style="opacity: 0" />
+          </g>
+
+          <!-- Line Labels Group -->
+          <g class="line-labels-group"></g>
+
+          <!-- Baseline -->
+          <line x1="100" y1="600" x2="1500" y2="600" stroke="black" stroke-width="1" />
+        </svg>
+
+        <!-- Source Line -->
+        <div class="source">Source: Internal analytics</div>
+      </div>
+
+      <style>
+        [data-composition-id="data-chart"] {
+          width: 1920px;
+          height: 1080px;
+          background-color: #faf9f6;
+          font-family: "Libre Franklin", sans-serif;
+          color: #333;
+          display: flex;
+          justify-content: center;
+          align-items: center;
+          overflow: hidden;
+        }
+
+        [data-composition-id="data-chart"] .chart-container {
+          width: 1600px;
+          height: 900px;
+          display: flex;
+          flex-direction: column;
+          position: relative;
+          transform: scale(1.15);
+          transform-origin: center center;
+        }
+
+        [data-composition-id="data-chart"] .header {
+          margin-bottom: 40px;
+          text-align: left;
+        }
+
+        [data-composition-id="data-chart"] .headline {
+          font-family: "Libre Baskerville", serif;
+          font-size: 42px;
+          margin: 0;
+          padding: 0;
+          clip-path: inset(0 100% 0 0);
+          white-space: nowrap;
+        }
+
+        [data-composition-id="data-chart"] .subtitle {
+          font-size: 16px;
+          color: #666;
+          margin: 8px 0 16px 0;
+          clip-path: inset(0 100% 0 0);
+          white-space: nowrap;
+        }
+
+        [data-composition-id="data-chart"] .key {
+          display: flex;
+          gap: 24px;
+          opacity: 0;
+        }
+
+        [data-composition-id="data-chart"] .key-item {
+          display: flex;
+          align-items: center;
+          gap: 8px;
+        }
+
+        [data-composition-id="data-chart"] .key-box {
+          width: 10px;
+          height: 10px;
+          background-color: #5c5c5c;
+        }
+
+        [data-composition-id="data-chart"] .key-line {
+          width: 16px;
+          height: 1.5px;
+          background-color: #326fa8;
+        }
+
+        [data-composition-id="data-chart"] .key-text {
+          font-size: 13px;
+          color: #666;
+        }
+
+        [data-composition-id="data-chart"] .chart-svg {
+          width: 100%;
+          height: 600px;
+          overflow: visible;
+        }
+
+        [data-composition-id="data-chart"] .source {
+          position: absolute;
+          bottom: 0;
+          left: 0;
+          font-size: 11px;
+          color: #999;
+          opacity: 0;
+        }
+
+        [data-composition-id="data-chart"] .grid-line {
+          stroke: #e8e8e8;
+          stroke-width: 0.5px;
+          opacity: 0;
+        }
+
+        [data-composition-id="data-chart"] .axis-label {
+          font-size: 14px;
+          fill: #666;
+          text-anchor: middle;
+        }
+
+        [data-composition-id="data-chart"] .bar {
+          fill: #5c5c5c;
+        }
+
+        [data-composition-id="data-chart"] .bar-label {
+          font-size: 14px;
+          fill: #333;
+          text-anchor: middle;
+          opacity: 0;
+        }
+
+        [data-composition-id="data-chart"] .line-label {
+          font-size: 14px;
+          fill: #326fa8;
+          font-weight: 600;
+          text-anchor: middle;
+          opacity: 0;
+        }
+      </style>
+
+      <script>
+        (function () {
+          const svg = document.querySelector('[data-composition-id="data-chart"] .chart-svg');
+          const tl = gsap.timeline({ paused: true });
+
+          // Data
+          const months = ["Jan", "Feb", "Mar", "Apr", "May", "Jun"];
+          const revenueData = [8, 12, 15, 11, 18, 22];
+          const conversionData = [2.1, 2.8, 3.2, 2.9, 3.8, 4.2];
+
+          // Chart Dimensions
+          const chartWidth = 1400;
+          const chartHeight = 500;
+          const startX = 100;
+          const startY = 600;
+          const barWidth = 80;
+          const spacing = (chartWidth - barWidth * months.length) / (months.length + 1);
+
+          // Scales
+          const maxRevenue = 25;
+          const maxConversion = 5;
+
+          const getBarY = (val) => startY - (val / maxRevenue) * chartHeight;
+          const getLineY = (val) => startY - (val / maxConversion) * chartHeight;
+          const getX = (i) => startX + spacing + i * (barWidth + spacing) + barWidth / 2;
+
+          // Setup Elements
+          const gridGroup = svg.querySelector(".gridlines");
+          const xAxisGroup = svg.querySelector(".x-axis-labels");
+          const barsGroup = svg.querySelector(".bars-group");
+          const barLabelsGroup = svg.querySelector(".bar-labels-group");
+          const lineLabelsGroup = svg.querySelector(".line-labels-group");
+          const conversionPath = svg.querySelector(".conversion-path");
+          const lineDot = svg.querySelector(".line-dot");
+
+          // Create Gridlines
+          for (let i = 1; i <= 5; i++) {
+            const y = startY - i * (chartHeight / 5);
+            const line = document.createElementNS("http://www.w3.org/2000/svg", "line");
+            line.setAttribute("x1", startX);
+            line.setAttribute("y1", y);
+            line.setAttribute("x2", startX + chartWidth);
+            line.setAttribute("y2", y);
+            line.setAttribute("class", "grid-line");
+            gridGroup.appendChild(line);
+          }
+
+          // Create X-Axis Labels & Bars & Bar Labels
+          const linePoints = [];
+          months.forEach((month, i) => {
+            const x = getX(i);
+
+            const label = document.createElementNS("http://www.w3.org/2000/svg", "text");
+            label.setAttribute("x", x);
+            label.setAttribute("y", startY + 30);
+            label.setAttribute("class", "axis-label");
+            label.textContent = month;
+            xAxisGroup.appendChild(label);
+
+            const barHeight = (revenueData[i] / maxRevenue) * chartHeight;
+            const bar = document.createElementNS("http://www.w3.org/2000/svg", "rect");
+            bar.setAttribute("x", x - barWidth / 2);
+            bar.setAttribute("y", startY);
+            bar.setAttribute("width", barWidth);
+            bar.setAttribute("height", 0);
+            bar.setAttribute("class", "bar");
+            barsGroup.appendChild(bar);
+
+            const barLabel = document.createElementNS("http://www.w3.org/2000/svg", "text");
+            barLabel.setAttribute("x", x);
+            barLabel.setAttribute("y", getBarY(revenueData[i]) - 10);
+            barLabel.setAttribute("class", "bar-label");
+            barLabel.textContent = `$${revenueData[i]}K`;
+            barLabelsGroup.appendChild(barLabel);
+
+            linePoints.push(`${x},${getLineY(conversionData[i])}`);
+
+            const lineLabel = document.createElementNS("http://www.w3.org/2000/svg", "text");
+            lineLabel.setAttribute("x", x);
+            lineLabel.setAttribute("y", getLineY(conversionData[i]) - 15);
+            lineLabel.setAttribute("class", "line-label");
+            lineLabel.textContent = `${conversionData[i]}%`;
+            lineLabelsGroup.appendChild(lineLabel);
+          });
+
+          // Set Path Data
+          conversionPath.setAttribute("d", `M ${linePoints.join(" L ")}`);
+          const pathLength = conversionPath.getTotalLength();
+          conversionPath.style.strokeDasharray = pathLength;
+          conversionPath.style.strokeDashoffset = pathLength;
+
+          // --- ANIMATION TIMELINE ---
+
+          tl.to(
+            '[data-composition-id="data-chart"] .headline',
+            {
+              clipPath: "inset(0 0% 0 0)",
+              duration: 1.2,
+              ease: "power1.inOut",
+            },
+            0,
+          );
+
+          tl.to(
+            '[data-composition-id="data-chart"] .subtitle',
+            {
+              clipPath: "inset(0 0% 0 0)",
+              duration: 1.2,
+              ease: "power1.inOut",
+            },
+            0.2,
+          );
+
+          tl.to(
+            '[data-composition-id="data-chart"] .key',
+            {
+              opacity: 1,
+              duration: 0.4,
+              ease: "power2.out",
+            },
+            1.0,
+          );
+
+          tl.to(
+            '[data-composition-id="data-chart"] .grid-line',
+            {
+              opacity: 1,
+              duration: 0.5,
+              stagger: 0.25,
+              ease: "power2.out",
+            },
+            0.5,
+          );
+
+          // Bars
+          const bars = barsGroup.querySelectorAll(".bar");
+          const barLabels = barLabelsGroup.querySelectorAll(".bar-label");
+
+          bars.forEach((bar, i) => {
+            const barHeight = (revenueData[i] / maxRevenue) * chartHeight;
+            const startTime = 1.5 + i * 0.5;
+
+            tl.to(
+              bar,
+              {
+                attr: { height: barHeight, y: startY - barHeight },
+                duration: 0.8,
+                ease: "power2.out",
+              },
+              startTime,
+            );
+
+            tl.to(
+              barLabels[i],
+              {
+                opacity: 1,
+                duration: 0.3,
+                ease: "power2.out",
+              },
+              startTime + 0.8,
+            );
+          });
+
+          // Line
+          const lastBarStartTime = 1.5 + (months.length - 1) * 0.5;
+          const lineStartTime = lastBarStartTime + 0.5;
+
+          tl.to(
+            conversionPath,
+            {
+              strokeDashoffset: 0,
+              duration: 3,
+              ease: "none",
+            },
+            lineStartTime,
+          );
+
+          // Line Dot & Labels
+          tl.set(
+            lineDot,
+            {
+              opacity: 1,
+              attr: { cx: getX(0), cy: getLineY(conversionData[0]) },
+            },
+            lineStartTime,
+          );
+
+          const lineLabels = lineLabelsGroup.querySelectorAll(".line-label");
+          months.forEach((_, i) => {
+            if (i > 0) {
+              const x = getX(i);
+              const y = getLineY(conversionData[i]);
+              tl.to(
+                lineDot,
+                {
+                  attr: { cx: x, cy: y },
+                  duration: 3 / (months.length - 1),
+                  ease: "none",
+                },
+                lineStartTime + ((i - 1) / (months.length - 1)) * 3,
+              );
+            }
+
+            const labelTime = lineStartTime + (i / (months.length - 1)) * 3 + 0.2;
+
+            lineLabels[i].textContent = "0.0%";
+
+            tl.to(
+              lineLabels[i],
+              {
+                opacity: 1,
+                duration: 0.1,
+                ease: "power2.out",
+              },
+              labelTime,
+            );
+
+            const dummy = { val: 0 };
+            tl.to(
+              dummy,
+              {
+                val: conversionData[i],
+                duration: 0.8,
+                ease: "power2.out",
+                onUpdate: () => {
+                  lineLabels[i].textContent = dummy.val.toFixed(1) + "%";
+                },
+              },
+              labelTime,
+            );
+          });
+
+          // Source Line
+          tl.to(
+            '[data-composition-id="data-chart"] .source',
+            {
+              opacity: 1,
+              duration: 0.5,
+              ease: "power2.out",
+            },
+            ">+0.5",
+          );
+
+          window.__timelines = window.__timelines || {};
+          window.__timelines["data-chart"] = tl;
+        })();
+      </script>
+    </div>
+  </body>
+</html>
diff --git a/blocks/data-chart/registry-item.json b/blocks/data-chart/registry-item.json
new file mode 100644
index 0000000..d6c8147
--- /dev/null
+++ b/blocks/data-chart/registry-item.json
@@ -0,0 +1,42 @@
+{
+  "$schema": "https://hyperframes.heygen.com/schema/registry-item.json",
+  "name": "data-chart",
+  "type": "hyperframes:block",
+  "title": "Data Chart",
+  "description": "Animated bar + line chart with staggered reveal, NYT-style typography, and value labels",
+  "tags": [
+    "data",
+    "chart",
+    "statistics"
+  ],
+  "dimensions": {
+    "width": 1920,
+    "height": 1080
+  },
+  "duration": 15,
+  "files": [
+    {
+      "path": "data-chart.html",
+      "target": "compositions/data-chart.html",
+      "type": "hyperframes:composition"
+    }
+  ],
+  "preview": {
+    "video": "https://static.heygen.ai/hyperframes-oss/docs/images/catalog/blocks/data-chart.mp4",
+    "poster": "https://static.heygen.ai/hyperframes-oss/docs/images/catalog/blocks/data-chart.png"
+  },
+  "params": [
+    {
+      "key": "--bg-color",
+      "label": "Background",
+      "type": "color",
+      "default": "#faf9f6"
+    },
+    {
+      "key": "--text-color",
+      "label": "Text color",
+      "type": "color",
+      "default": "#333333"
+    }
+  ]
+}
\ No newline at end of file
diff --git a/blocks/grain-overlay/grain-overlay.html b/blocks/grain-overlay/grain-overlay.html
new file mode 100644
index 0000000..6bd06c3
--- /dev/null
+++ b/blocks/grain-overlay/grain-overlay.html
@@ -0,0 +1,75 @@
+<!--
+  Grain Overlay — animated film grain texture.
+
+  Usage: paste this snippet into your composition's HTML.
+  The overlay covers the full viewport with pointer-events: none
+  so it sits on top of all content without blocking interaction.
+
+  Customize:
+  - opacity: adjust .grain-texture opacity (default 0.15)
+  - speed: change animation duration (default 0.5s)
+  - texture: swap the background URL for a different pattern
+  - z-index: adjust #grain-overlay z-index to layer correctly
+-->
+
+<div
+  id="grain-overlay"
+  style="
+    position: absolute;
+    top: 0;
+    left: 0;
+    width: 100%;
+    height: 100%;
+    pointer-events: none;
+    z-index: 100;
+  "
+>
+  <div class="grain-texture"></div>
+</div>
+
+<style>
+  @keyframes hf-grain-noise {
+    0%,
+    100% {
+      transform: translate(0, 0);
+    }
+    10% {
+      transform: translate(-5%, -5%);
+    }
+    20% {
+      transform: translate(-10%, 5%);
+    }
+    30% {
+      transform: translate(5%, -10%);
+    }
+    40% {
+      transform: translate(-5%, 15%);
+    }
+    50% {
+      transform: translate(-10%, 5%);
+    }
+    60% {
+      transform: translate(15%, 0);
+    }
+    70% {
+      transform: translate(0, 10%);
+    }
+    80% {
+      transform: translate(-15%, 0);
+    }
+    90% {
+      transform: translate(10%, 5%);
+    }
+  }
+
+  #grain-overlay .grain-texture {
+    position: absolute;
+    top: -50%;
+    left: -50%;
+    width: 200%;
+    height: 200%;
+    background: url("data:image/svg+xml,%3Csvg viewBox='0 0 256 256' xmlns='http://www.w3.org/2000/svg'%3E%3Cfilter id='noise'%3E%3CfeTurbulence type='fractalNoise' baseFrequency='0.65' numOctaves='3' stitchTiles='stitch'/%3E%3C/filter%3E%3Crect width='100%25' height='100%25' filter='url(%23noise)'/%3E%3C/svg%3E");
+    opacity: var(--grain-opacity, 0.15);
+    animation: hf-grain-noise 0.5s steps(1) infinite;
+  }
+</style>
diff --git a/blocks/grain-overlay/registry-item.json b/blocks/grain-overlay/registry-item.json
new file mode 100644
index 0000000..0c934ad
--- /dev/null
+++ b/blocks/grain-overlay/registry-item.json
@@ -0,0 +1,23 @@
+{
+  "$schema": "https://hyperframes.heygen.com/schema/registry-item.json",
+  "name": "grain-overlay",
+  "type": "hyperframes:component",
+  "title": "Grain Overlay",
+  "description": "Animated film grain texture overlay using CSS keyframes — adds warmth and analog character to any composition",
+  "tags": [
+    "texture",
+    "grain",
+    "overlay",
+    "film"
+  ],
+  "files": [
+    {
+      "path": "grain-overlay.html",
+      "target": "compositions/components/grain-overlay.html",
+      "type": "hyperframes:snippet"
+    }
+  ],
+  "preview": {
+    "poster": "https://static.heygen.ai/hyperframes-oss/docs/images/catalog/components/grain-overlay.png"
+  }
+}
\ No newline at end of file
diff --git a/blocks/logo-outro/logo-outro.html b/blocks/logo-outro/logo-outro.html
new file mode 100644
index 0000000..96c2808
--- /dev/null
+++ b/blocks/logo-outro/logo-outro.html
@@ -0,0 +1,226 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=1920, height=1080" />
+    <title>Logo Outro</title>
+    <link rel="preconnect" href="https://fonts.googleapis.com" />
+    <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin />
+    <link
+      href="https://fonts.googleapis.com/css2?family=Inter:wght@400;500;600;700&display=block"
+      rel="stylesheet"
+    />
+    <script src="https://cdn.jsdelivr.net/npm/gsap@3.14.2/dist/gsap.min.js"></script>
+    <style>
+      * {
+        margin: 0;
+        padding: 0;
+        box-sizing: border-box;
+      }
+      html,
+      body {
+        margin: 0;
+        width: 1920px;
+        height: 1080px;
+        overflow: hidden;
+        background: #0a0a0f;
+      }
+    </style>
+  </head>
+  <body>
+    <div
+      id="logo-outro"
+      data-composition-id="logo-outro"
+      data-width="1920"
+      data-height="1080"
+      data-start="0"
+      data-duration="6"
+    >
+      <div class="canvas">
+        <!-- Glow effect behind the logo -->
+        <div class="logo-glow"></div>
+
+        <!-- Logo Container -->
+        <div class="logo-container">
+          <svg viewBox="0 0 160 240" width="160" height="240" class="logo-svg">
+            <!-- Replace these paths with your own logo SVG -->
+            <path
+              class="logo-piece logo-tl"
+              d="M 0 40 C 0 17.9 17.9 0 40 0 L 80 0 L 80 80 L 40 80 C 17.9 80 0 62.1 0 40 Z"
+              fill="#0ea5e9"
+            />
+            <path
+              class="logo-piece logo-tr"
+              d="M 80 0 L 120 0 C 142.1 0 160 17.9 160 40 C 160 62.1 142.1 80 120 80 L 80 80 L 80 0 Z"
+              fill="#38bdf8"
+            />
+            <path
+              class="logo-piece logo-ml"
+              d="M 0 120 C 0 97.9 17.9 80 40 80 L 80 80 L 80 160 L 40 160 C 17.9 160 0 142.1 0 120 Z"
+              fill="#22d3ee"
+            />
+            <circle class="logo-piece logo-mr" cx="120" cy="120" r="40" fill="#7dd3fc" />
+            <path
+              class="logo-piece logo-bl"
+              d="M 0 200 C 0 177.9 17.9 160 40 160 L 80 160 L 80 200 C 80 222.1 62.1 240 40 240 C 17.9 240 0 222.1 0 200 Z"
+              fill="#0369a1"
+            />
+          </svg>
+        </div>
+
+        <div class="text-container">
+          <div class="tagline">Demos as code. Motion as catalog.</div>
+          <div class="url-pill">
+            <span class="url-text">argo &times; hyperframes</span>
+          </div>
+        </div>
+      </div>
+
+      <style>
+        [data-composition-id="logo-outro"] .canvas {
+          width: 1920px;
+          height: 1080px;
+          background: #0a0a0f;
+          position: relative;
+          overflow: hidden;
+          font-family: "Inter", sans-serif;
+        }
+
+        [data-composition-id="logo-outro"] .logo-container {
+          position: absolute;
+          left: 880px;
+          top: 380px;
+          width: 160px;
+          height: 240px;
+          z-index: 2;
+        }
+
+        [data-composition-id="logo-outro"] .logo-piece {
+          transform-origin: center center;
+          opacity: 0;
+        }
+
+        [data-composition-id="logo-outro"] .logo-glow {
+          position: absolute;
+          left: 760px;
+          top: 300px;
+          width: 400px;
+          height: 400px;
+          background: radial-gradient(circle, rgba(162, 89, 255, 0.25) 0%, rgba(10, 10, 15, 0) 70%);
+          border-radius: 50%;
+          opacity: 0;
+          pointer-events: none;
+          z-index: 1;
+        }
+
+        [data-composition-id="logo-outro"] .text-container {
+          position: absolute;
+          top: 720px;
+          width: 100%;
+          display: flex;
+          flex-direction: column;
+          align-items: center;
+          z-index: 3;
+        }
+
+        [data-composition-id="logo-outro"] .tagline {
+          font-size: 44px;
+          font-weight: 500;
+          color: white;
+          opacity: 0;
+          margin-bottom: 32px;
+          text-align: center;
+        }
+
+        [data-composition-id="logo-outro"] .url-pill {
+          background: #1a1a1f;
+          border: 1px solid #2c2c2c;
+          border-radius: 100px;
+          padding: 8px 24px;
+          opacity: 0;
+          display: flex;
+          align-items: center;
+          justify-content: center;
+        }
+
+        [data-composition-id="logo-outro"] .url-text {
+          font-size: 18px;
+          color: #666;
+          letter-spacing: 0.5px;
+        }
+      </style>
+
+      <script>
+        (function () {
+          const tl = gsap.timeline({ paused: true });
+
+          const pieces = {
+            tl: '[data-composition-id="logo-outro"] .logo-tl',
+            tr: '[data-composition-id="logo-outro"] .logo-tr',
+            ml: '[data-composition-id="logo-outro"] .logo-ml',
+            mr: '[data-composition-id="logo-outro"] .logo-mr',
+            bl: '[data-composition-id="logo-outro"] .logo-bl',
+          };
+
+          const pieceArray = [pieces.tl, pieces.tr, pieces.ml, pieces.mr, pieces.bl];
+          const logoGlow = '[data-composition-id="logo-outro"] .logo-glow';
+          const tagline = '[data-composition-id="logo-outro"] .tagline';
+          const urlPill = '[data-composition-id="logo-outro"] .url-pill';
+
+          // 1. Pieces slide in from the right with ripple stagger
+          pieceArray.forEach((piece, i) => {
+            tl.fromTo(
+              piece,
+              { x: 1920, opacity: 0 },
+              { x: 0, opacity: 1, duration: 1.2, ease: "power4.out" },
+              i * 0.08,
+            );
+          });
+
+          // 2. Expand and close
+          const expandTime = 1.2;
+
+          tl.to(
+            pieceArray,
+            { scale: 1.15, duration: 0.5, ease: "back.out(1.7)", stagger: 0.02 },
+            expandTime,
+          );
+
+          tl.to(pieceArray, { scale: 1, duration: 0.4, ease: "power2.inOut" }, expandTime + 0.3);
+
+          // 3. Glow bloom
+          tl.fromTo(
+            logoGlow,
+            { opacity: 0, scale: 0.5 },
+            { opacity: 1, scale: 1.2, duration: 0.4, ease: "power2.out" },
+            expandTime,
+          );
+          tl.to(
+            logoGlow,
+            { opacity: 0, scale: 1.8, duration: 1.2, ease: "power2.out" },
+            expandTime + 0.4,
+          );
+
+          // 4. Tagline and URL pill fade in
+          const textStartTime = expandTime + 0.8;
+          tl.fromTo(
+            tagline,
+            { opacity: 0, y: 20 },
+            { opacity: 1, y: 0, duration: 1, ease: "power3.out" },
+            textStartTime,
+          );
+
+          tl.fromTo(
+            urlPill,
+            { opacity: 0, y: 15 },
+            { opacity: 1, y: 0, duration: 0.8, ease: "power3.out" },
+            textStartTime + 0.4,
+          );
+
+          window.__timelines = window.__timelines || {};
+          window.__timelines["logo-outro"] = tl;
+        })();
+      </script>
+    </div>
+  </body>
+</html>
diff --git a/blocks/logo-outro/registry-item.json b/blocks/logo-outro/registry-item.json
new file mode 100644
index 0000000..a44c982
--- /dev/null
+++ b/blocks/logo-outro/registry-item.json
@@ -0,0 +1,42 @@
+{
+  "$schema": "https://hyperframes.heygen.com/schema/registry-item.json",
+  "name": "logo-outro",
+  "type": "hyperframes:block",
+  "title": "Logo Outro",
+  "description": "Cinematic logo reveal with piece-by-piece assembly, glow bloom, tagline fade-in, and URL pill",
+  "tags": [
+    "branding",
+    "outro",
+    "logo"
+  ],
+  "dimensions": {
+    "width": 1920,
+    "height": 1080
+  },
+  "duration": 6,
+  "files": [
+    {
+      "path": "logo-outro.html",
+      "target": "compositions/logo-outro.html",
+      "type": "hyperframes:composition"
+    }
+  ],
+  "preview": {
+    "video": "https://static.heygen.ai/hyperframes-oss/docs/images/catalog/blocks/logo-outro.mp4",
+    "poster": "https://static.heygen.ai/hyperframes-oss/docs/images/catalog/blocks/logo-outro.png"
+  },
+  "params": [
+    {
+      "key": "--bg-color",
+      "label": "Background",
+      "type": "color",
+      "default": "#0a0a0f"
+    },
+    {
+      "key": "--accent-color",
+      "label": "Accent",
+      "type": "color",
+      "default": "#1a1a1f"
+    }
+  ]
+}
\ No newline at end of file
diff --git a/blocks/shimmer-sweep/registry-item.json b/blocks/shimmer-sweep/registry-item.json
new file mode 100644
index 0000000..aa8cde1
--- /dev/null
+++ b/blocks/shimmer-sweep/registry-item.json
@@ -0,0 +1,23 @@
+{
+  "$schema": "https://hyperframes.heygen.com/schema/registry-item.json",
+  "name": "shimmer-sweep",
+  "type": "hyperframes:component",
+  "title": "Shimmer Sweep",
+  "description": "Animated light sweep across text or elements using a CSS gradient mask — ideal for AI accents and premium reveals",
+  "tags": [
+    "text",
+    "shimmer",
+    "highlight",
+    "effect"
+  ],
+  "files": [
+    {
+      "path": "shimmer-sweep.html",
+      "target": "compositions/components/shimmer-sweep.html",
+      "type": "hyperframes:snippet"
+    }
+  ],
+  "preview": {
+    "poster": "https://static.heygen.ai/hyperframes-oss/docs/images/catalog/components/shimmer-sweep.png"
+  }
+}
\ No newline at end of file
diff --git a/blocks/shimmer-sweep/shimmer-sweep.html b/blocks/shimmer-sweep/shimmer-sweep.html
new file mode 100644
index 0000000..84d3be4
--- /dev/null
+++ b/blocks/shimmer-sweep/shimmer-sweep.html
@@ -0,0 +1,66 @@
+<!--
+  Shimmer Sweep — animated light pass across text or elements.
+
+  Usage: place this snippet AFTER your .shimmer-sweep-target elements.
+  Wrap your text element with class="shimmer-sweep-target" and
+  paste this snippet into your composition. The GSAP timeline drives
+  the sweep position for deterministic frame-by-frame rendering.
+
+  Customize:
+  - --shimmer-color: highlight color (default rgba(255,255,255,0.6))
+  - --shimmer-width: highlight band width as % (default 20%)
+  - --shimmer-angle: sweep angle (default 120deg)
+  - Timeline duration/ease: adjust in the script below
+-->
+
+<style>
+  .shimmer-sweep-target {
+    position: relative;
+    display: inline-block;
+  }
+
+  .shimmer-sweep-target .shimmer-mask {
+    position: absolute;
+    top: 0;
+    left: 0;
+    width: 100%;
+    height: 100%;
+    pointer-events: none;
+    background: linear-gradient(
+      var(--shimmer-angle, 120deg),
+      transparent 0%,
+      transparent calc(var(--shimmer-pos, -20%) - var(--shimmer-width, 20%) / 2),
+      var(--shimmer-color, rgba(255, 255, 255, 0.6)) var(--shimmer-pos, -20%),
+      transparent calc(var(--shimmer-pos, -20%) + var(--shimmer-width, 20%) / 2),
+      transparent 100%
+    );
+    mix-blend-mode: overlay;
+  }
+</style>
+
+<script>
+  (function () {
+    // Auto-inject .shimmer-mask into every .shimmer-sweep-target
+    document.querySelectorAll(".shimmer-sweep-target").forEach((el) => {
+      if (!el.querySelector(".shimmer-mask")) {
+        const mask = document.createElement("div");
+        mask.className = "shimmer-mask";
+        el.appendChild(mask);
+      }
+    });
+  })();
+</script>
+
+<!--
+  Timeline integration example (add to your composition's GSAP timeline):
+
+  // Single sweep from left to right
+  tl.fromTo(".shimmer-sweep-target", {
+    "--shimmer-pos": "-20%",
+  }, {
+    "--shimmer-pos": "120%",
+    duration: 1.2,
+    ease: "power2.inOut",
+    stagger: 0.15,
+  }, startTime);
+-->
diff --git a/blocks/vignette/registry-item.json b/blocks/vignette/registry-item.json
new file mode 100644
index 0000000..a1c0283
--- /dev/null
+++ b/blocks/vignette/registry-item.json
@@ -0,0 +1,23 @@
+{
+  "$schema": "https://hyperframes.heygen.com/schema/registry-item.json",
+  "name": "vignette",
+  "type": "hyperframes:component",
+  "title": "Vignette",
+  "description": "Cinematic radial vignette overlay using a pure-CSS gradient — darkens the edges to pull focus toward the center",
+  "tags": [
+    "vignette",
+    "overlay",
+    "cinematic",
+    "effect"
+  ],
+  "files": [
+    {
+      "path": "vignette.html",
+      "target": "compositions/components/vignette.html",
+      "type": "hyperframes:snippet"
+    }
+  ],
+  "preview": {
+    "poster": "https://static.heygen.ai/hyperframes-oss/docs/images/catalog/components/vignette.png"
+  }
+}
\ No newline at end of file
diff --git a/blocks/vignette/vignette.html b/blocks/vignette/vignette.html
new file mode 100644
index 0000000..18ba2d0
--- /dev/null
+++ b/blocks/vignette/vignette.html
@@ -0,0 +1,51 @@
+<!--
+  Vignette — cinematic radial darkening overlay.
+
+  Usage: paste this snippet inside your composition's positioned stage.
+  The overlay covers the full viewport with pointer-events: none so it
+  sits on top of all content without blocking interaction.
+
+  Customize:
+  - --vignette-color: edge color and alpha (default rgba(0, 0, 0, 0.7))
+  - --vignette-size: where the transparent center ends (default 45%)
+  - --vignette-edge: where the color reaches its final stop (default 100%)
+  - --vignette-shape: ellipse | circle (default ellipse)
+  - z-index: defaults to 90 so grain-overlay (100) reads on top
+-->
+
+<div
+  id="hf-vignette"
+  style="
+    position: absolute;
+    top: 0;
+    left: 0;
+    width: 100%;
+    height: 100%;
+    pointer-events: none;
+    z-index: 90;
+  "
+></div>
+
+<style>
+  #hf-vignette {
+    background: radial-gradient(
+      var(--vignette-shape, ellipse) at center,
+      transparent var(--vignette-size, 45%),
+      var(--vignette-color, rgba(0, 0, 0, 0.7)) var(--vignette-edge, 100%)
+    );
+  }
+</style>
+
+<!--
+  Timeline integration example (add to your composition's GSAP timeline):
+
+  // Fade the vignette in over the first second
+  tl.fromTo("#hf-vignette",
+    { "--vignette-color": "rgba(0, 0, 0, 0)" },
+    { "--vignette-color": "rgba(0, 0, 0, 0.7)", duration: 1, ease: "power2.out" },
+    0,
+  );
+
+  // Or breathe the size in and out (works with any easing)
+  tl.to("#hf-vignette", { "--vignette-size": "35%", duration: 1, ease: "sine.inOut" }, 2);
+-->
diff --git a/demos/hyperframes-showcase.config.mjs b/demos/hyperframes-showcase.config.mjs
new file mode 100644
index 0000000..702b5bb
--- /dev/null
+++ b/demos/hyperframes-showcase.config.mjs
@@ -0,0 +1,35 @@
+import { defineConfig } from '@argo-video/cli';
+
+export default defineConfig({
+  baseURL: 'http://localhost:8976',
+  demosDir: 'demos',
+  outputDir: 'videos',
+  blocksDir: 'blocks',
+  tts: { defaultVoice: 'af_heart', defaultSpeed: 1.0 },
+  video: {
+    width: 1920,
+    height: 1080,
+    fps: 30,
+    browser: 'chromium',
+    captureMode: 'jpeg-stitch',
+    // q88 (not 95): the catalog scene captures a playing video preview —
+    // q95 frames of video noise saturate the stitch writer.
+    jpegQuality: 88,
+    // The live-site scenes occasionally wedge the renderer under screencast;
+    // one retry re-runs the demo rather than failing the pipeline.
+    retries: 1,
+    showActions: false,
+  },
+  export: {
+    preset: 'slow',
+    // Dark story-page backdrops — same banding rationale as the main showcase.
+    crf: 14,
+    encoder: 'cpu',
+    // Track 1 dogfood: hyperframes-ported shader at every boundary, tinted
+    // with the brand accent (domain-warp uses accentDark/accentBright for its
+    // edge glow).
+    // whip-pan: fast camera-language cut — matches the "choreography" thesis
+    // and never smears on-screen text the way long warps do.
+    transition: { type: 'shader', shader: 'whip-pan', durationMs: 1600, accent: '#0ea5e9' },
+  },
+});
diff --git a/demos/hyperframes-showcase.demo.ts b/demos/hyperframes-showcase.demo.ts
new file mode 100644
index 0000000..bccc75d
--- /dev/null
+++ b/demos/hyperframes-showcase.demo.ts
@@ -0,0 +1,213 @@
+/**
+ * Argo × HyperFrames — comprehensive "full tour" showcase.
+ *
+ * Covers every major feature of both systems in one take:
+ *   argo: multi-voice TTS, all overlay templates + blocks, GSAP motion,
+ *         spotlight/focusRing/dimAround, post-export zoomTo, cursorHighlight,
+ *         confetti (burst + emoji), freeze-frame hold, 16 shader transitions,
+ *         chapters/subtitles/meta (narrated).
+ *   hyperframes: 142-item catalog (live site), vignette/grain/shimmer-sweep
+ *         components, data-chart block cutaway, edited logo-outro end card.
+ *
+ * Prerequisites:
+ *   1. npx argo add vignette grain-overlay shimmer-sweep data-chart logo-outro (one per call)
+ *   2. python3 -m http.server 8976 --directory demos
+ *   3. npx tsx bin/argo.js pipeline hyperframes-showcase --config demos/hyperframes-showcase.config.mjs
+ */
+import { test } from '@argo-video/cli';
+import { showOverlay, applyComponent, showConfetti } from '@argo-video/cli';
+import { zoomTo, spotlight, focusRing, dimAround, resetCamera } from '@argo-video/cli';
+import { cursorHighlight, resetCursor } from '@argo-video/cli';
+
+test('hyperframes-showcase', async ({ page, narration }) => {
+  // 15 min: the recording is ~3.5 min of content, but a loaded machine can
+  // run the screencast writer 2x+ slower — give slow runs room to finish
+  // rather than dying at the outro (mark-drift clamps handle the rest).
+  test.setTimeout(900_000);
+
+  await page.goto('/hyperframes-showcase.html');
+  await page.waitForTimeout(700);
+
+  await narration.startRecording(page);
+
+  // ── 1. hook ───────────────────────────────────────────────────────────────
+  narration.mark('hook');
+  const hookMs = narration.sceneDuration('hook');
+  void showOverlay(page, 'hook', Math.floor(hookMs * 0.75));
+  await page.waitForTimeout(narration.durationFor('hook'));
+
+  // ── 2. catalog (live site — three movements for energy) ─────────────────
+  // Screencast + jpeg-stitch note: pages full of autoplaying <video> saturate
+  // the frame writer (every frame unique, huge q-JPEGs) — the showcase grid
+  // wedged two runs. m1 instead rides the catalog page: rapid scrolls down the
+  // 142-item sidebar read as "the catalog is huge" with zero video decode.
+  await page.goto('https://hyperframes.heygen.com/catalog', {
+    waitUntil: 'domcontentloaded',
+    timeout: 20_000,
+  });
+  await page.waitForTimeout(1400);
+  narration.mark('catalog');
+  cursorHighlight(page, { color: '#0ea5e9', radius: 16 });
+  await page.mouse.move(160, 560, { steps: 20 });
+  for (const dy of [900, 1100, 1300]) {
+    await page.mouse.wheel(0, dy);
+    await page.waitForTimeout(850);
+  }
+  await page.waitForTimeout(600);
+
+  // m2: hard cut into a flashy catalog item, preview playing, punch-zoom.
+  // NOTE: deliberately a page whose own content is static (the motion is the
+  // <video> preview). Liquid-glass pages run live backdrop-filter demos that
+  // crush the renderer under swiftshader + screencast (10-minute stall).
+  await page.goto('https://hyperframes.heygen.com/catalog/blocks/glitch', {
+    waitUntil: 'domcontentloaded',
+    timeout: 20_000,
+  });
+  await page.waitForTimeout(900);
+  await page.evaluate(() => {
+    const v = document.querySelector('video');
+    if (v) {
+      v.muted = true;
+      v.scrollIntoView({ block: 'center' });
+      void v.play();
+    }
+  });
+  await page.waitForTimeout(400);
+  await zoomTo(page, 'video', { scale: 1.5, duration: 2600, holdMs: 2600, narration });
+  await page.waitForTimeout(3600);
+  // Stop the preview before leaving — a decoding <video> left behind keeps
+  // the screencast frame writer churning long after the scene.
+  await page.evaluate(() => document.querySelector('video')?.pause());
+
+  // m3: camera settles — lower-third rides the tail.
+  const catalogTail = Math.max(2500, narration.durationFor('catalog'));
+  void showOverlay(page, 'catalog', catalogTail - 400);
+  await page.waitForTimeout(narration.durationFor('catalog'));
+  resetCursor(page);
+
+  // ── 3. argo ───────────────────────────────────────────────────────────────
+  await page.goto('/hyperframes-showcase.html#argo', { waitUntil: 'domcontentloaded' });
+  await page.locator('#argo').scrollIntoViewIfNeeded();
+  await page.waitForTimeout(500);
+  narration.mark('argo');
+  await page.waitForTimeout(narration.durationFor('argo'));
+
+  // ── 4. voices (narrator swap — keep the frame calm) ─────────────────────
+  narration.mark('voices');
+  await page.waitForTimeout(narration.durationFor('voices'));
+
+  // ── 5. overlays (template sequence via inline cues) ──────────────────────
+  await page.locator('#overlays').scrollIntoViewIfNeeded();
+  await page.waitForTimeout(500);
+  narration.mark('overlays');
+  const overlaysMs = narration.sceneDuration('overlays');
+  const beat = Math.floor(overlaysMs / 3.4);
+  void showOverlay(page, 'overlays', { type: 'callout', text: 'callout — point at anything', placement: 'top-right' }, beat);
+  await page.waitForTimeout(beat);
+  void showOverlay(page, 'overlays', { type: 'arrow', direction: 'up', label: 'arrow annotation', placement: 'bottom-left' }, beat);
+  await page.waitForTimeout(beat);
+  void showOverlay(
+    page,
+    'overlays',
+    {
+      type: 'block',
+      block: 'x-post',
+      props: {
+        handle: '@argo_video',
+        name: 'Argo',
+        body: 'Blocks are overlays too — this post is the x-post block from argo’s catalog.',
+        verified: true,
+      },
+      placement: 'bottom-right',
+    },
+    beat,
+  );
+  await page.waitForTimeout(narration.durationFor('overlays'));
+
+  // ── 6. camera (spotlight → focusRing → dimAround) ────────────────────────
+  await page.locator('#camera').scrollIntoViewIfNeeded();
+  await page.waitForTimeout(500);
+  narration.mark('camera');
+  cursorHighlight(page, { color: '#0ea5e9', radius: 18 });
+  const cameraMs = narration.sceneDuration('camera');
+  const camBeat = Math.floor(cameraMs / 3.5);
+  spotlight(page, '#cam-spotlight', { duration: camBeat });
+  await page.waitForTimeout(camBeat);
+  focusRing(page, '#cam-focus', { duration: camBeat });
+  await page.waitForTimeout(camBeat);
+  dimAround(page, '#cam-dim', { duration: camBeat });
+  await page.waitForTimeout(narration.durationFor('camera'));
+  await resetCamera(page);
+  resetCursor(page);
+
+  // ── 7. zoom (post-export zoompan on the zoomTo card) ─────────────────────
+  narration.mark('zoom');
+  const zoomMs = narration.sceneDuration('zoom');
+  await zoomTo(page, '#cam-zoom', { scale: 1.55, duration: 3000, holdMs: Math.floor(zoomMs * 0.3), narration });
+  await page.waitForTimeout(narration.durationFor('zoom'));
+
+  // ── 8. chart (hf-block cutaway covers the frame at export) ──────────────
+  narration.mark('chart');
+  await page.waitForTimeout(narration.durationFor('chart'));
+
+  // ── 9. components (vignette + grain + shimmer sweep) ─────────────────────
+  await page.locator('#components').scrollIntoViewIfNeeded();
+  await page.waitForTimeout(500);
+  narration.mark('components');
+  const compMs = narration.sceneDuration('components');
+  await page.waitForTimeout(Math.floor(compMs * 0.25));
+  await applyComponent(page, 'vignette', { params: { '--vignette-size': '50%' } });
+  await page.waitForTimeout(Math.floor(compMs * 0.3));
+  // shimmer-sweep injects masks into .shimmer-sweep-target; the sweep position
+  // is a CSS var normally driven by a composition timeline — drive it with a
+  // small rAF loop here (two passes).
+  await applyComponent(page, 'shimmer-sweep');
+  await page.evaluate(() => {
+    const start = performance.now();
+    const sweep = (now: number) => {
+      const t = (now - start) / 1400; // 1.4s per pass
+      const pass = t % 1;
+      document.documentElement.style.setProperty('--shimmer-pos', `${-20 + pass * 140}%`);
+      if (t < 2) requestAnimationFrame(sweep);
+      else document.documentElement.style.setProperty('--shimmer-pos', '120%');
+    };
+    requestAnimationFrame(sweep);
+  });
+  await page.waitForTimeout(narration.durationFor('components'));
+
+  // ── 10. effects (confetti + freeze hold at the peak) ─────────────────────
+  await page.locator('#effects').scrollIntoViewIfNeeded();
+  await page.waitForTimeout(500);
+  narration.mark('effects');
+  // Fixed offsets so the manifest freeze (atMs 6000) catches confetti mid-air:
+  // burst at 4.0s (3s life), emoji rain at 5.2s — at 6.0s both are airborne.
+  await page.waitForTimeout(4000);
+  void showConfetti(page, { spread: 'burst', pieces: 180 });
+  await page.waitForTimeout(1200);
+  void showConfetti(page, { spread: 'rain', emoji: ['🚀', '⭐'], pieces: 90, duration: 3200 });
+  await page.waitForTimeout(narration.durationFor('effects'));
+
+  // ── 11. shaders ───────────────────────────────────────────────────────────
+  await page.locator('#shaders').scrollIntoViewIfNeeded();
+  await page.waitForTimeout(500);
+  narration.mark('shaders');
+  await page.waitForTimeout(narration.durationFor('shaders'));
+
+  // ── 12. better together ───────────────────────────────────────────────────
+  await page.locator('#better').scrollIntoViewIfNeeded();
+  await page.waitForTimeout(500);
+  narration.mark('better');
+  const betterMs = narration.sceneDuration('better');
+  await page.waitForTimeout(Math.floor(betterMs * 0.4));
+  void showOverlay(page, 'better', Math.floor(betterMs * 0.5));
+  await page.waitForTimeout(narration.durationFor('better'));
+
+  // ── 13. outro (logo-outro composites over this at export) ────────────────
+  await page.locator('#outro').scrollIntoViewIfNeeded();
+  await page.waitForTimeout(500);
+  narration.mark('outro');
+  await page.waitForTimeout(narration.durationFor('outro'));
+  // Tail buffer: jpeg-stitch frame drops make the assembled video slightly
+  // shorter than wall-clock, so keep the last mark off the video's edge.
+  await page.waitForTimeout(1500);
+});
diff --git a/demos/hyperframes-showcase.html b/demos/hyperframes-showcase.html
new file mode 100644
index 0000000..2dedce0
--- /dev/null
+++ b/demos/hyperframes-showcase.html
@@ -0,0 +1,233 @@
+<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8" />
+<meta name="viewport" content="width=device-width, initial-scale=1" />
+<title>Argo × HyperFrames</title>
+<style>
+  * { margin: 0; padding: 0; box-sizing: border-box; }
+  :root {
+    --accent: #0ea5e9;
+    --accent-bright: #7dd3fc;
+    --ink: #f5f7fa;
+    --muted: rgba(245, 247, 250, 0.62);
+    --bg: #07090d;
+  }
+  html, body { background: var(--bg); color: var(--ink); }
+  body {
+    font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", system-ui, sans-serif;
+    -webkit-font-smoothing: antialiased;
+    overflow-x: hidden;
+  }
+  section {
+    min-height: 100vh;
+    display: flex;
+    flex-direction: column;
+    justify-content: center;
+    padding: 8vh 9vw;
+    position: relative;
+  }
+  .kicker {
+    font-size: 15px;
+    font-weight: 700;
+    letter-spacing: 0.22em;
+    text-transform: uppercase;
+    color: var(--accent);
+    margin-bottom: 26px;
+  }
+  h1 {
+    font-size: clamp(56px, 7.2vw, 118px);
+    font-weight: 800;
+    letter-spacing: -0.035em;
+    line-height: 1.02;
+    max-width: 15ch;
+  }
+  h1 .dim { color: var(--muted); }
+  h1 .glow { color: var(--accent-bright); }
+  .sub {
+    margin-top: 30px;
+    font-size: clamp(19px, 1.6vw, 26px);
+    line-height: 1.55;
+    color: var(--muted);
+    max-width: 52ch;
+  }
+  .sub strong { color: var(--ink); font-weight: 650; }
+  code.cmd {
+    display: inline-block;
+    margin-top: 34px;
+    padding: 16px 26px;
+    border-radius: 12px;
+    background: rgba(14, 165, 233, 0.09);
+    border: 1px solid rgba(14, 165, 233, 0.35);
+    font-family: ui-monospace, "SF Mono", Menlo, monospace;
+    font-size: clamp(17px, 1.4vw, 23px);
+    color: var(--accent-bright);
+  }
+  code.cmd .p { color: var(--muted); }
+
+  /* hook backdrop: faint radial wash + grid */
+  #hook::before {
+    content: "";
+    position: absolute; inset: 0;
+    background:
+      radial-gradient(1100px 620px at 76% 22%, rgba(14, 165, 233, 0.16), transparent 62%),
+      radial-gradient(800px 520px at 12% 88%, rgba(56, 189, 248, 0.08), transparent 60%);
+    pointer-events: none;
+  }
+  #hook::after {
+    content: "";
+    position: absolute; inset: 0;
+    background-image:
+      linear-gradient(rgba(245,247,250,0.035) 1px, transparent 1px),
+      linear-gradient(90deg, rgba(245,247,250,0.035) 1px, transparent 1px);
+    background-size: 72px 72px;
+    mask-image: radial-gradient(900px 600px at 70% 30%, black, transparent 75%);
+    pointer-events: none;
+  }
+
+  /* pillars row on #better */
+  .pillars {
+    margin-top: 54px;
+    display: grid;
+    grid-template-columns: 1fr auto 1fr;
+    gap: 40px;
+    align-items: center;
+    max-width: 1180px;
+  }
+  .pillar {
+    padding: 34px 36px;
+    border-radius: 18px;
+    background: rgba(245, 247, 250, 0.04);
+    border: 1px solid rgba(245, 247, 250, 0.09);
+  }
+  .pillar h3 {
+    font-size: 26px;
+    font-weight: 750;
+    letter-spacing: -0.015em;
+    margin-bottom: 12px;
+  }
+  .pillar p { color: var(--muted); font-size: 18px; line-height: 1.55; }
+  .pillar .tag { font-size: 13px; font-weight: 700; letter-spacing: 0.18em; color: var(--accent); text-transform: uppercase; display: block; margin-bottom: 14px; }
+  .times {
+    font-size: 54px;
+    font-weight: 300;
+    color: var(--accent);
+    text-align: center;
+  }
+
+  .stat-row { margin-top: 46px; display: flex; gap: 64px; }
+  .stat .n { font-size: clamp(44px, 4.6vw, 76px); font-weight: 800; letter-spacing: -0.03em; color: var(--accent-bright); }
+  .stat .l { margin-top: 6px; font-size: 16px; color: var(--muted); letter-spacing: 0.04em; }
+
+  .shader-grid {
+    margin-top: 46px;
+    display: grid;
+    grid-template-columns: repeat(4, minmax(0, 1fr));
+    gap: 14px;
+    max-width: 1080px;
+    font-family: ui-monospace, "SF Mono", Menlo, monospace;
+    font-size: 17px;
+  }
+  .shader-grid span {
+    padding: 14px 18px;
+    border-radius: 10px;
+    background: rgba(245, 247, 250, 0.04);
+    border: 1px solid rgba(245, 247, 250, 0.09);
+    color: var(--muted);
+    text-align: center;
+  }
+  .shader-grid span.hot {
+    color: var(--accent-bright);
+    border-color: rgba(14, 165, 233, 0.5);
+    background: rgba(14, 165, 233, 0.10);
+  }
+
+  /* outro backdrop — intentionally quiet; the logo-outro block composites over it */
+  #outro { align-items: center; text-align: center; }
+  #outro .sub { margin-top: 18px; }
+  #outro h1 { max-width: none; }
+</style>
+</head>
+<body>
+
+<section id="hook">
+  <div class="kicker">Argo &times; HyperFrames</div>
+  <h1>Product demos,<br /><span class="glow">but cinematic.</span></h1>
+  <p class="sub">This video is <strong>choreography, not screen capture</strong>. Playwright drives the browser. Argo directs the film. HyperFrames supplies the motion — <strong>no editor, no timeline, no re-takes</strong>.</p>
+</section>
+
+<section id="argo">
+  <div class="kicker">Meet Argo</div>
+  <h1>Record the <span class="glow">real thing.</span></h1>
+  <p class="sub">Not a screen recorder — <strong>the full power of Playwright, pointed at filmmaking</strong>. Real navigation, real clicks, real waits: your product driven the way users drive it, then narrated, directed, and exported. <strong>One command, end to end</strong>.</p>
+  <code class="cmd"><span class="p">$</span> argo pipeline my-demo</code>
+</section>
+
+<section id="overlays">
+  <div class="kicker">Argo overlays</div>
+  <h1>Five templates.<br /><span class="glow">Plus blocks.</span></h1>
+  <p class="sub">Lower-thirds, headline cards, callouts, arrows, image cards — and a curated block catalog. All GSAP-animated, all driven from a <strong>JSON manifest</strong>.</p>
+</section>
+
+<section id="camera">
+  <div class="kicker">Camera direction</div>
+  <h1>Direct the <span class="glow">viewer's eye.</span></h1>
+  <div class="pillars" style="grid-template-columns: 1fr 1fr; max-width: 1080px; gap: 28px; margin-top: 44px;">
+    <div class="pillar" id="cam-spotlight"><span class="tag">spotlight()</span><h3>Spotlight</h3><p>Dim everything but the point of interest.</p></div>
+    <div class="pillar" id="cam-focus"><span class="tag">focusRing()</span><h3>Focus ring</h3><p>Draw a pulsing ring around any element.</p></div>
+    <div class="pillar" id="cam-dim"><span class="tag">dimAround()</span><h3>Dim around</h3><p>Fade the page back, keep the subject lit.</p></div>
+    <div class="pillar" id="cam-zoom"><span class="tag">zoomTo()</span><h3>Post-export zoom</h3><p>Frame-exact ffmpeg zoompan — no DOM tricks.</p></div>
+  </div>
+</section>
+
+<section id="components">
+  <div class="kicker">HyperFrames components</div>
+  <h1 class="shimmer-sweep-target">Film grade,<br /><span class="glow">one install.</span></h1>
+  <p class="sub">Vignette. Shimmer. Installed from the catalog with <strong>argo add</strong>, injected live into the recording — watch this very footage change.</p>
+</section>
+
+<section id="effects">
+  <div class="kicker">Effects &amp; freeze</div>
+  <h1>Ship-it <span class="glow">moments.</span></h1>
+  <p class="sub">Confetti bursts, emoji rain — and when the moment lands, argo can <strong>freeze the frame</strong> in the export while the narration keeps going.</p>
+</section>
+
+<section id="shaders">
+  <div class="kicker">Shader transitions</div>
+  <h1>Sixteen <span class="glow">shaders.</span></h1>
+  <p class="sub">Every cut in this video is <strong>whip-pan</strong> — ported from the HyperFrames shader library. Restyle the whole film by changing one word.</p>
+  <div class="shader-grid">
+    <span>crosswarp</span><span>swirl</span><span>ripple</span><span>luma-mask</span>
+    <span>light-leak</span><span>domain-warp</span><span>ridged-burn</span><span>thermal-distortion</span>
+    <span>swirl-vortex</span><span class="hot">whip-pan</span><span>gravitational-lens</span><span>cinematic-zoom</span>
+    <span>chromatic-split</span><span>flash-through-white</span><span>sdf-iris</span><span>ripple-waves</span>
+  </div>
+</section>
+
+<section id="better">
+  <div class="kicker">Better together</div>
+  <h1>Crafted with Playwright.<br /><span class="glow">Composed via HyperFrames.</span></h1>
+  <div class="pillars">
+    <div class="pillar">
+      <span class="tag">Argo directs</span>
+      <h3>The choreography</h3>
+      <p>The full Playwright API driving your real product — plus narration, camera moves, one-command export.</p>
+    </div>
+    <div class="times">&times;</div>
+    <div class="pillar">
+      <span class="tag">HyperFrames performs</span>
+      <h3>The composition</h3>
+      <p>Shader transitions, film grade, branded end cards — a motion catalog, installed with one command.</p>
+    </div>
+  </div>
+  <code class="cmd"><span class="p">$</span> argo add vignette grain-overlay logo-outro</code>
+</section>
+
+<section id="outro">
+  <div class="kicker">Argo &times; HyperFrames</div>
+  <h1>Ship the demo.</h1>
+  <p class="sub">github.com/shreyaskarnik/argo &nbsp;·&nbsp; github.com/heygen-com/hyperframes</p>
+</section>
+
+</body>
+</html>
diff --git a/demos/hyperframes-showcase.scenes.json b/demos/hyperframes-showcase.scenes.json
new file mode 100644
index 0000000..14662aa
--- /dev/null
+++ b/demos/hyperframes-showcase.scenes.json
@@ -0,0 +1,101 @@
+[
+  {
+    "scene": "hook",
+    "text": "This video was not edited. It was choreographed. Every camera move, every beat, every cut you are about to see is code. Playwright drives the browser. Argo directs the film. Hyper Frames supplies the motion. This is the full tour.",
+    "speed": 0.94,
+    "overlay": {
+      "type": "headline-card",
+      "kicker": "ARGO × HYPERFRAMES",
+      "title": "The full tour.",
+      "body": "Every feature. One take. Zero editors.",
+      "placement": "top-right",
+      "motion": {
+        "type": "gsap",
+        "in": { "from": { "y": -30, "opacity": 0, "scale": 0.92 }, "duration": 0.55, "ease": "back.out" },
+        "out": { "to": { "opacity": 0, "y": -12 }, "duration": 0.35 }
+      }
+    }
+  },
+  {
+    "scene": "catalog",
+    "text": "First, the catalog. Hyper Frames, by Hey Jen, is an open source motion library: over a hundred and forty blocks, components, and shader transitions, all plain H T M L. Liquid glass U I. Three D code. Shader dissolves. And every one of them installs into argo with a single command.",
+    "speed": 0.95,
+    "overlay": {
+      "type": "lower-third",
+      "text": "hyperframes.heygen.com — 142 blocks · components · shader transitions",
+      "placement": "bottom-left",
+      "motion": {
+        "type": "gsap",
+        "in": { "from": { "x": -40, "opacity": 0 }, "duration": 0.5, "ease": "power3.out" },
+        "out": { "to": { "opacity": 0 }, "duration": 0.35 }
+      }
+    }
+  },
+  {
+    "scene": "argo",
+    "text": "And this is argo. Not a screen recorder: the full power of Playwright, pointed at film making. Real navigation, real clicks, real waits. Your product, driven exactly the way users drive it, then narrated, directed, and exported. One command, end to end."
+  },
+  {
+    "scene": "voices",
+    "voice": "am_michael",
+    "text": "Notice anything different? New narrator. Argo's voiceover is per scene: swap voices, engines, even languages, from one line of JSON in the manifest. She'll take it back from here."
+  },
+  {
+    "scene": "overlays",
+    "text": "Overlays are declared, not keyframed. Five built in templates, plus a curated block catalog, all animated with G sap. Here is a callout, an arrow, and a social post block, straight from the manifest."
+  },
+  {
+    "scene": "camera",
+    "text": "Camera direction is a function call. Spotlight the thing that matters. Ring it. Dim everything else. The viewer's eye goes exactly where the script says."
+  },
+  {
+    "scene": "zoom",
+    "text": "And the zoom is not a browser trick. Argo records the move, then applies it at export with frame exact F F M peg zoom pan. Overlays stay crisp. Nothing in the page ever moved."
+  },
+  {
+    "scene": "chart",
+    "text": "This entire chart is a Hyper Frames block. A full H T M L composition with its own timeline, pre rendered frame by frame in a headless browser, and composited into this video as a cutaway. No screen recording involved.",
+    "overlay": {
+      "type": "hf-block",
+      "name": "data-chart",
+      "params": { "--bg-color": "#0b0e14", "--text-color": "#f5f7fa" }
+    }
+  },
+  {
+    "scene": "components",
+    "text": "Components grade the footage itself. A cinematic vignette pulls your eye to the center. A shimmer sweeps across the headline. Installed from the catalog, injected live, while the recorder was rolling."
+  },
+  {
+    "scene": "effects",
+    "text": "Ship it moments get confetti. And right at the peak, argo freezes the frame in the export, while I keep talking. The recording never stopped. The timeline just held its breath.",
+    "post": [{ "type": "freeze", "atMs": 6000, "durationMs": 1800 }]
+  },
+  {
+    "scene": "shaders",
+    "text": "Every cut in this video is whip pan: a shader ported from the Hyper Frames library. Fifteen more ship with argo, from ridged burn to gravitational lens, and changing the whole video's style is one word in the config."
+  },
+  {
+    "scene": "better",
+    "text": "So here is the thesis. This is not just a Playwright video. It is cinematic choreography: carefully crafted with Playwright, composed via Hyper Frames. Argo directs; the catalog performs. Better together.",
+    "overlay": {
+      "type": "callout",
+      "text": "argo add vignette grain-overlay data-chart logo-outro",
+      "placement": "top-right",
+      "motion": {
+        "type": "gsap",
+        "in": { "from": { "y": -24, "opacity": 0 }, "duration": 0.45, "ease": "back.out" },
+        "out": { "to": { "opacity": 0 }, "duration": 0.3 }
+      }
+    }
+  },
+  {
+    "scene": "outro",
+    "text": "And this end card? A catalog block. We installed it, opened the H T M L, made it ours, and argo re rendered it automatically. Chapters, subtitles, and metadata are already in the file. Crafted with Playwright. Composed via Hyper Frames. Go ship one.",
+    "speed": 0.93,
+    "overlay": {
+      "type": "hf-block",
+      "name": "logo-outro",
+      "holdLastFrame": true
+    }
+  }
+]
diff --git a/docs/superpowers/plans/2026-07-06-hyperframes-shader-port.md b/docs/superpowers/plans/2026-07-06-hyperframes-shader-port.md
new file mode 100644
index 0000000..e627cdb
--- /dev/null
+++ b/docs/superpowers/plans/2026-07-06-hyperframes-shader-port.md
@@ -0,0 +1,1008 @@
+# HyperFrames Shader Transition Port — Implementation Plan (Track 1 of 4)
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** Expand argo's shader transition library from 5 to 16 by porting 11 fragment shaders from hyperframes, with a new configurable accent color that tints edge-glow/burn effects.
+
+**Architecture:** Each shader is a self-contained `.glsl` file in `src/transitions/shaders/`, registered in a compile-time registry (`index.ts`). The WebGL page harness (`shader-page.html.ts`) gains four new optional uniforms (`accent`, `accentDark`, `accentBright` vec3; `resolution` vec2) set only when a shader declares them (WebGL ignores `uniform*` calls with null locations). Accent hex comes from `export.transition.accent` config, is derived into dark/bright variants in Node, and is included in the shader cache key.
+
+**Tech Stack:** TypeScript (strict, ESM, ES2022), vitest, Playwright Chromium (headless WebGL via swiftshader), GLSL ES 1.0.
+
+**Spec:** `docs/superpowers/specs/2026-07-06-hyperframes-integration-design.md` (Track 1 section)
+
+## Global Constraints
+
+- All work on branch `feat/hyperframes-integration` (already exists).
+- GPG signing may fail: commit with `git -c commit.gpgsign=false commit ...`.
+- Build = `npm run build` (tsc + `copy-assets` which globs `src/transitions/shaders/*.glsl` → `dist/transitions/shaders/` — new `.glsl` files are picked up automatically, no build-script change needed).
+- Every ported `.glsl` file MUST carry the 3-line attribution header (hyperframes, Apache-2.0) exactly as shown in the task bodies.
+- Default accent color: `#0ea5e9`.
+- The GLSL in Tasks 3–5 was mechanically transformed from hyperframes source and **verified to compile and render** in argo's harness on 2026-07-06. Copy it byte-for-byte; do not "improve" it.
+- Run single test file: `npx vitest run tests/path/to/test.ts`. Full suite: `npm test`.
+- README/skill snippets must stay in sync with code changes (checked in Task 6).
+
+---
+
+### Task 1: Accent color derivation utility
+
+**Files:**
+- Create: `src/transitions/accent.ts`
+- Test: `tests/transitions/accent.test.ts`
+
+**Interfaces:**
+- Consumes: nothing (pure utility).
+- Produces: `deriveAccentColors(hex?: string): AccentColors` where `AccentColors = { accent: Vec3; accentDark: Vec3; accentBright: Vec3 }`, `Vec3 = [number, number, number]` (components in `[0,1]`), and `DEFAULT_ACCENT = '#0ea5e9'`. Task 2 imports all three names.
+
+- [ ] **Step 1: Write the failing test**
+
+Create `tests/transitions/accent.test.ts`:
+
+```typescript
+import { describe, it, expect } from 'vitest';
+import { deriveAccentColors, DEFAULT_ACCENT } from '../../src/transitions/accent.js';
+
+describe('deriveAccentColors', () => {
+  it('parses 6-digit hex into normalized rgb', () => {
+    const { accent } = deriveAccentColors('#ff8000');
+    expect(accent[0]).toBeCloseTo(1.0, 5);
+    expect(accent[1]).toBeCloseTo(128 / 255, 5);
+    expect(accent[2]).toBeCloseTo(0.0, 5);
+  });
+
+  it('accepts hex without leading #', () => {
+    expect(deriveAccentColors('0ea5e9').accent).toEqual(deriveAccentColors('#0ea5e9').accent);
+  });
+
+  it('defaults to DEFAULT_ACCENT when called without args', () => {
+    expect(DEFAULT_ACCENT).toBe('#0ea5e9');
+    expect(deriveAccentColors().accent).toEqual(deriveAccentColors(DEFAULT_ACCENT).accent);
+  });
+
+  it('derives dark as 0.35x and bright as mix-toward-white 0.65', () => {
+    const { accent, accentDark, accentBright } = deriveAccentColors('#0ea5e9');
+    for (let i = 0; i < 3; i++) {
+      expect(accentDark[i]).toBeCloseTo(accent[i] * 0.35, 5);
+      expect(accentBright[i]).toBeCloseTo(accent[i] + (1 - accent[i]) * 0.65, 5);
+    }
+  });
+
+  it('throws a clear error on malformed input', () => {
+    expect(() => deriveAccentColors('#12')).toThrow(/Invalid accent color/);
+    expect(() => deriveAccentColors('red')).toThrow(/Invalid accent color/);
+  });
+});
+```
+
+- [ ] **Step 2: Run test to verify it fails**
+
+Run: `npx vitest run tests/transitions/accent.test.ts`
+Expected: FAIL — `Cannot find module '../../src/transitions/accent.js'`
+
+- [ ] **Step 3: Write the implementation**
+
+Create `src/transitions/accent.ts`:
+
+```typescript
+/** RGB triple with components normalized to [0, 1]. */
+export type Vec3 = [number, number, number];
+
+export interface AccentColors {
+  accent: Vec3;
+  accentDark: Vec3;
+  accentBright: Vec3;
+}
+
+/** Default accent used when `export.transition.accent` is not configured. */
+export const DEFAULT_ACCENT = '#0ea5e9';
+
+/**
+ * Parse a 6-digit hex color and derive the dark/bright variants the ported
+ * hyperframes shaders expect (edge glow, burn tinting). Dark is a simple
+ * luminance scale; bright mixes toward white.
+ */
+export function deriveAccentColors(hex: string = DEFAULT_ACCENT): AccentColors {
+  const m = /^#?([0-9a-fA-F]{6})$/.exec(hex.trim());
+  if (!m) {
+    throw new Error(`Invalid accent color "${hex}" — expected a 6-digit hex like #0ea5e9`);
+  }
+  const n = parseInt(m[1], 16);
+  const accent: Vec3 = [((n >> 16) & 0xff) / 255, ((n >> 8) & 0xff) / 255, (n & 0xff) / 255];
+  const accentDark = accent.map((v) => v * 0.35) as Vec3;
+  const accentBright = accent.map((v) => v + (1 - v) * 0.65) as Vec3;
+  return { accent, accentDark, accentBright };
+}
+```
+
+- [ ] **Step 4: Run test to verify it passes**
+
+Run: `npx vitest run tests/transitions/accent.test.ts`
+Expected: PASS (5 tests)
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add src/transitions/accent.ts tests/transitions/accent.test.ts
+git -c commit.gpgsign=false commit -m "feat(transitions): accent color derivation for shader uniforms"
+```
+
+---
+
+### Task 2: Accent + resolution uniform plumbing (harness, cache key, config, call sites)
+
+**Files:**
+- Modify: `src/transitions/shader-page.html.ts` (signature + uniform setup)
+- Modify: `src/transitions/shader-render.ts` (`computeShaderHash`, `RenderShaderFramesOptions`, `renderShaderFrames`, `renderShaderTransitions`)
+- Modify: `src/config.ts:97-101` (`ShaderTransitionConfig`)
+- Modify: `src/pipeline.ts:434-442` and `src/pipeline.ts:643-651` (add `accent` to both `renderShaderTransitions` calls)
+- Modify: `src/cli.ts:248-256` (same)
+- Modify: `src/preview.ts:1077-1085` (same)
+- Test: `tests/transitions/shader-render.test.ts` (extend)
+
+**Interfaces:**
+- Consumes: `deriveAccentColors`, `AccentColors`, `DEFAULT_ACCENT` from `src/transitions/accent.ts` (Task 1).
+- Produces: `buildShaderPageHtml(width, height, glsl, accent?: AccentColors)`; `computeShaderHash(shader, durationMs, fps, width, height, aPngPath, bPngPath, accentHex?: string)`; `RenderShaderFramesOptions.accent?: string`; `renderShaderTransitions` opts gain `accent?: string`; `ShaderTransitionConfig.accent?: string`. Tasks 3–5 rely on the harness setting `resolution`/`accent*` uniforms.
+
+- [ ] **Step 1: Write the failing tests**
+
+Append to `tests/transitions/shader-render.test.ts` (inside the file, after the existing `computeShaderHash` describe block; reuse its `tmp` fixture pattern):
+
+```typescript
+describe('computeShaderHash accent', () => {
+  let tmp: string;
+  beforeEach(() => { tmp = mkdtempSync(join(tmpdir(), 'argo-shader-accent-')); });
+  afterEach(() => { rmSync(tmp, { recursive: true, force: true }); });
+
+  it('different accent produces a different hash', async () => {
+    const { computeShaderHash } = await import('../../src/transitions/shader-render.js');
+    const a = join(tmp, 'a.png');
+    const b = join(tmp, 'b.png');
+    writeFileSync(a, Buffer.from([1, 2, 3]));
+    writeFileSync(b, Buffer.from([4, 5, 6]));
+    const h1 = computeShaderHash('crosswarp', 800, 30, 640, 360, a, b, '#0ea5e9');
+    const h2 = computeShaderHash('crosswarp', 800, 30, 640, 360, a, b, '#ff0000');
+    expect(h1).not.toBe(h2);
+  });
+
+  it('omitted accent equals DEFAULT_ACCENT hash', async () => {
+    const { computeShaderHash } = await import('../../src/transitions/shader-render.js');
+    const { DEFAULT_ACCENT } = await import('../../src/transitions/accent.js');
+    const a = join(tmp, 'a.png');
+    const b = join(tmp, 'b.png');
+    writeFileSync(a, Buffer.from([1, 2, 3]));
+    writeFileSync(b, Buffer.from([4, 5, 6]));
+    expect(computeShaderHash('crosswarp', 800, 30, 640, 360, a, b))
+      .toBe(computeShaderHash('crosswarp', 800, 30, 640, 360, a, b, DEFAULT_ACCENT));
+  });
+});
+
+describe('buildShaderPageHtml uniforms', () => {
+  it('embeds accent values and resolution setup', async () => {
+    const { buildShaderPageHtml } = await import('../../src/transitions/shader-page.html.js');
+    const { deriveAccentColors } = await import('../../src/transitions/accent.js');
+    const html = buildShaderPageHtml(640, 360, 'void main(){}', deriveAccentColors('#ff8000'));
+    expect(html).toContain('accentDark');
+    expect(html).toContain('resolution');
+    expect(html).toContain('gl.uniform2f');
+  });
+
+  it('accepts a shader-variant config with accent at compile time', () => {
+    const cfg: TransitionConfig = {
+      type: 'shader',
+      shader: 'crosswarp',
+      durationMs: 800,
+      accent: '#ff8000',
+    };
+    expect(cfg.type).toBe('shader');
+  });
+});
+```
+
+- [ ] **Step 2: Run tests to verify they fail**
+
+Run: `npx vitest run tests/transitions/shader-render.test.ts`
+Expected: FAIL — accent-hash test (hashes equal, 8th arg ignored), `buildShaderPageHtml` arity/TS error, and `accent` not assignable to `ShaderTransitionConfig`.
+
+- [ ] **Step 3: Implement config + hash + harness + threading**
+
+**3a.** In `src/config.ts`, replace the `ShaderTransitionConfig` interface (lines 97–101) with:
+
+```typescript
+export interface ShaderTransitionConfig {
+  type: 'shader';
+  shader: ShaderName;
+  durationMs?: number;
+  /** Accent hex color tinting edge-glow/burn effects in shaders that use it
+   *  (e.g. ridged-burn, domain-warp, sdf-iris). Default '#0ea5e9'. */
+  accent?: string;
+}
+```
+
+**3b.** In `src/transitions/shader-render.ts`:
+
+Add to imports: `import { deriveAccentColors, DEFAULT_ACCENT } from './accent.js';`
+
+Replace `computeShaderHash` with (only the signature line, the `parts` line, and the JSDoc change — body otherwise identical):
+
+```typescript
+export function computeShaderHash(
+  shader: string,
+  durationMs: number,
+  fps: number,
+  width: number,
+  height: number,
+  aPngPath: string,
+  bPngPath: string,
+  accentHex: string = DEFAULT_ACCENT,
+): string {
+  const aHash = createHash('sha256').update(readFileSync(aPngPath)).digest('hex');
+  const bHash = createHash('sha256').update(readFileSync(bPngPath)).digest('hex');
+  const parts = [shader, durationMs, fps, width, height, aHash, bHash, accentHex].join('|');
+  return createHash('sha256').update(parts).digest('hex').slice(0, 16);
+}
+```
+
+Add `accent?: string;` to `RenderShaderFramesOptions` (with JSDoc `/** Accent hex for shaders using accent uniforms. Default DEFAULT_ACCENT. */`).
+
+In `renderShaderFrames`, change the `buildShaderPageHtml` call to:
+
+```typescript
+const html = buildShaderPageHtml(
+  opts.width,
+  opts.height,
+  SHADERS[opts.shader],
+  deriveAccentColors(opts.accent),
+);
+```
+
+Add `accent?: string;` to the `renderShaderTransitions` opts type, and inside it pass `accent: opts.accent` in the `renderShaderFrames` call and `opts.accent ?? DEFAULT_ACCENT` as the 8th arg to its `computeShaderHash` call.
+
+**3c.** In `src/transitions/shader-page.html.ts`, change the signature to:
+
+```typescript
+import type { AccentColors } from './accent.js';
+
+export function buildShaderPageHtml(
+  width: number,
+  height: number,
+  fragmentShaderGlsl: string,
+  accent?: AccentColors,
+): string {
+```
+
+and insert immediately after the `gl.useProgram(prog);` line in the template (before the buffer setup):
+
+```javascript
+  // Optional uniforms — WebGL silently ignores uniform* calls with a null
+  // location, so shaders that don't declare these are unaffected.
+  const accentColors = ${JSON.stringify(accent ?? null)};
+  if (accentColors) {
+    const set3 = (name, v) => gl.uniform3f(gl.getUniformLocation(prog, name), v[0], v[1], v[2]);
+    set3('accent', accentColors.accent);
+    set3('accentDark', accentColors.accentDark);
+    set3('accentBright', accentColors.accentBright);
+  }
+  gl.uniform2f(gl.getUniformLocation(prog, 'resolution'), ${width}, ${height});
+```
+
+**3d.** At each of the four call sites — `src/pipeline.ts:434`, `src/pipeline.ts:643`, `src/cli.ts:248`, `src/preview.ts:1077` — add one line to the `renderShaderTransitions({...})` object (all four use the local variable `shaderTransition`):
+
+```typescript
+          accent: shaderTransition.accent,
+```
+
+- [ ] **Step 4: Run tests to verify they pass**
+
+Run: `npx vitest run tests/transitions/shader-render.test.ts && npx vitest run tests/transitions/accent.test.ts`
+Expected: PASS (all, including pre-existing tests)
+
+- [ ] **Step 5: Build to catch TS errors at call sites**
+
+Run: `npm run build`
+Expected: exit 0
+
+- [ ] **Step 6: Commit**
+
+```bash
+git add src/transitions/shader-page.html.ts src/transitions/shader-render.ts src/config.ts src/pipeline.ts src/cli.ts src/preview.ts tests/transitions/shader-render.test.ts
+git -c commit.gpgsign=false commit -m "feat(transitions): accent + resolution uniforms threaded through shader pipeline"
+```
+
+---
+
+### Task 3: Port batch A — noise-based shaders + data-driven compile test
+
+**Files:**
+- Create: `src/transitions/shaders/domain-warp.glsl`
+- Create: `src/transitions/shaders/ridged-burn.glsl`
+- Create: `src/transitions/shaders/thermal-distortion.glsl`
+- Create: `src/transitions/shaders/swirl-vortex.glsl`
+- Modify: `src/transitions/shaders/index.ts` (register 4 names)
+- Test: `tests/transitions/shader-render.test.ts` (update registry test; add data-driven compile smoke)
+
+**Interfaces:**
+- Consumes: harness from Task 2 (accent uniforms available).
+- Produces: `SHADER_NAMES` grows to 9; the data-driven compile-smoke test Tasks 4–5 extend for free (it iterates `SHADER_NAMES`).
+
+- [ ] **Step 1: Update the registry test to the new list and add the compile smoke (failing first)**
+
+In `tests/transitions/shader-render.test.ts`, replace the `ships exactly the v1 five shaders` test with:
+
+```typescript
+  it('ships the v1 five plus the hyperframes ports', () => {
+    expect(SHADER_NAMES).toEqual([
+      'crosswarp', 'swirl', 'ripple', 'luma-mask', 'light-leak',
+      'domain-warp', 'ridged-burn', 'thermal-distortion', 'swirl-vortex',
+    ]);
+  });
+```
+
+Append a new describe block at the end of the file:
+
+```typescript
+describe('every registered shader compiles and renders', () => {
+  let tmp: string;
+  beforeEach(() => { tmp = mkdtempSync(join(tmpdir(), 'argo-shader-smoke-')); });
+  afterEach(() => { rmSync(tmp, { recursive: true, force: true }); });
+
+  it.skipIf(!hasFfmpeg)('renders one frame per shader without GL errors', async () => {
+    const { renderShaderFrames } = await import('../../src/transitions/shader-render.js');
+    const { chromium } = await import('playwright');
+    // two tiny solid-color PNG fixtures via ffmpeg
+    const a = join(tmp, 'a.png');
+    const b = join(tmp, 'b.png');
+    await execFileP('ffmpeg', ['-y', '-f', 'lavfi', '-i', 'color=red:s=64x36', '-frames:v', '1', a]);
+    await execFileP('ffmpeg', ['-y', '-f', 'lavfi', '-i', 'color=blue:s=64x36', '-frames:v', '1', b]);
+    const browser = await chromium.launch({
+      args: ['--use-gl=angle', '--use-angle=swiftshader', '--enable-webgl', '--ignore-gpu-blacklist'],
+    });
+    try {
+      for (const shader of SHADER_NAMES) {
+        const outDir = join(tmp, shader);
+        const n = await renderShaderFrames({
+          shader, aPng: a, bPng: b, width: 64, height: 36,
+          fps: 30, durationMs: 66, outputDir: outDir, browser,
+        });
+        expect(n, shader).toBeGreaterThanOrEqual(1);
+        expect(existsSync(join(outDir, 'frame_0000.png')), shader).toBe(true);
+      }
+    } finally {
+      await browser.close();
+    }
+  }, 120_000);
+});
+```
+
+- [ ] **Step 2: Run to verify failure**
+
+Run: `npx vitest run tests/transitions/shader-render.test.ts`
+Expected: FAIL — registry list mismatch (new names not yet registered).
+
+- [ ] **Step 3: Create the four `.glsl` files**
+
+Create `src/transitions/shaders/domain-warp.glsl` with exactly:
+
+```glsl
+// Adapted from hyperframes (github.com/heygen-com/hyperframes)
+// packages/shader-transitions/src/shaders/registry.ts — "domain-warp"
+// License: Apache-2.0
+precision mediump float;
+uniform sampler2D from;
+uniform sampler2D to;
+uniform float progress;
+uniform vec2 resolution;
+uniform vec3 accent;
+uniform vec3 accentDark;
+uniform vec3 accentBright;
+varying vec2 vUv;
+
+float hash(vec2 p){
+  return fract(sin(dot(p,vec2(127.1,311.7)))*43758.5453);
+}
+float vnoise(vec2 p){
+  vec2 i=floor(p),f=fract(p);
+  f=f*f*f*(f*(f*6.-15.)+10.);
+  return mix(mix(hash(i),hash(i+vec2(1,0)),f.x),mix(hash(i+vec2(0,1)),hash(i+vec2(1,1)),f.x),f.y);
+}
+float fbm(vec2 p){
+  float v=0.,a=.5;
+  mat2 R=mat2(.8,.6,-.6,.8);
+  for(int i=0; i<5; i++){
+    v+=a*vnoise(p);
+    p=R*p*2.02;
+    a*=.5;
+  }
+  return v;
+}
+void main(){
+  vec2 q=vec2(fbm(vUv*3.),fbm(vUv*3.+vec2(5.2,1.3)));
+  vec2 r=vec2(fbm(vUv*3.+q*4.+vec2(1.7,9.2)),fbm(vUv*3.+q*4.+vec2(8.3,2.8)));
+  float n=fbm(vUv*3.+r*2.);
+  vec2 warpDir=(q-.5)*.4;
+  vec4 A=texture2D(from,clamp(vUv+warpDir*progress,0.,1.));
+  vec4 B=texture2D(to,clamp(vUv-warpDir*(1.-progress),0.,1.));
+  float e=smoothstep(progress-.08,progress+.08,n);
+  float ed=abs(n-progress);
+  float em=smoothstep(.1,0.,ed)*(1.-step(1.,progress));
+  vec3 ec=mix(accentDark,accentBright,smoothstep(0.,.1,ed));
+  gl_FragColor=vec4(mix(B,A,e).rgb+ec*em*2.,1.);
+}
+```
+
+Create `src/transitions/shaders/ridged-burn.glsl` with exactly:
+
+```glsl
+// Adapted from hyperframes (github.com/heygen-com/hyperframes)
+// packages/shader-transitions/src/shaders/registry.ts — "ridged-burn"
+// License: Apache-2.0
+precision mediump float;
+uniform sampler2D from;
+uniform sampler2D to;
+uniform float progress;
+uniform vec2 resolution;
+uniform vec3 accent;
+uniform vec3 accentDark;
+uniform vec3 accentBright;
+varying vec2 vUv;
+
+float hash(vec2 p){
+  return fract(sin(dot(p,vec2(127.1,311.7)))*43758.5453);
+}
+float vnoise(vec2 p){
+  vec2 i=floor(p),f=fract(p);
+  f=f*f*f*(f*(f*6.-15.)+10.);
+  return mix(mix(hash(i),hash(i+vec2(1,0)),f.x),mix(hash(i+vec2(0,1)),hash(i+vec2(1,1)),f.x),f.y);
+}
+float fbm(vec2 p){
+  float v=0.,a=.5;
+  mat2 R=mat2(.8,.6,-.6,.8);
+  for(int i=0; i<5; i++){
+    v+=a*vnoise(p);
+    p=R*p*2.02;
+    a*=.5;
+  }
+  return v;
+}
+float ridged(vec2 p){
+  float v=0.,a=.5;
+  mat2 R=mat2(.8,.6,-.6,.8);
+  for(int i=0; i<5; i++){
+    v+=a*abs(vnoise(p)*2.-1.);
+    p=R*p*2.02;
+    a*=.5;
+  }
+  return v;
+}
+void main(){
+  vec4 A=texture2D(from,vUv),B=texture2D(to,vUv);
+  float n=ridged(vUv*4.);
+  float e=smoothstep(progress-.04,progress+.04,n);
+  float heat=smoothstep(.12,0.,abs(n-progress))*(1.-step(1.,progress));
+  vec3 burn=mix(accentDark,accent,smoothstep(0.,.25,heat));
+  burn=mix(burn,accentBright,smoothstep(.25,.5,heat));
+  burn=mix(burn,vec3(1),smoothstep(.5,1.,heat));
+  float sparks=step(.92,vnoise(vUv*80.))*heat*3.;
+  gl_FragColor=vec4(mix(B,A,e).rgb+burn*heat*3.5+accentBright*sparks,1.);
+}
+```
+
+Create `src/transitions/shaders/thermal-distortion.glsl` with exactly:
+
+```glsl
+// Adapted from hyperframes (github.com/heygen-com/hyperframes)
+// packages/shader-transitions/src/shaders/registry.ts — "thermal-distortion"
+// License: Apache-2.0
+precision mediump float;
+uniform sampler2D from;
+uniform sampler2D to;
+uniform float progress;
+uniform vec2 resolution;
+uniform vec3 accent;
+uniform vec3 accentDark;
+uniform vec3 accentBright;
+varying vec2 vUv;
+
+float hash(vec2 p){
+  return fract(sin(dot(p,vec2(127.1,311.7)))*43758.5453);
+}
+float vnoise(vec2 p){
+  vec2 i=floor(p),f=fract(p);
+  f=f*f*f*(f*(f*6.-15.)+10.);
+  return mix(mix(hash(i),hash(i+vec2(1,0)),f.x),mix(hash(i+vec2(0,1)),hash(i+vec2(1,1)),f.x),f.y);
+}
+float fbm(vec2 p){
+  float v=0.,a=.5;
+  mat2 R=mat2(.8,.6,-.6,.8);
+  for(int i=0; i<5; i++){
+    v+=a*vnoise(p);
+    p=R*p*2.02;
+    a*=.5;
+  }
+  return v;
+}
+void main(){
+  float heat=progress*1.5;
+  float yFade=smoothstep(1.,0.,vUv.y);
+  float shimmer=sin(vUv.y*40.+fbm(vUv*6.)*8.)*fbm(vUv*3.+vec2(0.,progress*2.));
+  float dispX=shimmer*heat*.03*yFade;
+  vec2 fromUv=clamp(vUv+vec2(dispX,0.),0.,1.);
+  vec4 A=texture2D(from,fromUv);
+  float invShimmer=sin(vUv.y*40.+fbm(vUv*6.+3.)*8.)*fbm(vUv*3.+vec2(3.,progress*2.));
+  float dispX2=invShimmer*(1.-progress)*.03*yFade;
+  vec2 toUv=clamp(vUv+vec2(dispX2,0.),0.,1.);
+  vec4 B=texture2D(to,toUv);
+  float haze=heat*yFade*.15*(1.-progress);
+  gl_FragColor=vec4(mix(A.rgb,B.rgb,progress)+accentBright*haze,1.);
+}
+```
+
+Create `src/transitions/shaders/swirl-vortex.glsl` with exactly:
+
+```glsl
+// Adapted from hyperframes (github.com/heygen-com/hyperframes)
+// packages/shader-transitions/src/shaders/registry.ts — "swirl-vortex"
+// License: Apache-2.0
+precision mediump float;
+uniform sampler2D from;
+uniform sampler2D to;
+uniform float progress;
+uniform vec2 resolution;
+uniform vec3 accent;
+uniform vec3 accentDark;
+uniform vec3 accentBright;
+varying vec2 vUv;
+
+float hash(vec2 p){
+  return fract(sin(dot(p,vec2(127.1,311.7)))*43758.5453);
+}
+float vnoise(vec2 p){
+  vec2 i=floor(p),f=fract(p);
+  f=f*f*f*(f*(f*6.-15.)+10.);
+  return mix(mix(hash(i),hash(i+vec2(1,0)),f.x),mix(hash(i+vec2(0,1)),hash(i+vec2(1,1)),f.x),f.y);
+}
+float fbm(vec2 p){
+  float v=0.,a=.5;
+  mat2 R=mat2(.8,.6,-.6,.8);
+  for(int i=0; i<5; i++){
+    v+=a*vnoise(p);
+    p=R*p*2.02;
+    a*=.5;
+  }
+  return v;
+}
+void main(){
+  vec2 uv=vUv-.5;
+  float dist=length(uv);
+  float warp=fbm(vUv*4.)*.5;
+  float fromAng=progress*(1.-dist)*10.+warp*progress*3.;
+  float fs=sin(fromAng),fc=cos(fromAng);
+  vec2 fromUv=clamp(vec2(uv.x*fc-uv.y*fs,uv.x*fs+uv.y*fc)+.5,0.,1.);
+  float toAng=-(1.-progress)*(1.-dist)*10.-warp*(1.-progress)*3.;
+  float ts=sin(toAng),tc=cos(toAng);
+  vec2 toUv=clamp(vec2(uv.x*tc-uv.y*ts,uv.x*ts+uv.y*tc)+.5,0.,1.);
+  vec4 A=texture2D(from,fromUv);
+  vec4 B=texture2D(to,toUv);
+  gl_FragColor=mix(A,B,progress);
+}
+```
+
+- [ ] **Step 4: Register the four shaders**
+
+In `src/transitions/shaders/index.ts`, replace the `SHADER_NAMES` and `SHADERS` declarations with:
+
+```typescript
+export const SHADER_NAMES = [
+  'crosswarp', 'swirl', 'ripple', 'luma-mask', 'light-leak',
+  'domain-warp', 'ridged-burn', 'thermal-distortion', 'swirl-vortex',
+] as const;
+export type ShaderName = (typeof SHADER_NAMES)[number];
+
+export const SHADERS: Record<ShaderName, string> = Object.fromEntries(
+  SHADER_NAMES.map((name) => [name, loadShader(name)]),
+) as Record<ShaderName, string>;
+```
+
+(The `Object.fromEntries` form replaces the hand-written literal so Tasks 4–5 only touch `SHADER_NAMES`.)
+
+- [ ] **Step 5: Run tests to verify they pass**
+
+Run: `npx vitest run tests/transitions/shader-render.test.ts`
+Expected: PASS — including the compile-smoke iterating all 9 shaders (needs ffmpeg + Playwright chromium installed; smoke test auto-skips without ffmpeg).
+
+- [ ] **Step 6: Commit**
+
+```bash
+git add src/transitions/shaders/ tests/transitions/shader-render.test.ts
+git -c commit.gpgsign=false commit -m "feat(transitions): port domain-warp, ridged-burn, thermal-distortion, swirl-vortex shaders from hyperframes"
+```
+
+---
+
+### Task 4: Port batch B — geometric shaders
+
+**Files:**
+- Create: `src/transitions/shaders/whip-pan.glsl`
+- Create: `src/transitions/shaders/gravitational-lens.glsl`
+- Create: `src/transitions/shaders/cinematic-zoom.glsl`
+- Create: `src/transitions/shaders/chromatic-split.glsl`
+- Create: `src/transitions/shaders/flash-through-white.glsl`
+- Modify: `src/transitions/shaders/index.ts` (append 5 names to `SHADER_NAMES`)
+- Test: `tests/transitions/shader-render.test.ts` (update expected list)
+
+**Interfaces:**
+- Consumes: `Object.fromEntries` registry form from Task 3 (only `SHADER_NAMES` changes).
+- Produces: `SHADER_NAMES` grows to 14.
+
+- [ ] **Step 1: Update the registry list test (failing first)**
+
+In `tests/transitions/shader-render.test.ts`, replace the expected array in `ships the v1 five plus the hyperframes ports` with:
+
+```typescript
+    expect(SHADER_NAMES).toEqual([
+      'crosswarp', 'swirl', 'ripple', 'luma-mask', 'light-leak',
+      'domain-warp', 'ridged-burn', 'thermal-distortion', 'swirl-vortex',
+      'whip-pan', 'gravitational-lens', 'cinematic-zoom', 'chromatic-split', 'flash-through-white',
+    ]);
+```
+
+Run: `npx vitest run tests/transitions/shader-render.test.ts` — Expected: FAIL (list mismatch).
+
+- [ ] **Step 2: Create the five `.glsl` files**
+
+Create `src/transitions/shaders/whip-pan.glsl` with exactly:
+
+```glsl
+// Adapted from hyperframes (github.com/heygen-com/hyperframes)
+// packages/shader-transitions/src/shaders/registry.ts — "whip-pan"
+// License: Apache-2.0
+precision mediump float;
+uniform sampler2D from;
+uniform sampler2D to;
+uniform float progress;
+uniform vec2 resolution;
+uniform vec3 accent;
+uniform vec3 accentDark;
+uniform vec3 accentBright;
+varying vec2 vUv;
+
+void main(){
+  float fromOff=progress*1.5;
+  vec3 fromC=vec3(0.);
+  for(int i=0; i<10; i++){
+    float f=float(i)/10.;
+    vec2 fuv=vec2(vUv.x+fromOff+progress*.08*f,vUv.y);
+    fromC+=texture2D(from,clamp(fuv,0.,1.)).rgb;
+  }
+  fromC/=10.;
+  float toOff=(1.-progress)*1.5;
+  vec3 toC=vec3(0.);
+  for(int i=0; i<10; i++){
+    float f=float(i)/10.;
+    vec2 tuv=vec2(vUv.x-toOff-(1.-progress)*.08*f,vUv.y);
+    toC+=texture2D(to,clamp(tuv,0.,1.)).rgb;
+  }
+  toC/=10.;
+  gl_FragColor=vec4(mix(fromC,toC,progress),1.);
+}
+```
+
+Create `src/transitions/shaders/gravitational-lens.glsl` with exactly:
+
+```glsl
+// Adapted from hyperframes (github.com/heygen-com/hyperframes)
+// packages/shader-transitions/src/shaders/registry.ts — "gravitational-lens"
+// License: Apache-2.0
+precision mediump float;
+uniform sampler2D from;
+uniform sampler2D to;
+uniform float progress;
+uniform vec2 resolution;
+uniform vec3 accent;
+uniform vec3 accentDark;
+uniform vec3 accentBright;
+varying vec2 vUv;
+
+void main(){
+  vec4 B=texture2D(to,vUv);
+  vec2 uv=vUv-.5;
+  float dist=length(uv);
+  float pull=progress*2.;
+  float warpStr=pull*.3/(dist+.1);
+  vec2 warped=clamp(vUv-uv*warpStr,0.,1.);
+  vec4 A=texture2D(from,warped);
+  float horizon=smoothstep(0.,.3,dist/(1.-progress*.85+.001));
+  float shift=pull*.02/(dist+.2);
+  float r=texture2D(from,clamp(vUv-uv*(warpStr+shift),0.,1.)).r;
+  float b=texture2D(from,clamp(vUv-uv*(warpStr-shift),0.,1.)).b;
+  vec3 lensed=vec3(r,A.g,b)*horizon;
+  gl_FragColor=vec4(mix(lensed,B.rgb,smoothstep(.3,.9,progress)),1.);
+}
+```
+
+Create `src/transitions/shaders/cinematic-zoom.glsl` with exactly:
+
+```glsl
+// Adapted from hyperframes (github.com/heygen-com/hyperframes)
+// packages/shader-transitions/src/shaders/registry.ts — "cinematic-zoom"
+// License: Apache-2.0
+precision mediump float;
+uniform sampler2D from;
+uniform sampler2D to;
+uniform float progress;
+uniform vec2 resolution;
+uniform vec3 accent;
+uniform vec3 accentDark;
+uniform vec3 accentBright;
+varying vec2 vUv;
+
+void main(){
+  vec2 d=vUv-vec2(.5);
+  float fromS=progress*.08;
+  float toS=(1.-progress)*.06;
+  float fr=0.,fg=0.,fb=0.;
+  for(int i=0; i<12; i++){
+    float f=float(i)/12.;
+    fr+=texture2D(from,vUv-d*(fromS*1.06)*f).r;
+    fg+=texture2D(from,vUv-d*fromS*f).g;
+    fb+=texture2D(from,vUv-d*(fromS*.94)*f).b;
+  }
+  vec3 fromBl=vec3(fr,fg,fb)/12.;
+  float tr=0.,tg=0.,tb=0.;
+  for(int i=0; i<12; i++){
+    float f=float(i)/12.;
+    tr+=texture2D(to,vUv+d*(toS*1.06)*f).r;
+    tg+=texture2D(to,vUv+d*toS*f).g;
+    tb+=texture2D(to,vUv+d*(toS*.94)*f).b;
+  }
+  vec3 toBl=vec3(tr,tg,tb)/12.;
+  gl_FragColor=vec4(mix(fromBl,toBl,progress),1.);
+}
+```
+
+Create `src/transitions/shaders/chromatic-split.glsl` with exactly:
+
+```glsl
+// Adapted from hyperframes (github.com/heygen-com/hyperframes)
+// packages/shader-transitions/src/shaders/registry.ts — "chromatic-split"
+// License: Apache-2.0
+precision mediump float;
+uniform sampler2D from;
+uniform sampler2D to;
+uniform float progress;
+uniform vec2 resolution;
+uniform vec3 accent;
+uniform vec3 accentDark;
+uniform vec3 accentBright;
+varying vec2 vUv;
+
+void main(){
+  vec2 c=vUv-.5;
+  float fromShift=progress*.06;
+  float fr=texture2D(from,clamp(vUv+c*fromShift,0.,1.)).r;
+  float fg=texture2D(from,vUv).g;
+  float fb=texture2D(from,clamp(vUv-c*fromShift,0.,1.)).b;
+  vec3 fromSplit=vec3(fr,fg,fb);
+  float toShift=(1.-progress)*.06;
+  float tr=texture2D(to,clamp(vUv-c*toShift,0.,1.)).r;
+  float tg=texture2D(to,vUv).g;
+  float tb=texture2D(to,clamp(vUv+c*toShift,0.,1.)).b;
+  vec3 toSplit=vec3(tr,tg,tb);
+  gl_FragColor=vec4(mix(fromSplit,toSplit,progress),1.);
+}
+```
+
+Create `src/transitions/shaders/flash-through-white.glsl` with exactly:
+
+```glsl
+// Adapted from hyperframes (github.com/heygen-com/hyperframes)
+// packages/shader-transitions/src/shaders/registry.ts — "flash-through-white"
+// License: Apache-2.0
+precision mediump float;
+uniform sampler2D from;
+uniform sampler2D to;
+uniform float progress;
+uniform vec2 resolution;
+uniform vec3 accent;
+uniform vec3 accentDark;
+uniform vec3 accentBright;
+varying vec2 vUv;
+
+void main(){
+  vec4 A=texture2D(from,vUv),B=texture2D(to,vUv);
+  float toWhite=smoothstep(0.,.45,progress);
+  vec3 fromC=mix(A.rgb,vec3(1.),toWhite);
+  float fromWhite=1.-smoothstep(.5,1.,progress);
+  vec3 toC=mix(B.rgb,vec3(1.),fromWhite);
+  gl_FragColor=vec4(mix(fromC,toC,smoothstep(.35,.65,progress)),1.);
+}
+```
+
+- [ ] **Step 3: Append the five names to `SHADER_NAMES`**
+
+In `src/transitions/shaders/index.ts`:
+
+```typescript
+export const SHADER_NAMES = [
+  'crosswarp', 'swirl', 'ripple', 'luma-mask', 'light-leak',
+  'domain-warp', 'ridged-burn', 'thermal-distortion', 'swirl-vortex',
+  'whip-pan', 'gravitational-lens', 'cinematic-zoom', 'chromatic-split', 'flash-through-white',
+] as const;
+```
+
+- [ ] **Step 4: Run tests to verify they pass**
+
+Run: `npx vitest run tests/transitions/shader-render.test.ts`
+Expected: PASS — compile smoke now covers 14 shaders.
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add src/transitions/shaders/ tests/transitions/shader-render.test.ts
+git -c commit.gpgsign=false commit -m "feat(transitions): port whip-pan, gravitational-lens, cinematic-zoom, chromatic-split, flash-through-white shaders"
+```
+
+---
+
+### Task 5: Port batch C — resolution/accent shaders
+
+**Files:**
+- Create: `src/transitions/shaders/sdf-iris.glsl`
+- Create: `src/transitions/shaders/ripple-waves.glsl`
+- Modify: `src/transitions/shaders/index.ts` (append 2 names)
+- Test: `tests/transitions/shader-render.test.ts` (update expected list)
+
+**Interfaces:**
+- Consumes: `resolution` uniform from Task 2 (sdf-iris is the only shader that reads it — aspect-ratio-corrected iris circle).
+- Produces: final `SHADER_NAMES` of 16.
+
+- [ ] **Step 1: Update the registry list test (failing first)**
+
+Replace the expected array with the final list:
+
+```typescript
+    expect(SHADER_NAMES).toEqual([
+      'crosswarp', 'swirl', 'ripple', 'luma-mask', 'light-leak',
+      'domain-warp', 'ridged-burn', 'thermal-distortion', 'swirl-vortex',
+      'whip-pan', 'gravitational-lens', 'cinematic-zoom', 'chromatic-split', 'flash-through-white',
+      'sdf-iris', 'ripple-waves',
+    ]);
+```
+
+Run: `npx vitest run tests/transitions/shader-render.test.ts` — Expected: FAIL.
+
+- [ ] **Step 2: Create the two `.glsl` files**
+
+Create `src/transitions/shaders/sdf-iris.glsl` with exactly:
+
+```glsl
+// Adapted from hyperframes (github.com/heygen-com/hyperframes)
+// packages/shader-transitions/src/shaders/registry.ts — "sdf-iris"
+// License: Apache-2.0
+precision mediump float;
+uniform sampler2D from;
+uniform sampler2D to;
+uniform float progress;
+uniform vec2 resolution;
+uniform vec3 accent;
+uniform vec3 accentDark;
+uniform vec3 accentBright;
+varying vec2 vUv;
+
+void main(){
+  vec4 A=texture2D(from,vUv),B=texture2D(to,vUv);
+  vec2 uv=(vUv-.5)*vec2(resolution.x/resolution.y,1.);
+  float d=length(uv);
+  float radius=progress*1.2;
+  float fw=.003;
+  float edge=smoothstep(radius+fw,radius-fw,d);
+  float ring1=exp(-abs(d-radius)*25.);
+  float ring2=exp(-abs(d-radius+.04)*20.)*.5;
+  float ring3=exp(-abs(d-radius+.08)*15.)*.25;
+  float glow=(ring1+ring2+ring3)*progress*(1.-progress)*4.;
+  gl_FragColor=vec4(mix(A,B,edge).rgb+accentBright*glow*.6,1.);
+}
+```
+
+Create `src/transitions/shaders/ripple-waves.glsl` with exactly:
+
+```glsl
+// Adapted from hyperframes (github.com/heygen-com/hyperframes)
+// packages/shader-transitions/src/shaders/registry.ts — "ripple-waves"
+// License: Apache-2.0
+precision mediump float;
+uniform sampler2D from;
+uniform sampler2D to;
+uniform float progress;
+uniform vec2 resolution;
+uniform vec3 accent;
+uniform vec3 accentDark;
+uniform vec3 accentBright;
+varying vec2 vUv;
+
+void main(){
+  vec2 uv=vUv-.5;
+  float dist=length(uv);
+  vec2 dir=normalize(uv+.001);
+  float fromAmp=progress*.04;
+  float fw1=exp(sin(dist*25.-progress*12.)-1.);
+  float fw2=exp(sin(dist*50.-progress*18.)-1.)*.5;
+  vec2 fromUv=clamp(vUv+dir*(fw1+fw2)*fromAmp,0.,1.);
+  float toAmp=(1.-progress)*.04;
+  float tw1=exp(sin(dist*25.+progress*12.)-1.);
+  float tw2=exp(sin(dist*50.+progress*18.)-1.)*.5;
+  vec2 toUv=clamp(vUv-dir*(tw1+tw2)*toAmp,0.,1.);
+  vec4 A=texture2D(from,fromUv);
+  vec4 B=texture2D(to,toUv);
+  float peak=fw1*progress;
+  vec3 tint=accentBright*peak*.1;
+  gl_FragColor=vec4(mix(A.rgb+tint,B.rgb,progress),1.);
+}
+```
+
+- [ ] **Step 3: Append the two names to `SHADER_NAMES`** (same pattern as Task 4 Step 3, final list as in Step 1's test).
+
+- [ ] **Step 4: Run tests to verify they pass**
+
+Run: `npx vitest run tests/transitions/shader-render.test.ts`
+Expected: PASS — compile smoke covers all 16.
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add src/transitions/shaders/ tests/transitions/shader-render.test.ts
+git -c commit.gpgsign=false commit -m "feat(transitions): port sdf-iris and ripple-waves shaders from hyperframes"
+```
+
+---
+
+### Task 6: Docs sync + full verification
+
+**Files:**
+- Modify: `README.md` (shader transition list + `accent` config option — find the section documenting `export.transition`)
+- Modify: `CLAUDE.md` (Shader Transitions section: "v1 ships: crosswarp, swirl, ripple, luma-mask, light-leak" → add "plus 11 hyperframes ports (Apache-2.0): domain-warp, ridged-burn, thermal-distortion, swirl-vortex, whip-pan, gravitational-lens, cinematic-zoom, chromatic-split, flash-through-white, sdf-iris, ripple-waves. `export.transition.accent` tints accent-aware shaders.")
+- Modify: `skills/argo-guide/` — grep for shader names (`grep -rn "crosswarp\|luma-mask" skills/`) and update any list that enumerates available shaders + document `accent`.
+
+**Interfaces:**
+- Consumes: final 16-shader registry from Task 5.
+- Produces: nothing downstream — this closes Track 1.
+
+- [ ] **Step 1: Update README**
+
+Find the transition config docs: `grep -n "shader" README.md`. Add the 11 new names to any shader enumeration and document the new option with this snippet style:
+
+```js
+export default defineConfig({
+  export: {
+    transition: {
+      type: 'shader',
+      shader: 'ridged-burn',
+      durationMs: 2000,
+      accent: '#0ea5e9', // tints edge glow/burn in accent-aware shaders
+    },
+  },
+});
+```
+
+- [ ] **Step 2: Update CLAUDE.md and the argo-guide skill** as listed under Files. For the skill, check `skills/argo-guide/SKILL.md` and `skills/argo-guide/references/` for shader enumerations.
+
+- [ ] **Step 3: Full verification**
+
+Run: `npm run build && npm test`
+Expected: build exit 0; all tests pass. Then verify dist copy picked up the new files:
+
+Run: `ls dist/transitions/shaders/*.glsl | wc -l`
+Expected: `16`
+
+- [ ] **Step 4: Commit**
+
+```bash
+git add README.md CLAUDE.md skills/
+git -c commit.gpgsign=false commit -m "docs: document 11 new shader transitions and accent config"
+```
+
+---
+
+## Self-Review Notes
+
+- **Spec coverage:** accent config (Task 1–2), uniform shim + attribution + self-contained GLSL (Tasks 3–5), README/validate/skill sync (Task 6; shader-name validation is type-driven via `ShaderName` so no separate validate change is needed), cache-key correctness (Task 2 — accent added to hash, a spec-implied requirement since different accents produce different frames).
+- **Duplicates skipped per spec:** `cross-warp-morph` (≈ existing `crosswarp`), `light-leak` (name collision with existing).
+- **Type consistency:** `AccentColors`/`deriveAccentColors`/`DEFAULT_ACCENT` names match across Tasks 1–2; `SHADER_NAMES` list is stated in full in each task that changes it.
diff --git a/docs/superpowers/plans/2026-07-07-argo-add-registry.md b/docs/superpowers/plans/2026-07-07-argo-add-registry.md
new file mode 100644
index 0000000..7c065e8
--- /dev/null
+++ b/docs/superpowers/plans/2026-07-07-argo-add-registry.md
@@ -0,0 +1,1373 @@
+# `argo add` + HyperFrames Registry Compatibility — Implementation Plan (Track 2 of 4)
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** `argo add <name>` installs blocks/components from the hyperframes registry into a project-local `blocks/` dir, and installed **components** become usable during recording via a new `hf-component` overlay cue and a script-side `applyComponent()` API.
+
+**Architecture:** Items are stored as native hyperframes HTML (verbatim) and adapted at use time — never converted to argo's `BlockDefinition` format. New `src/hf/` module family: `registry-client.ts` (fetch), `add.ts` (install), `component.ts` (snippet parser + param safety), `apply-component.ts` (page injection). Config gains `blocksDir` (default `'blocks'`) and `registry?: { url?: string }`. The blocks dir bridges to the Playwright subprocess via `ARGO_BLOCKS_DIR` (set in `record.ts`, passed at all three `record()` call sites).
+
+**Tech Stack:** TypeScript (strict, ESM, ES2022), vitest, Node 24 global `fetch`, Playwright chromium for the one injection integration test.
+
+**Spec:** `docs/superpowers/specs/2026-07-06-hyperframes-integration-design.md` (Track 2 section)
+
+## Global Constraints
+
+- Branch: `feat/hyperframes-integration` (exists). Commit with `git -c commit.gpgsign=false commit ...`.
+- Default registry URL: `https://raw.githubusercontent.com/heygen-com/hyperframes/main/registry`.
+- Registry index lives at `<registryUrl>/registry.json` with shape `{ items: [{ name, type }] }` where type ∈ `hyperframes:block | hyperframes:component | hyperframes:example`. Item metadata: `<registryUrl>/<blocks|components>/<name>/registry-item.json`; item files: `<registryUrl>/<blocks|components>/<name>/<file.path>`.
+- Item names AND item file paths must be validated against `/^[a-zA-Z0-9][a-zA-Z0-9._-]*$/` (no slashes) before any `path.join()` — path-traversal invariant. Item *names* use the stricter demo-name pattern `/^[a-zA-Z0-9][a-zA-Z0-9_-]*$/`.
+- `hyperframes:example` items are NOT installable — reject with a clear error.
+- Caption components (`caption-*`) install fine but are NOT given special support (word timing is out of scope — deferred to the STT track).
+- Unit tests must NOT hit the network — inject a fetch stub. Exactly one Playwright integration test (Task 5).
+- Env bridge rule: config→Playwright vars are set in `src/record.ts` and passed at ALL THREE `record()` call sites: `src/pipeline.ts:172`, `src/pipeline.ts:527`, `src/cli.ts:93`.
+- README/CLAUDE.md/skill sync happens in the final task.
+- Run single test file: `npx vitest run tests/path/to/test.ts`. Full suite: `npm test`.
+
+---
+
+### Task 1: Registry client
+
+**Files:**
+- Create: `src/hf/registry-client.ts`
+- Test: `tests/hf/registry-client.test.ts`
+
+**Interfaces:**
+- Consumes: nothing (fetch injected).
+- Produces (Task 2 depends on these exact names):
+  - `DEFAULT_REGISTRY_URL: string`
+  - `type FetchLike = (url: string) => Promise<{ ok: boolean; status: number; text(): Promise<string> }>`
+  - `interface RegistryIndexItem { name: string; type: string }`
+  - `interface RegistryItemFile { path: string; target?: string; type?: string }`
+  - `interface RegistryItem { name: string; type: string; title?: string; description?: string; tags?: string[]; files: RegistryItemFile[]; params?: Array<{ key: string; label?: string; type?: string; default?: string }> }`
+  - `kindFromType(t: string): 'blocks' | 'components' | null`
+  - `fetchRegistryIndex(registryUrl: string, fetchImpl?: FetchLike): Promise<RegistryIndexItem[]>`
+  - `fetchRegistryItem(registryUrl: string, kind: 'blocks' | 'components', name: string, fetchImpl?: FetchLike): Promise<RegistryItem>`
+  - `fetchItemFile(registryUrl: string, kind: 'blocks' | 'components', name: string, filePath: string, fetchImpl?: FetchLike): Promise<string>`
+
+- [ ] **Step 1: Write the failing test**
+
+Create `tests/hf/registry-client.test.ts`:
+
+```typescript
+import { describe, it, expect } from 'vitest';
+import {
+  DEFAULT_REGISTRY_URL,
+  kindFromType,
+  fetchRegistryIndex,
+  fetchRegistryItem,
+  fetchItemFile,
+  type FetchLike,
+} from '../../src/hf/registry-client.js';
+
+function stubFetch(routes: Record<string, string>): FetchLike {
+  return async (url: string) => {
+    const body = routes[url];
+    return {
+      ok: body !== undefined,
+      status: body !== undefined ? 200 : 404,
+      text: async () => body ?? 'not found',
+    };
+  };
+}
+
+const REG = 'https://example.test/registry';
+
+describe('registry client', () => {
+  it('exposes the hyperframes default registry URL', () => {
+    expect(DEFAULT_REGISTRY_URL).toBe(
+      'https://raw.githubusercontent.com/heygen-com/hyperframes/main/registry',
+    );
+  });
+
+  it('maps registry item types to fetch kinds', () => {
+    expect(kindFromType('hyperframes:block')).toBe('blocks');
+    expect(kindFromType('hyperframes:component')).toBe('components');
+    expect(kindFromType('hyperframes:example')).toBe(null);
+    expect(kindFromType('bogus')).toBe(null);
+  });
+
+  it('fetches and parses the registry index', async () => {
+    const f = stubFetch({
+      [`${REG}/registry.json`]: JSON.stringify({
+        items: [{ name: 'vignette', type: 'hyperframes:component' }],
+      }),
+    });
+    const items = await fetchRegistryIndex(REG, f);
+    expect(items).toEqual([{ name: 'vignette', type: 'hyperframes:component' }]);
+  });
+
+  it('fetches and parses a registry item', async () => {
+    const f = stubFetch({
+      [`${REG}/components/vignette/registry-item.json`]: JSON.stringify({
+        name: 'vignette',
+        type: 'hyperframes:component',
+        files: [{ path: 'vignette.html' }],
+      }),
+    });
+    const item = await fetchRegistryItem(REG, 'components', 'vignette', f);
+    expect(item.name).toBe('vignette');
+    expect(item.files).toHaveLength(1);
+  });
+
+  it('fetches raw item file content', async () => {
+    const f = stubFetch({
+      [`${REG}/components/vignette/vignette.html`]: '<div id="hf-vignette"></div>',
+    });
+    await expect(fetchItemFile(REG, 'components', 'vignette', 'vignette.html', f)).resolves.toContain(
+      'hf-vignette',
+    );
+  });
+
+  it('throws a clear error on HTTP failure', async () => {
+    const f = stubFetch({});
+    await expect(fetchRegistryIndex(REG, f)).rejects.toThrow(/registry.*404/i);
+  });
+
+  it('throws a clear error on malformed index JSON', async () => {
+    const f = stubFetch({ [`${REG}/registry.json`]: '{"nope": true}' });
+    await expect(fetchRegistryIndex(REG, f)).rejects.toThrow(/items/i);
+  });
+});
+```
+
+- [ ] **Step 2: Run test to verify it fails**
+
+Run: `npx vitest run tests/hf/registry-client.test.ts`
+Expected: FAIL — `Cannot find module '../../src/hf/registry-client.js'`
+
+- [ ] **Step 3: Write the implementation**
+
+Create `src/hf/registry-client.ts`:
+
+```typescript
+/**
+ * Minimal client for the hyperframes registry layout:
+ *   <registryUrl>/registry.json
+ *   <registryUrl>/<blocks|components>/<name>/registry-item.json
+ *   <registryUrl>/<blocks|components>/<name>/<file.path>
+ * Fetch is injectable so unit tests never touch the network.
+ */
+
+export const DEFAULT_REGISTRY_URL =
+  'https://raw.githubusercontent.com/heygen-com/hyperframes/main/registry';
+
+export type FetchLike = (
+  url: string,
+) => Promise<{ ok: boolean; status: number; text(): Promise<string> }>;
+
+export interface RegistryIndexItem {
+  name: string;
+  type: string;
+}
+
+export interface RegistryItemFile {
+  path: string;
+  target?: string;
+  type?: string;
+}
+
+export interface RegistryItem {
+  name: string;
+  type: string;
+  title?: string;
+  description?: string;
+  tags?: string[];
+  files: RegistryItemFile[];
+  params?: Array<{ key: string; label?: string; type?: string; default?: string }>;
+}
+
+/** Registry item type → URL path segment. Examples are not installable. */
+export function kindFromType(t: string): 'blocks' | 'components' | null {
+  if (t === 'hyperframes:block') return 'blocks';
+  if (t === 'hyperframes:component') return 'components';
+  return null;
+}
+
+async function fetchText(url: string, fetchImpl: FetchLike): Promise<string> {
+  const res = await fetchImpl(url);
+  if (!res.ok) {
+    throw new Error(`Registry fetch failed (${res.status}): ${url}`);
+  }
+  return res.text();
+}
+
+export async function fetchRegistryIndex(
+  registryUrl: string,
+  fetchImpl: FetchLike = fetch,
+): Promise<RegistryIndexItem[]> {
+  const raw = await fetchText(`${registryUrl}/registry.json`, fetchImpl);
+  const parsed = JSON.parse(raw) as { items?: RegistryIndexItem[] };
+  if (!Array.isArray(parsed.items)) {
+    throw new Error(`Malformed registry index: expected an "items" array at ${registryUrl}/registry.json`);
+  }
+  return parsed.items;
+}
+
+export async function fetchRegistryItem(
+  registryUrl: string,
+  kind: 'blocks' | 'components',
+  name: string,
+  fetchImpl: FetchLike = fetch,
+): Promise<RegistryItem> {
+  const raw = await fetchText(`${registryUrl}/${kind}/${name}/registry-item.json`, fetchImpl);
+  const item = JSON.parse(raw) as RegistryItem;
+  if (!item.name || !Array.isArray(item.files)) {
+    throw new Error(`Malformed registry-item.json for "${name}": missing name or files`);
+  }
+  return item;
+}
+
+export async function fetchItemFile(
+  registryUrl: string,
+  kind: 'blocks' | 'components',
+  name: string,
+  filePath: string,
+  fetchImpl: FetchLike = fetch,
+): Promise<string> {
+  return fetchText(`${registryUrl}/${kind}/${name}/${filePath}`, fetchImpl);
+}
+```
+
+Note: the error message for HTTP failure contains "Registry fetch failed (404)" which satisfies the test's `/registry.*404/i`.
+
+- [ ] **Step 4: Run test to verify it passes**
+
+Run: `npx vitest run tests/hf/registry-client.test.ts`
+Expected: PASS (7 tests)
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add src/hf/registry-client.ts tests/hf/registry-client.test.ts
+git -c commit.gpgsign=false commit -m "feat(hf): hyperframes registry client with injectable fetch"
+```
+
+---
+
+### Task 2: Installer
+
+**Files:**
+- Create: `src/hf/add.ts`
+- Test: `tests/hf/add.test.ts`
+
+**Interfaces:**
+- Consumes: everything from Task 1's `registry-client.ts` (exact names above).
+- Produces (Task 3 depends on):
+  - `interface InstallResult { name: string; kind: 'blocks' | 'components'; files: string[]; targetDir: string }`
+  - `installItem(opts: { name: string; blocksDir: string; registryUrl?: string; fetchImpl?: FetchLike }): Promise<InstallResult>`
+  - `listItems(opts: { registryUrl?: string; fetchImpl?: FetchLike }): Promise<RegistryIndexItem[]>`
+
+- [ ] **Step 1: Write the failing test**
+
+Create `tests/hf/add.test.ts`:
+
+```typescript
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import { mkdtempSync, rmSync, existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { tmpdir } from 'node:os';
+import { installItem, listItems } from '../../src/hf/add.js';
+import type { FetchLike } from '../../src/hf/registry-client.js';
+
+const REG = 'https://example.test/registry';
+
+function stubFetch(routes: Record<string, string>): FetchLike {
+  return async (url: string) => ({
+    ok: routes[url] !== undefined,
+    status: routes[url] !== undefined ? 200 : 404,
+    text: async () => routes[url] ?? 'not found',
+  });
+}
+
+const ROUTES = {
+  [`${REG}/registry.json`]: JSON.stringify({
+    items: [
+      { name: 'vignette', type: 'hyperframes:component' },
+      { name: 'logo-outro', type: 'hyperframes:block' },
+      { name: 'warm-grain', type: 'hyperframes:example' },
+    ],
+  }),
+  [`${REG}/components/vignette/registry-item.json`]: JSON.stringify({
+    name: 'vignette',
+    type: 'hyperframes:component',
+    files: [{ path: 'vignette.html' }],
+  }),
+  [`${REG}/components/vignette/vignette.html`]: '<div id="hf-vignette"></div>',
+};
+
+describe('installItem', () => {
+  let tmp: string;
+  beforeEach(() => { tmp = mkdtempSync(join(tmpdir(), 'argo-add-')); });
+  afterEach(() => { rmSync(tmp, { recursive: true, force: true }); });
+
+  it('installs a component: files + registry-item.json under blocksDir/<name>/', async () => {
+    const result = await installItem({
+      name: 'vignette', blocksDir: tmp, registryUrl: REG, fetchImpl: stubFetch(ROUTES),
+    });
+    expect(result.kind).toBe('components');
+    expect(existsSync(join(tmp, 'vignette', 'vignette.html'))).toBe(true);
+    expect(existsSync(join(tmp, 'vignette', 'registry-item.json'))).toBe(true);
+    expect(readFileSync(join(tmp, 'vignette', 'vignette.html'), 'utf-8')).toContain('hf-vignette');
+    expect(result.files).toContain('vignette.html');
+  });
+
+  it('rejects invalid item names (path traversal guard)', async () => {
+    for (const bad of ['../evil', 'a/b', '.hidden', 'name!']) {
+      await expect(
+        installItem({ name: bad, blocksDir: tmp, registryUrl: REG, fetchImpl: stubFetch(ROUTES) }),
+      ).rejects.toThrow(/invalid item name/i);
+    }
+  });
+
+  it('rejects example items with a helpful error', async () => {
+    await expect(
+      installItem({ name: 'warm-grain', blocksDir: tmp, registryUrl: REG, fetchImpl: stubFetch(ROUTES) }),
+    ).rejects.toThrow(/example.*not installable/i);
+  });
+
+  it('rejects unknown items pointing at --list', async () => {
+    await expect(
+      installItem({ name: 'nope', blocksDir: tmp, registryUrl: REG, fetchImpl: stubFetch(ROUTES) }),
+    ).rejects.toThrow(/not found.*--list/is);
+  });
+
+  it('rejects item files with unsafe paths', async () => {
+    const routes = {
+      ...ROUTES,
+      [`${REG}/components/vignette/registry-item.json`]: JSON.stringify({
+        name: 'vignette',
+        type: 'hyperframes:component',
+        files: [{ path: '../../etc/passwd' }],
+      }),
+    };
+    await expect(
+      installItem({ name: 'vignette', blocksDir: tmp, registryUrl: REG, fetchImpl: stubFetch(routes) }),
+    ).rejects.toThrow(/unsafe file path/i);
+  });
+});
+
+describe('listItems', () => {
+  it('returns the raw index', async () => {
+    const items = await listItems({ registryUrl: REG, fetchImpl: stubFetch(ROUTES) });
+    expect(items).toHaveLength(3);
+  });
+});
+```
+
+- [ ] **Step 2: Run test to verify it fails**
+
+Run: `npx vitest run tests/hf/add.test.ts`
+Expected: FAIL — module not found.
+
+- [ ] **Step 3: Write the implementation**
+
+Create `src/hf/add.ts`:
+
+```typescript
+import { mkdirSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import {
+  DEFAULT_REGISTRY_URL,
+  fetchItemFile,
+  fetchRegistryIndex,
+  fetchRegistryItem,
+  kindFromType,
+  type FetchLike,
+  type RegistryIndexItem,
+} from './registry-client.js';
+
+/** Same pattern the CLI uses for demo names — path-traversal guard. */
+const ITEM_NAME_RE = /^[a-zA-Z0-9][a-zA-Z0-9_-]*$/;
+/** Item file paths must be flat (no slashes) — e.g. "vignette.html". */
+const ITEM_FILE_RE = /^[a-zA-Z0-9][a-zA-Z0-9._-]*$/;
+
+export interface InstallResult {
+  name: string;
+  kind: 'blocks' | 'components';
+  files: string[];
+  targetDir: string;
+}
+
+export async function listItems(opts: {
+  registryUrl?: string;
+  fetchImpl?: FetchLike;
+}): Promise<RegistryIndexItem[]> {
+  return fetchRegistryIndex(opts.registryUrl ?? DEFAULT_REGISTRY_URL, opts.fetchImpl ?? fetch);
+}
+
+export async function installItem(opts: {
+  name: string;
+  blocksDir: string;
+  registryUrl?: string;
+  fetchImpl?: FetchLike;
+}): Promise<InstallResult> {
+  const { name, blocksDir } = opts;
+  const registryUrl = opts.registryUrl ?? DEFAULT_REGISTRY_URL;
+  const fetchImpl = opts.fetchImpl ?? (fetch as FetchLike);
+
+  if (!ITEM_NAME_RE.test(name)) {
+    throw new Error(
+      `Invalid item name "${name}" — only letters, digits, "-" and "_" are allowed.`,
+    );
+  }
+
+  const index = await fetchRegistryIndex(registryUrl, fetchImpl);
+  const entry = index.find((i) => i.name === name);
+  if (!entry) {
+    throw new Error(
+      `Item "${name}" not found in the registry.\nBrowse available items with: argo add --list`,
+    );
+  }
+
+  const kind = kindFromType(entry.type);
+  if (!kind) {
+    throw new Error(
+      `"${name}" is a registry example and examples are not installable via argo add. ` +
+        `Use the hyperframes CLI (hyperframes init --example ${name}) instead.`,
+    );
+  }
+
+  const item = await fetchRegistryItem(registryUrl, kind, name, fetchImpl);
+  for (const f of item.files) {
+    if (!ITEM_FILE_RE.test(f.path)) {
+      throw new Error(`Unsafe file path in registry-item.json for "${name}": "${f.path}"`);
+    }
+  }
+
+  const targetDir = join(blocksDir, name);
+  mkdirSync(targetDir, { recursive: true });
+
+  const written: string[] = [];
+  for (const f of item.files) {
+    const content = await fetchItemFile(registryUrl, kind, name, f.path, fetchImpl);
+    writeFileSync(join(targetDir, f.path), content, 'utf-8');
+    written.push(f.path);
+  }
+  writeFileSync(join(targetDir, 'registry-item.json'), JSON.stringify(item, null, 2), 'utf-8');
+
+  return { name, kind, files: written, targetDir };
+}
+```
+
+- [ ] **Step 4: Run test to verify it passes**
+
+Run: `npx vitest run tests/hf/add.test.ts`
+Expected: PASS (7 tests)
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add src/hf/add.ts tests/hf/add.test.ts
+git -c commit.gpgsign=false commit -m "feat(hf): installItem/listItems with path-traversal guards"
+```
+
+---
+
+### Task 3: Config fields + `argo add` CLI command
+
+**Files:**
+- Modify: `src/config.ts` (ArgoConfig at :232, DEFAULTS at :253, and `defineConfig`)
+- Modify: `src/cli.ts` (new command; place it after the existing `validate` command block that ends near :372)
+- Test: `tests/hf/config-blocks.test.ts`
+
+**Interfaces:**
+- Consumes: `installItem`, `listItems` (Task 2).
+- Produces: `ArgoConfig.blocksDir: string` (default `'blocks'`), `ArgoConfig.registry?: { url?: string }`. Tasks 5–7 read `config.blocksDir`; the CLI command exists end-to-end.
+
+- [ ] **Step 1: Write the failing test**
+
+Create `tests/hf/config-blocks.test.ts`:
+
+```typescript
+import { describe, it, expect } from 'vitest';
+import { defineConfig } from '../../src/config.js';
+
+describe('blocksDir / registry config', () => {
+  it('defaults blocksDir to "blocks"', () => {
+    expect(defineConfig({}).blocksDir).toBe('blocks');
+  });
+
+  it('honors a custom blocksDir', () => {
+    expect(defineConfig({ blocksDir: 'assets/hf' }).blocksDir).toBe('assets/hf');
+  });
+
+  it('passes registry.url through and defaults registry to undefined', () => {
+    expect(defineConfig({}).registry).toBeUndefined();
+    expect(defineConfig({ registry: { url: 'https://x.test/reg' } }).registry?.url).toBe(
+      'https://x.test/reg',
+    );
+  });
+});
+```
+
+- [ ] **Step 2: Run test to verify it fails**
+
+Run: `npx vitest run tests/hf/config-blocks.test.ts`
+Expected: FAIL — `blocksDir`/`registry` not on `ArgoConfig` (TS) / undefined at runtime.
+
+- [ ] **Step 3: Implement config fields**
+
+In `src/config.ts`:
+
+**3a.** Add to `interface ArgoConfig` (line ~232, after `outputDir: string;`):
+
+```typescript
+  /** Directory where `argo add` installs hyperframes registry items. Default 'blocks'. */
+  blocksDir: string;
+  /** Registry override for `argo add`. Defaults to the hyperframes GitHub registry. */
+  registry?: { url?: string };
+```
+
+**3b.** Add to `DEFAULTS` (line ~253): `blocksDir: 'blocks',`
+
+**3c.** In `defineConfig`, follow the exact pattern the function already uses for top-level fields like `demosDir`/`outputDir` (Read the function body first): ensure the returned object includes `blocksDir: userConfig.blocksDir ?? DEFAULTS.blocksDir` and `registry: userConfig.registry`. If `defineConfig` builds its result with a spread of `DEFAULTS` then `userConfig`, the default may already flow — verify with the test rather than assuming.
+
+- [ ] **Step 4: Run config test to verify it passes**
+
+Run: `npx vitest run tests/hf/config-blocks.test.ts`
+Expected: PASS (3 tests)
+
+- [ ] **Step 5: Add the CLI command**
+
+In `src/cli.ts`, after the `validate` command registration block, add:
+
+```typescript
+  program
+    .command('add [name]')
+    .description('Install a block or component from the hyperframes registry into blocksDir')
+    .option('--list', 'list available registry items instead of installing')
+    .option('--json', 'machine-readable output')
+    .option('--registry <url>', 'override the registry URL')
+    .action(async (name: string | undefined, cmdOpts: { list?: boolean; json?: boolean; registry?: string }) => {
+      const { installItem, listItems } = await import('./hf/add.js');
+      const config = await loadConfig();
+      const registryUrl = cmdOpts.registry ?? config.registry?.url;
+
+      if (cmdOpts.list) {
+        const items = await listItems({ registryUrl });
+        if (cmdOpts.json) {
+          console.log(JSON.stringify(items, null, 2));
+        } else {
+          for (const item of items) {
+            console.log(`${item.type.replace('hyperframes:', '').padEnd(10)} ${item.name}`);
+          }
+          console.log(`\n${items.length} items. Install with: argo add <name>`);
+        }
+        return;
+      }
+
+      if (!name) {
+        console.error('Usage: argo add <name>  (or argo add --list)');
+        process.exitCode = 1;
+        return;
+      }
+
+      try {
+        const result = await installItem({ name, blocksDir: config.blocksDir, registryUrl });
+        if (cmdOpts.json) {
+          console.log(JSON.stringify(result, null, 2));
+        } else {
+          console.log(`Installed ${result.kind === 'components' ? 'component' : 'block'} "${result.name}" → ${result.targetDir}/`);
+          for (const f of result.files) console.log(`  ${f}`);
+          if (result.kind === 'components') {
+            console.log(`\nUse it in a scene: "overlay": { "type": "hf-component", "name": "${result.name}" }`);
+            console.log(`Or in a demo script: await applyComponent(page, '${result.name}')`);
+          }
+        }
+      } catch (err) {
+        console.error((err as Error).message);
+        process.exitCode = 1;
+      }
+    });
+```
+
+Match the surrounding file's conventions for how `loadConfig` is called in other commands (Read a neighboring command's action first — e.g. `validate` — and mirror its config-loading call exactly, including any arguments it passes).
+
+- [ ] **Step 6: Build + verify the command wires up**
+
+Run: `npm run build && node bin/argo.js add --help`
+Expected: build exit 0; help text shows `--list`, `--json`, `--registry`.
+
+- [ ] **Step 7: Commit**
+
+```bash
+git add src/config.ts src/cli.ts tests/hf/config-blocks.test.ts
+git -c commit.gpgsign=false commit -m "feat(cli): argo add command + blocksDir/registry config"
+```
+
+---
+
+### Task 4: Component snippet parser + param safety
+
+**Files:**
+- Create: `src/hf/component.ts`
+- Test: `tests/hf/component.test.ts`
+
+**Interfaces:**
+- Consumes: nothing.
+- Produces (Task 5 depends on): `interface ComponentSnippet { html: string; css: string; js: string }`, `parseComponentSnippet(source: string): ComponentSnippet`, `isSafeCssValue(v: string): boolean`, `isSafeCssVarName(k: string): boolean`.
+
+- [ ] **Step 1: Write the failing test**
+
+Create `tests/hf/component.test.ts`:
+
+```typescript
+import { describe, it, expect } from 'vitest';
+import { parseComponentSnippet, isSafeCssValue, isSafeCssVarName } from '../../src/hf/component.js';
+
+const VIGNETTE_LIKE = `<!--
+  Vignette — usage notes here.
+-->
+<div id="hf-vignette" style="position: absolute; inset: 0; pointer-events: none;"></div>
+<style>
+  #hf-vignette { background: radial-gradient(ellipse at center, transparent 45%, rgba(0,0,0,0.7) 100%); }
+</style>
+<!-- Timeline integration example: tl.fromTo("#hf-vignette", ...) -->`;
+
+const SHIMMER_LIKE = `<style>
+  .shimmer-sweep-target { position: relative; }
+</style>
+<script>
+  (function () { document.querySelectorAll(".shimmer-sweep-target").forEach(() => {}); })();
+</script>`;
+
+describe('parseComponentSnippet', () => {
+  it('splits a root-element component into html + css, stripping comments', () => {
+    const s = parseComponentSnippet(VIGNETTE_LIKE);
+    expect(s.html).toContain('hf-vignette');
+    expect(s.html).not.toContain('<style');
+    expect(s.html).not.toContain('Timeline integration');
+    expect(s.css).toContain('radial-gradient');
+    expect(s.js).toBe('');
+  });
+
+  it('extracts scripts from style+script components (no root element)', () => {
+    const s = parseComponentSnippet(SHIMMER_LIKE);
+    expect(s.html).toBe('');
+    expect(s.css).toContain('.shimmer-sweep-target');
+    expect(s.js).toContain('querySelectorAll');
+  });
+});
+
+describe('param safety', () => {
+  it('accepts normal CSS values', () => {
+    for (const ok of ['rgba(0, 0, 0, 0.7)', '45%', '120deg', '#ff8800', 'ellipse', '2.5s']) {
+      expect(isSafeCssValue(ok), ok).toBe(true);
+    }
+  });
+
+  it('rejects values that could escape a declaration or load resources', () => {
+    for (const bad of [
+      'red; background: blue',
+      '} body { display: none',
+      'url(https://evil.test/x)',
+      'expression(alert(1))',
+      '<script>',
+      'javascript:alert(1)',
+      '@import "x"',
+    ]) {
+      expect(isSafeCssValue(bad), bad).toBe(false);
+    }
+  });
+
+  it('validates custom property names', () => {
+    expect(isSafeCssVarName('--vignette-size')).toBe(true);
+    expect(isSafeCssVarName('--x')).toBe(true);
+    expect(isSafeCssVarName('color')).toBe(false);
+    expect(isSafeCssVarName('--bad;inject')).toBe(false);
+  });
+});
+```
+
+- [ ] **Step 2: Run test to verify it fails**
+
+Run: `npx vitest run tests/hf/component.test.ts`
+Expected: FAIL — module not found.
+
+- [ ] **Step 3: Write the implementation**
+
+Create `src/hf/component.ts`:
+
+```typescript
+/**
+ * Parse a hyperframes component snippet (HTML + <style> + optional <script>,
+ * with usage notes in HTML comments) into injectable parts.
+ *
+ * Components are trusted-at-install (the user chose to `argo add` them and
+ * the files are git-reviewable), but cue/script `params` are runtime input —
+ * they are validated before being set as CSS custom properties.
+ */
+
+export interface ComponentSnippet {
+  html: string;
+  css: string;
+  js: string;
+}
+
+export function parseComponentSnippet(source: string): ComponentSnippet {
+  const noComments = source.replace(/<!--[\s\S]*?-->/g, '');
+  const css: string[] = [];
+  const js: string[] = [];
+  let rest = noComments.replace(/<style[^>]*>([\s\S]*?)<\/style>/gi, (_m, body: string) => {
+    css.push(body.trim());
+    return '';
+  });
+  rest = rest.replace(/<script[^>]*>([\s\S]*?)<\/script>/gi, (_m, body: string) => {
+    js.push(body.trim());
+    return '';
+  });
+  return { html: rest.trim(), css: css.join('\n\n'), js: js.join('\n\n') };
+}
+
+/** CSS custom property name: --kebab-or-camel, nothing else. */
+export function isSafeCssVarName(k: string): boolean {
+  return /^--[a-zA-Z][a-zA-Z0-9-]*$/.test(k);
+}
+
+/**
+ * Conservative allowlist-by-rejection for CSS custom property VALUES.
+ * Blocks declaration/block escapes and resource loads. Values are plain
+ * lengths, colors, keywords, and simple functions like rgba()/calc().
+ */
+export function isSafeCssValue(v: string): boolean {
+  if (typeof v !== 'string' || v.length === 0 || v.length > 200) return false;
+  if (/[;{}<>]/.test(v)) return false;
+  if (/url\s*\(|expression\s*\(|@import|javascript:/i.test(v)) return false;
+  // Reject raw control characters — never legitimate in a CSS value.
+  // eslint-disable-next-line no-control-regex
+  if (/[\u0000-\u001f\u007f]/.test(v)) return false;
+  return true;
+}
+```
+
+- [ ] **Step 4: Run test to verify it passes**
+
+Run: `npx vitest run tests/hf/component.test.ts`
+Expected: PASS (5 tests)
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add src/hf/component.ts tests/hf/component.test.ts
+git -c commit.gpgsign=false commit -m "feat(hf): component snippet parser + CSS param safety checks"
+```
+
+---
+
+### Task 5: `applyComponent` / `removeComponent` page injection
+
+**Files:**
+- Create: `src/hf/apply-component.ts`
+- Modify: `src/index.ts` (add export line)
+- Test: `tests/hf/apply-component.test.ts` (Playwright integration — the one allowed browser test)
+
+**Interfaces:**
+- Consumes: `parseComponentSnippet`, `isSafeCssValue`, `isSafeCssVarName` (Task 4).
+- Produces (Task 6 depends on):
+  - `resolveBlocksDir(explicit?: string): string` — `explicit ?? process.env.ARGO_BLOCKS_DIR ?? 'blocks'`
+  - `applyComponent(page: Page, name: string, opts?: { params?: Record<string, string>; blocksDir?: string }): Promise<void>`
+  - `removeComponent(page: Page, name: string): Promise<void>`
+
+Injection contract (Task 6's cue dispatch and the docs rely on this): container `<div id="argo-hf-<name>">`, fixed full-viewport, `pointer-events: none`, `z-index: 2147482000`; component CSS in a `<style data-argo-hf="<name>">` in `<head>`; params set as CSS custom properties on BOTH the container and `document.documentElement` (components like shimmer-sweep target page elements outside the container); param keys recorded on `container.dataset.argoHfParams` so `removeComponent` can clean up the documentElement props; scripts run via `new Function(js)()` (CSP caveat: on apps with a strict `script-src` this throws — surface as a warning naming CSP, do not fail the demo).
+
+- [ ] **Step 1: Write the failing test**
+
+Create `tests/hf/apply-component.test.ts`:
+
+```typescript
+import { describe, it, expect, beforeAll, afterAll, beforeEach, afterEach } from 'vitest';
+import { mkdtempSync, rmSync, mkdirSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { tmpdir } from 'node:os';
+import { chromium, type Browser, type Page } from 'playwright';
+import { applyComponent, removeComponent, resolveBlocksDir } from '../../src/hf/apply-component.js';
+
+const SNIPPET = `<div id="hf-vignette"></div>
+<style>#hf-vignette { position: absolute; inset: 0; background: radial-gradient(ellipse, transparent var(--vignette-size, 45%), rgba(0,0,0,0.7) 100%); }</style>
+<script>document.documentElement.dataset.hfScriptRan = '1';</script>`;
+
+let browser: Browser;
+let page: Page;
+let tmp: string;
+
+beforeAll(async () => {
+  browser = await chromium.launch();
+}, 60_000);
+afterAll(async () => { await browser.close(); });
+
+beforeEach(async () => {
+  tmp = mkdtempSync(join(tmpdir(), 'argo-apply-'));
+  mkdirSync(join(tmp, 'vignette'), { recursive: true });
+  writeFileSync(join(tmp, 'vignette', 'vignette.html'), SNIPPET);
+  page = await browser.newPage();
+  await page.setContent('<h1>app</h1>');
+});
+afterEach(async () => {
+  await page.close();
+  rmSync(tmp, { recursive: true, force: true });
+});
+
+describe('resolveBlocksDir', () => {
+  it('prefers explicit, then env, then "blocks"', () => {
+    const prev = process.env.ARGO_BLOCKS_DIR;
+    delete process.env.ARGO_BLOCKS_DIR;
+    expect(resolveBlocksDir('x')).toBe('x');
+    expect(resolveBlocksDir()).toBe('blocks');
+    process.env.ARGO_BLOCKS_DIR = '/tmp/bd';
+    expect(resolveBlocksDir()).toBe('/tmp/bd');
+    if (prev === undefined) delete process.env.ARGO_BLOCKS_DIR; else process.env.ARGO_BLOCKS_DIR = prev;
+  });
+});
+
+describe('applyComponent / removeComponent', () => {
+  it('injects container + style + runs script, applies params, and removes cleanly', async () => {
+    await applyComponent(page, 'vignette', {
+      blocksDir: tmp,
+      params: { '--vignette-size': '30%' },
+    });
+
+    expect(await page.locator('#argo-hf-vignette').count()).toBe(1);
+    expect(await page.locator('style[data-argo-hf="vignette"]').count()).toBe(1);
+    expect(await page.evaluate(() => document.documentElement.dataset.hfScriptRan)).toBe('1');
+    expect(
+      await page.evaluate(() =>
+        document.documentElement.style.getPropertyValue('--vignette-size'),
+      ),
+    ).toBe('30%');
+
+    await removeComponent(page, 'vignette');
+    expect(await page.locator('#argo-hf-vignette').count()).toBe(0);
+    expect(await page.locator('style[data-argo-hf="vignette"]').count()).toBe(0);
+    expect(
+      await page.evaluate(() =>
+        document.documentElement.style.getPropertyValue('--vignette-size'),
+      ),
+    ).toBe('');
+  });
+
+  it('throws for a component that is not installed', async () => {
+    await expect(applyComponent(page, 'nope', { blocksDir: tmp })).rejects.toThrow(/argo add nope/);
+  });
+
+  it('rejects unsafe params before touching the page', async () => {
+    await expect(
+      applyComponent(page, 'vignette', { blocksDir: tmp, params: { '--x': 'red; }' } }),
+    ).rejects.toThrow(/unsafe/i);
+    await expect(
+      applyComponent(page, 'vignette', { blocksDir: tmp, params: { 'not-a-var': 'red' } }),
+    ).rejects.toThrow(/custom property/i);
+  });
+}, 60_000);
+```
+
+- [ ] **Step 2: Run test to verify it fails**
+
+Run: `npx vitest run tests/hf/apply-component.test.ts`
+Expected: FAIL — module not found.
+
+- [ ] **Step 3: Write the implementation**
+
+First Read the top of `src/effects.ts` to copy its `Page` import style and its disposal-error filter helper exactly (the catch block that swallows only page/context-closed errors and warns on everything else). Then create `src/hf/apply-component.ts`:
+
+```typescript
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import type { Page } from 'playwright';
+import { isSafeCssValue, isSafeCssVarName, parseComponentSnippet } from './component.js';
+
+const ITEM_NAME_RE = /^[a-zA-Z0-9][a-zA-Z0-9_-]*$/;
+const CONTAINER_PREFIX = 'argo-hf-';
+
+export function resolveBlocksDir(explicit?: string): string {
+  return explicit ?? process.env.ARGO_BLOCKS_DIR ?? 'blocks';
+}
+
+export interface ApplyComponentOptions {
+  /** CSS custom property overrides, e.g. { '--vignette-size': '40%' }. */
+  params?: Record<string, string>;
+  /** Override the blocks directory (defaults to ARGO_BLOCKS_DIR or 'blocks'). */
+  blocksDir?: string;
+}
+
+/**
+ * Inject an installed hyperframes component (full-frame, pointer-events:
+ * none) into the recorded page. Persists until removeComponent() — pair
+ * them, or use the `hf-component` overlay cue for duration-based display.
+ */
+export async function applyComponent(
+  page: Page,
+  name: string,
+  opts?: ApplyComponentOptions,
+): Promise<void> {
+  if (!ITEM_NAME_RE.test(name)) {
+    throw new Error(`Invalid component name "${name}"`);
+  }
+  const dir = resolveBlocksDir(opts?.blocksDir);
+  const file = join(dir, name, `${name}.html`);
+  if (!existsSync(file)) {
+    throw new Error(`Component "${name}" is not installed (looked in ${dir}/). Run: argo add ${name}`);
+  }
+  const snippet = parseComponentSnippet(readFileSync(file, 'utf-8'));
+
+  const params = opts?.params ?? {};
+  for (const [k, v] of Object.entries(params)) {
+    if (!isSafeCssVarName(k)) {
+      throw new Error(`Param "${k}" is not a CSS custom property name (must match --kebab-case)`);
+    }
+    if (!isSafeCssValue(v)) {
+      throw new Error(`Unsafe CSS value for param "${k}": ${JSON.stringify(v)}`);
+    }
+  }
+
+  // Render fence — flush pending browser renders before injecting (same
+  // rationale as overlay injection; see src/overlays/zones.ts).
+  await page.evaluate(() => {});
+  await page.evaluate(
+    ({ name, html, css, js, params, prefix }) => {
+      const id = prefix + name;
+      document.getElementById(id)?.remove();
+      document.querySelectorAll(`style[data-argo-hf="${name}"]`).forEach((el) => el.remove());
+
+      if (css) {
+        const st = document.createElement('style');
+        st.setAttribute('data-argo-hf', name);
+        st.textContent = css;
+        document.head.appendChild(st);
+      }
+
+      const container = document.createElement('div');
+      container.id = id;
+      container.style.cssText =
+        'position:fixed;top:0;left:0;width:100vw;height:100vh;pointer-events:none;z-index:2147482000';
+      for (const [k, v] of Object.entries(params)) {
+        container.style.setProperty(k, v);
+        document.documentElement.style.setProperty(k, v);
+      }
+      container.dataset.argoHfParams = JSON.stringify(Object.keys(params));
+      if (html) container.innerHTML = html;
+      document.body.appendChild(container);
+
+      if (js) {
+        try {
+          new Function(js)();
+        } catch (e) {
+          console.warn(
+            `[argo] component "${name}" script failed (strict CSP can block injected scripts): ${String(e)}`,
+          );
+        }
+      }
+    },
+    { name, html: snippet.html, css: snippet.css, js: snippet.js, params, prefix: CONTAINER_PREFIX },
+  );
+}
+
+/** Remove an applied component and its params/styles. */
+export async function removeComponent(page: Page, name: string): Promise<void> {
+  if (!ITEM_NAME_RE.test(name)) return;
+  await page.evaluate(
+    ({ name, prefix }) => {
+      const container = document.getElementById(prefix + name);
+      if (container?.dataset.argoHfParams) {
+        try {
+          for (const k of JSON.parse(container.dataset.argoHfParams) as string[]) {
+            document.documentElement.style.removeProperty(k);
+          }
+        } catch {
+          /* ignore malformed dataset */
+        }
+      }
+      container?.remove();
+      document.querySelectorAll(`style[data-argo-hf="${name}"]`).forEach((el) => el.remove());
+    },
+    { name, prefix: CONTAINER_PREFIX },
+  );
+}
+```
+
+Then wrap the two `page.evaluate` bodies' outer calls in the same try/catch disposal-filter pattern `showConfetti` uses (swallow page/context-closed errors, `console.warn` everything else) — copy that catch block verbatim from `src/effects.ts` so the error-handling contract matches the rest of the effects API. Note: the param/name validation and the not-installed check must throw BEFORE the try/catch region (the test asserts they reject).
+
+**Export:** add to `src/index.ts`, near the `showConfetti` export (line ~57):
+
+```typescript
+export {
+  applyComponent,
+  removeComponent,
+  type ApplyComponentOptions,
+} from './hf/apply-component.js';
+```
+
+- [ ] **Step 4: Run test to verify it passes**
+
+Run: `npx vitest run tests/hf/apply-component.test.ts`
+Expected: PASS (5 tests; launches chromium, ~5-15s)
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add src/hf/apply-component.ts src/index.ts tests/hf/apply-component.test.ts
+git -c commit.gpgsign=false commit -m "feat(hf): applyComponent/removeComponent page injection"
+```
+
+---
+
+### Task 6: `hf-component` overlay cue + env bridge
+
+**Files:**
+- Modify: `src/overlays/types.ts` (add cue interface; extend union at :101)
+- Modify: `src/overlays/index.ts` (early dispatch in `showOverlay` at :90 and `withOverlay` at :159)
+- Modify: `src/overlays/templates.ts` (`renderTemplate` switch — add throw case for exhaustiveness)
+- Modify: `src/record.ts` (`RecordOptions` + env at :293)
+- Modify: `src/pipeline.ts:172` block, `src/pipeline.ts:527` block, `src/cli.ts:93` block (add `blocksDir: config.blocksDir,` to each `record()` options object)
+- Test: `tests/hf/hf-component-cue.test.ts`
+
+**Interfaces:**
+- Consumes: `applyComponent`, `removeComponent` (Task 5), `config.blocksDir` (Task 3).
+- Produces: `HfComponentCue { type: 'hf-component'; name: string; params?: Record<string, string>; placement?: Zone }` in the `OverlayCue` union; `RecordOptions.blocksDir?: string`; `ARGO_BLOCKS_DIR` env in the Playwright subprocess. Task 7 validates the cue; Task 8 documents it.
+
+- [ ] **Step 1: Write the failing test**
+
+Create `tests/hf/hf-component-cue.test.ts`:
+
+```typescript
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import { mkdtempSync, rmSync, mkdirSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { tmpdir } from 'node:os';
+import type { OverlayCue } from '../../src/overlays/types.js';
+import { showOverlay } from '../../src/overlays/index.js';
+import { renderTemplate } from '../../src/overlays/templates.js';
+
+describe('HfComponentCue', () => {
+  it('is part of the OverlayCue union at compile time', () => {
+    const cue: OverlayCue = { type: 'hf-component', name: 'vignette', params: { '--x': '1' } };
+    expect(cue.type).toBe('hf-component');
+  });
+
+  it('renderTemplate rejects hf-component cues with a pointer to the right path', () => {
+    expect(() => renderTemplate({ type: 'hf-component', name: 'vignette' })).toThrow(
+      /full-frame/i,
+    );
+  });
+});
+
+describe('showOverlay dispatch for hf-component', () => {
+  let tmp: string;
+  let prevEnv: string | undefined;
+  beforeEach(() => {
+    tmp = mkdtempSync(join(tmpdir(), 'argo-cue-'));
+    mkdirSync(join(tmp, 'vignette'), { recursive: true });
+    writeFileSync(join(tmp, 'vignette', 'vignette.html'), '<div id="hf-vignette"></div>');
+    prevEnv = process.env.ARGO_BLOCKS_DIR;
+    process.env.ARGO_BLOCKS_DIR = tmp;
+  });
+  afterEach(() => {
+    rmSync(tmp, { recursive: true, force: true });
+    if (prevEnv === undefined) delete process.env.ARGO_BLOCKS_DIR;
+    else process.env.ARGO_BLOCKS_DIR = prevEnv;
+  });
+
+  it('applies, waits durationMs, and removes — never touching zone machinery', async () => {
+    const calls: string[] = [];
+    const fakePage = {
+      evaluate: async () => { calls.push('evaluate'); },
+      waitForTimeout: async (ms: number) => { calls.push(`wait:${ms}`); },
+    };
+    await showOverlay(
+      fakePage as never,
+      'intro',
+      { type: 'hf-component', name: 'vignette' },
+      1200,
+    );
+    // applyComponent issues 2 evaluates (fence + inject), removeComponent 1.
+    expect(calls).toEqual(['evaluate', 'evaluate', 'wait:1200', 'evaluate']);
+  });
+});
+```
+
+- [ ] **Step 2: Run test to verify it fails**
+
+Run: `npx vitest run tests/hf/hf-component-cue.test.ts`
+Expected: FAIL — `'hf-component'` not assignable to `OverlayCue['type']` (TS via vitest transform runs, so runtime failures: renderTemplate falls through / dispatch missing → different call sequence).
+
+- [ ] **Step 3: Implement**
+
+**3a.** In `src/overlays/types.ts`, add before the union (line ~101):
+
+```typescript
+export interface HfComponentCue {
+  type: 'hf-component';
+  /** Installed component name under blocksDir (see `argo add`). */
+  name: string;
+  /** CSS custom property overrides, e.g. { '--vignette-size': '40%' }. */
+  params?: Record<string, string>;
+  /** Accepted for manifest uniformity but ignored — components are full-frame. */
+  placement?: Zone;
+}
+```
+
+and extend the union:
+
+```typescript
+export type OverlayCue = LowerThirdCue | HeadlineCardCue | CalloutCue | ImageCardCue | ArrowCue | CustomBlockCue | HfComponentCue;
+```
+
+(If `Zone` is not already imported in types.ts, mirror how `placement` is typed on the other cue interfaces in this file — use exactly that type.)
+
+**3b.** In `src/overlays/index.ts`, import `applyComponent`/`removeComponent` from `../hf/apply-component.js`, then insert the early dispatch in `showOverlay` immediately after `cue`/`durationMs` are resolved (after the `if (typeof cueOrDuration === 'number') {...} else {...}` block, before the `const zone: Zone = ...` line):
+
+```typescript
+  if (cue.type === 'hf-component') {
+    // Full-frame component — bypasses zone/theme/template machinery.
+    await applyComponent(page, cue.name, { params: cue.params });
+    await page.waitForTimeout(durationMs);
+    await removeComponent(page, cue.name);
+    return;
+  }
+```
+
+In `withOverlay`, add the equivalent branch after its cue resolution (Read the function body first — it wraps a user action; apply before running the action, remove in the `finally`):
+
+```typescript
+  if (cue.type === 'hf-component') {
+    await applyComponent(page, cue.name, { params: cue.params });
+    try {
+      return await action();
+    } finally {
+      await removeComponent(page, cue.name);
+    }
+  }
+```
+
+(Adjust the `action` identifier to the actual parameter name used in `withOverlay` — read it, don't guess.)
+
+**3c.** In `src/overlays/templates.ts`, add to the `renderTemplate` switch before the closing brace:
+
+```typescript
+    case 'hf-component':
+      throw new Error(
+        'hf-component cues are injected full-frame by showOverlay/applyComponent, not rendered as zone templates.',
+      );
+```
+
+**3d.** In `src/record.ts`: add to `RecordOptions` (line ~9 block): `blocksDir?: string;` — then in the env object (line ~293, next to `ARGO_OVERLAYS_PATH`):
+
+```typescript
+          ARGO_BLOCKS_DIR: path.resolve(options.blocksDir ?? 'blocks'),
+```
+
+**3e.** Add `blocksDir: config.blocksDir,` to the `record()` options objects at `src/pipeline.ts:172` block, `src/pipeline.ts:527` block, and `src/cli.ts:93` block (all three list `demosDir: config.demosDir,` first — add the new line right after it).
+
+- [ ] **Step 4: Run tests + build**
+
+Run: `npx vitest run tests/hf/hf-component-cue.test.ts && npx vitest run tests/overlays/ && npm run build`
+Expected: new tests PASS; existing overlay tests still PASS; build exit 0.
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add src/overlays/types.ts src/overlays/index.ts src/overlays/templates.ts src/record.ts src/pipeline.ts src/cli.ts tests/hf/hf-component-cue.test.ts
+git -c commit.gpgsign=false commit -m "feat(overlays): hf-component cue + ARGO_BLOCKS_DIR env bridge"
+```
+
+---
+
+### Task 7: `argo validate` — hf-component names + accent hex
+
+**Files:**
+- Modify: `src/validate.ts` (validTypes at :59; overlay checks at :73-100; `ValidateOptions` at the top)
+- Modify: `src/cli.ts` (validate command action — pass the two new options; Read the existing call to see how options are passed)
+- Test: extend the existing validate test file (find it: `ls tests/ | grep -i validate`; if none exists, create `tests/hf/validate-hf.test.ts` using `validateDemo` directly with a temp demos dir — mirror how other tests build fixture manifests, e.g. the preview tests create temp `.scenes.json` files)
+
+**Interfaces:**
+- Consumes: `HfComponentCue` shape (Task 6), `config.blocksDir` (Task 3), the accent regex contract from Track 1 (`/^#?[0-9a-fA-F]{6}$/`).
+- Produces: `ValidateOptions.blocksDir?: string` (default `'blocks'`) and `ValidateOptions.transitionAccent?: string`; two new error classes in validate output.
+
+- [ ] **Step 1: Write the failing tests**
+
+Add tests (in the located/created test file) covering exactly these behaviors:
+
+```typescript
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import { mkdtempSync, rmSync, mkdirSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { tmpdir } from 'node:os';
+import { validateDemo } from '../../src/validate.js';
+
+describe('validate: hf-component + accent', () => {
+  let tmp: string;
+  beforeEach(() => {
+    tmp = mkdtempSync(join(tmpdir(), 'argo-validate-hf-'));
+    mkdirSync(join(tmp, 'demos'), { recursive: true });
+    mkdirSync(join(tmp, 'blocks', 'vignette'), { recursive: true });
+    writeFileSync(join(tmp, 'blocks', 'vignette', 'vignette.html'), '<div></div>');
+    writeFileSync(
+      join(tmp, 'demos', 'd.demo.ts'),
+      `import { test } from '@argo-video/cli';\ntest('d', async ({ page, narration }) => { narration.mark('intro'); });\n`,
+    );
+  });
+  afterEach(() => { rmSync(tmp, { recursive: true, force: true }); });
+
+  function writeManifest(overlay: unknown) {
+    writeFileSync(
+      join(tmp, 'demos', 'd.scenes.json'),
+      JSON.stringify({ scenes: [{ scene: 'intro', text: 'hi', overlay }] }),
+    );
+  }
+
+  it('accepts an installed hf-component', async () => {
+    writeManifest({ type: 'hf-component', name: 'vignette' });
+    const result = await validateDemo({ demo: 'd', demosDir: join(tmp, 'demos'), blocksDir: join(tmp, 'blocks') });
+    expect(result.errors.filter((e) => e.includes('hf-component'))).toEqual([]);
+  });
+
+  it('errors on a missing hf-component with an install hint', async () => {
+    writeManifest({ type: 'hf-component', name: 'grain-overlay' });
+    const result = await validateDemo({ demo: 'd', demosDir: join(tmp, 'demos'), blocksDir: join(tmp, 'blocks') });
+    expect(result.errors.some((e) => /grain-overlay.*argo add/.test(e))).toBe(true);
+  });
+
+  it('errors on an hf-component cue missing "name"', async () => {
+    writeManifest({ type: 'hf-component' });
+    const result = await validateDemo({ demo: 'd', demosDir: join(tmp, 'demos'), blocksDir: join(tmp, 'blocks') });
+    expect(result.errors.some((e) => /hf-component.*name/i.test(e))).toBe(true);
+  });
+
+  it('errors on a malformed transition accent', async () => {
+    writeManifest(undefined);
+    const result = await validateDemo({
+      demo: 'd', demosDir: join(tmp, 'demos'), blocksDir: join(tmp, 'blocks'), transitionAccent: 'blue',
+    });
+    expect(result.errors.some((e) => /accent.*hex/i.test(e))).toBe(true);
+  });
+
+  it('accepts a valid transition accent', async () => {
+    writeManifest(undefined);
+    const result = await validateDemo({
+      demo: 'd', demosDir: join(tmp, 'demos'), blocksDir: join(tmp, 'blocks'), transitionAccent: '#0EA5E9',
+    });
+    expect(result.errors.filter((e) => /accent/i.test(e))).toEqual([]);
+  });
+});
+```
+
+IMPORTANT: before finalizing these tests, Read `src/validate.ts:1-60` and one existing validate test to confirm `ValidateOptions`'s actual field names for demo/demosDir (adjust the option keys in the tests above to the real interface — the shape shown here is the expected addition, not a license to rename existing fields) and to confirm what a minimal passing fixture requires (the demo script scene-name cross-check may need the manifest and script scenes to agree, as in the fixture above).
+
+- [ ] **Step 2: Run to verify failures** — the hf-component manifests currently produce `unknown type "hf-component"` errors and `blocksDir`/`transitionAccent` are not accepted options (TS error at build; vitest runs untyped so expect assertion failures).
+
+- [ ] **Step 3: Implement in `src/validate.ts`**
+
+**3a.** Add to `ValidateOptions`: 
+
+```typescript
+  /** Directory holding installed hyperframes items (config.blocksDir). Default 'blocks'. */
+  blocksDir?: string;
+  /** Mirrors config `export.transition.accent` — validated as 6-digit hex when set. */
+  transitionAccent?: string;
+```
+
+**3b.** At `:59`, add `'hf-component'` to `validTypes`.
+
+**3c.** After the block-specific validation (`if (ov.type === 'block') {...}` region), add:
+
+```typescript
+            // Validate hf-component-specific fields
+            if (ov.type === 'hf-component') {
+              if (!ov.name || typeof ov.name !== 'string') {
+                errors.push(`Scene "${entry.scene}" overlay: hf-component requires a "name" field`);
+              } else {
+                const blocksDir = options.blocksDir ?? 'blocks';
+                const componentFile = path.join(blocksDir, ov.name, `${ov.name}.html`);
+                if (!/^[a-zA-Z0-9][a-zA-Z0-9_-]*$/.test(ov.name)) {
+                  errors.push(`Scene "${entry.scene}" overlay: invalid hf-component name "${ov.name}"`);
+                } else if (!existsSync(componentFile)) {
+                  errors.push(
+                    `Scene "${entry.scene}" overlay: hf-component "${ov.name}" is not installed ` +
+                      `(missing ${componentFile}). Run: argo add ${ov.name}`,
+                  );
+                }
+              }
+            }
+```
+
+(Use whatever fs/path import style validate.ts already has — Read its imports and extend them rather than adding duplicate imports.)
+
+**3d.** Add the accent check once, near the top of the validation flow (not per-scene):
+
+```typescript
+    if (options.transitionAccent !== undefined && !/^#?[0-9a-fA-F]{6}$/.test(options.transitionAccent.trim())) {
+      errors.push(
+        `export.transition.accent: "${options.transitionAccent}" is not a 6-digit hex color (e.g. #0ea5e9)`,
+      );
+    }
+```
+
+**3e.** In `src/cli.ts`'s validate command action, pass the new options from config: `blocksDir: config.blocksDir` and `transitionAccent: config.export.transition?.type === 'shader' ? config.export.transition.accent : undefined` (match how the action already reads `config` — Read it first; if the transition config type needs narrowing, mirror how other CLI code narrows `config.export.transition`).
+
+- [ ] **Step 4: Run tests + build**
+
+Run: `npx vitest run tests/hf/ && npm test && npm run build`
+Expected: all green (the full suite guards the validate changes against regressions in existing validate tests).
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add src/validate.ts src/cli.ts tests/
+git -c commit.gpgsign=false commit -m "feat(validate): hf-component install checks + transition accent hex validation"
+```
+
+---
+
+### Task 8: Docs sync + end-to-end network smoke
+
+**Files:**
+- Modify: `README.md` (new "Catalog: argo add" section; config reference gains `blocksDir` + `registry.url`; overlay cue types list gains `hf-component`; script API list gains `applyComponent`/`removeComponent`)
+- Modify: `CLAUDE.md` (new `### HyperFrames Catalog (src/hf/)` subsection under Architecture; env var list gains `ARGO_BLOCKS_DIR`; CLI section gains `argo add`)
+- Modify: `skills/argo-guide/` (SKILL.md + references — grep for where overlay types and CLI commands are enumerated)
+
+**Interfaces:** consumes everything; produces nothing downstream — closes Track 2.
+
+- [ ] **Step 1: Update README** — document, minimally: `argo add <name>` / `argo add --list`; the install location (`blocks/<name>/`, git-tracked); the `hf-component` cue with a manifest example:
+
+```json
+{ "scene": "intro", "text": "…", "overlay": { "type": "hf-component", "name": "vignette", "params": { "--vignette-size": "40%" } } }
+```
+
+and the script API:
+
+```ts
+import { applyComponent, removeComponent } from '@argo-video/cli';
+await applyComponent(page, 'grain-overlay');   // persists until removed
+await removeComponent(page, 'grain-overlay');
+```
+
+Note the two caveats: caption-* components install but need word-timing support (future), and injected component scripts can be blocked by strict CSP (warning, not failure).
+
+- [ ] **Step 2: Update CLAUDE.md and the argo-guide skill** per the Files list. CLAUDE.md's "Env Vars Bridging Config to Playwright" section gains: `ARGO_BLOCKS_DIR — blocks directory for installed hyperframes items (loaded by applyComponent/hf-component cues)`.
+
+- [ ] **Step 3: Full verification + network smoke**
+
+Run: `npm run build && npm test`
+Expected: all green.
+
+Then the one allowed network smoke (requires internet; if offline, report DONE_WITH_CONCERNS naming this step):
+
+```bash
+cd "$(mktemp -d)" && node /Users/shreyas/work/rnd/argo/bin/argo.js add --list | head -5 && node /Users/shreyas/work/rnd/argo/bin/argo.js add vignette && test -f blocks/vignette/vignette.html && echo SMOKE-OK
+```
+
+Expected: item list prints; `SMOKE-OK`.
+
+- [ ] **Step 4: Commit**
+
+```bash
+git add README.md CLAUDE.md skills/
+git -c commit.gpgsign=false commit -m "docs: argo add command, hf-component cue, blocksDir config"
+```
+
+---
+
+## Self-Review Notes
+
+- **Spec coverage:** command + --list/--json (T3), registry URL config (T3), native-format storage + traversal guards (T2), component adapter with injection fence + instance cleanup (T5), cue + `applyComponent` script API (T5/T6), `ARGO_BLOCKS_DIR` at record.ts with all THREE call sites (T6 — the spec said "both pipeline call sites"; recon found `argo record` in cli.ts:93 is a third `record()` caller, included), validate checks (T7), caption deferral (constraint + README caveat), trust model + param validation (T4/T5), Track-1-deferred accent validation folded into T7.
+- **Placeholder scan:** steps that depend on unread code (defineConfig body, withOverlay param name, validate option names, effects.ts catch block) explicitly instruct Read-then-mirror with the target named — bounded lookups, not open TBDs.
+- **Type consistency:** `FetchLike`/`RegistryIndexItem`/`InstallResult` names match across T1→T3; `resolveBlocksDir`/`applyComponent`/`removeComponent` match T5→T6; `blocksDir`/`transitionAccent` option names match T7's tests and impl; evaluate-call count in T6's fake-page test (fence + inject + remove = 3 evaluates) matches T5's implementation.
diff --git a/docs/superpowers/plans/2026-07-07-hf-block-prerender.md b/docs/superpowers/plans/2026-07-07-hf-block-prerender.md
new file mode 100644
index 0000000..dd6483f
--- /dev/null
+++ b/docs/superpowers/plans/2026-07-07-hf-block-prerender.md
@@ -0,0 +1,831 @@
+# HyperFrames Block Pre-Render Adapter — Implementation Plan (Track 3 of 4)
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** Installed hyperframes **blocks** (full HTML compositions with paused GSAP timelines) become composited overlays in exported videos: a new `hf-block` overlay cue triggers an export-time pre-pass that renders the block's timeline frame-by-frame in headless Chromium (alpha PNG sequence, content-addressed cache) and composites it via ffmpeg `overlay` with `enable='between(t,start,end)'` — cutaway semantics, no timeline surgery.
+
+**Architecture:** Generalizes the `shader-render.ts` pattern. New modules: `src/hf/block-render.ts` (frame renderer + cue resolver + orchestrator) and `src/hf/block-filter.ts` (ffmpeg filter builder mirroring `buildOverlayPngFilters` in `src/overlays/render-to-png.ts`, extended for image sequences with a `setpts` time shift). `ExportOptions` gains `hfBlocks?: RenderedHfBlock[]`, composited in the same layer slot as `overlayPngs` (after camera moves, before frame effect/watermark). Wired at all four export paths.
+
+**Tech Stack:** TypeScript (strict, ESM), vitest, Playwright Chromium (swiftshader flags, shared browser across blocks), ffmpeg image2 sequence inputs.
+
+**Spec:** `docs/superpowers/specs/2026-07-06-hyperframes-integration-design.md` (Track 3 section)
+
+## Global Constraints
+
+- Branch: `feat/hyperframes-integration`. Commit with `git -c commit.gpgsign=false commit ...`.
+- Cache: `sha256(blockHtml, JSON.stringify(params ?? {}), durationMs, fps, width, height)` (16-hex prefix) → `<cacheDir>/<hash>/frame_%04d.png`; a complete cached dir skips the browser entirely (same contract as the shader cache).
+- Compositing is **cutaway semantics**: never changes video duration, never shifts placements/chapters/subtitles. `eof_action=pass` + `enable=between` guarantee this.
+- Layer order in export.ts: hf-blocks composite **after** camera moves/motion blur, **immediately after** the existing `overlayPngs` step, **before** frame effect and watermark.
+- The renderer must not require GSAP or network in unit/integration tests — it interacts with `window.__timelines[<id>]` only through the interface `{ duration(): number; pause(): void; seek(t: number): void }`, so test fixtures register a plain object. (Real blocks load GSAP + Google Fonts from CDNs — network needed at export time for real blocks; documented caveat.)
+- Timeline readiness: wait for `document.fonts.ready` AND poll `window.__timelines` until non-empty (10s timeout → error naming the block and the expected convention).
+- Duration mapping: linear retime `seek(tVideo × nativeDuration / requestedDuration)`; with `holdLastFrame: true`, `seek(min(tVideo, nativeDuration))` (no retime).
+- Known v1 limitation (document, do not solve): `hf-block` windows are computed on the pre-speed-ramp output timeline — combining `hf-block` cues with `export.speedRamp` produces misaligned windows. Same class of limitation as the original speedRamp+transitions conflict.
+- All FOUR export paths wired: pipeline primary (`src/pipeline.ts:368` exportOptions / `:452` exportVideo), pipeline variants (`:663`), CLI export (`src/cli.ts:266`), preview export (`src/preview.ts:1095`). Line numbers may drift a few lines — anchor on the code shown in each task.
+- Window resolution uses the SAME placements array each site passes to `exportVideo` (post-trim, freeze-adjusted) — pipeline: `finalPlacements`; cli: `placements`; preview: `freezeAdjustedPlacements`.
+- Run single test file: `npx vitest run tests/path/to/test.ts`. Full suite: `npm test`.
+
+---
+
+### Task 1: Block frame renderer (`renderBlockFrames` + hash)
+
+**Files:**
+- Create: `src/hf/block-render.ts`
+- Test: `tests/hf/block-render.test.ts`
+
+**Interfaces:**
+- Consumes: playwright `chromium` (same launch flags as `src/transitions/shader-render.ts:86-93`).
+- Produces (Tasks 2/5 depend on):
+  - `computeBlockHash(blockHtml: string, params: Record<string, string> | undefined, durationMs: number, fps: number, width: number, height: number): string` (16-hex)
+  - `interface RenderBlockFramesOptions { blockHtmlPath: string; outputDir: string; durationMs: number; fps: number; width: number; height: number; params?: Record<string, string>; holdLastFrame?: boolean; browser?: Browser }`
+  - `renderBlockFrames(opts: RenderBlockFramesOptions): Promise<number>` — returns frame count `N = max(1, round(durationMs × fps / 1000))`, writes `outputDir/frame_0000.png …`.
+
+- [ ] **Step 1: Write the failing test**
+
+Create `tests/hf/block-render.test.ts`:
+
+```typescript
+import { describe, it, expect, beforeAll, afterAll, beforeEach, afterEach } from 'vitest';
+import { mkdtempSync, rmSync, writeFileSync, readdirSync, existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { tmpdir } from 'node:os';
+import { chromium, type Browser } from 'playwright';
+import { computeBlockHash, renderBlockFrames } from '../../src/hf/block-render.js';
+
+// Fixture block: no GSAP, no network. Registers a fake timeline implementing
+// the { duration, pause, seek } interface the renderer relies on, and mirrors
+// seek progress into the DOM so frames are visually distinguishable.
+const FIXTURE_BLOCK = `<!doctype html>
+<html><head><style>
+  html, body { margin: 0; width: 320px; height: 180px; background: transparent; }
+  #bar { position: absolute; top: 80px; left: 0; height: 20px; background: rgb(255, 0, 0); width: 0; }
+</style></head>
+<body>
+  <div id="root" data-composition-id="fixture"><div id="bar"></div></div>
+  <script>
+    window.__timelines = {
+      fixture: {
+        _t: 0,
+        duration() { return 2; },
+        pause() {},
+        seek(t) { this._t = t; document.getElementById('bar').style.width = (t / 2) * 320 + 'px'; },
+      },
+    };
+  </script>
+</body></html>`;
+
+describe('computeBlockHash', () => {
+  it('is stable and sensitive to every component', () => {
+    const base = computeBlockHash('<html>', { '--x': '1' }, 1000, 30, 320, 180);
+    expect(base).toMatch(/^[0-9a-f]{16}$/);
+    expect(computeBlockHash('<html>', { '--x': '1' }, 1000, 30, 320, 180)).toBe(base);
+    expect(computeBlockHash('<html>!', { '--x': '1' }, 1000, 30, 320, 180)).not.toBe(base);
+    expect(computeBlockHash('<html>', { '--x': '2' }, 1000, 30, 320, 180)).not.toBe(base);
+    expect(computeBlockHash('<html>', { '--x': '1' }, 1500, 30, 320, 180)).not.toBe(base);
+    expect(computeBlockHash('<html>', undefined, 1000, 30, 320, 180)).toBe(
+      computeBlockHash('<html>', {}, 1000, 30, 320, 180),
+    );
+  });
+});
+
+describe('renderBlockFrames', () => {
+  let browser: Browser;
+  let tmp: string;
+
+  beforeAll(async () => { browser = await chromium.launch(); }, 60_000);
+  afterAll(async () => { await browser.close(); });
+  beforeEach(() => { tmp = mkdtempSync(join(tmpdir(), 'argo-blockrender-')); });
+  afterEach(() => { rmSync(tmp, { recursive: true, force: true }); });
+
+  it('renders N frames by seeking the registered timeline', async () => {
+    const blockPath = join(tmp, 'fixture.html');
+    writeFileSync(blockPath, FIXTURE_BLOCK);
+    const outDir = join(tmp, 'frames');
+    const n = await renderBlockFrames({
+      blockHtmlPath: blockPath, outputDir: outDir,
+      durationMs: 1000, fps: 10, width: 320, height: 180, browser,
+    });
+    expect(n).toBe(10);
+    const frames = readdirSync(outDir).filter((f) => f.endsWith('.png')).sort();
+    expect(frames).toHaveLength(10);
+    expect(frames[0]).toBe('frame_0000.png');
+    expect(frames[9]).toBe('frame_0009.png');
+    // first and last frame must differ (bar width animates with seek)
+    expect(readFileSync(join(outDir, 'frame_0000.png')).equals(readFileSync(join(outDir, 'frame_0009.png')))).toBe(false);
+  }, 60_000);
+
+  it('applies params as CSS custom properties on the document root', async () => {
+    const blockPath = join(tmp, 'fx.html');
+    writeFileSync(blockPath, FIXTURE_BLOCK.replace('rgb(255, 0, 0)', 'var(--bar-color, rgb(255, 0, 0))'));
+    const a = join(tmp, 'a');
+    const b = join(tmp, 'b');
+    await renderBlockFrames({ blockHtmlPath: blockPath, outputDir: a, durationMs: 200, fps: 5, width: 320, height: 180, browser });
+    await renderBlockFrames({ blockHtmlPath: blockPath, outputDir: b, durationMs: 200, fps: 5, width: 320, height: 180, params: { '--bar-color': 'rgb(0, 0, 255)' }, browser });
+    expect(readFileSync(join(a, 'frame_0000.png')).equals(readFileSync(join(b, 'frame_0000.png')))).toBe(false);
+  }, 60_000);
+
+  it('fails with an actionable error when no timeline is registered', async () => {
+    const blockPath = join(tmp, 'no-tl.html');
+    writeFileSync(blockPath, '<!doctype html><html><body><div>static</div></body></html>');
+    await expect(
+      renderBlockFrames({ blockHtmlPath: blockPath, outputDir: join(tmp, 'out'), durationMs: 200, fps: 5, width: 320, height: 180, browser }),
+    ).rejects.toThrow(/__timelines/);
+  }, 60_000);
+});
+```
+
+- [ ] **Step 2: Run test to verify it fails**
+
+Run: `npx vitest run tests/hf/block-render.test.ts`
+Expected: FAIL — module not found.
+
+- [ ] **Step 3: Write the implementation**
+
+Create `src/hf/block-render.ts`:
+
+```typescript
+import { createHash } from 'node:crypto';
+import { mkdirSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { chromium, type Browser } from 'playwright';
+
+/**
+ * Pre-render a hyperframes block's paused GSAP timeline as a PNG sequence.
+ * Generalizes the shader-render pattern: headless Chromium, per-frame seek,
+ * content-addressed cache managed by the caller (renderHfBlocks in Task 5).
+ *
+ * The renderer only relies on the hyperframes convention
+ * `window.__timelines[<id>] = { duration(), pause(), seek(t) }` — it does
+ * not need GSAP itself, so test fixtures can register plain objects.
+ */
+
+export function computeBlockHash(
+  blockHtml: string,
+  params: Record<string, string> | undefined,
+  durationMs: number,
+  fps: number,
+  width: number,
+  height: number,
+): string {
+  const parts = [blockHtml, JSON.stringify(params ?? {}), durationMs, fps, width, height].join('|');
+  return createHash('sha256').update(parts).digest('hex').slice(0, 16);
+}
+
+export interface RenderBlockFramesOptions {
+  blockHtmlPath: string;
+  outputDir: string;
+  /** Window duration in the video (drives frame count and retiming). */
+  durationMs: number;
+  fps: number;
+  /** Block canvas dimensions (native block size; compositing scales later). */
+  width: number;
+  height: number;
+  /** CSS custom property overrides applied on document.documentElement. */
+  params?: Record<string, string>;
+  /** Pin the final timeline frame instead of linearly retiming. */
+  holdLastFrame?: boolean;
+  /** Reusable browser — pass one across multiple blocks for performance. */
+  browser?: Browser;
+}
+
+export async function renderBlockFrames(opts: RenderBlockFramesOptions): Promise<number> {
+  mkdirSync(opts.outputDir, { recursive: true });
+  const N = Math.max(1, Math.round((opts.durationMs * opts.fps) / 1000));
+
+  const ownsBrowser = !opts.browser;
+  const browser = opts.browser ?? await chromium.launch({
+    args: [
+      '--use-gl=angle',
+      '--use-angle=swiftshader',
+      '--enable-webgl',
+      '--ignore-gpu-blacklist',
+    ],
+  });
+  try {
+    const page = await browser.newPage({ viewport: { width: opts.width, height: opts.height } });
+    try {
+      await page.goto(pathToFileURL(resolve(opts.blockHtmlPath)).href, { waitUntil: 'load' });
+
+      if (opts.params) {
+        await page.evaluate((params) => {
+          for (const [k, v] of Object.entries(params)) {
+            document.documentElement.style.setProperty(k, v);
+          }
+        }, opts.params);
+      }
+
+      await page.evaluate(() => document.fonts.ready.then(() => undefined));
+
+      // Wait for the hyperframes timeline registration convention.
+      try {
+        await page.waitForFunction(
+          () => {
+            const tls = (window as unknown as { __timelines?: Record<string, unknown> }).__timelines;
+            return !!tls && Object.keys(tls).length > 0;
+          },
+          undefined,
+          { timeout: 10_000 },
+        );
+      } catch {
+        throw new Error(
+          `Block "${opts.blockHtmlPath}" never registered a timeline on window.__timelines ` +
+            `(hyperframes blocks register a paused GSAP timeline keyed by composition id).`,
+        );
+      }
+
+      const nativeDurationSec = await page.evaluate(() => {
+        const tls = (window as unknown as {
+          __timelines: Record<string, { duration(): number; pause(): void }>;
+        }).__timelines;
+        const tl = tls[Object.keys(tls)[0]];
+        tl.pause();
+        return tl.duration();
+      });
+
+      const requestedSec = opts.durationMs / 1000;
+      for (let i = 0; i < N; i++) {
+        const tVideo = N === 1 ? 0 : (i / (N - 1)) * requestedSec;
+        const tBlock = opts.holdLastFrame
+          ? Math.min(tVideo, nativeDurationSec)
+          : (tVideo * nativeDurationSec) / requestedSec;
+        await page.evaluate((t) => {
+          const tls = (window as unknown as {
+            __timelines: Record<string, { seek(t: number): void }>;
+          }).__timelines;
+          tls[Object.keys(tls)[0]].seek(t);
+        }, tBlock);
+        await page.screenshot({
+          path: join(opts.outputDir, `frame_${String(i).padStart(4, '0')}.png`),
+          omitBackground: true,
+        });
+      }
+    } finally {
+      await page.close();
+    }
+  } finally {
+    if (ownsBrowser) await browser.close();
+  }
+
+  return N;
+}
+```
+
+- [ ] **Step 4: Run test to verify it passes**
+
+Run: `npx vitest run tests/hf/block-render.test.ts`
+Expected: PASS (4 tests; launches chromium, ~10-25s)
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add src/hf/block-render.ts tests/hf/block-render.test.ts
+git -c commit.gpgsign=false commit -m "feat(hf): block frame renderer seeking window.__timelines"
+```
+
+---
+
+### Task 2: ffmpeg composite filter builder
+
+**Files:**
+- Create: `src/hf/block-filter.ts`
+- Test: `tests/hf/block-filter.test.ts`
+
+**Interfaces:**
+- Consumes: nothing (pure string builder). Mirrors `buildOverlayPngFilters` in `src/overlays/render-to-png.ts:…` — Read that function first and keep the same return contract `{ inputArgs, filterParts, videoSource, nextInput }`.
+- Produces (Tasks 3/5 depend on):
+  - `interface RenderedHfBlock { name: string; pngDir: string; frameCount: number; fps: number; startMs: number; endMs: number; width: number; height: number; fit: 'cover' | { x: number; y: number; scale: number } }`
+  - `buildHfBlockFilters(blocks: RenderedHfBlock[], baseInputCount: number, videoSourceLabel: string, videoW: number, videoH: number): { inputArgs: string[]; filterParts: string[]; videoSource: string; nextInput: number }`
+
+- [ ] **Step 1: Write the failing test**
+
+Create `tests/hf/block-filter.test.ts`:
+
+```typescript
+import { describe, it, expect } from 'vitest';
+import { buildHfBlockFilters, type RenderedHfBlock } from '../../src/hf/block-filter.js';
+
+const BLOCK: RenderedHfBlock = {
+  name: 'logo-outro', pngDir: '/tmp/cache/abc', frameCount: 60, fps: 30,
+  startMs: 12_000, endMs: 14_000, width: 1920, height: 1080, fit: 'cover',
+};
+
+describe('buildHfBlockFilters', () => {
+  it('returns passthrough for an empty list', () => {
+    const r = buildHfBlockFilters([], 2, 'v0', 1920, 1080);
+    expect(r).toEqual({ inputArgs: [], filterParts: [], videoSource: 'v0', nextInput: 2 });
+  });
+
+  it('adds a framerate-pinned image2 sequence input per block', () => {
+    const r = buildHfBlockFilters([BLOCK], 2, 'v0', 1920, 1080);
+    expect(r.inputArgs).toEqual([
+      '-framerate', '30', '-start_number', '0', '-i', '/tmp/cache/abc/frame_%04d.png',
+    ]);
+    expect(r.nextInput).toBe(3);
+  });
+
+  it('cover fit: scales to video size, shifts pts to the window start, overlays with enable window', () => {
+    const r = buildHfBlockFilters([BLOCK], 2, 'v0', 1920, 1080);
+    expect(r.filterParts).toHaveLength(2);
+    expect(r.filterParts[0]).toBe('[2:v]format=rgba,scale=1920:1080,setpts=PTS+12.000/TB[hfblk0]');
+    expect(r.filterParts[1]).toBe(
+      "[v0][hfblk0]overlay=0:0:enable='between(t\\,12.000\\,14.000)':format=auto:eof_action=pass[hfb0]",
+    );
+    expect(r.videoSource).toBe('hfb0');
+  });
+
+  it('custom fit: scales by factor and positions at x/y', () => {
+    const r = buildHfBlockFilters(
+      [{ ...BLOCK, fit: { x: 100, y: 50, scale: 0.5 } }], 2, 'v0', 1920, 1080,
+    );
+    expect(r.filterParts[0]).toBe('[2:v]format=rgba,scale=960:540,setpts=PTS+12.000/TB[hfblk0]');
+    expect(r.filterParts[1]).toContain('overlay=100:50:enable=');
+  });
+
+  it('chains multiple blocks through intermediate labels', () => {
+    const second: RenderedHfBlock = { ...BLOCK, name: 'x-post', pngDir: '/tmp/cache/def', startMs: 2000, endMs: 3000 };
+    const r = buildHfBlockFilters([BLOCK, second], 2, 'v0', 1920, 1080);
+    expect(r.nextInput).toBe(4);
+    expect(r.filterParts[1]).toContain('[v0][hfblk0]');
+    expect(r.filterParts[3]).toContain('[hfb0][hfblk1]');
+    expect(r.videoSource).toBe('hfb1');
+  });
+});
+```
+
+- [ ] **Step 2: Run test to verify it fails**
+
+Run: `npx vitest run tests/hf/block-filter.test.ts` — Expected: FAIL, module not found.
+
+- [ ] **Step 3: Write the implementation**
+
+Create `src/hf/block-filter.ts`:
+
+```typescript
+import { join } from 'node:path';
+
+/**
+ * Build ffmpeg inputs + filter_complex parts that composite pre-rendered
+ * hyperframes block PNG sequences onto the video. Mirrors
+ * buildOverlayPngFilters (src/overlays/render-to-png.ts) but for image2
+ * sequences: the sequence starts at t=0, so setpts shifts it to the cue's
+ * window before the enable-gated overlay. eof_action=pass keeps cutaway
+ * semantics — output duration never changes.
+ */
+
+export interface RenderedHfBlock {
+  name: string;
+  pngDir: string;
+  frameCount: number;
+  fps: number;
+  startMs: number;
+  endMs: number;
+  /** Native block canvas size (the PNG dimensions). */
+  width: number;
+  height: number;
+  fit: 'cover' | { x: number; y: number; scale: number };
+}
+
+export function buildHfBlockFilters(
+  blocks: RenderedHfBlock[],
+  baseInputCount: number,
+  videoSourceLabel: string,
+  videoW: number,
+  videoH: number,
+): { inputArgs: string[]; filterParts: string[]; videoSource: string; nextInput: number } {
+  if (blocks.length === 0) {
+    return { inputArgs: [], filterParts: [], videoSource: videoSourceLabel, nextInput: baseInputCount };
+  }
+
+  const inputArgs: string[] = [];
+  const filterParts: string[] = [];
+  let currentVideo = videoSourceLabel;
+  let nextInput = baseInputCount;
+
+  for (let i = 0; i < blocks.length; i++) {
+    const b = blocks[i];
+    const inputIdx = nextInput++;
+    inputArgs.push('-framerate', String(b.fps), '-start_number', '0', '-i', join(b.pngDir, 'frame_%04d.png'));
+
+    const startSec = (b.startMs / 1000).toFixed(3);
+    const endSec = (b.endMs / 1000).toFixed(3);
+
+    let scaleExpr: string;
+    let x: number;
+    let y: number;
+    if (b.fit === 'cover') {
+      scaleExpr = `scale=${videoW}:${videoH}`;
+      x = 0;
+      y = 0;
+    } else {
+      scaleExpr = `scale=${Math.round(b.width * b.fit.scale)}:${Math.round(b.height * b.fit.scale)}`;
+      x = b.fit.x;
+      y = b.fit.y;
+    }
+
+    const prepLabel = `hfblk${i}`;
+    const outLabel = `hfb${i}`;
+    filterParts.push(`[${inputIdx}:v]format=rgba,${scaleExpr},setpts=PTS+${startSec}/TB[${prepLabel}]`);
+    filterParts.push(
+      `[${currentVideo}][${prepLabel}]overlay=${x}:${y}:enable='between(t\\,${startSec}\\,${endSec})':format=auto:eof_action=pass[${outLabel}]`,
+    );
+    currentVideo = outLabel;
+  }
+
+  return { inputArgs, filterParts, videoSource: currentVideo, nextInput };
+}
+```
+
+- [ ] **Step 4: Run test to verify it passes**
+
+Run: `npx vitest run tests/hf/block-filter.test.ts` — Expected: PASS (5 tests).
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add src/hf/block-filter.ts tests/hf/block-filter.test.ts
+git -c commit.gpgsign=false commit -m "feat(hf): ffmpeg composite filter builder for block PNG sequences"
+```
+
+---
+
+### Task 3: Export integration (`ExportOptions.hfBlocks`)
+
+**Files:**
+- Modify: `src/export.ts` (options interface at :17; composite step right after the `overlayPngs` block at ~:466; every other place `overlayPngs` is referenced)
+- Test: `tests/hf/export-hf-blocks.test.ts`
+
+**Interfaces:**
+- Consumes: `RenderedHfBlock`, `buildHfBlockFilters` (Task 2).
+- Produces: `ExportOptions.hfBlocks?: RenderedHfBlock[]` — Task 5's four wiring sites pass it.
+
+- [ ] **Step 1: Map every `overlayPngs` touchpoint**
+
+Run: `grep -n "overlayPngs" src/export.ts` — for EACH hit, decide whether `hfBlocks` needs the same treatment and note it in your report:
+- the `ExportOptions` field (~:68) → add `hfBlocks?: RenderedHfBlock[]` with JSDoc `/** Pre-rendered hyperframes block PNG sequences composited as cutaway overlays. */`
+- the filter-complex gate (~:419, an `||` chain deciding whether a `filter_complex` is required) → add `(options.hfBlocks && options.hfBlocks.length > 0) ||`
+- the composite step (~:466-473) → add the equivalent block IMMEDIATELY AFTER it:
+
+```typescript
+  const hfBlocks = options.hfBlocks;
+  if (hfBlocks && hfBlocks.length > 0) {
+    const hfResult = buildHfBlockFilters(hfBlocks, nextInput, videoSource, outputWidth ?? 1920, outputHeight ?? 1080);
+    args.push(...hfResult.inputArgs);
+    filterParts.push(...hfResult.filterParts);
+    videoSource = hfResult.videoSource;
+    nextInput = hfResult.nextInput;
+  }
+```
+
+(Match the surrounding code's actual local variable names — `nextInput`, `videoSource`, `filterParts`, `args`, `outputWidth`/`outputHeight` are the names visible at the `overlayPngs` step; verify from context when editing.)
+- the `hasOverlayPngs` reference (~:763) — Read that region: if it gates `-shortest` or map decisions for overlay PNG inputs, mirror the same gate for hf-block sequence inputs (`hasHfBlocks`). Image2 sequences are finite so they cannot hang the encode, but `-shortest` semantics must not truncate: mirror exactly what overlayPngs does and record your finding in the report.
+
+Add the import: `import { buildHfBlockFilters, type RenderedHfBlock } from './hf/block-filter.js';`
+
+- [ ] **Step 2: Write the failing test**
+
+Create `tests/hf/export-hf-blocks.test.ts` — a compile-time + wiring test (running full ffmpeg here would be slow; Task 5 has the e2e):
+
+```typescript
+import { describe, it, expect } from 'vitest';
+import type { ExportOptions } from '../../src/export.js';
+import type { RenderedHfBlock } from '../../src/hf/block-filter.js';
+
+describe('ExportOptions.hfBlocks', () => {
+  it('accepts pre-rendered block sequences at compile time', () => {
+    const blocks: RenderedHfBlock[] = [{
+      name: 'logo-outro', pngDir: '/tmp/x', frameCount: 60, fps: 30,
+      startMs: 0, endMs: 2000, width: 1920, height: 1080, fit: 'cover',
+    }];
+    const opts: Partial<ExportOptions> = { hfBlocks: blocks };
+    expect(opts.hfBlocks).toHaveLength(1);
+  });
+});
+```
+
+(If `ExportOptions` is not currently exported from `src/export.ts`, export it — check first; the interface is declared with `export` at :17.)
+
+- [ ] **Step 3: Run tests, then build**
+
+Run: `npx vitest run tests/hf/export-hf-blocks.test.ts && npm run build`
+Expected: PASS + build exit 0.
+
+- [ ] **Step 4: Run the export-related test files to catch regressions**
+
+Run: `npx vitest run tests/export-frame.test.ts tests/freeze.test.ts tests/motion-blur.test.ts`
+Expected: PASS (these exercise export filter assembly).
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add src/export.ts tests/hf/export-hf-blocks.test.ts
+git -c commit.gpgsign=false commit -m "feat(export): composite pre-rendered hf-block sequences as cutaway overlays"
+```
+
+---
+
+### Task 4: `hf-block` cue + validate + recording no-op
+
+**Files:**
+- Modify: `src/overlays/types.ts` (add `HfBlockCue`, extend union)
+- Modify: `src/overlays/index.ts` (early branch in `showOverlay` and `withOverlay`)
+- Modify: `src/overlays/templates.ts` (`renderTemplate` throw case)
+- Modify: `src/validate.ts` (validTypes + install check — extend the existing `hf-component` branch to cover both)
+- Test: `tests/hf/hf-block-cue.test.ts`
+
+**Interfaces:**
+- Consumes: patterns from Track 2's `hf-component` cue (same files, adjacent code).
+- Produces: `HfBlockCue { type: 'hf-block'; name: string; params?: Record<string, string>; durationMs?: number; fit?: 'cover' | { x: number; y: number; scale: number }; holdLastFrame?: boolean; placement?: Zone; motion?: MotionPreset; autoBackground?: boolean }` in the `OverlayCue` union (the last three optional/ignored, mirroring `HfComponentCue` — Read that interface and match its optional-field pattern exactly). Task 5's cue resolver consumes this shape.
+
+**Recording semantics:** hf-block is an EXPORT-time effect. During recording, `showOverlay` must do nothing visual but still wait `durationMs` (demo scripts use showOverlay's wait for scene pacing); `withOverlay` just runs its action.
+
+- [ ] **Step 1: Write the failing test**
+
+Create `tests/hf/hf-block-cue.test.ts`:
+
+```typescript
+import { describe, it, expect } from 'vitest';
+import type { OverlayCue } from '../../src/overlays/types.js';
+import { showOverlay } from '../../src/overlays/index.js';
+import { renderTemplate } from '../../src/overlays/templates.js';
+
+describe('HfBlockCue', () => {
+  it('is part of the OverlayCue union at compile time', () => {
+    const cue: OverlayCue = {
+      type: 'hf-block', name: 'logo-outro', fit: 'cover', holdLastFrame: true, durationMs: 2500,
+    };
+    expect(cue.type).toBe('hf-block');
+  });
+
+  it('renderTemplate rejects hf-block cues with a pointer to export-time compositing', () => {
+    expect(() => renderTemplate({ type: 'hf-block', name: 'logo-outro' })).toThrow(/export/i);
+  });
+
+  it('showOverlay is a pacing no-op during recording (waits, no page mutation)', async () => {
+    const calls: string[] = [];
+    const fakePage = {
+      evaluate: async () => { calls.push('evaluate'); },
+      waitForTimeout: async (ms: number) => { calls.push(`wait:${ms}`); },
+    };
+    await showOverlay(fakePage as never, 'outro', { type: 'hf-block', name: 'logo-outro' }, 900);
+    expect(calls).toEqual(['wait:900']);
+  });
+});
+```
+
+- [ ] **Step 2: Run to verify failures** — TS/type failures + dispatch missing.
+
+- [ ] **Step 3: Implement**
+
+**3a.** `src/overlays/types.ts` — add `HfBlockCue` (fields per Interfaces above; copy the optional ignored-field JSDoc style from `HfComponentCue` directly above it) and add `| HfBlockCue` to the union.
+
+**3b.** `src/overlays/index.ts` — in `showOverlay`, immediately after the existing `hf-component` early branch:
+
+```typescript
+  if (cue.type === 'hf-block') {
+    // Export-time cutaway — nothing is injected during recording, but the
+    // wait preserves the demo script's scene pacing.
+    await page.waitForTimeout(durationMs);
+    return;
+  }
+```
+
+In `withOverlay`, after its `hf-component` branch (match the actual action parameter name):
+
+```typescript
+  if (cue.type === 'hf-block') {
+    return await action();
+  }
+```
+
+**3c.** `src/overlays/templates.ts` — add before the switch's closing brace:
+
+```typescript
+    case 'hf-block':
+      throw new Error(
+        'hf-block cues are composited at export time (pre-rendered PNG sequences), not rendered as zone templates.',
+      );
+```
+
+**3d.** `src/validate.ts` — extend the existing hf-component validation: the same name-regex + install-file check applies to `hf-block` (blocks install to the same `blocksDir/<name>/<name>.html` layout). Refactor minimally: change the condition to `if (ov.type === 'hf-component' || ov.type === 'hf-block')` and use `ov.type` in the error strings so messages stay accurate. Add `'hf-block'` to `validTypes`. Additionally validate that `fit`, when present and not `'cover'`, has numeric `x`, `y`, `scale` fields (push an error naming the scene otherwise).
+
+- [ ] **Step 4: Extend validate tests**
+
+Add to `tests/hf/validate-hf.test.ts` (mirror its existing fixture helpers):
+
+```typescript
+  it('accepts an installed hf-block and errors on a missing one', async () => {
+    writeManifest({ type: 'hf-block', name: 'vignette' }); // fixture dir reused — any installed name works
+    const ok = await validateDemo({ demoName: 'd', demosDir: join(tmp, 'demos'), blocksDir: join(tmp, 'blocks') });
+    expect(ok.errors.filter((e) => e.includes('hf-block'))).toEqual([]);
+    writeManifest({ type: 'hf-block', name: 'logo-outro' });
+    const missing = await validateDemo({ demoName: 'd', demosDir: join(tmp, 'demos'), blocksDir: join(tmp, 'blocks') });
+    expect(missing.errors.some((e) => /logo-outro.*argo add/.test(e))).toBe(true);
+  });
+
+  it('errors on a malformed hf-block fit', async () => {
+    writeManifest({ type: 'hf-block', name: 'vignette', fit: { x: 1 } });
+    const result = await validateDemo({ demoName: 'd', demosDir: join(tmp, 'demos'), blocksDir: join(tmp, 'blocks') });
+    expect(result.errors.some((e) => /fit/.test(e))).toBe(true);
+  });
+```
+
+(IMPORTANT: first Read `tests/hf/validate-hf.test.ts` to reuse its actual helper names and option keys — the sketch above assumes `writeManifest`/`demoName`; adjust to what Track 2 actually shipped.)
+
+- [ ] **Step 5: Run tests + build**
+
+Run: `npx vitest run tests/hf/ && npx vitest run tests/overlays/ && npm run build`
+Expected: all PASS, build exit 0.
+
+- [ ] **Step 6: Commit**
+
+```bash
+git add src/overlays/ src/validate.ts tests/hf/
+git -c commit.gpgsign=false commit -m "feat(overlays): hf-block cue (export-time cutaway) + validate checks"
+```
+
+---
+
+### Task 5: Cue resolution + render orchestrator + four-path wiring
+
+**Files:**
+- Modify: `src/hf/block-render.ts` (add `resolveHfBlockCues` + `renderHfBlocks`)
+- Modify: `src/pipeline.ts` (primary: collect cues after the manifest parse at ~:286-297, render pre-pass near the shader pre-pass at ~:434, add `hfBlocks` to `exportOptions` at ~:368-452; variants: same around ~:643-663)
+- Modify: `src/cli.ts` (export command around :248-266)
+- Modify: `src/preview.ts` (export path around :1077-1095)
+- Test: `tests/hf/render-hf-blocks.test.ts`
+
+**Interfaces:**
+- Consumes: `renderBlockFrames`, `computeBlockHash` (Task 1), `RenderedHfBlock` (Task 2), `HfBlockCue` (Task 4), `Placement { scene; startMs; endMs }` from `src/tts/align.ts`.
+- Produces:
+  - `interface HfBlockCueResolved { name: string; params?: Record<string, string>; fit: 'cover' | { x: number; y: number; scale: number }; holdLastFrame: boolean; startMs: number; endMs: number }`
+  - `resolveHfBlockCues(rawManifest: unknown[], placements: Placement[]): HfBlockCueResolved[]` — for each manifest entry whose `overlay?.type === 'hf-block'` and whose `scene` has a placement: `startMs = placement.startMs`, `endMs = min(placement.startMs + (cue.durationMs ?? (placement.endMs - placement.startMs)), placement.endMs)` … except when `cue.durationMs` exceeds the placement window, allow it to extend to the next placement's startMs (or Infinity for the last scene — the enable window is naturally clipped by video length). Defaults: `fit: 'cover'`, `holdLastFrame: false`. Scenes without placements are skipped with a `console.warn`.
+  - `renderHfBlocks(opts: { cues: HfBlockCueResolved[]; blocksDir: string; cacheDir: string; fps: number }): Promise<RenderedHfBlock[]>` — per cue: read `blocksDir/<name>/<name>.html` (throw with `argo add <name>` hint if missing); read native dimensions from `blocksDir/<name>/registry-item.json` (`dimensions.width/height`, fallback 1920×1080); `computeBlockHash` → if `<cacheDir>/<hash>/` already contains the expected `frame_{N-1}.png`, skip rendering (cache hit); else `renderBlockFrames` into it. One shared `chromium.launch(...)` across all cues (launched lazily on first cache miss, closed in `finally`). Returns `RenderedHfBlock[]`.
+
+- [ ] **Step 1: Write the failing test**
+
+Create `tests/hf/render-hf-blocks.test.ts`:
+
+```typescript
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import { mkdtempSync, rmSync, mkdirSync, writeFileSync, readdirSync } from 'node:fs';
+import { join } from 'node:path';
+import { tmpdir } from 'node:os';
+import { resolveHfBlockCues, renderHfBlocks } from '../../src/hf/block-render.js';
+
+const FIXTURE_BLOCK = `<!doctype html><html><head><style>html,body{margin:0;width:320px;height:180px}</style></head>
+<body><div data-composition-id="fx"><div id="p"></div></div>
+<script>window.__timelines={fx:{duration(){return 1},pause(){},seek(t){document.getElementById('p').textContent=String(t)}}};</script>
+</body></html>`;
+
+describe('resolveHfBlockCues', () => {
+  const placements = [
+    { scene: 'intro', startMs: 0, endMs: 4000 },
+    { scene: 'outro', startMs: 10_000, endMs: 13_000 },
+  ];
+
+  it('maps cues onto placement windows with defaults', () => {
+    const manifest = [
+      { scene: 'intro', overlay: { type: 'lower-third', title: 'x' } },
+      { scene: 'outro', overlay: { type: 'hf-block', name: 'logo-outro' } },
+    ];
+    const cues = resolveHfBlockCues(manifest, placements);
+    expect(cues).toEqual([{
+      name: 'logo-outro', params: undefined, fit: 'cover', holdLastFrame: false,
+      startMs: 10_000, endMs: 13_000,
+    }]);
+  });
+
+  it('caps cue durationMs at the placement window but lets it extend for the last scene', () => {
+    const manifest = [
+      { scene: 'intro', overlay: { type: 'hf-block', name: 'a', durationMs: 99_000 } },
+      { scene: 'outro', overlay: { type: 'hf-block', name: 'b', durationMs: 20_000 } },
+    ];
+    const cues = resolveHfBlockCues(manifest, placements);
+    expect(cues[0].endMs).toBe(10_000);   // capped at next placement start
+    expect(cues[1].endMs).toBe(30_000);   // last scene: extends; ffmpeg clips at video end
+  });
+
+  it('skips scenes without placements', () => {
+    const cues = resolveHfBlockCues(
+      [{ scene: 'ghost', overlay: { type: 'hf-block', name: 'a' } }],
+      placements,
+    );
+    expect(cues).toEqual([]);
+  });
+});
+
+describe('renderHfBlocks', () => {
+  let tmp: string;
+  beforeEach(() => {
+    tmp = mkdtempSync(join(tmpdir(), 'argo-renderhf-'));
+    mkdirSync(join(tmp, 'blocks', 'fx'), { recursive: true });
+    writeFileSync(join(tmp, 'blocks', 'fx', 'fx.html'), FIXTURE_BLOCK);
+    writeFileSync(join(tmp, 'blocks', 'fx', 'registry-item.json'), JSON.stringify({
+      name: 'fx', type: 'hyperframes:block', files: [{ path: 'fx.html' }],
+      dimensions: { width: 320, height: 180 },
+    }));
+  });
+  afterEach(() => { rmSync(tmp, { recursive: true, force: true }); });
+
+  it('renders, caches, and returns composite-ready records', async () => {
+    const cues = [{ name: 'fx', params: undefined, fit: 'cover' as const, holdLastFrame: false, startMs: 500, endMs: 1500 }];
+    const r1 = await renderHfBlocks({ cues, blocksDir: join(tmp, 'blocks'), cacheDir: join(tmp, 'cache'), fps: 10 });
+    expect(r1).toHaveLength(1);
+    expect(r1[0]).toMatchObject({ name: 'fx', startMs: 500, endMs: 1500, fps: 10, width: 320, height: 180, fit: 'cover', frameCount: 10 });
+    expect(readdirSync(r1[0].pngDir).filter((f) => f.endsWith('.png'))).toHaveLength(10);
+
+    // second run: cache hit — same pngDir, no re-render (mtime of first frame unchanged)
+    const before = readdirSync(r1[0].pngDir).length;
+    const r2 = await renderHfBlocks({ cues, blocksDir: join(tmp, 'blocks'), cacheDir: join(tmp, 'cache'), fps: 10 });
+    expect(r2[0].pngDir).toBe(r1[0].pngDir);
+    expect(readdirSync(r2[0].pngDir).length).toBe(before);
+  }, 60_000);
+
+  it('throws with an install hint for a missing block', async () => {
+    await expect(renderHfBlocks({
+      cues: [{ name: 'nope', params: undefined, fit: 'cover', holdLastFrame: false, startMs: 0, endMs: 1000 }],
+      blocksDir: join(tmp, 'blocks'), cacheDir: join(tmp, 'cache'), fps: 10,
+    })).rejects.toThrow(/argo add nope/);
+  });
+});
+```
+
+- [ ] **Step 2: Run to verify failure** — functions not exported.
+
+- [ ] **Step 3: Implement `resolveHfBlockCues` + `renderHfBlocks`** in `src/hf/block-render.ts` per the Interfaces contract. For the cache-hit check: `existsSync(join(dir, `frame_${String(N - 1).padStart(4, '0')}.png`))` where N is the expected frame count. Import `Placement` type via `import type { Placement } from '../tts/align.js';`. Manifest entries are `unknown` — narrow with the same defensive property checks validate.ts uses (Read its hf-component branch for the idiom).
+
+- [ ] **Step 4: Run the focused test** — `npx vitest run tests/hf/render-hf-blocks.test.ts` — PASS.
+
+- [ ] **Step 5: Wire the four export paths**
+
+At each site, the pattern is: (a) resolve cues from the manifest + the placements array that site passes to `exportVideo`, (b) if non-empty, run `renderHfBlocks` (cacheDir = sibling of the shader cache: pipeline primary `join(argoDir, 'hf-blocks')`, variants `join('.argo', variantSubdir, 'hf-blocks')`, cli `` `.argo/${demo}/hf-blocks` ``, preview `join(demoDir, 'hf-blocks')`), (c) pass the result as `hfBlocks` in the exportVideo options.
+
+- `src/pipeline.ts` primary: the manifest is already parsed as `rawManifest` (~:290). After `finalPlacements` exists and near the shader pre-pass (~:430), add:
+
+```typescript
+  // hf-block cutaways — pre-render installed hyperframes blocks (cache-hit cheap)
+  const hfBlockCues = resolveHfBlockCues(rawManifest, finalPlacements);
+  if (hfBlockCues.length > 0) {
+    exportOptions.hfBlocks = await renderHfBlocks({
+      cues: hfBlockCues,
+      blocksDir: config.blocksDir,
+      cacheDir: join(argoDir, 'hf-blocks'),
+      fps: config.video?.fps ?? 30,
+    });
+  }
+```
+
+(Place AFTER `exportOptions` is constructed at ~:368 and BEFORE `exportVideo(exportOptions)` at ~:452. If `rawManifest`'s type annotation lacks `overlay`, widen its inline type with `overlay?: { type?: string; [k: string]: unknown }`.)
+
+- `src/pipeline.ts` variants (~:643-663), `src/cli.ts` export (~:248-266), `src/preview.ts` export (~:1077-1095): same pattern with each site's own manifest source, placements array, and cacheDir. Each site already reads the manifest or has a path to it (`config.demosDir`/`demoName`) — Read each site's surrounding code and reuse whatever manifest variable exists, or parse the manifest file the same way pipeline does. In preview, `config.blocksDir` may not be in scope — Read how preview accesses config (it holds an `ec` export-config object and a config module) and thread `blocksDir` the same way `shaderTransition` reached that code.
+
+- [ ] **Step 6: Full verification**
+
+Run: `npm run build && npm test`
+Expected: build exit 0; full suite green.
+
+- [ ] **Step 7: Commit**
+
+```bash
+git add src/hf/block-render.ts src/pipeline.ts src/cli.ts src/preview.ts tests/hf/render-hf-blocks.test.ts
+git -c commit.gpgsign=false commit -m "feat(pipeline): resolve + pre-render hf-block cues across all export paths"
+```
+
+---
+
+### Task 6: Docs sync
+
+**Files:**
+- Modify: `README.md` (hf-block cue docs in the catalog section Task 8 of Track 2 created; cue example with `durationMs`/`fit`/`holdLastFrame`; note the cutaway semantics + network caveat)
+- Modify: `CLAUDE.md` (HyperFrames Catalog section gains the block pre-render paragraph: cache location, `window.__timelines` convention, cutaway semantics, speedRamp limitation; Known Issues gains the speedRamp+hf-block limitation)
+- Modify: `skills/argo-guide/` (overlay-type enumerations gain `hf-block`; grep as in prior doc tasks)
+
+- [ ] **Step 1: Update the three surfaces.** Facts to document (verify each against code): cue shape `{ type: 'hf-block', name, params?, durationMs?, fit?: 'cover' | {x,y,scale}, holdLastFrame? }`; recording-time no-op (pacing wait only); export-time pre-render with cache at `.argo/<demo>/hf-blocks/<hash>/`; compositing after camera moves, before frame/watermark; window = scene placement (durationMs caps/extends per resolver rules); blocks need network at export time (GSAP + fonts CDNs); speedRamp incompatibility.
+
+- [ ] **Step 2: Full verification.** Run: `npm run build && npm test` — green. Then the real-block smoke (network + ~60s; report DONE_WITH_CONCERNS naming this step if offline):
+
+```bash
+cd "$(mktemp -d)" && node /Users/shreyas/work/rnd/argo/bin/argo.js add logo-outro && node -e "
+const { renderHfBlocks } = require('/Users/shreyas/work/rnd/argo/dist/hf/block-render.js');
+renderHfBlocks({ cues: [{ name: 'logo-outro', fit: 'cover', holdLastFrame: false, startMs: 0, endMs: 2000 }], blocksDir: 'blocks', cacheDir: '.argo/smoke/hf-blocks', fps: 30 })
+  .then(r => console.log('SMOKE-OK', r[0].frameCount, 'frames'));
+"
+```
+
+(If `dist` is ESM so `require` fails, use `node --input-type=module -e` with a dynamic `import()` — adapt as needed; the goal is: real registry block installs, pre-renders 60 frames, prints SMOKE-OK.)
+
+- [ ] **Step 3: Commit**
+
+```bash
+git add README.md CLAUDE.md skills/
+git -c commit.gpgsign=false commit -m "docs: hf-block cutaway cue, pre-render cache, speedRamp caveat"
+```
+
+---
+
+## Self-Review Notes
+
+- **Spec coverage:** cue shape incl. `fit` default `'cover'` (T4/T5), chromium pre-pass with fonts + `__timelines` wait + `omitBackground` alpha (T1), linear retime + opt-in `holdLastFrame` (T1), content-addressed cache with browser-skip on hit (T5), `overlay` + `enable=between` compositing after transitions/camera moves before frame/watermark (T2/T3), no timeline surgery (constraint + `eof_action=pass`), all four export paths (T5), actionable missing-timeline error (T1, spec's named risk).
+- **Deviation from spec, justified:** spec's cue sketch omitted `durationMs`; recording-time overlay duration comes from script calls which don't exist at export, so the manifest cue carries it (defaulting to the placement window). Recorded here so the final review sees it as intentional.
+- **Type consistency:** `RenderedHfBlock` fields match between T2 (definition), T3 (export), T5 (producer + test assertions); `HfBlockCueResolved` matches T5's resolver test; `frame_%04d.png` naming matches T1's writer, T2's input args, and T5's cache-hit probe.
+- **Placeholder scan:** Read-then-mirror steps name their exact target (overlayPngs touchpoints, validate idiom, preview config threading, withOverlay param name) — bounded lookups.
diff --git a/docs/superpowers/specs/2026-07-06-hyperframes-integration-design.md b/docs/superpowers/specs/2026-07-06-hyperframes-integration-design.md
new file mode 100644
index 0000000..05a1805
--- /dev/null
+++ b/docs/superpowers/specs/2026-07-06-hyperframes-integration-design.md
@@ -0,0 +1,123 @@
+# Argo × HyperFrames Integration — Design
+
+**Date:** 2026-07-06
+**Status:** Approved
+**Scope:** Four sequential tracks adopting HyperFrames capabilities in Argo, culminating in a showcase demo video.
+
+## Background
+
+[HyperFrames](https://github.com/heygen-com/hyperframes) (Apache-2.0) is HeyGen's "write HTML, render video" framework. Both tools converged on the same primitive — a GSAP timeline scoped under a `data-*` attribute root — which makes their content interoperable: HyperFrames *seeks* a paused timeline deterministically; Argo can *play* the same timeline live, or seek it in a pre-render pass.
+
+Its registry catalog holds **142 items** (109 blocks, 25 components, 8 examples) at
+`https://raw.githubusercontent.com/heygen-com/hyperframes/main/registry/registry.json`.
+
+- **Block** — standalone HTML composition (fixed canvas, typically 1920×1080; fixed duration) with scoped styles and a script that builds a **paused** GSAP timeline registered on `window.__timelines[<id>]`. Typed params exposed as CSS custom properties, declared in `registry-item.json`.
+- **Component** — HTML + scoped CSS snippet (`pointer-events: none`), params via CSS custom properties, optional GSAP timeline-integration hints in comments.
+
+All 12 of Argo's existing blocks have HyperFrames counterparts; the catalog's remaining ~130 items are the payoff.
+
+## Goals
+
+1. Expand Argo's shader transition library from 5 to ~18 (Track 1).
+2. Let users install and use HyperFrames catalog items with one command (Track 2).
+3. Composite full HyperFrames blocks into exported videos, frame-exact (Track 3).
+4. Ship a demo video proving the combo: **"Argo + HyperFrames — better together"** (Track 4).
+
+## Non-Goals
+
+- Caption components (`caption-*`, 18 items) — blocked on the word-level STT roadmap item (v0.38 candidate). Explicitly deferred.
+- An Argo-native registry server. The registry URL is configurable; v1 points at the HyperFrames GitHub raw registry only.
+- Converting HyperFrames items to Argo `BlockDefinition` format. Items are stored native and adapted at use time.
+- Per-boundary shader selection (pre-existing limitation, unchanged).
+
+---
+
+## Track 1 — Shader transitions port
+
+**Source:** `packages/shader-transitions/src/shaders/registry.ts` (fragment shaders as minified JS strings) + `common.ts` (`H` header/varyings, `NQ` noise helpers).
+**Target:** self-contained, formatted, commented `.glsl` files in `src/transitions/shaders/`, matching the existing five.
+
+- Port all non-duplicates (~13): `domain-warp`, `ridged-burn`, `whip-pan`, `sdf-iris`, `gravitational-lens`, `cinematic-zoom`, `chromatic-radial-split`, `glitch`, `swirl-vortex`, `thermal-distortion`, `flash-through-white`, and others. Final list determined by diffing against the existing five (`cross-warp-morph` ≈ `crosswarp`; `light-leak` exists; `ripple-waves` vs `ripple` and `swirl-vortex` vs `swirl` compared visually before inclusion).
+- **Uniform shim at port time** (not runtime): `u_from`/`u_to`/`u_progress`/`v_uv` → `from`/`to`/`progress`/`vUv`. Noise helpers inlined per file so each shader stays self-contained.
+- **Accent uniforms:** shaders that use `u_accent`/`u_accent_dark`/`u_accent_bright` keep them as `accent`/`accentDark`/`accentBright`. New config `export.transition.accent: '#hex'` (default `#0ea5e9`). The render harness parses the hex, derives dark (luminance-scaled) and bright (mixed toward white) variants, and supplies the three uniforms **only when the shader source declares them** — existing shaders are unaffected.
+- Each file carries an attribution header: adapted from heygen-com/hyperframes, Apache-2.0.
+- Build step already copies `.glsl` → `dist/`; shader cache keys already hash shader source, so new shaders cache correctly with no changes.
+- Update: README shader list, `argo validate` shader-name validation, `skills/argo-guide` references.
+
+**Testing:** extend `tests/transitions/shader-render.test.ts` — every registered shader compiles and renders a frame in headless Chromium (the existing test pattern); accent-derivation unit tests.
+
+---
+
+## Track 2 — `argo add` + registry compatibility
+
+### Command
+
+```
+argo add <name>          # install a block or component
+argo add --list          # browse the catalog (name, type, tags, description)
+argo add --list --json   # machine-readable
+```
+
+- Registry URL from `registry.url` in `argo.config.*`; default `https://raw.githubusercontent.com/heygen-com/hyperframes/main/registry`.
+- Item names validated with the same `[a-zA-Z0-9][a-zA-Z0-9_-]*` pattern as demo names before any `path.join()` (security invariant).
+- Flow: fetch `registry.json` → locate item → fetch its `registry-item.json` → download declared files → write verbatim to `blocks/<name>/` (project-local, git-tracked; dir configurable via `blocksDir` in config). The `registry-item.json` is stored alongside for params metadata. Examples (`hyperframes:example`) are not installable — clear error pointing at the HyperFrames CLI.
+
+### Use-time adapter (Tier 1: components, 25 items)
+
+- New overlay cue variant: `{ type: 'hf-component', name: string, params?: Record<string, string> }` in `.scenes.json`, plus a script-side API `applyComponent(page, name, params?)` exported from fixtures (fire-and-forget-safe; error handling mirrors `showConfetti` — swallow disposal errors, warn otherwise).
+- Loader reads `blocks/<name>/<name>.html`, extracts snippet HTML and `<style>` content, injects full-viewport (components are full-frame effects, not zone-positioned) via `page.evaluate` behind the existing injection fence.
+- `params` map onto CSS custom properties on the injected root. Values validated against a conservative CSS-value pattern (no `;`, `}`, `url(`, `expression(`) before interpolation; component HTML itself is trusted-at-install (user-chosen, git-reviewable — same trust posture as config files).
+- Env bridge: `ARGO_BLOCKS_DIR` (config → Playwright subprocess), added at **both** `src/pipeline.ts` call sites (primary + variants), per the established bridging rule.
+- `argo validate` checks that every referenced `hf-component`/`hf-block` name exists in the blocks dir.
+
+**Testing:** registry fetch with a local fixture registry (no network in unit tests); name-validation rejection cases; component extraction + param-substitution units; an integration test injecting `vignette` into a test page.
+
+---
+
+## Track 3 — Block pre-render adapter
+
+New module `src/hf/block-render.ts`, generalizing the `shader-render.ts` pattern.
+
+1. **Cue:** `overlay: { type: 'hf-block', name, params?, fit?: 'cover' | { x, y, scale } }` — rides normal scene/placement timing from the manifest. Default `fit: 'cover'` (full-frame cutaway).
+2. **Render pre-pass (export time):** launch headless Chromium (same `--use-gl=angle --use-angle=swiftshader` flags as shader-render), load the installed block HTML, apply `params` as CSS custom properties, wait for `document.fonts.ready` + `window.__timelines[<id>]`, then for each of `N = durationMs × fps / 1000` frames: `tl.pause(); tl.seek(t)` → PNG screenshot (`omitBackground: true` so transparent block roots produce alpha).
+3. **Duration mapping:** requested duration ≠ block native duration → linear retime (`seek(t × D_block / D_requested)`); opt-in `holdLastFrame: true` to pin the final frame instead when the requested window is longer.
+4. **Cache:** `sha256(blockHtml, params, durationMs, fps, width, height)` → `.argo/<demo>/hf-blocks/<hash>/`. Unchanged blocks re-export with no browser launch (same behavior as shader cache).
+5. **Composite:** ffmpeg `overlay` (PNG sequence input) gated by `enable='between(t,start,end)'`, scaled per `fit`. Position in the filter chain: **after** transitions and camera moves, **before** frame effect and watermark — deliberately *cutaway semantics*: compositing never changes timeline length, so chapters, subtitles, and speed-ramp placements need zero adjustment (unlike freeze).
+6. Wired through **all four export paths**: pipeline, CLI `argo export`, preview Export, viewport variants.
+
+**Testing:** filter-graph construction units (mirroring freeze/camera-move tests); cache-key stability; an e2e rendering `logo-outro` frames and asserting frame count + alpha channel presence.
+
+---
+
+## Track 4 — Showcase demo: "Better Together"
+
+`demos/hyperframes-showcase.demo.ts` + `demos/hyperframes-showcase.scenes.json`. Hybrid recording: purpose-built local story page (served like the existing showcase via `python3 -m http.server`) interleaved with the **live** hyperframes catalog site.
+
+**Narrative spine (user-mandated): Argo + HyperFrames is better together.**
+
+| Scene | On screen | Dogfoods |
+|---|---|---|
+| 1. Hook | Story page: "Product demos, but cinematic." | TTS, overlays |
+| 2. Meet HyperFrames | Live catalog site, camera zooms on block cards | `zoomTo` post-export moves |
+| 3. Meet Argo | Story page: records your real product, AI voiceover, one command | overlays, blocks |
+| 4. Better together | `argo add` results applied live: `vignette` + `grain-overlay` grade the footage on screen | Track 2 |
+| 5. Outro | Pre-rendered `logo-outro` block, full-frame | Track 3 |
+
+Every scene boundary uses a Track-1 shader (`ridged-burn` / `domain-warp`), accent-tinted to match the story page's brand color. Kokoro voiceover (phonetic spellings per engine rules). Live-site scenes need network; if the site is flaky at record time, fall back to full-page screenshots embedded in the story page.
+
+---
+
+## Implementation order & dependencies
+
+```
+Track 1 (shaders)  →  Track 2 (argo add)  →  Track 3 (block pre-render)  →  Track 4 (demo)
+```
+
+Track 1 is standalone. Track 3 renders content that Track 2 installs. Track 4 requires all three. Each track lands as its own PR with tests green; README/skill updates ride the track that changes the surface.
+
+## Risks
+
+- **Upstream registry drift:** item schema or URL changes break `argo add`. Mitigation: registry URL configurable; adapter validates `registry-item.json` shape and fails with a clear error.
+- **Block HTML assumptions:** the adapter depends on the `window.__timelines[<id>]` convention. Mitigation: probe for the timeline after load; if absent, fail the pre-pass with an actionable message naming the block.
+- **Google Fonts CDN in blocks:** recording/pre-render needs network for fonts. Mitigation: `document.fonts.ready` wait + graceful degradation to fallback fonts; document the offline caveat.
+- **GSAP version skew:** blocks pin gsap@3.14 CDN; Argo bundles ~3.15 UMD. Pre-render loads the block's own HTML (its own GSAP tag) so no conflict; live component injection uses Argo's GSAP only.
diff --git a/skills/argo-guide/SKILL.md b/skills/argo-guide/SKILL.md
index f582802..9c36e28 100644
--- a/skills/argo-guide/SKILL.md
+++ b/skills/argo-guide/SKILL.md
@@ -187,7 +187,7 @@ Key fields: `scene` (required, matches `mark()`), `text` (spoken narration — o
 
 ### Overlay Templates
 
-Five types, each with a `type` discriminant. All support `placement`, `motion`, and `autoBackground`.
+Five zone-based template types, each with a `type` discriminant. All support `placement`, `motion`, and `autoBackground`. (Three more cue types exist: `block` — see Overlay blocks below; `hf-component` — full-frame hyperframes components, see HyperFrames components below; and `hf-block` — export-time hyperframes block cutaways, see HyperFrames blocks below.)
 
 - **`lower-third`**: `{ type: 'lower-third', text: '...' }` — text banner
 - **`headline-card`**: `{ type: 'headline-card', title: '...', kicker: '...', body: '...' }` — large card
@@ -245,6 +245,45 @@ Argo ships 12 ready-to-use blocks for narrative inserts. Reference via `overlay:
 
 See `demos/blocks-showcase.demo.ts` for a full example. Block sources live under `src/blocks/<name>/` with a `block.json` schema and a `template.ts` exporting the `BlockDefinition` (+ optional `defaultMotion`). Animated blocks credit HyperFrames (Apache-2.0) for inspiration in their `block.json`.
 
+### HyperFrames components (`argo add`)
+
+Beyond the built-in blocks, install full-frame components (vignettes, grain, glows) from the hyperframes registry:
+
+```bash
+npx argo add --list          # browse registry items (--json for machine-readable)
+npx argo add vignette        # installs into blocksDir (default blocks/, git-tracked)
+```
+
+Reference an installed component with the `hf-component` cue type:
+
+```json
+{ "scene": "intro", "overlay": { "type": "hf-component", "name": "vignette", "params": { "--vignette-size": "40%" } } }
+```
+
+`hf-component` cues are **full-frame** — they bypass zones/placement/motion; duration comes from `showOverlay`. `params` are validated CSS custom properties. For effects that should persist across scenes, use the script API instead:
+
+```typescript
+import { applyComponent, removeComponent } from '@argo-video/cli';
+await applyComponent(page, 'grain-overlay');   // persists until removed
+await removeComponent(page, 'grain-overlay');
+```
+
+Config: `blocksDir` (install location, default `blocks/`) and `registry: { url }` (registry override; also `--registry <url>` per-invocation). `argo validate` errors if a referenced component isn't installed. Caveats: `caption-*` components install but lack word-timing support (future); component `<script>`s may be blocked by strict CSP on the recorded page (warning, not failure); components are trusted-at-install — review `blocks/` before committing.
+
+### HyperFrames blocks (`hf-block`, export-time cutaways)
+
+Installed **blocks** (e.g. `logo-outro`, animated end-cards) can also be used as a scene-anchored cutaway that's pre-rendered and composited at export time, instead of injected live:
+
+```json
+{ "scene": "outro", "overlay": { "type": "hf-block", "name": "logo-outro", "durationMs": 2000, "fit": "cover", "holdLastFrame": false } }
+```
+
+`hf-block` does nothing during recording — no injection, just a pacing wait. At export time, a headless Chromium pre-pass loads the block, seeks its GSAP timeline, and captures an alpha PNG sequence, which is composited over the recording as a cutaway overlay (video duration is unaffected). Frames are cached at `.argo/<demo>/hf-blocks/<hash>/`; an unchanged block/params/duration skips the render on the next export.
+
+The cutaway window defaults to the scene's placement (mark to next mark); `durationMs` can shorten it or extend it into the gap after the scene. `fit` is `'cover'` (default, fills the frame) or `{ x, y, scale }` for a positioned placement. `holdLastFrame: true` freezes the block's last frame instead of stretching its whole animation to fit the window.
+
+Caveats: the pre-render pass needs network access for blocks that load GSAP/fonts from a CDN — offline exports of `hf-block` demos will fail at that step. Not currently compatible with `export.speedRamp` (cutaway windows can misalign with the retimed video) — avoid combining the two.
+
 ### How Overlays Get Triggered
 
 Overlays need **two things** to appear in the video:
@@ -281,6 +320,8 @@ npx argo clip <name> <scene>                # Extract a scene as MP4 clip
 npx argo clip <name> <scene> --format gif   # Extract as GIF (for release notes, docs)
 npx argo import <video-file>                 # Import external video for post-production
 npx argo import <video-file> --demo <name>   # Import with custom demo name
+npx argo add <name>                          # Install hyperframes registry item into blocksDir
+npx argo add --list                          # Browse registry items (--json for machine-readable)
 npx argo init                               # Scaffold example demo + config
 npx argo init --from tests/spec.ts          # Convert existing Playwright test
 ```
@@ -324,7 +365,7 @@ export: {
 
 - **Transitions:** `fade-through-black` | `dissolve` | `wipe-left` | `wipe-right` — applied at scene boundaries during export. `dissolve` is a quicker dip-to-black (not a true crossfade blend). Use `durationMs: 2000` or higher for transitions that are clearly visible with voiceover (500ms is too fast to notice). Content changes (page navigation, slide switches) should happen BEFORE `narration.mark()` so the transition fades between old and new content.
 
-- **Shader transitions:** Pre-rendered WebGL shaders for high-impact transitions. Config: `transition: { type: 'shader', shader: 'crosswarp', durationMs: 800 }`. Shaders: `crosswarp`, `swirl`, `ripple`, `luma-mask`, `light-leak` (gl-transitions.com, MIT). Pre-rendered once per boundary, cached at `.argo/<demo>/shaders/<hash>/` keyed by content hash — second export skips the browser launch. On first export, Chromium renders PNG frames at `N = durationMs × fps` values; `buildShaderSpliceFilter` splices PNG sequence between boundary scenes.
+- **Shader transitions:** Pre-rendered WebGL shaders for high-impact transitions. Config: `transition: { type: 'shader', shader: 'ridged-burn', durationMs: 2000, accent: '#0ea5e9' }`. 16 shaders: `crosswarp`, `swirl`, `ripple`, `luma-mask`, `light-leak` (gl-transitions.com, MIT), plus `domain-warp`, `ridged-burn`, `thermal-distortion`, `swirl-vortex`, `whip-pan`, `gravitational-lens`, `cinematic-zoom`, `chromatic-split`, `flash-through-white`, `sdf-iris`, `ripple-waves` (ported from [hyperframes](https://github.com/heygen-com/hyperframes), Apache-2.0). `accent` (default `'#0ea5e9'`) tints edge glow/burn in accent-aware shaders: `domain-warp`, `ridged-burn`, `thermal-distortion`, `sdf-iris`, `ripple-waves`. Pre-rendered once per boundary, cached at `.argo/<demo>/shaders/<hash>/` keyed by content hash (includes accent) — second export skips the browser launch. On first export, Chromium renders PNG frames at `N = durationMs × fps` values; `buildShaderSpliceFilter` splices PNG sequence between boundary scenes.
 - **Speed ramp:** Compresses inter-scene gaps (navigation, page loads) to keep demos tight. `gapSpeed: 2.0` = 2× speed for gaps. Only gaps > `minGapMs` (default 500ms) are affected.
 - **Formats:** `1:1` (square), `9:16` (vertical), `gif` (palette-optimized animated GIF). Both `1:1` and `9:16` use **blur-fill** — the source is scaled to fit, overlaid on a blurred version of itself. No more hard crop clipping.
 - **Audio:** `audio: { loudnorm: true }` applies EBU R128 loudness normalization (-16 LUFS). Makes voiceover consistent across engines and scenes.
@@ -473,7 +514,7 @@ PATH="/opt/homebrew/opt/node@22/bin:$PATH" npx hyperframes add logo-outro
 # drops compositions/logo-outro.html + any model/asset files into the project
 ```
 
-The catalog is at <https://hyperframes.heygen.com/catalog/>. Most blocks work on stable chromium; 3D/WebGL ones need `experimentalCanvasDrawElement: true` + `browserChannel: 'chrome-canary'`. See `references/compositions.md` for the import workflow.
+The catalog is at <https://hyperframes.heygen.com/catalog/>. Most blocks work on stable chromium; 3D/WebGL ones need `experimentalCanvasDrawElement: true` + `browserChannel: 'chrome-canary'`. See `references/compositions.md` for the import workflow. For full-frame **components** (vignettes, grain, glows) applied over the recorded page, use `npx argo add <name>` and the `hf-component` cue instead — see "HyperFrames components" above.
 
 **Composition contract** (compatible with hyperframes blocks — `npx hyperframes add <name>` works):
 
diff --git a/skills/argo-guide/references/config-and-quality.md b/skills/argo-guide/references/config-and-quality.md
index 7b55af0..cf04dc0 100644
--- a/skills/argo-guide/references/config-and-quality.md
+++ b/skills/argo-guide/references/config-and-quality.md
@@ -11,6 +11,8 @@ export default defineConfig({
   baseURL: 'http://localhost:3000',
   demosDir: 'demos',
   outputDir: 'videos',
+  blocksDir: 'blocks',        // where `argo add` installs hyperframes registry items (git-tracked)
+  // registry: { url: '...' }, // override the hyperframes registry for `argo add`
   tts: { defaultVoice: 'af_heart', defaultSpeed: 1.0 },
   video: {
     width: 1920,
diff --git a/src/cli.ts b/src/cli.ts
index 2646712..b133c8b 100644
--- a/src/cli.ts
+++ b/src/cli.ts
@@ -29,6 +29,7 @@ import { applySpeedRampToTimeline, type Segment, type SceneSpeedMap } from './sp
 import { scaleCameraMoves, shiftCameraMoves, type CameraMove } from './camera-move.js';
 import { resolveFreezes, adjustPlacementsForFreezes, totalFreezeDurationMs, type FreezeSpec } from './freeze.js';
 import { renderShaderTransitions } from './transitions/shader-render.js';
+import { resolveHfBlockCues, renderHfBlocks } from './hf/block-render.js';
 import type { Placement } from './tts/align.js';
 
 function validateDemoName(name: string): string {
@@ -92,6 +93,7 @@ export function createProgram(): Command {
       const browser = (cmdOpts.browser as BrowserEngine) ?? config.video.browser;
       await record(demo, {
         demosDir: config.demosDir,
+        blocksDir: config.blocksDir,
         baseURL,
         video: { width: config.video.width, height: config.video.height },
         browser,
@@ -253,6 +255,7 @@ export function createProgram(): Command {
           height: exportSize.height,
           fps: config.video?.fps ?? 30,
           cacheDir: `.argo/${demo}/shaders`,
+          accent: shaderTransition.accent,
         });
         // Remap boundarySec to post-trim for the filter_complex splice
         shaderTransitions = rendered.map((r, i) => ({
@@ -261,6 +264,21 @@ export function createProgram(): Command {
         }));
       }
 
+      // hf-block cutaways — pre-render installed hyperframes blocks (cache-hit cheap)
+      let hfBlocks: import('./hf/block-filter.js').RenderedHfBlock[] | undefined;
+      if (placements && placements.length > 0 && existsSync(manifestPath)) {
+        const hfManifestEntries = readScenesManifest(manifestPath);
+        const hfBlockCues = resolveHfBlockCues(hfManifestEntries, placements);
+        if (hfBlockCues.length > 0) {
+          hfBlocks = await renderHfBlocks({
+            cues: hfBlockCues,
+            blocksDir: config.blocksDir,
+            cacheDir: `.argo/${demo}/hf-blocks`,
+            fps: config.video?.fps ?? 30,
+          });
+        }
+      }
+
       await exportVideo({
         demoName: demo,
         argoDir: '.argo',
@@ -303,6 +321,7 @@ export function createProgram(): Command {
         freezeSpecs: resolvedFreezes.length > 0 ? resolvedFreezes : undefined,
         overlayPngs,
         shaderTransitions,
+        hfBlocks,
         encoder: config.export.encoder,
         encoderDefault: 'cpu',
       });
@@ -351,6 +370,9 @@ export function createProgram(): Command {
         demoName: demo,
         demosDir: config.demosDir,
         allowRawGsap: config.overlays.allowRawGsap,
+        blocksDir: config.blocksDir,
+        transitionAccent:
+          config.export.transition?.type === 'shader' ? config.export.transition.accent : undefined,
       });
 
       for (const err of result.errors) {
@@ -370,6 +392,55 @@ export function createProgram(): Command {
       }
     });
 
+  program
+    .command('add [name]')
+    .description('Install a block or component from the hyperframes registry into blocksDir')
+    .option('--list', 'list available registry items instead of installing')
+    .option('--json', 'machine-readable output')
+    .option('--registry <url>', 'override the registry URL')
+    .action(async (name: string | undefined, cmdOpts: { list?: boolean; json?: boolean; registry?: string }) => {
+      const { installItem, listItems } = await import('./hf/add.js');
+      const configPath = program.opts().config;
+      const config = await loadConfigForDemo(undefined, configPath);
+      const registryUrl = cmdOpts.registry ?? config.registry?.url;
+
+      if (cmdOpts.list) {
+        const items = await listItems({ registryUrl });
+        if (cmdOpts.json) {
+          console.log(JSON.stringify(items, null, 2));
+        } else {
+          for (const item of items) {
+            console.log(`${item.type.replace('hyperframes:', '').padEnd(10)} ${item.name}`);
+          }
+          console.log(`\n${items.length} items. Install with: argo add <name>`);
+        }
+        return;
+      }
+
+      if (!name) {
+        console.error('Usage: argo add <name>  (or argo add --list)');
+        process.exitCode = 1;
+        return;
+      }
+
+      try {
+        const result = await installItem({ name, blocksDir: config.blocksDir, registryUrl });
+        if (cmdOpts.json) {
+          console.log(JSON.stringify(result, null, 2));
+        } else {
+          console.log(`Installed ${result.kind === 'components' ? 'component' : 'block'} "${result.name}" → ${result.targetDir}/`);
+          for (const f of result.files) console.log(`  ${f}`);
+          if (result.kind === 'components') {
+            console.log(`\nUse it in a scene: "overlay": { "type": "hf-component", "name": "${result.name}" }`);
+            console.log(`Or in a demo script: await applyComponent(page, '${result.name}')`);
+          }
+        }
+      } catch (err) {
+        console.error((err as Error).message);
+        process.exitCode = 1;
+      }
+    });
+
   program
     .command('doctor')
     .description('Check environment: ffmpeg, Playwright, config, assets')
@@ -461,6 +532,7 @@ export function createProgram(): Command {
             sharpen: config.export.sharpen,
             frame: config.export.frame,
             motionBlur: config.export.motionBlur,
+            blocksDir: config.blocksDir,
           },
         });
         console.log(`\nArgo Dashboard running at: ${url}`);
@@ -500,6 +572,7 @@ export function createProgram(): Command {
           sharpen: config.export.sharpen,
           frame: config.export.frame,
           motionBlur: config.export.motionBlur,
+          blocksDir: config.blocksDir,
         },
       });
       console.log(`\nArgo Preview running at: ${url}`);
diff --git a/src/config.ts b/src/config.ts
index 63a2914..e5a5309 100644
--- a/src/config.ts
+++ b/src/config.ts
@@ -98,6 +98,9 @@ export interface ShaderTransitionConfig {
   type: 'shader';
   shader: ShaderName;
   durationMs?: number;
+  /** Accent hex color tinting edge-glow/burn effects in shaders that use it
+   *  (e.g. ridged-burn, domain-warp, sdf-iris). Default '#0ea5e9'. */
+  accent?: string;
 }
 
 export type TransitionConfig = FilterTransitionConfig | ShaderTransitionConfig;
@@ -230,6 +233,10 @@ export interface ArgoConfig {
   baseURL?: string;
   demosDir: string;
   outputDir: string;
+  /** Directory where `argo add` installs hyperframes registry items. Default 'blocks'. */
+  blocksDir: string;
+  /** Registry override for `argo add`. Defaults to the hyperframes GitHub registry. */
+  registry?: { url?: string };
   tts: TTSConfig;
   video: VideoConfig;
   export: ExportConfig;
@@ -250,6 +257,7 @@ export type UserConfig = Partial<
 const DEFAULTS: ArgoConfig = {
   demosDir: 'demos',
   outputDir: 'videos',
+  blocksDir: 'blocks',
   tts: { defaultVoice: 'af_heart', defaultSpeed: 1.0 },
   video: { width: 1920, height: 1080, fps: 30, browser: 'chromium' as BrowserEngine, deviceScaleFactor: 1 },
   export: { preset: 'slow', crf: 16 },
diff --git a/src/export.ts b/src/export.ts
index 7d2315b..e0fc2be 100644
--- a/src/export.ts
+++ b/src/export.ts
@@ -11,6 +11,7 @@ import { buildCameraMoveFilter, buildMotionBlurFilter, type CameraMove } from '.
 import { buildFreezeFilter, type ResolvedFreeze } from './freeze.js';
 import { getVideoFrameRate } from './media.js';
 import { buildOverlayPngFilters, isImportedVideo, type RenderedOverlayPng } from './overlays/render-to-png.js';
+import { buildHfBlockFilters, type RenderedHfBlock } from './hf/block-filter.js';
 import { buildFrameFilter } from './frame.js';
 import { getGpuEncoderName, resolveEncoder, type GpuEncoder } from './gpu-encoder.js';
 
@@ -66,6 +67,8 @@ export interface ExportOptions {
   watermark?: WatermarkConfig;
   /** Pre-rendered overlay PNGs to composite onto the video (for imported videos). */
   overlayPngs?: RenderedOverlayPng[];
+  /** Pre-rendered hyperframes block PNG sequences composited as cutaway overlays. */
+  hfBlocks?: RenderedHfBlock[];
   /** Apply contrast-adaptive sharpening (CAS) to restore text crispness.
    * true = strength 0.5. { strength: 0.0-1.0 } to tune. */
   sharpen?: boolean | { strength: number };
@@ -412,11 +415,13 @@ export async function exportVideo(options: ExportOptions): Promise<string> {
     // filter_complex — otherwise ffmpeg rejects with "Option vf cannot be
     // applied to input url" because the new `-i` lands after the `-vf`. Covers
     // frame (adds PNG input), watermark (adds PNG input), overlayPngs (adds
-    // PNG inputs), cameraMoves (filter_complex only), and sharpen (which
-    // routes via filter_complex once other filters are present).
+    // PNG inputs), hfBlocks (adds image2 sequence inputs), cameraMoves
+    // (filter_complex only), and sharpen (which routes via filter_complex
+    // once other filters are present).
     const downstreamWillUseFilterComplex =
       (options.cameraMoves && options.cameraMoves.length > 0) ||
       (options.overlayPngs && options.overlayPngs.length > 0) ||
+      (options.hfBlocks && options.hfBlocks.length > 0) ||
       Boolean(options.frame) ||
       Boolean(options.watermark && options.watermark.src && existsSync(options.watermark.src)) ||
       Boolean(options.sharpen);
@@ -472,6 +477,18 @@ export async function exportVideo(options: ExportOptions): Promise<string> {
     nextInput = ovlResult.nextInput;
   }
 
+  // Pre-rendered hyperframes block PNG sequences — composited immediately after
+  // overlay PNGs (same layer priority: after transitions/camera moves, before
+  // frame/watermark) as cutaway overlays with an `enable`-gated timeline window.
+  const hfBlocks = options.hfBlocks;
+  if (hfBlocks && hfBlocks.length > 0) {
+    const hfResult = buildHfBlockFilters(hfBlocks, nextInput, videoSource, outputWidth ?? 1920, outputHeight ?? 1080);
+    args.push(...hfResult.inputArgs);
+    filterParts.push(...hfResult.filterParts);
+    videoSource = hfResult.videoSource;
+    nextInput = hfResult.nextInput;
+  }
+
   // Frame effect — padding, rounded corners, shadow, background
   // Applied AFTER all content processing, BEFORE watermark
   let frame = options.frame;
@@ -758,11 +775,16 @@ export async function exportVideo(options: ExportOptions): Promise<string> {
     // Skip -shortest when:
     // - Freeze-frame holds extend the video beyond the audio
     // - Overlay PNGs are present (imported videos where audio may be shorter than video)
+    // - hf-block PNG sequences are present (same reasoning as overlay PNGs — these
+    //   are finite image2 sequences with eof_action=pass, so they can't hang the
+    //   encode, but -shortest could still truncate the video against a shorter
+    //   audio track when they're the reason overlayPngs would otherwise be absent)
     // - Imported videos have narration shorter than the full source video
     const hasFreezes = freezeSpecs && freezeSpecs.length > 0;
     const hasOverlayPngs = options.overlayPngs && options.overlayPngs.length > 0;
+    const hasHfBlocks = options.hfBlocks && options.hfBlocks.length > 0;
     const importedNarrationVideo = importedVideo && hasAudio;
-    if (!hasFreezes && !hasOverlayPngs && !importedNarrationVideo) {
+    if (!hasFreezes && !hasOverlayPngs && !hasHfBlocks && !importedNarrationVideo) {
       args.push('-shortest');
     }
   }
diff --git a/src/hf/add.ts b/src/hf/add.ts
new file mode 100644
index 0000000..ff45d23
--- /dev/null
+++ b/src/hf/add.ts
@@ -0,0 +1,86 @@
+import { mkdirSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import {
+  DEFAULT_REGISTRY_URL,
+  fetchItemFile,
+  fetchRegistryIndex,
+  fetchRegistryItem,
+  kindFromType,
+  type FetchLike,
+  type RegistryIndexItem,
+} from './registry-client.js';
+
+/** Same pattern the CLI uses for demo names — path-traversal guard. */
+const ITEM_NAME_RE = /^[a-zA-Z0-9][a-zA-Z0-9_-]*$/;
+/** Item file paths must be flat (no slashes) — e.g. "vignette.html". */
+const ITEM_FILE_RE = /^[a-zA-Z0-9][a-zA-Z0-9._-]*$/;
+
+export interface InstallResult {
+  name: string;
+  kind: 'blocks' | 'components';
+  files: string[];
+  targetDir: string;
+}
+
+export async function listItems(opts: {
+  registryUrl?: string;
+  fetchImpl?: FetchLike;
+}): Promise<RegistryIndexItem[]> {
+  return fetchRegistryIndex(opts.registryUrl ?? DEFAULT_REGISTRY_URL, opts.fetchImpl ?? fetch);
+}
+
+export async function installItem(opts: {
+  name: string;
+  blocksDir: string;
+  registryUrl?: string;
+  fetchImpl?: FetchLike;
+}): Promise<InstallResult> {
+  const { name, blocksDir } = opts;
+  const registryUrl = opts.registryUrl ?? DEFAULT_REGISTRY_URL;
+  const fetchImpl = opts.fetchImpl ?? (fetch as FetchLike);
+
+  if (!ITEM_NAME_RE.test(name)) {
+    throw new Error(
+      `Invalid item name "${name}" — only letters, digits, "-" and "_" are allowed.`,
+    );
+  }
+
+  const index = await fetchRegistryIndex(registryUrl, fetchImpl);
+  const entry = index.find((i) => i.name === name);
+  if (!entry) {
+    throw new Error(
+      `Item "${name}" not found in the registry.\nBrowse available items with: argo add --list`,
+    );
+  }
+
+  const kind = kindFromType(entry.type);
+  if (!kind) {
+    if (entry.type === 'hyperframes:example') {
+      throw new Error(
+        `"${name}" is a registry example and examples are not installable via argo add. ` +
+          `Use the hyperframes CLI (hyperframes init --example ${name}) instead.`,
+      );
+    }
+    throw new Error(`"${name}" has unsupported registry type "${entry.type}" — cannot install.`);
+  }
+
+  const item = await fetchRegistryItem(registryUrl, kind, name, fetchImpl);
+  for (const f of item.files) {
+    if (!ITEM_FILE_RE.test(f.path)) {
+      throw new Error(`Unsafe file path in registry-item.json for "${name}": "${f.path}"`);
+    }
+  }
+
+  const targetDir = join(blocksDir, name);
+  mkdirSync(targetDir, { recursive: true });
+
+  const written: string[] = [];
+  for (const f of item.files) {
+    const content = await fetchItemFile(registryUrl, kind, name, f.path, fetchImpl);
+    writeFileSync(join(targetDir, f.path), content, 'utf-8');
+    written.push(f.path);
+  }
+  writeFileSync(join(targetDir, 'registry-item.json'), JSON.stringify(item, null, 2), 'utf-8');
+
+  return { name, kind, files: written, targetDir };
+}
diff --git a/src/hf/apply-component.ts b/src/hf/apply-component.ts
new file mode 100644
index 0000000..c3eb6dd
--- /dev/null
+++ b/src/hf/apply-component.ts
@@ -0,0 +1,130 @@
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import type { Page } from '@playwright/test';
+import { isSafeCssValue, isSafeCssVarName, parseComponentSnippet } from './component.js';
+
+const ITEM_NAME_RE = /^[a-zA-Z0-9][a-zA-Z0-9_-]*$/;
+const CONTAINER_PREFIX = 'argo-hf-';
+
+export function resolveBlocksDir(explicit?: string): string {
+  return explicit ?? process.env.ARGO_BLOCKS_DIR ?? 'blocks';
+}
+
+export interface ApplyComponentOptions {
+  /** CSS custom property overrides, e.g. { '--vignette-size': '40%' }. */
+  params?: Record<string, string>;
+  /** Override the blocks directory (defaults to ARGO_BLOCKS_DIR or 'blocks'). */
+  blocksDir?: string;
+}
+
+/**
+ * Inject an installed hyperframes component (full-frame, pointer-events:
+ * none) into the recorded page. Persists until removeComponent() - pair
+ * them, or use the `hf-component` overlay cue for duration-based display.
+ */
+export async function applyComponent(
+  page: Page,
+  name: string,
+  opts?: ApplyComponentOptions,
+): Promise<void> {
+  if (!ITEM_NAME_RE.test(name)) {
+    throw new Error(`Invalid component name "${name}"`);
+  }
+  const dir = resolveBlocksDir(opts?.blocksDir);
+  const file = join(dir, name, `${name}.html`);
+  if (!existsSync(file)) {
+    throw new Error(`Component "${name}" is not installed (looked in ${dir}/). Run: argo add ${name}`);
+  }
+  const snippet = parseComponentSnippet(readFileSync(file, 'utf-8'));
+
+  const params = opts?.params ?? {};
+  for (const [k, v] of Object.entries(params)) {
+    if (!isSafeCssVarName(k)) {
+      throw new Error(`Param "${k}" is not a CSS custom property name (must match --kebab-case)`);
+    }
+    if (!isSafeCssValue(v)) {
+      throw new Error(`Unsafe CSS value for param "${k}": ${JSON.stringify(v)}`);
+    }
+  }
+
+  try {
+    // Render fence - flush pending browser renders before injecting (same
+    // rationale as overlay injection; see src/overlays/zones.ts).
+    await page.evaluate(() => {});
+    await page.evaluate(
+      ({ name, html, css, js, params, prefix }) => {
+        const id = prefix + name;
+        document.getElementById(id)?.remove();
+        document.querySelectorAll(`style[data-argo-hf="${name}"]`).forEach((el) => el.remove());
+
+        if (css) {
+          const st = document.createElement('style');
+          st.setAttribute('data-argo-hf', name);
+          st.textContent = css;
+          document.head.appendChild(st);
+        }
+
+        const container = document.createElement('div');
+        container.id = id;
+        container.style.cssText =
+          'position:fixed;top:0;left:0;width:100vw;height:100vh;pointer-events:none;z-index:2147482000';
+        for (const [k, v] of Object.entries(params)) {
+          container.style.setProperty(k, v);
+          document.documentElement.style.setProperty(k, v);
+        }
+        container.dataset.argoHfParams = JSON.stringify(Object.keys(params));
+        if (html) container.innerHTML = html;
+        document.body.appendChild(container);
+
+        if (js) {
+          try {
+            new Function(js)();
+          } catch (e) {
+            console.warn(
+              `[argo] component "${name}" script failed (strict CSP can block injected scripts): ${String(e)}`,
+            );
+          }
+        }
+      },
+      { name, html: snippet.html, css: snippet.css, js: snippet.js, params, prefix: CONTAINER_PREFIX },
+    );
+  } catch (err) {
+    // Swallow page/context disposal errors so fire-and-forget callers
+    // never see an unhandled rejection. Surface anything else.
+    const msg = (err as Error)?.message ?? '';
+    if (!msg.includes('Target closed') && !msg.includes('destroyed') && !msg.includes('closed') && !msg.includes('disposed')) {
+      console.warn(`Warning: component "${name}" injection failed: ${msg}`);
+    }
+  }
+}
+
+/** Remove an applied component and its params/styles. */
+export async function removeComponent(page: Page, name: string): Promise<void> {
+  if (!ITEM_NAME_RE.test(name)) return;
+  try {
+    await page.evaluate(
+      ({ name, prefix }) => {
+        const container = document.getElementById(prefix + name);
+        if (container?.dataset.argoHfParams) {
+          try {
+            for (const k of JSON.parse(container.dataset.argoHfParams) as string[]) {
+              document.documentElement.style.removeProperty(k);
+            }
+          } catch {
+            /* ignore malformed dataset */
+          }
+        }
+        container?.remove();
+        document.querySelectorAll(`style[data-argo-hf="${name}"]`).forEach((el) => el.remove());
+      },
+      { name, prefix: CONTAINER_PREFIX },
+    );
+  } catch (err) {
+    // Swallow page/context disposal errors so fire-and-forget callers
+    // never see an unhandled rejection. Surface anything else.
+    const msg = (err as Error)?.message ?? '';
+    if (!msg.includes('Target closed') && !msg.includes('destroyed') && !msg.includes('closed') && !msg.includes('disposed')) {
+      console.warn(`Warning: component "${name}" removal failed: ${msg}`);
+    }
+  }
+}
diff --git a/src/hf/block-filter.ts b/src/hf/block-filter.ts
new file mode 100644
index 0000000..d452260
--- /dev/null
+++ b/src/hf/block-filter.ts
@@ -0,0 +1,72 @@
+import { join } from 'node:path';
+
+/**
+ * Build ffmpeg inputs + filter_complex parts that composite pre-rendered
+ * hyperframes block PNG sequences onto the video. Mirrors
+ * buildOverlayPngFilters (src/overlays/render-to-png.ts) but for image2
+ * sequences: the sequence starts at t=0, so setpts shifts it to the cue's
+ * window before the enable-gated overlay. eof_action=pass keeps cutaway
+ * semantics — output duration never changes.
+ */
+
+export interface RenderedHfBlock {
+  name: string;
+  pngDir: string;
+  frameCount: number;
+  fps: number;
+  startMs: number;
+  endMs: number;
+  /** Native block canvas size (the PNG dimensions). */
+  width: number;
+  height: number;
+  fit: 'cover' | { x: number; y: number; scale: number };
+}
+
+export function buildHfBlockFilters(
+  blocks: RenderedHfBlock[],
+  baseInputCount: number,
+  videoSourceLabel: string,
+  videoW: number,
+  videoH: number,
+): { inputArgs: string[]; filterParts: string[]; videoSource: string; nextInput: number } {
+  if (blocks.length === 0) {
+    return { inputArgs: [], filterParts: [], videoSource: videoSourceLabel, nextInput: baseInputCount };
+  }
+
+  const inputArgs: string[] = [];
+  const filterParts: string[] = [];
+  let currentVideo = videoSourceLabel;
+  let nextInput = baseInputCount;
+
+  for (let i = 0; i < blocks.length; i++) {
+    const b = blocks[i];
+    const inputIdx = nextInput++;
+    inputArgs.push('-framerate', String(b.fps), '-start_number', '0', '-i', join(b.pngDir, 'frame_%04d.png'));
+
+    const startSec = (b.startMs / 1000).toFixed(3);
+    const endSec = (b.endMs / 1000).toFixed(3);
+
+    let scaleExpr: string;
+    let x: number;
+    let y: number;
+    if (b.fit === 'cover') {
+      scaleExpr = `scale=${videoW}:${videoH}`;
+      x = 0;
+      y = 0;
+    } else {
+      scaleExpr = `scale=${Math.round(b.width * b.fit.scale)}:${Math.round(b.height * b.fit.scale)}`;
+      x = b.fit.x;
+      y = b.fit.y;
+    }
+
+    const prepLabel = `hfblk${i}`;
+    const outLabel = `hfb${i}`;
+    filterParts.push(`[${inputIdx}:v]format=rgba,${scaleExpr},setpts=PTS+${startSec}/TB[${prepLabel}]`);
+    filterParts.push(
+      `[${currentVideo}][${prepLabel}]overlay=${x}:${y}:enable='between(t\\,${startSec}\\,${endSec})':format=auto:eof_action=pass[${outLabel}]`,
+    );
+    currentVideo = outLabel;
+  }
+
+  return { inputArgs, filterParts, videoSource: currentVideo, nextInput };
+}
diff --git a/src/hf/block-render.ts b/src/hf/block-render.ts
new file mode 100644
index 0000000..51c5390
--- /dev/null
+++ b/src/hf/block-render.ts
@@ -0,0 +1,318 @@
+import { createHash } from 'node:crypto';
+import { existsSync, mkdirSync, readFileSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { chromium, type Browser } from 'playwright';
+import type { Placement } from '../tts/align.js';
+import type { RenderedHfBlock } from './block-filter.js';
+
+/**
+ * Pre-render a hyperframes block's paused GSAP timeline as a PNG sequence.
+ * Generalizes the shader-render pattern: headless Chromium, per-frame seek,
+ * content-addressed cache managed by the caller (renderHfBlocks in Task 5).
+ *
+ * The renderer only relies on the hyperframes convention
+ * `window.__timelines[<id>] = { duration(), pause(), seek(t) }` — it does
+ * not need GSAP itself, so test fixtures can register plain objects.
+ */
+
+/** Bump when renderBlockFrames' behavior changes what pixels are produced —
+ * salts the cache hash so stale frames from an older renderer never reuse. */
+const RENDERER_VERSION = 2;
+
+export function computeBlockHash(
+  blockHtml: string,
+  params: Record<string, string> | undefined,
+  durationMs: number,
+  fps: number,
+  width: number,
+  height: number,
+  holdLastFrame = false,
+): string {
+  const parts = [RENDERER_VERSION, blockHtml, JSON.stringify(params ?? {}), durationMs, fps, width, height, holdLastFrame].join('|');
+  return createHash('sha256').update(parts).digest('hex').slice(0, 16);
+}
+
+export interface RenderBlockFramesOptions {
+  blockHtmlPath: string;
+  outputDir: string;
+  /** Window duration in the video (drives frame count and retiming). */
+  durationMs: number;
+  fps: number;
+  /** Block canvas dimensions (native block size; compositing scales later). */
+  width: number;
+  height: number;
+  /** CSS custom property overrides applied on document.documentElement. */
+  params?: Record<string, string>;
+  /** Pin the final timeline frame instead of linearly retiming. */
+  holdLastFrame?: boolean;
+  /** Reusable browser — pass one across multiple blocks for performance. */
+  browser?: Browser;
+}
+
+export async function renderBlockFrames(opts: RenderBlockFramesOptions): Promise<number> {
+  mkdirSync(opts.outputDir, { recursive: true });
+  const N = Math.max(1, Math.round((opts.durationMs * opts.fps) / 1000));
+
+  const ownsBrowser = !opts.browser;
+  const browser = opts.browser ?? await chromium.launch({
+    args: [
+      '--use-gl=angle',
+      '--use-angle=swiftshader',
+      '--enable-webgl',
+      '--ignore-gpu-blacklist',
+    ],
+  });
+  try {
+    const page = await browser.newPage({ viewport: { width: opts.width, height: opts.height } });
+    try {
+      await page.goto(pathToFileURL(resolve(opts.blockHtmlPath)).href, { waitUntil: 'load' });
+
+      if (opts.params) {
+        await page.evaluate((params) => {
+          for (const [k, v] of Object.entries(params)) {
+            document.documentElement.style.setProperty(k, v);
+          }
+        }, opts.params);
+      }
+
+      // Fonts load from CDNs in real blocks — bound the wait so a broken
+      // @font-face can't hang the export; warn and continue with fallbacks.
+      const fontsReady = await Promise.race([
+        page.evaluate(() => document.fonts.ready.then(() => true)),
+        new Promise<boolean>((r) => setTimeout(() => r(false), 10_000)),
+      ]);
+      if (!fontsReady) {
+        console.warn(`[argo] fonts still loading after 10s for ${opts.blockHtmlPath} — rendering with fallback fonts`);
+      }
+
+      // Wait for the hyperframes timeline registration convention.
+      try {
+        await page.waitForFunction(
+          () => {
+            const tls = (window as unknown as { __timelines?: Record<string, unknown> }).__timelines;
+            return !!tls && Object.keys(tls).length > 0;
+          },
+          undefined,
+          { timeout: 10_000 },
+        );
+      } catch {
+        throw new Error(
+          `Block "${opts.blockHtmlPath}" never registered a timeline on window.__timelines ` +
+            `(hyperframes blocks register a paused GSAP timeline keyed by composition id).`,
+        );
+      }
+
+      const nativeDurationSec = await page.evaluate(() => {
+        const tls = (window as unknown as {
+          __timelines: Record<string, { duration(): number; pause(): void }>;
+        }).__timelines;
+        const tl = tls[Object.keys(tls)[0]];
+        tl.pause();
+        return tl.duration();
+      });
+
+      const requestedSec = opts.durationMs / 1000;
+      for (let i = 0; i < N; i++) {
+        // Edge-inclusive sampling (matches shader-render.ts): the last frame
+        // lands exactly at the requested window end so the block's final
+        // composed state is captured. N === 1 degenerates to t=0 (usually the
+        // pre-animation state), so a single frame samples the window midpoint.
+        const tVideo = N === 1 ? requestedSec / 2 : (i / (N - 1)) * requestedSec;
+        const tBlock = opts.holdLastFrame
+          ? Math.min(tVideo, nativeDurationSec)
+          : (tVideo * nativeDurationSec) / requestedSec;
+        await page.evaluate((t) => {
+          const tls = (window as unknown as {
+            __timelines: Record<string, { seek(t: number, suppressEvents?: boolean): void }>;
+          }).__timelines;
+          // suppressEvents=false: GSAP's seek() default (true) skips callbacks,
+          // but compositions write label text in onUpdate/.call() — without
+          // this, count-up numbers freeze at their initial value (e.g. "0.0%").
+          tls[Object.keys(tls)[0]].seek(t, false);
+        }, tBlock);
+        await page.screenshot({
+          path: join(opts.outputDir, `frame_${String(i).padStart(4, '0')}.png`),
+          omitBackground: true,
+        });
+      }
+    } finally {
+      await page.close();
+    }
+  } finally {
+    if (ownsBrowser) await browser.close();
+  }
+
+  return N;
+}
+
+/**
+ * A resolved `hf-block` overlay cue: manifest `overlay.type === 'hf-block'`
+ * data merged with the placement window (scene timing) it plays over.
+ */
+export interface HfBlockCueResolved {
+  name: string;
+  params?: Record<string, string>;
+  fit: 'cover' | { x: number; y: number; scale: number };
+  holdLastFrame: boolean;
+  startMs: number;
+  endMs: number;
+}
+
+/**
+ * Extract `hf-block` overlay cues from a raw (untyped) scenes manifest and
+ * anchor each to its scene's placement window on the final export timeline.
+ *
+ * `endMs` is `placement.startMs + (cue.durationMs ?? windowMs)`, clamped to
+ * the placement's own `endMs` — unless the requested duration overshoots the
+ * window, in which case the cue is allowed to run into the gap after the
+ * scene (capped at the next placement's `startMs`, or left uncapped for the
+ * last scene — ffmpeg's `between()` enable window is naturally clipped by
+ * the video's total duration).
+ *
+ * Scenes without a matching placement (e.g. a scene name typo, or a scene
+ * that produced no timeline placement) are skipped with a warning rather
+ * than throwing — hf-block cutaways are best-effort like overlays/subtitles.
+ */
+export function resolveHfBlockCues(rawManifest: unknown[], placements: Placement[]): HfBlockCueResolved[] {
+  const placementByScene = new Map<string, Placement>();
+  for (const p of placements) placementByScene.set(p.scene, p);
+  const sortedPlacements = [...placements].sort((a, b) => a.startMs - b.startMs);
+
+  const cues: HfBlockCueResolved[] = [];
+  for (const entry of rawManifest) {
+    if (!entry || typeof entry !== 'object') continue;
+    const e = entry as { scene?: unknown; overlay?: unknown };
+    if (typeof e.scene !== 'string') continue;
+
+    const overlay = e.overlay;
+    if (!overlay || typeof overlay !== 'object') continue;
+    const ov = overlay as {
+      type?: unknown;
+      name?: unknown;
+      durationMs?: unknown;
+      params?: unknown;
+      fit?: unknown;
+      holdLastFrame?: unknown;
+    };
+    if (ov.type !== 'hf-block' || typeof ov.name !== 'string') continue;
+
+    const placement = placementByScene.get(e.scene);
+    if (!placement) {
+      console.warn(`hf-block cue for scene "${e.scene}" has no placement on the timeline — skipping.`);
+      continue;
+    }
+
+    const windowMs = placement.endMs - placement.startMs;
+    const requestedMs = typeof ov.durationMs === 'number' ? ov.durationMs : windowMs;
+    const naiveEnd = placement.startMs + requestedMs;
+
+    let endMs: number;
+    if (naiveEnd > placement.endMs) {
+      const idx = sortedPlacements.findIndex((p) => p === placement);
+      const next = idx >= 0 ? sortedPlacements[idx + 1] : undefined;
+      endMs = next ? Math.min(naiveEnd, next.startMs) : naiveEnd;
+    } else {
+      endMs = naiveEnd;
+    }
+
+    const params = ov.params && typeof ov.params === 'object'
+      ? (ov.params as Record<string, string>)
+      : undefined;
+    const fit: HfBlockCueResolved['fit'] = ov.fit && ov.fit !== 'cover'
+      ? (ov.fit as { x: number; y: number; scale: number })
+      : 'cover';
+    const holdLastFrame = typeof ov.holdLastFrame === 'boolean' ? ov.holdLastFrame : false;
+
+    cues.push({ name: ov.name, params, fit, holdLastFrame, startMs: placement.startMs, endMs });
+  }
+
+  return cues;
+}
+
+export interface RenderHfBlocksOptions {
+  cues: HfBlockCueResolved[];
+  blocksDir: string;
+  cacheDir: string;
+  fps: number;
+}
+
+interface RegistryItemMeta {
+  dimensions?: { width?: number; height?: number };
+}
+
+/**
+ * Render (or reuse from cache) the PNG sequence for each resolved hf-block
+ * cue. One `chromium` instance is shared across cache misses (launched
+ * lazily, closed in `finally`) — mirrors the shader-render pre-pass pattern.
+ */
+export async function renderHfBlocks(opts: RenderHfBlocksOptions): Promise<RenderedHfBlock[]> {
+  const results: RenderedHfBlock[] = [];
+  let browser: Browser | undefined;
+
+  try {
+    for (const cue of opts.cues) {
+      const blockDir = join(opts.blocksDir, cue.name);
+      const blockHtmlPath = join(blockDir, `${cue.name}.html`);
+      if (!existsSync(blockHtmlPath)) {
+        throw new Error(
+          `hf-block "${cue.name}" is not installed (missing ${blockHtmlPath}). Run: argo add ${cue.name}`,
+        );
+      }
+
+      let width = 1920;
+      let height = 1080;
+      try {
+        const registry = JSON.parse(
+          readFileSync(join(blockDir, 'registry-item.json'), 'utf-8'),
+        ) as RegistryItemMeta;
+        if (typeof registry.dimensions?.width === 'number') width = registry.dimensions.width;
+        if (typeof registry.dimensions?.height === 'number') height = registry.dimensions.height;
+      } catch {
+        // Missing/malformed registry-item.json — fall back to 1920x1080.
+      }
+
+      const durationMs = cue.endMs - cue.startMs;
+      const frameCount = Math.max(1, Math.round((durationMs * opts.fps) / 1000));
+      const blockHtml = readFileSync(blockHtmlPath, 'utf-8');
+      const hash = computeBlockHash(blockHtml, cue.params, durationMs, opts.fps, width, height, cue.holdLastFrame);
+      const pngDir = join(opts.cacheDir, hash);
+      const expectedLastFrame = join(pngDir, `frame_${String(frameCount - 1).padStart(4, '0')}.png`);
+
+      if (!existsSync(expectedLastFrame)) {
+        if (!browser) {
+          browser = await chromium.launch({
+            args: ['--use-gl=angle', '--use-angle=swiftshader', '--enable-webgl', '--ignore-gpu-blacklist'],
+          });
+        }
+        await renderBlockFrames({
+          blockHtmlPath,
+          outputDir: pngDir,
+          durationMs,
+          fps: opts.fps,
+          width,
+          height,
+          params: cue.params,
+          holdLastFrame: cue.holdLastFrame,
+          browser,
+        });
+      }
+
+      results.push({
+        name: cue.name,
+        pngDir,
+        frameCount,
+        fps: opts.fps,
+        startMs: cue.startMs,
+        endMs: cue.endMs,
+        width,
+        height,
+        fit: cue.fit,
+      });
+    }
+  } finally {
+    if (browser) await browser.close();
+  }
+
+  return results;
+}
diff --git a/src/hf/component.ts b/src/hf/component.ts
new file mode 100644
index 0000000..ea1adc9
--- /dev/null
+++ b/src/hf/component.ts
@@ -0,0 +1,49 @@
+/**
+ * Parse a hyperframes component snippet (HTML + <style> + optional <script>,
+ * with usage notes in HTML comments) into injectable parts.
+ *
+ * Components are trusted-at-install (the user chose to `argo add` them and
+ * the files are git-reviewable), but cue/script `params` are runtime input —
+ * they are validated before being set as CSS custom properties.
+ */
+
+export interface ComponentSnippet {
+  html: string;
+  css: string;
+  js: string;
+}
+
+export function parseComponentSnippet(source: string): ComponentSnippet {
+  const noComments = source.replace(/<!--[\s\S]*?-->/g, '');
+  const css: string[] = [];
+  const js: string[] = [];
+  let rest = noComments.replace(/<style[^>]*>([\s\S]*?)<\/style>/gi, (_m, body: string) => {
+    css.push(body.trim());
+    return '';
+  });
+  rest = rest.replace(/<script[^>]*>([\s\S]*?)<\/script>/gi, (_m, body: string) => {
+    js.push(body.trim());
+    return '';
+  });
+  return { html: rest.trim(), css: css.join('\n\n'), js: js.join('\n\n') };
+}
+
+/** CSS custom property name: --kebab-or-camel, nothing else. */
+export function isSafeCssVarName(k: string): boolean {
+  return /^--[a-zA-Z][a-zA-Z0-9-]*$/.test(k);
+}
+
+/**
+ * Conservative allowlist-by-rejection for CSS custom property VALUES.
+ * Blocks declaration/block escapes and resource loads. Values are plain
+ * lengths, colors, keywords, and simple functions like rgba()/calc().
+ */
+export function isSafeCssValue(v: string): boolean {
+  if (typeof v !== 'string' || v.length === 0 || v.length > 200) return false;
+  if (/[;{}<>]/.test(v)) return false;
+  if (/url\s*\(|expression\s*\(|@import|javascript:/i.test(v)) return false;
+  // Reject raw control characters — never legitimate in a CSS value.
+  // eslint-disable-next-line no-control-regex
+  if (/[\x00-\x1f\x7f]/.test(v)) return false;
+  return true;
+}
diff --git a/src/hf/registry-client.ts b/src/hf/registry-client.ts
new file mode 100644
index 0000000..75142c1
--- /dev/null
+++ b/src/hf/registry-client.ts
@@ -0,0 +1,98 @@
+/**
+ * Minimal client for the hyperframes registry layout:
+ *   <registryUrl>/registry.json
+ *   <registryUrl>/<blocks|components>/<name>/registry-item.json
+ *   <registryUrl>/<blocks|components>/<name>/<file.path>
+ * Fetch is injectable so unit tests never touch the network.
+ */
+
+export const DEFAULT_REGISTRY_URL =
+  'https://raw.githubusercontent.com/heygen-com/hyperframes/main/registry';
+
+export type FetchLike = (
+  url: string,
+) => Promise<{ ok: boolean; status: number; text(): Promise<string> }>;
+
+export interface RegistryIndexItem {
+  name: string;
+  type: string;
+}
+
+export interface RegistryItemFile {
+  path: string;
+  target?: string;
+  type?: string;
+}
+
+export interface RegistryItem {
+  name: string;
+  type: string;
+  title?: string;
+  description?: string;
+  tags?: string[];
+  files: RegistryItemFile[];
+  params?: Array<{ key: string; label?: string; type?: string; default?: string }>;
+}
+
+/** Registry item type → URL path segment. Examples are not installable. */
+export function kindFromType(t: string): 'blocks' | 'components' | null {
+  if (t === 'hyperframes:block') return 'blocks';
+  if (t === 'hyperframes:component') return 'components';
+  return null;
+}
+
+async function fetchText(url: string, fetchImpl: FetchLike): Promise<string> {
+  const res = await fetchImpl(url);
+  if (!res.ok) {
+    throw new Error(`Registry fetch failed (${res.status}): ${url}`);
+  }
+  return res.text();
+}
+
+export async function fetchRegistryIndex(
+  registryUrl: string,
+  fetchImpl: FetchLike = fetch,
+): Promise<RegistryIndexItem[]> {
+  const url = `${registryUrl}/registry.json`;
+  const raw = await fetchText(url, fetchImpl);
+  let parsed: { items?: RegistryIndexItem[] };
+  try {
+    parsed = JSON.parse(raw) as { items?: RegistryIndexItem[] };
+  } catch {
+    throw new Error(`Malformed JSON from registry at ${url} — got non-JSON response`);
+  }
+  if (!Array.isArray(parsed.items)) {
+    throw new Error(`Malformed registry index: expected an "items" array at ${url}`);
+  }
+  return parsed.items;
+}
+
+export async function fetchRegistryItem(
+  registryUrl: string,
+  kind: 'blocks' | 'components',
+  name: string,
+  fetchImpl: FetchLike = fetch,
+): Promise<RegistryItem> {
+  const url = `${registryUrl}/${kind}/${name}/registry-item.json`;
+  const raw = await fetchText(url, fetchImpl);
+  let item: RegistryItem;
+  try {
+    item = JSON.parse(raw) as RegistryItem;
+  } catch {
+    throw new Error(`Malformed JSON from registry at ${url} — got non-JSON response`);
+  }
+  if (!item.name || !Array.isArray(item.files)) {
+    throw new Error(`Malformed registry-item.json for "${name}": missing name or files`);
+  }
+  return item;
+}
+
+export async function fetchItemFile(
+  registryUrl: string,
+  kind: 'blocks' | 'components',
+  name: string,
+  filePath: string,
+  fetchImpl: FetchLike = fetch,
+): Promise<string> {
+  return fetchText(`${registryUrl}/${kind}/${name}/${filePath}`, fetchImpl);
+}
diff --git a/src/index.ts b/src/index.ts
index 94907dc..03a971f 100644
--- a/src/index.ts
+++ b/src/index.ts
@@ -56,6 +56,13 @@ export {
 // Effects
 export { showConfetti, type ConfettiOptions } from './effects.js';
 
+// Hyperframes component injection
+export {
+  applyComponent,
+  removeComponent,
+  type ApplyComponentOptions,
+} from './hf/apply-component.js';
+
 // Camera
 export {
   spotlight,
diff --git a/src/overlays/index.ts b/src/overlays/index.ts
index a8beb51..c1eb40c 100644
--- a/src/overlays/index.ts
+++ b/src/overlays/index.ts
@@ -8,6 +8,7 @@ import { isGsapMotion } from './gsap-motion.js';
 import { runGsapEntrance, runGsapExit, gsapExitWallMs } from './gsap-runtime.js';
 import { loadOverlayFromManifest } from './manifest-loader.js';
 import { getBlock, isValidBlockName } from '../blocks/index.js';
+import { applyComponent, removeComponent } from '../hf/apply-component.js';
 
 export type { OverlayCue, OverlayManifestEntry, Zone, TemplateType, MotionPreset } from './types.js';
 export type { SceneEntry } from './types.js';
@@ -110,6 +111,21 @@ export async function showOverlay(
     opts = options;
   }
 
+  if (cue.type === 'hf-component') {
+    // Full-frame component — bypasses zone/theme/template machinery.
+    await applyComponent(page, cue.name, { params: cue.params });
+    await page.waitForTimeout(durationMs);
+    await removeComponent(page, cue.name);
+    return;
+  }
+
+  if (cue.type === 'hf-block') {
+    // Export-time cutaway — nothing is injected during recording, but the
+    // wait preserves the demo script's scene pacing.
+    await page.waitForTimeout(durationMs);
+    return;
+  }
+
   const zone: Zone = cue.placement ?? getConfigDefaultPlacement() ?? 'bottom-center';
   const motion = resolveMotion(cue);
   const theme = await resolveTheme(page, cue, zone, opts?.autoBackground);
@@ -179,6 +195,19 @@ export async function withOverlay(
     opts = options;
   }
 
+  if (cue.type === 'hf-component') {
+    await applyComponent(page, cue.name, { params: cue.params });
+    try {
+      return await action();
+    } finally {
+      await removeComponent(page, cue.name);
+    }
+  }
+
+  if (cue.type === 'hf-block') {
+    return await action();
+  }
+
   const zone: Zone = cue.placement ?? getConfigDefaultPlacement() ?? 'bottom-center';
   const motion = resolveMotion(cue);
   const theme = await resolveTheme(page, cue, zone, opts?.autoBackground);
diff --git a/src/overlays/templates.ts b/src/overlays/templates.ts
index 58206a1..c5161fa 100644
--- a/src/overlays/templates.ts
+++ b/src/overlays/templates.ts
@@ -174,5 +174,13 @@ export function renderTemplate(cue: OverlayCue, theme: BackgroundTheme = 'dark')
       const merged = { ...block.defaultProps, ...cue.props };
       return block.render(merged as never, theme);
     }
+    case 'hf-component':
+      throw new Error(
+        'hf-component cues are injected full-frame by showOverlay/applyComponent, not rendered as zone templates.',
+      );
+    case 'hf-block':
+      throw new Error(
+        'hf-block cues are composited at export time (pre-rendered PNG sequences), not rendered as zone templates.',
+      );
   }
 }
diff --git a/src/overlays/types.ts b/src/overlays/types.ts
index 26dfe30..00eac61 100644
--- a/src/overlays/types.ts
+++ b/src/overlays/types.ts
@@ -98,7 +98,41 @@ export interface CustomBlockCue {
   autoBackground?: boolean;
 }
 
-export type OverlayCue = LowerThirdCue | HeadlineCardCue | CalloutCue | ImageCardCue | ArrowCue | CustomBlockCue;
+export interface HfComponentCue {
+  type: 'hf-component';
+  /** Installed component name under blocksDir (see `argo add`). */
+  name: string;
+  /** CSS custom property overrides, e.g. { '--vignette-size': '40%' }. */
+  params?: Record<string, string>;
+  /** Accepted for manifest uniformity but ignored — components are full-frame. */
+  placement?: Zone;
+  /** Accepted for manifest uniformity but ignored — components are full-frame. */
+  motion?: MotionPreset;
+  /** Accepted for manifest uniformity but ignored — components are full-frame. */
+  autoBackground?: boolean;
+}
+
+export interface HfBlockCue {
+  type: 'hf-block';
+  /** Installed block name under blocksDir (see `argo add`). */
+  name: string;
+  /** Block-specific param overrides passed through to the pre-render step. */
+  params?: Record<string, string>;
+  /** Duration of the export-time cutaway in ms. */
+  durationMs?: number;
+  /** How the rendered block frame is fit into the timeline. Default: 'cover'. */
+  fit?: 'cover' | { x: number; y: number; scale: number };
+  /** Hold the last rendered frame instead of looping/collapsing. */
+  holdLastFrame?: boolean;
+  /** Accepted for manifest uniformity but ignored — blocks are composited at export time. */
+  placement?: Zone;
+  /** Accepted for manifest uniformity but ignored — blocks are composited at export time. */
+  motion?: MotionPreset;
+  /** Accepted for manifest uniformity but ignored — blocks are composited at export time. */
+  autoBackground?: boolean;
+}
+
+export type OverlayCue = LowerThirdCue | HeadlineCardCue | CalloutCue | ImageCardCue | ArrowCue | CustomBlockCue | HfComponentCue | HfBlockCue;
 
 export type OverlayManifestEntry = OverlayCue & {
   scene: string;
diff --git a/src/pipeline.ts b/src/pipeline.ts
index 58b8d83..becbfe7 100644
--- a/src/pipeline.ts
+++ b/src/pipeline.ts
@@ -21,6 +21,7 @@ import { resolveExportSize, type ArgoConfig } from './config.js';
 import { getVideoDurationMs } from './media.js';
 import { buildOverlayPngsForImport } from './overlays/render-to-png.js';
 import { renderShaderTransitions } from './transitions/shader-render.js';
+import { resolveHfBlockCues, renderHfBlocks } from './hf/block-render.js';
 // Note: MusicGen (AI music generation) is a preview-only feature — runs in browser via WebGPU.
 // Pipeline uses saved WAV files via audio.music config path.
 import {
@@ -77,7 +78,7 @@ export function discoverDemos(demosDir: string): string[] {
  * Run the pipeline for all demos in the demosDir.
  */
 export async function runBatchPipeline(
-  config: Pick<ArgoConfig, 'baseURL' | 'demosDir' | 'outputDir' | 'tts' | 'video' | 'export' | 'overlays'>,
+  config: Pick<ArgoConfig, 'baseURL' | 'demosDir' | 'blocksDir' | 'outputDir' | 'tts' | 'video' | 'export' | 'overlays'>,
   pipelineOpts?: PipelineOptions,
 ): Promise<string[]> {
   const demos = discoverDemos(config.demosDir);
@@ -108,7 +109,7 @@ export async function runBatchPipeline(
 
 export async function runPipeline(
   demoName: string,
-  config: Pick<ArgoConfig, 'baseURL' | 'demosDir' | 'outputDir' | 'tts' | 'video' | 'export' | 'overlays'>,
+  config: Pick<ArgoConfig, 'baseURL' | 'demosDir' | 'blocksDir' | 'outputDir' | 'tts' | 'video' | 'export' | 'overlays'>,
   pipelineOpts?: PipelineOptions,
 ): Promise<string> {
   if (!config.baseURL) {
@@ -171,6 +172,7 @@ export async function runPipeline(
   console.log('🎬 Rolling camera...');
   const { timingPath, videoPath } = await record(demoName, {
     demosDir: config.demosDir,
+    blocksDir: config.blocksDir,
     baseURL: config.baseURL,
     video: { width: config.video.width, height: config.video.height, fps: config.video.fps },
     browser: config.video.browser,
@@ -284,7 +286,12 @@ export async function runPipeline(
   // Read per-scene playback speeds from scenes manifest
   const manifestPath = `${config.demosDir}/${demoName}.scenes.json`;
   const sceneSpeeds: SceneSpeedMap = {};
-  let rawManifest: Array<{ scene?: string; playbackSpeed?: number; post?: Array<{ type?: string; atMs?: number; durationMs?: number }> }> = [];
+  let rawManifest: Array<{
+    scene?: string;
+    playbackSpeed?: number;
+    post?: Array<{ type?: string; atMs?: number; durationMs?: number }>;
+    overlay?: { type?: string; [k: string]: unknown };
+  }> = [];
   try {
     rawManifest = JSON.parse(readFileSync(manifestPath, 'utf-8'));
     for (const entry of rawManifest) {
@@ -439,6 +446,7 @@ export async function runPipeline(
       height: exportSize.height,
       fps: config.video?.fps ?? 30,
       cacheDir: join(argoDir, 'shaders'),
+      accent: shaderTransition.accent,
     });
     // Remap boundarySec from pre-trim back to post-trim for the filter_complex splice
     exportOptions.shaderTransitions = rendered.map((r, i) => ({
@@ -447,6 +455,17 @@ export async function runPipeline(
     }));
   }
 
+  // hf-block cutaways — pre-render installed hyperframes blocks (cache-hit cheap)
+  const hfBlockCues = resolveHfBlockCues(rawManifest, finalPlacements);
+  if (hfBlockCues.length > 0) {
+    exportOptions.hfBlocks = await renderHfBlocks({
+      cues: hfBlockCues,
+      blocksDir: config.blocksDir,
+      cacheDir: join(argoDir, 'hf-blocks'),
+      fps: config.video?.fps ?? 30,
+    });
+  }
+
   const outputPath = await exportVideo(exportOptions);
 
   // Scene report
@@ -525,6 +544,7 @@ export async function runPipeline(
       console.log('🎬 Rolling camera...');
       const variantRecord = await record(demoName, {
         demosDir: config.demosDir,
+        blocksDir: config.blocksDir,
         baseURL: config.baseURL,
         video: { width: variant.video.width, height: variant.video.height, fps: config.video.fps },
         browser: config.video.browser,
@@ -648,6 +668,7 @@ export async function runPipeline(
           height: variant.video.height,
           fps: config.video?.fps ?? 30,
           cacheDir: join('.argo', variantSubdir, 'shaders'),
+          accent: shaderTransition.accent,
         });
         // Remap boundarySec to post-trim for the filter_complex splice
         variantShaderTransitions = variantRendered.map((r, i) => ({
@@ -656,6 +677,19 @@ export async function runPipeline(
         }));
       }
 
+      // hf-block cutaways for this variant — same manifest (outer `rawManifest`,
+      // still overlay-typed here — the text-only shadow above is try-block scoped),
+      // own placements + cache dir.
+      const variantHfBlockCues = resolveHfBlockCues(rawManifest, variantPlacements);
+      const variantHfBlocks = variantHfBlockCues.length > 0
+        ? await renderHfBlocks({
+          cues: variantHfBlockCues,
+          blocksDir: config.blocksDir,
+          cacheDir: join('.argo', variantSubdir, 'hf-blocks'),
+          fps: config.video?.fps ?? 30,
+        })
+        : undefined;
+
       const variantOutputPath = await exportVideo({
         demoName: variantSubdir,
         argoDir: '.argo',
@@ -682,6 +716,7 @@ export async function runPipeline(
         freezeSpecs: variantResolvedFreezes.length > 0 ? variantResolvedFreezes : undefined,
         overlayPngs: variantOverlayPngs,
         shaderTransitions: variantShaderTransitions,
+        hfBlocks: variantHfBlocks,
         encoder: config.export.encoder,
         encoderDefault: 'cpu',
       });
diff --git a/src/preview.ts b/src/preview.ts
index d38b63c..3a2acaa 100644
--- a/src/preview.ts
+++ b/src/preview.ts
@@ -26,6 +26,8 @@ import { generateFramePng } from './frame.js';
 import { resolveFreezes, adjustPlacementsForFreezes, totalFreezeDurationMs, type FreezeSpec } from './freeze.js';
 import { buildOverlayPngsForImport, isImportedVideo, type RenderedOverlayPng } from './overlays/render-to-png.js';
 import { renderShaderTransitions, type ShaderTransitionRenderResult } from './transitions/shader-render.js';
+import { resolveHfBlockCues, renderHfBlocks } from './hf/block-render.js';
+import type { RenderedHfBlock } from './hf/block-filter.js';
 import { detectVideoTheme, getVideoDurationMs, probeEdgeColors } from './media.js';
 import { computeWaveform } from './preview-waveform.js';
 import type { BackgroundTheme } from './overlays/zones.js';
@@ -51,6 +53,7 @@ export interface PreviewExportConfig {
   frame?: import('./config.js').FrameConfig;
   motionBlur?: boolean | { intensity: number };
   encoder?: 'cpu' | 'gpu';
+  blocksDir?: string;
 }
 
 export interface PreviewOptions {
@@ -1082,6 +1085,7 @@ export async function startPreviewServer(options: PreviewOptions): Promise<{ url
               height: ec?.outputHeight ?? 720,
               fps: ec?.fps ?? 30,
               cacheDir: join(demoDir, 'shaders'),
+              accent: shaderTransition.accent,
             });
             // Remap boundarySec to post-trim for the filter_complex splice
             previewShaderTransitions = rendered.map((r, i) => ({
@@ -1090,6 +1094,18 @@ export async function startPreviewServer(options: PreviewOptions): Promise<{ url
             }));
           }
 
+          // hf-block cutaways — pre-render installed hyperframes blocks (cache-hit cheap)
+          let previewHfBlocks: RenderedHfBlock[] | undefined;
+          const previewHfBlockCues = resolveHfBlockCues(scenes, freezeAdjustedPlacements);
+          if (previewHfBlockCues.length > 0) {
+            previewHfBlocks = await renderHfBlocks({
+              cues: previewHfBlockCues,
+              blocksDir: ec?.blocksDir ?? 'blocks',
+              cacheDir: join(demoDir, 'hf-blocks'),
+              fps: ec?.fps ?? 30,
+            });
+          }
+
           // Export — use full config so output matches argo pipeline
           await exportVideo({
             demoName,
@@ -1121,6 +1137,7 @@ export async function startPreviewServer(options: PreviewOptions): Promise<{ url
             freezeSpecs: previewResolvedFreezes.length > 0 ? previewResolvedFreezes : undefined,
             overlayPngs,
             shaderTransitions: previewShaderTransitions,
+            hfBlocks: previewHfBlocks,
             encoder: ec?.encoder,
             encoderDefault: 'gpu',
           });
diff --git a/src/record.ts b/src/record.ts
index 629867a..0f4b30d 100644
--- a/src/record.ts
+++ b/src/record.ts
@@ -7,6 +7,8 @@ import { normalizeDeviceScaleFactor, type BrowserEngine, type ShowActionsConfig
 
 export interface RecordOptions {
   demosDir: string;
+  /** Directory containing installed hyperframes components (see `argo add`). */
+  blocksDir?: string;
   baseURL: string;
   video: { width: number; height: number; fps?: number };
   browser?: BrowserEngine;
@@ -294,6 +296,7 @@ export async function record(demoName: string, options: RecordOptions): Promise<
           ARGO_SCENE_DURATIONS_PATH: path.resolve(path.join('.argo', demoName, '.scene-durations.json')),
           ARGO_TRANSCRIPT_PATH: path.resolve(path.join('.argo', demoName, '.scene-transcripts.json')),
           ARGO_OVERLAYS_PATH: path.resolve(path.join(options.demosDir, `${demoName}.scenes.json`)),
+          ARGO_BLOCKS_DIR: path.resolve(options.blocksDir ?? 'blocks'),
         },
       }, (error, stdout, stderr) => {
         clearInterval(progressPoll);
diff --git a/src/transitions/accent.ts b/src/transitions/accent.ts
new file mode 100644
index 0000000..0984efc
--- /dev/null
+++ b/src/transitions/accent.ts
@@ -0,0 +1,28 @@
+/** RGB triple with components normalized to [0, 1]. */
+export type Vec3 = [number, number, number];
+
+export interface AccentColors {
+  accent: Vec3;
+  accentDark: Vec3;
+  accentBright: Vec3;
+}
+
+/** Default accent used when `export.transition.accent` is not configured. */
+export const DEFAULT_ACCENT = '#0ea5e9';
+
+/**
+ * Parse a 6-digit hex color and derive the dark/bright variants the ported
+ * hyperframes shaders expect (edge glow, burn tinting). Dark is a simple
+ * luminance scale; bright mixes toward white.
+ */
+export function deriveAccentColors(hex: string = DEFAULT_ACCENT): AccentColors {
+  const m = /^#?([0-9a-fA-F]{6})$/.exec(hex.trim());
+  if (!m) {
+    throw new Error(`Invalid accent color "${hex}" — expected a 6-digit hex like #0ea5e9`);
+  }
+  const n = parseInt(m[1], 16);
+  const accent: Vec3 = [((n >> 16) & 0xff) / 255, ((n >> 8) & 0xff) / 255, (n & 0xff) / 255];
+  const accentDark = accent.map((v) => v * 0.35) as Vec3;
+  const accentBright = accent.map((v) => v + (1 - v) * 0.65) as Vec3;
+  return { accent, accentDark, accentBright };
+}
diff --git a/src/transitions/shader-page.html.ts b/src/transitions/shader-page.html.ts
index e1f2fa0..804ab44 100644
--- a/src/transitions/shader-page.html.ts
+++ b/src/transitions/shader-page.html.ts
@@ -1,10 +1,17 @@
+import type { AccentColors } from './accent.js';
+
 /**
  * Inline HTML template for the Playwright page used to render shader frames.
  * The page exposes two globals:
  *   window.__loadFrames(aDataUri, bDataUri) — uploads A/B textures
  *   window.__renderAt(progress) → Promise<string> — returns PNG as data URI
  */
-export function buildShaderPageHtml(width: number, height: number, fragmentShaderGlsl: string): string {
+export function buildShaderPageHtml(
+  width: number,
+  height: number,
+  fragmentShaderGlsl: string,
+  accent?: AccentColors,
+): string {
   return `<!DOCTYPE html>
 <html>
 <head><meta charset="utf-8"><style>
@@ -55,6 +62,17 @@ export function buildShaderPageHtml(width: number, height: number, fragmentShade
   }
   gl.useProgram(prog);
 
+  // Optional uniforms — WebGL silently ignores uniform* calls with a null
+  // location, so shaders that don't declare these are unaffected.
+  const accentColors = ${JSON.stringify(accent ?? null)};
+  if (accentColors) {
+    const set3 = (name, v) => gl.uniform3f(gl.getUniformLocation(prog, name), v[0], v[1], v[2]);
+    set3('accent', accentColors.accent);
+    set3('accentDark', accentColors.accentDark);
+    set3('accentBright', accentColors.accentBright);
+  }
+  gl.uniform2f(gl.getUniformLocation(prog, 'resolution'), ${width}, ${height});
+
   const buf = gl.createBuffer();
   gl.bindBuffer(gl.ARRAY_BUFFER, buf);
   gl.bufferData(gl.ARRAY_BUFFER, new Float32Array([-1,-1, 1,-1, -1,1, 1,1]), gl.STATIC_DRAW);
diff --git a/src/transitions/shader-render.ts b/src/transitions/shader-render.ts
index 52a2f41..3bbf2eb 100644
--- a/src/transitions/shader-render.ts
+++ b/src/transitions/shader-render.ts
@@ -5,14 +5,16 @@ import { execFile } from 'node:child_process';
 import { promisify } from 'node:util';
 import { chromium, type Browser } from '@playwright/test';
 import { buildShaderPageHtml } from './shader-page.html.js';
+import { getVideoDurationMs } from '../media.js';
 import { SHADERS, type ShaderName } from './shaders/index.js';
+import { deriveAccentColors, DEFAULT_ACCENT } from './accent.js';
 
 const execFileP = promisify(execFile);
 
 /**
  * Content hash keying the shader render cache. Includes every input that can
- * affect output: shader source, timing parameters, resolution, and the content
- * of the two boundary frames.
+ * affect output: shader source, timing parameters, resolution, the content
+ * of the two boundary frames, and the accent color.
  */
 export function computeShaderHash(
   shader: string,
@@ -22,10 +24,11 @@ export function computeShaderHash(
   height: number,
   aPngPath: string,
   bPngPath: string,
+  accentHex: string = DEFAULT_ACCENT,
 ): string {
   const aHash = createHash('sha256').update(readFileSync(aPngPath)).digest('hex');
   const bHash = createHash('sha256').update(readFileSync(bPngPath)).digest('hex');
-  const parts = [shader, durationMs, fps, width, height, aHash, bHash].join('|');
+  const parts = [shader, durationMs, fps, width, height, aHash, bHash, accentHex.trim().toLowerCase()].join('|');
   return createHash('sha256').update(parts).digest('hex').slice(0, 16);
 }
 
@@ -69,6 +72,8 @@ export interface RenderShaderFramesOptions {
   outputDir: string;
   /** Reusable browser — pass one across multiple boundaries for performance. */
   browser?: Browser;
+  /** Accent hex for shaders using accent uniforms. Default DEFAULT_ACCENT. */
+  accent?: string;
 }
 
 /**
@@ -95,7 +100,12 @@ export async function renderShaderFrames(opts: RenderShaderFramesOptions): Promi
   try {
     const page = await browser.newPage({ viewport: { width: opts.width, height: opts.height } });
     try {
-      const html = buildShaderPageHtml(opts.width, opts.height, SHADERS[opts.shader]);
+      const html = buildShaderPageHtml(
+        opts.width,
+        opts.height,
+        SHADERS[opts.shader],
+        deriveAccentColors(opts.accent),
+      );
       await page.setContent(html, { waitUntil: 'load' });
 
       const glError = await page.evaluate(() => (window as any).__glError as string | undefined);
@@ -156,6 +166,8 @@ export async function renderShaderTransitions(opts: {
   height: number;
   fps: number;
   cacheDir: string;
+  /** Accent hex for shaders using accent uniforms. Default DEFAULT_ACCENT. */
+  accent?: string;
 }): Promise<ShaderTransitionRenderResult[]> {
   if (opts.boundaries.length === 0) return [];
 
@@ -166,18 +178,31 @@ export async function renderShaderTransitions(opts: {
   mkdirSync(tmpFramesDir, { recursive: true });
   const extracted: Array<{ aPath: string; bPath: string; spec: BoundarySpec }> = [];
   const epsilon = 1 / opts.fps / 2;
+  // Marks are wall-clock but the assembled video can run shorter (dropped
+  // frames under jpeg-stitch), so a late boundary may land past the video's
+  // end — clamp extraction inside the video or ffmpeg emits no frame (ENOENT).
+  const videoDurationSec = getVideoDurationMs(opts.videoPath) / 1000;
+  const maxBoundarySec = Math.max(0, videoDurationSec - 2 / opts.fps);
   for (let i = 0; i < opts.boundaries.length; i++) {
     const b = opts.boundaries[i];
+    let boundarySec = b.boundarySec;
+    if (boundarySec > maxBoundarySec) {
+      console.warn(
+        `Shader boundary ${i} at ${boundarySec.toFixed(2)}s is past the video end ` +
+          `(${videoDurationSec.toFixed(2)}s) — clamping.`,
+      );
+      boundarySec = maxBoundarySec;
+    }
     const aPath = pathJoin(tmpFramesDir, `b${i}_a.png`);
     const bPath = pathJoin(tmpFramesDir, `b${i}_b.png`);
-    await extractBoundaryFrame(opts.videoPath, Math.max(0, b.boundarySec - epsilon), aPath);
-    await extractBoundaryFrame(opts.videoPath, b.boundarySec + epsilon, bPath);
+    await extractBoundaryFrame(opts.videoPath, Math.max(0, boundarySec - epsilon), aPath);
+    await extractBoundaryFrame(opts.videoPath, Math.min(boundarySec + epsilon, maxBoundarySec), bPath);
     extracted.push({ aPath, bPath, spec: b });
   }
 
   // Determine cache hits / misses
   const plan = extracted.map(({ aPath, bPath, spec }) => {
-    const hash = computeShaderHash(opts.shader, spec.durationMs, opts.fps, opts.width, opts.height, aPath, bPath);
+    const hash = computeShaderHash(opts.shader, spec.durationMs, opts.fps, opts.width, opts.height, aPath, bPath, opts.accent ?? DEFAULT_ACCENT);
     const pngDir = pathJoin(opts.cacheDir, hash);
     const N = Math.max(1, Math.round((spec.durationMs * opts.fps) / 1000));
     const cached = existsSyncFs(pngDir) && readdirSync(pngDir).filter(f => f.endsWith('.png')).length === N;
@@ -211,6 +236,7 @@ export async function renderShaderTransitions(opts: {
           durationMs: p.spec.durationMs,
           outputDir: p.pngDir,
           browser,
+          accent: opts.accent,
         });
       }
       results.push({
diff --git a/src/transitions/shaders/README.md b/src/transitions/shaders/README.md
index 6cb34b3..3bb4e40 100644
--- a/src/transitions/shaders/README.md
+++ b/src/transitions/shaders/README.md
@@ -4,15 +4,26 @@ WebGL fragment shaders used for cinematic scene transitions. Pre-rendered via Pl
 
 ## Attribution
 
-All shaders are adapted from [gl-transitions.com](https://gl-transitions.com) unless otherwise noted. The gl-transitions project is MIT-licensed.
+The original five shaders are adapted from [gl-transitions.com](https://gl-transitions.com) (MIT) unless otherwise noted. The remaining eleven are adapted from [hyperframes](https://github.com/heygen-com/hyperframes) (`packages/shader-transitions/src/shaders/registry.ts`, Apache-2.0).
 
-| Shader       | Original Author    | License |
-|--------------|--------------------|---------|
-| crosswarp    | Eke Péter          | MIT     |
-| swirl        | Sergey Kosarevsky  | MIT     |
-| ripple       | gre                | MIT     |
-| luma-mask    | adapted from gre   | MIT     |
-| light-leak   | Argo original      | MIT     |
+| Shader              | Original Author           | License    |
+|---------------------|---------------------------|------------|
+| crosswarp           | Eke Péter                 | MIT        |
+| swirl               | Sergey Kosarevsky         | MIT        |
+| ripple              | gre                       | MIT        |
+| luma-mask           | adapted from gre          | MIT        |
+| light-leak          | Argo original             | MIT        |
+| domain-warp         | adapted from hyperframes  | Apache-2.0 |
+| ridged-burn         | adapted from hyperframes  | Apache-2.0 |
+| thermal-distortion  | adapted from hyperframes  | Apache-2.0 |
+| swirl-vortex        | adapted from hyperframes  | Apache-2.0 |
+| whip-pan            | adapted from hyperframes  | Apache-2.0 |
+| gravitational-lens  | adapted from hyperframes  | Apache-2.0 |
+| cinematic-zoom      | adapted from hyperframes  | Apache-2.0 |
+| chromatic-split     | adapted from hyperframes  | Apache-2.0 |
+| flash-through-white | adapted from hyperframes  | Apache-2.0 |
+| sdf-iris            | adapted from hyperframes  | Apache-2.0 |
+| ripple-waves        | adapted from hyperframes  | Apache-2.0 |
 
 All shaders use the gl-transitions fragment shader interface:
 
@@ -21,3 +32,9 @@ All shaders use the gl-transitions fragment shader interface:
 - `uniform float progress` — 0..1 transition progress
 - `varying vec2 vUv` — normalized coord
 - Output: `gl_FragColor`
+
+Accent-aware shaders (`domain-warp`, `ridged-burn`, `thermal-distortion`, `sdf-iris`, `ripple-waves`) additionally receive accent uniforms derived from `export.transition.accent` (default `#0ea5e9`):
+
+- `uniform vec3 accent` — configured accent color
+- `uniform vec3 accentDark` — darkened variant
+- `uniform vec3 accentBright` — brightened variant
diff --git a/src/transitions/shaders/chromatic-split.glsl b/src/transitions/shaders/chromatic-split.glsl
new file mode 100644
index 0000000..7ec3677
--- /dev/null
+++ b/src/transitions/shaders/chromatic-split.glsl
@@ -0,0 +1,27 @@
+// Adapted from hyperframes (github.com/heygen-com/hyperframes)
+// packages/shader-transitions/src/shaders/registry.ts — "chromatic-split"
+// License: Apache-2.0
+precision mediump float;
+uniform sampler2D from;
+uniform sampler2D to;
+uniform float progress;
+uniform vec2 resolution;
+uniform vec3 accent;
+uniform vec3 accentDark;
+uniform vec3 accentBright;
+varying vec2 vUv;
+
+void main(){
+  vec2 c=vUv-.5;
+  float fromShift=progress*.06;
+  float fr=texture2D(from,clamp(vUv+c*fromShift,0.,1.)).r;
+  float fg=texture2D(from,vUv).g;
+  float fb=texture2D(from,clamp(vUv-c*fromShift,0.,1.)).b;
+  vec3 fromSplit=vec3(fr,fg,fb);
+  float toShift=(1.-progress)*.06;
+  float tr=texture2D(to,clamp(vUv-c*toShift,0.,1.)).r;
+  float tg=texture2D(to,vUv).g;
+  float tb=texture2D(to,clamp(vUv+c*toShift,0.,1.)).b;
+  vec3 toSplit=vec3(tr,tg,tb);
+  gl_FragColor=vec4(mix(fromSplit,toSplit,progress),1.);
+}
diff --git a/src/transitions/shaders/cinematic-zoom.glsl b/src/transitions/shaders/cinematic-zoom.glsl
new file mode 100644
index 0000000..31dfdb2
--- /dev/null
+++ b/src/transitions/shaders/cinematic-zoom.glsl
@@ -0,0 +1,35 @@
+// Adapted from hyperframes (github.com/heygen-com/hyperframes)
+// packages/shader-transitions/src/shaders/registry.ts — "cinematic-zoom"
+// License: Apache-2.0
+precision mediump float;
+uniform sampler2D from;
+uniform sampler2D to;
+uniform float progress;
+uniform vec2 resolution;
+uniform vec3 accent;
+uniform vec3 accentDark;
+uniform vec3 accentBright;
+varying vec2 vUv;
+
+void main(){
+  vec2 d=vUv-vec2(.5);
+  float fromS=progress*.08;
+  float toS=(1.-progress)*.06;
+  float fr=0.,fg=0.,fb=0.;
+  for(int i=0; i<12; i++){
+    float f=float(i)/12.;
+    fr+=texture2D(from,vUv-d*(fromS*1.06)*f).r;
+    fg+=texture2D(from,vUv-d*fromS*f).g;
+    fb+=texture2D(from,vUv-d*(fromS*.94)*f).b;
+  }
+  vec3 fromBl=vec3(fr,fg,fb)/12.;
+  float tr=0.,tg=0.,tb=0.;
+  for(int i=0; i<12; i++){
+    float f=float(i)/12.;
+    tr+=texture2D(to,vUv+d*(toS*1.06)*f).r;
+    tg+=texture2D(to,vUv+d*toS*f).g;
+    tb+=texture2D(to,vUv+d*(toS*.94)*f).b;
+  }
+  vec3 toBl=vec3(tr,tg,tb)/12.;
+  gl_FragColor=vec4(mix(fromBl,toBl,progress),1.);
+}
diff --git a/src/transitions/shaders/domain-warp.glsl b/src/transitions/shaders/domain-warp.glsl
new file mode 100644
index 0000000..e6dcd14
--- /dev/null
+++ b/src/transitions/shaders/domain-warp.glsl
@@ -0,0 +1,44 @@
+// Adapted from hyperframes (github.com/heygen-com/hyperframes)
+// packages/shader-transitions/src/shaders/registry.ts — "domain-warp"
+// License: Apache-2.0
+precision mediump float;
+uniform sampler2D from;
+uniform sampler2D to;
+uniform float progress;
+uniform vec2 resolution;
+uniform vec3 accent;
+uniform vec3 accentDark;
+uniform vec3 accentBright;
+varying vec2 vUv;
+
+float hash(vec2 p){
+  return fract(sin(dot(p,vec2(127.1,311.7)))*43758.5453);
+}
+float vnoise(vec2 p){
+  vec2 i=floor(p),f=fract(p);
+  f=f*f*f*(f*(f*6.-15.)+10.);
+  return mix(mix(hash(i),hash(i+vec2(1,0)),f.x),mix(hash(i+vec2(0,1)),hash(i+vec2(1,1)),f.x),f.y);
+}
+float fbm(vec2 p){
+  float v=0.,a=.5;
+  mat2 R=mat2(.8,.6,-.6,.8);
+  for(int i=0; i<5; i++){
+    v+=a*vnoise(p);
+    p=R*p*2.02;
+    a*=.5;
+  }
+  return v;
+}
+void main(){
+  vec2 q=vec2(fbm(vUv*3.),fbm(vUv*3.+vec2(5.2,1.3)));
+  vec2 r=vec2(fbm(vUv*3.+q*4.+vec2(1.7,9.2)),fbm(vUv*3.+q*4.+vec2(8.3,2.8)));
+  float n=fbm(vUv*3.+r*2.);
+  vec2 warpDir=(q-.5)*.4;
+  vec4 A=texture2D(from,clamp(vUv+warpDir*progress,0.,1.));
+  vec4 B=texture2D(to,clamp(vUv-warpDir*(1.-progress),0.,1.));
+  float e=smoothstep(progress-.08,progress+.08,n);
+  float ed=abs(n-progress);
+  float em=smoothstep(.1,0.,ed)*(1.-step(1.,progress));
+  vec3 ec=mix(accentDark,accentBright,smoothstep(0.,.1,ed));
+  gl_FragColor=vec4(mix(B,A,e).rgb+ec*em*2.,1.);
+}
diff --git a/src/transitions/shaders/flash-through-white.glsl b/src/transitions/shaders/flash-through-white.glsl
new file mode 100644
index 0000000..e8a16e6
--- /dev/null
+++ b/src/transitions/shaders/flash-through-white.glsl
@@ -0,0 +1,21 @@
+// Adapted from hyperframes (github.com/heygen-com/hyperframes)
+// packages/shader-transitions/src/shaders/registry.ts — "flash-through-white"
+// License: Apache-2.0
+precision mediump float;
+uniform sampler2D from;
+uniform sampler2D to;
+uniform float progress;
+uniform vec2 resolution;
+uniform vec3 accent;
+uniform vec3 accentDark;
+uniform vec3 accentBright;
+varying vec2 vUv;
+
+void main(){
+  vec4 A=texture2D(from,vUv),B=texture2D(to,vUv);
+  float toWhite=smoothstep(0.,.45,progress);
+  vec3 fromC=mix(A.rgb,vec3(1.),toWhite);
+  float fromWhite=1.-smoothstep(.5,1.,progress);
+  vec3 toC=mix(B.rgb,vec3(1.),fromWhite);
+  gl_FragColor=vec4(mix(fromC,toC,smoothstep(.35,.65,progress)),1.);
+}
diff --git a/src/transitions/shaders/gravitational-lens.glsl b/src/transitions/shaders/gravitational-lens.glsl
new file mode 100644
index 0000000..60c45b8
--- /dev/null
+++ b/src/transitions/shaders/gravitational-lens.glsl
@@ -0,0 +1,28 @@
+// Adapted from hyperframes (github.com/heygen-com/hyperframes)
+// packages/shader-transitions/src/shaders/registry.ts — "gravitational-lens"
+// License: Apache-2.0
+precision mediump float;
+uniform sampler2D from;
+uniform sampler2D to;
+uniform float progress;
+uniform vec2 resolution;
+uniform vec3 accent;
+uniform vec3 accentDark;
+uniform vec3 accentBright;
+varying vec2 vUv;
+
+void main(){
+  vec4 B=texture2D(to,vUv);
+  vec2 uv=vUv-.5;
+  float dist=length(uv);
+  float pull=progress*2.;
+  float warpStr=pull*.3/(dist+.1);
+  vec2 warped=clamp(vUv-uv*warpStr,0.,1.);
+  vec4 A=texture2D(from,warped);
+  float horizon=smoothstep(0.,.3,dist/(1.-progress*.85+.001));
+  float shift=pull*.02/(dist+.2);
+  float r=texture2D(from,clamp(vUv-uv*(warpStr+shift),0.,1.)).r;
+  float b=texture2D(from,clamp(vUv-uv*(warpStr-shift),0.,1.)).b;
+  vec3 lensed=vec3(r,A.g,b)*horizon;
+  gl_FragColor=vec4(mix(lensed,B.rgb,smoothstep(.3,.9,progress)),1.);
+}
diff --git a/src/transitions/shaders/index.ts b/src/transitions/shaders/index.ts
index a3a3d63..f8cadef 100644
--- a/src/transitions/shaders/index.ts
+++ b/src/transitions/shaders/index.ts
@@ -9,16 +9,17 @@ function loadShader(name: string): string {
   return readFileSync(path, 'utf-8');
 }
 
-export const SHADER_NAMES = ['crosswarp', 'swirl', 'ripple', 'luma-mask', 'light-leak'] as const;
+export const SHADER_NAMES = [
+  'crosswarp', 'swirl', 'ripple', 'luma-mask', 'light-leak',
+  'domain-warp', 'ridged-burn', 'thermal-distortion', 'swirl-vortex',
+  'whip-pan', 'gravitational-lens', 'cinematic-zoom', 'chromatic-split', 'flash-through-white',
+  'sdf-iris', 'ripple-waves',
+] as const;
 export type ShaderName = (typeof SHADER_NAMES)[number];
 
-export const SHADERS: Record<ShaderName, string> = {
-  'crosswarp': loadShader('crosswarp'),
-  'swirl': loadShader('swirl'),
-  'ripple': loadShader('ripple'),
-  'luma-mask': loadShader('luma-mask'),
-  'light-leak': loadShader('light-leak'),
-};
+export const SHADERS: Record<ShaderName, string> = Object.fromEntries(
+  SHADER_NAMES.map((name) => [name, loadShader(name)]),
+) as Record<ShaderName, string>;
 
 export function isValidShaderName(name: string): name is ShaderName {
   return (SHADER_NAMES as readonly string[]).includes(name);
diff --git a/src/transitions/shaders/ridged-burn.glsl b/src/transitions/shaders/ridged-burn.glsl
new file mode 100644
index 0000000..9fd9eab
--- /dev/null
+++ b/src/transitions/shaders/ridged-burn.glsl
@@ -0,0 +1,52 @@
+// Adapted from hyperframes (github.com/heygen-com/hyperframes)
+// packages/shader-transitions/src/shaders/registry.ts — "ridged-burn"
+// License: Apache-2.0
+precision mediump float;
+uniform sampler2D from;
+uniform sampler2D to;
+uniform float progress;
+uniform vec2 resolution;
+uniform vec3 accent;
+uniform vec3 accentDark;
+uniform vec3 accentBright;
+varying vec2 vUv;
+
+float hash(vec2 p){
+  return fract(sin(dot(p,vec2(127.1,311.7)))*43758.5453);
+}
+float vnoise(vec2 p){
+  vec2 i=floor(p),f=fract(p);
+  f=f*f*f*(f*(f*6.-15.)+10.);
+  return mix(mix(hash(i),hash(i+vec2(1,0)),f.x),mix(hash(i+vec2(0,1)),hash(i+vec2(1,1)),f.x),f.y);
+}
+float fbm(vec2 p){
+  float v=0.,a=.5;
+  mat2 R=mat2(.8,.6,-.6,.8);
+  for(int i=0; i<5; i++){
+    v+=a*vnoise(p);
+    p=R*p*2.02;
+    a*=.5;
+  }
+  return v;
+}
+float ridged(vec2 p){
+  float v=0.,a=.5;
+  mat2 R=mat2(.8,.6,-.6,.8);
+  for(int i=0; i<5; i++){
+    v+=a*abs(vnoise(p)*2.-1.);
+    p=R*p*2.02;
+    a*=.5;
+  }
+  return v;
+}
+void main(){
+  vec4 A=texture2D(from,vUv),B=texture2D(to,vUv);
+  float n=ridged(vUv*4.);
+  float e=smoothstep(progress-.04,progress+.04,n);
+  float heat=smoothstep(.12,0.,abs(n-progress))*(1.-step(1.,progress));
+  vec3 burn=mix(accentDark,accent,smoothstep(0.,.25,heat));
+  burn=mix(burn,accentBright,smoothstep(.25,.5,heat));
+  burn=mix(burn,vec3(1),smoothstep(.5,1.,heat));
+  float sparks=step(.92,vnoise(vUv*80.))*heat*3.;
+  gl_FragColor=vec4(mix(B,A,e).rgb+burn*heat*3.5+accentBright*sparks,1.);
+}
diff --git a/src/transitions/shaders/ripple-waves.glsl b/src/transitions/shaders/ripple-waves.glsl
new file mode 100644
index 0000000..7ecf246
--- /dev/null
+++ b/src/transitions/shaders/ripple-waves.glsl
@@ -0,0 +1,31 @@
+// Adapted from hyperframes (github.com/heygen-com/hyperframes)
+// packages/shader-transitions/src/shaders/registry.ts — "ripple-waves"
+// License: Apache-2.0
+precision mediump float;
+uniform sampler2D from;
+uniform sampler2D to;
+uniform float progress;
+uniform vec2 resolution;
+uniform vec3 accent;
+uniform vec3 accentDark;
+uniform vec3 accentBright;
+varying vec2 vUv;
+
+void main(){
+  vec2 uv=vUv-.5;
+  float dist=length(uv);
+  vec2 dir=normalize(uv+.001);
+  float fromAmp=progress*.04;
+  float fw1=exp(sin(dist*25.-progress*12.)-1.);
+  float fw2=exp(sin(dist*50.-progress*18.)-1.)*.5;
+  vec2 fromUv=clamp(vUv+dir*(fw1+fw2)*fromAmp,0.,1.);
+  float toAmp=(1.-progress)*.04;
+  float tw1=exp(sin(dist*25.+progress*12.)-1.);
+  float tw2=exp(sin(dist*50.+progress*18.)-1.)*.5;
+  vec2 toUv=clamp(vUv-dir*(tw1+tw2)*toAmp,0.,1.);
+  vec4 A=texture2D(from,fromUv);
+  vec4 B=texture2D(to,toUv);
+  float peak=fw1*progress;
+  vec3 tint=accentBright*peak*.1;
+  gl_FragColor=vec4(mix(A.rgb+tint,B.rgb,progress),1.);
+}
diff --git a/src/transitions/shaders/sdf-iris.glsl b/src/transitions/shaders/sdf-iris.glsl
new file mode 100644
index 0000000..659070a
--- /dev/null
+++ b/src/transitions/shaders/sdf-iris.glsl
@@ -0,0 +1,26 @@
+// Adapted from hyperframes (github.com/heygen-com/hyperframes)
+// packages/shader-transitions/src/shaders/registry.ts — "sdf-iris"
+// License: Apache-2.0
+precision mediump float;
+uniform sampler2D from;
+uniform sampler2D to;
+uniform float progress;
+uniform vec2 resolution;
+uniform vec3 accent;
+uniform vec3 accentDark;
+uniform vec3 accentBright;
+varying vec2 vUv;
+
+void main(){
+  vec4 A=texture2D(from,vUv),B=texture2D(to,vUv);
+  vec2 uv=(vUv-.5)*vec2(resolution.x/resolution.y,1.);
+  float d=length(uv);
+  float radius=progress*1.2;
+  float fw=.003;
+  float edge=smoothstep(radius+fw,radius-fw,d);
+  float ring1=exp(-abs(d-radius)*25.);
+  float ring2=exp(-abs(d-radius+.04)*20.)*.5;
+  float ring3=exp(-abs(d-radius+.08)*15.)*.25;
+  float glow=(ring1+ring2+ring3)*progress*(1.-progress)*4.;
+  gl_FragColor=vec4(mix(A,B,edge).rgb+accentBright*glow*.6,1.);
+}
diff --git a/src/transitions/shaders/swirl-vortex.glsl b/src/transitions/shaders/swirl-vortex.glsl
new file mode 100644
index 0000000..6d611f6
--- /dev/null
+++ b/src/transitions/shaders/swirl-vortex.glsl
@@ -0,0 +1,45 @@
+// Adapted from hyperframes (github.com/heygen-com/hyperframes)
+// packages/shader-transitions/src/shaders/registry.ts — "swirl-vortex"
+// License: Apache-2.0
+precision mediump float;
+uniform sampler2D from;
+uniform sampler2D to;
+uniform float progress;
+uniform vec2 resolution;
+uniform vec3 accent;
+uniform vec3 accentDark;
+uniform vec3 accentBright;
+varying vec2 vUv;
+
+float hash(vec2 p){
+  return fract(sin(dot(p,vec2(127.1,311.7)))*43758.5453);
+}
+float vnoise(vec2 p){
+  vec2 i=floor(p),f=fract(p);
+  f=f*f*f*(f*(f*6.-15.)+10.);
+  return mix(mix(hash(i),hash(i+vec2(1,0)),f.x),mix(hash(i+vec2(0,1)),hash(i+vec2(1,1)),f.x),f.y);
+}
+float fbm(vec2 p){
+  float v=0.,a=.5;
+  mat2 R=mat2(.8,.6,-.6,.8);
+  for(int i=0; i<5; i++){
+    v+=a*vnoise(p);
+    p=R*p*2.02;
+    a*=.5;
+  }
+  return v;
+}
+void main(){
+  vec2 uv=vUv-.5;
+  float dist=length(uv);
+  float warp=fbm(vUv*4.)*.5;
+  float fromAng=progress*(1.-dist)*10.+warp*progress*3.;
+  float fs=sin(fromAng),fc=cos(fromAng);
+  vec2 fromUv=clamp(vec2(uv.x*fc-uv.y*fs,uv.x*fs+uv.y*fc)+.5,0.,1.);
+  float toAng=-(1.-progress)*(1.-dist)*10.-warp*(1.-progress)*3.;
+  float ts=sin(toAng),tc=cos(toAng);
+  vec2 toUv=clamp(vec2(uv.x*tc-uv.y*ts,uv.x*ts+uv.y*tc)+.5,0.,1.);
+  vec4 A=texture2D(from,fromUv);
+  vec4 B=texture2D(to,toUv);
+  gl_FragColor=mix(A,B,progress);
+}
diff --git a/src/transitions/shaders/thermal-distortion.glsl b/src/transitions/shaders/thermal-distortion.glsl
new file mode 100644
index 0000000..caf2566
--- /dev/null
+++ b/src/transitions/shaders/thermal-distortion.glsl
@@ -0,0 +1,45 @@
+// Adapted from hyperframes (github.com/heygen-com/hyperframes)
+// packages/shader-transitions/src/shaders/registry.ts — "thermal-distortion"
+// License: Apache-2.0
+precision mediump float;
+uniform sampler2D from;
+uniform sampler2D to;
+uniform float progress;
+uniform vec2 resolution;
+uniform vec3 accent;
+uniform vec3 accentDark;
+uniform vec3 accentBright;
+varying vec2 vUv;
+
+float hash(vec2 p){
+  return fract(sin(dot(p,vec2(127.1,311.7)))*43758.5453);
+}
+float vnoise(vec2 p){
+  vec2 i=floor(p),f=fract(p);
+  f=f*f*f*(f*(f*6.-15.)+10.);
+  return mix(mix(hash(i),hash(i+vec2(1,0)),f.x),mix(hash(i+vec2(0,1)),hash(i+vec2(1,1)),f.x),f.y);
+}
+float fbm(vec2 p){
+  float v=0.,a=.5;
+  mat2 R=mat2(.8,.6,-.6,.8);
+  for(int i=0; i<5; i++){
+    v+=a*vnoise(p);
+    p=R*p*2.02;
+    a*=.5;
+  }
+  return v;
+}
+void main(){
+  float heat=progress*1.5;
+  float yFade=smoothstep(1.,0.,vUv.y);
+  float shimmer=sin(vUv.y*40.+fbm(vUv*6.)*8.)*fbm(vUv*3.+vec2(0.,progress*2.));
+  float dispX=shimmer*heat*.03*yFade;
+  vec2 fromUv=clamp(vUv+vec2(dispX,0.),0.,1.);
+  vec4 A=texture2D(from,fromUv);
+  float invShimmer=sin(vUv.y*40.+fbm(vUv*6.+3.)*8.)*fbm(vUv*3.+vec2(3.,progress*2.));
+  float dispX2=invShimmer*(1.-progress)*.03*yFade;
+  vec2 toUv=clamp(vUv+vec2(dispX2,0.),0.,1.);
+  vec4 B=texture2D(to,toUv);
+  float haze=heat*yFade*.15*(1.-progress);
+  gl_FragColor=vec4(mix(A.rgb,B.rgb,progress)+accentBright*haze,1.);
+}
diff --git a/src/transitions/shaders/whip-pan.glsl b/src/transitions/shaders/whip-pan.glsl
new file mode 100644
index 0000000..67dabdf
--- /dev/null
+++ b/src/transitions/shaders/whip-pan.glsl
@@ -0,0 +1,32 @@
+// Adapted from hyperframes (github.com/heygen-com/hyperframes)
+// packages/shader-transitions/src/shaders/registry.ts — "whip-pan"
+// License: Apache-2.0
+precision mediump float;
+uniform sampler2D from;
+uniform sampler2D to;
+uniform float progress;
+uniform vec2 resolution;
+uniform vec3 accent;
+uniform vec3 accentDark;
+uniform vec3 accentBright;
+varying vec2 vUv;
+
+void main(){
+  float fromOff=progress*1.5;
+  vec3 fromC=vec3(0.);
+  for(int i=0; i<10; i++){
+    float f=float(i)/10.;
+    vec2 fuv=vec2(vUv.x+fromOff+progress*.08*f,vUv.y);
+    fromC+=texture2D(from,clamp(fuv,0.,1.)).rgb;
+  }
+  fromC/=10.;
+  float toOff=(1.-progress)*1.5;
+  vec3 toC=vec3(0.);
+  for(int i=0; i<10; i++){
+    float f=float(i)/10.;
+    vec2 tuv=vec2(vUv.x-toOff-(1.-progress)*.08*f,vUv.y);
+    toC+=texture2D(to,clamp(tuv,0.,1.)).rgb;
+  }
+  toC/=10.;
+  gl_FragColor=vec4(mix(fromC,toC,progress),1.);
+}
diff --git a/src/validate.ts b/src/validate.ts
index fbe5e70..db8cda5 100644
--- a/src/validate.ts
+++ b/src/validate.ts
@@ -7,6 +7,10 @@ export interface ValidateOptions {
   demosDir: string;
   /** Mirrors config `overlays.allowRawGsap`. When true, `motion.raw` is accepted. */
   allowRawGsap?: boolean;
+  /** Directory holding installed hyperframes items (config.blocksDir). Default 'blocks'. */
+  blocksDir?: string;
+  /** Mirrors config `export.transition.accent` — validated as 6-digit hex when set. */
+  transitionAccent?: string;
 }
 
 export interface ValidateResult {
@@ -19,6 +23,13 @@ export async function validateDemo(options: ValidateOptions): Promise<ValidateRe
   const errors: string[] = [];
   const warnings: string[] = [];
 
+  // Validate export.transition.accent (6-digit hex, optional leading #)
+  if (options.transitionAccent !== undefined && !/^#?[0-9a-fA-F]{6}$/.test(options.transitionAccent.trim())) {
+    errors.push(
+      `export.transition.accent: "${options.transitionAccent}" is not a 6-digit hex color (e.g. #0ea5e9)`,
+    );
+  }
+
   // Check demo script exists
   const scriptPath = join(demosDir, `${demoName}.demo.ts`);
   if (!existsSync(scriptPath)) {
@@ -56,7 +67,7 @@ export async function validateDemo(options: ValidateOptions): Promise<ValidateRe
       if (!Array.isArray(scenes)) {
         errors.push(`Scenes manifest must be a JSON array`);
       } else {
-        const validTypes = new Set(['lower-third', 'headline-card', 'callout', 'image-card', 'arrow', 'block']);
+        const validTypes = new Set(['lower-third', 'headline-card', 'callout', 'image-card', 'arrow', 'block', 'hf-component', 'hf-block']);
         const validPlacements = new Set(['bottom-center', 'top-left', 'top-right', 'bottom-left', 'bottom-right', 'center']);
         const validMotions = new Set(['none', 'fade-in', 'slide-in']);
 
@@ -108,6 +119,36 @@ export async function validateDemo(options: ValidateOptions): Promise<ValidateRe
                 errors.push(`Scene "${entry.scene}" overlay: "props" object is required when type="block"`);
               }
             }
+            // Validate hf-component / hf-block fields — both install to the same
+            // blocksDir/<name>/<name>.html layout.
+            if (ov.type === 'hf-component' || ov.type === 'hf-block') {
+              if (!ov.name || typeof ov.name !== 'string') {
+                errors.push(`Scene "${entry.scene}" overlay: ${ov.type} requires a "name" field`);
+              } else if (!/^[a-zA-Z0-9][a-zA-Z0-9_-]*$/.test(ov.name)) {
+                errors.push(`Scene "${entry.scene}" overlay: invalid ${ov.type} name "${ov.name}"`);
+              } else {
+                const blocksDir = options.blocksDir ?? 'blocks';
+                const componentFile = join(blocksDir, ov.name, `${ov.name}.html`);
+                if (!existsSync(componentFile)) {
+                  errors.push(
+                    `Scene "${entry.scene}" overlay: ${ov.type} "${ov.name}" is not installed ` +
+                      `(missing ${componentFile}). Run: argo add ${ov.name}`,
+                  );
+                }
+              }
+            }
+            // Validate hf-block fit shape
+            if (ov.type === 'hf-block' && ov.fit !== undefined && ov.fit !== 'cover') {
+              const fit = ov.fit;
+              if (
+                typeof fit !== 'object' || fit === null ||
+                typeof fit.x !== 'number' || typeof fit.y !== 'number' || typeof fit.scale !== 'number'
+              ) {
+                errors.push(
+                  `Scene "${entry.scene}" overlay: hf-block "fit" must be 'cover' or { x, y, scale } with numeric fields`,
+                );
+              }
+            }
           }
         }
 
diff --git a/tests/config.test.ts b/tests/config.test.ts
index 4495592..ccb4d77 100644
--- a/tests/config.test.ts
+++ b/tests/config.test.ts
@@ -15,6 +15,7 @@ import { engines } from '../src/tts/engines/index.js';
 const DEFAULTS: ArgoConfig = {
   demosDir: 'demos',
   outputDir: 'videos',
+  blocksDir: 'blocks',
   tts: { defaultVoice: 'af_heart', defaultSpeed: 1.0 },
   video: { width: 1920, height: 1080, fps: 30, browser: 'chromium', deviceScaleFactor: 1 },
   export: { preset: 'slow', crf: 16 },
diff --git a/tests/hf/add.test.ts b/tests/hf/add.test.ts
new file mode 100644
index 0000000..57cb65e
--- /dev/null
+++ b/tests/hf/add.test.ts
@@ -0,0 +1,105 @@
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import { mkdtempSync, rmSync, existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { tmpdir } from 'node:os';
+import { installItem, listItems } from '../../src/hf/add.js';
+import type { FetchLike } from '../../src/hf/registry-client.js';
+
+const REG = 'https://example.test/registry';
+
+function stubFetch(routes: Record<string, string>): FetchLike {
+  return async (url: string) => ({
+    ok: routes[url] !== undefined,
+    status: routes[url] !== undefined ? 200 : 404,
+    text: async () => routes[url] ?? 'not found',
+  });
+}
+
+const ROUTES = {
+  [`${REG}/registry.json`]: JSON.stringify({
+    items: [
+      { name: 'vignette', type: 'hyperframes:component' },
+      { name: 'logo-outro', type: 'hyperframes:block' },
+      { name: 'warm-grain', type: 'hyperframes:example' },
+    ],
+  }),
+  [`${REG}/components/vignette/registry-item.json`]: JSON.stringify({
+    name: 'vignette',
+    type: 'hyperframes:component',
+    files: [{ path: 'vignette.html' }],
+  }),
+  [`${REG}/components/vignette/vignette.html`]: '<div id="hf-vignette"></div>',
+};
+
+describe('installItem', () => {
+  let tmp: string;
+  beforeEach(() => { tmp = mkdtempSync(join(tmpdir(), 'argo-add-')); });
+  afterEach(() => { rmSync(tmp, { recursive: true, force: true }); });
+
+  it('installs a component: files + registry-item.json under blocksDir/<name>/', async () => {
+    const result = await installItem({
+      name: 'vignette', blocksDir: tmp, registryUrl: REG, fetchImpl: stubFetch(ROUTES),
+    });
+    expect(result.kind).toBe('components');
+    expect(existsSync(join(tmp, 'vignette', 'vignette.html'))).toBe(true);
+    expect(existsSync(join(tmp, 'vignette', 'registry-item.json'))).toBe(true);
+    expect(readFileSync(join(tmp, 'vignette', 'vignette.html'), 'utf-8')).toContain('hf-vignette');
+    expect(result.files).toContain('vignette.html');
+  });
+
+  it('rejects invalid item names (path traversal guard)', async () => {
+    for (const bad of ['../evil', 'a/b', '.hidden', 'name!']) {
+      await expect(
+        installItem({ name: bad, blocksDir: tmp, registryUrl: REG, fetchImpl: stubFetch(ROUTES) }),
+      ).rejects.toThrow(/invalid item name/i);
+    }
+  });
+
+  it('rejects example items with a helpful error', async () => {
+    await expect(
+      installItem({ name: 'warm-grain', blocksDir: tmp, registryUrl: REG, fetchImpl: stubFetch(ROUTES) }),
+    ).rejects.toThrow(/example.*not installable/i);
+  });
+
+  it('rejects unsupported registry types with a clear error', async () => {
+    const routes = {
+      ...ROUTES,
+      [`${REG}/registry.json`]: JSON.stringify({
+        items: [
+          { name: 'vignette', type: 'hyperframes:component' },
+          { name: 'widget-x', type: 'hyperframes:widget' },
+        ],
+      }),
+    };
+    await expect(
+      installItem({ name: 'widget-x', blocksDir: tmp, registryUrl: REG, fetchImpl: stubFetch(routes) }),
+    ).rejects.toThrow(/unsupported registry type.*hyperframes:widget/i);
+  });
+
+  it('rejects unknown items pointing at --list', async () => {
+    await expect(
+      installItem({ name: 'nope', blocksDir: tmp, registryUrl: REG, fetchImpl: stubFetch(ROUTES) }),
+    ).rejects.toThrow(/not found.*--list/is);
+  });
+
+  it('rejects item files with unsafe paths', async () => {
+    const routes = {
+      ...ROUTES,
+      [`${REG}/components/vignette/registry-item.json`]: JSON.stringify({
+        name: 'vignette',
+        type: 'hyperframes:component',
+        files: [{ path: '../../etc/passwd' }],
+      }),
+    };
+    await expect(
+      installItem({ name: 'vignette', blocksDir: tmp, registryUrl: REG, fetchImpl: stubFetch(routes) }),
+    ).rejects.toThrow(/unsafe file path/i);
+  });
+});
+
+describe('listItems', () => {
+  it('returns the raw index', async () => {
+    const items = await listItems({ registryUrl: REG, fetchImpl: stubFetch(ROUTES) });
+    expect(items).toHaveLength(3);
+  });
+});
diff --git a/tests/hf/apply-component.test.ts b/tests/hf/apply-component.test.ts
new file mode 100644
index 0000000..35fa03c
--- /dev/null
+++ b/tests/hf/apply-component.test.ts
@@ -0,0 +1,83 @@
+import { describe, it, expect, beforeAll, afterAll, beforeEach, afterEach } from 'vitest';
+import { mkdtempSync, rmSync, mkdirSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { tmpdir } from 'node:os';
+import { chromium, type Browser, type Page } from 'playwright';
+import { applyComponent, removeComponent, resolveBlocksDir } from '../../src/hf/apply-component.js';
+
+const SNIPPET = `<div id="hf-vignette"></div>
+<style>#hf-vignette { position: absolute; inset: 0; background: radial-gradient(ellipse, transparent var(--vignette-size, 45%), rgba(0,0,0,0.7) 100%); }</style>
+<script>document.documentElement.dataset.hfScriptRan = '1';</script>`;
+
+let browser: Browser;
+let page: Page;
+let tmp: string;
+
+beforeAll(async () => {
+  browser = await chromium.launch();
+}, 60_000);
+afterAll(async () => { await browser.close(); });
+
+beforeEach(async () => {
+  tmp = mkdtempSync(join(tmpdir(), 'argo-apply-'));
+  mkdirSync(join(tmp, 'vignette'), { recursive: true });
+  writeFileSync(join(tmp, 'vignette', 'vignette.html'), SNIPPET);
+  page = await browser.newPage();
+  await page.setContent('<h1>app</h1>');
+});
+afterEach(async () => {
+  await page.close();
+  rmSync(tmp, { recursive: true, force: true });
+});
+
+describe('resolveBlocksDir', () => {
+  it('prefers explicit, then env, then "blocks"', () => {
+    const prev = process.env.ARGO_BLOCKS_DIR;
+    delete process.env.ARGO_BLOCKS_DIR;
+    expect(resolveBlocksDir('x')).toBe('x');
+    expect(resolveBlocksDir()).toBe('blocks');
+    process.env.ARGO_BLOCKS_DIR = '/tmp/bd';
+    expect(resolveBlocksDir()).toBe('/tmp/bd');
+    if (prev === undefined) delete process.env.ARGO_BLOCKS_DIR; else process.env.ARGO_BLOCKS_DIR = prev;
+  });
+});
+
+describe('applyComponent / removeComponent', () => {
+  it('injects container + style + runs script, applies params, and removes cleanly', async () => {
+    await applyComponent(page, 'vignette', {
+      blocksDir: tmp,
+      params: { '--vignette-size': '30%' },
+    });
+
+    expect(await page.locator('#argo-hf-vignette').count()).toBe(1);
+    expect(await page.locator('style[data-argo-hf="vignette"]').count()).toBe(1);
+    expect(await page.evaluate(() => document.documentElement.dataset.hfScriptRan)).toBe('1');
+    expect(
+      await page.evaluate(() =>
+        document.documentElement.style.getPropertyValue('--vignette-size'),
+      ),
+    ).toBe('30%');
+
+    await removeComponent(page, 'vignette');
+    expect(await page.locator('#argo-hf-vignette').count()).toBe(0);
+    expect(await page.locator('style[data-argo-hf="vignette"]').count()).toBe(0);
+    expect(
+      await page.evaluate(() =>
+        document.documentElement.style.getPropertyValue('--vignette-size'),
+      ),
+    ).toBe('');
+  });
+
+  it('throws for a component that is not installed', async () => {
+    await expect(applyComponent(page, 'nope', { blocksDir: tmp })).rejects.toThrow(/argo add nope/);
+  });
+
+  it('rejects unsafe params before touching the page', async () => {
+    await expect(
+      applyComponent(page, 'vignette', { blocksDir: tmp, params: { '--x': 'red; }' } }),
+    ).rejects.toThrow(/unsafe/i);
+    await expect(
+      applyComponent(page, 'vignette', { blocksDir: tmp, params: { 'not-a-var': 'red' } }),
+    ).rejects.toThrow(/custom property/i);
+  });
+}, 60_000);
diff --git a/tests/hf/block-filter.test.ts b/tests/hf/block-filter.test.ts
new file mode 100644
index 0000000..b375a24
--- /dev/null
+++ b/tests/hf/block-filter.test.ts
@@ -0,0 +1,49 @@
+import { describe, it, expect } from 'vitest';
+import { buildHfBlockFilters, type RenderedHfBlock } from '../../src/hf/block-filter.js';
+
+const BLOCK: RenderedHfBlock = {
+  name: 'logo-outro', pngDir: '/tmp/cache/abc', frameCount: 60, fps: 30,
+  startMs: 12_000, endMs: 14_000, width: 1920, height: 1080, fit: 'cover',
+};
+
+describe('buildHfBlockFilters', () => {
+  it('returns passthrough for an empty list', () => {
+    const r = buildHfBlockFilters([], 2, 'v0', 1920, 1080);
+    expect(r).toEqual({ inputArgs: [], filterParts: [], videoSource: 'v0', nextInput: 2 });
+  });
+
+  it('adds a framerate-pinned image2 sequence input per block', () => {
+    const r = buildHfBlockFilters([BLOCK], 2, 'v0', 1920, 1080);
+    expect(r.inputArgs).toEqual([
+      '-framerate', '30', '-start_number', '0', '-i', '/tmp/cache/abc/frame_%04d.png',
+    ]);
+    expect(r.nextInput).toBe(3);
+  });
+
+  it('cover fit: scales to video size, shifts pts to the window start, overlays with enable window', () => {
+    const r = buildHfBlockFilters([BLOCK], 2, 'v0', 1920, 1080);
+    expect(r.filterParts).toHaveLength(2);
+    expect(r.filterParts[0]).toBe('[2:v]format=rgba,scale=1920:1080,setpts=PTS+12.000/TB[hfblk0]');
+    expect(r.filterParts[1]).toBe(
+      "[v0][hfblk0]overlay=0:0:enable='between(t\\,12.000\\,14.000)':format=auto:eof_action=pass[hfb0]",
+    );
+    expect(r.videoSource).toBe('hfb0');
+  });
+
+  it('custom fit: scales by factor and positions at x/y', () => {
+    const r = buildHfBlockFilters(
+      [{ ...BLOCK, fit: { x: 100, y: 50, scale: 0.5 } }], 2, 'v0', 1920, 1080,
+    );
+    expect(r.filterParts[0]).toBe('[2:v]format=rgba,scale=960:540,setpts=PTS+12.000/TB[hfblk0]');
+    expect(r.filterParts[1]).toContain('overlay=100:50:enable=');
+  });
+
+  it('chains multiple blocks through intermediate labels', () => {
+    const second: RenderedHfBlock = { ...BLOCK, name: 'x-post', pngDir: '/tmp/cache/def', startMs: 2000, endMs: 3000 };
+    const r = buildHfBlockFilters([BLOCK, second], 2, 'v0', 1920, 1080);
+    expect(r.nextInput).toBe(4);
+    expect(r.filterParts[1]).toContain('[v0][hfblk0]');
+    expect(r.filterParts[3]).toContain('[hfb0][hfblk1]');
+    expect(r.videoSource).toBe('hfb1');
+  });
+});
diff --git a/tests/hf/block-render.test.ts b/tests/hf/block-render.test.ts
new file mode 100644
index 0000000..9697a6d
--- /dev/null
+++ b/tests/hf/block-render.test.ts
@@ -0,0 +1,118 @@
+import { describe, it, expect, beforeAll, afterAll, beforeEach, afterEach } from 'vitest';
+import { mkdtempSync, rmSync, writeFileSync, readdirSync, existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { tmpdir } from 'node:os';
+import { chromium, type Browser } from 'playwright';
+import { computeBlockHash, renderBlockFrames } from '../../src/hf/block-render.js';
+
+// Fixture block: no GSAP, no network. Registers a fake timeline implementing
+// the { duration, pause, seek } interface the renderer relies on, and mirrors
+// seek progress into the DOM so frames are visually distinguishable.
+const FIXTURE_BLOCK = `<!doctype html>
+<html><head><style>
+  html, body { margin: 0; width: 320px; height: 180px; background: transparent; }
+  #bar { position: absolute; top: 80px; left: 0; height: 20px; background: rgb(255, 0, 0); width: 0; }
+</style></head>
+<body>
+  <div id="root" data-composition-id="fixture"><div id="bar"></div></div>
+  <script>
+    window.__timelines = {
+      fixture: {
+        _t: 0,
+        duration() { return 2; },
+        pause() {},
+        seek(t) { this._t = t; document.getElementById('bar').style.width = (t / 2) * 320 + 'px'; },
+      },
+    };
+  </script>
+</body></html>`;
+
+describe('computeBlockHash', () => {
+  it('is stable and sensitive to every component', () => {
+    const base = computeBlockHash('<html>', { '--x': '1' }, 1000, 30, 320, 180);
+    expect(base).toMatch(/^[0-9a-f]{16}$/);
+    expect(computeBlockHash('<html>', { '--x': '1' }, 1000, 30, 320, 180)).toBe(base);
+    expect(computeBlockHash('<html>!', { '--x': '1' }, 1000, 30, 320, 180)).not.toBe(base);
+    expect(computeBlockHash('<html>', { '--x': '2' }, 1000, 30, 320, 180)).not.toBe(base);
+    expect(computeBlockHash('<html>', { '--x': '1' }, 1500, 30, 320, 180)).not.toBe(base);
+    expect(computeBlockHash('<html>', undefined, 1000, 30, 320, 180)).toBe(
+      computeBlockHash('<html>', {}, 1000, 30, 320, 180),
+    );
+    expect(computeBlockHash('<html>', undefined, 1000, 30, 320, 180, true)).not.toBe(
+      computeBlockHash('<html>', undefined, 1000, 30, 320, 180, false),
+    );
+  });
+});
+
+describe('renderBlockFrames', () => {
+  let browser: Browser;
+  let tmp: string;
+
+  beforeAll(async () => { browser = await chromium.launch(); }, 60_000);
+  afterAll(async () => { await browser.close(); });
+  beforeEach(() => { tmp = mkdtempSync(join(tmpdir(), 'argo-blockrender-')); });
+  afterEach(() => { rmSync(tmp, { recursive: true, force: true }); });
+
+  it('renders N frames by seeking the registered timeline', async () => {
+    const blockPath = join(tmp, 'fixture.html');
+    writeFileSync(blockPath, FIXTURE_BLOCK);
+    const outDir = join(tmp, 'frames');
+    const n = await renderBlockFrames({
+      blockHtmlPath: blockPath, outputDir: outDir,
+      durationMs: 1000, fps: 10, width: 320, height: 180, browser,
+    });
+    expect(n).toBe(10);
+    const frames = readdirSync(outDir).filter((f) => f.endsWith('.png')).sort();
+    expect(frames).toHaveLength(10);
+    expect(frames[0]).toBe('frame_0000.png');
+    expect(frames[9]).toBe('frame_0009.png');
+    // first and last frame must differ (bar width animates with seek)
+    expect(readFileSync(join(outDir, 'frame_0000.png')).equals(readFileSync(join(outDir, 'frame_0009.png')))).toBe(false);
+  }, 60_000);
+
+  it('applies params as CSS custom properties on the document root', async () => {
+    const blockPath = join(tmp, 'fx.html');
+    writeFileSync(blockPath, FIXTURE_BLOCK.replace('rgb(255, 0, 0)', 'var(--bar-color, rgb(255, 0, 0))'));
+    const a = join(tmp, 'a');
+    const b = join(tmp, 'b');
+    await renderBlockFrames({ blockHtmlPath: blockPath, outputDir: a, durationMs: 200, fps: 5, width: 320, height: 180, browser });
+    await renderBlockFrames({ blockHtmlPath: blockPath, outputDir: b, durationMs: 200, fps: 5, width: 320, height: 180, params: { '--bar-color': 'rgb(0, 0, 255)' }, browser });
+    expect(readFileSync(join(a, 'frame_0000.png')).equals(readFileSync(join(b, 'frame_0000.png')))).toBe(false);
+  }, 60_000);
+
+  it('fails with an actionable error when no timeline is registered', async () => {
+    const blockPath = join(tmp, 'no-tl.html');
+    writeFileSync(blockPath, '<!doctype html><html><body><div>static</div></body></html>');
+    await expect(
+      renderBlockFrames({ blockHtmlPath: blockPath, outputDir: join(tmp, 'out'), durationMs: 200, fps: 5, width: 320, height: 180, browser }),
+    ).rejects.toThrow(/__timelines/);
+  }, 60_000);
+
+  it('holdLastFrame produces different pixels than retiming when the window overshoots the native duration', async () => {
+    // FIXTURE_BLOCK's native timeline duration is 2s. Requesting a 4s window
+    // (durationMs: 4000, fps: 2) makes N = round(4000*2/1000) = 8, so the
+    // window overshoots the native 2s duration and the two modes diverge.
+    //
+    // At i=4: tVideo = (4/(N-1)) * requestedSec = (4/7) * 4 = 16/7 ≈ 2.2857s
+    //   - holdLastFrame: tBlock = min(tVideo, nativeDurationSec) = min(2.2857, 2) = 2.0
+    //   - retime:        tBlock = (tVideo * nativeDurationSec) / requestedSec
+    //                            = (2.2857 * 2) / 4 ≈ 1.1429
+    // 2.0 (bar fully extended) vs ~1.1429 (bar ~57% extended) render visibly
+    // different bar widths, so frame_0004.png differs between the two modes.
+    const blockPath = join(tmp, 'hold-vs-retime.html');
+    writeFileSync(blockPath, FIXTURE_BLOCK);
+    const holdDir = join(tmp, 'hold');
+    const retimeDir = join(tmp, 'retime');
+    await renderBlockFrames({
+      blockHtmlPath: blockPath, outputDir: holdDir,
+      durationMs: 4000, fps: 2, width: 320, height: 180, holdLastFrame: true, browser,
+    });
+    await renderBlockFrames({
+      blockHtmlPath: blockPath, outputDir: retimeDir,
+      durationMs: 4000, fps: 2, width: 320, height: 180, holdLastFrame: false, browser,
+    });
+    expect(
+      readFileSync(join(holdDir, 'frame_0004.png')).equals(readFileSync(join(retimeDir, 'frame_0004.png'))),
+    ).toBe(false);
+  }, 60_000);
+});
diff --git a/tests/hf/component.test.ts b/tests/hf/component.test.ts
new file mode 100644
index 0000000..c23aa58
--- /dev/null
+++ b/tests/hf/component.test.ts
@@ -0,0 +1,71 @@
+import { describe, it, expect } from 'vitest';
+import { parseComponentSnippet, isSafeCssValue, isSafeCssVarName } from '../../src/hf/component.js';
+
+const VIGNETTE_LIKE = `<!--
+  Vignette — usage notes here.
+-->
+<div id="hf-vignette" style="position: absolute; inset: 0; pointer-events: none;"></div>
+<style>
+  #hf-vignette { background: radial-gradient(ellipse at center, transparent 45%, rgba(0,0,0,0.7) 100%); }
+</style>
+<!-- Timeline integration example: tl.fromTo("#hf-vignette", ...) -->`;
+
+const SHIMMER_LIKE = `<style>
+  .shimmer-sweep-target { position: relative; }
+</style>
+<script>
+  (function () { document.querySelectorAll(".shimmer-sweep-target").forEach(() => {}); })();
+</script>`;
+
+describe('parseComponentSnippet', () => {
+  it('splits a root-element component into html + css, stripping comments', () => {
+    const s = parseComponentSnippet(VIGNETTE_LIKE);
+    expect(s.html).toContain('hf-vignette');
+    expect(s.html).not.toContain('<style');
+    expect(s.html).not.toContain('Timeline integration');
+    expect(s.css).toContain('radial-gradient');
+    expect(s.js).toBe('');
+  });
+
+  it('extracts scripts from style+script components (no root element)', () => {
+    const s = parseComponentSnippet(SHIMMER_LIKE);
+    expect(s.html).toBe('');
+    expect(s.css).toContain('.shimmer-sweep-target');
+    expect(s.js).toContain('querySelectorAll');
+  });
+});
+
+describe('param safety', () => {
+  it('accepts normal CSS values', () => {
+    for (const ok of ['rgba(0, 0, 0, 0.7)', '45%', '120deg', '#ff8800', 'ellipse', '2.5s']) {
+      expect(isSafeCssValue(ok), ok).toBe(true);
+    }
+  });
+
+  it('rejects values that could escape a declaration or load resources', () => {
+    for (const bad of [
+      'red; background: blue',
+      '} body { display: none',
+      'url(https://evil.test/x)',
+      'expression(alert(1))',
+      '<script>',
+      'javascript:alert(1)',
+      '@import "x"',
+    ]) {
+      expect(isSafeCssValue(bad), bad).toBe(false);
+    }
+  });
+
+  it('validates custom property names', () => {
+    expect(isSafeCssVarName('--vignette-size')).toBe(true);
+    expect(isSafeCssVarName('--x')).toBe(true);
+    expect(isSafeCssVarName('color')).toBe(false);
+    expect(isSafeCssVarName('--bad;inject')).toBe(false);
+  });
+
+  it('rejects values containing raw control characters', () => {
+    expect(isSafeCssValue('a\x00b')).toBe(false);
+    expect(isSafeCssValue('a\tb')).toBe(false);
+    expect(isSafeCssValue('a\nb')).toBe(false);
+  });
+});
diff --git a/tests/hf/config-blocks.test.ts b/tests/hf/config-blocks.test.ts
new file mode 100644
index 0000000..3c7011c
--- /dev/null
+++ b/tests/hf/config-blocks.test.ts
@@ -0,0 +1,19 @@
+import { describe, it, expect } from 'vitest';
+import { defineConfig } from '../../src/config.js';
+
+describe('blocksDir / registry config', () => {
+  it('defaults blocksDir to "blocks"', () => {
+    expect(defineConfig({}).blocksDir).toBe('blocks');
+  });
+
+  it('honors a custom blocksDir', () => {
+    expect(defineConfig({ blocksDir: 'assets/hf' }).blocksDir).toBe('assets/hf');
+  });
+
+  it('passes registry.url through and defaults registry to undefined', () => {
+    expect(defineConfig({}).registry).toBeUndefined();
+    expect(defineConfig({ registry: { url: 'https://x.test/reg' } }).registry?.url).toBe(
+      'https://x.test/reg',
+    );
+  });
+});
diff --git a/tests/hf/export-hf-blocks.test.ts b/tests/hf/export-hf-blocks.test.ts
new file mode 100644
index 0000000..b839c3e
--- /dev/null
+++ b/tests/hf/export-hf-blocks.test.ts
@@ -0,0 +1,14 @@
+import { describe, it, expect } from 'vitest';
+import type { ExportOptions } from '../../src/export.js';
+import type { RenderedHfBlock } from '../../src/hf/block-filter.js';
+
+describe('ExportOptions.hfBlocks', () => {
+  it('accepts pre-rendered block sequences at compile time', () => {
+    const blocks: RenderedHfBlock[] = [{
+      name: 'logo-outro', pngDir: '/tmp/x', frameCount: 60, fps: 30,
+      startMs: 0, endMs: 2000, width: 1920, height: 1080, fit: 'cover',
+    }];
+    const opts: Partial<ExportOptions> = { hfBlocks: blocks };
+    expect(opts.hfBlocks).toHaveLength(1);
+  });
+});
diff --git a/tests/hf/hf-block-cue.test.ts b/tests/hf/hf-block-cue.test.ts
new file mode 100644
index 0000000..6a8d0b5
--- /dev/null
+++ b/tests/hf/hf-block-cue.test.ts
@@ -0,0 +1,27 @@
+import { describe, it, expect } from 'vitest';
+import type { OverlayCue } from '../../src/overlays/types.js';
+import { showOverlay } from '../../src/overlays/index.js';
+import { renderTemplate } from '../../src/overlays/templates.js';
+
+describe('HfBlockCue', () => {
+  it('is part of the OverlayCue union at compile time', () => {
+    const cue: OverlayCue = {
+      type: 'hf-block', name: 'logo-outro', fit: 'cover', holdLastFrame: true, durationMs: 2500,
+    };
+    expect(cue.type).toBe('hf-block');
+  });
+
+  it('renderTemplate rejects hf-block cues with a pointer to export-time compositing', () => {
+    expect(() => renderTemplate({ type: 'hf-block', name: 'logo-outro' })).toThrow(/export/i);
+  });
+
+  it('showOverlay is a pacing no-op during recording (waits, no page mutation)', async () => {
+    const calls: string[] = [];
+    const fakePage = {
+      evaluate: async () => { calls.push('evaluate'); },
+      waitForTimeout: async (ms: number) => { calls.push(`wait:${ms}`); },
+    };
+    await showOverlay(fakePage as never, 'outro', { type: 'hf-block', name: 'logo-outro' }, 900);
+    expect(calls).toEqual(['wait:900']);
+  });
+});
diff --git a/tests/hf/hf-component-cue.test.ts b/tests/hf/hf-component-cue.test.ts
new file mode 100644
index 0000000..0cdc3cb
--- /dev/null
+++ b/tests/hf/hf-component-cue.test.ts
@@ -0,0 +1,53 @@
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import { mkdtempSync, rmSync, mkdirSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { tmpdir } from 'node:os';
+import type { OverlayCue } from '../../src/overlays/types.js';
+import { showOverlay } from '../../src/overlays/index.js';
+import { renderTemplate } from '../../src/overlays/templates.js';
+
+describe('HfComponentCue', () => {
+  it('is part of the OverlayCue union at compile time', () => {
+    const cue: OverlayCue = { type: 'hf-component', name: 'vignette', params: { '--x': '1' } };
+    expect(cue.type).toBe('hf-component');
+  });
+
+  it('renderTemplate rejects hf-component cues with a pointer to the right path', () => {
+    expect(() => renderTemplate({ type: 'hf-component', name: 'vignette' })).toThrow(
+      /full-frame/i,
+    );
+  });
+});
+
+describe('showOverlay dispatch for hf-component', () => {
+  let tmp: string;
+  let prevEnv: string | undefined;
+  beforeEach(() => {
+    tmp = mkdtempSync(join(tmpdir(), 'argo-cue-'));
+    mkdirSync(join(tmp, 'vignette'), { recursive: true });
+    writeFileSync(join(tmp, 'vignette', 'vignette.html'), '<div id="hf-vignette"></div>');
+    prevEnv = process.env.ARGO_BLOCKS_DIR;
+    process.env.ARGO_BLOCKS_DIR = tmp;
+  });
+  afterEach(() => {
+    rmSync(tmp, { recursive: true, force: true });
+    if (prevEnv === undefined) delete process.env.ARGO_BLOCKS_DIR;
+    else process.env.ARGO_BLOCKS_DIR = prevEnv;
+  });
+
+  it('applies, waits durationMs, and removes — never touching zone machinery', async () => {
+    const calls: string[] = [];
+    const fakePage = {
+      evaluate: async () => { calls.push('evaluate'); },
+      waitForTimeout: async (ms: number) => { calls.push(`wait:${ms}`); },
+    };
+    await showOverlay(
+      fakePage as never,
+      'intro',
+      { type: 'hf-component', name: 'vignette' },
+      1200,
+    );
+    // applyComponent issues 2 evaluates (fence + inject), removeComponent 1.
+    expect(calls).toEqual(['evaluate', 'evaluate', 'wait:1200', 'evaluate']);
+  });
+});
diff --git a/tests/hf/registry-client.test.ts b/tests/hf/registry-client.test.ts
new file mode 100644
index 0000000..706ee7f
--- /dev/null
+++ b/tests/hf/registry-client.test.ts
@@ -0,0 +1,93 @@
+import { describe, it, expect } from 'vitest';
+import {
+  DEFAULT_REGISTRY_URL,
+  kindFromType,
+  fetchRegistryIndex,
+  fetchRegistryItem,
+  fetchItemFile,
+  type FetchLike,
+} from '../../src/hf/registry-client.js';
+
+function stubFetch(routes: Record<string, string>): FetchLike {
+  return async (url: string) => {
+    const body = routes[url];
+    return {
+      ok: body !== undefined,
+      status: body !== undefined ? 200 : 404,
+      text: async () => body ?? 'not found',
+    };
+  };
+}
+
+const REG = 'https://example.test/registry';
+
+describe('registry client', () => {
+  it('exposes the hyperframes default registry URL', () => {
+    expect(DEFAULT_REGISTRY_URL).toBe(
+      'https://raw.githubusercontent.com/heygen-com/hyperframes/main/registry',
+    );
+  });
+
+  it('maps registry item types to fetch kinds', () => {
+    expect(kindFromType('hyperframes:block')).toBe('blocks');
+    expect(kindFromType('hyperframes:component')).toBe('components');
+    expect(kindFromType('hyperframes:example')).toBe(null);
+    expect(kindFromType('bogus')).toBe(null);
+  });
+
+  it('fetches and parses the registry index', async () => {
+    const f = stubFetch({
+      [`${REG}/registry.json`]: JSON.stringify({
+        items: [{ name: 'vignette', type: 'hyperframes:component' }],
+      }),
+    });
+    const items = await fetchRegistryIndex(REG, f);
+    expect(items).toEqual([{ name: 'vignette', type: 'hyperframes:component' }]);
+  });
+
+  it('fetches and parses a registry item', async () => {
+    const f = stubFetch({
+      [`${REG}/components/vignette/registry-item.json`]: JSON.stringify({
+        name: 'vignette',
+        type: 'hyperframes:component',
+        files: [{ path: 'vignette.html' }],
+      }),
+    });
+    const item = await fetchRegistryItem(REG, 'components', 'vignette', f);
+    expect(item.name).toBe('vignette');
+    expect(item.files).toHaveLength(1);
+  });
+
+  it('fetches raw item file content', async () => {
+    const f = stubFetch({
+      [`${REG}/components/vignette/vignette.html`]: '<div id="hf-vignette"></div>',
+    });
+    await expect(fetchItemFile(REG, 'components', 'vignette', 'vignette.html', f)).resolves.toContain(
+      'hf-vignette',
+    );
+  });
+
+  it('throws a clear error on HTTP failure', async () => {
+    const f = stubFetch({});
+    await expect(fetchRegistryIndex(REG, f)).rejects.toThrow(/registry.*404/i);
+  });
+
+  it('throws a clear error on malformed index JSON', async () => {
+    const f = stubFetch({ [`${REG}/registry.json`]: '{"nope": true}' });
+    await expect(fetchRegistryIndex(REG, f)).rejects.toThrow(/items/i);
+  });
+
+  it('throws a clear error when registry.json returns HTML (proxy/captive portal)', async () => {
+    const f = stubFetch({ [`${REG}/registry.json`]: '<html><body>Captive Portal</body></html>' });
+    await expect(fetchRegistryIndex(REG, f)).rejects.toThrow(/malformed json/i);
+  });
+
+  it('throws a clear error when registry-item.json returns non-JSON', async () => {
+    const f = stubFetch({
+      [`${REG}/blocks/my-block/registry-item.json`]: '<html>Not Found</html>',
+    });
+    await expect(
+      fetchRegistryItem(REG, 'blocks', 'my-block', f),
+    ).rejects.toThrow(/malformed json/i);
+  });
+});
diff --git a/tests/hf/render-hf-blocks.test.ts b/tests/hf/render-hf-blocks.test.ts
new file mode 100644
index 0000000..feacc53
--- /dev/null
+++ b/tests/hf/render-hf-blocks.test.ts
@@ -0,0 +1,82 @@
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import { mkdtempSync, rmSync, mkdirSync, writeFileSync, readdirSync } from 'node:fs';
+import { join } from 'node:path';
+import { tmpdir } from 'node:os';
+import { resolveHfBlockCues, renderHfBlocks } from '../../src/hf/block-render.js';
+
+const FIXTURE_BLOCK = `<!doctype html><html><head><style>html,body{margin:0;width:320px;height:180px}</style></head>
+<body><div data-composition-id="fx"><div id="p"></div></div>
+<script>window.__timelines={fx:{duration(){return 1},pause(){},seek(t){document.getElementById('p').textContent=String(t)}}};</script>
+</body></html>`;
+
+describe('resolveHfBlockCues', () => {
+  const placements = [
+    { scene: 'intro', startMs: 0, endMs: 4000 },
+    { scene: 'outro', startMs: 10_000, endMs: 13_000 },
+  ];
+
+  it('maps cues onto placement windows with defaults', () => {
+    const manifest = [
+      { scene: 'intro', overlay: { type: 'lower-third', title: 'x' } },
+      { scene: 'outro', overlay: { type: 'hf-block', name: 'logo-outro' } },
+    ];
+    const cues = resolveHfBlockCues(manifest, placements);
+    expect(cues).toEqual([{
+      name: 'logo-outro', params: undefined, fit: 'cover', holdLastFrame: false,
+      startMs: 10_000, endMs: 13_000,
+    }]);
+  });
+
+  it('caps cue durationMs at the placement window but lets it extend for the last scene', () => {
+    const manifest = [
+      { scene: 'intro', overlay: { type: 'hf-block', name: 'a', durationMs: 99_000 } },
+      { scene: 'outro', overlay: { type: 'hf-block', name: 'b', durationMs: 20_000 } },
+    ];
+    const cues = resolveHfBlockCues(manifest, placements);
+    expect(cues[0].endMs).toBe(10_000);   // capped at next placement start
+    expect(cues[1].endMs).toBe(30_000);   // last scene: extends; ffmpeg clips at video end
+  });
+
+  it('skips scenes without placements', () => {
+    const cues = resolveHfBlockCues(
+      [{ scene: 'ghost', overlay: { type: 'hf-block', name: 'a' } }],
+      placements,
+    );
+    expect(cues).toEqual([]);
+  });
+});
+
+describe('renderHfBlocks', () => {
+  let tmp: string;
+  beforeEach(() => {
+    tmp = mkdtempSync(join(tmpdir(), 'argo-renderhf-'));
+    mkdirSync(join(tmp, 'blocks', 'fx'), { recursive: true });
+    writeFileSync(join(tmp, 'blocks', 'fx', 'fx.html'), FIXTURE_BLOCK);
+    writeFileSync(join(tmp, 'blocks', 'fx', 'registry-item.json'), JSON.stringify({
+      name: 'fx', type: 'hyperframes:block', files: [{ path: 'fx.html' }],
+      dimensions: { width: 320, height: 180 },
+    }));
+  });
+  afterEach(() => { rmSync(tmp, { recursive: true, force: true }); });
+
+  it('renders, caches, and returns composite-ready records', async () => {
+    const cues = [{ name: 'fx', params: undefined, fit: 'cover' as const, holdLastFrame: false, startMs: 500, endMs: 1500 }];
+    const r1 = await renderHfBlocks({ cues, blocksDir: join(tmp, 'blocks'), cacheDir: join(tmp, 'cache'), fps: 10 });
+    expect(r1).toHaveLength(1);
+    expect(r1[0]).toMatchObject({ name: 'fx', startMs: 500, endMs: 1500, fps: 10, width: 320, height: 180, fit: 'cover', frameCount: 10 });
+    expect(readdirSync(r1[0].pngDir).filter((f) => f.endsWith('.png'))).toHaveLength(10);
+
+    // second run: cache hit — same pngDir, no re-render (mtime of first frame unchanged)
+    const before = readdirSync(r1[0].pngDir).length;
+    const r2 = await renderHfBlocks({ cues, blocksDir: join(tmp, 'blocks'), cacheDir: join(tmp, 'cache'), fps: 10 });
+    expect(r2[0].pngDir).toBe(r1[0].pngDir);
+    expect(readdirSync(r2[0].pngDir).length).toBe(before);
+  }, 60_000);
+
+  it('throws with an install hint for a missing block', async () => {
+    await expect(renderHfBlocks({
+      cues: [{ name: 'nope', params: undefined, fit: 'cover', holdLastFrame: false, startMs: 0, endMs: 1000 }],
+      blocksDir: join(tmp, 'blocks'), cacheDir: join(tmp, 'cache'), fps: 10,
+    })).rejects.toThrow(/argo add nope/);
+  });
+});
diff --git a/tests/hf/validate-hf.test.ts b/tests/hf/validate-hf.test.ts
new file mode 100644
index 0000000..b905c02
--- /dev/null
+++ b/tests/hf/validate-hf.test.ts
@@ -0,0 +1,131 @@
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import { mkdtempSync, rmSync, mkdirSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { tmpdir } from 'node:os';
+import { validateDemo } from '../../src/validate.js';
+
+describe('validate: hf-component + accent', () => {
+  let tmp: string;
+
+  beforeEach(() => {
+    tmp = mkdtempSync(join(tmpdir(), 'argo-validate-hf-'));
+    mkdirSync(join(tmp, 'demos'), { recursive: true });
+    mkdirSync(join(tmp, 'blocks', 'vignette'), { recursive: true });
+    writeFileSync(join(tmp, 'blocks', 'vignette', 'vignette.html'), '<div></div>');
+    writeFileSync(
+      join(tmp, 'demos', 'd.demo.ts'),
+      `import { test } from '@argo-video/cli';\ntest('d', async ({ page, narration }) => { narration.mark('intro'); });\n`,
+    );
+  });
+
+  afterEach(() => {
+    rmSync(tmp, { recursive: true, force: true });
+  });
+
+  function writeManifest(overlay: unknown) {
+    const entry: Record<string, unknown> = { scene: 'intro', text: 'hi' };
+    if (overlay !== undefined) entry.overlay = overlay;
+    writeFileSync(join(tmp, 'demos', 'd.scenes.json'), JSON.stringify([entry]));
+  }
+
+  it('accepts an installed hf-component', async () => {
+    writeManifest({ type: 'hf-component', name: 'vignette' });
+    const result = await validateDemo({
+      demoName: 'd',
+      demosDir: join(tmp, 'demos'),
+      blocksDir: join(tmp, 'blocks'),
+    });
+    expect(result.errors.filter((e) => e.includes('hf-component'))).toEqual([]);
+  });
+
+  it('errors on a missing hf-component with an install hint', async () => {
+    writeManifest({ type: 'hf-component', name: 'grain-overlay' });
+    const result = await validateDemo({
+      demoName: 'd',
+      demosDir: join(tmp, 'demos'),
+      blocksDir: join(tmp, 'blocks'),
+    });
+    expect(result.errors.some((e) => /grain-overlay[\s\S]*argo add/.test(e))).toBe(true);
+  });
+
+  it('errors on an hf-component cue missing "name"', async () => {
+    writeManifest({ type: 'hf-component' });
+    const result = await validateDemo({
+      demoName: 'd',
+      demosDir: join(tmp, 'demos'),
+      blocksDir: join(tmp, 'blocks'),
+    });
+    expect(result.errors.some((e) => /hf-component.*name/i.test(e))).toBe(true);
+  });
+
+  it('errors on an hf-component name with path traversal characters', async () => {
+    writeManifest({ type: 'hf-component', name: '../evil' });
+    const result = await validateDemo({
+      demoName: 'd',
+      demosDir: join(tmp, 'demos'),
+      blocksDir: join(tmp, 'blocks'),
+    });
+    expect(result.errors.some((e) => /invalid hf-component name/.test(e))).toBe(true);
+  });
+
+  it('errors on a malformed transition accent', async () => {
+    writeManifest(undefined);
+    const result = await validateDemo({
+      demoName: 'd',
+      demosDir: join(tmp, 'demos'),
+      blocksDir: join(tmp, 'blocks'),
+      transitionAccent: 'blue',
+    });
+    expect(result.errors.some((e) => /accent.*hex/i.test(e))).toBe(true);
+  });
+
+  it('accepts a valid transition accent', async () => {
+    writeManifest(undefined);
+    const result = await validateDemo({
+      demoName: 'd',
+      demosDir: join(tmp, 'demos'),
+      blocksDir: join(tmp, 'blocks'),
+      transitionAccent: '#0EA5E9',
+    });
+    expect(result.errors.filter((e) => /accent/i.test(e))).toEqual([]);
+  });
+
+  it('accepts an installed hf-block and errors on a missing one', async () => {
+    writeManifest({ type: 'hf-block', name: 'vignette' }); // fixture dir reused — any installed name works
+    const ok = await validateDemo({
+      demoName: 'd',
+      demosDir: join(tmp, 'demos'),
+      blocksDir: join(tmp, 'blocks'),
+    });
+    expect(ok.errors.filter((e) => e.includes('hf-block'))).toEqual([]);
+
+    writeManifest({ type: 'hf-block', name: 'logo-outro' });
+    const missing = await validateDemo({
+      demoName: 'd',
+      demosDir: join(tmp, 'demos'),
+      blocksDir: join(tmp, 'blocks'),
+    });
+    expect(missing.errors.some((e) => /logo-outro[\s\S]*argo add/.test(e))).toBe(true);
+  });
+
+  it('errors on a malformed hf-block fit', async () => {
+    writeManifest({ type: 'hf-block', name: 'vignette', fit: { x: 1 } });
+    const result = await validateDemo({
+      demoName: 'd',
+      demosDir: join(tmp, 'demos'),
+      blocksDir: join(tmp, 'blocks'),
+    });
+    expect(result.errors.some((e) => /fit/.test(e))).toBe(true);
+  });
+
+  it('accepts a valid transition accent without leading #', async () => {
+    writeManifest(undefined);
+    const result = await validateDemo({
+      demoName: 'd',
+      demosDir: join(tmp, 'demos'),
+      blocksDir: join(tmp, 'blocks'),
+      transitionAccent: '0ea5e9',
+    });
+    expect(result.errors.filter((e) => /accent/i.test(e))).toEqual([]);
+  });
+});
diff --git a/tests/transitions/accent.test.ts b/tests/transitions/accent.test.ts
new file mode 100644
index 0000000..bc372d6
--- /dev/null
+++ b/tests/transitions/accent.test.ts
@@ -0,0 +1,33 @@
+import { describe, it, expect } from 'vitest';
+import { deriveAccentColors, DEFAULT_ACCENT } from '../../src/transitions/accent.js';
+
+describe('deriveAccentColors', () => {
+  it('parses 6-digit hex into normalized rgb', () => {
+    const { accent } = deriveAccentColors('#ff8000');
+    expect(accent[0]).toBeCloseTo(1.0, 5);
+    expect(accent[1]).toBeCloseTo(128 / 255, 5);
+    expect(accent[2]).toBeCloseTo(0.0, 5);
+  });
+
+  it('accepts hex without leading #', () => {
+    expect(deriveAccentColors('0ea5e9').accent).toEqual(deriveAccentColors('#0ea5e9').accent);
+  });
+
+  it('defaults to DEFAULT_ACCENT when called without args', () => {
+    expect(DEFAULT_ACCENT).toBe('#0ea5e9');
+    expect(deriveAccentColors().accent).toEqual(deriveAccentColors(DEFAULT_ACCENT).accent);
+  });
+
+  it('derives dark as 0.35x and bright as mix-toward-white 0.65', () => {
+    const { accent, accentDark, accentBright } = deriveAccentColors('#0ea5e9');
+    for (let i = 0; i < 3; i++) {
+      expect(accentDark[i]).toBeCloseTo(accent[i] * 0.35, 5);
+      expect(accentBright[i]).toBeCloseTo(accent[i] + (1 - accent[i]) * 0.65, 5);
+    }
+  });
+
+  it('throws a clear error on malformed input', () => {
+    expect(() => deriveAccentColors('#12')).toThrow(/Invalid accent color/);
+    expect(() => deriveAccentColors('red')).toThrow(/Invalid accent color/);
+  });
+});
diff --git a/tests/transitions/shader-render.test.ts b/tests/transitions/shader-render.test.ts
index 506d9dc..034e358 100644
--- a/tests/transitions/shader-render.test.ts
+++ b/tests/transitions/shader-render.test.ts
@@ -21,8 +21,13 @@ try {
 }
 
 describe('shader registry', () => {
-  it('ships exactly the v1 five shaders', () => {
-    expect(SHADER_NAMES).toEqual(['crosswarp', 'swirl', 'ripple', 'luma-mask', 'light-leak']);
+  it('ships the v1 five plus the hyperframes ports', () => {
+    expect(SHADER_NAMES).toEqual([
+      'crosswarp', 'swirl', 'ripple', 'luma-mask', 'light-leak',
+      'domain-warp', 'ridged-burn', 'thermal-distortion', 'swirl-vortex',
+      'whip-pan', 'gravitational-lens', 'cinematic-zoom', 'chromatic-split', 'flash-through-white',
+      'sdf-iris', 'ripple-waves',
+    ]);
   });
 
   it('each shader has non-empty GLSL source', () => {
@@ -191,3 +196,118 @@ describe('renderShaderTransitions', () => {
     rmSync(tmp, { recursive: true, force: true });
   }, 120000);
 });
+
+describe('computeShaderHash accent', () => {
+  let tmp: string;
+  beforeEach(() => { tmp = mkdtempSync(join(tmpdir(), 'argo-shader-accent-')); });
+  afterEach(() => { rmSync(tmp, { recursive: true, force: true }); });
+
+  it('different accent produces a different hash', async () => {
+    const { computeShaderHash } = await import('../../src/transitions/shader-render.js');
+    const a = join(tmp, 'a.png');
+    const b = join(tmp, 'b.png');
+    writeFileSync(a, Buffer.from([1, 2, 3]));
+    writeFileSync(b, Buffer.from([4, 5, 6]));
+    const h1 = computeShaderHash('crosswarp', 800, 30, 640, 360, a, b, '#0ea5e9');
+    const h2 = computeShaderHash('crosswarp', 800, 30, 640, 360, a, b, '#ff0000');
+    expect(h1).not.toBe(h2);
+  });
+
+  it('omitted accent equals DEFAULT_ACCENT hash', async () => {
+    const { computeShaderHash } = await import('../../src/transitions/shader-render.js');
+    const { DEFAULT_ACCENT } = await import('../../src/transitions/accent.js');
+    const a = join(tmp, 'a.png');
+    const b = join(tmp, 'b.png');
+    writeFileSync(a, Buffer.from([1, 2, 3]));
+    writeFileSync(b, Buffer.from([4, 5, 6]));
+    expect(computeShaderHash('crosswarp', 800, 30, 640, 360, a, b))
+      .toBe(computeShaderHash('crosswarp', 800, 30, 640, 360, a, b, DEFAULT_ACCENT));
+  });
+
+  it('accent hex case does not change the hash', async () => {
+    const { computeShaderHash } = await import('../../src/transitions/shader-render.js');
+    const a = join(tmp, 'a.png');
+    const b = join(tmp, 'b.png');
+    writeFileSync(a, Buffer.from([1, 2, 3]));
+    writeFileSync(b, Buffer.from([4, 5, 6]));
+    expect(computeShaderHash('crosswarp', 800, 30, 640, 360, a, b, '#0EA5E9'))
+      .toBe(computeShaderHash('crosswarp', 800, 30, 640, 360, a, b, '#0ea5e9'));
+  });
+});
+
+describe('buildShaderPageHtml uniforms', () => {
+  it('embeds accent values and resolution setup', async () => {
+    const { buildShaderPageHtml } = await import('../../src/transitions/shader-page.html.js');
+    const { deriveAccentColors } = await import('../../src/transitions/accent.js');
+    const html = buildShaderPageHtml(640, 360, 'void main(){}', deriveAccentColors('#ff8000'));
+    expect(html).toContain('accentDark');
+    expect(html).toContain('resolution');
+    expect(html).toContain('gl.uniform2f');
+  });
+
+  it('accepts a shader-variant config with accent at compile time', () => {
+    const cfg: TransitionConfig = {
+      type: 'shader',
+      shader: 'crosswarp',
+      durationMs: 800,
+      accent: '#ff8000',
+    };
+    expect(cfg.type).toBe('shader');
+  });
+});
+
+describe('every registered shader compiles and renders', () => {
+  let tmp: string;
+  beforeEach(() => { tmp = mkdtempSync(join(tmpdir(), 'argo-shader-smoke-')); });
+  afterEach(() => { rmSync(tmp, { recursive: true, force: true }); });
+
+  it.skipIf(!hasFfmpeg)('renders one frame per shader without GL errors', async () => {
+    const { renderShaderFrames } = await import('../../src/transitions/shader-render.js');
+    const { chromium } = await import('playwright');
+    // two tiny solid-color PNG fixtures via ffmpeg
+    const a = join(tmp, 'a.png');
+    const b = join(tmp, 'b.png');
+    await execFileP('ffmpeg', ['-y', '-f', 'lavfi', '-i', 'color=red:s=64x36', '-frames:v', '1', a]);
+    await execFileP('ffmpeg', ['-y', '-f', 'lavfi', '-i', 'color=blue:s=64x36', '-frames:v', '1', b]);
+    const browser = await chromium.launch({
+      args: ['--use-gl=angle', '--use-angle=swiftshader', '--enable-webgl', '--ignore-gpu-blacklist'],
+    });
+    try {
+      for (const shader of SHADER_NAMES) {
+        const outDir = join(tmp, shader);
+        const n = await renderShaderFrames({
+          shader, aPng: a, bPng: b, width: 64, height: 36,
+          fps: 30, durationMs: 66, outputDir: outDir, browser,
+        });
+        expect(n, shader).toBeGreaterThanOrEqual(1);
+        expect(existsSync(join(outDir, 'frame_0000.png')), shader).toBe(true);
+      }
+    } finally {
+      await browser.close();
+    }
+  }, 120_000);
+});
+
+describe('renderShaderTransitions boundary clamping', () => {
+  let tmp: string;
+  beforeEach(() => { tmp = mkdtempSync(join(tmpdir(), 'argo-shader-clamp-')); });
+  afterEach(() => { rmSync(tmp, { recursive: true, force: true }); });
+
+  it.skipIf(!hasFfmpeg)('clamps a boundary past the video end instead of failing', async () => {
+    const { renderShaderTransitions } = await import('../../src/transitions/shader-render.js');
+    // 2-second test video
+    const video = join(tmp, 'v.mp4');
+    await execFileP('ffmpeg', ['-y', '-f', 'lavfi', '-i', 'color=red:s=64x36:d=2', '-r', '30', video]);
+    // boundary at 5s — well past the 2s video (mark-drift scenario)
+    const results = await renderShaderTransitions({
+      videoPath: video,
+      boundaries: [{ boundarySec: 5, durationMs: 200 }],
+      shader: 'crosswarp',
+      width: 64, height: 36, fps: 30,
+      cacheDir: join(tmp, 'cache'),
+    });
+    expect(results).toHaveLength(1);
+    expect(results[0].frameCount).toBeGreaterThanOrEqual(1);
+    expect(existsSync(join(results[0].pngDir, 'frame_0000.png'))).toBe(true);
+  }, 120_000);
+});