hyperframes 0.4.37 → 0.4.39

package/dist/skills/hyperframes/references/prompt-expansion.md

@@ -0,0 +1,68 @@
+# Prompt Expansion
+
+Run on every composition. Expansion is not about lengthening a short prompt — it's about grounding the user's intent against `design.md` and `house-style.md` and producing a consistent intermediate that every downstream agent reads the same way.
+
+Runs AFTER design direction is established (Step 1). The expansion consumes design.md (if present) and produces output that cites its exact values.
+
+## Prerequisites
+
+Read before generating:
+
+- `design.md` (if it exists) — extract brand colors, fonts, mood, and constraints. The expansion cites these exact values (hex codes, font names); it does not invent new ones.
+- [beat-direction.md](beat-direction.md) — per-beat planning format (concept, mood, choreography verbs, transitions, depth layers, rhythm). The expansion outputs each scene using this format.
+- [video-composition.md](video-composition.md) — video-medium rules for density, scale, and color presence. The expansion applies these automatically.
+- [../house-style.md](../house-style.md) — its rules for Background Layer (2-5 decoratives), Color, Motion, Typography apply to every scene. The expansion writes output that conforms to them.
+
+If `design.md` doesn't exist yet, run Step 1 (Design system) first. Expansion without a design context produces generic scene breakdowns that later agents ignore.
+
+## Why always run it
+
+**The expansion is never pass-through.** Every user prompt — no matter how detailed — is a _seed_. The expansion's job is to enrich it into a fully-realized per-scene production spec that the scene subagents can build from directly.
+
+Even a detailed 7-scene brief lacks things only the expansion adds:
+
+- **Atmosphere layers per scene** (required 2–5 from house-style: radial glows, ghost type, hairline rules, grain, thematic decoratives) — the user's prompt almost never lists these; expansion adds them.
+- **Secondary motion for every decorative** — breath, drift, pulse, orbit. A decorative without ambient motion feels dead.
+- **Micro-details that make a scene feel real** — registration marks, tick indicators, monospace coord labels, typographic accents, code snippets in the background, grid patterns. Things the user didn't think to request.
+- **Transition choreography at the object level** — not "crossfade" but "X expands outward and becomes Y". Specific duration, ease, and morph source/target.
+- **Pacing beats within each scene** — where tension builds, where a hold lets the viewer breathe, where the accent word lands.
+- **Exact hex values, typography parameters, ease choices** from design.md — no vagueness left for the scene subagent to guess.
+
+Expansion's job on a detailed prompt is not to summarize or pass through — it's to **take what the user wrote and make it richer**. The user's content stays; the atmosphere, ambient motion, and micro-details are added on top. That's what makes the difference between a scene that matches the brief and a scene that feels alive.
+
+The quality gap between a single-pass composition and a multi-scene-pipeline composition comes from this step. Expansion front-loads the richness so every scene subagent builds from a rich brief, not a terse one.
+
+**Do not skip. Do not pass through.** Single-scene compositions and trivial edits are the only exceptions.
+
+## What to generate
+
+Expand into a full production prompt with these sections:
+
+1. **Title + style block** — cite design.md's exact hex values, font names, and mood. Do NOT invent a palette — quote what the design provides.
+
+2. **Rhythm declaration** — name the scene rhythm before detailing any scene. Example: `hook-PUNCH-breathe-CTA` or `slow-build-BUILD-PEAK-breathe-CTA`. See [beat-direction.md](beat-direction.md) for rhythm templates by video type.
+
+3. **Global rules** — parallax layers, micro-motion requirements, transition style, primary + accent transitions. Match energy to mood (calm → slow eases, high → snappy eases).
+
+4. **Per-scene beats** — for each scene, use the beat-direction format:
+   - **Concept** — the big idea in 2-3 sentences. What visual WORLD? What metaphor? What should the viewer FEEL?
+   - **Mood direction** — cultural/design references, not hex codes. ("Bauhaus color studies", "cinematic title sequence", "editorial calm")
+   - **Depth layers** — BG (2-5 decoratives with ambient motion), MG (content), FG (accents, structural elements, micro-details). 8-10 total elements per scene per video-composition.md.
+   - **Animation choreography** — specific verbs per element. High: SLAMS, CRASHES. Medium: CASCADE, SLIDES. Low: floats, types on, counts up. Every element gets a verb. If you can't name the verb, the element is not yet designed.
+   - **Transition out** — shader or CSS, with specific type and parameters. Not "crossfade" but "blur crossfade, 0.4s, power2.inOut."
+
+5. **Recurring motifs** — visual threads across scenes from the brand palette.
+
+6. **Negative prompt** — what to avoid, informed by design.md's constraints if present.
+
+## Output
+
+Write the expanded prompt to `.hyperframes/expanded-prompt.md` in the project directory. Do NOT dump it into the chat — it will be hundreds of lines.
+
+Tell the user:
+
+> "I've expanded your prompt into a full production breakdown. Review it here: `.hyperframes/expanded-prompt.md`
+>
+> It has [N] scenes across [duration] seconds with specific visual elements, transitions, and pacing. Edit anything you want, then let me know when you're ready to proceed."
+
+Only move to construction after the user approves or says to continue.

