dsh-hyperframes 0.1.0

package/skills/hyperframes/patterns.md

@@ -0,0 +1,118 @@
+# Composition Patterns
+
+## Picture-in-Picture (Video in a Frame)
+
+Animate a wrapper div for position/size. The video fills the wrapper. The wrapper has NO data attributes.
+
+```html
+<div
+  id="pip-frame"
+  style="position:absolute;top:0;left:0;width:1920px;height:1080px;z-index:50;overflow:hidden;"
+>
+  <video
+    id="el-video"
+    data-start="0"
+    data-duration="60"
+    data-track-index="0"
+    src="talking-head.mp4"
+    muted
+    playsinline
+  ></video>
+</div>
+```
+
+```js
+tl.to(
+  "#pip-frame",
+  { top: 700, left: 1360, width: 500, height: 280, borderRadius: 16, duration: 1 },
+  10,
+);
+tl.to("#pip-frame", { left: 40, duration: 0.6 }, 30);
+```
+
+## Title Card with Fade
+
+```html
+<div
+  id="title-card"
+  data-start="0"
+  data-duration="5"
+  data-track-index="5"
+  style="display:flex;align-items:center;justify-content:center;background:#111;z-index:60;"
+>
+  <h1 style="font-size:64px;color:#fff;opacity:0;">My Video Title</h1>
+</div>
+```
+
+```js
+tl.to("#title-card h1", { opacity: 1, duration: 0.6 }, 0.3);
+tl.to("#title-card", { opacity: 0, duration: 0.5 }, 4);
+```
+
+## Slide Show with Section Headers
+
+Use separate elements on the same track, each with its own time range. Slides auto-mount/unmount based on `data-start`/`data-duration`.
+
+```html
+<div class="slide" data-start="0" data-duration="30" data-track-index="3">...</div>
+<div class="slide" data-start="30" data-duration="25" data-track-index="3">...</div>
+<div class="slide" data-start="55" data-duration="20" data-track-index="3">...</div>
+```
+
+## Top-Level Composition Example
+
+```html
+<div
+  id="comp-1"
+  data-composition-id="my-video"
+  data-start="0"
+  data-duration="60"
+  data-width="1920"
+  data-height="1080"
+>
+  <!-- Primitive clips -->
+  <video
+    id="el-1"
+    data-start="0"
+    data-duration="10"
+    data-track-index="0"
+    src="..."
+    muted
+    playsinline
+  ></video>
+  <video
+    id="el-2"
+    data-start="el-1"
+    data-duration="8"
+    data-track-index="0"
+    src="..."
+    muted
+    playsinline
+  ></video>
+  <img id="el-3" data-start="5" data-duration="4" data-track-index="1" src="..." />
+  <audio id="el-4" data-start="0" data-duration="30" data-track-index="2" src="..." />
+
+  <!-- Sub-compositions loaded from files -->
+  <div
+    id="el-5"
+    data-composition-id="intro-anim"
+    data-composition-src="compositions/intro-anim.html"
+    data-start="0"
+    data-track-index="3"
+  ></div>
+
+  <div
+    id="el-6"
+    data-composition-id="captions"
+    data-composition-src="compositions/caption-overlay.html"
+    data-start="0"
+    data-track-index="4"
+  ></div>
+
+  <script>
+    // Just register the timeline — framework auto-nests sub-compositions
+    const tl = gsap.timeline({ paused: true });
+    window.__timelines["my-video"] = tl;
+  </script>
+</div>
+```

package/skills/hyperframes/references/audio-reactive.md

