@mevdragon/vidfarm-devcli 0.13.0 → 0.15.0

package/.agents/skills/hyperframes-animation/rules/ai-tracking-box.md

@@ -0,0 +1,382 @@
+---
+name: ai-tracking-box
+description: Animated bounding box with L-shaped corner markers following an oscillating path — simulates AI object detection / tracking.
+metadata:
+  tags: ai, tracking, bounding-box, detection, corner, yellow, ml
+---
+
+# AI Tracking Box
+
+A bounding box with corner markers ("L-brackets") that follows a moving target, simulating real-time AI detection. Position and size oscillate on sine paths to mimic continuous re-computation. Conventionally rendered in "AI detection yellow" (`{detectionYellow}`) on a dark background with a confidence label.
+
+## How It Works
+
+- Box position `(x, y)` and size `(w, h)` are derived from sine + drift across composition time
+- 4 L-bracket corner markers (`<div>` per corner with two-sided borders) sit ON the box
+- Optional label tag above the top-left corner showing class name + confidence percent
+
+All driven by GSAP timeline so HF seeks deterministically.
+
+## HTML
+
+```html
+<div
+  class="scene"
+  id="track-scene"
+  data-composition-id="track-scene"
+  data-start="0"
+  data-duration="5"
+  data-track-index="0"
+>
+  <!-- Background — could be a product mockup, hero image, etc. -->
+  <div class="bg">
+    <div class="bg-content">{Brand}</div>
+    <div class="bg-mascot" id="mascot">{targetGlyph}</div>
+  </div>
+
+  <!-- Tracking box wraps the target -->
+  <div class="track-box" id="track-box">
+    <div class="corner tl"></div>
+    <div class="corner tr"></div>
+    <div class="corner bl"></div>
+    <div class="corner br"></div>
+    <div class="label" id="label">{targetGlyph} {LABEL} · {confidence}%</div>
+  </div>
+</div>
+```
+
+## CSS
+
+```css
+.scene {
+  position: relative;
+  width: 100%;
+  height: 100%;
+  background: radial-gradient(ellipse at center, {bgInner} 0%, {bgOuter} 70%);
+  font-family: {font};
+  overflow: hidden;
+}
+.bg {
+  position: absolute;
+  inset: 0;
+  display: grid;
+  place-items: center;
+  gap: 60px;
+}
+.bg-content {
+  position: absolute;
+  top: 120px;
+  left: 50%;
+  transform: translateX(-50%);
+  font-size: 80px;
+  font-weight: 900;
+  color: {bgTextColor};
+  letter-spacing: 12px;
+  text-transform: uppercase;
+}
+.bg-mascot {
+  position: absolute;
+  font-size: 240px;
+  line-height: 1;
+}
+
+.track-box {
+  position: absolute;
+  /* Position + size set by GSAP onUpdate */
+  pointer-events: none;
+  will-change: transform, width, height;
+}
+.corner {
+  position: absolute;
+  width: 48px;
+  height: 48px;
+}
+.corner.tl {
+  top: -8px;
+  left: -8px;
+  border-top: 6px solid {detectionYellow};
+  border-left: 6px solid {detectionYellow};
+}
+.corner.tr {
+  top: -8px;
+  right: -8px;
+  border-top: 6px solid {detectionYellow};
+  border-right: 6px solid {detectionYellow};
+}
+.corner.bl {
+  bottom: -8px;
+  left: -8px;
+  border-bottom: 6px solid {detectionYellow};
+  border-left: 6px solid {detectionYellow};
+}
+.corner.br {
+  bottom: -8px;
+  right: -8px;
+  border-bottom: 6px solid {detectionYellow};
+  border-right: 6px solid {detectionYellow};
+}
+.label {
+  position: absolute;
+  top: -56px;
+  left: -8px;
+  padding: 8px 16px;
+  background: {detectionYellow};
+  color: {labelTextColor};
+  font-family: {monoFont};
+  font-size: 24px;
+  font-weight: 800;
+  letter-spacing: 2px;
+  border-radius: 6px;
+  white-space: nowrap;
+}
+```
+
+## GSAP Timeline
+
+```html
+<script src="https://cdn.jsdelivr.net/npm/gsap@3.14.2/dist/gsap.min.js"></script>
+<script>
+  window.__timelines = window.__timelines || {};
+  const tl = gsap.timeline({ paused: true });
+
+  const box = document.getElementById("track-box");
+  const mascot = document.getElementById("mascot");
+  const label = document.getElementById("label");
+
+  // Initial state — box invisible, will fade in
+  gsap.set(box, { opacity: 0, scale: ENTRY_SCALE });
+
+  // Phase 1 — box entry (fade in + scale to 1)
+  tl.to(
+    box,
+    {
+      opacity: 1,
+      scale: 1,
+      duration: ENTRY_DUR,
+      ease: `back.out(${ENTRY_BOUNCE})`,
+    },
+    ENTRY_START,
+  );
+
+  // Phase 2 — continuous "AI tracking" — box and mascot move in lock-step on sine paths
+  const SCREEN_CENTER = { x: COMP_WIDTH / 2, y: COMP_HEIGHT / 2 };
+  // DRIFT_X / DRIFT_Y — target oscillation amplitude (px)
+  // SIZE_BASE / SIZE_VAR — box mean size + per-frame jitter amplitude (px)
+  // SIZE_FREQ_MULT — multiplier on tracking phase so box "breathes" off-tempo from drift
+  // CYCLES — number of full oscillations across TRACK_DUR
+  // TRACK_DUR — duration of the tracking phase (s)
+  // TRACK_START — when tracking phase begins (s)
+  // CONFIDENCE_MEAN / CONFIDENCE_VAR — center + half-range of the flickering confidence %
+  // CONFIDENCE_FREQ_MULT — how fast confidence flickers relative to drift
+
+  const tracking = { p: 0 };
+  tl.to(
+    tracking,
+    {
+      p: Math.PI * 2 * CYCLES,
+      duration: TRACK_DUR,
+      ease: "none",
+      onUpdate: () => {
+        // Target position (the mascot moves on a wider arc)
+        const mx = SCREEN_CENTER.x + Math.cos(tracking.p) * DRIFT_X;
+        const my = SCREEN_CENTER.y + Math.sin(tracking.p) * DRIFT_Y;
+        mascot.style.position = "absolute";
+        mascot.style.left = `${mx - MASCOT_SIZE / 2}px`;
+        mascot.style.top = `${my - MASCOT_SIZE / 2}px`;
+
+        // Box size oscillates slightly (size confidence variation)
+        const w = SIZE_BASE + Math.sin(tracking.p * SIZE_FREQ_MULT) * SIZE_VAR;
+        const h = SIZE_BASE + Math.sin(tracking.p * SIZE_FREQ_MULT + Math.PI / 2) * SIZE_VAR;
+
+        // Box position centers on mascot
+        box.style.width = `${w}px`;
+        box.style.height = `${h}px`;
+        box.style.left = `${mx - w / 2}px`;
+        box.style.top = `${my - h / 2}px`;
+
+        // Confidence label fluctuates inside [CONFIDENCE_MEAN ± CONFIDENCE_VAR]
+        const confidence = Math.round(
+          CONFIDENCE_MEAN + Math.sin(tracking.p * CONFIDENCE_FREQ_MULT) * CONFIDENCE_VAR,
+        );
+        label.textContent = `${TARGET_GLYPH} ${LABEL_TEXT} · ${confidence}%`;
+      },
+    },
+    TRACK_START,
+  );
+
+  window.__timelines["track-scene"] = tl;
+</script>
+```
+
+## How to Choose Values
+
+- **ENTRY_SCALE** — start scale of the box before it pops in
+  - Range: 0.5-0.9
+  - Effects: low end = stronger pop / more "snapping into focus"; high end = subtle reveal
+  - Constraints: must be < 1 (box scales UP into place)
+  - Reference: examples use 0.7
+
+- **ENTRY_DUR** — duration of the fade-in + scale-up (seconds)
+  - Range: 0.3-0.8 s
+  - Effects: low end = snappy / authoritative lock-on; high end = soft / observational
+  - Constraints: should end before TRACK_START
+  - Reference: examples use 0.5
+
+- **ENTRY_START** — when the entry tween begins (seconds, absolute on timeline)
+  - Range: 0-2 s typically
+  - Effects: late start = lets the viewer notice the target first before the AI "finds" it; early start = AI is already watching
+  - Constraints: ENTRY_START + ENTRY_DUR ≤ TRACK_START
+  - Reference: examples use 0.5
+
+- **ENTRY_BOUNCE** — coefficient passed to `back.out(...)` on entry
+  - Range: 1.2-2.5
+  - Effects: low end = subtle overshoot; high end = exaggerated snap (reads as "aggressive lock-on")
+  - Constraints: stick to `back.out` family — `elastic` reads as cartoonish, `power` reads as flat
+  - Reference: examples use 1.4
+
+- **TRACK_START** — when continuous tracking begins (seconds)
+  - Range: ≥ ENTRY_START + ENTRY_DUR
+  - Effects: gap between entry and tracking = pause for emphasis; no gap = seamless lock + follow
+  - Constraints: TRACK_START + TRACK_DUR ≤ composition duration
+  - Reference: examples use 1.0
+
+- **TRACK_DUR** — length of the tracking phase (seconds)
+  - Range: 2-8 s
+  - Effects: short = "quick scan"; long = "sustained observation"
+  - Constraints: must accommodate at least one full CYCLE to read as oscillation
+  - Reference: examples use 4.0
+
+- **CYCLES** — number of full sine oscillations of the target across TRACK_DUR
+  - Range: 0.5-3
+  - Effects: low = lazy drift; high = jittery / hyperactive target
+  - Constraints: CYCLES / TRACK_DUR sets effective Hz of drift; keep < ~0.6 Hz or motion blurs
+  - Reference: examples use 1.5
+
+- **DRIFT_X / DRIFT_Y** — amplitude of target oscillation around screen center (px, 1920×1080 basis)
+  - Range: 40-200 px
+  - Effects: small = subtle hover; large = wide chase that pushes the box near the frame edge
+  - Constraints: SCREEN_CENTER ± DRIFT must keep mascot fully on screen given MASCOT_SIZE
+  - Reference: examples use 80 / 50
+
+- **SIZE_BASE** — mean width/height of the bounding box (px)
+  - Range: 200-500 px
+  - Effects: small = "specimen tag"; large = "the box IS the subject"
+  - Constraints: must visibly enclose the target glyph at all confidence sizes
+  - Reference: examples use 320
+
+- **SIZE_VAR** — half-amplitude of per-frame size jitter (px)
+  - Range: 5-10% of SIZE_BASE
+  - Effects: low end = stable / confident detector; high end = jittery / re-fitting detector. Outside this range reads as "broken" (too much) or "static UI" (none)
+  - Constraints: keep < 0.15 × SIZE_BASE to avoid breaking the L-bracket illusion
+  - Reference: examples use 30 (~9% of 320)
+
+- **SIZE_FREQ_MULT** — multiplier on tracking phase for size oscillation
+  - Range: 1.5-3
+  - Effects: 1 = size pulses in lock-step with drift (reads mechanical); irrational ratio = organic re-fitting
+  - Constraints: avoid integer ratios; non-integer reads as continuous recomputation
+  - Reference: examples use 2.3
+
+- **MASCOT_SIZE** — rendered width of the mascot element (px); used to center it on (mx, my)
+  - Range: matches CSS `font-size` of `.bg-mascot`
+  - Effects: must match the actual rendered size or mascot drifts out of the box
+  - Constraints: MASCOT_SIZE / 2 = offset applied to top/left
+  - Reference: examples use 240 (matches `font-size: 240px`)
+
+- **CONFIDENCE_MEAN** — center % shown on the label
+  - Range: 95-99
+  - Effects: < 95 reads "uncertain"; 100 reads "fake-precise". 97 is the sweet spot for "confident AI"
+  - Constraints: keep CONFIDENCE_MEAN + CONFIDENCE_VAR ≤ 99
+  - Reference: examples use 97
+
+- **CONFIDENCE_VAR** — flicker half-range around CONFIDENCE_MEAN
+  - Range: 1-3
+  - Effects: 0 = static (looks like a screenshot); >3 = unstable (looks broken)
+  - Constraints: CONFIDENCE_MEAN ± CONFIDENCE_VAR ⊂ [95, 99]
+  - Reference: examples use 2
+
+- **CONFIDENCE_FREQ_MULT** — multiplier on tracking phase for label flicker
+  - Range: 3-6
+  - Effects: low = synced with drift (mechanical); high = fast nervous flicker (reads "live inference")
+  - Constraints: keep above SIZE_FREQ_MULT so label flickers faster than the box breathes
+  - Reference: examples use 4
+
+- **COMP_WIDTH / COMP_HEIGHT** — composition pixel dimensions (used to derive SCREEN_CENTER)
+  - Range: dictated by the HF composition (`data-width` / `data-height`)
+  - Effects: not a creative choice — match the parent composition
+  - Constraints: SCREEN_CENTER = (COMP_WIDTH/2, COMP_HEIGHT/2)
+  - Reference: examples use 1920 × 1080
+
+- **{detectionYellow}** — corner-marker + label background color
+  - This is a **discrete convention**, not a tunable range. AI detection overlays are yellow on dark backgrounds across the industry (autonomous-vehicle HUDs, security CV, ML demos). Red reads as "warning", green as "success", blue as "info" — none read as "detection."
+  - Recommended: a saturated warm yellow (`#facc15` / `#FCD34D` family) on a dark navy or near-black background. Substituting any other hue loses genre legibility.
+  - Reference: examples use `#facc15` (Tailwind `yellow-400`)
+
+- **{bgInner} / {bgOuter}** — radial-gradient background stops
+  - Should be dark and low-chroma so the yellow markers pop
+  - Constraints: choose colors with sufficient contrast against {detectionYellow} (the corners and label must remain readable)
+  - Reference: examples use `#161a3a` (inner) → `#0b0d1f` (outer)
+
+- **{labelTextColor}** — text color inside the yellow label tag
+  - Constraints: must contrast against {detectionYellow}; typically the same near-black as {bgOuter}
+  - Reference: examples use `#0b0d1f`
+
+- **{font} / {monoFont}** — scene text font and label font
+  - {font}: sans-serif body font for {Brand} backdrop
+  - {monoFont}: monospaced font for the confidence label (mono reinforces "machine readout" affordance)
+  - Reference: examples use `"Inter", sans-serif` and `"JetBrains Mono", monospace`
+
+## Variations
+
+### Multi-object detection
+
+Multiple boxes at different phases (each tracking its own mascot). Each is its own onUpdate-driven set; offset their phase by `Math.PI / N` so they don't tick synchronously.
+
+### Lost-then-reacquired
+
+The box fades to {LOST_OPACITY} (~{LOST_DUR}) then re-snaps to a new position with a "REACQUIRED" label flash:
+
+```js
+tl.to(box, { opacity: LOST_OPACITY, duration: LOST_DUR }, LOST_START);
+tl.to(
+  box,
+  { opacity: 1.0, duration: REACQUIRE_DUR, ease: `back.out(${REACQUIRE_BOUNCE})` },
+  REACQUIRE_START,
+);
+tl.to(label, { textContent: "REACQUIRED · 99%", duration: 0 }, REACQUIRE_START);
+```
+
+(LOST_OPACITY ≈ 0.2-0.4; REACQUIRE_BOUNCE ≈ 1.8-2.5 for a snappier re-lock than the initial entry.)
+
+### Tracking-then-zoom
+
+After tracking, the camera (via [viewport-change](viewport-change.md)) zooms into the tracked box. Combined effect: "the AI found something, now show it."
+
+## Key Principles
+
+- **Yellow on dark background is the detection convention** — see {detectionYellow} entry. Other colors lose the genre signal.
+- **Box ALWAYS contains the target** — recompute box position EVERY frame from target position; never trail behind. If the box lags, it reads as "broken tracker," not "smart AI."
+- **Subtle size variation (~5-10% of SIZE_BASE)** — too much and the tracker looks confused; just right reads as "real-time recomputation."
+- **Corner markers, not full borders** — L-brackets are the genre signature. Full border looks like a generic UI box.
+- **Confidence label flickers in a tight range (CONFIDENCE_MEAN ± CONFIDENCE_VAR inside [95, 99])** — outside that range reads as "uncertain"; ≥100 reads as "fake-precise."
+- **No CSS animation for the tracking — use timeline onUpdate** — HF seek-by-frame doesn't sync with CSS animation.
+
+## Critical Constraints
+
+- **Timeline must be paused**: `gsap.timeline({ paused: true })`
+- **Registry key = `data-composition-id`**
+- **No CSS animation on `.track-box` or `.corner`** — must be timeline-driven
+- **`will-change: transform, width, height`** on `.track-box`
+- **`pointer-events: none`** on `.track-box` — decorative overlay
+- **Box position recomputed per-frame from target** — never tween box position separately from target
+
+## Combinations
+
+- [viewport-change.md](viewport-change.md) — zoom into the tracked box after detection phase
+- [multi-phase-camera.md](multi-phase-camera.md) — wide shot during tracking, push-in on lock
+- [sine-wave-loop.md](sine-wave-loop.md) — the mascot itself idle-breathes inside the box
+
+## Pairs with HF skills
+
+- `/hyperframes-animation` — onUpdate writing multi-element positions
+- `/hyperframes-core` — composition wiring
+- `/hyperframes-cli` — `hyperframes lint`

