@mevdragon/vidfarm-devcli 0.13.0 → 0.15.0

package/.agents/skills/hyperframes-animation/rules/multi-phase-camera.md

@@ -0,0 +1,273 @@
+---
+name: multi-phase-camera
+description: Sequential camera zoom with 2-3 distinct phases (pull-back / focus / push) plus continuous micro-drift for organic cinematic feel.
+metadata:
+  tags: camera, zoom, phase, drift, scale, cinematic
+---
+
+# Multi-Phase Camera
+
+A camera wrapper around the entire scene that progresses through discrete zoom phases at scripted triggers. Continuous sine-driven micro-drift overlays so the camera never feels static between phases. Distinct from a single linear zoom — multi-phase creates "cinematic pacing" (anticipation → reveal → settle).
+
+## How It Works
+
+The camera is a single wrapping `<div>` whose `transform: scale() translate(x, y)` is driven by:
+
+1. **Phase scale** — a stepwise scale value that advances through phases at trigger times (e.g. `PHASE_1_SCALE` at t=0 → `PHASE_2_SCALE` at PHASE_2_AT → `PHASE_3_SCALE` at PHASE_3_AT)
+2. **Drift offset** — a continuous sine-based `translateX` / `translateY` (small amplitude, slow frequency) ADDED to the phase transform
+
+Both run inside the GSAP timeline so HF seeks frame-by-frame deterministically.
+
+## HTML
+
+```html
+<div
+  class="scene"
+  data-composition-id="cam-scene"
+  data-start="0"
+  data-duration="6"
+  data-track-index="0"
+>
+  <div class="camera" id="camera">
+    <div class="content">
+      <div class="hero">{Brand}</div>
+      <div class="tagline">{tagline}</div>
+      <div class="cta">{ctaText}</div>
+    </div>
+  </div>
+</div>
+```
+
+## CSS
+
+```css
+.scene {
+  position: relative;
+  width: 100%;
+  height: 100%;
+  overflow: hidden;
+  background: {sceneBgColor};
+}
+.camera {
+  position: absolute;
+  inset: 0;
+  display: grid;
+  place-items: center;
+  transform-origin: 50% 50%;
+  will-change: transform;
+}
+.content {
+  display: flex;
+  flex-direction: column;
+  align-items: center;
+  gap: 32px;
+  text-align: center;
+}
+.hero {
+  font-family: {font};
+  font-weight: 900;
+  font-size: {heroSize};
+  letter-spacing: 8px;
+  color: {textColor};
+  text-transform: uppercase;
+}
+.tagline {
+  font-family: {font};
+  font-weight: 600;
+  font-size: {taglineSize};
+  color: {accentColor};
+}
+.cta {
+  font-family: {monoFont};
+  font-weight: 700;
+  font-size: {ctaSize};
+  letter-spacing: 6px;
+  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 });
+
+  const camera = document.getElementById("camera");
+
+  // Three-phase scale plan: pullback → focus → push
+  const phase = { scale: PHASE_1_SCALE };
+
+  // Phase 1 — start pulled back
+  // (no tween needed for the initial value; set via the phase object)
+
+  // Phase 2 — settle to neutral focus
+  tl.to(
+    phase,
+    {
+      scale: PHASE_2_SCALE,
+      duration: PHASE_2_DUR,
+      ease: PHASE_2_EASE,
+    },
+    PHASE_2_AT,
+  );
+
+  // Phase 3 — slow push-in for the climax
+  tl.to(
+    phase,
+    {
+      scale: PHASE_3_SCALE,
+      duration: PHASE_3_DUR,
+      ease: PHASE_3_EASE,
+    },
+    PHASE_3_AT,
+  );
+
+  // Drift driver — continuous sine motion overlaid on the phase scale
+  const drift = { p: 0 };
+
+  tl.to(
+    drift,
+    {
+      p: Math.PI * 2 * DRIFT_CYCLES,
+      duration: TOTAL_DURATION,
+      ease: "none",
+      onUpdate: () => {
+        const dx = Math.sin(drift.p) * DRIFT_AMP_X;
+        const dy = Math.sin(drift.p * DRIFT_FREQ_RATIO) * DRIFT_AMP_Y;
+        camera.style.transform = `scale(${phase.scale}) translate(${dx}px, ${dy}px)`;
+      },
+    },
+    0,
+  );
+
+  // Content reveals (entry beats inside the camera frame)
+  tl.from(".hero", { opacity: 0, y: 32, scale: 0.96, duration: 0.9, ease: "power3.out" }, HERO_AT);
+  tl.from(".tagline", { opacity: 0, y: 16, duration: 0.7, ease: "power3.out" }, TAGLINE_AT);
+  tl.from(".cta", { opacity: 0, y: 8, duration: 0.7, ease: "power3.out" }, CTA_AT);
+
+  window.__timelines["cam-scene"] = tl;
+</script>
+```
+
+## How to Choose Values
+
+- **PHASE_1_SCALE / PHASE_2_SCALE / PHASE_3_SCALE** — three-step zoom values
+  - Range: PHASE_1 0.88–0.96; PHASE_2 0.98–1.02; PHASE_3 1.04–1.15
+  - Effects: tighter spread = subtler camera; wider = more cinematic
+  - Constraints: at PHASE_1_SCALE < 1, `.scene` MUST have `overflow: hidden` or the inner content's edges leak outside the frame
+
+- **PHASE_2_AT / PHASE_2_DUR** — when the focus phase starts and how long it takes
+  - Range: PHASE_2_AT 0.3–1.0 s; PHASE_2_DUR 1.0–1.8 s
+  - Effects: longer DUR = slower settle, more cinematic
+
+- **PHASE_3_AT / PHASE_3_DUR** — when the push phase starts and how long it takes
+  - Range: PHASE_3_AT 2.0–4.0 s; PHASE_3_DUR 1.0–2.0 s
+  - Constraints: PHASE_3_AT must be ≥ PHASE_2_AT + PHASE_2_DUR (otherwise focus is preempted)
+
+- **PHASE_2_EASE / PHASE_3_EASE** — ease per transition
+  - Discrete choice: `power2.out`, `power3.out`, `power2.inOut`
+  - Selection: cinematic feel; spring/back easing on a camera feels uncomfortable. Each later phase should imply more settling than the previous (longer dur OR more out-easing).
+
+- **TOTAL_DURATION** — composition's total runtime (matches `data-duration`)
+  - Reference: the drift tween must span the whole composition
+
+- **DRIFT_CYCLES** — number of sine cycles across TOTAL_DURATION
+  - Range: 1–3
+  - Effects: 1 = one slow breath; 3 = noticeably busier
+  - Constraints: high values read as mechanical wobble rather than organic drift
+
+- **DRIFT_AMP_X / DRIFT_AMP_Y** — peak drift offset in pixels
+  - Range: DRIFT_AMP_X 2–8 px; DRIFT_AMP_Y 1–4 px
+  - Effects: per-frame imperceptible, visible over time. If drift is a discrete shake, it's too much.
+
+- **DRIFT_FREQ_RATIO** — multiplier on the Y-axis sine frequency
+  - Range: 1.2–1.5
+  - Effects: 1.0 = perfect diagonal (reads mechanical); ~1.3 = organic Lissajous
+
+- **HERO_AT / TAGLINE_AT / CTA_AT** — content reveal beats
+  - Constraints: HERO_AT should land AFTER PHASE_1 settles via PHASE_2 (otherwise the hero feels like it's flying away while camera is still pulling back)
+
+## Phase Patterns
+
+| Pattern             | Scale Sequence (Phase 1 → 2 → 3)  | Feel                            | When to use                   |
+| ------------------- | --------------------------------- | ------------------------------- | ----------------------------- |
+| **Focus-in**        | back → neutral → slight push      | Approach → settle → slight push | Default product reveal        |
+| **Dramatic reveal** | push → neutral → pull             | Wide → focus → settle back      | Hero shot with breathing room |
+| **Steady push**     | neutral → slight push → more push | Gradual forward momentum        | Continuous narrative push     |
+| **Bookend pull**    | neutral → strong push → neutral   | Settle → push → release         | CTA emphasis then release     |
+
+## Variations
+
+### Phase trigger by content beat (not time)
+
+If the composition has content phases (e.g. an entry completes, then orbit starts), align the camera tween start time with the content tween's end time rather than using a fixed clock value.
+
+### Camera shake (panic / impact)
+
+For a brief shake instead of drift, replace the drift tween with a higher-amplitude, higher-frequency one over a short window:
+
+```js
+tl.to(
+  drift,
+  {
+    p: Math.PI * 2 * SHAKE_CYCLES,
+    duration: SHAKE_DUR,
+    ease: "none",
+    onUpdate: () => {
+      const dx = Math.sin(drift.p) * SHAKE_AMP_X;
+      const dy = Math.sin(drift.p * SHAKE_FREQ_RATIO) * SHAKE_AMP_Y;
+      camera.style.transform = `scale(${phase.scale}) translate(${dx}px, ${dy}px)`;
+    },
+  },
+  SHAKE_AT,
+);
+```
+
+### Targeted zoom into off-center element
+
+If the climax should zoom into a non-centered element, combine scale with counter-translation. Compute the offset so the target ends at viewport center after scale:
+
+```js
+const target = document.querySelector(".cta");
+const tRect = target.getBoundingClientRect();
+const viewportCenter = { x: STAGE_W / 2, y: STAGE_H / 2 };
+const offsetX = (viewportCenter.x - (tRect.left + tRect.width / 2)) / phase.scale;
+const offsetY = (viewportCenter.y - (tRect.top + tRect.height / 2)) / phase.scale;
+// then in onUpdate: translate(offsetX + dx, offsetY + dy)
+```
+
+## Key Principles
+
+- **Drift is imperceptible per-frame, visible over time** — if drift reads as discrete shake, the amplitude is too high
+- **Drift X and Y at slightly different frequencies** — `DRIFT_FREQ_RATIO ≈ 1.3` prevents perfect-diagonal motion, which reads as mechanical
+- **Phase springs softer than UI springs** — `power2.inOut` or `power3.out` for cinematic feel; spring/back easing on a camera feels uncomfortable
+- **Each later phase settles "deeper"** — phase 2 ease should imply more settling than phase 1 (longer duration OR more out-easing). Wakes up → settles → settles deeper
+- **Camera wraps EVERYTHING in the scene** — applying camera per-element creates parallax bugs and breaks "this is one viewpoint"
+- **❗ overflow: hidden on .scene** — phases that pull back (`scale < 1`) reveal edges of the inner content. Without `overflow: hidden`, those edges leak outside the stage frame and HF renders them as visible content
+- **❗ Hero reveal starts AFTER initial pullback ease lands** — if the camera is still pulling back when the headline fades in, the headline feels like it's flying away
+
+## Critical Constraints
+
+- **Timeline must be paused**: `gsap.timeline({ paused: true })`
+- **Registry key = `data-composition-id`**
+- **No CSS `transition` on `.camera`** — competes with the GSAP transform
+- **`transform-origin: 50% 50%`** on camera — off-center origin creates unpredictable phase-to-phase drift
+- **`will-change: transform`** on `.camera` — the camera transform updates every frame
+- **`overflow: hidden` on `.scene`** — required when any phase scale < 1
+- **Scene background on `.scene`, not `.camera`** — if background is on camera, scaling/translating it reveals the outer void
+
+## Combinations
+
+- [orbit-3d-entry.md](orbit-3d-entry.md) — orbit motion inside a slowly drifting camera
+- [counting-dynamic-scale.md](counting-dynamic-scale.md) — climax phase push synced to counter peak
+- [3d-text-depth-layers.md](3d-text-depth-layers.md) — depth-stacked hero with cinematic camera moves
+- [sine-wave-loop.md](sine-wave-loop.md) — element idle inside the camera (compound motion)
+
+## Pairs with HF skills
+
+- `/hyperframes-animation` — multi-phase tween + drift onUpdate
+- `/hyperframes-core` — composition wiring, scene wrapper
+- `/hyperframes-cli` — `hyperframes lint`

package/.agents/skills/hyperframes-animation/rules/orbit-3d-entry.md

@@ -0,0 +1,301 @@
+---
+name: orbit-3d-entry
+description: Elements flip in from 3D space then settle into continuous elliptical orbit around a focal point.
+metadata:
+  tags: orbit, 3d, flip, ellipse, circular, icon, entry, continuous
+---
+
+# Orbit with 3D Entry
+
+Elements flip in from 3D space (rotateX + rotateY + translateZ) then transition into a continuous elliptical orbit around a focal point. Distinct from one-shot reveals — the orbit keeps running.
+
+## How It Works
+
+Two phases per element:
+
+1. **Entry (per element)**: GSAP tween from hidden 3D orientation (`rotateX`, `rotateY`, negative `z`) to flat (`rotateX: 0, rotateY: 0, z: 0`). Spring-like ease (`back.out`) for the flip-in.
+2. **Orbit (after entry)**: Continuous trigonometric position around a center point. The element's `x` and `y` translate are driven by `cos(t)` and `sin(t)` at a slow angular speed.
+
+The orbit runs **inside the timeline** — not via `requestAnimationFrame` — so HF seek-by-frame stays deterministic.
+
+## HTML
+
+```html
+<div
+  class="scene"
+  id="orbit-scene"
+  data-composition-id="orbit-scene"
+  data-start="0"
+  data-duration="5"
+  data-track-index="0"
+>
+  <div class="orbit-stage">
+    <div class="orbit-item" data-angle="0">{glyph1}</div>
+    <div class="orbit-item" data-angle="60">{glyph2}</div>
+    <div class="orbit-item" data-angle="120">{glyph3}</div>
+    <div class="orbit-item" data-angle="180">{glyph4}</div>
+    <div class="orbit-item" data-angle="240">{glyph5}</div>
+    <div class="orbit-item" data-angle="300">{glyph6}</div>
+    <div class="orbit-center">{centerLabel}</div>
+  </div>
+</div>
+```
+
+## CSS
+
+```css
+.scene {
+  position: relative;
+  width: 100%;
+  height: 100%;
+  display: grid;
+  place-items: center;
+  background: {sceneBackground};
+  perspective: 1800px; /* REQUIRED — without perspective, rotateX/Y flatten */
+}
+.orbit-stage {
+  position: relative;
+  width: 1000px;
+  height: 700px;
+  display: grid;
+  place-items: center;
+  transform-style: preserve-3d;
+}
+.orbit-item {
+  position: absolute;
+  /* Items live at stage center; GSAP translates them along the orbit. */
+  top: 50%;
+  left: 50%;
+  width: 140px;
+  height: 140px;
+  display: grid;
+  place-items: center;
+  background: {accentColor};
+  border-radius: 50%;
+  font-family: {font};
+  font-weight: 900;
+  font-size: 64px;
+  color: {itemTextColor};
+  transform-style: preserve-3d;
+  will-change: transform;
+  box-shadow: 0 12px 36px {accentShadowColor};
+}
+.orbit-center {
+  position: relative;
+  z-index: 5;
+  font-family: {font};
+  font-weight: 900;
+  font-size: 96px;
+  letter-spacing: 8px;
+  color: {centerTextColor};
+  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 });
+
+  const items = document.querySelectorAll(".orbit-item");
+  // RADIUS_X, RADIUS_Y, ORBIT_DURATION, ENTRY_DUR, STAGGER, FLIP_BACK, CENTER_BACK
+  // — all named constants; values per "How to Choose Values" below.
+  const RADIUS_Y = RADIUS_X * Y_TO_X_RATIO; // perspective-flattened ellipse
+
+  items.forEach((el, i) => {
+    const initialAngleDeg = Number(el.dataset.angle);
+    const initialAngleRad = (initialAngleDeg / 360) * Math.PI * 2;
+    const startX = Math.cos(initialAngleRad) * RADIUS_X;
+    const startY = Math.sin(initialAngleRad) * RADIUS_Y;
+
+    // 1) Place at orbital position with opacity 0 — BEFORE any tween fires
+    gsap.set(el, {
+      xPercent: -50,
+      yPercent: -50,
+      x: startX,
+      y: startY,
+      rotateX: ROTATE_X_FROM,
+      rotateY: ROTATE_Y_FROM,
+      z: Z_FROM,
+      opacity: 0,
+      scale: SCALE_FROM,
+    });
+
+    // 2) Phase 1 — flip in IN PLACE at orbital position
+    tl.to(
+      el,
+      {
+        rotateX: 0,
+        rotateY: 0,
+        z: 0,
+        opacity: 1,
+        scale: 1,
+        duration: ENTRY_DUR,
+        ease: `back.out(${FLIP_BACK})`,
+      },
+      i * STAGGER,
+    );
+
+    // 3) Phase 2 — continuous orbit driven via a 0→1 progress tween
+    const orbitState = { p: 0 };
+    tl.to(
+      orbitState,
+      {
+        p: 1,
+        duration: ORBIT_DURATION,
+        ease: "none",
+        onUpdate: () => {
+          const angle = initialAngleRad + orbitState.p * Math.PI * 2;
+          const x = Math.cos(angle) * RADIUS_X;
+          const y = Math.sin(angle) * RADIUS_Y;
+          // z-index by orbit Y — see "Center label clearance" in Key Principles
+          // for the capped-range form when a center label is present.
+          el.style.zIndex = String(Math.round(y + RADIUS_Y));
+          el.style.transform = `translate(-50%, -50%) translate(${x}px, ${y}px)`;
+        },
+      },
+      i * STAGGER + ENTRY_DUR,
+    );
+  });
+
+  // Center label fades in once a few orbit items have landed
+  tl.from(
+    ".orbit-center",
+    { opacity: 0, scale: 0.6, duration: ENTRY_DUR, ease: `back.out(${CENTER_BACK})` },
+    CENTER_FADE_AT,
+  );
+
+  window.__timelines["orbit-scene"] = tl;
+</script>
+```
+
+## How to Choose Values
+
+- **RADIUS_X** — horizontal radius of the orbit ellipse, in px
+  - Range: 300–900 px
+  - Effects: small radius reads as a tight cluster; large radius spreads the ring across the frame and lets a large center element breathe
+  - Constraints: must clear the center element horizontally at every angle — see Key Principles for the `RADIUS_X * min(|cos(θ)|) ≥ L_w + I_w + breathing_room` rule
+  - Reference: ../../examples/cta-orbit-collapse.html uses 480
+
+- **Y_TO_X_RATIO** — `RADIUS_Y / RADIUS_X`, the orbit's perspective flattening
+  - Range: 0.4–0.7
+  - Effects: low values read as a near-horizontal disc seen from above; values approaching 1 read as a flat plane facing the camera
+  - Constraints: keep < 1 — the orbit should look like a tilted ring, not a frontal halo
+  - Reference: ../../examples/cta-orbit-collapse.html uses ≈ 0.58
+
+- **ORBIT_DURATION** — seconds for one full revolution
+  - Range: 4–25 s (longer for ambient backdrop, shorter for active feature motion)
+  - Effects: short durations look frenetic; long durations read as drifting / calm
+  - Constraints: must be ≥ the time the orbit is on screen, otherwise the tween ends and items stop
+  - Reference: ../../examples/cta-orbit-collapse.html uses ~25 s effective (orbit speed 0.25 rad/s)
+
+- **ENTRY_DUR** — per-element flip-in duration
+  - Range: 0.4–0.8 s
+  - Effects: short feels punchy; long feels stately
+  - Constraints: must be ≤ the gap between the first and last element's start so the cascade doesn't overlap to incoherence
+  - Reference: ../../examples/cta-orbit-collapse.html uses 0.55 s
+
+- **STAGGER** — delay between consecutive element entries
+  - Range: 0.06–0.12 s
+  - Effects: below ~0.06 s reads as "popcorn"; above ~0.12 s reads as plodding
+  - Constraints: total cascade `(n - 1) * STAGGER` should still complete before the next scene phase begins
+  - Reference: ../../examples/cta-orbit-collapse.html uses 0.10 s
+
+- **FLIP_BACK** — `back.out(<n>)` overshoot for the flip-in
+  - Range: 1.2–2.0
+  - Effects: low end is a soft arrive; high end snaps with visible overshoot
+  - Constraints: pair with a calmer `CENTER_BACK` if both fire close together — competing overshoots cancel each other
+  - Reference: ../../examples/cta-orbit-collapse.html uses 1.4
+
+- **CENTER_BACK** — `back.out(<n>)` overshoot for the center label fade-in
+  - Range: 1.2–1.8
+  - Effects: low end keeps the label calm under the busy orbit; high end gives it a small "pop" of arrival
+  - Reference: ../../examples/cta-orbit-collapse.html uses 1.4
+
+- **CENTER_FADE_AT** — when the center label fades in, in seconds
+  - Range: just after the first 2–4 elements have landed
+  - Effects: too early competes with the cascade; too late leaves a hole at the center of the orbit
+  - Reference: ../../examples/cta-orbit-collapse.html starts the center brand near the front of the scene
+
+- **ROTATE_X_FROM / ROTATE_Y_FROM / Z_FROM / SCALE_FROM** — initial 3D orientation
+  - Range: rotateX ±60° to ±120°; rotateY ±45° to ±120°; z −200 to −400; scale 0.2–0.6
+  - Effects: higher absolute rotation + deeper negative z = more dramatic "card flipping out of depth"; lower = subtle reorientation
+  - Constraints: pick a direction consistent with the scene's perspective; mixing positive and negative rotateY across items reads as noise
+  - Reference: ../../examples/cta-orbit-collapse.html uses rotateX 90, rotateY −45, z −100, scale 0
+
+## Variations
+
+### Collapse to center
+
+To reverse — orbit then collapse inward — interpolate `RADIUS_X` and `RADIUS_Y` to 0 in a final phase by multiplying both radii by a 1→0 driver:
+
+```js
+const collapse = { r: 1 };
+tl.to(
+  collapse,
+  {
+    r: 0,
+    duration: COLLAPSE_DUR,
+    ease: "power3.inOut",
+    onUpdate: () =>
+      items.forEach((el) => {
+        const a = (Number(el.dataset.angle) / 360) * Math.PI * 2;
+        const x = Math.cos(a) * RADIUS_X * collapse.r;
+        const y = Math.sin(a) * RADIUS_Y * collapse.r;
+        el.style.transform = `translate(-50%,-50%) translate(${x}px,${y}px) scale(${collapse.r})`;
+      }),
+  },
+  COLLAPSE_AT,
+);
+```
+
+### Tilted orbit plane
+
+For a more dramatic 3D orbit, rotate the entire `.orbit-stage` on the X axis:
+
+```css
+.orbit-stage {
+  transform: rotateX(25deg);
+}
+```
+
+Items rendered above/below the equator visually arc through the plane.
+
+## Key Principles
+
+- **`perspective` on scene root REQUIRED** — without it, rotateX/Y read as 2D scale and the flip-in looks flat
+- **`transform-style: preserve-3d`** on both the stage and each item — preserves the 3D context as items have their own transforms
+- **Stagger entries** — cascade reads as "swarm forming," simultaneous reads as "popcorn." See `STAGGER` in How to Choose Values
+- **Element count 4-12** — fewer feels empty, more crowds the center
+- **❗ Center label clearance — translateZ + capped item z-index** — `z-index` ALONE is unreliable inside a `transform-style: preserve-3d` stage (paint order follows Z position, not stacking-context z-index). For the orbit to NEVER occlude the headline:
+  1. Push the center label forward: `transform: translateZ(220px); z-index: 9999;`
+  2. Cap orbit-item dynamic z-index in `[1, 50]` so bottom-of-orbit items still read as "in front of" top-of-orbit items, but **never above the center label**. e.g.: `el.style.zIndex = String(1 + Math.round((y + RADIUS_Y) / (2 * RADIUS_Y) * 49));`
+  3. **Choose `RADIUS_X` so items also clear the center label HORIZONTALLY at all angles.** If the label's half-width is `L_w` and the item's half-width is `I_w`, then `RADIUS_X` must satisfy `RADIUS_X * min(|cos(θ_minimum)|) ≥ L_w + I_w + breathing_room`. For a 6-item orbit with 60° angular spacing, the worst case is `cos(30°) ≈ 0.866` between items. Scale `RADIUS_X` with the center label's width — a heavier wordmark needs a wider ring.
+- **❗ Center element is the headline** — the orbit is ornamental motion around it. If the orbit dominates the eye, increase center element size or fade orbit items down
+
+## Critical Constraints
+
+- **No `requestAnimationFrame`** — orbit must run inside the timeline so HF seeks frame-by-frame deterministically
+- **Timeline must be paused**: `gsap.timeline({ paused: true })`
+- **Registry key = `data-composition-id`**
+- **Each item gets its OWN orbit tween** — don't share one tween with `targets: '.orbit-item'` because each starts at a different `initialAngle`
+- **`will-change: transform`** — many simultaneous orbital transforms benefit from compositor hints
+- **Don't animate `left`/`top`** — use `translate()` (composes with `translate(-50%, -50%)` centering)
+- **❗ Entry must flip IN PLACE at orbital position, NOT at center** — a fromTo whose "from" and "to" both have `x: 0, y: 0` keeps the item at the stage center during phase 1, so it collides with the center label during flip-in (and then snaps to orbit on phase 2 start — a visible teleport).
+
+  The correct pattern (see GSAP Timeline above) is to `gsap.set()` each item at `(cos(initialAngle)*RADIUS_X, sin(initialAngle)*RADIUS_Y)` with `opacity: 0` BEFORE adding tweens, then have phase 1 animate only rotation/opacity/scale — NOT translate. The item fades in IN PLACE at its orbital starting point, and phase 2 picks up the orbit smoothly from there.
+
+## Combinations
+
+- [center-outward-expansion.md](center-outward-expansion.md) — alternative entry pattern (burst, not orbit); also the reversed driver for an orbit-collapse finish
+- [cursor-click-ripple.md](cursor-click-ripple.md) — pairs naturally when the center element is a CTA the user "clicks" to trigger the collapse
+- [sine-wave-loop.md](sine-wave-loop.md) — per-item idle wobble layered on top of the orbit
+
+## Pairs with HF skills
+
+- `/hyperframes-animation` — timeline + `onUpdate` API
+- `/hyperframes-core` — composition wiring
+- `/hyperframes-cli` — `hyperframes lint`