@@ -0,0 +1,76 @@
+# Audio-Reactive Animation
+
+Drive visuals from music, voice, or sound. Any GSAP-animatable property can respond to pre-extracted audio data.
+
+## Audio Data Format
+
+```js
+var AUDIO_DATA = {
+  fps: 30,
+  totalFrames: 900,
+  frames: [{ bands: [0.82, 0.45, 0.31, ...] }, ...]
+};
+```
+
+- `frames[i].bands[]` — frequency band amplitudes, 0-1. Index 0 = bass, higher = treble.
+- Each band normalized independently across the full track.
+
+## Mapping Audio to Visuals
+
+| Audio signal           | Visual property                   | Effect                     |
+| ---------------------- | --------------------------------- | -------------------------- |
+| Bass (bands[0])        | `scale`                           | Pulse on beat              |
+| Treble (bands[12-14])  | `textShadow`, `boxShadow`         | Glow intensity             |
+| Overall amplitude      | `opacity`, `y`, `backgroundColor` | Breathe, lift, color shift |
+| Mid-range (bands[4-8]) | `borderRadius`, `width`           | Shape morphing             |
+
+Any GSAP-tweenable property works — `clipPath`, `filter`, SVG attributes, CSS custom properties.
+
+## Content, Not Medium
+
+Audio provides **timing and intensity**. The visual vocabulary comes from the narrative.
+
+**Never add:** equalizer bars, spectrum analyzers, waveform displays, musical notes clip art, generic particle systems, rainbow color cycling, strobing white on beats, abstract pulsing orbs.
+
+**Instead:** Let content guide the visual and audio drive its behavior. Bass makes warmth _swell_. Treble sharpens _contrast_. The visual choice comes from "what does this piece feel like?"
+
+## Sampling Pattern
+
+Audio reactivity requires per-frame sampling via a `for` loop with `tl.call()`, not a single tween:
+
+```js
+// ✅ Correct — sample every frame
+for (var f = 0; f < AUDIO_DATA.totalFrames; f++) {
+  tl.call(
+    (function (frame) {
+      return function () {
+        draw(frame);
+      };
+    })(AUDIO_DATA.frames[f]),
+    [],
+    f / AUDIO_DATA.fps,
+  );
+}
+
+// ❌ Wrong — single tween, doesn't react to audio
+gsap.to(".el", { scale: 1.2, duration: totalDuration });
+```
+
+Without per-frame sampling, the composition doesn't actually react to audio.
+
+## textShadow Gotcha
+
+`textShadow` on a parent container with semi-transparent children (e.g., inactive caption words at `rgba(255,255,255,0.3)`) renders a visible glow rectangle behind all children. Fix: apply `scale` to the container for beat pulse, but apply `textShadow` to individual active words only.
+
+## Guidelines
+
+- **Subtlety for text** — 3-6% scale variation, soft glow. Heavy pulsing makes text unreadable.
+- **Go bigger on non-text** — backgrounds and shapes can handle 10-30% swings.
+- **Match the energy** — corporate = subtle; music video = dramatic.
+- **Deterministic** — pre-extracted data, no Web Audio API, no runtime analysis.
+
+## Constraints
+
+- All audio data must be pre-extracted (use `extract-audio-data.py` from the gsap skill's scripts/)
+- No `Math.random()` or `Date.now()`
+- Audio reactivity runs on the same GSAP timeline as everything else

package/skills/hyperframes/references/captions.md

@@ -0,0 +1,132 @@
+# Captions
+
+## Language Rule (Non-Negotiable)
+
+**Never use `.en` models unless the user explicitly states the audio is English.** `.en` models TRANSLATE non-English audio into English instead of transcribing it.
+
+1. User says the language → `--model small --language <code>` (no `.en`)
+2. User says English → `--model small.en`
+3. Language unknown → `--model small` (no `.en`, no `--language`) — auto-detects
+
+---
+
+Analyze spoken content to determine caption style. If user specifies a style, use that. Otherwise, detect tone from the transcript.
+
+## Transcript Source
+
+```json
+[
+  { "text": "Hello", "start": 0.0, "end": 0.5 },
+  { "text": "world.", "start": 0.6, "end": 1.2 }
+]
+```
+
+For transcription commands, whisper models, external APIs, see [transcript-guide.md](transcript-guide.md).
+
+## Style Detection (When No Style Specified)
+
+Read the full transcript before choosing. Four dimensions:
+
+**1. Visual feel** — corporate→clean; energetic→bold; storytelling→elegant; technical→precise; social→playful.
+
+**2. Color palette** — dark+bright for energy; muted for professional; high contrast for clarity; one accent color.
+
+**3. Font mood** — heavy/condensed for impact; clean sans for modern; rounded for friendly; serif for elegance.
+
+**4. Animation character** — scale-pop for punchy; gentle fade for calm; word-by-word for emphasis; typewriter for technical.
+
+## Per-Word Styling
+
+Scan for words deserving distinct treatment:
+
+- **Brand/product names** — larger size, unique color
+- **ALL CAPS** — scale boost, flash, accent color
+- **Numbers/statistics** — bold weight, accent color
+- **Emotional keywords** — exaggerated animation (overshoot, bounce)
+- **Call-to-action** — highlight, underline, color pop
+- **Marker highlight** — for beyond-color emphasis, see [css-patterns.md](css-patterns.md)
+
+## Script-to-Style Mapping
+
+| Tone         | Font mood                | Animation                          | Color                       | Size    |
+| ------------ | ------------------------ | ---------------------------------- | --------------------------- | ------- |
+| Hype/launch  | Heavy condensed, 800-900 | Scale-pop, back.out(1.7), 0.1-0.2s | Bright on dark              | 72-96px |
+| Corporate    | Clean sans, 600-700      | Fade+slide, power3.out, 0.3s       | White/neutral, muted accent | 56-72px |
+| Tutorial     | Mono/clean sans, 500-600 | Typewriter/fade, 0.4-0.5s          | High contrast, minimal      | 48-64px |
+| Storytelling | Serif/elegant, 400-500   | Slow fade, power2.out, 0.5-0.6s    | Warm muted tones            | 44-56px |
+| Social       | Rounded sans, 700-800    | Bounce, elastic.out, word-by-word  | Playful, colored pills      | 56-80px |
+
+## Word Grouping
+
+- **High energy:** 2-3 words. Quick turnover.
+- **Conversational:** 3-5 words. Natural phrases.
+- **Measured/calm:** 4-6 words. Longer groups.
+
+Break on sentence boundaries, 150ms+ pauses, or max word count.
+
+## Positioning
+
+- **Landscape (1920x1080):** Bottom 80-120px, centered
+- **Portrait (1080x1920):** Lower middle ~600-700px from bottom, centered
+- Never cover the subject's face
+- `position: absolute` — never relative
+- One caption group visible at a time
+
+## Text Overflow Prevention
+
+Use `window.__hyperframes.fitTextFontSize()`:
+
+```js
+var result = window.__hyperframes.fitTextFontSize(group.text.toUpperCase(), {
+  fontFamily: "Outfit",
+  fontWeight: 900,
+  maxWidth: 1600,
+});
+el.style.fontSize = result.fontSize + "px";
+```
+
+Options: `maxWidth` (1600 landscape, 900 portrait), `baseFontSize` (78), `minFontSize` (42), `fontWeight`, `fontFamily`, `step` (2).
+
+CSS safety nets: `max-width` on container, `overflow: visible` (**not** `hidden` — hidden clips scaled emphasis words and glow effects), `position: absolute`, explicit `height`. When per-word styling uses `scale > 1.0`, compute `maxWidth = safeWidth / maxScale` to leave headroom.
+
+**Container pattern:** Full-width absolute container, centered. Do **not** use `left: 50%; transform: translateX(-50%)` — causes clipping at composition edges.
+
+## Caption Exit Guarantee
+
+Every group **must** have a hard kill after exit animation:
+
+```js
+tl.to(groupEl, { opacity: 0, scale: 0.95, duration: 0.12, ease: "power2.in" }, group.end - 0.12);
+tl.set(groupEl, { opacity: 0, visibility: "hidden" }, group.end); // deterministic kill
+```
+
+Self-lint after building timeline — place **before** `window.__timelines[id] = tl` so it runs at composition init:
+
+```js
+GROUPS.forEach(function (group, gi) {
+  var el = document.getElementById("cg-" + gi);
+  if (!el) return;
+  tl.seek(group.end + 0.01);
+  var computed = window.getComputedStyle(el);
+  if (computed.opacity !== "0" && computed.visibility !== "hidden") {
+    console.warn(
+      "[caption-lint] group " + gi + " still visible at t=" + (group.end + 0.01).toFixed(2) + "s",
+    );
+  }
+});
+tl.seek(0);
+```
+
+## Further References
+
+- [dynamic-techniques.md](dynamic-techniques.md) — karaoke, clip-path reveals, slam words, scatter exits, elastic, 3D rotation
+- [transcript-guide.md](transcript-guide.md) — transcription commands, whisper models, external APIs
+- [css-patterns.md](css-patterns.md) — CSS+GSAP marker highlighting (deterministic, fully seekable)
+
+## Constraints
+
+- Deterministic. No `Math.random()`, no `Date.now()`.
+- Sync to transcript timestamps.
+- One group visible at a time.
+- Every group must have a hard `tl.set` kill at `group.end`.
+- The compiler embeds supported fonts automatically — just declare `font-family` in CSS.

package/skills/hyperframes/references/css-patterns.md

@@ -0,0 +1,373 @@
+# CSS Patterns for Marker Highlighting
+
+Pure CSS + GSAP implementations of all five MarkerHighlight.js drawing modes. Use these for deterministic rendering in HyperFrames compositions — no external library dependency, full GSAP timeline control.
+
+## Table of Contents
+
+- [1. Highlight Mode](#1-highlight-mode) — Yellow marker sweep behind text
+- [2. Circle Mode](#2-circle-mode) — Hand-drawn ellipse around text
+- [3. Burst Mode](#3-burst-mode) — Radiating lines from text
+- [4. Scribble Mode](#4-scribble-mode) — Chaotic scribble over text
+- [5. Sketchout Mode](#5-sketchout-mode) — Rough rectangle outline
+
+## 1. Highlight Mode
+
+Yellow marker sweep behind text. The most common mode.
+
+```html
+<span class="mh-highlight-wrap">
+  <span class="mh-highlight-bar" id="hl-1"></span>
+  <span class="mh-highlight-text">highlighted text</span>
+</span>
+```
+
+```css
+.mh-highlight-wrap {
+  position: relative;
+  display: inline;
+}
+.mh-highlight-bar {
+  position: absolute;
+  top: 0;
+  left: -6px;
+  right: -6px;
+  bottom: 0;
+  background: #fdd835;
+  opacity: 0.35;
+  transform: scaleX(0);
+  transform-origin: left center;
+  border-radius: 3px;
+  z-index: 0;
+}
+.mh-highlight-text {
+  position: relative;
+  z-index: 1;
+}
+```
+
+```js
+// Sweep in from left
+tl.to("#hl-1", { scaleX: 1, duration: 0.5, ease: "power2.out" }, 0.6);
+
+// Optional: skew for hand-drawn feel
+// gsap.set("#hl-1", { skewX: -2 });
+```
+
+### Multi-line Highlight
+
+Stagger bars across multiple lines:
+
+```js
+tl.to(
+  ".mh-highlight-bar",
+  {
+    scaleX: 1,
+    duration: 0.5,
+    ease: "power2.out",
+    stagger: 0.3,
+  },
+  0.6,
+);
+```
+
+## 2. Circle Mode
+
+Hand-drawn circle around text. Use `border-radius: 50%` with a slight rotation for organic feel.
+
+```html
+<span class="mh-circle-wrap">
+  <span class="mh-circle-text" id="circle-word">IMPORTANT</span>
+  <span class="mh-circle-ring" id="circle-1"></span>
+</span>
+```
+
+```css
+.mh-circle-wrap {
+  position: relative;
+  display: inline;
+}
+.mh-circle-text {
+  position: relative;
+  z-index: 1;
+}
+.mh-circle-ring {
+  position: absolute;
+  top: 50%;
+  left: 50%;
+  width: 130%;
+  height: 160%;
+  transform: translate(-50%, -50%) rotate(-3deg) scale(0);
+  border: 3px solid #e53935;
+  border-radius: 50%;
+  pointer-events: none;
+  z-index: 0;
+}
+```
+
+```js
+// Circle scales in with a wobble
+tl.to(
+  "#circle-1",
+  {
+    scale: 1,
+    rotation: -3,
+    duration: 0.6,
+    ease: "back.out(1.7)",
+    transformOrigin: "center center",
+  },
+  0.7,
+);
+```
+
+### Variations
+
+```css
+/* Tighter circle (for short words) */
+.mh-circle-ring.tight {
+  width: 150%;
+  height: 180%;
+}
+
+/* Squared circle (rounded rectangle) */
+.mh-circle-ring.rounded {
+  border-radius: 30%;
+  width: 120%;
+  height: 140%;
+}
+
+/* Ellipse (wider than tall) */
+.mh-circle-ring.ellipse {
+  width: 150%;
+  height: 130%;
+  border-radius: 50%;
+}
+```
+
+## 3. Burst Mode
+
+Radiating lines from text center. Each line is a positioned div rotated to its angle.
+
+```html
+<span class="mh-burst-wrap">
+  <span class="mh-burst-text">WOW</span>
+  <span class="mh-burst-container" id="burst-1">
+    <span class="mh-burst-line" style="--angle: 0deg; --len: 70px;"></span>
+    <span class="mh-burst-line" style="--angle: 30deg; --len: 55px;"></span>
+    <span class="mh-burst-line" style="--angle: 60deg; --len: 80px;"></span>
+    <span class="mh-burst-line" style="--angle: 90deg; --len: 45px;"></span>
+    <span class="mh-burst-line" style="--angle: 120deg; --len: 65px;"></span>
+    <span class="mh-burst-line" style="--angle: 150deg; --len: 75px;"></span>
+    <span class="mh-burst-line" style="--angle: 180deg; --len: 50px;"></span>
+    <span class="mh-burst-line" style="--angle: 210deg; --len: 60px;"></span>
+    <span class="mh-burst-line" style="--angle: 240deg; --len: 80px;"></span>
+    <span class="mh-burst-line" style="--angle: 270deg; --len: 40px;"></span>
+    <span class="mh-burst-line" style="--angle: 300deg; --len: 70px;"></span>
+    <span class="mh-burst-line" style="--angle: 330deg; --len: 55px;"></span>
+  </span>
+</span>
+```
+
+```css
+.mh-burst-wrap {
+  position: relative;
+  display: inline;
+}
+.mh-burst-text {
+  position: relative;
+  z-index: 2;
+}
+.mh-burst-container {
+  position: absolute;
+  top: 50%;
+  left: 50%;
+  width: 0;
+  height: 0;
+  z-index: 1;
+}
+.mh-burst-line {
+  position: absolute;
+  display: block;
+  width: 3px;
+  height: var(--len);
+  background: #1e88e5;
+  left: -1.5px;
+  top: calc(-1 * var(--len));
+  transform: rotate(var(--angle));
+  transform-origin: bottom center;
+  opacity: 0;
+}
+```
+
+```js
+// All lines burst outward simultaneously with slight stagger
+tl.fromTo(
+  "#burst-1 .mh-burst-line",
+  { scaleY: 0, opacity: 0 },
+  { scaleY: 1, opacity: 1, duration: 0.4, ease: "power2.out", stagger: 0.03 },
+  0.7,
+);
+```
+
+**Vary line lengths** (40-80px range) for an organic, hand-drawn feel. Equal lengths look mechanical.
+
+## 4. Scribble Mode
+
+Wavy SVG underlines and strikethroughs that draw themselves via `stroke-dashoffset`.
+
+```html
+<span class="mh-scribble-wrap">
+  <span class="mh-scribble-text">underlined text</span>
+  <svg class="mh-scribble-svg" viewBox="0 0 500 24" preserveAspectRatio="none">
+    <path
+      id="scribble-1"
+      d="M0,12 Q31,0 62,12 Q93,24 125,12 Q156,0 187,12 Q218,24 250,12 Q281,0 312,12 Q343,24 375,12 Q406,0 437,12 Q468,24 500,12"
+      fill="none"
+      stroke="#FDD835"
+      stroke-width="3"
+      stroke-linecap="round"
+    />
+  </svg>
+</div>
+```
+
+```css
+.mh-scribble-wrap {
+  position: relative;
+  display: inline;
+}
+.mh-scribble-text {
+  position: relative;
+  z-index: 1;
+}
+.mh-scribble-svg {
+  position: absolute;
+  left: 0;
+  bottom: -6px;
+  width: 100%;
+  height: 24px;
+  z-index: 0;
+}
+```
+
+```js
+// Measure path length and set initial dash state
+var path = document.querySelector("#scribble-1");
+var len = path.getTotalLength();
+gsap.set(path, { strokeDasharray: len, strokeDashoffset: len });
+
+// Draw the line
+tl.to(
+  "#scribble-1",
+  {
+    strokeDashoffset: 0,
+    duration: 0.8,
+    ease: "power1.inOut",
+  },
+  0.7,
+);
+```
+
+### Strikethrough Variant
+
+Position the SVG at `top: 50%; transform: translateY(-50%)` instead of `bottom: -6px`.
+
+### Wavy Path Generator
+
+Scale the path's viewBox width to match text width. The wave pattern `Q x1,y1 x2,y2` alternates between `y=0` and `y=24` for a natural wobble. Adjust the control points for tighter or looser waves:
+
+- **Tight waves**: smaller x-increments (25px per half-wave)
+- **Loose waves**: larger x-increments (50px per half-wave)
+- **Amplitude**: change the y range (0-24 for standard, 0-16 for subtle)
+
+## 5. Sketchout Mode
+
+Cross-hatch lines over de-emphasized text. Multiple angled lines create a "crossed out" effect.
+
+```html
+<span class="mh-sketchout-wrap">
+  <span class="mh-sketchout-text">old price</span>
+  <span class="mh-sketchout-lines" id="sketchout-1">
+    <span class="mh-sketchout-line mh-sketchout-fwd"></span>
+    <span class="mh-sketchout-line mh-sketchout-bwd"></span>
+  </span>
+</span>
+```
+
+```css
+.mh-sketchout-wrap {
+  position: relative;
+  display: inline;
+}
+.mh-sketchout-text {
+  position: relative;
+  z-index: 0;
+}
+.mh-sketchout-lines {
+  position: absolute;
+  top: 0;
+  left: -4px;
+  right: -4px;
+  bottom: 0;
+  overflow: hidden;
+  z-index: 1;
+}
+.mh-sketchout-line {
+  position: absolute;
+  display: block;
+  top: 50%;
+  left: 0;
+  width: 100%;
+  height: 2px;
+  background: #e53935;
+  transform-origin: left center;
+  transform: scaleX(0);
+}
+.mh-sketchout-fwd {
+  transform: scaleX(0) rotate(-12deg);
+}
+.mh-sketchout-bwd {
+  transform: scaleX(0) rotate(12deg);
+}
+```
+
+```js
+// Forward slash draws first
+tl.to(
+  "#sketchout-1 .mh-sketchout-fwd",
+  {
+    scaleX: 1,
+    duration: 0.3,
+    ease: "power2.out",
+  },
+  1.0,
+);
+
+// Backward slash follows
+tl.to(
+  "#sketchout-1 .mh-sketchout-bwd",
+  {
+    scaleX: 1,
+    duration: 0.3,
+    ease: "power2.out",
+  },
+  1.15,
+);
+```
+
+## Combining Modes in Captions
+
+Use mode cycling for visual variety across caption groups:
+
+```js
+var MODES = ["highlight", "circle", "burst", "scribble"];
+
+GROUPS.forEach(function (group, gi) {
+  var mode = MODES[gi % MODES.length];
+  // Apply the mode's CSS pattern to emphasis words in this group
+  group.emphasisWords.forEach(function (word) {
+    applyMode(word.el, mode, tl, word.start);
+  });
+});
+```
+
+Cycle every 2-3 groups for high energy, every 3-4 for medium, every 4-5 for low.