package/.agents/skills/hyperframes-animation/rules/ambient-glow-bloom.md

@@ -0,0 +1,305 @@
+---
+name: ambient-glow-bloom
+description: Un-triggered soft radial glow that blooms in behind a hero element and holds with a bounded idle breathe, or a single-pass traveling sweep across a surface. No click, no word-sync — it just blooms. Finite, deterministic, seek-safe.
+metadata:
+  tags: glow, bloom, ambient, radial, sweep, hero, presence, finite, un-triggered
+---
+
+# Ambient Glow Bloom
+
+A soft radial glow that **blooms in behind a hero element** (card, logo, metric) and holds, giving it presence. Unlike `press-release-spring`'s click-triggered burst or `asr-keyword-glow`'s word-timed envelope, this glow is **un-triggered** — it simply blooms on the hero's settle and stays lit. Two forms: a **hero bloom** that swells behind a settling element and then breathes, and a **traveling glow sweep** that translates a soft highlight across a surface exactly once. Both are finite, deterministic, and seek-safe.
+
+## How It Works
+
+A radial-gradient layer sits **behind** the hero (`z-index` below it), starting at `opacity: 0`. Over the bloom-in window it ramps `opacity: 0 → peak` with a gentle `scale` swell (the halo "inflates" into place), timed to land on the hero's settle so the two read as one beat.
+
+Two forms diverge after bloom-in:
+
+1. **Hero bloom** — once lit, the glow does a **bounded idle breathe** during the hold. Drive it with an `onUpdate` reading `tl.time()` (NOT a `repeat: -1` yoyo): a `Math.sin` of elapsed time nudges `opacity` and `scale` a hair around their peak. At `sin(0) = 0` the breathe starts exactly at the bloom's resting state — no jump.
+2. **Traveling sweep** — a narrow highlight gradient at one edge of the surface translates **once** across to the other edge (`x` from off-surface to off-surface), a single finite pass. No loop, no return. The sweep layer is clipped to the surface so the highlight only reads where it overlaps.
+
+Peak opacity stays restrained (≤ ~0.45) so the glow gives presence without washing the frame; the glow color is darker / more saturated than the element it backs.
+
+## HTML
+
+```html
+<div
+  class="scene"
+  id="bloom-scene"
+  data-composition-id="bloom-scene"
+  data-start="0"
+  data-duration="DURATION"
+  data-track-index="0"
+>
+  <div class="bloom-stage">
+    <!-- Glow layer sits BEHIND the hero -->
+    <div class="bloom-glow" id="bloom-glow"></div>
+    <div class="hero-card" id="hero-card">{HeroLabel}</div>
+  </div>
+</div>
+```
+
+For the traveling-sweep form, the sweep layer is clipped to the surface it crosses:
+
+```html
+<div class="surface" id="surface">
+  <!-- grid / wordmark / card content here -->
+  <div class="sweep" id="sweep"></div>
+</div>
+```
+
+## CSS
+
+```css
+.scene {
+  position: relative;
+  width: 100%;
+  height: 100%;
+  display: grid;
+  place-items: center;
+  background: {bgColor};
+}
+.bloom-stage {
+  position: relative;
+  display: grid;
+  place-items: center;
+}
+.hero-card {
+  position: relative;
+  z-index: 2;
+  width: HERO_WIDTH;
+  height: HERO_HEIGHT;
+  display: grid;
+  place-items: center;
+  background: {heroBg};
+  border-radius: HERO_RADIUS;
+  font-family: {font};
+  font-weight: 900;
+  font-size: HERO_FONT_SIZE;
+  color: {heroTextColor};
+}
+.bloom-glow {
+  /* Radial halo behind the hero — extends past it via negative inset */
+  position: absolute;
+  z-index: 1;
+  inset: GLOW_INSET;
+  background: {glowGradient};
+  opacity: 0;
+  transform: scale(GLOW_START_SCALE);
+  transform-origin: 50% 50%;
+  pointer-events: none;
+  /* will-change because opacity + scale both animate during bloom AND breathe */
+  will-change: transform, opacity;
+}
+
+/* Traveling-sweep form */
+.surface {
+  position: relative;
+  overflow: hidden; /* clips the sweep to the surface footprint */
+  border-radius: SURFACE_RADIUS;
+}
+.sweep {
+  position: absolute;
+  top: 0;
+  bottom: 0;
+  /* A narrow soft band, wider than it needs to be so the falloff is gentle */
+  width: SWEEP_WIDTH;
+  /* Diagonal highlight: angle the gradient so the sweep reads as raked light */
+  background: {sweepGradient};
+  opacity: 0;
+  pointer-events: none;
+  will-change: transform, opacity;
+}
+```
+
+## GSAP Timeline
+
+```html
+<script src="https://cdn.jsdelivr.net/npm/gsap@3.14.2/dist/gsap.min.js"></script>
+<script>
+  window.__timelines = window.__timelines || {};
+  const tl = gsap.timeline({ paused: true });
+
+  const glow = document.getElementById("bloom-glow");
+
+  // ── Form A: HERO BLOOM ──────────────────────────────────────────────
+  // Phase 1 — bloom in. opacity 0 → peak + gentle scale swell, landing on
+  // the hero's settle. ease "power2.out" so it arrives soft, not snappy.
+  tl.fromTo(
+    glow,
+    { opacity: 0, scale: GLOW_START_SCALE },
+    {
+      opacity: GLOW_PEAK_OPACITY,
+      scale: 1,
+      duration: BLOOM_DUR,
+      ease: "power2.out",
+    },
+    BLOOM_START,
+  );
+
+  // Phase 2 — bounded idle breathe during the hold. NOT a yoyo loop:
+  // a single finite tween advances `phase` 0 → 2π·CYCLES; onUpdate reads it
+  // and nudges opacity + scale a hair around their peak.
+  // sin(0) = 0 → breathe starts exactly at the bloom's resting state.
+  const phase = { p: 0 };
+  tl.to(
+    phase,
+    {
+      p: Math.PI * 2 * BREATHE_CYCLES,
+      duration: BREATHE_DUR,
+      ease: "none",
+      onUpdate: () => {
+        const s = Math.sin(phase.p);
+        glow.style.opacity = String(GLOW_PEAK_OPACITY + s * OPACITY_AMP);
+        glow.style.transform = `scale(${1 + s * SCALE_AMP})`;
+      },
+    },
+    BLOOM_START + BLOOM_DUR, // breathe begins right as the bloom settles
+  );
+
+  // ── Form B: TRAVELING SWEEP ─────────────────────────────────────────
+  // A single finite pass. opacity fades in, x travels from off one edge to
+  // off the other, opacity fades out as it exits. One pass — no repeat.
+  const sweep = document.getElementById("sweep");
+  tl.fromTo(
+    sweep,
+    { x: SWEEP_START_X, opacity: 0 },
+    {
+      x: SWEEP_END_X,
+      opacity: SWEEP_PEAK_OPACITY,
+      duration: SWEEP_DUR,
+      ease: "none", // constant glide reads as a raking light, not an ease-in object
+    },
+    SWEEP_START,
+  );
+  // Fade the trailing edge out so it doesn't pop off at the surface edge.
+  tl.to(sweep, { opacity: 0, duration: SWEEP_FADE_DUR, ease: "power1.in" }, SWEEP_FADE_START);
+
+  window.__timelines["bloom-scene"] = tl;
+</script>
+```
+
+## Variations
+
+### Bloom-and-hold (no breathe)
+
+For very short scenes (< 3s) or when the hero already has its own idle, skip Phase 2 entirely — bloom to peak and hold flat. The single `fromTo` is the whole recipe; the glow is just lit presence.
+
+### Pulse-on-arrival (one swell, then settle to a lower hold)
+
+Bloom slightly **past** peak, then ease back down to a steady hold level — a single breath that punctuates the hero's landing without an ongoing loop. Two adjacent tweens (state continuity, same as `press-release-spring`):
+
+```js
+tl.fromTo(
+  glow,
+  { opacity: 0, scale: GLOW_START_SCALE },
+  { opacity: GLOW_OVERSHOOT_OPACITY, scale: 1.06, duration: BLOOM_DUR, ease: "power2.out" },
+  BLOOM_START,
+);
+tl.to(
+  glow,
+  { opacity: GLOW_HOLD_OPACITY, scale: 1, duration: SETTLE_DUR, ease: "power2.inOut" },
+  BLOOM_START + BLOOM_DUR,
+);
+```
+
+### Multi-hero relay (staggered blooms behind a row of cards)
+
+Bloom each card's glow on a stagger so presence sweeps across the row. Per-glow `BLOOM_START` offset by `STAGGER` (~0.15-0.3s); shrink `OPACITY_AMP` / `SCALE_AMP` per the concurrent-elements rule below so N breathing halos don't compound into a shimmer.
+
+### Diagonal raked sweep (wordmark sheen)
+
+Angle `{sweepGradient}` (e.g. a 105° linear gradient) and let the band travel left→right across a wordmark or logo lockup. Reads as light raking across a surface — the classic one-pass logo sheen. Same single-pass timeline; just a narrower `SWEEP_WIDTH` and a higher `SWEEP_PEAK_OPACITY` since it's a tight highlight on a small target.
+
+## How to Choose Values
+
+### Glow geometry
+
+- **GLOW_INSET** — negative inset so the radial halo extends past the hero edges.
+  - Range: `-200` to `-450` px on a 1920×1080 canvas; larger halo for a bigger hero
+  - Effects: too small and the glow is a tight rim, not ambient presence
+- **GLOW_START_SCALE** — scale at the start of bloom-in (the halo "inflates" to 1).
+  - Range: 0.80 (clear inflation) → 0.92 (subtle) → 1.0 (no swell, opacity-only bloom)
+  - Constraints: keep ≤ 1.0 — the swell should grow into place, not shrink
+
+### Bloom-in dynamics
+
+- **BLOOM_DUR** — bloom-in duration.
+  - Range: 0.6-1.4s; longer for a hero that's still settling so they land together
+  - Effects: shorter → the glow "snaps on"; longer → it suffuses in (the ambient feel)
+- **BLOOM_START** — when the bloom begins.
+  - Constraints: align so `BLOOM_START + BLOOM_DUR` ≈ the hero's settle frame, so glow and hero resolve as one beat — not glow-then-card or card-then-glow
+- **GLOW_PEAK_OPACITY** — peak halo opacity.
+  - Range: 0.15 (subtle) → 0.30 (default) → 0.45 (dramatic)
+  - **Constraints: ≤ 0.45** — higher washes the whole frame and the hero loses contrast against its own glow
+
+### Idle breathe (hero-bloom form)
+
+- **BREATHE_DUR** — breathe tween length.
+  - Constraints: equals `TOTAL_DURATION − (BLOOM_START + BLOOM_DUR)` to fill the hold with motion
+- **BREATHE_CYCLES** — number of full breaths across `BREATHE_DUR`.
+  - Range: `BREATHE_DUR / 4s ≤ CYCLES ≤ BREATHE_DUR / 2.5s` (a 2.5-4s breath period reads as a slow ambient pulse — glow breathing wants to be slower than element breathing)
+- **OPACITY_AMP** — sine amplitude on opacity around the peak.
+  - **Default: 0.02-0.05** (barely-perceptible pulse — the right answer for most scenes)
+  - Constraints: `GLOW_PEAK_OPACITY + OPACITY_AMP` must stay ≤ 0.45
+- **SCALE_AMP** — sine amplitude on the halo scale.
+  - **Default: 0.01-0.03** (the halo "breathes" without visibly resizing)
+  - Push higher only when the glow is the sole motion in a short isolated scene
+
+### Traveling sweep
+
+- **SWEEP_WIDTH** — width of the soft highlight band.
+  - Range: 15-35% of the surface width (a wide soft band) for a grid sheen; 8-15% for a tight wordmark sheen
+- **SWEEP_START_X / SWEEP_END_X** — travel endpoints, both fully off-surface.
+  - Constraints: start ≈ `-(SWEEP_WIDTH + edge)`, end ≈ `surfaceWidth + edge` — the band must enter from fully off one edge and exit fully off the other, so there's no visible spawn/despawn mid-surface
+- **SWEEP_DUR** — single-pass travel duration.
+  - Range: 0.8-1.6s; one deliberate pass, slow enough to read as light, fast enough not to dominate
+- **SWEEP_PEAK_OPACITY** — highlight opacity.
+  - Range: 0.10 (whisper sheen) → 0.25 (default) → 0.40 (bright rake)
+  - Constraints: ≤ ~0.45 (same wash limit); tighter sweeps tolerate the high end
+- **SWEEP_START / SWEEP_FADE_START / SWEEP_FADE_DUR** — when the pass runs and tails out.
+  - Constraints: `SWEEP_FADE_START + SWEEP_FADE_DUR ≈ SWEEP_START + SWEEP_DUR` so opacity reaches 0 exactly as the band clears the far edge
+
+### Tokens
+
+- **{glowGradient}** — radial-gradient, saturated near center fading to transparent. Color should be **darker + more saturated** than `{heroBg}` — a same-color glow looks washed out (same rule as `press-release-spring`'s burst).
+- **{sweepGradient}** — a soft band: `transparent → highlight → transparent`. For a sheen, a near-white or brand-tint highlight at low alpha; angle it (e.g. `linear-gradient(105deg, …)`) for a raked look.
+- **{heroBg} / {heroTextColor}** — the hero surface the glow backs; high contrast so the lit hero still reads against its halo.
+
+## Key Principles
+
+- **Un-triggered by design** — this glow does NOT wait on a click (`press-release-spring`) or a word timestamp (`asr-keyword-glow`). It blooms on the hero's settle as ambient presence. If you need a triggered burst, reach for one of those rules instead.
+- **Glow behind, hero in front** — glow `z-index: 1`, hero `z-index: 2`. A glow in front occludes the hero at peak opacity.
+- **Glow color darker + more saturated than the element** — bright hero → dark, saturated halo. A same-hue, same-lightness glow disappears into the surface.
+- **Land glow and hero as ONE beat** — time `BLOOM_START + BLOOM_DUR` to the hero's settle. A glow that arrives before or after the card reads as two separate events; arriving together reads as the card "powering on."
+- **Restrained peak — default to the LOW end.** `GLOW_PEAK_OPACITY` 0.15-0.30 for most scenes; 0.45 is a hard ceiling. A glow you consciously notice is too strong — it should register as the hero having weight, not as a visible light source.
+- **Breathe is BOUNDED, never a loop** — the idle pulse is a finite `onUpdate` tween reading `tl.time()` (via the `phase` proxy), not `repeat: -1` / `yoyo`. `sin(0) = 0` means it starts at the bloom's resting state with no jump. (Same reason as `sine-wave-loop`: an infinite/CSS loop desyncs from the HF seek clock.)
+- **Sweep is ONE pass** — the traveling highlight enters off one edge and exits off the other a single time. No return trip, no loop. A repeating sweep reads as a loading shimmer, not a one-time reveal accent.
+- **Concurrent halos compound** — N breathing glows in a row add up. Per-glow `OPACITY_AMP` and `SCALE_AMP` ≤ default `/ √N`, and stagger the breathe period (2.6s / 2.9s / 3.3s) so they don't pulse in lockstep. (Same `/√N` discipline as `sine-wave-loop`'s concurrent-elements rule.)
+- **Don't combine `boxShadow` glow on the hero with this halo layer** — they compete in the layout pipeline and the result reads muddy. Put the glow on the dedicated `.bloom-glow` layer, not as a shadow on the hero.
+
+## Critical Constraints
+
+- **Timeline must be paused**: `gsap.timeline({ paused: true })`
+- **Registry key = `data-composition-id`**
+- **No CSS `transition`** on the glow / sweep — interpolates independently of HF seek and flickers
+- **No `repeat` / `yoyo` / `repeat: -1`** — the breathe is a bounded finite tween; the sweep is one pass
+- **No `Math.random` / `Date.now`** — the breathe phase is deterministic (`phase.p` over a fixed duration)
+- **GSAP transform aliases only**: `x`, `y`, `scale`, `rotation` — plus `opacity` / `filter`. Never tween `width` / `height` / `left` / `top` (the halo swell is `scale`, the sweep travel is `x`).
+- **`will-change: transform, opacity`** on the glow — it animates both during bloom-in and the breathe
+- **Glow peak `opacity ≤ 0.45`** — higher washes the composition
+- **Sweep endpoints fully off-surface** — band must enter and exit beyond the clipped edges so it never spawns/despawns mid-frame
+
+## Combinations
+
+- [sine-wave-loop.md](sine-wave-loop.md) — pair the hero-bloom form with a sine breathe on the hero element itself; the glow breathes on opacity, the hero breathes on scale/y, slightly out of phase for a layered "alive" hold
+- [press-release-spring.md](press-release-spring.md) — distinct sibling: that rule's `bg-glow` is **click-triggered**, this one is un-triggered. Don't run both behind the same element
+- [counting-dynamic-scale.md](counting-dynamic-scale.md) — bloom the accent halo behind the hero stat card on the count-up's settle (the `dataviz-countup` blueprint's "soft accent glow blooms behind the hero metric" beat)
+- [stat-bars-and-fills.md](stat-bars-and-fills.md) — glow blooms behind the hero metric + its paired graphic as they land together
+- [center-outward-expansion.md](center-outward-expansion.md) — run the traveling-sweep across the assembled layout once it resolves (the `grid-card-assemble` blueprint's "traveling-glow sweep across the assembled grid")
+
+## Pairs with HF skills
+
+- `/hyperframes-animation` — `onUpdate` writing opacity/transform + bounded sine breathe
+- `/hyperframes-core` — composition wiring
+- `/hyperframes-cli` — `hyperframes lint`