@mevdragon/vidfarm-devcli 0.14.0 → 0.16.0

package/.agents/skills/hyperframes-animation/rules/spring-pop-entrance.md

@@ -0,0 +1,273 @@
+---
+name: spring-pop-entrance
+description: The canonical entrance pop — an element (or staggered group) arrives by scaling 0 → 1 on a smooth long-tail settle (power3 default); bouncy overshoot is a rare, explicitly-playful exception. fromTo so it's correct at t=0 under seek.
+metadata:
+  tags: spring, entrance, pop, scale, power3, settle, stagger, reveal, arrival
+---
+
+# Spring-Pop Entrance
+
+> **Smooth beats bouncy.** Per the motion doctrine (`references/motion-language.md`), this entrance **defaults to a smooth long-tail settle — `power3.out` (or `expo.out` for a faster arrival)** that decelerates cleanly into the resting size with **no overshoot**. Bouncy `back.out` overshoot is the **#1 instant turn-off** in agent-made videos and is almost never executed well; it is demoted here to a **rare, explicitly-playful exception** (a consumer / fun brand), never the default. When unsure, settle smoothly.
+
+THE entrance primitive: an element (or a staggered group of them) arrives on screen by springing from nothing — `scale: 0 → 1`, optionally with a small `y` rise — riding a **smooth long-tail ease (`power3.out` default)** so it grows confidently into its resting size and settles without bouncing. This is **arrival**, not reaction.
+
+Explicitly distinct from [press-release-spring.md](press-release-spring.md): that rule is a click/press → release feedback chain (a press phase, then a spring recovery to `1.0`). This one has **no press phase** — there is no prior resting state, the element did not exist on screen, it springs into being. Many blueprints used to borrow `press-release-spring` to fake an entrance; reach for this instead.
+
+## How It Works
+
+A single `fromTo` carries the whole arrival:
+
+1. **From-state**: `{ scale: 0, opacity: 0 }` — the element is collapsed to a point and invisible. Stated explicitly in the `from` object so a seek to `t=0` lands the element in this exact state (never rely on a CSS-hidden start — see Critical Constraints).
+2. **To-state (default)**: `{ scale: 1, opacity: 1, ease: "power3.out" }` — a long-tail decel that grows the element into its resting size and **settles smoothly, no overshoot**. Use `expo.out` instead for a punchier, faster-front arrival (still no bounce). This smooth settle is the house style; the bouncy `back.out` variant is the rare playful exception (see Variations).
+
+For a **group**, the same `fromTo` runs per element with a **deterministic, index-derived stagger** (`i * STAGGER`), and the total entry window is **capped** (`ITEM_COUNT × STAGGER ≤ ~0.5s`) so the group reads as one arriving beat, not a slow arpeggio.
+
+A small `y` rise (`y: 24 → 0`) layers a subtle "lifts into place" on top of the pop — optional garnish; the `scale` grow on a smooth ease is the load-bearing motion. (A `rotation` settle belongs only to the playful overshoot variant below.)
+
+## HTML
+
+```html
+<!-- Single hero pop -->
+<div
+  class="scene"
+  data-composition-id="pop-scene"
+  data-start="0"
+  data-duration="3"
+  data-track-index="0"
+>
+  <div class="pop-hero" id="hero">{heroLabel}</div>
+</div>
+
+<!-- Staggered group: nodes / cards / icons / pills / callouts -->
+<div
+  class="scene"
+  data-composition-id="pop-group-scene"
+  data-start="0"
+  data-duration="3"
+  data-track-index="0"
+>
+  <div class="pop-grid">
+    <div class="pop-item">{itemA}</div>
+    <div class="pop-item">{itemB}</div>
+    <div class="pop-item">{itemC}</div>
+    <div class="pop-item">{itemD}</div>
+    <div class="pop-item">{itemE}</div>
+    <div class="pop-item">{itemF}</div>
+  </div>
+</div>
+```
+
+## CSS
+
+```css
+.scene {
+  position: relative;
+  width: 100%;
+  height: 100%;
+  display: grid;
+  place-items: center;
+  background: {bgColor};
+}
+.pop-hero {
+  display: grid;
+  place-items: center;
+  width: {heroSize};
+  height: {heroSize};
+  background: {heroBg};
+  border-radius: HERO_RADIUS;
+  font-family: {font};
+  font-weight: 900;
+  font-size: HERO_FONT_SIZE;
+  color: {heroTextColor};
+  /* Pop scales around the center — see Critical Constraints */
+  transform-origin: 50% 50%;
+  will-change: transform;
+}
+.pop-grid {
+  display: grid;
+  grid-template-columns: repeat(3, 1fr);
+  gap: GRID_GAP;
+  place-items: center;
+}
+.pop-item {
+  display: grid;
+  place-items: center;
+  width: {itemSize};
+  height: {itemSize};
+  background: {itemBg};
+  border-radius: ITEM_RADIUS;
+  font-family: {font};
+  font-weight: 800;
+  font-size: ITEM_FONT_SIZE;
+  color: {itemTextColor};
+  transform-origin: 50% 50%;
+  will-change: transform;
+}
+```
+
+## 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 });
+
+  // --- Single hero pop (default: smooth long-tail settle, no overshoot) ---
+  // fromTo states the collapsed start explicitly so the hero is correct at t=0
+  // under seek. power3.out grows scale into 1.0 and decelerates smoothly.
+  tl.fromTo(
+    "#hero",
+    { scale: 0, opacity: 0 },
+    {
+      scale: 1,
+      opacity: 1,
+      duration: POP_DUR,
+      ease: "power3.out", // smooth beats bouncy; expo.out for a punchier front
+    },
+    ENTRY_AT,
+  );
+
+  // --- Staggered group pop ---
+  // Deterministic, index-derived stagger (no Math.random). The cap keeps the
+  // whole group inside one arriving beat: ITEM_COUNT * STAGGER <= ~0.5s.
+  const items = gsap.utils.toArray(".pop-item");
+  items.forEach((el, i) => {
+    tl.fromTo(
+      el,
+      { scale: 0, opacity: 0, y: Y_RISE },
+      {
+        scale: 1,
+        opacity: 1,
+        y: 0,
+        duration: POP_DUR,
+        ease: "power3.out",
+      },
+      GROUP_ENTRY_AT + i * STAGGER,
+    );
+  });
+
+  window.__timelines["pop-scene"] = tl;
+</script>
+```
+
+## Variations
+
+### Calm settle (refined / enterprise / "premium calm") — default
+
+`power3.out`, no rotation, drop the `y` rise or keep it tiny (~12px). Reads as a confident, weighted settle — right for a hero wordmark or a single product shot landing. The safe default for premium / enterprise brands.
+
+### Firm settle (default product reveal) — default
+
+The everyday entrance. `power3.out` (or `expo.out` for a punchier front), optional `Y_RISE` ~24px. Clear, deliberate arrival that decelerates clean — the safe default for cards, icons, and callouts. **No overshoot.**
+
+### Bouncy pop (RARE — explicitly-playful only)
+
+The exception, not the default. **Only** for a deliberately playful register (a consumer / fun brand, a toy-like icon set) where a bounce is clearly the intent — never for product / enterprise / serious launch tone. Bouncy is the #1 turn-off and the agent rarely lands it, so reach for this knowingly and sparingly. Swap `power3.out` for `back.out(OVERSHOOT)` and (optionally) add a `rotation` settle so each element looks hand-placed:
+
+```js
+// Playful exception only — default to power3.out (see above).
+tl.fromTo(
+  el,
+  { scale: 0, opacity: 0, rotation: ROT_FROM },
+  { scale: 1, opacity: 1, rotation: 0, duration: POP_DUR, ease: `back.out(${OVERSHOOT})` },
+  GROUP_ENTRY_AT + i * STAGGER,
+);
+```
+
+Keep `OVERSHOOT` modest even here (≤ ~2) — past that it reads as a cartoon wobble, not an arrival.
+
+### Origin-anchored pop (callout springs from a pointer / source)
+
+When a callout should appear to grow out of a specific point (e.g. a station marker or pointer tip), set `transform-origin` to that point instead of center, so the `scale: 0 → 1` reads as "emerging from the source" rather than "inflating in place."
+
+```css
+.callout {
+  transform-origin: 0% 100%; /* bottom-left = pointer tip; match to the anchor */
+}
+```
+
+### Pop into a held slot — then hold (jitter at most)
+
+When a popped element then **holds** an ongoing slot (a constellation node, a persistent badge), do **not** bake an idle loop into this entrance — it must stay finite. Land the pop and let it hold still; if the held frame genuinely needs life, hand off to [sine-wave-loop.md](sine-wave-loop.md) for **subtle jitter** (low amplitude) on a separate, later tween — not a breathing loop. Prefer revealing the next element on its VO cue over keeping this one animating.
+
+## How to Choose Values
+
+- **EASE** — the settle curve (the load-bearing decision)
+  - Default: **`power3.out`** — a smooth long-tail settle, no overshoot; the house style for product / enterprise / serious tone. Use `expo.out` for a punchier, faster-front arrival (still smooth).
+  - Playful exception only: `back.out(OVERSHOOT)` — see the Bouncy pop variation; reach for it only when a bounce is clearly the brand intent.
+
+- **OVERSHOOT** — `back.out(OVERSHOOT)` overshoot strength — **only used in the rare bouncy variant**; the smooth default has no overshoot dial
+  - Range (playful only): ~1.3 (barely) → ~2.0 (clearly bouncy)
+  - Constraints: keep ≤ ~2 — past that the overshoot exceeds the element's bounds and reads as a cartoon wobble, not an arrival. If you're not in the explicitly-playful case, don't use this — use `power3.out`.
+
+- **POP_DUR** — duration of each element's `scale: 0 → 1` tween
+  - Range: 0.4 – 0.7 s
+  - Effects: shorter = tight snap; longer = a looser, more floating pop
+  - Constraints: the main subject must be visible by **`t ≤ 0.5s`** — keep `ENTRY_AT + POP_DUR`'s readable midpoint early; don't let the hero finish arriving after the half-second mark
+
+- **STAGGER** — gap between successive items' start times (group only)
+  - Range: 0.04 – 0.08 s
+  - Effects: < 0.04 reads as a simultaneous chord; > 0.08 feels lazy / arpeggiated
+  - Constraints: **`ITEM_COUNT × STAGGER ≤ ~0.5s`** (the cap) — beyond that the group stops reading as one beat. Cap the per-item stagger for large groups: `STAGGER = min(0.06, 0.5 / ITEM_COUNT)`
+
+- **ITEM_COUNT** — number of elements in a group pop
+  - Range: 3 – 9
+  - Effects: 3 = sparse; 9 = full grid. More than ~9 forces `STAGGER` so small the stagger vanishes — switch to a wipe/sweep reveal instead
+
+- **Y_RISE** — optional upward offset the element lifts from (`y: Y_RISE → 0`)
+  - Range: 0 (pure pop) – 32 px
+  - Effects: adds a subtle "lifts into place"; keep small so the `scale` pop stays dominant
+  - Constraints: 0 for the calm-settle variant; never large enough to read as a slide-up (that's a different primitive)
+
+- **ROT_FROM** — optional starting rotation, **playful (bouncy) variant only** (`rotation: ROT_FROM → 0`)
+  - Range: −10° – +10°
+  - Effects: a small tilt that resolves makes the element look hand-placed
+  - Constraints: derive sign/size deterministically from index if you want alternating tilt (e.g. `i % 2 ? 6 : -6`) — never `Math.random`
+
+- **ENTRY_AT / GROUP_ENTRY_AT** — timeline offset before the (group's) pop begins
+  - Range: 0 – 0.4 s
+  - Effects: > 0 gives a beat of quiet before the arrival; keep small so the subject still lands by `t ≤ 0.5s`
+
+### Geometry & tokens
+
+- **{heroSize} / {itemSize}** — footprints. A hero entrance should occupy a clearly readable share of the frame; group items size down so the grid fits with `GRID_GAP` breathing room.
+- **HERO_RADIUS / ITEM_RADIUS** — `height × 0.15` (sharp) → `height / 2` (pill).
+- **{heroBg} / {itemBg} / {\*TextColor}** — surface + label tokens; inherit from the composition palette.
+
+## Key Principles
+
+- **Smooth beats bouncy** — default to `power3.out` (or `expo.out`): a long-tail settle into `scale: 1`, no overshoot. Bouncy `back.out` is the rare, explicitly-playful exception (the #1 turn-off, and the agent rarely lands it). When unsure, settle smoothly.
+- **fromTo, always** — the collapsed `{ scale: 0, opacity: 0 }` start is stated in the `from` object so a seek to `t=0` lands it exactly there. An entrance built on a CSS-hidden start (e.g. `opacity:0` in CSS + a `.to()`) flickers under HF seek — the element renders visible before the tween claims it.
+- **Easing carries the motion, not keyframes** — let the ease produce the settle for free. Don't hand-key a `scale: 1.1` mid-state; that double-bounces and fights the curve. (And in the playful variant, the overshoot is a byproduct of `back.out`, not a hand-keyed bounce.)
+- **The grow is the motion** — `scale` is load-bearing; the `y` rise (and, in the playful variant, the `rotation` settle) is garnish layered on top. If you drop everything but the `scale` grow, it should still read as a clean entrance.
+- **Cap the stagger window** — a group must arrive inside ~0.5s total or it stops reading as one beat and starts reading as a slow list reveal. Derive the stagger from `ITEM_COUNT` so it self-caps.
+- **Deterministic per index** — all stagger and any rotation/tilt variation comes from the loop index, never `Math.random` — the renderer must produce the identical frame on every seek.
+- **Visible early** — the main subject must be on screen by `t ≤ 0.5s`. A hero that finishes arriving at `t=1s` wastes the opening beat.
+- **Don't bake an idle loop here** — this entrance is finite. If the element then holds a slot, hand off to `sine-wave-loop` on a later tween; an infinite `repeat`/`yoyo` here breaks seek.
+
+## Critical Constraints
+
+- **Timeline must be paused**: `gsap.timeline({ paused: true })`
+- **Registry key = `data-composition-id`**
+- **Entrances use `fromTo`** — explicit `{ scale: 0, opacity: 0 }` from-state; never rely on a CSS-hidden starting state
+- **No CSS `transition`** on popped elements — those interpolate independently of HF seek and cause flicker
+- **No `repeat` / `yoyo` / infinite tweens** — this is a finite arrival; idle motion is a separate `sine-wave-loop` tween
+- **No `Math.random` / `Date.now`** — stagger and tilt are index-derived and deterministic
+- **GSAP transform aliases only**: `x`, `y`, `scale`, `rotation`. Never tween `width` / `height` / `left` / `top`
+- **`transform-origin: 50% 50%`** for an in-place pop (default); set it to the source point only for the origin-anchored variation
+- **Default ease `power3.out`** (smooth, no overshoot); `back.out(OVERSHOOT)` only in the explicitly-playful variant, and there keep **`OVERSHOOT ≤ ~2`** — beyond that it reads as a cartoon wobble, not an arrival
+- **`ITEM_COUNT × STAGGER ≤ ~0.5s`** — the group must land inside one beat
+- **`will-change: transform`** on popped elements, especially groups — many simultaneous spring tweens benefit from compositor hints
+
+## Combinations
+
+- [sine-wave-loop.md](sine-wave-loop.md) — at most **subtle jitter** on a held node/badge AFTER its pop lands (don't bake any loop into the entrance; and prefer a VO-timed reveal over ambient motion — see that rule's caution)
+- [center-outward-expansion.md](center-outward-expansion.md) — elements pop in as they radiate from center to their slots
+- [press-release-spring.md](press-release-spring.md) — the reaction counterpart: once popped in, a button can take a press→release; this rule supplies the arrival, that one the click feedback
+
+## Pairs with HF skills
+
+- `/hyperframes-animation` — `power3.out` settle (smooth default), `fromTo` entrances, deterministic stagger
+- `/hyperframes-core` — composition wiring
+- `/hyperframes-cli` — `hyperframes lint`

package/.agents/skills/hyperframes-animation/rules/stat-bars-and-fills.md

@@ -0,0 +1,156 @@
+---
+name: stat-bars-and-fills
+description: Data-viz primitives that pair a number with a graphic — growth bars (CSS scaleY stagger), a progress fill (bar or ring), and a partial star-rating wipe. Seek-safe, deterministic.
+metadata:
+  tags: data, stats, chart, bars, progress, ring, stars, rating, infographic, number
+---
+
+# Stat Bars & Fills
+
+The graphics that give a stat **visual weight** beside its number: a small bar chart, a progress bar/ring filling to a percentage, or a star row filling to a fractional rating. Pair these with [counting-dynamic-scale.md](counting-dynamic-scale.md) (the number) for a complete stat scene.
+
+**Layout blueprint — pick ONE and hold it across all stats:**
+
+- **Single-focus** — one centered frame, the number is the hero, a ring or bar sits under/around it. Cleanest for a sequential reveal (stat 1 → stat 2 → stat 3 in the same frame).
+- **Split-frame** — big number on the left, paired graphic on the right. Better when stats are shown together or each needs a distinct visual.
+
+Don't mix blueprints between stats in one piece — that reads as inconsistent.
+
+## 1 — Growth Bars (CSS `scaleY` stagger)
+
+Bars grow from the baseline with a stagger; the last bar is the accent.
+
+```css
+.bars {
+  display: flex;
+  align-items: flex-end;
+  gap: 14px;
+  height: 280px;
+}
+.bar {
+  width: 48px;
+  background: #3a4a64;
+  transform: scaleY(0);
+  transform-origin: bottom center; /* grow UP from the baseline, not from center */
+}
+.bar:last-child {
+  background: #ffc300;
+} /* accent the final/current bar */
+```
+
+```js
+// Heights are authored in CSS (e.g. inline height per bar); GSAP only reveals scaleY 0→1.
+tl.to(".bar", { scaleY: 1, duration: 0.7, ease: "power3.out", stagger: 0.08 }, 0.3);
+```
+
+> Use `scaleY` (a transform), never animate `height` — height tweens are forbidden by the runtime. Set each bar's final height in CSS, scale from 0.
+
+## 2 — Progress Fill
+
+**Bar form** — `scaleX` from a left origin:
+
+```css
+.track {
+  width: 520px;
+  height: 16px;
+  background: #1b263b;
+  border-radius: 8px;
+  overflow: hidden;
+}
+/* width:100% is REQUIRED — an absolutely-positioned fill with no width is 0px, and scaleX of 0 is
+   still 0 → the bar renders invisible (and no lint/inspect check catches a zero-width scaled element). */
+.fill {
+  width: 100%;
+  height: 100%;
+  background: #ffc300;
+  transform: scaleX(0);
+  transform-origin: left center;
+}
+```
+
+```js
+const PCT = 0.92; // 92%
+tl.to(".fill", { scaleX: PCT, duration: 1.0, ease: "power2.out" }, 0.3);
+```
+
+**Ring form** — measured stroke draw (delegates to [svg-path-draw.md](svg-path-draw.md)):
+
+```js
+const ring = document.querySelector("#ring");
+const LEN = ring.getTotalLength(); // measure, don't hard-code the circumference
+ring.style.strokeDasharray = LEN;
+ring.style.strokeDashoffset = LEN; // empty
+// rotate the <circle> -90deg in CSS so the fill starts at 12 o'clock
+tl.to(ring, { strokeDashoffset: LEN * (1 - 0.92), duration: 1.1, ease: "power2.out" }, 0.3);
+```
+
+## 3 — Star-Rating Fill (fractional)
+
+A gold star row revealed left-to-right to a fractional value (e.g. 4.6 / 5) via a clip wipe over a gold layer sitting on a gray layer.
+
+```html
+<div class="stars">
+  <div class="stars-gray">★★★★★</div>
+  <div class="stars-gold" id="goldStars">★★★★★</div>
+</div>
+```
+
+```css
+.stars {
+  position: relative;
+  font-size: 64px;
+  letter-spacing: 8px;
+}
+.stars-gray {
+  color: #2b3548;
+}
+.stars-gold {
+  position: absolute;
+  inset: 0;
+  color: #ffc300;
+  width: 100%;
+  clip-path: inset(0 100% 0 0);
+}
+```
+
+```js
+const RATING = 4.6,
+  MAX = 5;
+tl.to(
+  "#goldStars",
+  { clipPath: `inset(0 ${100 - (RATING / MAX) * 100}% 0 0)`, duration: 1.0, ease: "power2.out" },
+  0.3,
+);
+```
+
+## How to Choose Values
+
+- **Bar count** — 4–6 reads as "a trend" without clutter; the last bar is the current/accent value.
+- **Fill duration** — 0.8–1.2s, matched to the paired count-up so number and graphic land together (share the ease).
+- **Accent hue** — exactly one; bars/fill/stars all use the same accent, the rest is muted.
+- **Stagger** — 0.06–0.1s on bars; larger feels sluggish, 0 loses the build.
+
+## Key Principles
+
+- **Transforms only** — `scaleY` / `scaleX` / `clipPath`, never `width`/`height` tweens (runtime-forbidden).
+- **Match the number's timing** — the fill and the count-up should peak together (same start + ease), so the stat resolves as one beat, not two.
+- **Measure, don't hard-code** — ring length via `getTotalLength()`; a hard-coded circumference breaks if the radius changes.
+- **One accent hue, consistent blueprint** — see `hyperframes-creative/references/data-in-motion.md`.
+
+## Critical Constraints
+
+- **Timeline paused**; build synchronously; registry key = `data-composition-id`.
+- **`onUpdate` (if pairing a counter) must be O(1)** — the runtime seeks frame-by-frame (see [counting-dynamic-scale.md](counting-dynamic-scale.md)).
+- **No `height`/`width` tweens, no `repeat: -1`** — transforms + finite repeats only.
+- **`transform-origin`** must be `bottom` (bars grow up) / `left` (bars/fills grow right) — default center origin scales from the middle and looks wrong.
+
+## Combinations
+
+- [counting-dynamic-scale.md](counting-dynamic-scale.md) — the number beside the graphic (pair them; same ease/duration)
+- [svg-path-draw.md](svg-path-draw.md) — the progress-ring draw mechanics
+
+## Pairs with HF skills
+
+- `/hyperframes-animation` — timeline + transform tweens
+- `/hyperframes-creative` — `references/data-in-motion.md` (stat layout + visual weight)
+- `/hyperframes-core` — composition wiring; the no-`width`/`height`-tween rule