dsh-hyperframes 0.2.0 → 0.3.1

package/skills/gsap/references/effects.md

@@ -1,297 +0,0 @@
-# GSAP Effects for HyperFrames
-
-Drop-in animation patterns for HyperFrames compositions. Each effect is self-contained with HTML, CSS, and code.
-
-All effects follow HyperFrames composition rules — deterministic, no randomness, timelines registered via `window.__timelines`.
-
-## Table of Contents
-
-- [Typewriter](#typewriter)
-- [Audio Visualizer](#audio-visualizer)
-
----
-
-## Typewriter
-
-Reveal text character by character using GSAP's TextPlugin.
-
-### Required Plugin
-
-```html
-<script src="https://cdn.jsdelivr.net/npm/gsap@3.14.2/dist/gsap.min.js"></script>
-<script src="https://cdn.jsdelivr.net/npm/gsap@3.14.2/dist/TextPlugin.min.js"></script>
-<script>
-  gsap.registerPlugin(TextPlugin);
-</script>
-```
-
-### Basic Typewriter
-
-```js
-const text = "Hello, world!";
-const cps = 10; // chars per second: 3-5 dramatic, 8-12 conversational, 15-20 energetic
-tl.to(
-  "#typed-text",
-  { text: { value: text }, duration: text.length / cps, ease: "none" },
-  startTime,
-);
-```
-
-### With Blinking Cursor
-
-Three rules:
-
-1. **One cursor visible at a time** — hide previous before showing next.
-2. **Cursor must blink when idle** — after typing, during pauses.
-3. **No gap between text and cursor** — elements must be flush in HTML.
-
-```html
-<span id="typed-text"></span><span id="cursor" class="cursor-blink">|</span>
-```
-
-```css
-@keyframes blink {
-  0%,
-  100% {
-    opacity: 1;
-  }
-  50% {
-    opacity: 0;
-  }
-}
-.cursor-blink {
-  animation: blink 0.8s step-end infinite;
-}
-.cursor-solid {
-  animation: none;
-  opacity: 1;
-}
-.cursor-hide {
-  animation: none;
-  opacity: 0;
-}
-```
-
-Pattern: blink → solid (typing starts) → type → solid → blink (typing done).
-
-```js
-tl.call(() => cursor.classList.replace("cursor-blink", "cursor-solid"), [], startTime);
-tl.to("#typed-text", { text: { value: text }, duration: dur, ease: "none" }, startTime);
-tl.call(() => cursor.classList.replace("cursor-solid", "cursor-blink"), [], startTime + dur);
-```
-
-### Backspacing
-
-TextPlugin removes from front — wrong for backspace. Use manual substring removal:
-
-```js
-function backspace(tl, selector, word, startTime, cps) {
-  const el = document.querySelector(selector);
-  const interval = 1 / cps;
-  for (let i = word.length - 1; i >= 0; i--) {
-    tl.call(
-      () => {
-        el.textContent = word.slice(0, i);
-      },
-      [],
-      startTime + (word.length - i) * interval,
-    );
-  }
-  return word.length * interval;
-}
-```
-
-### Spacing with Static Text
-
-When a typewriter word sits next to static text, use `margin-left` on a wrapper span. Don't use flex gap (spaces cursor from text) or trailing space in static text (collapses when dynamic is empty).
-
-```html
-<div style="display:flex; align-items:baseline;">
-  <span style="font-size:40px; color:#555;">Ship something</span>
-  <span style="margin-left:14px;"><span id="word"></span><span id="cursor">|</span></span>
-</div>
-```
-
-### Word Rotation
-
-Type → hold → backspace → next word. Cursor blinks during every idle moment (holds, after backspace).
-
-```js
-words.forEach((word, i) => {
-  const typeDur = word.length / 10;
-  // Solid while typing
-  tl.call(() => cursor.classList.replace("cursor-blink", "cursor-solid"), [], offset);
-  tl.to("#typed-text", { text: { value: word }, duration: typeDur, ease: "none" }, offset);
-  // Blink during hold
-  tl.call(() => cursor.classList.replace("cursor-solid", "cursor-blink"), [], offset + typeDur);
-  offset += typeDur + 1.5; // hold
-
-  if (i < words.length - 1) {
-    tl.call(() => cursor.classList.replace("cursor-blink", "cursor-solid"), [], offset);
-    const clearDur = backspace(tl, el, word, offset, 20);
-    tl.call(() => cursor.classList.replace("cursor-solid", "cursor-blink"), [], offset + clearDur);
-    offset += clearDur + 0.3;
-  }
-});
-```
-
-### Appending Words
-
-Build a sentence word-by-word into the same element:
-
-```js
-let accumulated = "";
-words.forEach((word) => {
-  const target = accumulated + (accumulated ? " " : "") + word;
-  const newChars = target.length - accumulated.length;
-  tl.to("#typed-text", { text: { value: target }, duration: newChars / 10, ease: "none" }, offset);
-  accumulated = target;
-  offset += newChars / 10 + 0.3;
-});
-```
-
-### Multi-Line Cursor Handoff
-
-When handing off between typewriter lines: hide previous → blink new → pause → solid when typing. Never go hidden→solid (skips idle state).
-
-```js
-tl.call(
-  () => {
-    prevCursor.classList.replace("cursor-blink", "cursor-hide");
-    nextCursor.classList.replace("cursor-hide", "cursor-blink");
-  },
-  [],
-  handoffTime,
-);
-
-const typeStart = handoffTime + 0.5; // brief blink pause
-tl.call(() => nextCursor.classList.replace("cursor-blink", "cursor-solid"), [], typeStart);
-tl.to("#next-text", { text: { value: text }, duration: dur, ease: "none" }, typeStart);
-tl.call(() => nextCursor.classList.replace("cursor-solid", "cursor-blink"), [], typeStart + dur);
-```
-
-### Timing Guide
-
-| CPS   | Feel             | Good for                   |
-| ----- | ---------------- | -------------------------- |
-| 3-5   | Slow, deliberate | Dramatic reveals, suspense |
-| 8-12  | Natural typing   | Dialogue, narration        |
-| 15-20 | Fast, energetic  | Tech demos, code           |
-| 30+   | Near-instant     | Filling long blocks        |
-
----
-
-## Audio Visualizer
-
-Pre-extract audio data, drive canvas/DOM rendering from GSAP timeline.
-
-### Extract Audio Data
-
-```bash
-python scripts/extract-audio-data.py audio.mp3 -o audio-data.json
-python scripts/extract-audio-data.py video.mp4 --fps 30 --bands 16 -o audio-data.json
-```
-
-Requires ffmpeg and numpy.
-
-### Data Format
-
-```json
-{
-  "fps": 30, "totalFrames": 5415,
-  "frames": [{ "time": 0.0, "rms": 0.42, "bands": [0.8, 0.6, 0.3, ...] }]
-}
-```
-
-- **rms** (0-1): overall loudness, normalized across track
-- **bands[]** (0-1): frequency magnitudes. Index 0 = bass, higher = treble. Each normalized independently.
-
-### Loading the Data
-
-```js
-// Option A: inline (small files, under ~500KB)
-var AUDIO_DATA = {
-  /* paste audio-data.json contents */
-};
-
-// Option B: sync XHR (large files — must be synchronous for deterministic timeline construction)
-var xhr = new XMLHttpRequest();
-xhr.open("GET", "audio-data.json", false);
-xhr.send();
-var AUDIO_DATA = JSON.parse(xhr.responseText);
-```
-
-**Do NOT use async `fetch()` to load audio data.** HyperFrames requires synchronous timeline construction — the capture engine reads `window.__timelines` synchronously after page load. Building timelines inside `.then()` callbacks means the timeline isn't ready when capture starts.
-
-### Rendering Approaches
-
-**Canvas 2D** (most common — bars, waveforms, circles, gradients):
-
-```js
-for (let f = 0; f < AUDIO_DATA.totalFrames; f++) {
-  tl.call(
-    () => {
-      const frame = AUDIO_DATA.frames[f];
-      ctx.clearRect(0, 0, canvas.width, canvas.height);
-      // draw using frame.rms and frame.bands
-    },
-    [],
-    f / AUDIO_DATA.fps,
-  );
-}
-```
-
-**WebGL / Three.js** — HyperFrames patches `THREE.Clock` for deterministic time. Update uniforms from audio data each frame.
-
-**DOM Elements** — fine for < 20 elements, less performant than Canvas for many.
-
-### Spatial Mapping
-
-- **Horizontal**: bass left, treble right (iterate bands left-to-right)
-- **Vertical**: bass bottom, treble top
-- **Circular**: bass at 12 o'clock, wrap clockwise; mirror for full circle
-
-### Smoothing
-
-```js
-let prev = null;
-const smoothing = 0.25; // 0.1-0.2 snappy, 0.3-0.5 flowing
-function smooth(f) {
-  const raw = AUDIO_DATA.frames[f];
-  if (!prev) {
-    prev = { rms: raw.rms, bands: [...raw.bands] };
-    return prev;
-  }
-  prev = {
-    rms: prev.rms * smoothing + raw.rms * (1 - smoothing),
-    bands: raw.bands.map((b, i) => prev.bands[i] * smoothing + b * (1 - smoothing)),
-  };
-  return prev;
-}
-```
-
-### Motion Principles
-
-- **Bass drives big moves** — scale, glow, position shifts
-- **Treble drives detail** — shimmer, flicker, edge effects
-- **RMS drives globals** — background brightness, overall energy
-- Pick 2-3 properties to animate. More looks noisy.
-- Keep minimums above zero — quiet sections need life.
-
-### Band Count
-
-| Bands | Detail    | Good for                   |
-| ----- | --------- | -------------------------- |
-| 4     | Low       | Background glow, pulsing   |
-| 8     | Medium    | Bar charts, basic spectrum |
-| 16    | High      | Detailed EQ (default)      |
-| 32    | Very high | Dense radial layouts       |
-
-### Layering
-
-Layer multiple canvases with CSS z-index for depth — a background layer driven by bass/rms and a foreground layer driven by individual bands creates depth without complexity.
-
-```html
-<canvas id="bg-layer" style="position:absolute;top:0;left:0;z-index:1;"></canvas>
-<canvas id="main-layer" style="position:absolute;top:0;left:0;z-index:2;"></canvas>
-```

package/skills/hyperframes/patterns.md

@@ -1,118 +0,0 @@
-# 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/captions.md

@@ -1,132 +0,0 @@
-# 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.