npm - @mevdragon/vidfarm-devcli - Versions diffs - 0.14.0 → 0.15.0 - Mend

@mevdragon/vidfarm-devcli 0.14.0 → 0.15.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (418) hide show

package/.agents/skills/embedded-captions/modes/cinematic/engine.html ADDED Viewed

@@ -0,0 +1,355 @@
+<!doctype html>
+<!--
+  ENGINE — the one Cinematic-mode shell, parameterized by a DNA (dna/<name>.json).
+  Replaces per-template HTML files: the DNA supplies type / palette / blend / motion
+  grammar / hero orchestration; safe-zones v2 supplies scene tokens (accent sampling,
+  contact-shadow direction, depth-match blur); the plan supplies layout + per-group
+  typography. Compiled by make-composition.cjs.
+  Contract (unchanged from cinematic-cream — gates depend on it):
+    #root[data-composition-id="main"] · #a-roll · #stage · #a-roll-audio
+    .plane > .cap > .w spans · paused seek-safe GSAP on window.__timelines["main"]
+    container fade via tl.set at g.in−0.01 · exit fade + display:none at g.out
+    no Math.random / Date.now / CSS keyframes / repeat:-1
+  New in the engine:
+    - MOTION grammar from the DNA: soft / present / impact tones (+ "burn" reveal)
+    - HERO three-act orchestration:
+        act 1 SETUP   — co-visible groups dim 0.35s before the hero lands
+        act 2 IMPACT  — entrance (emergence | settle | slam | rise) with per-letter
+                        stagger; amplitude coupled to the spoken word's RMS loudness
+        act 3 AFTERGLOW — slow breathe scale + glow layer (DNA-gated) until exit
+    - depth-match blur on embed (bg) captions only; fg stays sharp
+    - scene-sampled --accent custom property available to per-group CSS
+-->
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width={{WIDTH}}, height={{HEIGHT}}" />
+    <script src="https://cdn.jsdelivr.net/npm/gsap@3.14.2/dist/gsap.min.js"></script>
+    <style>
+      :root {
+        --font-scale: {{FONT_SCALE}};
+        --h: {{HEIGHT}}px; --w: {{WIDTH}}px;
+        --accent: {{ACCENT}};
+      }
+      * { margin: 0; padding: 0; box-sizing: border-box; }
+      html, body {
+        margin: 0;
+        width: {{WIDTH}}px; height: {{HEIGHT}}px;
+        overflow: hidden;
+        background: #000;
+        font-family: '{{FONT_FAMILY}}', "Helvetica Neue", system-ui, sans-serif;
+      }
+      #a-roll { position: absolute; inset: 0; width: 100%; height: 100%; object-fit: cover; }
+      #stage {
+        position: absolute;
+        top: 0; left: 0;
+        width: {{WIDTH}}px; height: {{HEIGHT}}px;
+        pointer-events: none;
+        z-index: 2;
+      }
+      /* BASE — DNA tokens. bg (embed) captions get the depth-match filter; fg stays sharp. */
+      .cap {
+        display: block;
+        position: absolute;
+        opacity: 0;
+        mix-blend-mode: {{BLEND_MODE}};
+        color: {{CAP_COLOR}};
+        text-shadow: {{TEXT_SHADOW}};
+        filter: {{TEXT_FILTER_BG}};
+        line-height: 1.12; /* contains ink + internal leading — wrapped rows breathe (was 1.0: rows touched) */
+        will-change: transform, opacity;
+        top: 50%; left: 0; right: 0; text-align: center;
+      }
+      .cap[data-layer="fg"] { filter: {{TEXT_FILTER_FG}}; }
+      .cap .w { display: inline-block; opacity: 0; will-change: opacity, transform; }
+      .cap .w .l { display: inline-block; will-change: opacity, transform; }
+      /* hero glow — same glyphs duplicated UNDER the hero, blurred; opacity driven by GSAP.
+         em-based blur scales with the hero's font size. Not part of plan.groups → gates skip it.
+         MUST be out of flow (absolute) — as a flow sibling inside a plane it displaces the hero. */
+      .hero-glow, .plane > .cap.hero-glow { position: absolute; left: 0; right: 0; top: 0; filter: blur(0.06em); }
+      /* hero echoes — colored duplicates (RGB fringe / speed trails); position mirrors the
+         hero via its #id rule, color comes from each echo's own rule */
+      .hero-echo, .plane > .cap.hero-echo { position: absolute; left: 0; right: 0; top: 0; }
+      .plane { position: absolute; pointer-events: none; }
+      .plane > .cap {
+        position: relative;
+        top: auto; left: auto; right: auto; bottom: auto;
+      }
+      {{DNA_CSS}}
+      {{PLANES_CSS}}
+      /* Per-group typography (agent-authored). */
+      {{CUSTOM_CSS}}
+    </style>
+  </head>
+  <body>
+    <div
+      id="root"
+      data-composition-id="main"
+      data-start="0"
+      data-duration="{{DURATION}}"
+      data-width="{{WIDTH}}"
+      data-height="{{HEIGHT}}"
+    >
+      <video
+        id="a-roll"
+        src="source.mp4"
+        muted
+        playsinline
+        data-duration="{{DURATION}}"
+        data-track-index="0"
+        style="z-index: 1"
+      ></video>
+      <div id="stage">{{GROUPS_HTML}}</div>
+      <audio
+        id="a-roll-audio"
+        src="source.mp4"
+        data-start="0"
+        data-duration="{{DURATION}}"
+        data-track-index="3"
+        data-volume="1"
+      ></audio>
+    </div>
+    <script>
+      window.__timelines = window.__timelines || {};
+      const tl = gsap.timeline({ paused: true });
+      const DUR = {{DURATION}};
+      const GROUPS = {{GROUPS_JSON}};
+      const MOTION = {{MOTION_JSON}};
+      const HEROES = {{HEROES_JSON}};
+      const HERO_IDS = {};
+      HEROES.forEach(function (h) { HERO_IDS[h.id] = true; });
+      /* ── word entrance: the DNA's motion grammar ─────────────────────────
+         Each tone = {y, x, blur, scale, rot, dur, ease} or {reveal:"burn"}.
+         rot alternates sign by word index (deterministic percussion); blur is a
+         filter tween on the word span only (the container's depth-match filter
+         is a separate element — no conflict, no reflow). */
+      function wordReveal(wsel, m, at, idx) {
+        if (m.reveal === "burn") { tl.set(wsel, { opacity: 1 }, at); return; }
+        if (m.reveal === "flicker") {
+          /* neon tube igniting — deterministic on/off pattern, phase-shifted by word
+             index so a line of words doesn't strobe in unison */
+          var o = (idx % 3) * 0.018;
+          tl.set(wsel, { opacity: 1 }, at);
+          tl.set(wsel, { opacity: 0.25 }, at + 0.042 + o);
+          tl.set(wsel, { opacity: 1 }, at + 0.078 + o);
+          tl.set(wsel, { opacity: 0.5 }, at + 0.112 + o);
+          tl.set(wsel, { opacity: 1 }, at + 0.152 + o);
+          return;
+        }
+        var from = { opacity: 0 }, to = { opacity: 1, duration: m.dur || 0.4,
+          ease: m.ease || "power2.out", overwrite: "auto", transformOrigin: "50% 70%" };
+        if (m.y) { from.y = m.y; to.y = 0; }
+        if (m.x) { from.x = m.x; to.x = 0; }
+        if (m.scale && m.scale !== 1) { from.scale = m.scale; to.scale = 1; }
+        if (m.stretchX && m.stretchX !== 1) { from.scaleX = m.stretchX; to.scaleX = 1; }
+        if (m.skewX) { from.skewX = m.skewX; to.skewX = 0; }
+        if (m.rot) { from.rotation = ((idx % 2) ? 1 : -1) * m.rot; to.rotation = 0; }
+        if (m.blur) { from.filter = "blur(" + m.blur + "px)"; to.filter = "blur(0px)"; }
+        tl.fromTo(wsel, from, to, at);
+      }
+      var EXIT = MOTION.exit || { dur: 0.5, ease: "power2.in", stagger: 0 };
+      var LINE_REVEAL = MOTION.lineReveal || null;
+      /* exit cascade: lines of the same plane sharing one page-flip `out` can leave
+         top-to-bottom (editorial). Slot layout = absolute positions, so staggered
+         exits cause no reflow. Every exit still hard-kills at g.out. */
+      var pageMates = {};
+      GROUPS.forEach(function (g) {
+        if (HERO_IDS[g.id]) return;
+        var key = (g.plane || "free") + "@" + g.out;
+        (pageMates[key] = pageMates[key] || []).push(g.id);
+      });
+      GROUPS.forEach(function (g) {
+        if (HERO_IDS[g.id]) return; // heroes are orchestrated below
+        var sel = "#" + g.id;
+        var m = MOTION[g.tone] || MOTION.soft || {};
+        tl.set(sel, { opacity: 1 }, Math.max(0, g.in - 0.01));
+        /* line container reveal (keynote's surgical wipe) — clip-path, not transform.
+           PHRASE mode: the whole line is set visible up front and the WIPE is the
+           reveal (slide-title idiom) — wiping an empty container reads as nothing. */
+        if (LINE_REVEAL && LINE_REVEAL.type === "wipe-x") {
+          tl.set(sel + " .w", { opacity: 1 }, Math.max(0, g.in - 0.01));
+          tl.fromTo(sel, { clipPath: "inset(0% 100% 0% 0%)" },
+            { clipPath: "inset(0% 0% 0% 0%)", duration: LINE_REVEAL.dur || 0.4,
+              ease: LINE_REVEAL.ease || "expo.out", overwrite: "auto" },
+            Math.max(0, g.in - 0.01));
+        } else {
+          g.words.forEach(function (w, i) {
+            wordReveal(sel + " .w[data-i='" + i + "']", m, w.start, i);
+          });
+        }
+        /* exit: DNA grammar — direction + speed + optional per-line cascade */
+        var mates = pageMates[(g.plane || "free") + "@" + g.out];
+        var rank = mates.indexOf(g.id);
+        var lead = (EXIT.stagger || 0) * (mates.length - 1 - rank);
+        var exitAt = Math.max(g.in + 0.1, g.out - (EXIT.dur || 0.5) - lead);
+        var to = { opacity: 0, duration: EXIT.dur || 0.5, ease: EXIT.ease || "power2.in", overwrite: "auto" };
+        if (EXIT.y) to.y = EXIT.y;
+        if (EXIT.x) to.x = EXIT.x;
+        if (EXIT.scale && EXIT.scale !== 1) to.scale = EXIT.scale;
+        if (g.out < DUR) tl.to(sel, to, exitAt);
+        tl.set(sel, { opacity: 0, display: "none" }, g.out);
+      });
+      /* ── HEROES: three-act orchestration, one per promoted beat ──────────── */
+      HEROES.forEach(function (HERO) {
+        var hsel = "#" + HERO.id;
+        var gsel = "#" + HERO.id + "-glow";
+        var hg = GROUPS.filter(function (g) { return g.id === HERO.id; })[0];
+        var amp = HERO.amp || 1;
+        /* act 1 — SETUP: co-visible groups yield (dim) just before the hero lands.
+           Minor heroes are emphasis-plus: no dim, no ripple, no breathe — the apex
+           keeps those privileges (that's what makes it the apex). */
+        if (!HERO.minor && HERO.dimOthers < 1) {
+          GROUPS.forEach(function (g) {
+            if (g.id === HERO.id) return;
+            if (g.in < HERO.in && g.out > HERO.in) {
+              tl.to("#" + g.id, { opacity: HERO.dimOthers, duration: 0.3, ease: "power2.out", overwrite: "auto" },
+                    Math.max(0, HERO.in - 0.35));
+            }
+          });
+        }
+        tl.set(hsel, { opacity: 1 }, Math.max(0, HERO.in - 0.01));
+        /* act 2 — IMPACT: container entrance (amplitude ∝ spoken loudness) */
+        if (HERO.entrance === "settle") {
+          tl.fromTo(hsel, { scale: 1 + 0.10 * amp },
+            { scale: 1, duration: 0.50, ease: "expo.out", transformOrigin: "50% 60%", overwrite: "auto" }, HERO.in);
+        } else if (HERO.entrance === "slam") {
+          /* percussion: ONE unit, violent snap — geometry locks in 0.16s; heat comes after */
+          tl.fromTo(hsel, { scale: 1 + 0.22 * amp },
+            { scale: 1, duration: 0.16, ease: "back.out(2.2)", transformOrigin: "50% 55%", overwrite: "auto" }, HERO.in);
+        } else if (HERO.entrance === "rise") {
+          tl.fromTo(hsel, { y: 22 * amp },
+            { y: 0, duration: 0.60, ease: "power2.out", overwrite: "auto" }, HERO.in);
+        } else if (HERO.entrance === "wipe-up") {
+          /* surgical slide-title reveal — clip-path only (not a transform: can't
+             collide with the afterglow scale channel), bottom-up behind the subject */
+          tl.fromTo(hsel, { clipPath: "inset(100% 0% 0% 0%)" },
+            { clipPath: "inset(0% 0% 0% 0%)", duration: 0.45, ease: "expo.out", overwrite: "auto" }, HERO.in);
+        } else if (HERO.entrance === "flicker-on") {
+          /* neon sign powering up — deterministic strobe, then steady */
+          tl.set(hsel, { opacity: 1 }, HERO.in);
+          tl.set(hsel, { opacity: 0.15 }, HERO.in + 0.05);
+          tl.set(hsel, { opacity: 1 }, HERO.in + 0.095);
+          tl.set(hsel, { opacity: 0.4 }, HERO.in + 0.14);
+          tl.set(hsel, { opacity: 1 }, HERO.in + 0.19);
+          tl.fromTo(hsel, { scale: 1.03 }, { scale: 1, duration: 0.4, ease: "power2.out", overwrite: "auto", transformOrigin: "50% 55%" }, HERO.in + 0.19);
+        } else if (HERO.entrance === "streak") {
+          /* speed pass — slides in along its own motion blur (skew rides the velocity) */
+          tl.fromTo(hsel, { x: -90 * amp, skewX: -12, opacity: 0 },
+            { x: 0, skewX: 0, opacity: 1, duration: 0.28, ease: "expo.out", overwrite: "auto", transformOrigin: "50% 80%" }, HERO.in);
+        } else { /* emergence — grows out from behind the subject */
+          tl.fromTo(hsel, { scale: Math.max(0.74, 1 - 0.18 * amp) },
+            { scale: 1, duration: 0.55, ease: "expo.out", transformOrigin: "50% 62%", overwrite: "auto" }, HERO.in);
+        }
+        /* impact ripple (loud): the hero's landing bumps every co-visible caption —
+           captions only, the footage itself NEVER moves */
+        if (!HERO.minor && HERO.ripple > 0) {
+          GROUPS.forEach(function (g) {
+            if (g.id === HERO.id) return;
+            if (g.in < HERO.in && g.out > HERO.in + 0.3) {
+              tl.to("#" + g.id, { y: HERO.ripple, duration: 0.07, ease: "power2.out", overwrite: "auto" }, HERO.in + 0.04);
+              tl.to("#" + g.id, { y: 0, duration: 0.20, ease: "power2.out", overwrite: "auto" }, HERO.in + 0.11);
+            }
+          });
+        }
+        /* words / letters */
+        (hg ? hg.words : []).forEach(function (w, i) {
+          var wsel = hsel + " .w[data-i='" + i + "']";
+          if (HERO.perLetter) {
+            tl.set(wsel, { opacity: 1 }, w.start);
+            var letters = document.querySelectorAll(wsel + " .l");
+            for (var li = 0; li < letters.length; li++) {
+              var lf = { opacity: 0, y: "0.16em", scale: 1.05 };
+              var lt = { opacity: 1, y: 0, scale: 1, duration: 0.30, ease: "power4.out", overwrite: "auto" };
+              if (HERO.letterBlur) { lf.filter = "blur(" + HERO.letterBlur + "px)"; lt.filter = "blur(0px)"; }
+              tl.fromTo(letters[li], lf, lt, w.start + li * (HERO.letterStagger || 0.014));
+            }
+          } else {
+            var m = MOTION.impact || MOTION.present || {};
+            wordReveal(wsel, m, w.start, i);
+          }
+        });
+        /* glow layer (DNA-gated). Slam = impact THEN heat: glow waits for geometry lock. */
+        if (HERO.glow > 0) {
+          var glowAt = HERO.in + (HERO.entrance === "slam" ? 0.17 : 0.08);
+          var glowPeak = Math.min(0.5, HERO.glow * amp) * (HERO.minor ? 0.5 : 1);
+          tl.set(gsel + " .w", { opacity: 1 }, Math.max(0, HERO.in - 0.01));
+          tl.fromTo(gsel, { opacity: 0 },
+            { opacity: glowPeak, duration: HERO.entrance === "slam" ? 0.3 : 0.5, ease: "power2.out", overwrite: "auto" },
+            glowAt);
+          tl.to(gsel, { opacity: 0, duration: 0.5, ease: "power2.in", overwrite: "auto" }, HERO.out - 0.5);
+          tl.set(gsel, { opacity: 0, display: "none" }, HERO.out);
+        }
+        /* fx: ECHO layers (RGB-split fringe / speed trails) — colored duplicates that
+           CONVERGE as the word lands, then rest at a small offset until exit */
+        if (HERO.echoes && HERO.echoes.length) {
+          HERO.echoes.forEach(function (ec, k) {
+            var esel = "#" + HERO.id + "-echo-" + k;
+            tl.set(esel + " .w", { opacity: 1 }, Math.max(0, HERO.in - 0.01));
+            tl.fromTo(esel,
+              { x: (ec.dx || 0) * 4, y: (ec.dy || 0) * 4, opacity: 0 },
+              { x: ec.dx || 0, y: ec.dy || 0, opacity: ec.opacity != null ? ec.opacity : 0.5,
+                duration: 0.22, ease: "power4.out", overwrite: "auto" }, HERO.in);
+            tl.to(esel, { opacity: 0, duration: 0.4, ease: "power2.in", overwrite: "auto" }, HERO.out - 0.45);
+            tl.set(esel, { opacity: 0, display: "none" }, HERO.out);
+          });
+        }
+        /* fx: SHEEN — one gradient sweep across the hero during the hold (chrome).
+           Targets the .w spans (the gradient lives there — see wordCss). Starts as the
+           entrance settles so the specular hit is visible early in the hold. */
+        if (HERO.sheen && HERO.out - HERO.in > 0.9) {
+          tl.fromTo(hsel + " .w", { backgroundPosition: "0% 50%" },
+            { backgroundPosition: "200% 50%", duration: Math.min(1.2, HERO.out - HERO.in - 0.5),
+              ease: "power1.inOut", overwrite: "auto" }, HERO.in + 0.22);
+        }
+        /* act 3 — AFTERGLOW: ONE slow scale tween (no loops — deterministic).
+           loom (slow growth, loud) subsumes breathe — never two transform tweens
+           on the same element in the same window. wipe-up entrances are clip-path,
+           so the afterglow scale channel is always free by now. */
+        var after = HERO.loom > 0 ? HERO.loom : HERO.breathe;
+        if (!HERO.minor && after > 0 && HERO.out - HERO.in > 1.4) {
+          tl.fromTo(hsel, { scale: 1 },
+            { scale: 1 + after, duration: HERO.out - HERO.in - 1.2, ease: HERO.loom > 0 ? "power1.inOut" : "sine.inOut", overwrite: "auto" },
+            HERO.in + 0.7);
+        }
+        /* exit */
+        if (HERO.out < DUR) {
+          tl.to(hsel, { opacity: 0, duration: 0.5, ease: "power2.in", overwrite: "auto" }, HERO.out - 0.5);
+        }
+        tl.set(hsel, { opacity: 0, display: "none" }, HERO.out);
+      });
+      tl.seek(0);
+      window.__timelines["main"] = tl;
+    </script>
+  </body>
+</html>

