@w3kits-com/plugin-opendesign 0.1.8 → 0.1.10

package/dist/__w3kits/assets/design-templates/hyperframes/references/transcript-guide.md

@@ -0,0 +1,151 @@
+# Transcript Guide
+
+## How Transcripts Are Generated
+
+`hyperframes transcribe` handles both transcription and format conversion:
+
+```bash
+# Transcribe audio/video (uses whisper.cpp locally, no API key needed)
+npx hyperframes transcribe audio.mp3
+
+# Use a larger model for better accuracy
+npx hyperframes transcribe audio.mp3 --model medium.en
+
+# Filter to English only (skips non-English speech)
+npx hyperframes transcribe audio.mp3 --language en
+
+# Import an existing transcript from another tool
+npx hyperframes transcribe captions.srt
+npx hyperframes transcribe captions.vtt
+npx hyperframes transcribe openai-response.json
+```
+
+## Supported Input Formats
+
+The CLI auto-detects and normalizes these formats:
+
+| Format                | Extension | Source                                                                      | Word-level?       |
+| --------------------- | --------- | --------------------------------------------------------------------------- | ----------------- |
+| whisper.cpp JSON      | `.json`   | `hyperframes init --video`, `hyperframes transcribe`                        | Yes               |
+| OpenAI Whisper API    | `.json`   | `openai.audio.transcriptions.create({ timestamp_granularities: ["word"] })` | Yes               |
+| SRT subtitles         | `.srt`    | Video editors, subtitle tools, YouTube                                      | No (phrase-level) |
+| VTT subtitles         | `.vtt`    | Web players, YouTube, transcription services                                | No (phrase-level) |
+| Normalized word array | `.json`   | Pre-processed by any tool                                                   | Yes               |
+
+**Word-level timestamps produce better captions.** SRT/VTT give phrase-level timing, which works but can't do per-word animation effects.
+
+## Whisper Model Guide
+
+The default model (`small.en`) balances accuracy and speed. For better results, use a larger model:
+
+| Model      | Size   | Speed    | Accuracy  | When to use                           |
+| ---------- | ------ | -------- | --------- | ------------------------------------- |
+| `tiny`     | 75 MB  | Fastest  | Low       | Quick previews, testing pipeline      |
+| `base`     | 142 MB | Fast     | Fair      | Short clips, clear audio              |
+| `small`    | 466 MB | Moderate | Good      | **Default** — good for most content   |
+| `medium`   | 1.5 GB | Slow     | Very good | Important content, noisy audio, music |
+| `large-v3` | 3.1 GB | Slowest  | Best      | Production quality                    |
+
+**Only add `.en` suffix when the user explicitly says the audio is English.** `.en` models are slightly more accurate for English but will TRANSLATE non-English audio instead of transcribing it.
+
+**Critical: `.en` models translate non-English audio into English** — they don't transcribe it. If the audio might not be English, always use a model without the `.en` suffix and pass `--language` to specify the source language. If you're unsure of the language, use `small` (not `small.en`) without `--language` — whisper will auto-detect.
+
+```bash
+# Spanish audio
+npx hyperframes transcribe audio.mp3 --model small --language es
+
+# Unknown language — let whisper auto-detect
+npx hyperframes transcribe audio.mp3 --model small
+```
+
+**Music and vocals over instrumentation**: `small.en` will misidentify lyrics — use `medium.en` as the minimum, or import lyrics manually. Even `medium.en` struggles with heavily produced tracks; for music videos, providing known lyrics as an SRT/VTT and importing with `hyperframes transcribe lyrics.srt` will always beat automated transcription.
+
+## Transcript Quality Check (Mandatory)
+
+After every transcription, **read the transcript and check for quality issues before proceeding.** Bad transcripts produce nonsensical captions. Never skip this step.
+
+### What to look for
+
+| Signal                       | Example                                | Cause                                                                        |
+| ---------------------------- | -------------------------------------- | ---------------------------------------------------------------------------- |
+| Music note tokens (`♪`, `�`) | `{ "text": "♪" }` or `{ "text": "�" }` | Whisper detected music, not speech                                           |
+| Garbled / nonsense words     | "Do a chin", "Get so gay", "huh"       | Model misheard lyrics or background noise                                    |
+| Long gaps with no words      | 20+ seconds of only `♪` tokens         | Instrumental section — expected, but high ratio means speech is being missed |
+| Repeated filler              | Many "huh", "uh", "oh" entries         | Model is hallucinating on music                                              |
+| Very short word spans        | Words with `end - start < 0.05`        | Unreliable timestamp alignment                                               |
+
+### Automatic retry rules
+
+**If more than 20% of entries are `♪`/`�` tokens, or the transcript contains obvious nonsense words, the transcription failed.** Do not proceed with the bad transcript. Instead:
+
+1. **Retry with `medium.en`** if the original used `small.en` or smaller:
+   ```bash
+   npx hyperframes transcribe audio.mp3 --model medium.en
+   ```
+2. **If `medium.en` also fails** (still >20% music tokens or garbled), tell the user the audio is too noisy for local transcription and suggest:
+   - Providing lyrics manually as an SRT/VTT file
+   - Using an external API (OpenAI or Groq Whisper — see below)
+3. **Always clean the transcript** before building captions — filter out `♪`/`�` tokens and entries where `text` is a single non-word character. Only real words should reach the caption composition.
+
+### Cleaning a transcript
+
+After transcription (even with a good model), strip non-word entries:
+
+```js
+var raw = JSON.parse(transcriptJson);
+var words = raw.filter(function (w) {
+  if (!w.text || w.text.trim().length === 0) return false;
+  if (/^[♪�\u266a\u266b\u266c\u266d\u266e\u266f]+$/.test(w.text)) return false;
+  if (/^(huh|uh|um|ah|oh)$/i.test(w.text) && w.end - w.start < 0.1) return false;
+  return true;
+});
+```
+
+### When to use which model (decision tree)
+
+1. **Is this speech over silence/light background?** → `small.en` is fine
+2. **Is this speech over music, or music with vocals?** → Start with `medium.en`
+3. **Is this a produced music track (vocals + full instrumentation)?** → Start with `medium.en`, expect to need manual lyrics or an external API
+4. **Is this multilingual?** → Use `medium` or `large-v3` (no `.en` suffix)
+
+## Using External Transcription APIs
+
+For the best accuracy, use an external API and import the result:
+
+**OpenAI Whisper API** (recommended for quality):
+
+```bash
+# Generate with word timestamps, then import
+curl https://api.openai.com/v1/audio/transcriptions \
+  -H "Authorization: Bearer $OPENAI_API_KEY" \
+  -F file=@audio.mp3 -F model=whisper-1 \
+  -F response_format=verbose_json \
+  -F "timestamp_granularities[]=word" \
+  -o transcript-openai.json
+
+npx hyperframes transcribe transcript-openai.json
+```
+
+**Groq Whisper API** (fast, free tier available):
+
+```bash
+curl https://api.groq.com/openai/v1/audio/transcriptions \
+  -H "Authorization: Bearer $GROQ_API_KEY" \
+  -F file=@audio.mp3 -F model=whisper-large-v3 \
+  -F response_format=verbose_json \
+  -F "timestamp_granularities[]=word" \
+  -o transcript-groq.json
+
+npx hyperframes transcribe transcript-groq.json
+```
+
+## If No Transcript Exists
+
+1. Check the project root for `transcript.json`, `.srt`, or `.vtt` files
+2. If none found, run transcription — pick the starting model based on the content type:
+   - Speech/voiceover → `small.en`
+   - Music with vocals → `medium.en`
+   ```bash
+   npx hyperframes transcribe <audio-or-video-file> --model medium.en
+   ```
+3. **Read the transcript and run the quality check** (see above). If it fails, retry with a larger model or suggest manual lyrics.

