@mevdragon/vidfarm-devcli 0.13.0 → 0.15.0

package/.agents/skills/hyperframes-animation/rules/asr-keyword-glow.md

@@ -0,0 +1,286 @@
+---
+name: asr-keyword-glow
+description: Keywords glow + scale up when "spoken" — attack/sustain/release envelope synced to per-word timestamps. Even without real audio, hardcoded timings create a "narrator emphasis" effect.
+metadata:
+  tags: asr, audio-sync, highlight, glow, keyword, text, speech, emphasis
+---
+
+# ASR Keyword Glow
+
+Words in a phrase visually activate (glow blur + scale) when "spoken," following an attack-sustain-release (ASR-like) envelope. In a real ASR pipeline these timings come from word-level transcript data; for promotional video, hardcode the timings to control emphasis pacing. The envelope leaves a subtle "rest glow" after the word, creating a breadcrumb of recent emphasis.
+
+## How It Works
+
+Each word has `{ start, end }` timestamps. At each frame, compute the word's envelope value:
+
+- **Pre-start** → 0 (not yet)
+- **Start → peak** → attack (linear ramp 0 → 1)
+- **Peak → end** → sustain (stays at 1)
+- **End → end+release** → decay (1 → restLevel, typically 0.25)
+- **After release** → restLevel (stays subtly highlighted)
+
+The envelope drives `textShadow` blur radius AND `scale`. Higher blur + bigger scale = "speaking" emphasis.
+
+## HTML
+
+```html
+<div
+  class="scene"
+  id="asr-scene"
+  data-composition-id="asr-scene"
+  data-start="0"
+  data-duration="6"
+  data-track-index="0"
+>
+  <div class="phrase">
+    <!-- One <span class="word"> per word in {phrase}. data-word is a
+         stable key used to look up the word's ASR timing in JS. The
+         final word may be a {brandWord}, which gets longer emphasis
+         and the .brand modifier. -->
+    <span class="word" data-word="{w1Key}">{w1}</span>
+    <span class="word" data-word="{w2Key}">{w2}</span>
+    <!-- … -->
+    <span class="word brand" data-word="{brandKey}">{brandWord}</span>
+  </div>
+</div>
+```
+
+## CSS
+
+```css
+.scene {
+  position: relative;
+  width: 100%;
+  height: 100%;
+  display: grid;
+  place-items: center;
+  background: {sceneBackgroundColor};
+  font-family: {font};
+}
+.phrase {
+  display: flex;
+  flex-wrap: wrap;
+  gap: 24px;
+  justify-content: center;
+  max-width: 1700px;
+  font-size: 120px;
+  font-weight: 900;
+  letter-spacing: 2px;
+  color: {restColor};
+  text-align: center;
+  line-height: 1.2;
+}
+.word {
+  display: inline-block;
+  transform-origin: 50% 50%;
+  /* Initial subtle rest glow */
+  text-shadow: 0 0 0 {glowColorTransparent};
+  will-change: transform, text-shadow;
+}
+.word.brand {
+  color: {brandAccentColor};
+  letter-spacing: 12px;
+  text-transform: uppercase;
+}
+```
+
+## 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 });
+
+  // Per-word "spoken" times — author these to control narrator pacing.
+  // Shape: { [wordKey]: { start, end } } in local seconds. One entry
+  // per <span class="word" data-word="…">. The brand word's window is
+  // typically 1.5-2× as long as a normal word.
+  const TIMINGS = {
+    // {w1Key}: { start: …, end: … },
+    // {w2Key}: { start: …, end: … },
+    // …
+    // {brandKey}: { start: …, end: … },
+  };
+
+  function envelope(time, start, end) {
+    const releaseEnd = end + RELEASE;
+    if (time < start) return 0;
+    if (time < end) {
+      // attack — linear ramp over ATTACK_DUR then sustain
+      const attack = Math.min((time - start) / ATTACK_DUR, 1);
+      return attack;
+    }
+    if (time < releaseEnd) {
+      // decay to rest level
+      const decay = (time - end) / RELEASE;
+      return 1 - decay * (1 - REST_LEVEL);
+    }
+    return REST_LEVEL;
+  }
+
+  const words = document.querySelectorAll(".word");
+
+  // Single driver — 0 → composition duration
+  const driver = { t: 0 };
+  tl.to(
+    driver,
+    {
+      t: SCENE_DURATION,
+      duration: SCENE_DURATION,
+      ease: "none",
+      onUpdate: () => {
+        words.forEach((el) => {
+          const word = el.dataset.word;
+          const timing = TIMINGS[word];
+          if (!timing) return;
+          const env = envelope(driver.t, timing.start, timing.end);
+          const blur = MAX_BLUR * env;
+          const scale = 1 + MAX_SCALE_BOOST * env;
+          el.style.textShadow = `0 0 ${blur}px ${glowColorRgba(env)}`;
+          el.style.transform = `scale(${scale})`;
+        });
+      },
+    },
+    0,
+  );
+
+  window.__timelines["asr-scene"] = tl;
+</script>
+```
+
+`glowColorRgba(env)` returns the brand glow color with `env`-modulated alpha (e.g. `rgba({glowR}, {glowG}, {glowB}, ${GLOW_ALPHA_BASE + env * GLOW_ALPHA_RANGE})`).
+
+## Variations
+
+### Multi-octave glow (more dramatic peaks)
+
+Combine the envelope-driven blur with a sin pulse during the sustain phase — high-emphasis words breathe at peak. The sine frequency `PULSE_HZ` controls how many breaths fit in the sustain window; amplitude `PULSE_AMPLITUDE` controls how visible the breath is.
+
+```js
+const sustain = env * (1 + Math.sin(driver.t * PULSE_HZ) * PULSE_AMPLITUDE);
+const blur = MAX_BLUR * sustain;
+```
+
+### Color shift on the peak
+
+The active word lerps from `restColor` → `peakColor` as `env` rises, settling back to `restColor` at rest:
+
+```js
+function lerpChannel(a, b, t) {
+  return Math.round(a + (b - a) * t);
+}
+el.style.color = `rgb(${lerpChannel(REST_RGB.r, PEAK_RGB.r, env)}, ${lerpChannel(REST_RGB.g, PEAK_RGB.g, env)}, ${lerpChannel(REST_RGB.b, PEAK_RGB.b, env)})`;
+```
+
+### Karaoke style (dim-rest + bright-active, RECOMMENDED for video narration)
+
+Default amplitudes (small MAX_BLUR, small MAX_SCALE_BOOST, rest text full white) read as too subtle in video — the inactive words still dominate. Karaoke style fixes this: **inactive words rendered DIM**, active words **lerp toward bright white + larger scale**:
+
+```js
+// Tunable constants — see How to Choose Values
+// REST_RGB    — dim color for inactive words
+// ACTIVE_RGB  — bright color at peak (non-brand)
+// BRAND_RGB   — bright color at peak (brand word)
+// MAX_BLUR, MAX_SCALE_BOOST, REST_LEVEL all pushed higher than default
+
+function lerpChannel(a, b, t) {
+  return Math.round(a + (b - a) * t);
+}
+function colorAt(env, isBrand) {
+  const target = isBrand ? BRAND_RGB : ACTIVE_RGB;
+  return `rgb(${lerpChannel(REST_RGB.r, target.r, env)}, ${lerpChannel(REST_RGB.g, target.g, env)}, ${lerpChannel(REST_RGB.b, target.b, env)})`;
+}
+
+// In onUpdate:
+el.style.color = colorAt(env, el.classList.contains("brand"));
+```
+
+Visual result: at any moment 1-2 words are bright + glowing (the spoken word + the recently-spoken one's lingering rest), and the rest of the phrase is dim. This is closer to actual karaoke / lyric video aesthetic than the subtle "everyone half-glowing" baseline.
+
+When to use karaoke vs default: short narration phrases (5-10 words) where one word at a time should clearly POP → karaoke. Long dense text where many words emphasize subtly → default subtle. Karaoke pushes MAX_BLUR, MAX_SCALE_BOOST, and contrast between REST_RGB and ACTIVE_RGB; everything else is identical.
+
+### 3D pop-out
+
+Combine envelope with `translateZ` for words to "lean toward camera" as they speak:
+
+```js
+const popZ = env * MAX_POP_Z;
+el.style.transform = `translateZ(${popZ}px) scale(${scale})`;
+```
+
+Requires `perspective` on the parent.
+
+### From real ASR transcripts
+
+For real ASR-driven scenes, replace hardcoded TIMINGS with transcript JSON (each entry has `word`, `start_ms`, `end_ms`). Convert to seconds and feed in identically. The shape `{ [wordKey]: { start, end } }` is the same whether hand-authored or derived from `hyperframes transcribe`.
+
+## How to Choose Values
+
+- **TIMINGS** — per-word `{ start, end }` map. Author one entry per `.word` span.
+  - Shape: `{ wordKey: { start: number, end: number } }`, all seconds local to the scene.
+  - Constraints: monotonic non-overlap — every entry's `end < next entry's start` (overlapping windows make the envelope ambiguous).
+  - Brand word window: typically 1.5-2× the average non-brand word window so the brand sustains.
+- **ATTACK_DUR** — seconds for the envelope to ramp 0 → 1 once a word starts.
+  - Range: 0.1-0.25 s
+  - Effects: shorter feels punchy and ASR-like; longer feels smoothed-out.
+  - Constraints: must be < (smallest word's end - start), otherwise the word never reaches 1.
+- **RELEASE** — seconds for the envelope to decay 1 → REST_LEVEL after a word ends.
+  - Range: 0.2-0.5 s
+- **REST_LEVEL** — held envelope value after RELEASE.
+  - Range: 0.15-0.4 (default style); 0.05-0.2 (karaoke style — dimmer rest).
+  - Effects: lower = quieter breadcrumb; higher = more recently-spoken words stay bright.
+  - Constraints: must be < 1; should be > 0 to preserve the breadcrumb.
+- **MAX_BLUR** — peak `text-shadow` blur radius in px.
+  - Range: 15-25 px (default style); 30-45 px (karaoke style).
+  - Effects: bigger reads as "shouting"; smaller reads as "neutral narration".
+- **MAX_SCALE_BOOST** — additive scale at peak (e.g. 0.08 ⇒ 1.0 → 1.08).
+  - Range: 0.03-0.10 (default style); 0.15-0.25 (karaoke style).
+  - Effects: bigger reads as "bouncy"; smaller reads as "just glowing".
+- **SCENE_DURATION** — total seconds for the single driver tween.
+  - Constraints: must equal the scene's `data-duration` so the driver `t` reaches the end of TIMINGS in sync with HF's seek.
+- **REST_RGB / ACTIVE_RGB / BRAND_RGB** (karaoke style) — discrete color choices, not numeric.
+  - REST_RGB: dim tone of the brand palette's neutral; should read as off-white-ish dim, not black.
+  - ACTIVE_RGB: brand text color at full readability.
+  - BRAND_RGB: brand accent color (often the same hue as the glow).
+- **PULSE_HZ / PULSE_AMPLITUDE** (multi-octave variation) — sine breath frequency / depth.
+  - PULSE_HZ range: 4-10 rad/s; PULSE_AMPLITUDE range: 0.1-0.3.
+- **MAX_POP_Z** (3D pop-out variation) — max Z translation at peak (px).
+  - Range: 20-60 px; requires parent `perspective`.
+
+Ease family — discrete choice:
+
+- Single linear driver (`ease: "none"`) so `t` maps 1:1 to scene time. Any other ease distorts the per-word envelope shape — do not change.
+
+## Key Principles
+
+- **Envelope shape: attack-sustain-decay-rest** — never zero out after a word. The rest level (REST_LEVEL > 0) keeps the recently-spoken words subtly highlighted, creating a "breadcrumb" of attention.
+- **Brand word gets longer emphasis (1.5-2× normal)** — the brand is the headline; let it sustain.
+- **`display: inline-block`** on each word — required for `transform` to apply to `<span>`.
+- **MAX_BLUR and MAX_SCALE_BOOST stay in their default-style ranges unless you commit to karaoke** — picking values between default and karaoke yields awkward "half-loud" emphasis.
+- **Per-word `text-shadow`** (not `box-shadow`) — text-shadow is the glow around the GLYPH, which is what reads as "speaking emphasis." Box-shadow would glow around the inline-block bounding box (rectangle).
+- **Single driver, multi-word onUpdate** — one tween that loops over all words. Don't create one tween per word — at 60+ words the timeline becomes unwieldy.
+- **❗ Climax dwell ≥1s** — after the final word's emphasis, comp continues ≥1s. The last word IS the headline beat.
+
+## Critical Constraints
+
+- **Timeline must be paused**: `gsap.timeline({ paused: true })`
+- **Registry key = `data-composition-id`**
+- **No CSS animation** on word elements
+- **`display: inline-block`** on each `.word`
+- **`will-change: transform, text-shadow`** on `.word`
+- **Timings monotonic** (later start > earlier end) — overlapping words mess up the envelope
+
+## Combinations
+
+- [3d-text-depth-layers.md](3d-text-depth-layers.md) — the active word gets depth-layered emphasis at peak
+- [sine-wave-loop.md](sine-wave-loop.md) — non-active words breathe subtly between emphasis moments
+- [context-sensitive-cursor.md](context-sensitive-cursor.md) — typewriter that types each word matching the ASR cadence
+
+## Pairs with HF skills
+
+- `/hyperframes-animation` — single driver, multi-element envelope
+- `/hyperframes-media` — `hyperframes transcribe` outputs real ASR data
+- `/hyperframes-media` — pair with caption rendering
+- `/hyperframes-core` — composition wiring
+- `/hyperframes-cli` — `hyperframes lint`

package/.agents/skills/hyperframes-animation/rules/avatar-cloud-network.md

@@ -0,0 +1,371 @@
+---
+name: avatar-cloud-network
+description: Avatars distributed on an elliptical ring connected by SVG dashed lines to a center hub — social proof "community" reveal with staggered entry.
+metadata:
+  tags: avatar, cloud, network, social-proof, ellipse, connection, stagger
+---
+
+# Avatar Cloud Network
+
+Avatars arranged on an elliptical ring around a central element (logo / counter / brand). SVG dashed connection lines from center to each avatar. Staggered spring entry on avatars, then connection lines draw outward — communicates "community" or "social proof." Distinct from [orbit-3d-entry](orbit-3d-entry.md) (which continuously orbits) — avatar-cloud is a static composed reveal.
+
+## How It Works
+
+Three rendering layers:
+
+1. **SVG connection lines** (z-index 1, behind everything) — line from center hub to each avatar's position
+2. **Avatars** (z-index 2) — `<div>` circles on elliptical positions
+3. **Center hub** (z-index 5) — brand counter or logo (sits ABOVE the lines that converge on it)
+
+Animation phases:
+
+- `HUB_FADE_START → HUB_FADE_START + HUB_FADE_DUR`: hub fades in
+- `AVATAR_ENTRY_START → AVATAR_ENTRY_START + (AVATAR_COUNT − 1) × AVATAR_STAGGER + AVATAR_ENTRY_DUR`: avatars cascade in
+- `LINES_START → LINES_START + (AVATAR_COUNT − 1) × LINE_STAGGER + LINES_DUR`: connection lines draw outward
+- climax dwell: optional idle breathing on avatars (see Variations / sine-wave-loop)
+
+## HTML
+
+```html
+<div
+  class="scene"
+  id="cloud-scene"
+  data-composition-id="cloud-scene"
+  data-start="0"
+  data-duration="4"
+  data-track-index="0"
+>
+  <!-- Connection lines layer -->
+  <svg class="lines" viewBox="0 0 1920 1080" xmlns="http://www.w3.org/2000/svg">
+    <!-- Lines injected by script — center to each avatar -->
+  </svg>
+
+  <!-- Avatars + center hub -->
+  <div class="hub-wrap">
+    <div class="hub" id="hub">
+      <div class="hub-num" id="hub-num">{counterValue}</div>
+      <div class="hub-label">{counterLabel}</div>
+    </div>
+    <!-- Avatars injected by script — AVATAR_COUNT around the ellipse -->
+  </div>
+
+  <div class="brand">{footerLine}</div>
+</div>
+```
+
+Placeholder tokens:
+
+- `{counterValue}` / `{counterLabel}` — the hub copy (numeric proof + category)
+- `{footerLine}` — optional attribution line under the cloud
+- `{avatar[i]}` — per-avatar image source (or emoji glyph if using the emoji variation below)
+
+## CSS
+
+```css
+.scene {
+  position: relative;
+  width: 100%;
+  height: 100%;
+  background: {bgColor};
+  font-family: {font};
+  overflow: hidden;
+}
+.lines {
+  position: absolute;
+  inset: 0;
+  width: 100%;
+  height: 100%;
+  pointer-events: none;
+  z-index: 1;
+}
+.hub-wrap {
+  position: absolute;
+  inset: 0;
+  display: grid;
+  place-items: center;
+}
+.hub {
+  position: relative;
+  z-index: 5;
+  display: flex;
+  flex-direction: column;
+  align-items: center;
+  gap: 12px;
+  padding: 48px 64px;
+  border-radius: 28px;
+  background: {hubBg};
+  border: 1px solid {hubBorder};
+}
+.hub-num {
+  font-size: HUB_NUM_FONT_SIZE;
+  font-weight: 900;
+  color: {textColor};
+  letter-spacing: -4px;
+  line-height: 1;
+  font-variant-numeric: tabular-nums;
+}
+.hub-label {
+  font-size: HUB_LABEL_FONT_SIZE;
+  font-weight: 800;
+  letter-spacing: 12px;
+  color: {accentColor};
+  text-transform: uppercase;
+}
+.avatar {
+  position: absolute;
+  z-index: 2;
+  width: AVATAR_SIZE;
+  height: AVATAR_SIZE;
+  border-radius: 50%;
+  border: 3px solid {avatarBorder};
+  box-shadow:
+    0 12px 32px rgba(0, 0, 0, 0.5),
+    0 0 24px {avatarGlow};
+  display: grid;
+  place-items: center;
+  font-size: AVATAR_GLYPH_SIZE;
+  background: {avatarBg};
+  will-change: transform, opacity;
+  /* Top-left positioned by script; transform centers via -50% trick */
+  transform: translate(-50%, -50%);
+}
+.brand {
+  position: absolute;
+  bottom: 80px;
+  left: 50%;
+  transform: translateX(-50%);
+  font-size: BRAND_FONT_SIZE;
+  font-weight: 900;
+  letter-spacing: 14px;
+  color: {accentColor};
+  text-transform: uppercase;
+}
+```
+
+## 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 });
+
+  // CENTER_X / CENTER_Y must match the hub's rendered center exactly.
+  // For a hub-wrap with place-items:center on a 1920×1080 canvas these are
+  // (compositionWidth/2, compositionHeight × CENTER_Y_FACTOR).
+  const SCREEN_CENTER = { x: CENTER_X, y: CENTER_Y };
+
+  const hubWrap = document.querySelector(".hub-wrap");
+  const linesSvg = document.querySelector(".lines");
+
+  // Build avatars + lines
+  const avatarPositions = [];
+  for (let i = 0; i < AVATAR_COUNT; i++) {
+    const angle = (i / AVATAR_COUNT) * Math.PI * 2 - Math.PI / 2; // start at top
+    const x = SCREEN_CENTER.x + Math.cos(angle) * RADIUS_X;
+    const y = SCREEN_CENTER.y + Math.sin(angle) * RADIUS_Y;
+    avatarPositions.push({ x, y, angle });
+
+    // Avatar
+    const av = document.createElement("div");
+    av.className = "avatar";
+    av.style.left = `${x}px`;
+    av.style.top = `${y}px`;
+    // assign avatar image / glyph from your authoring data (see {avatar[i]})
+    hubWrap.appendChild(av);
+
+    // Line from hub to avatar
+    const line = document.createElementNS("http://www.w3.org/2000/svg", "line");
+    line.setAttribute("x1", SCREEN_CENTER.x);
+    line.setAttribute("y1", SCREEN_CENTER.y);
+    line.setAttribute("x2", x);
+    line.setAttribute("y2", y);
+    line.setAttribute("stroke", "{lineColor}");
+    line.setAttribute("stroke-width", "2");
+    line.setAttribute("stroke-dasharray", "6 8");
+    const len = Math.hypot(x - SCREEN_CENTER.x, y - SCREEN_CENTER.y);
+    line.style.strokeDashoffset = String(len);
+    line.dataset.length = String(len);
+    line.dataset.index = String(i);
+    linesSvg.appendChild(line);
+  }
+
+  // Phase 1 — hub fade in
+  tl.from(
+    ".hub",
+    { opacity: 0, scale: 0.8, duration: HUB_FADE_DUR, ease: `back.out(${HUB_BOUNCE})` },
+    HUB_FADE_START,
+  );
+
+  // Phase 2 — avatars cascade-in (staggered spring)
+  const avatars = document.querySelectorAll(".avatar");
+  avatars.forEach((av, i) => {
+    tl.from(
+      av,
+      {
+        opacity: 0,
+        scale: 0,
+        duration: AVATAR_ENTRY_DUR,
+        ease: `back.out(${AVATAR_BOUNCE})`,
+      },
+      AVATAR_ENTRY_START + i * AVATAR_STAGGER,
+    );
+  });
+
+  // Phase 3 — connection lines draw outward (staggered) — starts after most avatars land
+  const lines = linesSvg.querySelectorAll("line");
+  lines.forEach((line, i) => {
+    tl.to(
+      line,
+      {
+        strokeDashoffset: 0,
+        duration: LINES_DUR,
+        ease: "power2.out",
+      },
+      LINES_START + i * LINE_STAGGER,
+    );
+  });
+
+  // Phase 4 — climax dwell (network fully formed), idle breathing on avatars
+  // (see sine-wave-loop.md for the multiplicative onUpdate form)
+  const breathDriver = { p: 0 };
+  tl.to(
+    breathDriver,
+    {
+      p: Math.PI * 2 * BREATH_CYCLES,
+      duration: BREATH_DUR,
+      ease: "none",
+      onUpdate: () => {
+        avatars.forEach((av, i) => {
+          const phase = breathDriver.p + (i / avatars.length) * Math.PI * 2;
+          const s = 1 + Math.sin(phase) * BREATH_AMP;
+          av.style.transform = `translate(-50%, -50%) scale(${s})`;
+        });
+      },
+    },
+    BREATH_START,
+  );
+
+  window.__timelines["cloud-scene"] = tl;
+</script>
+```
+
+## How to Choose Values
+
+### Geometry
+
+- **CENTER_X / CENTER_Y** — px coordinates of the hub center; lines and avatar positions derive from these.
+  - Constraints: **must equal the hub's actual rendered center** — when this rule is composed with another scene (e.g. a logo that has been recentered), `CENTER_X / CENTER_Y` must be baked from the same source as the hub's final position
+  - Reference: ../../examples/proof-logo-chain.html uses `(W/2, H × 0.47)` so the cloud sits slightly above the canvas midline
+- **RADIUS_X / RADIUS_Y** — ellipse radii in px (RADIUS_X ≥ RADIUS_Y reads as perspective).
+  - Range: `RADIUS_X` ~ 20-30% of viewport width; `RADIUS_Y` ~ 18-25% of viewport height
+  - Constraints: `RADIUS_X / RADIUS_Y` ratio between 1.5 and 3.0 reads as natural depth; ratio = 1 (circle) reads as a flat 2D layout
+  - Reference: ../../examples/proof-logo-chain.html uses `W * 0.25` (`480px`) and `H * 0.22` (`237.6px`)
+- **AVATAR_COUNT** — number of avatars distributed around the ring.
+  - Range: 8-12; fewer feels sparse, more clutters the ellipse
+  - Reference: ../../examples/proof-logo-chain.html uses `10`
+- **AVATAR_SIZE / AVATAR_GLYPH_SIZE** — px diameter of each avatar circle and (optional) inner glyph size.
+  - Range: `AVATAR_SIZE` ~ 80-120 px at 1920 wide; small enough that 10+ avatars fit the ring without overlap
+- **HUB_NUM_FONT_SIZE / HUB_LABEL_FONT_SIZE / BRAND_FONT_SIZE** — hub typography.
+  - Constraints: hub-num is the focal beat, sized 2-4× the label
+
+### Hub fade
+
+- **HUB_FADE_START** — when the hub fades in.
+  - Range: usually `0` (the hub establishes the focal point); offset if the scene precedes with another beat
+- **HUB_FADE_DUR** — hub fade-in duration.
+  - Range: 0.4-0.6s
+- **HUB_BOUNCE** — `back.out(HUB_BOUNCE)` coefficient on the hub's scale entry.
+  - Range: 1.4 (subtle) → 1.8 (firm)
+
+### Avatar cascade
+
+- **AVATAR_ENTRY_START** — when the first avatar pops in.
+  - Constraints: `≥ HUB_FADE_START + HUB_FADE_DUR × 0.6` so the hub is established before satellites arrive
+- **AVATAR_ENTRY_DUR** — per-avatar scale-up duration.
+  - Range: 0.4-0.7s
+- **AVATAR_STAGGER** — delay between consecutive avatar entries.
+  - Range: 0.06-0.10s; cascade reads as "joining"; simultaneous reads as "all already there"
+- **AVATAR_BOUNCE** — `back.out(AVATAR_BOUNCE)` coefficient on each avatar's pop.
+  - Range: 1.4 (gentle) → 1.8 (firm); slightly firmer than hub for differentiation
+
+### Connection lines
+
+- **LINES_START** — when the lines begin drawing outward.
+  - Constraints: `LINES_START + (AVATAR_COUNT − 1) × LINE_STAGGER` should overlap the last avatar's settle by ~0.1-0.2s so the drawing reads as a consequence of the avatars landing
+- **LINES_DUR** — per-line draw duration (strokeDashoffset → 0).
+  - Range: 0.4-0.7s
+- **LINE_STAGGER** — delay between consecutive lines starting.
+  - Range: 0.02-0.05s; tight stagger reads as a wave outward
+
+### Idle breathing
+
+- **BREATH_START** — when idle breathing activates.
+  - Constraints: `≥ LINES_START + (AVATAR_COUNT − 1) × LINE_STAGGER + LINES_DUR + ~0.2s` (let the lines settle)
+- **BREATH_DUR** — total duration of the breathing tween.
+  - Range: fills the remaining composition window
+- **BREATH_CYCLES** — number of full sine cycles across `BREATH_DUR`.
+  - Range: 1.0-2.0; under 1 reads as a single sigh, over 2 starts to look anxious
+- **BREATH_AMP** — sine amplitude on scale (multiplicative).
+  - Range: 0.02-0.06; smaller for headshots, larger for stylized glyphs
+
+### Color tokens
+
+- **{bgColor}** — stage background (typically a dark gradient so the cloud reads as a constellation)
+- **{textColor}** — hub-num color (primary copy)
+- **{accentColor}** — hub-label + footer (the brand voice)
+- **{hubBg} / {hubBorder}** — hub card surfaces; gradient + 1px border reads as elevated
+- **{avatarBg} / {avatarBorder} / {avatarGlow}** — avatar circle styling; soft border + glow keeps them legible on dark backgrounds
+- **{lineColor}** — SVG stroke color (translucent accent reads as networky)
+- **{font}** — base typography stack
+
+## Variations
+
+### Avatar size variation (organic feel)
+
+Vary avatar sizes by index — e.g. a small index-keyed array of sizes — so the ring doesn't read as rigidly repetitive.
+
+### Solid lines instead of dashed
+
+Drop `stroke-dasharray` and use a solid stroke. Drop the dash-draw animation; lines fade in via opacity instead. More corporate, less networky.
+
+### Multi-orbit (concentric rings)
+
+Two layers of avatars: smaller inner ring (fewer avatars, slightly larger size), larger outer ring (more, smaller). Lines connect ONLY inner ring to hub; outer ring is a "halo."
+
+### Country / role glyphs (geographic or persona spread)
+
+Replace face images with flags / emoji / iconography. Reads as "global community" or "diverse roles."
+
+## Key Principles
+
+- **Hub above lines (`z-index: 5` vs lines `z-index: 1`)** — lines should appear to terminate AT the hub edge, not pass through. Hub must be in front.
+- **Lines drawn outward (dash offset 0)** — drawing FROM center is the visual narrative: "the hub connects to its community."
+- **8-12 avatars** — fewer feels sparse, more clutters the ellipse.
+- **`RADIUS_X > RADIUS_Y`** — horizontal ellipse reads as perspective; equal radii (circle) reads as 2D flat layout.
+- **Avatar entry stagger 0.06-0.10s** — cascade reads as "joining"; simultaneous reads as "all already there."
+- **Stagger lines AFTER avatars are mostly settled** — line draw starts ~0.1-0.2s before last avatar settles for overlap.
+- **Idle breathing post-formation** — each avatar slightly out-of-phase. Holds the eye during climax dwell.
+- **❗ Climax dwell ≥1s** — after lines complete, hold for ≥1s so the formed network is readable.
+
+## Critical Constraints
+
+- **Timeline must be paused**: `gsap.timeline({ paused: true })`
+- **Registry key = `data-composition-id`**
+- **No CSS animation** on avatars or lines
+- **`will-change: transform, opacity`** on avatars
+- **SVG `pointer-events: none`** — decorative overlay
+- **`getTotalLength()` not needed for straight lines** — use `Math.hypot` for line length (cheaper, exact)
+- **Hub `z-index` > lines z-index** — explicit layering
+
+## Combinations
+
+- [counting-dynamic-scale.md](counting-dynamic-scale.md) — the hub IS a growing counter
+- [sine-wave-loop.md](sine-wave-loop.md) — avatar idle breathing pattern
+- [3d-text-depth-layers.md](3d-text-depth-layers.md) — hub label with depth layers
+
+## Pairs with HF skills
+
+- `/hyperframes-animation` — staggered spring entries + SVG dash draw
+- `/hyperframes-core` — composition wiring
+- `/hyperframes-cli` — `hyperframes lint`