takomi 2.5.1 → 2.5.4

package/assets/.agent/skills/hyperframes-animation/transitions/TRANSITION-REGISTRY.md

@@ -1,167 +1,167 @@
-# Transition Registry — machine source of truth
-
-Single source of truth for **PLV scene-to-scene transitions**. The deterministic
-injector (`product-launch-video/scripts/inject-transitions.mjs`) reads the JSON
-block below and stamps the matching `gsap_template` onto the master timeline.
-The planner (`product-launch-video/agents/visual-design.md`) names a transition
-by its `name`; everything else is harness.
-
-This file is **not** the catalog of all transitions — that is `catalog.md` +
-`css-*.md` (≈40 CSS + shader). This registry is the curated subset that is
-**Tier-B-ready**: pure transform / opacity / filter on the two scene **clip
-wrappers** (`#el-<sid>`), no injected overlay DOM, no per-scene cooperation.
-Overlay families (staggered blocks, blinds, light leak, grid dissolve, page
-burn) and shader transitions are deferred to later phases.
-
-## How the injector applies a transition
-
-At a `break` boundary between scene _i_ (`from`) and scene _i+1_ (`to`), the
-injector:
-
-1. Extends `#el-<from>` wrapper `data-duration` by `duration_s` (holds its final
-   frame — verified: `core/src/runtime/init.ts:1393-1410` external-slot branch).
-2. Pulls `#el-<to>` wrapper `data-start` earlier by `duration_s` (creates the
-   overlap window).
-3. Reassigns **all** clip `data-track-index` as a 0/1 ping-pong so the two
-   overlapping wrappers never share a track (same-track overlap is illegal —
-   `core/src/lint/rules/composition.ts`). Higher track composites on top.
-4. Stamps the `gsap_template` into `window.__timelines["main"]` at `T = overlap-start`.
-
-Verified by prototype render (2026-05-31): the master-timeline wrapper tween is
-seeked and rendered (no double-seek with the sub-comp's own paused timeline —
-the runtime drives them independently), the extended wrapper holds scene _i_'s
-final frame, and the higher-track incoming wrapper composites over + blends with
-the outgoing one.
-
-## Template placeholders
-
-The injector substitutes these tokens in each `gsap_template` line:
-
-| Token                              | Meaning                                                                  |
-| ---------------------------------- | ------------------------------------------------------------------------ |
-| `__OLD__`                          | `"#el-<from>"` — outgoing clip wrapper selector (quoted)                 |
-| `__NEW__`                          | `"#el-<to>"` — incoming clip wrapper selector (quoted)                   |
-| `__T__`                            | overlap-start time in seconds (master clock)                             |
-| `__DUR__`                          | `duration_s` for this boundary                                           |
-| `__DX__`                           | horizontal travel for directional types: `-1920` (LEFT) / `1920` (RIGHT) |
-| `__DY__`                           | vertical travel: `-1080` (UP) / `1080` (DOWN)                            |
-| `__ORIGIN_OUT__` / `__ORIGIN_IN__` | transformOrigin pair for `squeeze`                                       |
-
-`filter` / `scaleX` / `transformOrigin` are lint-clean on the master timeline
-(verified: `core/src/lint/rules/gsap.ts` has no per-property whitelist and scopes
-its checks to `data-composition-id` ranges; the x/y/scale/rotation/opacity
-whitelist is a _scene-worker_ prompt rule only — it does not bind index.html).
-
-## Registry
-
-```json
-{
-  "transitions": [
-    {
-      "name": "crossfade",
-      "tier": "b",
-      "overlay": false,
-      "energy": "any",
-      "default_duration_s": 0.5,
-      "directions": [],
-      "source": "css-dissolve.md",
-      "gsap_template": [
-        "tl.to(__OLD__, { opacity: 0, duration: __DUR__, ease: \"power2.inOut\" }, __T__);",
-        "tl.fromTo(__NEW__, { opacity: 0 }, { opacity: 1, duration: __DUR__, ease: \"power2.inOut\" }, __T__);"
-      ]
-    },
-    {
-      "name": "blur-crossfade",
-      "tier": "b",
-      "overlay": false,
-      "energy": "calm",
-      "default_duration_s": 0.6,
-      "directions": [],
-      "source": "css-dissolve.md",
-      "note": "Default when the two scenes' #root backgrounds differ a lot — the blur masks the background-color clash a plain crossfade would expose.",
-      "gsap_template": [
-        "tl.to(__OLD__, { filter: \"blur(10px)\", scale: 1.03, opacity: 0, duration: __DUR__, ease: \"power2.inOut\" }, __T__);",
-        "tl.fromTo(__NEW__, { filter: \"blur(10px)\", scale: 0.97, opacity: 0 }, { filter: \"blur(0px)\", scale: 1, opacity: 1, duration: __DUR__, ease: \"power2.inOut\" }, __T__);"
-      ]
-    },
-    {
-      "name": "push-slide",
-      "tier": "b",
-      "overlay": false,
-      "energy": "medium",
-      "default_duration_s": 0.5,
-      "directions": ["LEFT", "RIGHT", "UP", "DOWN"],
-      "default_direction": "LEFT",
-      "source": "css-push.md",
-      "note": "Directional. The injector picks __DX__/__DY__ from the direction and emits the horizontal OR vertical pair (not both).",
-      "gsap_template_horizontal": [
-        "tl.to(__OLD__, { x: __DX__, duration: __DUR__, ease: \"power3.inOut\" }, __T__);",
-        "tl.fromTo(__NEW__, { x: __DXIN__, opacity: 1 }, { x: 0, duration: __DUR__, ease: \"power3.inOut\" }, __T__);"
-      ],
-      "gsap_template_vertical": [
-        "tl.to(__OLD__, { y: __DY__, duration: __DUR__, ease: \"power3.inOut\" }, __T__);",
-        "tl.fromTo(__NEW__, { y: __DYIN__, opacity: 1 }, { y: 0, duration: __DUR__, ease: \"power3.inOut\" }, __T__);"
-      ]
-    },
-    {
-      "name": "zoom-through",
-      "tier": "b",
-      "overlay": false,
-      "energy": "high",
-      "default_duration_s": 0.4,
-      "directions": [],
-      "source": "css-scale.md",
-      "gsap_template": [
-        "tl.to(__OLD__, { scale: 2.5, opacity: 0, filter: \"blur(8px)\", duration: __DUR__, ease: \"power3.in\" }, __T__);",
-        "tl.fromTo(__NEW__, { scale: 0.5, opacity: 0, filter: \"blur(8px)\" }, { scale: 1, opacity: 1, filter: \"blur(0px)\", duration: __DUR__, ease: \"power3.out\" }, __T__);"
-      ]
-    },
-    {
-      "name": "squeeze",
-      "tier": "b",
-      "overlay": false,
-      "energy": "medium",
-      "default_duration_s": 0.4,
-      "directions": [],
-      "source": "css-push.md",
-      "note": "Old compresses to a vertical line on the left edge; new expands from the right edge. Incoming starts off (scaleX 0) so its higher-track stacking is harmless.",
-      "gsap_template": [
-        "tl.to(__OLD__, { scaleX: 0, transformOrigin: \"left center\", duration: __DUR__, ease: \"power3.inOut\" }, __T__);",
-        "tl.fromTo(__NEW__, { scaleX: 0, transformOrigin: \"right center\", opacity: 1 }, { scaleX: 1, transformOrigin: \"right center\", duration: __DUR__, ease: \"power3.inOut\" }, __T__);"
-      ]
-    }
-  ],
-  "tier_a_types": ["morph", "shared-element"],
-  "default_high_energy": "zoom-through",
-  "default_calm": "blur-crossfade",
-  "max_duration_s": 2.0
-}
-```
-
-## Default-derivation (used by prep.mjs when the planner omits `**Transition:**`)
-
-A `break` boundary with no named transition gets a default:
-
-1. If the incoming scene's creative brief reads HIGH energy (explosive / kinetic /
-   frenetic keywords), use `default_high_energy` (`zoom-through`).
-2. Otherwise use `default_calm` (`blur-crossfade`) — the universal default. The
-   blur masks any background shift and reads intentional, which keeps the whole
-   video to ~2 transition types (the "repeat 2-3" principle).
-
-## Choosing as a planner (the only agent touchpoint)
-
-Pick **2-3 types for the whole video** and repeat them — repetition is what reads
-as professional (see `overview.md`). This budget counts the **Tier-B between-scene
-types only** (the 5 in the registry above); the Tier-A `shared-element` morph is a
-worker-authored bridge driven by narrative `intent: morph` — it is **exempt and
-does not count** toward the 2-3. Name the entering transition on each scene:
-
-```
-**Transition:** blur-crossfade
-**Transition:** push-slide LEFT
-**Transition:** zoom-through 0.3s
-```
-
-Omit the anchor to accept the default above. Do NOT write GSAP, touch timing, or
-edit index.html — the harness stamps the code, computes the overlap, and assigns
-tracks.
+# Transition Registry — machine source of truth
+
+Single source of truth for **PLV scene-to-scene transitions**. The deterministic
+injector (`product-launch-video/scripts/inject-transitions.mjs`) reads the JSON
+block below and stamps the matching `gsap_template` onto the master timeline.
+The planner (`product-launch-video/agents/visual-design.md`) names a transition
+by its `name`; everything else is harness.
+
+This file is **not** the catalog of all transitions — that is `catalog.md` +
+`css-*.md` (≈40 CSS + shader). This registry is the curated subset that is
+**Tier-B-ready**: pure transform / opacity / filter on the two scene **clip
+wrappers** (`#el-<sid>`), no injected overlay DOM, no per-scene cooperation.
+Overlay families (staggered blocks, blinds, light leak, grid dissolve, page
+burn) and shader transitions are deferred to later phases.
+
+## How the injector applies a transition
+
+At a `break` boundary between scene _i_ (`from`) and scene _i+1_ (`to`), the
+injector:
+
+1. Extends `#el-<from>` wrapper `data-duration` by `duration_s` (holds its final
+   frame — verified: `core/src/runtime/init.ts:1393-1410` external-slot branch).
+2. Pulls `#el-<to>` wrapper `data-start` earlier by `duration_s` (creates the
+   overlap window).
+3. Reassigns **all** clip `data-track-index` as a 0/1 ping-pong so the two
+   overlapping wrappers never share a track (same-track overlap is illegal —
+   `core/src/lint/rules/composition.ts`). Higher track composites on top.
+4. Stamps the `gsap_template` into `window.__timelines["main"]` at `T = overlap-start`.
+
+Verified by prototype render (2026-05-31): the master-timeline wrapper tween is
+seeked and rendered (no double-seek with the sub-comp's own paused timeline —
+the runtime drives them independently), the extended wrapper holds scene _i_'s
+final frame, and the higher-track incoming wrapper composites over + blends with
+the outgoing one.
+
+## Template placeholders
+
+The injector substitutes these tokens in each `gsap_template` line:
+
+| Token                              | Meaning                                                                  |
+| ---------------------------------- | ------------------------------------------------------------------------ |
+| `__OLD__`                          | `"#el-<from>"` — outgoing clip wrapper selector (quoted)                 |
+| `__NEW__`                          | `"#el-<to>"` — incoming clip wrapper selector (quoted)                   |
+| `__T__`                            | overlap-start time in seconds (master clock)                             |
+| `__DUR__`                          | `duration_s` for this boundary                                           |
+| `__DX__`                           | horizontal travel for directional types: `-1920` (LEFT) / `1920` (RIGHT) |
+| `__DY__`                           | vertical travel: `-1080` (UP) / `1080` (DOWN)                            |
+| `__ORIGIN_OUT__` / `__ORIGIN_IN__` | transformOrigin pair for `squeeze`                                       |
+
+`filter` / `scaleX` / `transformOrigin` are lint-clean on the master timeline
+(verified: `core/src/lint/rules/gsap.ts` has no per-property whitelist and scopes
+its checks to `data-composition-id` ranges; the x/y/scale/rotation/opacity
+whitelist is a _scene-worker_ prompt rule only — it does not bind index.html).
+
+## Registry
+
+```json
+{
+  "transitions": [
+    {
+      "name": "crossfade",
+      "tier": "b",
+      "overlay": false,
+      "energy": "any",
+      "default_duration_s": 0.5,
+      "directions": [],
+      "source": "css-dissolve.md",
+      "gsap_template": [
+        "tl.to(__OLD__, { opacity: 0, duration: __DUR__, ease: \"power2.inOut\" }, __T__);",
+        "tl.fromTo(__NEW__, { opacity: 0 }, { opacity: 1, duration: __DUR__, ease: \"power2.inOut\" }, __T__);"
+      ]
+    },
+    {
+      "name": "blur-crossfade",
+      "tier": "b",
+      "overlay": false,
+      "energy": "calm",
+      "default_duration_s": 0.6,
+      "directions": [],
+      "source": "css-dissolve.md",
+      "note": "Default when the two scenes' #root backgrounds differ a lot — the blur masks the background-color clash a plain crossfade would expose.",
+      "gsap_template": [
+        "tl.to(__OLD__, { filter: \"blur(10px)\", scale: 1.03, opacity: 0, duration: __DUR__, ease: \"power2.inOut\" }, __T__);",
+        "tl.fromTo(__NEW__, { filter: \"blur(10px)\", scale: 0.97, opacity: 0 }, { filter: \"blur(0px)\", scale: 1, opacity: 1, duration: __DUR__, ease: \"power2.inOut\" }, __T__);"
+      ]
+    },
+    {
+      "name": "push-slide",
+      "tier": "b",
+      "overlay": false,
+      "energy": "medium",
+      "default_duration_s": 0.5,
+      "directions": ["LEFT", "RIGHT", "UP", "DOWN"],
+      "default_direction": "LEFT",
+      "source": "css-push.md",
+      "note": "Directional. The injector picks __DX__/__DY__ from the direction and emits the horizontal OR vertical pair (not both).",
+      "gsap_template_horizontal": [
+        "tl.to(__OLD__, { x: __DX__, duration: __DUR__, ease: \"power3.inOut\" }, __T__);",
+        "tl.fromTo(__NEW__, { x: __DXIN__, opacity: 1 }, { x: 0, duration: __DUR__, ease: \"power3.inOut\" }, __T__);"
+      ],
+      "gsap_template_vertical": [
+        "tl.to(__OLD__, { y: __DY__, duration: __DUR__, ease: \"power3.inOut\" }, __T__);",
+        "tl.fromTo(__NEW__, { y: __DYIN__, opacity: 1 }, { y: 0, duration: __DUR__, ease: \"power3.inOut\" }, __T__);"
+      ]
+    },
+    {
+      "name": "zoom-through",
+      "tier": "b",
+      "overlay": false,
+      "energy": "high",
+      "default_duration_s": 0.4,
+      "directions": [],
+      "source": "css-scale.md",
+      "gsap_template": [
+        "tl.to(__OLD__, { scale: 2.5, opacity: 0, filter: \"blur(8px)\", duration: __DUR__, ease: \"power3.in\" }, __T__);",
+        "tl.fromTo(__NEW__, { scale: 0.5, opacity: 0, filter: \"blur(8px)\" }, { scale: 1, opacity: 1, filter: \"blur(0px)\", duration: __DUR__, ease: \"power3.out\" }, __T__);"
+      ]
+    },
+    {
+      "name": "squeeze",
+      "tier": "b",
+      "overlay": false,
+      "energy": "medium",
+      "default_duration_s": 0.4,
+      "directions": [],
+      "source": "css-push.md",
+      "note": "Old compresses to a vertical line on the left edge; new expands from the right edge. Incoming starts off (scaleX 0) so its higher-track stacking is harmless.",
+      "gsap_template": [
+        "tl.to(__OLD__, { scaleX: 0, transformOrigin: \"left center\", duration: __DUR__, ease: \"power3.inOut\" }, __T__);",
+        "tl.fromTo(__NEW__, { scaleX: 0, transformOrigin: \"right center\", opacity: 1 }, { scaleX: 1, transformOrigin: \"right center\", duration: __DUR__, ease: \"power3.inOut\" }, __T__);"
+      ]
+    }
+  ],
+  "tier_a_types": ["morph", "shared-element"],
+  "default_high_energy": "zoom-through",
+  "default_calm": "blur-crossfade",
+  "max_duration_s": 2.0
+}
+```
+
+## Default-derivation (used by prep.mjs when the planner omits `**Transition:**`)
+
+A `break` boundary with no named transition gets a default:
+
+1. If the incoming scene's creative brief reads HIGH energy (explosive / kinetic /
+   frenetic keywords), use `default_high_energy` (`zoom-through`).
+2. Otherwise use `default_calm` (`blur-crossfade`) — the universal default. The
+   blur masks any background shift and reads intentional, which keeps the whole
+   video to ~2 transition types (the "repeat 2-3" principle).
+
+## Choosing as a planner (the only agent touchpoint)
+
+Pick **2-3 types for the whole video** and repeat them — repetition is what reads
+as professional (see `overview.md`). This budget counts the **Tier-B between-scene
+types only** (the 5 in the registry above); the Tier-A `shared-element` morph is a
+worker-authored bridge driven by narrative `intent: morph` — it is **exempt and
+does not count** toward the 2-3. Name the entering transition on each scene:
+
+```
+**Transition:** blur-crossfade
+**Transition:** push-slide LEFT
+**Transition:** zoom-through 0.3s
+```
+
+Omit the anchor to accept the default above. Do NOT write GSAP, touch timing, or
+edit index.html — the harness stamps the code, computes the overlap, and assigns
+tracks.