package/dist/__w3kits/assets/design-templates/hyperframes/references/transitions/catalog.md

@@ -0,0 +1,117 @@
+# 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.
+
+## 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 CSS rules in [transitions.md](../transitions.md) § "Shader-Compatible CSS Rules".
+
+## 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     | [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) |
+
+## 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.

package/dist/__w3kits/assets/design-templates/hyperframes/references/transitions/css-3d.md

@@ -0,0 +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);
+```

package/dist/__w3kits/assets/design-templates/hyperframes/references/transitions/css-blur.md

@@ -0,0 +1,51 @@
+## Blur
+
+All blur transitions scale with energy. See SKILL.md "Blur Intensity by Energy" for the full table.
+
+### Blur Through
+
+Content becomes fully abstract before resolving. The heaviest blur transition.
+
+**Calm (default for this type — it's inherently heavy):**
+
+```js
+tl.to(old, { filter: "blur(30px)", scale: 1.08, duration: 0.5, ease: "power1.in" }, T);
+tl.to(old, { opacity: 0, duration: 0.3, ease: "power1.in" }, T + 0.3);
+// Hold: both scenes in abstract blur state
+tl.fromTo(new,
+  { filter: "blur(30px)", scale: 0.92, opacity: 0 },
+  { filter: "blur(30px)", scale: 0.92, opacity: 1, duration: 0.2, ease: "none" }, T + 0.5);
+// Slow resolve
+tl.to(new, { filter: "blur(0px)", scale: 1, duration: 0.7, ease: "power1.out" }, T + 0.7);
+```
+
+**Medium:**
+
+```js
+tl.to(old, { filter: "blur(15px)", scale: 1.05, opacity: 0, duration: 0.4, ease: "power2.in" }, T);
+tl.fromTo(new,
+  { filter: "blur(15px)", scale: 0.95, opacity: 0 },
+  { filter: "blur(0px)", scale: 1, opacity: 1, duration: 0.4, ease: "power2.out" }, T + 0.2);
+```
+
+### Directional Blur
+
+Blur + skew simulating motion in one direction. Scale blur and skew with energy.
+
+**Medium (default):**
+
+```js
+tl.to(old, { filter: "blur(12px)", skewX: -8, x: -200, opacity: 0, duration: 0.4, ease: "power3.in" }, T);
+tl.fromTo(new,
+  { filter: "blur(12px)", skewX: 8, x: 200, opacity: 0 },
+  { filter: "blur(0px)", skewX: 0, x: 0, opacity: 1, duration: 0.4, ease: "power3.out" }, T + 0.15);
+```
+
+**Calm (heavier blur, gentler motion):**
+
+```js
+tl.to(old, { filter: "blur(20px)", skewX: -4, x: -100, opacity: 0, duration: 0.6, ease: "power1.in" }, T);
+tl.fromTo(new,
+  { filter: "blur(20px)", skewX: 4, x: 100, opacity: 0 },
+  { filter: "blur(0px)", skewX: 0, x: 0, opacity: 1, duration: 0.6, ease: "power1.out" }, T + 0.3);
+```

package/dist/__w3kits/assets/design-templates/hyperframes/references/transitions/css-cover.md

@@ -0,0 +1,43 @@
+## Cover
+
+### Staggered Color Blocks
+
+Full-screen (1920x1080) colored divs slide across staggered. Scene swaps while covered.
+
+**2-block** (standard):
+
+```js
+tl.set("#wipe-a", { x: -1920 }, T - 0.01);
+tl.set("#wipe-b", { x: -1920 }, T - 0.01);
+tl.to("#wipe-a", { x: 0, duration: 0.25, ease: "power3.inOut" }, T);
+tl.to("#wipe-b", { x: 0, duration: 0.25, ease: "power3.inOut" }, T + 0.06);
+tl.set(old, { opacity: 0 }, T + 0.2);
+tl.set(new, { opacity: 1 }, T + 0.2);
+tl.to("#wipe-a", { x: 1920, duration: 0.25, ease: "power3.inOut" }, T + 0.28);
+tl.to("#wipe-b", { x: 1920, duration: 0.25, ease: "power3.inOut" }, T + 0.34);
+```
+
+**5-block** (dense variant): same pattern with 5 blocks at 0.04s stagger. Use composition palette colors.
+
+### Horizontal Blinds
+
+Full-width strips slide across staggered. Each strip: `width: 1920px; height: Xpx`.
+
+**6 strips** (180px each): `0.03s` stagger
+**12 strips** (90px each): `0.018s` stagger
+
+```js
+for (var i = 0; i < N; i++) {
+  tl.set("#blind-h-" + i, { x: -1920 }, T - 0.01);
+  tl.fromTo("#blind-h-" + i, { x: -1920 }, { x: 0, duration: 0.2, ease: "power3.inOut" }, T + i * stagger);
+}
+tl.set(old, { opacity: 0 }, T + coverTime);
+tl.set(new, { opacity: 1 }, T + coverTime);
+for (var i = 0; i < N; i++) {
+  tl.to("#blind-h-" + i, { x: 1920, duration: 0.2, ease: "power3.inOut" }, T + exitStart + i * stagger);
+}
+```
+
+### Vertical Blinds
+
+Same as horizontal but strips are tall and narrow, moving on Y axis.

package/dist/__w3kits/assets/design-templates/hyperframes/references/transitions/css-destruction.md

@@ -0,0 +1,95 @@
+## Destruction
+
+### Page Burn
+
+The outgoing scene literally burns away from a corner. A fire front expands with noise-based irregular edges, a canvas draws the scorched char line at the burn boundary, and individual text characters/elements chip off and fall with gravity as the fire reaches them. The incoming scene reveals behind the burn.
+
+This transition has three systems working together:
+
+1. **Fire geometry** — a radial front expanding from a corner (e.g., bottom-right) with noise-based irregularity for organic edges
+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.
+
+**Requirements:**
+
+- A `<canvas>` element for the burn edge overlay
+- A noise function for organic fire edge geometry
+- SVG clip-path with evenodd fill-rule for the inverted clip
+
+**Fire geometry (deterministic noise):**
+
+```js
+function noise(x) {
+  var ix = Math.floor(x),
+    fx = x - ix;
+  var a = Math.sin(ix * 127.1 + 311.7) * 43758.5453;
+  var b = Math.sin((ix + 1) * 127.1 + 311.7) * 43758.5453;
+  var t = fx * fx * (3 - 2 * fx);
+  return a - Math.floor(a) + (b - Math.floor(b) - (a - Math.floor(a))) * t;
+}
+
+function fireRadiusAtAngle(angle, progress) {
+  var base = progress * maxRadius;
+  return (
+    base +
+    noise(angle * 3 + progress * 4) * 50 +
+    noise(angle * 8 + progress * 9) * 20 +
+    noise(angle * 15 + progress * 15) * 8
+  );
+}
+```
+
+**Incoming scene timing:** The incoming scene should NOT be visible during the burn. As the fire consumes the outgoing scene, **black shows through the holes** — this is the dramatic part. The viewer watches content being destroyed against blackness.
+
+At ~90% through the burn, the incoming scene fades in SLOWLY from black — the background first, then content staggered. Use long, gentle fades (`power1.out`, 0.8-1.2s durations) so it feels like the new scene materializes from darkness, not a hard swap.
+
+```js
+// Scene 2 stays at opacity: 0 during the burn — black behind the fire
+tl.set("#s2-title", { opacity: 0 }, T);
+tl.set("#s2-subtitle", { opacity: 0 }, T);
+
+// At 90% through, scene bg fades in slowly from black
+var contentReveal = T + BURN_DURATION * 0.9;
+tl.to("#scene2", { opacity: 1, duration: 1.2, ease: "power1.out" }, contentReveal);
+
+// Content fades in staggered on top, even slower
+tl.to("#s2-title", { opacity: 1, duration: 1.0, ease: "power1.out" }, contentReveal + 0.5);
+tl.to("#s2-subtitle", { opacity: 1, duration: 0.8, ease: "power1.out" }, contentReveal + 0.7);
+```
+
+**Content burns with the page — no falling debris.** The clip-path on scene1 IS the effect — as the fire shape expands, everything behind the fire edge (text, images, lines) disappears naturally. Don't clone elements, don't create falling debris. The content is part of the page being consumed. The scorched canvas edge provides the visual char line at the burn boundary.
+
+**Hide scene1 via `tl.set` at burn end — NEVER in `onComplete`.** Using `onComplete` to hide scene1 is not reversible when scrubbing. Instead, use a `tl.set` at the exact burn end time:
+
+```js
+tl.to(
+  burnState,
+  {
+    progress: 1,
+    duration: BURN_DURATION,
+    ease: "none",
+    onUpdate: function () {
+      var wp = burnState.progress;
+      var scene1 = document.getElementById("scene1");
+      if (wp <= 0) {
+        scene1.style.clipPath = "none"; // fully visible when rewound
+      } else if (wp < 1) {
+        scene1.style.clipPath = buildClipPath(wp);
+      }
+      drawEdge(wp);
+    },
+    // NO onComplete — use tl.set instead
+  },
+  T,
+);
+
+// Hide scene1 at exact burn end — reversible via timeline
+tl.set("#scene1", { opacity: 0 }, T + BURN_DURATION);
+tl.set("#scene1", { clipPath: "none" }, T + BURN_DURATION);
+```
+
+The `onUpdate` handles clip-path and canvas edge per-frame. The `tl.set` handles the final hide — and GSAP automatically reverses it when scrubbing backward, restoring scene1 to `opacity: 1`.
+
+The `onUpdate` callback is the key — it runs every frame to advance the clip-path and canvas edge in sync with the timeline.

package/dist/__w3kits/assets/design-templates/hyperframes/references/transitions/css-dissolve.md

@@ -0,0 +1,66 @@
+## Dissolve
+
+### Crossfade
+
+Simple opacity swap. The baseline.
+
+```js
+tl.to(old, { opacity: 0, duration: 0.5, ease: "power2.inOut" }, T);
+tl.fromTo(new, { opacity: 0 }, { opacity: 1, duration: 0.5, ease: "power2.inOut" }, T);
+```
+
+### Blur Crossfade
+
+Dissolve with blur + scale shift. **Scale blur amount by energy** — see SKILL.md "Blur Intensity by Energy" section. The examples below show the medium (default) version. For calm compositions, increase to 20-30px with a 0.3-0.5s hold at peak blur. For high-energy, decrease to 3-6px with no hold.
+
+**Medium (default):**
+
+```js
+tl.to(old, { filter: "blur(10px)", scale: 1.03, opacity: 0, duration: 0.5, ease: "power2.inOut" }, T);
+tl.fromTo(new,
+  { filter: "blur(10px)", scale: 0.97, opacity: 0 },
+  { filter: "blur(0px)", scale: 1, opacity: 1, duration: 0.5, ease: "power2.inOut" }, T + 0.1);
+```
+
+**Calm (wellness, luxury) — heavy blur, holds at abstract color:**
+
+```js
+tl.to(old, { filter: "blur(25px)", scale: 1.05, duration: 0.6, ease: "power1.in" }, T);
+tl.to(old, { opacity: 0, duration: 0.4, ease: "power1.in" }, T + 0.4);
+tl.fromTo(new,
+  { filter: "blur(25px)", scale: 0.95, opacity: 0 },
+  { filter: "blur(25px)", scale: 0.95, opacity: 1, duration: 0.3, ease: "power1.inOut" }, T + 0.5);
+tl.to(new, { filter: "blur(0px)", scale: 1, duration: 0.6, ease: "power1.out" }, T + 0.8);
+```
+
+### Focus Pull
+
+Outgoing slowly blurs while incoming fades in sharp. Depth-of-field feel. **Scale blur amount and hold duration by energy.**
+
+**Medium:**
+
+```js
+tl.to(old, { filter: "blur(15px)", duration: 0.5, ease: "power1.in" }, T);
+tl.to(old, { opacity: 0, duration: 0.3, ease: "power2.in" }, T + 0.25);
+tl.fromTo(new, { opacity: 0 }, { opacity: 1, duration: 0.3, ease: "power2.out" }, T + 0.25);
+```
+
+**Calm — slow rack focus with long hold at peak defocus:**
+
+```js
+tl.to(old, { filter: "blur(30px)", duration: 0.8, ease: "power1.in" }, T);
+tl.to(old, { opacity: 0, duration: 0.5, ease: "power1.in" }, T + 0.6);
+tl.fromTo(new, { opacity: 0, filter: "blur(20px)" },
+  { opacity: 1, filter: "blur(20px)", duration: 0.3, ease: "power1.inOut" }, T + 0.7);
+tl.to(new, { filter: "blur(0px)", duration: 0.6, ease: "power1.out" }, T + 1.0);
+```
+
+### Color Dip
+
+Fade to solid color, hold, fade up new scene.
+
+```js
+tl.to(old, { opacity: 0, duration: 0.2, ease: "power2.in" }, T);
+// Background color shows through
+tl.fromTo(new, { opacity: 0 }, { opacity: 1, duration: 0.2, ease: "power2.out" }, T + 0.25);
+```

package/dist/__w3kits/assets/design-templates/hyperframes/references/transitions/css-distortion.md

@@ -0,0 +1,45 @@
+## Distortion
+
+### Glitch
+
+RGB-tinted overlays (NOT multiply blend — use normal blending at 35% opacity) jitter with large offsets. Scene itself also jitters.
+
+```js
+tl.set("#glitch-r", { opacity: 1, x: 40, y: -8 }, T);
+tl.set("#glitch-g", { opacity: 1, x: -30, y: 12 }, T);
+tl.set("#glitch-b", { opacity: 1, x: 15, y: -20 }, T);
+tl.set(old, { x: -15 }, T);
+// 6 jitter frames at 0.03s intervals with big offsets (±30-60px)
+// ... swap and clear at T + 0.2
+```
+
+### Chromatic Aberration
+
+RGB overlays start aligned then spread apart (±80px), scene fades, converge on new scene.
+
+```js
+tl.set("#glitch-r", { opacity: 0.6, x: 0 }, T);
+tl.set("#glitch-g", { opacity: 0.6, x: 0 }, T);
+tl.set("#glitch-b", { opacity: 0.6, x: 0 }, T);
+tl.to("#glitch-r", { x: -80, opacity: 0.8, duration: 0.3, ease: "power2.in" }, T);
+tl.to("#glitch-b", { x: 80, opacity: 0.8, duration: 0.3, ease: "power2.in" }, T);
+tl.to("#glitch-g", { y: 30, duration: 0.3, ease: "power2.in" }, T);
+// Swap at T + 0.3, converge back at T + 0.3
+```
+
+### Ripple
+
+Rapid oscillation (±30px) + scale distortion (0.97-1.03) + increasing blur. Swap at peak distortion.
+
+```js
+tl.to(old, { x: 30, scale: 1.02, duration: 0.04, ease: "none" }, T);
+tl.to(old, { x: -25, scale: 0.98, filter: "blur(4px)", duration: 0.04, ease: "none" }, T + 0.04);
+// ... more oscillations with increasing blur
+// Swap at peak, incoming stabilizes with decreasing wobble
+```
+
+### VHS Tape
+
+Clone scene into 20 horizontal strips (each 54px, clip-path'd). Each strip shifts x independently with seeded pseudo-random offsets at per-bar random intervals. Add red+blue chromatic offset copies on each strip (z-index above main, 35% opacity). Make strips wider than frame (2020px at left:-50px) so edges never show.
+
+See SKILL.md for clone-based implementation pattern.

package/dist/__w3kits/assets/design-templates/hyperframes/references/transitions/css-grid.md

@@ -0,0 +1,10 @@
+## Grid
+
+### Grid Dissolve
+
+Grid of colored cells covers the frame in a ripple from center. Scene swaps at 50% coverage. Cells fade out in ripple.
+
+**12-cell** (4x3, each 480x270): standard
+**120-cell** (12x10, each 160x108): dense variant — lower opacity (0.75), tighter ripple
+
+Cells are created dynamically in JS, sorted by distance from center for ripple stagger.

package/dist/__w3kits/assets/design-templates/hyperframes/references/transitions/css-light.md

@@ -0,0 +1,49 @@
+## Light
+
+### Light Leak
+
+Multiple warm-colored overlays wash across frame. Needs: a flat warm tint layer + 2-3 bright radial gradient divs, all larger than the frame so edges are never visible.
+
+```js
+// Warm tint washes over entire frame
+tl.to("#leak-warm", { opacity: 0.4, duration: 0.3, ease: "power1.in" }, T);
+// Bright leak elements drift in
+tl.to("#leak-1", { opacity: 0.9, x: 300, duration: 0.5, ease: "sine.inOut" }, T + 0.05);
+tl.to("#leak-2", { opacity: 0.8, x: 200, duration: 0.6, ease: "sine.inOut" }, T + 0.1);
+// Peak warmth then swap
+tl.to("#leak-warm", { opacity: 0.6, duration: 0.15, ease: "power2.in" }, T + 0.35);
+tl.set(old, { opacity: 0 }, T + 0.45);
+tl.set(new, { opacity: 1 }, T + 0.45);
+// Leak fades
+tl.to("#leak-warm", { opacity: 0, duration: 0.4, ease: "power2.out" }, T + 0.5);
+tl.to("#leak-1", { opacity: 0, x: 600, duration: 0.35, ease: "power1.out" }, T + 0.5);
+```
+
+### Overexposure Burn
+
+Scene progressively blows out to white using CSS `filter: brightness()`, then white overlay fades in. Swap at peak white. White recedes to reveal new scene.
+
+```js
+tl.to(old, { filter: "brightness(1.5)", scale: 1.03, duration: 0.2, ease: "power1.in" }, T);
+tl.to(old, { filter: "brightness(3)", scale: 1.06, duration: 0.2, ease: "power2.in" }, T + 0.2);
+tl.to("#flash-overlay", { opacity: 0.5, duration: 0.25, ease: "power1.in" }, T + 0.15);
+tl.to("#flash-overlay", { opacity: 1, duration: 0.15, ease: "power2.in" }, T + 0.4);
+tl.set(old, { opacity: 0, filter: "brightness(1)", scale: 1 }, T + 0.55);
+tl.set(new, { opacity: 1 }, T + 0.55);
+tl.to("#flash-overlay", { opacity: 0, duration: 0.35, ease: "power2.out" }, T + 0.55);
+```
+
+### Film Burn
+
+Staggered warm overlays (amber, orange, red) bleed from one edge. Each overlay is a large radial gradient div at high z-index.
+
+```js
+tl.to("#burn-a", { opacity: 1, x: -300, duration: 0.4, ease: "power1.in" }, T);
+tl.to("#burn-b", { opacity: 1, x: -500, duration: 0.5, ease: "power1.in" }, T + 0.05);
+tl.to("#burn-c", { opacity: 1, x: -200, duration: 0.45, ease: "power1.in" }, T + 0.1);
+tl.set(old, { opacity: 0 }, T + 0.35);
+tl.set(new, { opacity: 1 }, T + 0.35);
+tl.to("#burn-a", { opacity: 0, duration: 0.3, ease: "power2.out" }, T + 0.45);
+tl.to("#burn-b", { opacity: 0, duration: 0.3, ease: "power2.out" }, T + 0.5);
+tl.to("#burn-c", { opacity: 0, duration: 0.3, ease: "power2.out" }, T + 0.55);
+```