freecodego 0.1.7-alpha.2.2 → 0.1.7-rc.2.2

package/dist/assets/design/skills/hyperframes-animation/rules/split-tilt-cards.md

@@ -0,0 +1,123 @@
+---
+name: split-tilt-cards
+description: Two cards side-by-side with opposing Y-rotation creating a symmetric 3D split-screen layout for comparisons or feature pairs.
+metadata:
+  tags: 3d, cards, split, tilt, comparison, symmetric, layout
+---
+
+# Split Tilt Cards
+
+Two cards side-by-side with opposing `rotateY` (left `+TILT`, right `−TILT`) — a symmetric "book-open" 3D split for comparisons, before/after, feature pairs. Each card slides in from its own side (reinforcing "they came from their own worlds and met here"), then the pair idles in counter-phase.
+
+## How It Works
+
+`perspective` on the scene root (REQUIRED — without it `rotateY` flattens to a 2D layout) and `transform-style: preserve-3d` on the stage and both cards. Entry starts each card off-axis with `TILT + TILT_OVERSHOOT`, settling to `TILT` — a pivot-into-place. Idle is a gentle counter-phase y-bob (the two yoyo tweens run in opposite directions); copy fades up during the cards' settle, not after.
+
+## Recipe
+
+```html
+<!-- inside a standard scene clip (hyperframes-core) -->
+<div class="split-stage">
+  <div class="card card-left">
+    <div class="card-eyebrow">{leftEyebrow}</div>
+    <div class="card-headline">{leftHeadline}</div>
+    <div class="card-body">{leftBody}</div>
+  </div>
+  <div class="card card-right">…</div>
+</div>
+```
+
+```css
+.scene-root {
+  display: grid;
+  place-items: center;
+  perspective: SCENE_PERSPECTIVE; /* REQUIRED */
+}
+.split-stage {
+  display: flex;
+  gap: STAGE_GAP;
+  transform-style: preserve-3d;
+}
+.card {
+  width: CARD_WIDTH;
+  transform-style: preserve-3d;
+  will-change: transform;
+}
+/* Shadow falls WITH the facing direction: left card faces right → shadow right. */
+.card-left {
+  box-shadow: -CARD_SHADOW_OFFSET CARD_SHADOW_DROP CARD_SHADOW_BLUR {shadowColor};
+}
+.card-right {
+  box-shadow: CARD_SHADOW_OFFSET CARD_SHADOW_DROP CARD_SHADOW_BLUR {shadowColor};
+}
+```
+
+```js
+// Entry — from outside, opposing tilts settle with a small pivot
+tl.fromTo(
+  ".card-left",
+  { x: -ENTRY_SLIDE_DIST, rotateY: TILT + TILT_OVERSHOOT, opacity: 0 },
+  { x: 0, rotateY: TILT, opacity: 1, duration: ENTRY_DUR, ease: "power3.out" },
+  LEFT_AT,
+);
+tl.fromTo(
+  ".card-right",
+  { x: ENTRY_SLIDE_DIST, rotateY: -TILT - TILT_OVERSHOOT, opacity: 0 },
+  { x: 0, rotateY: -TILT, opacity: 1, duration: ENTRY_DUR, ease: "power3.out" },
+  RIGHT_AT,
+);
+
+// Counter-phase idle bob — opposite signs = alive; synchronized = conveyor belt
+tl.to(
+  ".card-left",
+  { y: -FLOAT_AMP, duration: FLOAT_DURATION / 2, ease: "sine.inOut", yoyo: true, repeat: 1 },
+  IDLE_START,
+);
+tl.to(
+  ".card-right",
+  { y: FLOAT_AMP, duration: FLOAT_DURATION / 2, ease: "sine.inOut", yoyo: true, repeat: 1 },
+  IDLE_START,
+);
+
+// Copy fades up during the settle
+tl.from(
+  ".card-eyebrow, .card-headline, .card-body",
+  { opacity: 0, y: COPY_RISE, stagger: COPY_STAGGER, duration: COPY_DUR, ease: "power2.out" },
+  COPY_REVEAL_AT,
+);
+```
+
+## Variations
+
+- **Badges / floating labels**: position them on the PARENT, never inside a card — inside they inherit the `rotateY` and tilt off-axis.
+- **3+ cards**: center card stays flat (`rotateY: 0`), outer two tilt inward — "old way / nothing / our way."
+- **Zoom-through**: a separate camera tween scaling `.split-stage` reads as the viewer crossing the gap between the tilted pair.
+
+## Values
+
+| token             | range                            | notes                                                   |
+| ----------------- | -------------------------------- | ------------------------------------------------------- |
+| SCENE_PERSPECTIVE | 1000–2400px                      | lower exaggerates the tilt; higher reads near-isometric |
+| TILT              | 10–18°                           | < 10 reads almost flat; > 18 folds shut and copy blurs  |
+| TILT_OVERSHOOT    | 4–12°                            | the pivot-into-place feel                               |
+| STAGE_GAP         | 40–120px (~0.06–0.15×CARD_WIDTH) | small = fused pair; large = compared-but-separate       |
+| CARD_WIDTH        | 480–820px @1920                  | `2×CARD_WIDTH + STAGE_GAP ≤ 0.95×stage` at full tilt    |
+| ENTRY_SLIDE_DIST  | 200–500px (~0.3–0.6×CARD_WIDTH)  |                                                         |
+| ENTRY_DUR         | 0.6–1.2s                         |                                                         |
+| RIGHT_AT          | LEFT_AT + 0–0.3s                 | zero feels mechanical; large fragments the pair         |
+| FLOAT_AMP         | 3–8px                            | subtle is the point                                     |
+| FLOAT_DURATION    | 1.6–3.2s round trip              | breathing cadence; IDLE_START ≥ entry end               |
+| COPY_REVEAL_AT    | during the entry tail            | copy popping in after cards are idle reads disconnected |
+
+## Critical Constraints
+
+- **`perspective` on the scene root is REQUIRED**; `preserve-3d` on the stage AND each card.
+- **Shadow direction matches tilt** — left card faces right → shadow falls right (and mirrored). Wrong sign reads as broken 3D.
+- **Counter-phase idle** — the two bobs run with opposite signs at the same position.
+- **Badges outside the card divs** (they'd inherit the rotation).
+- **Body copy ≤ 2 lines per card** — tilted long paragraphs collapse into perspective blur.
+- **Symmetric weight** — same width, same vertical center, similar line counts; asymmetry breaks the comparison metaphor.
+
+## See also
+
+`card-morph-anchor` (the pair can morph into one unified shape afterward) · `counting-dynamic-scale` (numbers as each side's headline) · `sine-wave-loop` (the idle form).

package/dist/assets/design/skills/hyperframes-animation/rules/spring-pop-entrance.md

@@ -0,0 +1,107 @@
+---
+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.** This entrance defaults to a smooth long-tail settle — `power3.out` (or `expo.out` for a faster front) — that decelerates cleanly into the resting size with **no overshoot**. Bouncy `back.out` is the **#1 instant turn-off** in agent-made videos and is almost never executed well; it is a rare, explicitly-playful exception (consumer / fun brand), never the default. When unsure, settle smoothly.
+
+THE entrance primitive: an element (or staggered group) arrives by springing from nothing — `scale: 0 → 1`, optional small `y` rise — and settles without bouncing. This is **arrival**, not reaction: distinct from [press-release-spring.md](press-release-spring.md) (a click/press → release feedback chain on an element that already rests on screen). Many blueprints used to borrow that rule to fake an entrance; reach for this instead.
+
+## How It Works
+
+One `fromTo` carries the whole arrival: from `{ scale: 0, opacity: 0 }` (explicit, so t=0 is correct under seek) to `{ scale: 1, opacity: 1, ease: "power3.out" }`. For a **group**, the same `fromTo` runs per element at `i * STAGGER`, capped so the group reads as one arriving beat. The `scale` grow is load-bearing; the `y` rise is garnish — drop everything else and it must still read as a clean entrance. Let the ease produce the settle: never hand-key a `scale: 1.1` mid-state (it double-bounces against the curve).
+
+## Recipe
+
+```html
+<!-- inside a standard scene clip (hyperframes-core) -->
+<div class="pop-hero" id="hero">{heroLabel}</div>
+
+<div class="pop-grid">
+  <div class="pop-item">{itemA}</div>
+  <div class="pop-item">{itemB}</div>
+  <div class="pop-item">{itemC}</div>
+</div>
+```
+
+```css
+.pop-hero,
+.pop-item {
+  transform-origin: 50% 50%; /* in-place pop; move to the source point for the anchored variation */
+  will-change: transform;
+}
+.pop-grid {
+  display: grid;
+  grid-template-columns: repeat(3, 1fr);
+  gap: GRID_GAP;
+  place-items: center;
+}
+```
+
+```js
+// Single hero pop — smooth long-tail settle, no overshoot.
+tl.fromTo(
+  "#hero",
+  { scale: 0, opacity: 0 },
+  { scale: 1, opacity: 1, duration: POP_DUR, ease: "power3.out" },
+  ENTRY_AT,
+);
+
+// Staggered group pop — one arriving beat.
+gsap.utils.toArray(".pop-item").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,
+  );
+});
+```
+
+## Variations
+
+- **Calm settle** (premium / enterprise): `power3.out`, no rotation, `Y_RISE` 0–12px — a weighted, confident landing for a hero wordmark or product shot.
+- **Firm settle** (everyday default): `power3.out` or `expo.out` for a punchier front, `Y_RISE` ~24px — cards, icons, callouts.
+- **Exact-physics settle**: when the settle IS the shot, swap the ease for `springEase({ response: 0.4 })` (critically damped) from `../adapters/gsap-easing-and-stagger.md` → Spring Eases; take `duration` from the helper.
+- **Origin-anchored pop**: a callout growing out of a specific point (marker, pointer tip) sets `transform-origin` to that point (e.g. `0% 100%`) so `scale: 0 → 1` reads as "emerging from the source", not "inflating in place".
+- **Pop into a held slot**: land the pop and hold still — no idle loop baked into the entrance. If the held frame genuinely needs life, hand off to [sine-wave-loop.md](sine-wave-loop.md) for subtle jitter on a separate later tween; prefer revealing the next element on its VO cue.
+- **Bouncy pop (RARE — explicitly-playful only)**: swap the ease for `back.out(OVERSHOOT)` and optionally settle a small `rotation: ROT_FROM → 0` so elements look hand-placed. Only for a deliberately playful register — never product / enterprise / serious tone:
+
+```js
+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,
+);
+```
+
+Even here keep `OVERSHOOT ≤ ~2` — past that it reads as cartoon wobble. Better still: the baked spring at `dampingFraction: 0.6–0.7` (same adapters doc) gives ~5–10% overshoot that reads physical where `back.out` reads cartoon.
+
+## Values
+
+| token      | range                                     | notes                                                            |
+| ---------- | ----------------------------------------- | ---------------------------------------------------------------- |
+| EASE       | `power3.out` default; `expo.out` punchier | `back.out(OVERSHOOT)` only in the playful variant                |
+| POP_DUR    | 0.4–0.7s                                  | shorter = tight snap; hero must be visible by **t ≤ 0.5s**       |
+| STAGGER    | 0.04–0.08s                                | `min(0.06, 0.5 / ITEM_COUNT)` — self-caps the window             |
+| ITEM_COUNT | 3–9                                       | >9 makes the stagger vanish — switch to a wipe/sweep reveal      |
+| Y_RISE     | 0–32px                                    | small; never large enough to read as a slide-up                  |
+| ROT_FROM   | −10°–+10°                                 | playful variant only; alternate sign by index (`i % 2 ? 6 : -6`) |
+| ENTRY_AT   | 0–0.4s                                    | a beat of quiet, but keep the subject landing by t ≤ 0.5s        |
+
+## Critical Constraints
+
+- Default ease `power3.out` (no overshoot); `back.out` only in the explicitly-playful variant, and there `OVERSHOOT ≤ ~2`.
+- `ITEM_COUNT × STAGGER ≤ ~0.5s` — the group must land inside one beat.
+- Entrances state the collapsed from-state in `fromTo` — never rely on a CSS-hidden start (it renders visible before the tween claims it under seek).
+- `transform-origin: 50% 50%` for an in-place pop; the source point only for the anchored variation.
+- This is a finite arrival — idle motion on a held element is a separate, later `sine-wave-loop` tween.
+
+## See also
+
+`center-outward-expansion` (pop while radiating to slots) · `press-release-spring` (the click-feedback counterpart) · `sine-wave-loop` (post-arrival jitter, sparingly).

package/dist/assets/design/skills/hyperframes-animation/rules/stat-bars-and-fills.md

@@ -0,0 +1,145 @@
+---
+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.
+
+## Recipe
+
+### 1 — Growth Bars (CSS `scaleY` stagger)
+
+Bars grow from the baseline with a stagger; the last bar is the accent. Heights are authored in CSS (inline height per bar); GSAP only reveals `scaleY: 0 → 1` — never animate `height`.
+
+```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
+tl.to(".bar", { scaleY: 1, duration: 0.7, ease: "power3.out", stagger: 0.08 }, 0.3);
+```
+
+### 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 (automated gates may miss 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 (mechanics in [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,
+);
+```
+
+## Values
+
+| token         | range       | notes                                                                               |
+| ------------- | ----------- | ----------------------------------------------------------------------------------- |
+| 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) |
+| stagger       | 0.06–0.1s   | larger feels sluggish, 0 loses the build                                            |
+| accent hue    | exactly one | bars/fill/stars all use the same accent, the rest is muted                          |
+
+## Critical Constraints
+
+- **`scaleY` / `scaleX` / `clipPath`, never `height`/`width` tweens** — author each bar's final height in CSS and scale from 0.
+- **`transform-origin`** must be `bottom` (bars grow up) / `left` (fills grow right) — the default center origin scales from the middle and looks wrong.
+- **`.fill` needs `width: 100%`** — a zero-width fill scaled by any factor is still invisible, and automated gates may miss it.
+- **Measure, don't hard-code** — ring length via `getTotalLength()`; a hard-coded circumference breaks if the radius changes.
+- **Match the number's timing** — the fill and the count-up peak together (same start + ease) so the stat resolves as one beat, not two; a paired counter's `onUpdate` must be O(1) (see [counting-dynamic-scale.md](counting-dynamic-scale.md)).
+- **One accent hue, consistent blueprint** — see `hyperframes-creative/references/data-in-motion.md`.
+
+## See also
+
+`counting-dynamic-scale` (the number beside the graphic — same ease/duration) · `svg-path-draw` (progress-ring draw mechanics) · `hyperframes-creative/references/data-in-motion.md` (stat layout + visual weight).

package/dist/assets/design/skills/hyperframes-animation/rules/svg-icon-enrichment.md

@@ -0,0 +1,141 @@
+---
+name: svg-icon-enrichment
+description: Animate internal SVG elements (rotating hands, opening blades, pulsing dots, dash flows) to make icons feel alive without replacing them.
+metadata:
+  tags: svg, icon, animation, internal, micro-animation, pulse, rotation
+---
+
+# SVG Icon Enrichment
+
+Treats an SVG icon as a composition of animated PARTS, not an opaque image. Each meaningful internal element (a clock hand, scissor blade, recording dot, data line) gets its own micro-animation, targeted by id. Distinct from [svg-path-draw](svg-path-draw.md) (which animates the OUTLINE drawing) — enrichment animates INTERNAL PARTS, ideally after the outline has drawn.
+
+Four signature patterns:
+
+| Pattern     | Use For                            | Math                                  | Tip                                |
+| ----------- | ---------------------------------- | ------------------------------------- | ---------------------------------- |
+| Rotation    | Clock, gear, loader, dial          | `rotate(deg cx cy)` attribute, linear | see the transform-center gotcha    |
+| Oscillation | Scissors, wings, toggle            | `rotate(±sin·amp)` on opposing groups | opposite signs on the two parts    |
+| Pulse       | Recording dot, heart, notification | `scale(1 + sin·amp)` + opacity        | ring lags dot by π/2 for ripple    |
+| Dash flow   | Cutting line, data stream          | `strokeDashoffset` linear via time    | negative for L→R, positive for R→L |
+
+## The transform-center gotcha
+
+**For rotation around an explicit point inside an SVG, use the SVG `transform` ATTRIBUTE, not CSS transform**: `el.setAttribute("transform", `rotate(${deg} ${cx} ${cy})`)`. The CSS combination `transform: rotate(...)` + `transform-origin: 60px 60px` + `transform-box: fill-box` interprets the origin in the element's OWN **bbox-local** coordinates, NOT viewBox coordinates. For a thin `<line>` (whose bbox is the line's narrow envelope), `60 60` bbox-local is a point OUTSIDE the line — the hand flies along an off-center arc instead of rotating in place. Same trap for small inner shapes (a dot circle whose bbox is the small circle, not the full viewBox).
+
+**Scaling around a center point**: same attribute route — `el.setAttribute("transform", `translate(${cx} ${cy}) scale(${s}) translate(-${cx} -${cy})`)`.
+
+## Recipe
+
+```html
+<!-- inside a standard scene clip — named children are the animation targets -->
+<svg class="icon-svg" viewBox="0 0 120 120" xmlns="http://www.w3.org/2000/svg">
+  <circle cx="60" cy="60" r="50" fill="none" stroke="{accentColor}" stroke-width="6" />
+  <line
+    id="hand-min"
+    x1="60"
+    y1="60"
+    x2="60"
+    y2="22"
+    stroke="{textColor}"
+    stroke-width="6"
+    stroke-linecap="round"
+  />
+  <line
+    id="hand-sec"
+    x1="60"
+    y1="60"
+    x2="60"
+    y2="30"
+    stroke="{recordColor}"
+    stroke-width="3"
+    stroke-linecap="round"
+  />
+  <circle cx="60" cy="60" r="6" fill="{textColor}" />
+</svg>
+<!-- pulse icon: #rec-ring + #rec-dot circles; dash-flow: a <line> with stroke-dasharray="14 12" -->
+```
+
+```js
+// Pattern 1 — Rotation. Proxy tween → SVG transform attribute (explicit center, see gotcha).
+const hand = document.getElementById("hand-min");
+const minState = { deg: 0 };
+tl.to(
+  minState,
+  {
+    deg: 360 * MIN_REVOLUTIONS,
+    duration: TOTAL_DURATION,
+    ease: "none", // linear motion is the point
+    onUpdate: () => hand.setAttribute("transform", `rotate(${minState.deg} 60 60)`),
+  },
+  0,
+);
+// second hand: same shape with SEC_REVOLUTIONS (visibly faster).
+
+// Pattern 3 — Pulse. One phase proxy drives dot + ring, ring offset by π/2.
+const dot = document.getElementById("rec-dot");
+const ring = document.getElementById("rec-ring");
+const pulse = { p: 0 };
+tl.to(
+  pulse,
+  {
+    p: Math.PI * 2 * PULSE_CYCLES,
+    duration: TOTAL_DURATION,
+    ease: "none", // sine handles the curve
+    onUpdate: () => {
+      const sD = 1 + Math.sin(pulse.p) * PULSE_DOT_AMP;
+      const sR = 1 + Math.sin(pulse.p + Math.PI / 2) * PULSE_RING_AMP;
+      dot.setAttribute("transform", `translate(60 60) scale(${sD}) translate(-60 -60)`);
+      ring.setAttribute("transform", `translate(60 60) scale(${sR}) translate(-60 -60)`);
+      ring.style.opacity = String(
+        PULSE_RING_OPACITY_BASE + Math.sin(pulse.p) * PULSE_RING_OPACITY_AMP,
+      );
+    },
+  },
+  0,
+);
+
+// Pattern 4 — Dash flow. Linear offset tween on a dashed stroke.
+const flowState = { offset: 0 };
+tl.to(
+  flowState,
+  {
+    offset: DASH_FLOW_TOTAL_OFFSET, // negative = L→R
+    duration: TOTAL_DURATION,
+    ease: "none",
+    onUpdate: () => {
+      document.getElementById("data-flow").style.strokeDashoffset = String(flowState.offset);
+    },
+  },
+  0,
+);
+```
+
+## Variations
+
+- **Stroke draw → enrichment chain** — draw the outline first via [svg-path-draw](svg-path-draw.md) (phase 1, `0 → OUTLINE_DUR`), then start enrichment at `OUTLINE_DUR`: the icon "wakes up" after assembly.
+- **Per-icon entry stagger** — for a row of icons, each icon's enrichment starts as it fades in, not synchronized.
+
+## Values
+
+| token                           | range                | notes                                                                                           |
+| ------------------------------- | -------------------- | ----------------------------------------------------------------------------------------------- |
+| MIN_REVOLUTIONS                 | 0.5–2.0              | avoid integer revolutions if the end frame is visible (lands back at start)                     |
+| SEC_REVOLUTIONS                 | 4–10                 | > MIN × 3 or the speed difference doesn't read                                                  |
+| PULSE_CYCLES                    | 2–4 over a 3–5s comp | ≥5 reads as anxious flicker; ≤1 reads as forgotten                                              |
+| PULSE_DOT_AMP                   | 0.05–0.20            | 0.05 = breathing; 0.20 = throbbing                                                              |
+| PULSE_RING_AMP                  | 0.04–0.12            | must be < PULSE_DOT_AMP or the ring overshadows the dot                                         |
+| PULSE_RING_OPACITY_BASE / \_AMP | 0.4–0.6 / 0.3–0.5    | BASE − AMP ≥ 0 and BASE + AMP ≤ 1                                                               |
+| DASH_FLOW_TOTAL_OFFSET          | ±100–400             | must be an integer multiple of the dash period (dash + gap) or the end frame shows a phase jump |
+
+## Critical Constraints
+
+- **The transform-center gotcha above** — SVG `transform` attribute for any rotation/scale around an explicit interior point; never CSS `transform-origin` + `transform-box: fill-box` on thin lines or small inner shapes.
+- **No `requestAnimationFrame`** — like CSS animation, it desyncs from HF's frame-by-frame seek; continuous motion lives inside the timeline as linear proxy tweens.
+- **Amplitudes subtle** — icons are decorative, not headlines; calibrate rotation speed against composition length, not absolute time.
+- **Phase-offset the parts** — minute vs second hand at different speeds, ring lagging dot by π/2. Pure sync looks mechanical.
+- **`stroke-linecap: round`** on flowing/dashed lines for clean dash edges.
+- **Climax dwell ≥1s** — if the enrichment is the headline beat, the composition continues ≥1s after the most dramatic moment.
+
+## See also
+
+`svg-path-draw` (outline draws first, enrichment second) · `orbit-3d-entry` (orbiting items are enriched icons) · `sine-wave-loop` (the whole icon floats while internal parts animate).

package/dist/assets/design/skills/hyperframes-animation/rules/svg-path-draw.md

@@ -0,0 +1,122 @@
+---
+name: svg-path-draw
+description: Animate SVG paths drawing progressively using stroke-dasharray and stroke-dashoffset.
+metadata:
+  tags: svg, stroke, draw, path, reveal, icon, vector
+---
+
+# SVG Path Draw
+
+Reveals an SVG shape by animating its stroke as if a pen were tracing it. Two stroke properties together: **`stroke-dasharray = <pathLength>`** makes the entire path one dash; **`stroke-dashoffset`** starts at the path length (dash shifted fully out of view → invisible) and tweens to `0` (fully drawn). The length comes from the DOM API `path.getTotalLength()` — measured, never guessed.
+
+Works on anything with a stroke: `<path>`, `<circle>`, `<rect>`, `<line>`, `<polyline>`, `<polygon>`, `<ellipse>`.
+
+## Recipe
+
+```html
+<!-- inside a standard scene clip -->
+<svg class="logo-mark" viewBox="0 0 200 200" xmlns="http://www.w3.org/2000/svg">
+  <path id="bar-left" d="M 60 40 L 60 160" />
+  <path id="bar-right" d="M 140 40 L 140 160" />
+  <path id="bar-mid" d="M 60 100 L 140 100" />
+</svg>
+```
+
+```css
+.logo-mark path {
+  fill: none; /* outline-only draw — a fill would appear immediately and ruin the reveal */
+  stroke: {accentColor};
+  stroke-width: 12;
+  stroke-linecap: round; /* softer endpoints */
+  stroke-linejoin: round;
+}
+```
+
+```js
+// Setup: measure each path and set its dash pattern. Real measured geometry, not a magic number.
+document.querySelectorAll(".logo-mark path").forEach((p) => {
+  const len = p.getTotalLength();
+  p.style.strokeDasharray = `${len}`;
+  p.style.strokeDashoffset = `${len}`;
+});
+
+// Stagger draws so the eye reads continuous motion — each segment starts at
+// ~70-80% of the previous segment's duration, before it finishes.
+tl.to(
+  "#bar-left",
+  { strokeDashoffset: 0, duration: SEGMENT_DRAW_DUR, ease: "power2.out" },
+  SEG_1_START,
+);
+tl.to(
+  "#bar-right",
+  { strokeDashoffset: 0, duration: SEGMENT_DRAW_DUR, ease: "power2.out" },
+  SEG_2_START,
+);
+tl.to(
+  "#bar-mid",
+  { strokeDashoffset: 0, duration: FINAL_SEGMENT_DUR, ease: "power2.out" },
+  SEG_3_START,
+);
+
+// Companion wordmark fades in only after the last stroke settles.
+tl.to(
+  ".brand-line",
+  { opacity: 1, duration: BRAND_FADE_DUR, ease: "power1.out" },
+  BRAND_FADE_START,
+);
+```
+
+## Variations
+
+- **Ring starting at 12 o'clock** — `<circle>` / `<rect>` strokes start at 3 o'clock by default; rotate the element `-90deg` so a progress ring draws from the top:
+
+```html
+<circle
+  cx="100"
+  cy="100"
+  r="60"
+  id="ring"
+  style="transform-origin: 100px 100px; transform: rotate(-90deg)"
+/>
+```
+
+- **Linear (constant-speed) draw** — `ease: "none"` for a steady-rate "real pen" trace.
+- **Draw then fill** — for filled shapes, tween `fillOpacity: 0 → 1` AFTER the stroke completes (requires `fill-opacity: 0` initially and a real `fill` in CSS):
+
+```js
+tl.to(
+  "#path",
+  { strokeDashoffset: 0, duration: SEGMENT_DRAW_DUR, ease: "power2.out" },
+  SEG_1_START,
+);
+tl.to(
+  "#path",
+  { fillOpacity: 1, duration: FILL_FADE_DUR, ease: "power1.out" },
+  SEG_1_START + SEGMENT_DRAW_DUR,
+);
+```
+
+## Values
+
+| token             | range                                   | notes                                                                                              |
+| ----------------- | --------------------------------------- | -------------------------------------------------------------------------------------------------- |
+| SEGMENT_DRAW_DUR  | 0.3–0.8s                                | fast snap vs deliberate pen trace; >~1s feels sluggish for a logo reveal                           |
+| FINAL_SEGMENT_DUR | 60–80% of SEGMENT_DRAW_DUR              | proportional to segment length — a short connector at full duration reads slower than its siblings |
+| SEG_N_START       | previous start + 70–80% of its duration | reads as continuous motion, not N isolated animations                                              |
+| SEG_1_START       | 0–0.4s                                  | a small ~0.2s lead-in lets the viewer settle before motion                                         |
+| BRAND_FADE_START  | ≥ last stroke end (+ ~0.2s beat)        | earlier and the wordmark competes with the draw                                                    |
+| BRAND_FADE_DUR    | 0.3–0.8s                                | snap (urgent) vs glide (premium)                                                                   |
+
+Ease families are discrete choices: **stroke draws** use `power2.out` (a hand lifting at end of stroke) or `none` for constant speed — never `back.out` / `elastic.out` (pens don't bounce). **Fades** use `power1.out`.
+
+## Critical Constraints
+
+- **`fill: none`** for outline-only draws — otherwise the fill appears immediately.
+- **Dasharray/dashoffset = the measured `getTotalLength()`**, set at setup; requires the SVG in the DOM (inline SVG is fine; a loaded `<image>` SVG is not).
+- **Complex paths**: if `getTotalLength()` looks wrong, overestimate slightly (`len * 1.05`) — too large is invisible at animation start; too small clips the end.
+- **Stagger multi-path draws at ~70–80%** of the previous segment's duration.
+- **A drawn line must land on something.** When the path is a connector (rail, beam, underline, callout) rather than a shape, both endpoints must sit on real elements and the draw must do a job — reveal, route, validate, or emphasize. A stroke that only decorates empty space reads as filler; attach it or cut it.
+
+## See also
+
+`svg-icon-enrichment` (internal parts animate after the outline draws) · `counting-dynamic-scale` (stroke draws an icon while a number counts up) · `hacker-flip-3d` (logo draws, wordmark decodes beneath).