package/assets/.agent/skills/hyperframes-animation/transitions/catalog.md

@@ -1,127 +1,127 @@
-# Transition Catalog
-
-Hard rules, scene template, and routing to implementation code. Read the reference file for the transition type you need — don't load all of them.
-
-## Contents
-
-- Hard rules for CSS transitions
-- Shader transitions
-- Scene template
-- CSS transition examples
-- Shader transition routing
-
-## Hard Rules (CSS)
-
-These cause real bugs if violated.
-
-**Scene visibility:** Scene 1 visible by default (no `opacity: 0`). Scenes 2+ have `opacity: 0` on the CONTAINER div. GSAP reveals them. No visibility shim (`timedEls`).
-
-**Fonts:** Just write the `font-family` you want — the compiler embeds supported fonts automatically via `@font-face` with inline data URIs. No need for `<link>` tags or `@import`. Works in all contexts including sandboxed iframes.
-
-**Element structure:** No `class="clip"` on scene divs in standalone compositions. Only the root div gets `data-composition-id`/`data-start`/`data-duration`.
-
-**Overlay elements:** Staggered blocks = full-screen 1920x1080, NOT thin strips. Glitch RGB overlays = normal blending at 35% opacity, NOT `mix-blend-mode: multiply` (invisible on dark backgrounds). Light leak overlays = larger than the frame (2400px+), never a visible shape. Overexposure = use `filter: brightness()` on the scene, not just a white overlay.
-
-**VHS tape:** Clone actual scene content with `cloneNode(true)`, NOT colored bars. Each strip: wider than frame (2020px at left:-50px). Red+blue chromatic copies at z-index above main strip. Seeded PRNG for deterministic random offsets.
-
-**Z-index:** Gravity drop, zoom out, diagonal split need outgoing scene ON TOP (`zIndex: 10`) so it exits while revealing the new scene behind (`zIndex: 1`).
-
-**Page burn:** Content burns with the page — no falling debris. Hide scene1 via `tl.set` at burn end, NEVER `onComplete` (not reversible). `onUpdate` must restore `clipPath: "none"` when `wp <= 0` for rewind support. Incoming scene fades from black at 90% through burn.
-
-**Clock wipe:** 9-point polygon with intermediate edge positions. Step through 4 quadrants with separate tweens.
-
-**Grid dissolve:** Cycle 5 palette colors per cell, not monochrome.
-
-**Blinds count by energy:** Calm: 4h/6v. Medium: 6-8h/8v. High: 12-16h/16v.
-
-**Don't use:** Star iris (polygon interpolation broken), tilt-shift (no selective CSS blur), lens flare (visible shape, not optical), hinge/door (distorts too fast).
-
-## Shader Transitions
-
-Shader setup, WebGL init, capture, and fragment shaders are handled by `@hyperframes/shader-transitions` (`packages/shader-transitions/`). Read the package source for API details. Compositions using shaders must follow the shader-compatible CSS rules in `overview.md` (this directory).
-
-## Scene Template
-
-```html
-<!DOCTYPE html>
-<html lang="en">
-  <head>
-    <meta charset="UTF-8" />
-    <script src="https://cdn.jsdelivr.net/npm/gsap@3.14.2/dist/gsap.min.js"></script>
-    <style>
-      body {
-        margin: 0;
-        width: 1920px;
-        height: 1080px;
-        overflow: hidden;
-        background: #000;
-        font-family: "YOUR FONT", sans-serif; /* compiler embeds supported fonts automatically */
-      }
-      .scene {
-        position: absolute;
-        top: 0;
-        left: 0;
-        width: 1920px;
-        height: 1080px;
-        overflow: hidden;
-      }
-      #scene1 {
-        z-index: 1;
-        background: #color;
-      }
-      #scene2 {
-        z-index: 2;
-        background: #color;
-        opacity: 0;
-      }
-    </style>
-  </head>
-  <body>
-    <div
-      id="root"
-      data-composition-id="main"
-      data-width="1920"
-      data-height="1080"
-      data-start="0"
-      data-duration="TOTAL"
-    >
-      <div id="scene1" class="scene"><!-- visible --></div>
-      <div id="scene2" class="scene"><!-- hidden --></div>
-    </div>
-    <script>
-      window.__timelines = window.__timelines || {};
-      var tl = gsap.timeline({ paused: true });
-      // Transition code here
-      window.__timelines["main"] = tl;
-    </script>
-  </body>
-</html>
-```
-
-Every transition follows: position new scene → animate outgoing → swap → animate incoming → clean up overlays.
-
-## CSS Transitions
-
-All code examples use `old` for the outgoing scene-inner selector and `new` for the incoming, with `T` as the transition start time. Read the reference file for the type you need.
-
-| Type           | Transitions                                          | Reference                        |
-| -------------- | ---------------------------------------------------- | -------------------------------- |
-| Push           | Push slide, vertical push, elastic push, squeeze     | `transitions/css-push.md`        |
-| Radial / Shape | Circle iris, diamond iris, diagonal split            | `transitions/css-radial.md`      |
-| 3D             | 3D card flip                                         | `transitions/css-3d.md`          |
-| Scale / Zoom   | Zoom through, zoom out                               | `transitions/css-scale.md`       |
-| Dissolve       | Crossfade, blur crossfade, focus pull, color dip     | `transitions/css-dissolve.md`    |
-| Cover          | Staggered blocks, horizontal blinds, vertical blinds | `transitions/css-cover.md`       |
-| Light          | Light leak, overexposure burn, film burn             | `transitions/css-light.md`       |
-| Distortion     | Glitch, chromatic aberration, ripple, VHS tape       | `transitions/css-distortion.md`  |
-| Mechanical     | Shutter, clock wipe                                  | `transitions/css-mechanical.md`  |
-| Grid           | Grid dissolve                                        | `transitions/css-grid.md`        |
-| Other          | Gravity drop, morph circle                           | `transitions/css-other.md`       |
-| Blur           | Blur through, directional blur                       | `transitions/css-blur.md`        |
-| Destruction    | Page burn                                            | `transitions/css-destruction.md` |
-
-## Shader Transitions
-
-WebGL shader transitions are provided by `@hyperframes/shader-transitions` (`packages/shader-transitions/`). The package handles setup, capture, WebGL init, render loop, and GSAP integration. Read the package source for available shaders and API — do not copy raw GLSL manually.
-
-The built-ins are not a ceiling. For an effect no built-in covers, you can write custom GLSL from scratch, adapt shader code found online (ShaderToy, GLSL Sandbox, GitHub), or build a custom CSS transition that fits no existing category — combine clip-path, transforms, and filters in new ways. If the storyboard calls for an effect that doesn't exist yet, build it; the framework renders anything a browser can run.
+# Transition Catalog
+
+Hard rules, scene template, and routing to implementation code. Read the reference file for the transition type you need — don't load all of them.
+
+## Contents
+
+- Hard rules for CSS transitions
+- Shader transitions
+- Scene template
+- CSS transition examples
+- Shader transition routing
+
+## Hard Rules (CSS)
+
+These cause real bugs if violated.
+
+**Scene visibility:** Scene 1 visible by default (no `opacity: 0`). Scenes 2+ have `opacity: 0` on the CONTAINER div. GSAP reveals them. No visibility shim (`timedEls`).
+
+**Fonts:** Just write the `font-family` you want — the compiler embeds supported fonts automatically via `@font-face` with inline data URIs. No need for `<link>` tags or `@import`. Works in all contexts including sandboxed iframes.
+
+**Element structure:** No `class="clip"` on scene divs in standalone compositions. Only the root div gets `data-composition-id`/`data-start`/`data-duration`.
+
+**Overlay elements:** Staggered blocks = full-screen 1920x1080, NOT thin strips. Glitch RGB overlays = normal blending at 35% opacity, NOT `mix-blend-mode: multiply` (invisible on dark backgrounds). Light leak overlays = larger than the frame (2400px+), never a visible shape. Overexposure = use `filter: brightness()` on the scene, not just a white overlay.
+
+**VHS tape:** Clone actual scene content with `cloneNode(true)`, NOT colored bars. Each strip: wider than frame (2020px at left:-50px). Red+blue chromatic copies at z-index above main strip. Seeded PRNG for deterministic random offsets.
+
+**Z-index:** Gravity drop, zoom out, diagonal split need outgoing scene ON TOP (`zIndex: 10`) so it exits while revealing the new scene behind (`zIndex: 1`).
+
+**Page burn:** Content burns with the page — no falling debris. Hide scene1 via `tl.set` at burn end, NEVER `onComplete` (not reversible). `onUpdate` must restore `clipPath: "none"` when `wp <= 0` for rewind support. Incoming scene fades from black at 90% through burn.
+
+**Clock wipe:** 9-point polygon with intermediate edge positions. Step through 4 quadrants with separate tweens.
+
+**Grid dissolve:** Cycle 5 palette colors per cell, not monochrome.
+
+**Blinds count by energy:** Calm: 4h/6v. Medium: 6-8h/8v. High: 12-16h/16v.
+
+**Don't use:** Star iris (polygon interpolation broken), tilt-shift (no selective CSS blur), lens flare (visible shape, not optical), hinge/door (distorts too fast).
+
+## Shader Transitions
+
+Shader setup, WebGL init, capture, and fragment shaders are handled by `@hyperframes/shader-transitions` (`packages/shader-transitions/`). Read the package source for API details. Compositions using shaders must follow the shader-compatible CSS rules in `overview.md` (this directory).
+
+## Scene Template
+
+```html
+<!DOCTYPE html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <script src="https://cdn.jsdelivr.net/npm/gsap@3.14.2/dist/gsap.min.js"></script>
+    <style>
+      body {
+        margin: 0;
+        width: 1920px;
+        height: 1080px;
+        overflow: hidden;
+        background: #000;
+        font-family: "YOUR FONT", sans-serif; /* compiler embeds supported fonts automatically */
+      }
+      .scene {
+        position: absolute;
+        top: 0;
+        left: 0;
+        width: 1920px;
+        height: 1080px;
+        overflow: hidden;
+      }
+      #scene1 {
+        z-index: 1;
+        background: #color;
+      }
+      #scene2 {
+        z-index: 2;
+        background: #color;
+        opacity: 0;
+      }
+    </style>
+  </head>
+  <body>
+    <div
+      id="root"
+      data-composition-id="main"
+      data-width="1920"
+      data-height="1080"
+      data-start="0"
+      data-duration="TOTAL"
+    >
+      <div id="scene1" class="scene"><!-- visible --></div>
+      <div id="scene2" class="scene"><!-- hidden --></div>
+    </div>
+    <script>
+      window.__timelines = window.__timelines || {};
+      var tl = gsap.timeline({ paused: true });
+      // Transition code here
+      window.__timelines["main"] = tl;
+    </script>
+  </body>
+</html>
+```
+
+Every transition follows: position new scene → animate outgoing → swap → animate incoming → clean up overlays.
+
+## CSS Transitions
+
+All code examples use `old` for the outgoing scene-inner selector and `new` for the incoming, with `T` as the transition start time. Read the reference file for the type you need.
+
+| Type           | Transitions                                          | Reference                        |
+| -------------- | ---------------------------------------------------- | -------------------------------- |
+| Push           | Push slide, vertical push, elastic push, squeeze     | `transitions/css-push.md`        |
+| Radial / Shape | Circle iris, diamond iris, diagonal split            | `transitions/css-radial.md`      |
+| 3D             | 3D card flip                                         | `transitions/css-3d.md`          |
+| Scale / Zoom   | Zoom through, zoom out                               | `transitions/css-scale.md`       |
+| Dissolve       | Crossfade, blur crossfade, focus pull, color dip     | `transitions/css-dissolve.md`    |
+| Cover          | Staggered blocks, horizontal blinds, vertical blinds | `transitions/css-cover.md`       |
+| Light          | Light leak, overexposure burn, film burn             | `transitions/css-light.md`       |
+| Distortion     | Glitch, chromatic aberration, ripple, VHS tape       | `transitions/css-distortion.md`  |
+| Mechanical     | Shutter, clock wipe                                  | `transitions/css-mechanical.md`  |
+| Grid           | Grid dissolve                                        | `transitions/css-grid.md`        |
+| Other          | Gravity drop, morph circle                           | `transitions/css-other.md`       |
+| Blur           | Blur through, directional blur                       | `transitions/css-blur.md`        |
+| Destruction    | Page burn                                            | `transitions/css-destruction.md` |
+
+## Shader Transitions
+
+WebGL shader transitions are provided by `@hyperframes/shader-transitions` (`packages/shader-transitions/`). The package handles setup, capture, WebGL init, render loop, and GSAP integration. Read the package source for available shaders and API — do not copy raw GLSL manually.
+
+The built-ins are not a ceiling. For an effect no built-in covers, you can write custom GLSL from scratch, adapt shader code found online (ShaderToy, GLSL Sandbox, GitHub), or build a custom CSS transition that fits no existing category — combine clip-path, transforms, and filters in new ways. If the storyboard calls for an effect that doesn't exist yet, build it; the framework renders anything a browser can run.