package/.agents/skills/embedded-captions/modes/standard/_anatomy.md ADDED Viewed

@@ -0,0 +1,233 @@
+---
+name: caption-template-anatomy
+description: The shared, reproducible scene engine every caption template is built on — a matted talking-head with a flowing verbatim foreground caption and a single climax word, driven by one paused GSAP timeline. Read it ONCE per session (it is identical for all 54 templates); each per-template file in templates/ only overrides the style tokens + the named climax entrance/exit.
+metadata:
+  tags: caption, talking-head, matte, occlusion, verbatim, climax, gsap, hyperframes
+---
+# Caption Template — Anatomy (the shared engine)
+A **caption template** = one complete, reproducible HyperFrames scene:
+> **the person (always in frame)** + a **flowing foreground caption** (verbatim, word-by-word, with appear **and** disappear) + a **climax word** (big, behind the speaker, with a designed entrance **and** exit) + a coherent **font / colour / motion** design.
+Every file in `templates/` is the SAME engine described here with three things swapped: (1) the **style tokens** (font, fills, accent, optional gradient/stroke), (2) the named **climax entrance** + **exit** (see `_motion.md`), (3) the **copy** (flow lines + climax word) and **scene/person**. So read this once; each template file is short.
+HyperFrames-native, so anyone can reproduce it:
+- **One paused GSAP timeline per composition**, registered to `window.__timelines[data-composition-id]`.
+- All timing in **seconds**; `data-start` / `data-duration` carry the scene window.
+- **Deterministic + seek-safe** only — no `Math.random()`, no `Date.now()`, no infinite repeats, no un-seekable CSS animations. Every state is reachable by seeking the timeline to a time `t`.
+- GSAP transform aliases (`x`, `y`, `scale`, `rotation`); animate `opacity`, `filter`, `clipPath`, `textShadow`, `backgroundPosition`, `letterSpacing` — never layout props (width/top/left/margin).
+For the composition contract see `hyperframes-core`; eases + the animated-property allowlist see `hyperframes-gsap`; caption grouping/positioning/exit guarantees see `hyperframes-captions`.
+## 1 · Asset prep (two CLI calls)
+```bash
+# 1) The person — transparent talking-head cutout over the scene (VP9 + alpha)
+bash scripts/prepare.sh   <project>      # matte ∥ transcribe ∥ safe-zones (THIS skill — not remove-background)
+#    (a still works too:  remove-background portrait.jpg -o person.png)
+# 2) The verbatim word timings that drive the flowing caption
+npx hyperframes transcribe subject.mp4 --model small            # → transcript.json
+#    shape: [{ "id":"w0","text":"Hello","start":0.0,"end":0.5 }, …]
+```
+The flow caption consumes that `transcript.json` directly (word `start`/`end` → reveal + active-word emphasis). The climax word is authored by hand (it is the headline beat, not part of the spoken transcript). In production the avatar/matte pipeline yields a pixel-perfect alpha for free — `remove-background` is the fallback for arbitrary footage.
+## 2 · The matte sandwich (HTML)
+Six layers, back-to-front. The person is layered ON TOP of the climax so they physically **occlude** it — this is what sells "behind the speaker" (blur/opacity alone reads as a flat overlay).
+```html
+<div
+  class="stage {STYLE} {PERSON}"
+  id="cap-{id}"
+  data-composition-id="cap-{id}"
+  data-start="0"
+  data-duration="{SCENE_DUR}"
+  data-track-index="0"
+>
+  <!-- z0  background plate (the original frame, full) -->
+  <!--     supplied by .{PERSON} as background-image, or a <video> at z-index:0 -->
+  <!-- z1  CLIMAX — big, BEHIND the person, occluded -->
+  <div class="climax"><span>{CLIMAX_WORD}</span></div>
+  <!-- z4  the person cutout (transparent webm/png), aligned to the plate -->
+  <video class="cut" src="person.webm" muted playsinline></video>
+  <!-- or:  <img class="cut" src="person.png"> -->
+  <!-- z5  grade / vignette for depth + legibility -->
+  <div class="grade"></div>
+  <!-- z6  FLOW — the verbatim caption, IN FRONT, lower third -->
+  <div class="flow"></div>
+  <!-- words injected from transcript.json -->
+</div>
+```
+## 3 · Base CSS (layout · z-order · sizing)
+Caption size is in **`cqh`** (% of frame height) via a size container, so it honours broadcast spec at any resolution (~8% cap-height for a 16:9 word). The per-template file only sets the `--ff` / `--cfill` / `--cacc` tokens and any `.climax span` fill (gradient/stroke).
+```css
+.stage {
+  position: relative;
+  aspect-ratio: 16/9;
+  overflow: hidden;
+  container-type: size;
+  background-size: cover;
+  background-position: center 12%;
+  background-color: #0a0a0e;
+  font-family: var(--ff);
+}
+.stage > * {
+  position: absolute;
+}
+.cut {
+  z-index: 4;
+  inset: 0;
+  width: 100%;
+  height: 100%;
+  object-fit: cover;
+  object-position: center 12%;
+  pointer-events: none;
+}
+.grade {
+  z-index: 5;
+  inset: 0;
+  pointer-events: none;
+  background: radial-gradient(130% 100% at 50% 26%, transparent 40%, rgba(0, 0, 0, 0.6));
+}
+/* CLIMAX — big, behind person (z1), occluded. line-height ≥1.15 so clip-reveal
+   entrances (inset(0)) never slice glyph tops; pad clips negative for script faces. */
+.climax {
+  z-index: 1;
+  left: 50%;
+  top: 37%;
+  transform: translate(-50%, -50%);
+  white-space: nowrap;
+  text-align: center;
+  line-height: 1.18;
+  font-family: var(--ff);
+  color: var(--cfill);
+  font-weight: 900;
+  font-size: 44cqh;
+  text-transform: uppercase;
+  text-shadow:
+    0 2px 13px rgba(0, 0, 0, 0.6),
+    0 0 48px rgba(0, 0, 0, 0.42);
+}
+.climax span {
+  display: inline-block;
+  opacity: 0;
+} /* GSAP reveals it */
+/* FLOW — verbatim caption, in front (z6), lower third */
+.flow {
+  z-index: 6;
+  left: 50%;
+  bottom: 9%;
+  transform: translateX(-50%);
+  width: 90%;
+  text-align: center;
+  line-height: 1.15;
+  font-family: var(--ff);
+  font-weight: 700;
+  font-size: 7.5cqh;
+  color: var(--cfill);
+}
+.flow .w {
+  display: inline-block;
+  opacity: 0;
+  margin: 0 0.1em;
+  color: var(--cfill);
+}
+.flow .w.act {
+  color: var(--cacc);
+} /* the currently-spoken word */
+/* tokens every template overrides: */
+.stage {
+  --ff: "Inter";
+  --cfill: #fff;
+  --cacc: #10a37f;
+}
+```
+**Legibility on busy/bright scenes:** a behind-the-person climax needs separation from the footage, not just a fill colour. For dark or gradient fills on lit scenes give the climax an outline — `-webkit-text-stroke:1px rgba(0,0,0,.5);paint-order:stroke fill` — a dark drop-shadow alone fails against highlights (e.g. a lamp). Gradient/clip fills must live on `.climax span` (the text node), never on the transformed `.climax` container, or the clip detaches and only the shadow shows.
+## 4 · One paused GSAP timeline (the loop, made seek-safe)
+The gallery used a `setInterval` loop; HyperFrames needs the same beats as **absolute-time tweens on one paused timeline**. The cycle is **FLOW line → (FLOW line) → CLIMAX in → hold → out**. Restraint is the rule: flow stays clean; the one big mood move happens only at the climax.
+```html
+<script src="https://cdn.jsdelivr.net/npm/gsap@3.14.2/dist/gsap.min.js"></script>
+<script>
+  window.__timelines = window.__timelines || {};
+  const stage = document.getElementById("cap-{id}");
+  const flow = stage.querySelector(".flow");
+  const climax = stage.querySelector(".climax span");
+  const tl = gsap.timeline({ paused: true });
+  // --- FLOW: render words from transcript.json, reveal each at its start time ---
+  // WORDS = grouped transcript lines: [{ words:[{text,start,end}], end }] in scene-local seconds.
+  function renderLine(line) {
+    flow.innerHTML = line.words
+      .map((w, i) => `<span class="w" data-i="${i}">${w.text}</span>`)
+      .join(" ");
+    return [...flow.querySelectorAll(".w")];
+  }
+  WORDS.forEach((line) => {
+    const spans = renderLine(line); // (one renderLine per active line; see captions skill for multi-line groups)
+    spans.forEach((el, i) => {
+      const w = line.words[i];
+      tl.add(FLOW_IN(el), w.start); // FLOW_IN  = the template's flow entrance (see _motion.md)
+      tl.set(spans, { className: "w" }, w.start); // active-word sweep: only the spoken word gets .act
+      tl.set(el, { className: "w act" }, w.start);
+    });
+    tl.add(FLOW_OUT(spans), line.end); // FLOW_OUT = flow exit
+    tl.set(flow, { autoAlpha: 0 }, line.end + FOUT); // hard-hide the group so old text can't linger
+    tl.set(flow, { autoAlpha: 1 }, line.end + FOUT + 0.001);
+  });
+  // --- CLIMAX: entrance at the beat → hold ≥1s → exit (named recipes from _motion.md) ---
+  const T = CLIMAX_AT; // beat time (after the flow lines)
+  tl.add(CLIMAX_IN(climax), T); // e.g. SLAM / DEBLUR / INK-LOOM / CHROME-SWEEP …
+  tl.add(CLIMAX_OUT(climax), T + CLIMAX_HOLD); // hold ≥1s, then exit. CLIMAX_OUT ends opacity:0 (hard exit)
+  window.__timelines["cap-{id}"] = tl;
+</script>
+```
+`FLOW_IN` / `FLOW_OUT` / `CLIMAX_IN` / `CLIMAX_OUT` are the named recipes in **`_motion.md`** — each returns a GSAP tween/timeline so the per-template file just picks four names. A simpler equivalent for the flow active-word _glow_ (rather than discrete reveal) is the single-driver envelope in `hyperframes-animation/rules/asr-keyword-glow.md`.
+## 5 · How to choose values
+- **SCENE_DUR** — must equal `data-duration`. Typical 6–10 s for a looping demo card.
+- **WORDS grouping** — 2–4 words / line, ~380–520 ms per word (premium pacing is slower than Hormozi). Group from `transcript.json`; keep `end < next.start` (monotonic).
+- **CLIMAX_AT** — place the climax _after_ the flow lines clear, on the narration's emphasis beat.
+- **CLIMAX_HOLD** — **≥1 s** of settled dwell _after_ the entrance finishes (the climax is the headline beat). Entrances run 0.6–1.6 s, so e.g. hold = entranceDur + 1.0–1.6.
+- **FOUT** — flow exit ≈ 0.5 s. **Exit ≈ 75 % of entry** for every element (arrival deliberate, departure swift; see `_motion.md`).
+- **Climax size** — base 44 cqh; long words bleed off-frame (intended cinematic); 3-char words behind a centred subject need size + an outline so they peek.
+## Critical constraints (HyperFrames)
+- Timeline **paused**; registry key = `data-composition-id`.
+- **No CSS keyframe animation** on caption elements — all motion is GSAP tweens at absolute times (seek-safe).
+- No `Math.random` / `Date.now` / infinite repeats.
+- `display:inline-block` on every `.w` and the climax `span`.
+- **Hard-hide** each flow group at its end time; **CLIMAX_OUT ends at `opacity:0`** (or fully-clipped) so nothing lingers.
+- Gradient / `background-clip:text` / stroke fills go on `.climax span`, not the transformed `.climax`.
+- `.climax` `line-height ≥ 1.15`; pad clip-reveal entrances with negative insets for script/decorative fonts.
+## Pairs with HF skills
+- `hyperframes-media` — `remove-background` (the matte) + `transcribe` (word timings).
+- `hyperframes-captions` — transcript consumption, grouping, positioning, exit guarantees, `fitTextFontSize`.
+- `hyperframes-animation/rules/asr-keyword-glow.md` — the verbatim active-word envelope.
+- `hyperframes-gsap` — single paused timeline, transform aliases, ease palette.
+- `_motion.md` (this folder) — the named flow/climax entrance + exit recipes.