feat(demo): add 10s video explainer at top of README

Deterministic HTML+GSAP composition rendered via hyperframes (HeyGen,
Apache 2.0) — Puppeteer + FFmpeg pipeline. 1920×1080, 10s, 468KB MP4.

Three scenes with crossfade transitions:
1. Title card — "Fisheye·Menu / Fitts's Law, in cascading menus."
2. Menu demo — 6-item cascading menu with a coral cursor; items
   expand toward the cursor (fisheye behaviour) using the real
   dark-theme palette from fisheye-menu.css (navy bar, purple
   hover, silver text).
3. CTA — canonical URL + GitHub attribution.

Composition source in demo-video/index.html is reproducible — edit
and re-render via `cd demo-video && npx hyperframes render`. DESIGN.md
documents the extracted palette and motion rules.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: andyed

README.md

@@ -1,5 +1,9 @@
 # Fisheye Flyout Menu
 
+<p align="center">
+  <video src="demo-video/demo.mp4" width="720" autoplay loop muted playsinline></video>
+</p>
+
 <img src="logo.svg" width="120" alt="Fisheye Flyout Menu logo" />
 
 ![Fisheye Flyout Menu demo showing Dewey Decimal taxonomy with 600 Technology expanded](screenshot.png)

demo-video/AGENTS.md

@@ -0,0 +1,58 @@
+# HyperFrames Composition Project
+
+## Skills
+
+This project uses AI agent skills for framework-specific patterns. Install them if not already present:
+
+```bash
+npx skills add heygen-com/hyperframes
+```
+
+Skills encode patterns like `window.__timelines` registration, `data-*` attribute semantics, and shader-compatible CSS rules that are not in generic web docs. Using them produces correct compositions from the start.
+
+## Commands
+
+```bash
+npx hyperframes preview      # preview in browser (studio editor)
+npx hyperframes render       # render to MP4
+npx hyperframes lint         # validate compositions (errors + warnings)
+npx hyperframes lint --json  # machine-readable output for CI
+npx hyperframes docs <topic> # reference docs in terminal
+```
+
+## Project Structure
+
+- `index.html` — main composition (root timeline)
+- `compositions/` — sub-compositions referenced via `data-composition-src`
+- `assets/` — media files (video, audio, images)
+- `meta.json` — project metadata (id, name)
+- `transcript.json` — whisper word-level transcript (if generated)
+
+## Linting — Always Run After Changes
+
+After creating or editing any `.html` composition, run the linter before considering the task complete:
+
+```bash
+npx hyperframes lint
+```
+
+Fix all errors before presenting the result.
+
+## Key Rules
+
+1. Every timed element needs `data-start`, `data-duration`, and `data-track-index`
+2. Visible timed elements **must** have `class="clip"` — the framework uses this for visibility control
+3. GSAP timelines must be paused and registered on `window.__timelines`:
+   ```js
+   window.__timelines = window.__timelines || {};
+   window.__timelines["composition-id"] = gsap.timeline({ paused: true });
+   ```
+4. Videos use `muted` with a separate `<audio>` element for the audio track
+5. Sub-compositions use `data-composition-src="compositions/file.html"`
+6. Only deterministic logic — no `Date.now()`, no `Math.random()`, no network fetches
+
+## Documentation
+
+Full docs: https://hyperframes.heygen.com/introduction
+
+Machine-readable index for AI tools: https://hyperframes.heygen.com/llms.txt

demo-video/CLAUDE.md

