dsh-hyperframes 0.2.0 → 0.3.1

package/skills/hyperframes-registry/references/component-quality-bar.md

@@ -0,0 +1,250 @@
+# Component quality bar
+
+What a catalog component has to be for us to keep shipping it. Every criterion here comes from a
+defect found and verified on this branch, not from taste.
+
+A registry component is a motion primitive an author installs into their own composition and
+ships. The catalog page is marketing; the installed file is the product. Every criterion below is
+therefore evaluated against **the item's own `<name>.html`, mounted alone**, never against
+`demo.html` and never against the catalog page, because both of those carry scaffolding the author
+does not receive.
+
+Read this before auditing, scoring or cutting anything. It exists so several people auditing in
+parallel reach the same verdict on the same item.
+
+## The one rule
+
+> An item earns its place when the file the author installs, mounted by itself on the ground it
+> was designed for, renders the subject its name promises and moves the way its description says.
+> Anything that fails that and cannot be fixed into something no other item already does is cut.
+
+## How an audit runs
+
+Two passes, in this order. The mechanical pass is free and runs across every item in seconds; the
+visual pass costs a browser and eyes, so it is spent only on what the mechanical pass could not
+decide. A mechanical signal is a **candidate**, never a verdict.
+
+| Pass           | Cost           | Decides                                                                                  |
+| -------------- | -------------- | ---------------------------------------------------------------------------------------- |
+| **Mechanical** | grep and hash  | duplicates, missing timeline, banned hexes, empty markup, name gaps, unbounded variables |
+| **Visual**     | render and eye | renders at all, implements its description, legible, deterministic                       |
+
+`hyperframes check` is not a visual gate. It passes compositions that render nothing: a blank plot
+produces no error, no warning and no layout finding, because an empty render is a valid render. No
+criterion below may rest on `check` alone.
+
+### The mount harness
+
+Three ways to get a false verdict from a working item, all of them the harness's fault. Build the
+shell like this or the audit invents defects.
+
+1. **Two shapes of item, two ways to mount.** If the file, with HTML comments stripped, contains a
+   `data-composition-id`, it is a sub-composition: mount it with
+   `data-composition-src="./<name>.html"` on a clip. If it does not, it is a snippet: paste it
+   inline inside a `class="clip"` div. Inlining a sub-composition nests a document in a document
+   and renders black, which reads exactly like a dead item.
+2. **Use the item's own ground.** Take the background off its `demo.html` body rule. A snippet
+   whose ink defaults to `#18181b` is a 16:1 headline on its own `#f7f7f8` and an invisible 1.5:1
+   smudge on a dark stage. The stage is not evidence.
+3. **Load GSAP and register a paused root timeline**, then snapshot with
+   `hyperframes snapshot . --at 0.05,1.2,2.5,4.0 --no-end` and read the contact sheet.
+
+An item whose own `data-duration` is shorter than the shell's will be blank in the last frames.
+That is arithmetic, not a defect.
+
+## Fatal, cut the item
+
+Fatal means there is nothing worth keeping underneath the defect: no edit short of writing a
+different item fixes it, or the fix produces something the catalog already ships. Cite the named
+evidence; a fatal verdict without it does not count.
+
+**F1. Does not implement its own description.** The markup contains no trace of the subject the
+item is named and described for. Not "renders badly", but "the thing is absent from the file".
+`ecosystem-constellation`, `hero-device-assemble` and `terminal-to-browser-deploy` are the same
+file holding empty card divs with different headings.
+_Check:_ read the markup, then swap the name for any other item's name. If nothing in the file
+would have to change, the name is a label on a generic shell.
+_Evidence:_ the named subject has no element (no nodes in a constellation, no terminal in a
+terminal deploy).
+
+**F2. Redundant duplicate.** Same **motion fingerprint** and same **markup skeleton** as another
+item that survives. Fingerprint is the gsap call list with selectors neutralised, keeping props,
+durations and eases; skeleton is the tag sequence with classes and text stripped. One wipe
+currently ships eight times with the same properties, durations and easings; one word-stagger
+ships seven times.
+_Evidence:_ both hashes match a sibling, and the sibling wins the tie-break below.
+
+**F3. Renders nothing.** Frames are blank, or the named subject never appears, with the item
+mounted correctly on its own ground and its recipe applied.
+_Evidence:_ four blank frames plus the cause, in the item rather than the harness: a missing
+sibling asset, a `ReferenceError` in the console, a subject that never enters the viewport. A
+frame-capture artifact that renders correctly live is a false alarm, so confirm on a real page
+before recording it.
+
+**F4. The description is a different item.** The frames show the promised event never happening: a
+wipe that never reveals its second panel, a chart that draws no series. Not a wording gap.
+
+**F5. Cannot be made seekable.** Frame N genuinely depends on frame N-1 with no closed form and no
+bounded replay, and making it seekable would make it a different effect. Rare. Most accumulators
+have a trivial rewrite, so reach for this only after establishing there is none; a seeded,
+index-derived replacement for `Math.random()` is X7, not F5.
+_Evidence:_ two snapshots of the same timestamp reached by different seek paths differ.
+
+## Fixable, keep and repair
+
+Real defects, but the item has a reason to exist that nothing else covers and the repair is
+bounded. Log the specific fix, never "needs polish".
+
+**X1. No timeline of its own.** No `__timelines` registration, so the installed artifact renders a
+still frame while the catalog page looks fine, because the generator transplants the demo's
+timeline into the preview. 97 of the 213 new components are in this state.
+_Repair:_ fold the trailing `Timeline integration:` recipe into a real `<script>` that builds a
+paused timeline and registers it. Roughly 10 to 15 minutes for a single-element item.
+_Escalates to fatal_ only when there is no motion anywhere to fold in, which usually means F1 too.
+
+**X2. Name claims a technique the code lacks.** Grep the code region, never the doc header: the
+header's prose is full of the exact words you are looking for, and will report a match on an item
+that has none.
+| Name pattern | Must contain |
+| -------------------------------- | -------------------------------------------------- |
+| `spring-*` | `elastic`, `back.`, `bounce` or a custom spring ease |
+| `mask-*`, `*-mask*` | `mask` or `clip-path` |
+| `frosted*`, `*glass*` | `backdrop-filter` |
+| `*3d*`, `*depth*`, `*orbit*`, `*camera*` | `perspective`, `rotateX`, `rotateY`, `translateZ` |
+| `*-draw`, `*-trace`, `*stroke*` | `stroke-dash` or `pathLength` |
+_Repair:_ add the technique, or rename the item. Renaming is often the honest fix.
+
+**X3. Illegible.** At 1920x1080 on its own ground: text under 4.5:1, or a subject whose smallest
+meaningful feature is under about 24px.
+_Repair:_ one value step, per `placeholder-material.md`. Text never sits below L1.
+
+**X4. Placeholder gradients.** The purple and blue palette standing in for content.
+_Repair:_ the monochrome ramp. Already done across the catalog, so a new instance is a regression,
+not a legacy defect.
+
+**X5. Hardcoded ink, no theme token.** A literal colour on the item's own text or subject with no
+`var(--...)` fallback chain, so it disappears when an author drops it on the opposite theme.
+_Repair:_ route it through the theme token with the literal as fallback.
+
+**X6. No markup of its own.** The file is a `<style>` and a `<script>` and nothing else, so
+mounting it renders an empty box.
+_Repair:_ ship sample markup, or declare it an attachment snippet in `registry-item.json` and give
+the demo a host element.
+
+**X7. Unseeded randomness.** Scatter derived from `Math.random()` rather than the element index.
+_Repair:_ derive from the index.
+
+**X8. Declared bounds it cannot honour.** A number variable with no `min`/`max`, so the control
+offers values the item cannot express, or a default it can never return to.
+_Repair:_ declare real bounds, or use a numeric field instead of a slider.
+
+## Duplicates, which one survives
+
+A group is the set of items sharing both hashes from F2. Exactly one survives, chosen in order:
+
+1. **The one whose name describes what the shared motion actually does.** A group where one member
+   is a directional wipe and the rest borrowed it keeps the directional wipe.
+2. **Then the one with subject-specific markup.** More elements that only make sense for that
+   name, not more elements.
+3. **Then the one already on `origin/main`.** Removing a shipped item breaks installs.
+4. **Never a member whose name claims something the shared implementation does not do.**
+   `frosted-glass-wipe` has no `backdrop-filter`, `spring-scale-in` has no spring, `mask-reveal-up`
+   has no mask, so none of those three is the survivor. Such a member is F2 and X2 at once, and X2
+   cannot be fixed without breaking the group. If no member is honest, keep the plainest name.
+
+**If every member of a group fails F1, the group is cut entire.** Do not preserve a survivor to
+soften the count. Twelve names on one empty card shell is one bad item, not twelve, and keeping one
+of them keeps the bad item.
+
+Same motion with genuinely different subjects is not a duplicate. A bar chart, a line chart and a
+dashboard populate can share a stagger; the subject is the item.
+
+## Never cut
+
+Protection is per criterion, not blanket. A protected item still answers every other row.
+
+**N1. Load-bearing colour** is exempt from X4 only. `chromatic-aberration-wipe` (the RGB split is
+the effect), `confetti` (multi-hue is the celebration), `matrix-decode` (green is its identity),
+`mesh-gradient-bg` (the gradient is the subject), `multi-device-splay`. `us-map`'s gradient is a
+sequential choropleth scale, which is colour carrying data.
+
+**N2. Real product depiction** is exempt from X4 and F1. A Figma logo inside a Figma mock is not
+slop; the HyperFrames wordmark in `logo-brand-close` is the subject. Judge the placeholder content,
+not the depicted product.
+
+**N3. Deliberate static** is exempt from X1. An item whose description promises no motion is not
+failing X1. A style snippet or a passive overlay is allowed to sit still.
+
+**N4. Environment sets** are exempt from F3. An item that is a backdrop rather than a shot is not
+failing F3 for being calm. Measured PSNR between frames separates the two: sets score 45 or higher,
+things that genuinely run score 17 to 24. Judge against the description.
+
+**N5. A rest state that is the recipe's `from` state** is exempt from F3. `confetti` ships
+`.particle` spans sitting at opacity 0 until the timeline fans them out. Still is not dead.
+
+**N6. Attachment snippets** are exempt from F3. A text splitter has no markup by design. Grade X6.
+
+**N7. The 36 items already on `origin/main`** are out of audit scope.
+
+## Mechanical first pass
+
+| Signal              | How                                                                                   | Maps to |
+| ------------------- | ------------------------------------------------------------------------------------- | ------- |
+| No timeline         | `grep -L __timelines` over each composition                                           | X1      |
+| Duplicate           | motion fingerprint AND markup skeleton hashes, matched pairwise                       | F2      |
+| Empty shell         | markup skeleton matches an unrelated item, or is `<h3>` + `<p>` + generic panels only | F1      |
+| No markup at all    | element count of the comment-, style- and script-stripped file is 0                   | X6      |
+| Placeholder palette | grep the six banned hexes                                                             | X4      |
+| Name gap            | the X2 table, grepped over the code region only                                       | X2      |
+| Unbounded number    | read `min`/`max` in `registry-item.json`                                              | X8      |
+| Non-determinism     | grep `Math.random`, `Date.now`, `performance.now`, `requestAnimationFrame`            | X7, F5  |
+
+## Visual pass, required for a verdict
+
+Render at least four frames across the duration from the **composition**, not the demo, mounted per
+the harness rules above, and look at them. Then, for anything not scoring clean, confirm on the
+real catalog page before recording it.
+
+Record per item: the criteria it fails, the evidence you saw, and fatal or fixable. An unviewed
+item is not a pass.
+
+## Calibration
+
+Ten items scored with this rubric, frames rendered and looked at. Three of them corrected the
+rubric rather than the other way round.
+
+| Item                         | Expected   | Frames actually showed                                                                                                    | Verdict            |
+| ---------------------------- | ---------- | ------------------------------------------------------------------------------------------------------------------------- | ------------------ |
+| `ecosystem-constellation`    | fatal      | Sidebar with three pill buttons and three empty white panels. No nodes, no edges. Identical at all four timestamps.       | **Cut** F1, F2, F4 |
+| `terminal-to-browser-deploy` | fatal      | Pixel-identical to the above, only the `<h3>` and one subtitle differ. No terminal, no browser.                           | **Cut** F1, F2, F4 |
+| `frosted-glass-wipe`         | fatal      | One card reading "Before", static, forever; the "After" panel stays clipped. Recipe byte-identical to `directional-wipe`. | **Cut** F2, F4, X2 |
+| `char-slam-explode`          | pass       | Letters scattered at 0.05s, assembled into "Impact" by 1.2s, held. Real per-character motion.                             | **Keep**           |
+| `echo-trail`                 | pass       | Card travels left to right with a decaying blurred echo trail behind it. Legible on its own light ground.                 | **Keep**           |
+| `logo-brand-close`           | pass       | "H" resolves into the full wordmark, tagline and URL land after it. Staged, legible.                                      | **Keep**           |
+| `blur-in`                    | borderline | Still, but the still is the correct rest state: legible headline, unique implementation, theme-token ink.                 | **Keep**, X1       |
+| `spring-scale-in`            | borderline | Legible on its own `#f7f7f8`. Ease is `power3.out`, no spring anywhere. Shares its recipe with six others.                | **Cut** F2, X2     |
+| `confetti`                   | borderline | Card and mesh, no particles visible. Source ships `.particle` spans the recipe fans out from opacity 0.                   | **Keep**, X1       |
+| `bottom-up-letters`          | borderline | Four blank frames. The file is a splitter with no markup at all.                                                          | **Keep**, X6       |
+
+Three corrections the calibration forced, all of them false cuts:
+
+- `spring-scale-in` first scored X3 at roughly 1.5:1. That was the harness's dark stage, not the
+  item. Hence "use the item's own ground".
+- `confetti` first scored F3. Its rest state is its recipe's `from` state. Hence N5.
+- `char-slam-explode` first scored F3 with four black frames. It is a sub-composition and was being
+  inlined. Hence the two-shapes rule.
+
+A rubric that cuts a working item is wrong even when the verdict is convenient.
+
+## Checklist
+
+Per item, in order. Stop at the first fatal.
+
+- [ ] Mounted the right way for its shape, on its own ground, with GSAP and a paused root.
+- [ ] F1: the markup contains the named subject.
+- [ ] F2: motion fingerprint and markup skeleton are not both shared with a survivor.
+- [ ] F3: it renders something with the recipe applied, or it is protected by N3 to N6.
+- [ ] F4: the frames show the event the description promises.
+- [ ] F5: frame N is computed from N.
+- [ ] X1 through X8 logged with the specific fix.
+- [ ] Verdict cites the evidence the criterion names, not an impression.