package/dist/skills/hyperframes/references/techniques.md

@@ -0,0 +1,387 @@
+# Visual Techniques Reference
+
+10 proven techniques from production HyperFrames videos. Use these in your storyboard and compositions to create visually rich, professional output. Each technique includes a minimal code pattern you can adapt.
+
+These are NOT advanced — they're standard motion design patterns that every composition should use at least 2-3 of.
+
+---
+
+## 1. SVG Path Drawing
+
+A path draws itself in real-time, like someone tracing with a pen. Use for revealing diagrams, arrows, connector lines, or brand marks.
+
+```html
+<svg viewBox="0 0 400 200">
+  <path
+    class="draw-path"
+    d="M 50 100 L 200 50 L 350 100"
+    stroke="#c84f1c"
+    stroke-width="4"
+    fill="none"
+    stroke-linecap="round"
+  />
+</svg>
+<style>
+  .draw-path {
+    stroke-dasharray: 280;
+    stroke-dashoffset: 280;
+  }
+</style>
+<script>
+  tl.to(".draw-path", { strokeDashoffset: 0, duration: 0.7, ease: "power2.out" }, 0.5);
+</script>
+```
+
+Use `path.getTotalLength()` to calculate the dasharray value dynamically.
+
+---
+
+## 2. Canvas 2D Procedural Art
+
+Animated noise, particle fields, data visualizations — anything that evolves frame-by-frame. Drive it with a GSAP proxy.
+
+```html
+<canvas id="proc-canvas" width="1920" height="1080"></canvas>
+<script>
+  var canvas = document.getElementById("proc-canvas");
+  var ctx = canvas.getContext("2d");
+
+  function hash(x, y) {
+    var n = x * 374761393 + y * 668265263;
+    n = (n ^ (n >> 13)) * 1274126177;
+    return ((n ^ (n >> 16)) & 0x7fffffff) / 0x7fffffff;
+  }
+
+  function drawFrame(t) {
+    ctx.fillStyle = "#0a0a0a";
+    ctx.fillRect(0, 0, 1920, 1080);
+    for (var i = 0; i < 200; i++) {
+      var x = hash(i, 0) * 1920;
+      var y = hash(i, 1) * 1080;
+      var brightness = hash(i, Math.floor(t * 10)) * 255;
+      ctx.fillStyle = "rgba(255, 255, 255, " + brightness / 255 + ")";
+      ctx.beginPath();
+      ctx.arc(x, y, 2, 0, Math.PI * 2);
+      ctx.fill();
+    }
+  }
+
+  var proxy = { time: 0 };
+  tl.to(
+    proxy,
+    {
+      time: 5,
+      duration: 5,
+      ease: "none",
+      onUpdate: function () {
+        drawFrame(proxy.time);
+      },
+    },
+    0,
+  );
+</script>
+```
+
+The `hash()` function is deterministic — same frame renders identically every time.
+
+---
+
+## 3. CSS 3D Transforms
+
+Perspective rotations create depth. Use for product showcases, card flips, architectural reveals.
+
+```html
+<div class="stage" style="perspective: 900px;">
+  <div class="card-3d" style="transform-style: preserve-3d;">
+    <div class="face front">Product</div>
+    <div class="face back" style="transform: rotateY(180deg);">Details</div>
+  </div>
+</div>
+<script>
+  tl.to(".card-3d", { rotationY: 360, rotationX: 15, duration: 1.2, ease: "sine.inOut" }, 0);
+</script>
+```
+
+Always set `perspective` on the parent, `transform-style: preserve-3d` on the animated element.
+
+---
+
+## 4. Per-Word Kinetic Typography
+
+Words appear one-by-one, synced to transcript.json timestamps. The core technique for narration-driven videos.
+
+```html
+<div class="headline">
+  <span class="word w-0">Anything</span>
+  <span class="word w-1">a</span>
+  <span class="word w-2">browser</span>
+  <span class="word w-3">can</span>
+  <span class="word w-4">render</span>
+</div>
+<style>
+  .word {
+    display: inline-block;
+    opacity: 0;
+    margin: 0 0.12em;
+  }
+</style>
+<script>
+  // Word onset times from transcript.json (seconds relative to beat start)
+  var timings = [0.0, 0.23, 0.28, 0.63, 0.78];
+  var slides = [80, 60, 50, 25, 12]; // horizontal slide decay (px)
+
+  document.querySelectorAll(".word").forEach(function (word, i) {
+    tl.from(
+      word,
+      {
+        x: slides[i],
+        y: 14,
+        opacity: 0,
+        duration: 0.35,
+        ease: "power2.out",
+      },
+      timings[i],
+    );
+  });
+</script>
+```
+
+The slide distance DECAYS per word (80→12px) — mimics a camera settling.
+
+---
+
+## 5. Lottie Animation
+
+Vector animations that play inside a composition. Use for logos, character animations, icons.
+
+```html
+<script src="https://cdn.jsdelivr.net/npm/@dotlottie/player-component@2.7.12/dist/dotlottie-player.js"></script>
+<dotlottie-player
+  class="lottie"
+  src="../capture/assets/lottie/animation-0.json"
+  autoplay
+  loop
+  speed="1.5"
+  style="width:500px;height:500px;"
+>
+</dotlottie-player>
+<script>
+  gsap.set(".lottie", { scale: 0.3, opacity: 0 });
+  tl.to(".lottie", { scale: 1, opacity: 1, duration: 0.35, ease: "back.out(1.6)" }, 0.2);
+</script>
+```
+
+Or use lottie-web for more control:
+
+```javascript
+var anim = lottie.loadAnimation({
+  container: document.getElementById("anim"),
+  renderer: "svg",
+  loop: false,
+  autoplay: false,
+  path: "../capture/assets/lottie/animation-0.json",
+});
+```
+
+---
+
+## 6. Video Compositing
+
+Embed real video footage inside compositions. Videos must be `muted` with `playsinline`.
+
+```html
+<div class="video-frame" style="width:680px;height:840px;border-radius:16px;overflow:hidden;">
+  <video
+    id="footage"
+    src="../capture/assets/videos/clip.mp4"
+    muted
+    playsinline
+    style="width:100%;height:100%;object-fit:cover;"
+  ></video>
+</div>
+<script>
+  // Video playback is controlled by the framework — don't call play() manually
+  tl.from(".video-frame", { scale: 0.9, opacity: 0, duration: 0.3, ease: "power2.out" }, 0);
+</script>
+```
+
+The HyperFrames runtime handles video seeking and playback.
+
+---
+
+## 7. Character-by-Character Typing
+
+Terminal typing effect using `tl.call()` to update text content character by character.
+
+```html
+<div class="terminal-line">
+  <span class="prompt">❯</span>
+  <span class="typed" id="typed-text"></span>
+  <span class="cursor" style="width:11px;height:22px;background:#333;display:inline-block;"></span>
+</div>
+<script>
+  var CMD = "npx hyperframes init";
+  var typed = document.getElementById("typed-text");
+
+  // Cursor blinks
+  tl.to(".cursor", { opacity: 0, duration: 0.12, yoyo: true, repeat: 20, ease: "steps(1)" }, 0);
+
+  // Type each character
+  for (var i = 0; i < CMD.length; i++) {
+    (function (idx) {
+      tl.call(
+        function () {
+          typed.textContent = CMD.substring(0, idx + 1);
+        },
+        null,
+        (idx / CMD.length) * 0.9,
+      );
+    })(i);
+  }
+</script>
+```
+
+Use `ease: "steps(1)"` for cursor blink — creates discrete on/off.
+
+---
+
+## 8. Variable Font Axis Animation
+
+Animate font-variation-settings to reshape glyphs in real-time. Works with variable fonts that have axes like optical size (opsz), weight (wght), softness (SOFT).
+
+```html
+<style>
+  /* Load the captured local variable font — do NOT use Google Fonts @import.
+     Replace this placeholder with an @font-face pointing to ../capture/assets/fonts/. */
+  @font-face {
+    font-family: "Fraunces";
+    src: url("../capture/assets/fonts/Fraunces-Variable.woff2") format("woff2");
+    font-weight: 100 900;
+    font-style: normal;
+    font-display: block;
+  }
+  .wordmark {
+    --opsz: 144;
+    --wght: 440;
+    font-family: "Fraunces", serif;
+    font-variation-settings:
+      "opsz" var(--opsz),
+      "wght" var(--wght);
+    font-size: 200px;
+  }
+</style>
+<script>
+  tl.to(".wordmark", { "--opsz": 72, "--wght": 300, duration: 0.45, ease: "power2.out" }, 0);
+</script>
+```
+
+The glyph subtly reshapes as axes animate — optical size adjusts detail, weight changes thickness.
+
+---
+
+## 9. GSAP MotionPathPlugin
+
+Animate an element along an arbitrary SVG path. Use for sliders following curves, particles along trajectories, guided reveals.
+
+```html
+<script src="https://cdn.jsdelivr.net/npm/gsap@3.14.2/dist/MotionPathPlugin.min.js"></script>
+<div class="dot" style="width:20px;height:20px;background:#2a8a7c;border-radius:50%;"></div>
+<script>
+  gsap.registerPlugin(MotionPathPlugin);
+  tl.to(
+    ".dot",
+    {
+      motionPath: { path: "M 12 300 C 280 280 520 80 820 50 S 1200 48 1308 38" },
+      duration: 1.5,
+      ease: "power2.out",
+    },
+    0,
+  );
+</script>
+```
+
+---
+
+## 10. Velocity-Matched Transitions
+
+Exit one beat and enter the next with matched velocities — creates perceived continuous motion.
+
+```javascript
+// EXIT (in outgoing composition): accelerating with blur
+tl.to(
+  ".content",
+  {
+    y: -150,
+    filter: "blur(30px)",
+    opacity: 0,
+    duration: 0.33,
+    ease: "power2.in", // accelerates
+  },
+  beatDuration - 0.33,
+);
+
+// ENTRY (in incoming composition): decelerating from blur
+gsap.set(".content", { y: 150, filter: "blur(30px)" });
+tl.to(
+  ".content",
+  {
+    y: 0,
+    filter: "blur(0px)",
+    duration: 1.0,
+    ease: "power2.out", // decelerates
+  },
+  0,
+);
+```
+
+The fastest point of both curves meets at the cut — the viewer perceives smooth camera motion. Match ease families: `.in` for exits, `.out` for entries.
+
+---
+
+## 11. Audio-Reactive Animation
+
+Drive any GSAP-tweenable property from the playing audio. Bass pulses a logo on kick drums. Treble glows a CTA on cymbals. Amplitude breathes a background during quiet phrases. The result: motion that feels locked to the track in a way pre-authored tweens never can.
+
+**When to use:** Any video with music or dramatic narration — brand reels, product launches, hype edits. Skip for calm/tutorial pacing.
+
+**How it works:** Pre-extract audio frequency bands into a JSON file, then sample per-frame via `tl.call()`:
+
+```js
+// audio-data.json: { fps: 30, totalFrames: 900, frames: [{ bands: [0.82, 0.45, 0.31, ...] }, ...] }
+for (var f = 0; f < AUDIO_DATA.totalFrames; f++) {
+  tl.call(
+    (function (frame) {
+      return function () {
+        var bass = frame.bands[0]; // 0–1
+        var treble = frame.bands[13];
+        gsap.set(".logo", { scale: 1 + bass * 0.04 }); // 3–4% pulse on bass
+        gsap.set(".cta", { filter: `drop-shadow(0 0 ${treble * 24}px #00C3FF)` });
+      };
+    })(AUDIO_DATA.frames[f]),
+    [],
+    f / AUDIO_DATA.fps,
+  );
+}
+```
+
+Per-frame sampling is required — a single tween will not react. Use the extract script:
+
+```bash
+python3 skills/gsap/scripts/extract-audio-data.py narration.wav --fps 30 --bands 16 -o audio-data.json
+```
+
+Keep text/logo intensity subtle (≤5% scale, ≤30% glow) — audio-reactive motion on tiny elements reads as jitter. Bigger backgrounds can push to 10–30%.
+
+**Never do:** equalizer bars, spectrum analyzers, waveform displays, strobing, rainbow color cycling. The audio provides _timing and intensity_; the visual vocabulary still comes from the brand. See `skills/hyperframes/references/audio-reactive.md` for the full API and anti-patterns.
+
+---
+
+## When to Use What
+
+| Video energy                   | Techniques to combine                                           |
+| ------------------------------ | --------------------------------------------------------------- |
+| High impact (launches, promos) | Per-word typography + velocity transitions + counter animations |
+| Cinematic (tours, stories)     | SVG path drawing + video compositing + 3D transforms            |
+| Technical (dev tools, APIs)    | Character typing + Canvas 2D procedural + MotionPath            |
+| Premium (luxury, enterprise)   | Variable font animation + Lottie + slow velocity transitions    |
+| Data-driven (stats, metrics)   | Canvas 2D procedural + counter animations + SVG path drawing    |

package/dist/skills/hyperframes/references/video-composition.md

@@ -0,0 +1,62 @@
+# Video Composition
+
+Video frames are not web pages. These rules apply to every composition regardless of brand, style, or design.md.
+
+## design.md Is Brand, Not Layout
+
+design.md defines what the brand looks like: colors, fonts, personality, constraints. It does NOT define how to compose a video frame. Use brand colors at video-appropriate intensity — not at web-UI opacity.
+
+**Strict from design.md:** hex values (including background color), font families, weight relationships, Do's and Don'ts. If the user chose a light canvas, use a light canvas. If they chose dark, use dark. Do not override their palette.
+
+**Adapt for video:** type sizes, spacing, decorative opacity, border weight, component treatments. A web UI card at `border: 1px solid #e2e3e6` with `box-shadow: 0 2px 4px rgba(0,0,0,0.06)` is invisible on video. The brand color is sacred; the application is yours.
+
+## Density
+
+A beat with 3 elements looks empty. A beat with 8-10 feels alive.
+
+Every scene needs:
+
+- **Background texture** — radial glow, oversized ghost type, color panel, grain, grid. Never solid flat color.
+- **Midground content** — the actual message. Cards, stats, code blocks, images.
+- **Foreground accents** — dividers, labels, data bars, registration marks, monospace metadata. The details that make it feel produced, not generated.
+
+Aim for 8-10 visual elements per scene. Two of those should be decorative elements the user didn't ask for — you add them because empty frames look broken.
+
+## Color Presence
+
+Muted is fine. Flat is not. Every scene should have at least one color that pulls the eye.
+
+- Brand accent should be VISIBLE — not a 5% opacity glow lost in compression. 15-25% for atmospheric, full saturation for focal elements.
+- **Light canvases work differently than dark.** On dark: accent glows pop naturally. On light: use bolder borders (2px+ solid), stronger structural elements (rules, dividers), and full-saturation accent hits. Light backgrounds need texture (subtle grain, patterns) to avoid the "blank slide" feel. Don't switch to dark — make light cinematic.
+- Tint neutrals toward the brand hue. Dead gray reads as undesigned.
+
+## Scale
+
+Web sizes are invisible on video. Everything scales up.
+
+| Element            | Web     | Video    |
+| ------------------ | ------- | -------- |
+| Headlines          | 32-48px | 64-120px |
+| Body text          | 14-16px | 28-42px  |
+| Labels             | 12px    | 18-24px  |
+| Decorative opacity | 3-8%    | 12-25%   |
+| Borders            | 1px     | 2-4px    |
+| Padding            | 16-32px | 60-140px |
+
+If you're writing a font-size under 24px in a video composition, justify it. If you're writing decorative opacity under 10%, it's invisible.
+
+## Motion Intensity
+
+Subtle reads as static at 30fps. Err toward more movement than feels safe.
+
+- Every decorative element should have ambient motion: breathe, drift, pulse, orbit. Static decoratives feel dead.
+- Vary motion per scene — don't repeat the same ambient pattern.
+- Scene entrances should use 3+ different eases and directions. If every element enters from `y: 30, opacity: 0`, the scene has no choreography.
+
+## Frame Composition
+
+- **Two focal points minimum.** The eye needs somewhere to travel.
+- **Fill the frame.** Hero text: 60-80% of frame width.
+- **Anchor to edges.** Pin content to left/top or right/bottom. Centered-and-floating is a web layout pattern.
+- **Split frames.** Data panel left, content right. Top bar with metadata, full-width below. Zone-based layouts over centered stacks.
+- **Structural elements.** Rules, dividers, border panels. They create visual paths and animate well (`scaleX: 0` → `1`).