@@ -0,0 +1,73 @@
+# HyperFrames Composition Project
+
+## Skills — USE THESE FIRST
+
+**Always invoke the relevant skill before writing or modifying compositions.** Skills encode framework-specific patterns (e.g., `window.__timelines` registration, `data-*` attribute semantics, shader-compatible CSS rules) that are NOT in generic web docs. Skipping them produces broken compositions.
+
+| Skill                      | Command                   | When to use                                                                                       |
+| -------------------------- | ------------------------- | ------------------------------------------------------------------------------------------------- |
+| **hyperframes**            | `/hyperframes`            | Creating or editing HTML compositions, captions, TTS, audio-reactive animation, marker highlights |
+| **hyperframes-cli**        | `/hyperframes-cli`        | CLI commands: init, lint, preview, render, transcribe, tts                                        |
+| **hyperframes-registry**   | `/hyperframes-registry`   | Installing blocks and components via `hyperframes add`                                            |
+| **website-to-hyperframes** | `/website-to-hyperframes` | Capturing a URL and turning it into a video — full website-to-video pipeline                      |
+| **gsap**                   | `/gsap`                   | GSAP animations for HyperFrames — tweens, timelines, easing, performance                          |
+
+> **Skills not available?** Ask the user to run `npx hyperframes skills` and restart their
+> agent session, or install manually: `npx skills add heygen-com/hyperframes`.
+
+## Commands
+
+```bash
+npx hyperframes preview          # preview in browser (studio editor)
+npx hyperframes render       # render to MP4
+npx hyperframes lint         # validate compositions (errors + warnings)
+npx hyperframes lint --verbose  # include info-level findings
+npx hyperframes lint --json     # machine-readable output for CI
+npx hyperframes docs <topic> # reference docs in terminal
+```
+
+## Documentation
+
+**For quick reference**, use the local CLI docs command (no network required):
+
+```bash
+npx hyperframes docs <topic>
+```
+
+Topics: `data-attributes`, `gsap`, `compositions`, `rendering`, `examples`, `troubleshooting`
+
+**For full documentation**, discover pages via the machine-readable index — do NOT guess URLs:
+
+```
+https://hyperframes.heygen.com/llms.txt
+```
+
+## Project Structure
+
+- `index.html` — main composition (root timeline)
+- `compositions/` — sub-compositions referenced via `data-composition-src`
+- `meta.json` — project metadata (id, name)
+- `transcript.json` — whisper word-level transcript (if generated)
+
+## Linting — ALWAYS RUN AFTER CHANGES
+
+After creating or editing any `.html` composition, **always** run the linter before considering the task complete:
+
+```bash
+npx hyperframes lint
+```
+
+Fix all errors before presenting the result. Warnings are informational and usually safe to ignore.
+
+## Key Rules
+
+1. Every timed element needs `data-start`, `data-duration`, and `data-track-index`
+2. Elements with timing **MUST** have `class="clip"` — the framework uses this for visibility control
+3. Timelines must be paused and registered on `window.__timelines`:
+   ```js
+   window.__timelines = window.__timelines || {};
+   window.__timelines["composition-id"] = gsap.timeline({ paused: true });
+   ```
+4. Videos use `muted` with a separate `<audio>` element for the audio track
+5. Sub-compositions use `data-composition-src="compositions/file.html"` to reference other HTML files
+6. Only deterministic logic — no `Date.now()`, no `Math.random()`, no network fetches

demo-video/DESIGN.md

@@ -0,0 +1,40 @@
+# DESIGN — fisheye-menu demo video
+
+## Style Prompt
+
+Technical/editorial register. Dark canvas with navy + purple palette drawn from the fisheye-menu dark theme. Coral accent for focus/cursor, echoing the stylesheet's `--fisheye-focus-ring`. Feels like a precision engineering instrument, not a marketing reel — Fitts's Law is about economical motion, so animation is brisk, efficient, never lingering.
+
+## Colors (from fisheye-menu.css dark theme)
+
+| Token | Hex | Role |
+|---|---|---|
+| `bg` | `#0a0a1a` | Page background — slightly darker than menu for contrast |
+| `menu-bg` | `#16213e` | Menu bar / panel background (`--fisheye-bar-bg`) |
+| `menu-border` | `#0f3460` | Borders (`--fisheye-bar-border`) |
+| `text-silver` | `#c0c0c0` | Primary text (`--fisheye-bar-text`) |
+| `text-cream` | `#e6e4d2` | Display / hero text (higher contrast) |
+| `hover-purple` | `#533483` | Item hover / expanded state (`--fisheye-item-hover-bg`) |
+| `focus-coral` | `#ff9595` | Cursor, focus ring, accent highlights (`--fisheye-focus-ring`) |
+
+## Typography
+
+- Inter, weights 400 / 500 / 700 / 800
+- Title (hero): 140px / 800 / letter-spacing -0.03em
+- Subtitle: 42px / 400
+- Caption: 32px / 500
+- URL hero: 64px / 700
+
+## Motion rules
+
+- Eases: `power3.out` for hero entrances, `power2.out` for body elements, `back.out(1.8)` for playful accents, `expo.out` for container emergence. Exits use `power2.in`.
+- Scene 2 menu expansion is the signature motion — items animate at `power2.out` over 400ms (quick arrival, settle immediately). Mirrors the real CSS transition (80ms in the live demo, scaled up for video readability).
+- Cursor moves with `power2.inOut` — deliberate, not linear. Real mice accelerate and decelerate.
+
+## What NOT to Do
+
+- No rainbow / jet colormaps — palette is navy + purple + coral only.
+- No bouncy / springy eases on the menu items themselves — defeats the Fitts's Law precision vibe.
+- No hand-drawn / sketchy textures — this is precision engineering, not whimsy.
+- No centered body text paragraphs (universal muriel rule).
+- No accent lines under titles (AI-deck tell).
+- No music — silent video. The README embed plays muted by default and sound would feel promotional.

demo-video/demo.mp4

@@ -0,0 +1,9 @@
+{
+  "$schema": "https://hyperframes.heygen.com/schema/hyperframes.json",
+  "registry": "https://raw.githubusercontent.com/heygen-com/hyperframes/main/registry",
+  "paths": {
+    "blocks": "compositions",
+    "components": "compositions/components",
+    "assets": "assets"
+  }
+}