package/skills/hyperframes-registry/references/contributing.md

@@ -0,0 +1,174 @@
+# Contributing a Block or Component to the Registry
+
+Guide the user from idea to merged PR for a new registry block or component.
+
+## Workflow
+
+```
+1. Clarify → 2. Scaffold → 3. Build → 4. Validate → 5. Preview → 6. Ship
+```
+
+### Step 1: Clarify
+
+Ask what they're building. The registry has two item types:
+
+- **Block** (`registry/blocks/`, type `hyperframes:block`) — a full standalone composition with fixed dimensions and duration. Caption styles, VFX effects, title cards, lower thirds.
+- **Component** (`registry/components/`, type `hyperframes:component`) — a reusable snippet with no fixed dimensions or duration. CSS effects, text treatments, overlays that adapt to any composition size.
+
+Then ask:
+
+- One-sentence description of the effect
+- Visual reference (URL, screenshot, or description)
+- Who uses this and when?
+
+### Step 2: Scaffold
+
+Create the registry structure:
+
+**For blocks:**
+
+```
+registry/blocks/{block-name}/
+  {block-name}.html
+  registry-item.json
+```
+
+**For components:**
+
+```
+registry/components/{component-name}/
+  {component-name}.html
+  registry-item.json
+```
+
+**Naming convention:**
+
+| Item name        | ID prefix | Example IDs            |
+| ---------------- | --------- | ---------------------- |
+| `cap-hormozi`    | `hz`      | `hz-cg-0`, `hz-cw-3`   |
+| `cap-typewriter` | `tw`      | `tw-cg-0`, `tw-ch-0-5` |
+| `vfx-chrome`     | `vc`      | `vc-canvas`            |
+
+Use a 2-3 letter prefix. ALL element IDs must use this prefix to avoid collisions in sub-compositions.
+
+**registry-item.json** — use the canonical templates in [templates.md](templates.md) (block and component variants, both with all required fields).
+
+### Step 3: Build
+
+Apply the correct template based on type. See [templates.md](templates.md) for copy-paste starters.
+
+#### Caption blocks
+
+**Non-negotiable caption rules:**
+
+- Font: **96px minimum** for proportional fonts. **64-72px acceptable for monospace** (wider characters need less size).
+- Readability: `-webkit-text-stroke: 2-3px` OR multi-layer `text-shadow`
+- Overflow: call `window.__hyperframes.fitTextFontSize()` on every group
+- Karaoke: highlight active word via `tl.to(wordEl, { color/scale }, WORDS[wi].start)`
+- Hard kill: `tl.set(groupEl, { opacity: 0, visibility: "hidden" }, g.end)` on EVERY group
+- **Never use `tl.from(el, { opacity: 0 })` at the same position as `tl.set(el, { opacity: 1 })`** — the from clobbers the set. Use `tl.to` instead.
+
+**Per-character animation** (typewriter, scramble):
+
+- Wrap each character in `<span>` with ID `{prefix}-ch-{group}-{char}`
+- Stagger via `tl.set` at computed intervals from word timestamps
+- Cursors/decorative elements: use `tl.set` at intervals — NOT CSS animation (not seekable)
+
+**Positioning variants:**
+
+- Centered: `display: flex; align-items: center; justify-content: center;`
+- Lower-third: `position: absolute; bottom: 100px; left: 0; width: 100%; text-align: center;`
+- Left-aligned: `position: absolute; bottom: 100px; left: 120px; text-align: left;`
+
+#### VFX blocks (Three.js)
+
+- Use `three@0.147.0` from CDN (global script)
+- `tl.eventCallback("onUpdate", renderScene); renderScene();` — NO requestAnimationFrame
+- State proxy pattern: GSAP animates plain JS object, render function reads it
+- Seeded PRNG (`mulberry32`) for randomness
+
+#### All types
+
+- **Placeholder content is monochrome** — read
+  [placeholder-material.md](placeholder-material.md) before choosing a single colour. Stand-in
+  screens, images, cards, avatars, logos and chart series use four alpha steps of the
+  composition's ink; accent marks one element and never a placeholder.
+- `data-composition-id` MUST match `window.__timelines["id"]`
+- All element IDs prefixed with block abbreviation
+- `gsap.timeline({ paused: true })` — always paused
+- No `Math.random()`, no `Date.now()`
+
+### Step 4: Validate
+
+```bash
+hyperframes lint                    # 0 errors required
+hyperframes check --no-contrast  # 0 console errors required
+```
+
+### Step 5: Preview
+
+```bash
+# Render preview video
+hyperframes render -o preview.mp4
+
+# Snapshot for visual QA
+hyperframes snapshot --at "1.0,3.0,5.0,7.0"
+
+# Publish to hyperframes.dev for review
+npx hyperframes publish
+```
+
+**Catalog preview image** — The catalog card uses a PNG at `docs/images/catalog/{kind}/{name}.png` (where `{kind}` is `blocks` or `components`). Generate it from a snapshot, then:
+
+- **HeyGen internal contributors:** run `scripts/upload-docs-images.sh` (requires AWS profile `engineering-767398024897`)
+- **External contributors:** attach the preview MP4 to your PR description. A maintainer will generate and upload the catalog image before merging.
+
+### Step 6: Ship
+
+**All steps are required. Missing any one produces a broken catalog entry.**
+
+`{kind}` is `blocks` or `components` depending on what you built in Step 1.
+
+```bash
+# 1. Create branch
+git checkout -b feat/registry-{name}
+
+# 2. Format HTML
+npx oxfmt registry/{kind}/{name}/*.html
+
+# 3. Regenerate registry/registry.json from the item directories.
+#    Do not hand-edit it: an entry added by hand survives until the next
+#    regeneration and then vanishes, and one left behind for a directory that
+#    no longer exists is worse, because `hyperframes add <name>` resolves the
+#    name and then fails on missing files.
+npx tsx scripts/generate-registry-items.ts
+
+# 4. Generate catalog docs page
+npx tsx scripts/generate-catalog-pages.ts
+
+# 5. Publish to hyperframes.dev so reviewers can preview
+npx hyperframes publish
+
+# 6. Stage everything
+git add registry/{kind}/{name}/ registry/registry.json docs/catalog/
+
+# 7. Commit
+git commit -m "feat(registry): add {name} — {one sentence}"
+
+# 8. Push and open PR with hyperframes.dev link
+git push origin feat/registry-{name}
+gh pr create --title "feat(registry): {name}" --body "preview: {hyperframes.dev-url}"
+```
+
+**If you don't have a GitHub account:** you need one to open a PR. Sign up at https://github.com/signup, then run `gh auth login`.
+
+## Quality Gate
+
+- [ ] `hyperframes lint` → 0 errors
+- [ ] `hyperframes check` → 0 console errors
+- [ ] `npx oxfmt --check` passes
+- [ ] `registry/registry.json` updated with new entry
+- [ ] `scripts/generate-catalog-pages.ts` run (docs page generated)
+- [ ] `npx hyperframes publish` run (claim your project URL)
+- [ ] Preview MP4 attached to PR (external) or catalog PNG uploaded (internal)
+- [ ] All IDs unique and prefixed