package/assets/.agent/skills/hyperframes-animation/transitions/css-3d.md

@@ -1,12 +1,12 @@
-## 3D
-
-### 3D Card Flip
-
-180° Y-axis rotation. Requires CSS: `backface-visibility: hidden; transform-style: preserve-3d;` on both scene-inners. Parent needs `perspective: 1200px`.
-
-```js
-tl.set(new, { rotationY: -180, opacity: 1 }, T);
-tl.to(old, { rotationY: 180, duration: 0.6, ease: "power2.inOut" }, T);
-tl.to(new, { rotationY: 0, duration: 0.6, ease: "power2.inOut" }, T);
-tl.set(old, { opacity: 0 }, T + 0.6);
-```
+## 3D
+
+### 3D Card Flip
+
+180° Y-axis rotation. Requires CSS: `backface-visibility: hidden; transform-style: preserve-3d;` on both scene-inners. Parent needs `perspective: 1200px`.
+
+```js
+tl.set(new, { rotationY: -180, opacity: 1 }, T);
+tl.to(old, { rotationY: 180, duration: 0.6, ease: "power2.inOut" }, T);
+tl.to(new, { rotationY: 0, duration: 0.6, ease: "power2.inOut" }, T);
+tl.set(old, { opacity: 0 }, T + 0.6);
+```