@mevdragon/vidfarm-devcli 0.13.0 → 0.15.0

package/.agents/skills/hyperframes-animation/rules/gsap-effects.md

@@ -0,0 +1,299 @@
+# GSAP Effects for HyperFrames
+
+Drop-in animation patterns. Each effect is self-contained (HTML + CSS + JS) and follows the HyperFrames seek-driven contract — deterministic, no randomness, timeline registered on `window.__timelines`.
+
+## Index
+
+- [Typewriter](#typewriter) — character-by-character text reveal with optional cursor / backspace / word rotation
+- [Audio Visualizer](#audio-visualizer) — pre-extract audio data, drive Canvas/DOM rendering from the timeline
+
+---
+
+## 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` (it spaces the cursor from the text) and don't put a trailing space in the static text (it collapses when the dynamic span 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
+let offset = 0;
+words.forEach((word, i) => {
+  const typeDur = word.length / 10;
+  tl.call(() => cursor.classList.replace("cursor-blink", "cursor-solid"), [], offset);
+  tl.to("#typed-text", { text: { value: word }, duration: typeDur, ease: "none" }, offset);
+  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, "#typed-text", 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 = "";
+let offset = 0;
+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
+
+Handing off between typewriter lines: hide previous → blink new → pause → solid when typing. Never go `hidden → solid` (skips the idle blink).
+
+```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 a single `tl.call(...)` per frame. **Do not** use the Web Audio API at render time — there's no playback during seek.
+
+### Extract Audio Data
+
+Use the bundled extractor (requires `ffmpeg` and Python `numpy`):
+
+```bash
+python skills/hyperframes-creative/scripts/extract-audio-data.py audio.mp3 -o audio-data.json
+python skills/hyperframes-creative/scripts/extract-audio-data.py video.mp4 --fps 30 --bands 16 -o audio-data.json
+```
+
+### 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 the track.
+- **`bands[]`** (0-1) — frequency magnitudes. Index 0 = bass, higher index = treble. Each band normalized independently.
+
+### Loading the Data (Synchronously)
+
+```js
+// Option A — inline (small files, under ~500 KB)
+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()`.** HyperFrames reads `window.__timelines` synchronously after page load — building the timeline inside `.then()` means the timeline isn't ready when capture starts.
+
+### Driving the Timeline
+
+**Canvas 2D** — most common (bars, waveforms, circles, gradients):
+
+```js
+const canvas = document.getElementById("viz");
+const ctx = canvas.getContext("2d");
+
+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 fewer than ~20 elements, slower than Canvas for many.
+
+### 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;
+}
+```
+
+### 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 a full circle
+
+### 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 still 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 per-element 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/.agents/skills/hyperframes-animation/rules/hacker-flip-3d.md

@@ -0,0 +1,223 @@
+---
+name: hacker-flip-3d
+description: Character-level 3D rotation with random glyph substitution for a decryption reveal effect.
+metadata:
+  tags: text, 3d, reveal, decode, hacker, randomization, perspective
+---
+
+# Hacker Flip 3D Reveal
+
+Characters flip down from 90° in 3D while cycling through random glyphs, then settle on the target character. Creates a "decryption" or airport flap-display reveal.
+
+## How It Works
+
+Each character gets its own per-char tween from `rotateX: 90deg` (hidden) to `rotateX: 0deg` (revealed), staggered across the word. During the flip:
+
+1. **Phase A (0 → ~`REVEAL_THRESHOLD` progress)**: character displays a randomly-substituted glyph that flickers (changes every `FLICKER_RATE` frames)
+2. **Phase B (`REVEAL_THRESHOLD` → 1.0 progress)**: character displays the REAL target character, settling into its final upright position
+
+The `REVEAL_THRESHOLD` separates "scrambled" from "revealed" — by the time the flip is mostly done, viewer sees the correct letter clicking into place.
+
+## HTML
+
+```html
+<div
+  class="scene"
+  id="hacker-flip-scene"
+  data-composition-id="hacker-flip-scene"
+  data-start="0"
+  data-duration="3"
+  data-track-index="0"
+>
+  <div class="hacker-text-wrap" id="hacker-text" data-target="{phrase}">
+    <!-- Per-char spans get injected by setup script below.
+         Ghost placeholder (data-ghost) is rendered identically to reserve width. -->
+  </div>
+</div>
+```
+
+`{phrase}` is the target word the flip resolves to (typically a brand or short label).
+
+## CSS
+
+```css
+.scene {
+  position: relative;
+  width: 100%;
+  height: 100%;
+  display: grid;
+  place-items: center;
+  background: {bgColor};
+  perspective: 1500px; /* REQUIRED — without this rotateX renders flat */
+}
+
+.hacker-text-wrap {
+  font-family: {monoFont};      /* monospace recommended so flicker glyphs hold width */
+  font-weight: 900;
+  font-size: HACKER_FONT_SIZE;
+  color: {textColor};
+  letter-spacing: 4px;
+  display: flex;
+  /* Ghost / live chars are absolutely stacked; container reserves layout width */
+  position: relative;
+}
+
+.hacker-char {
+  display: inline-block;
+  /* Hinge at the bottom edge — flap-display look */
+  transform-origin: bottom;
+  transform-style: preserve-3d;
+  /* Will-change improves render perf */
+  will-change: transform, opacity;
+}
+
+/* Ghost placeholder is hidden but reserves width for variable-glyph fonts.
+   Without this, narrow target glyphs collapse width when displayed and
+   characters shift horizontally during flicker. */
+.hacker-ghost {
+  opacity: 0;
+  pointer-events: none;
+}
+```
+
+## GSAP Timeline + Random Glyph Logic
+
+```html
+<script src="https://cdn.jsdelivr.net/npm/gsap@3.14.2/dist/gsap.min.js"></script>
+<script>
+  window.__timelines = window.__timelines || {};
+
+  const wrap = document.getElementById("hacker-text");
+  const targetWord = wrap.dataset.target;
+  const GLYPHS = "ABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789!@#$%&*";
+
+  // Build live chars + ghost placeholders (ghost keeps layout width stable)
+  wrap.innerHTML = "";
+  const ghostRow = document.createElement("div");
+  ghostRow.className = "hacker-ghost";
+  ghostRow.style.display = "inline-flex";
+  ghostRow.style.position = "absolute";
+  ghostRow.style.left = "0";
+  ghostRow.style.top = "0";
+  ghostRow.textContent = targetWord;
+  wrap.appendChild(ghostRow);
+
+  const charEls = [];
+  const liveRow = document.createElement("div");
+  liveRow.style.display = "inline-flex";
+  liveRow.style.position = "relative";
+  for (const ch of targetWord) {
+    const span = document.createElement("span");
+    span.className = "hacker-char";
+    span.textContent = ch === " " ? " " : ch;
+    span.dataset.target = ch;
+    liveRow.appendChild(span);
+    charEls.push(span);
+  }
+  wrap.appendChild(liveRow);
+
+  // Deterministic "random" — seeded by char index + frame group so the same
+  // frame always yields the same glyph (HF seek determinism).
+  function pseudoGlyph(seed) {
+    const h = ((seed * 9301 + 49297) % 233280) / 233280;
+    return GLYPHS[Math.floor(h * GLYPHS.length)];
+  }
+
+  const tl = gsap.timeline({ paused: true });
+
+  // Per-char flip — stagger across the word
+  charEls.forEach((el, i) => {
+    const state = { p: 0 };
+    tl.to(
+      state,
+      {
+        p: 1,
+        duration: FLIP_DURATION,
+        ease: "power3.out",
+        onUpdate: () => {
+          // Phase A: random glyph flickering. Phase B: real character.
+          const progress = state.p;
+          if (progress < REVEAL_THRESHOLD) {
+            // Update glyph every FLICKER_RATE worth of progress
+            const flickerSeed = i * 1000 + Math.floor(progress * 100);
+            el.textContent = pseudoGlyph(flickerSeed);
+          } else {
+            el.textContent = el.dataset.target === " " ? " " : el.dataset.target;
+          }
+          // Flip rotateX from 90 (down) to 0 (upright)
+          const rotateX = 90 - progress * 90;
+          const opacity = Math.min(1, progress * 2);
+          el.style.transform = `rotateX(${rotateX}deg)`;
+          el.style.opacity = opacity;
+        },
+      },
+      i * CHAR_STAGGER,
+    );
+  });
+
+  window.__timelines["hacker-flip-scene"] = tl;
+</script>
+```
+
+## How to Choose Values
+
+- **HACKER_FONT_SIZE** — font-size of the flip text in px.
+  - Range: 6-10% of viewport min-dimension; the flip text is the focal beat, scale accordingly
+  - Constraints: ghost row must use the identical size so layout width stays stable mid-flicker
+  - Reference: ../../examples/proof-logo-chain.html uses `163px` at 1920×1080
+- **FLIP_DURATION** — per-character flip tween duration.
+  - Range: 0.4-1.0s; under 0.4s the random-glyph phase has no time to flicker, over 1.0s drags
+  - Effects: shorter feels snappy and modern; longer feels mechanical / typewriter
+  - Reference: ../../examples/proof-logo-chain.html uses `0.55s`
+- **CHAR_STAGGER** — delay between consecutive characters starting their flips, in seconds.
+  - Range: 0.03-0.08s; too fast and chars overlap visually, too slow and the effect feels labored
+  - Constraints: total decode time = `CHAR_STAGGER × (charCount − 1) + FLIP_DURATION`; ensure this fits the phase budget
+  - Reference: ../../examples/proof-logo-chain.html uses `0.033s` (≈2 frames at 60fps)
+- **REVEAL_THRESHOLD** — progress at which a glyph swaps from random → real.
+  - Range: 0.5-0.7; lower reveals too early (no decode tension), higher feels like a hard reveal at the end
+  - Effects: this is a discrete tuning of when the eye locks onto the real letter
+  - Reference: ../../examples/proof-logo-chain.html uses `0.6`
+- **FLICKER_RATE** — frames between glyph reshuffles during the random phase.
+  - Range: 3-6; lower than 3 looks like noise, higher than 6 looks like discrete typing instead of flicker
+  - Constraints: must be ≥ ~3 frames (see Critical Constraints)
+  - Reference: ../../examples/proof-logo-chain.html uses an equivalent of `3` (one shuffle every 3 internal-clock frames)
+- **{bgColor} / {textColor}** — stage background and live-character color tokens.
+- **{monoFont}** — monospace family preferred so flicker glyphs don't change width per swap; if a proportional font is required, the ghost placeholder makes the cost recoverable.
+- **{phrase}** — the target word the flip resolves to. Length feeds the total decode duration via `CHAR_STAGGER`.
+
+## Variations
+
+- **Top-down hinge** — swap `transform-origin: bottom` to `top` for a falling-flap look.
+- **Center spin** — `transform-origin: center` reads as a barrel roll, not a flap.
+- **Number-only pool** — restrict `GLYPHS` to digits for a price / countdown decode.
+- **Two-pass decode** — chain two `FLIP_DURATION` tweens with different glyph pools (e.g. symbols → letters → real) for a longer reveal.
+
+## Key Principles
+
+- **Threshold at ~`REVEAL_THRESHOLD`** for swap from random → real glyph — close enough to settled that viewer's eye catches the right letter
+- **Hinge at `transform-origin: bottom`** for flap-display look (vs `top` for top-down, vs `center` for spin)
+- **Deterministic random** via seeded hash — HF runtime seeks frame-by-frame, so the same frame must show the same glyph (no `Math.random()`)
+- **Ghost placeholder** sits behind the live chars with identical content + same font, reserving width — without it, narrow glyphs shift the layout mid-flicker
+- **Stagger in the 0.04-0.08s range** per char — too fast and chars overlap visually, too slow and effect feels labored
+- **Center the flip dead-center via `display: grid; place-items: center;`** on the scene root — and DO NOT add decorative headers/footers (timestamp lines, "// AUTH" tags, small status dots). The flip text IS the focal beat; surrounding clutter dilutes it. If a secondary label is necessary, promote it to BIG typography in the same stacked layout (56-72px caps + tracking), not a tiny corner annotation.
+
+## Critical Constraints
+
+- **`perspective` on scene root REQUIRED** — without parent perspective, `rotateX` looks like a 2D scale, not a 3D flip
+- **`transform-style: preserve-3d` on each char** — keeps 3D context intact when chars have their own transforms
+- **Timeline must be paused**: `gsap.timeline({ paused: true })`
+- **Registry key = `data-composition-id`**
+- **Deterministic randomness**: don't use `Math.random()`. Use a seed derived from char index + frame group so seek determinism holds
+- **`onUpdate` writes to DOM**: HF seeks every frame, so this runs many times — keep work O(1) per char per frame
+- **Flicker rate ≥ ~3 frames per glyph swap**: faster looks like noise, slower looks like discrete typing
+
+## Combinations
+
+- [card-morph-anchor.md](card-morph-anchor.md) — pair: hacker-flip reveals a phrase, then card morphs into the next shot
+- [counting-dynamic-scale.md](counting-dynamic-scale.md) — counterpart for numeric reveals (text vs number)
+
+## Pairs with HF skills
+
+- `/hyperframes-animation` — timeline + per-char stagger + `onUpdate`
+- `/hyperframes-core` — composition wiring
+- `/hyperframes-cli` — `hyperframes lint`