package/skills/hyperframes-registry/references/discovery.md

@@ -1,8 +1,24 @@
-# Registry Discovery
+# Registry discovery
 
-## Reading the registry manifest
+## Use the catalog command first
 
-The top-level `registry.json` lists all available items:
+```bash
+npx hyperframes catalog
+npx hyperframes catalog --type block
+npx hyperframes catalog --type component
+npx hyperframes catalog --type block --tag social
+npx hyperframes catalog --json
+npx hyperframes catalog --human-friendly
+```
+
+- Default output is a readable table. It does not install anything.
+- `--type` accepts `block` or `component`; `--tag` may narrow either result.
+- `--json` is the deterministic agent and CI surface. Select a name, then run `npx hyperframes add <name>`.
+- `--human-friendly` opens a picker and installs the selected item immediately.
+
+## Read the registry manifest as a fallback
+
+When the CLI is unavailable, the top-level `registry.json` lists all available items:
 
 ```bash
 curl -s https://raw.githubusercontent.com/heygen-com/hyperframes/main/registry/registry.json
@@ -38,16 +54,178 @@ Where `<type-dir>` is `examples`, `blocks`, or `components`.
 
 ### Blocks
 
-| Name         | Description                                     | Tags                            |
-| ------------ | ----------------------------------------------- | ------------------------------- |
-| `data-chart` | Animated bar + line chart with staggered reveal | data, chart, statistics         |
-| `flowchart`  | Decision tree with SVG connectors and cursor    | diagram, flowchart, interactive |
-| `logo-outro` | Cinematic logo reveal with tagline              | branding, outro, logo           |
+For an always-current list run `npx hyperframes catalog --type block`. The tables below group the 97 blocks by category. **Block name ≠ shader name**: shader-transition blocks (e.g. `domain-warp-dissolve`) wrap a HyperShader runtime whose internal name omits the `-dissolve`/`-warp` suffix — see the showcase HTML installed alongside the block for the canonical name.
+
+#### Shader transitions (14)
+
+Single-shader blocks; each installs one HyperShader runtime + a showcase composition. Use ≤2 per video.
+
+| Name                     | Description                                                              |
+| ------------------------ | ------------------------------------------------------------------------ |
+| `chromatic-radial-split` | Chromatic aberration radial split                                        |
+| `cinematic-zoom`         | Dramatic zoom blur                                                       |
+| `cross-warp-morph`       | Cross-warped morphing                                                    |
+| `domain-warp-dissolve`   | Fractal noise domain warping                                             |
+| `flash-through-white`    | White flash crossfade (rarely a neutral default — see SKILL.md guidance) |
+| `glitch`                 | Digital glitch artifacts                                                 |
+| `gravitational-lens`     | Gravitational lensing distortion                                         |
+| `light-leak`             | Cinematic light leak overlay                                             |
+| `ridged-burn`            | Ridged turbulence burn                                                   |
+| `ripple-waves`           | Concentric ripple wave distortion                                        |
+| `sdf-iris`               | Signed-distance-field iris reveal                                        |
+| `swirl-vortex`           | Swirling vortex distortion                                               |
+| `thermal-distortion`     | Heat-haze thermal distortion                                             |
+| `whip-pan`               | Fast camera whip-pan                                                     |
+
+#### Transition galleries (13)
+
+Showcase compositions grouping multiple CSS / GSAP transition styles by family. Use as reference for picking a CSS scene transition; not meant to embed as-is.
+
+| Name                      | Description                         |
+| ------------------------- | ----------------------------------- |
+| `transitions-3d`          | 3D perspective flip and rotate      |
+| `transitions-blur`        | Blur-based scene transitions        |
+| `transitions-cover`       | Cover / uncover slide               |
+| `transitions-destruction` | Destructive break-apart             |
+| `transitions-dissolve`    | Dissolve and fade                   |
+| `transitions-distortion`  | Warp and distortion                 |
+| `transitions-grid`        | Grid-based tile                     |
+| `transitions-light`       | Light-based glow and flash          |
+| `transitions-mechanical`  | Mechanical shutter and iris         |
+| `transitions-other`       | Misc creative (VHS, gravity, morph) |
+| `transitions-push`        | Push and slide                      |
+| `transitions-radial`      | Radial wipe and reveal              |
+| `transitions-scale`       | Scale and zoom                      |
+
+#### Liquid Glass (7)
+
+WebGPU + html-in-canvas frosted-glass surfaces. **Require Brave / Chrome canary** with WebGPU enabled — set `PRODUCER_HEADLESS_SHELL_PATH` to point at the browser; engine auto-passes `--enable-unsafe-webgpu`. See `/hyperframes-animation` → `adapters/typegpu.md`.
+
+| Name                          | Description                                                                             |
+| ----------------------------- | --------------------------------------------------------------------------------------- |
+| `ios26-liquid-glass`          | 3D iPhone (GLTF) + iOS 26 home screen, glass app icons, shader wallpaper, notifications |
+| `macos-tahoe-liquid-glass`    | 3D MacBook (GLTF) + macOS Tahoe-style desktop, glass menu bar, Finder, dock             |
+| `liquid-glass-widgets`        | Frosted stat cards, showcase panel, pill chips over aurora shader                       |
+| `liquid-glass-notification`   | Frosted notification cards floating over aurora shader                                  |
+| `liquid-glass-context-menu`   | Frosted context-menu panel drifting over aurora shader                                  |
+| `liquid-glass-media-controls` | Frosted media-control panels spreading over aurora shader                               |
+| `vfx-liquid-glass`            | Bare VFX composition shell for liquid-glass effects                                     |
+
+#### VFX (6)
+
+HTML-in-canvas + WebGL composition blocks. See `/hyperframes-animation` → `adapters/three.md` and `adapters/html-in-canvas-patterns.md` for the underlying APIs.
+
+| Name                    | Description                                                                                             |
+| ----------------------- | ------------------------------------------------------------------------------------------------------- |
+| `vfx-iphone-device`     | GLTF iPhone 15 Pro Max + MacBook Pro with live HTML-in-canvas screens, glass-lens morph, 360° turntable |
+| `vfx-liquid-background` | Organic liquid sim — vertex displacement on subdivided plane, HTML floats above                         |
+| `vfx-magnetic`          | VFX shell (magnetic field-line treatment)                                                               |
+| `vfx-portal`            | VFX shell (portal reveal)                                                                               |
+| `vfx-shatter`           | VFX shell (shatter into fragments)                                                                      |
+| `vfx-text-cursor`       | Cursor glow + chromatic shadow rays + spectral edges on a black stage                                   |
+
+#### Showcases (6)
+
+Story-driven showcase compositions — narrated YouTube-style inserts. Most include bundled SFX.
+
+| Name                       | Description                                                       |
+| -------------------------- | ----------------------------------------------------------------- |
+| `app-showcase`             | Three floating smartphone screens, fitness app product showcase   |
+| `apple-money-count`        | Counter $0 → $10,000, green flash, money-icon burst, SFX          |
+| `blue-sweater-intro-video` | Warm AI-creator intro resolving into an X follow card             |
+| `north-korea-locked-down`  | Map zoom with red scribble circle, locked-down pop-up label       |
+| `nyc-paris-flight`         | Map animation, plane NYC → Paris, marker circle, landing pop, SFX |
+| `vpn-youtube-spot`         | App-store scroll, VPN install flow, SFX                           |
+
+#### Maps + data viz (8)
+
+D3 + GSAP animated geographies and charts.
+
+| Name                               | Description                                                                                        |
+| ---------------------------------- | -------------------------------------------------------------------------------------------------- |
+| `us-map`                           | US choropleth, staggered state reveals, value labels, gradient legend                              |
+| `us-map-bubble`                    | US bubble map — proportional city markers, callouts, connection lines                              |
+| `us-map-flow`                      | US flow map — animated origin-destination arcs                                                     |
+| `us-map-hex`                       | US hex-grid map — each state as equal-weight hex with data fill                                    |
+| `spain-map`                        | Spain choropleth by autonomous community — D3 conic conformal                                      |
+| `world-map`                        | World choropleth + rotating globe inset, D3 Natural Earth                                          |
+| `data-chart`                       | Animated bar + line chart, staggered reveal, NYT-style typography                                  |
+| `flowchart` / `flowchart-vertical` | Decision tree, SVG connectors, sticky-note nodes, cursor + typing correction (vertical = portrait) |
+
+#### Social overlays (7)
+
+Platform-recognizable UI overlays. Stamp on top of a beat or use as a beat closer.
+
+| Name                 | Description                                      |
+| -------------------- | ------------------------------------------------ |
+| `instagram-follow`   | Profile card + follow button                     |
+| `tiktok-follow`      | Profile card + follow button                     |
+| `yt-lower-third`     | YouTube subscribe lower third with avatar        |
+| `x-post`             | X/Twitter post card with engagement metrics      |
+| `reddit-post`        | Post card with upvotes and comments              |
+| `spotify-card`       | Now-playing card with album art and progress bar |
+| `macos-notification` | macOS-style banner with app icon and message     |
+
+#### Branding + 3D UI (2)
+
+| Name           | Description                                                         |
+| -------------- | ------------------------------------------------------------------- |
+| `logo-outro`   | Piece-by-piece logo assembly, glow bloom, tagline fade-in, URL pill |
+| `ui-3d-reveal` | Perspective 3D reveal for UI elements                               |
+
+#### Code snippets (24)
+
+A code/terminal window that **types a code or shell session per-character**. Theme = visual chrome only; structure, wiring, and install are identical across all 24 — pick one by name, wire it like any block (`data-composition-id` + `data-start` + `data-track-index`, see `wiring-blocks.md`). Two chrome families:
+
+**VS Code workbench (12)** — full editor chrome (activity bar, sidebar, tabs, integrated terminal, status bar). Theme variants: `code-snippet-dark-2026`, `code-snippet-dark-modern`, `code-snippet-dark-plus`, `code-snippet-light-2026`, `code-snippet-light-modern`, `code-snippet-light-plus`, `code-snippet-high-contrast`, `code-snippet-high-contrast-light`, `code-snippet-monokai`, `code-snippet-solarized-light`, `code-snippet-visual-studio-dark`, `code-snippet-visual-studio-light`.
+
+**Apple Terminal (12)** — macOS Terminal.app window typing a shell session. Profile = window colors:
+
+| Name                                         | Look                                     |
+| -------------------------------------------- | ---------------------------------------- |
+| `code-snippet-apple-terminal-basic`          | White bg, black text                     |
+| `code-snippet-apple-terminal-clear-dark`     | Semi-transparent dark bg                 |
+| `code-snippet-apple-terminal-clear-light`    | Semi-transparent light bg                |
+| `code-snippet-apple-terminal-grass`          | Black bg, green text                     |
+| `code-snippet-apple-terminal-homebrew`       | Black bg, bright green text, lime cursor |
+| `code-snippet-apple-terminal-man-page`       | Pale yellow bg, black text               |
+| `code-snippet-apple-terminal-novel`          | Warm parchment bg, dark brown text       |
+| `code-snippet-apple-terminal-ocean`          | Deep blue bg, white text                 |
+| `code-snippet-apple-terminal-pro`            | Black bg, grey text, lime cursor         |
+| `code-snippet-apple-terminal-red-sands`      | Deep red bg, sandy text                  |
+| `code-snippet-apple-terminal-silver-aerogel` | Dark grey bg, white text                 |
+| `code-snippet-apple-terminal-solid-colors`   | Deep purple bg, white text               |
+
+#### Code Animations (9)
+
+The richer, motion-first counterpart to the static `code-snippet-*` window themes above: each is a self-contained 1920×1080 block (~5–8s) with a paused, deterministic GSAP timeline that _animates_ code — typing, diffing, morphing, spotlighting, or GPU hero reveals — rather than typing a fixed snippet inside editor/terminal chrome. **Reuse-first**: `npx hyperframes add <name>`, then customize the baked code/diff content in place; hand-author only when no block covers the motion you need.
+
+**DOM / text reveal (6):**
+
+| Name                  | Description                                                                                                                |
+| --------------------- | -------------------------------------------------------------------------------------------------------------------------- |
+| `code-typing`         | Token-streamed typing reveal, caret tracks the frontier (no CSS animation) — live-coding on screen                         |
+| `code-diff`           | An edit shown as a colored diff: removed lines collapse red, added expand green — before/after at line level               |
+| `code-morph`          | One snippet transforms into another, tokens glide between positions (Shiki Magic Move) — a refactor / one state to another |
+| `code-highlight`      | A highlight band sweeps a target line while surrounding context dims — spotlight one line                                  |
+| `code-scroll`         | Camera scrolls a long file to center + spotlight a target line — walk through a real module                                |
+| `code-snippet-flight` | Discrete snippets fly in from the side and assemble into a stacked program (block-level FLIP)                              |
+
+**GPU / WebGL hero reveals (3):** heavier, for a title-card / hero code moment.
+
+| Name                     | Description                                                                                                     |
+| ------------------------ | --------------------------------------------------------------------------------------------------------------- |
+| `code-3d-extrude`        | Syntax-highlighted code on a lit beveled 3D slab that rotates through real space and settles (true WebGL depth) |
+| `code-shader-dissolve`   | Code resolves out of seeded noise with a chromatic dissolve front + edge glow, then holds crisp                 |
+| `code-particle-assemble` | Thousands of GPU points fly to the exact glyph pixels and resolve into readable syntax-highlighted code         |
 
 ### Components
 
-| Name                 | Description                             | Tags                             |
-| -------------------- | --------------------------------------- | -------------------------------- |
-| `grain-overlay`      | Animated film grain texture overlay     | texture, grain, overlay, film    |
-| `shimmer-sweep`      | CSS gradient light sweep for AI accents | text, shimmer, highlight, effect |
-| `grid-pixelate-wipe` | Grid dissolve transition between scenes | transition, wipe, grid, pixelate |
+| Name                 | Description                                                                                               | Tags                                             |
+| -------------------- | --------------------------------------------------------------------------------------------------------- | ------------------------------------------------ |
+| `grain-overlay`      | Animated film grain texture overlay                                                                       | texture, grain, overlay, film                    |
+| `shimmer-sweep`      | CSS gradient light sweep for AI accents                                                                   | text, shimmer, highlight, effect                 |
+| `morph-text`         | Gooey text morph cycling an editable word list (SVG threshold + GSAP blur)                                | text, text-effect, typography, morph, gooey      |
+| `grid-pixelate-wipe` | Grid dissolve transition between scenes                                                                   | transition, wipe, grid, pixelate                 |
+| `parallax-zoom`      | Center card scales up to fill the frame while siblings parallax outward (single `--pz-progress` 0→1)      | transition, zoom, parallax, grid, hero           |
+| `parallax-unzoom`    | Reverse of `parallax-zoom` — focus card shrinks from full frame as siblings parallax in (`--pu-progress`) | transition, reveal, unzoom, parallax, grid, hero |