dsh-hyperframes 0.1.1 → 0.3.0

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

@@ -0,0 +1,168 @@
+# 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 (a readability convention, not a
+   render constraint,
+   `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/skills/{hyperframes/references → hyperframes-animation}/transitions/catalog.md

@@ -2,6 +2,14 @@
 
 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.
@@ -30,7 +38,7 @@ These cause real bugs if violated.
 
 ## 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 CSS rules in [transitions.md](../transitions.md) § "Shader-Compatible CSS Rules".
+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
 
@@ -96,22 +104,24 @@ Every transition follows: position new scene → animate outgoing → swap → a
 
 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     | [css-push.md](./css-push.md)               |
-| Radial / Shape | Circle iris, diamond iris, diagonal split            | [css-radial.md](./css-radial.md)           |
-| 3D             | 3D card flip                                         | [css-3d.md](./css-3d.md)                   |
-| Scale / Zoom   | Zoom through, zoom out                               | [css-scale.md](./css-scale.md)             |
-| Dissolve       | Crossfade, blur crossfade, focus pull, color dip     | [css-dissolve.md](./css-dissolve.md)       |
-| Cover          | Staggered blocks, horizontal blinds, vertical blinds | [css-cover.md](./css-cover.md)             |
-| Light          | Light leak, overexposure burn, film burn             | [css-light.md](./css-light.md)             |
-| Distortion     | Glitch, chromatic aberration, ripple, VHS tape       | [css-distortion.md](./css-distortion.md)   |
-| Mechanical     | Shutter, clock wipe                                  | [css-mechanical.md](./css-mechanical.md)   |
-| Grid           | Grid dissolve                                        | [css-grid.md](./css-grid.md)               |
-| Other          | Gravity drop, morph circle                           | [css-other.md](./css-other.md)             |
-| Blur           | Blur through, directional blur                       | [css-blur.md](./css-blur.md)               |
-| Destruction    | Page burn                                            | [css-destruction.md](./css-destruction.md) |
+| 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/skills/{hyperframes/references → hyperframes-animation}/transitions/css-destruction.md

@@ -10,7 +10,7 @@ This transition has three systems working together:
 2. **Scene clipping** — the outgoing scene uses an SVG clip-path (with `fill-rule: evenodd`) that cuts a hole matching the fire front. As the fire expands, more of the scene is clipped away. All content (text, images, lines) burns with the page — no separate debris.
 3. **Scorched edge** — a `<canvas>` overlay draws a radial gradient fringe at the fire boundary to simulate charring
 
-**When to use:** Dramatic reveals, edgy/destructive mood, gaming, cyberpunk. This is the most dramatic transition in the catalog — reserve it for hero moments.
+**When to use:** Dramatic reveals, edgy/destructive mood, gaming, neon-noir. This is the most dramatic transition in the catalog — reserve it for hero moments.
 
 **Requirements:**
 

package/skills/{hyperframes/references/transitions.md → hyperframes-animation/transitions/overview.md}

@@ -2,15 +2,41 @@
 
 A transition tells the viewer how two scenes relate. A crossfade says "this continues." A push slide says "next point." A blur crossfade says "drift with me." Choose transitions that match what the content is doing emotionally, not just technically.
 
+## Contents
+
+- Animation rules for multi-scene compositions
+- Energy and mood transition selection
+- Narrative position
+- Blur intensity
+- Presets
+- Implementation
+- CSS vs shader guidance
+- Shader-compatible CSS rules
+- Visual pattern warnings
+
 ## Animation Rules for Multi-Scene Compositions
 
 These are non-negotiable for every multi-scene composition:
 
 1. **Every composition uses transitions.** No exceptions. Scenes without transitions feel like jump cuts.
-2. **Every scene uses entrance animations.** Elements animate IN via `gsap.from()` — opacity, position, scale, etc. No scene should pop fully-formed onto screen.
+2. **Every scene uses entrance animations.** Elements animate IN — opacity, position, scale, etc. No scene should pop fully-formed onto screen. Use `gsap.fromTo()` (not `gsap.from()`) so the start state is explicit: `from()` animates _to_ current CSS, so pairing it with CSS `opacity: 0` is a 0→0 noop and the element never appears (see `/hyperframes-core` → sub-compositions).
 3. **Exit animations are BANNED** except on the final scene. Do NOT use `gsap.to()` to animate elements out before a transition fires. The transition IS the exit. Outgoing scene content must be fully visible when the transition starts — the transition handles the visual handoff.
 4. **Final scene exception:** The last scene MAY fade elements out (e.g., fade to black at the end of the composition). This is the only scene where exit animations are allowed.
 
+```js
+// ❌ BANNED — fading the outgoing scene out, then the next scene just runs its entrance.
+//    This is a jump cut with a dip, not a transition.
+tl.to("#s1", { opacity: 0, duration: 0.4 }, 4.0);
+tl.from("#s2 .headline", { y: 40, opacity: 0 }, 4.4);
+
+// ✅ CORRECT — outgoing and incoming animate AT THE SAME TIME T; the motion IS the handoff.
+const T = 4.0;
+tl.to("#s1", { yPercent: -100, filter: "blur(8px)", duration: 0.5, ease: "power3.in" }, T);
+tl.fromTo("#s2", { yPercent: 100 }, { yPercent: 0, duration: 0.5, ease: "power3.out" }, T);
+```
+
+> **You are NOT done after this file.** This overview gives you _which_ transition and _when_. Before writing any transition you MUST open **`catalog.md`** in this directory for the GSAP code and the hard rule every transition follows — _position new scene → animate outgoing → swap → animate incoming → clean up overlays_ — plus the per-category `css-*.md` files for specifics. Authoring transitions from this overview alone is how you end up shipping the ❌ pattern above.
+
 ## Energy → Primary Transition
 
 | Energy                                   | CSS Primary                  | Shader Primary                       | Accent                         | Duration  | Easing                 |
@@ -69,7 +95,7 @@ Think about what the transition _communicates_, not just what it looks like.
 
 ## Implementation
 
-Read [transitions/catalog.md](transitions/catalog.md) for GSAP code and hard rules for every transition type.
+Read `catalog.md` in this directory for GSAP code and hard rules for every transition type, and the `css-*.md` files for per-category implementation details.
 
 | Category    | CSS                                                            | Shader (WebGL)                                                            |
 | ----------- | -------------------------------------------------------------- | ------------------------------------------------------------------------- |
@@ -92,7 +118,22 @@ CSS transitions animate scene containers with opacity, transforms, clip-path, an
 
 **Both are first-class options.** Shaders are provided by the `@hyperframes/shader-transitions` package — import from the package instead of writing raw GLSL. CSS transitions are simpler to set up. Choose based on the effect you want, not based on which is easier.
 
-When a composition uses shader transitions, ALL transitions in that composition should be shader-based (the WebGL canvas replaces DOM-based scene switching). Don't mix CSS and shader transitions in the same composition.
+**Mixing is supported.** You can have some transitions use WebGL shaders and others use a CSS crossfade in the same composition. Omit the `shader` field on any `TransitionConfig` entry to get a smooth opacity crossfade instead of a WebGL effect:
+
+```js
+var tl = HyperShader.init({
+  bgColor: "#000",
+  accentColor: "#6366f1",
+  scenes: ["s1", "s2", "s3", "s4"],
+  transitions: [
+    { time: 4.0, shader: "sdf-iris", duration: 0.7 }, // WebGL shader
+    { time: 8.5, duration: 0.8 }, // no shader → CSS crossfade
+    { time: 13.0, shader: "domain-warp", duration: 0.6 }, // WebGL shader
+  ],
+});
+```
+
+HyperShader manages all scene visibility regardless of transition type. Let it create the timeline (don't pass `timeline:` into `init()`) and add your beat animations to the returned `tl` after the call.
 
 ## Shader-Compatible CSS Rules