@mevdragon/vidfarm-devcli 0.13.0 → 0.15.0

package/.agents/skills/hyperframes-animation/rules/3d-page-scroll.md

@@ -0,0 +1,227 @@
+---
+name: 3d-page-scroll
+description: Full webpage rendered as tilted 3D card that scrolls to reveal specific sections.
+metadata:
+  tags: 3d, page, scroll, webpage, tilt, product-demo, perspective
+---
+
+# 3D Page Scroll
+
+A webpage (or long content) presented as a tilted 3D card. Spring-eased scroll reveals specific sections while the static 3D perspective adds physical depth.
+
+## How It Works
+
+Two independent transforms combine:
+
+1. **3D tilt** — Static `rotateY` + `rotateX` with `perspective` on the card. The angle does **not** change during the scene.
+2. **Scroll** — The content inside the card translates vertically (`translateY` / `y` in GSAP) within a clipped container, driven by a GSAP tween. Spring-like deceleration via `ease: "power3.out"` or `"power4.out"`.
+
+Optional layer:
+
+3. **Spotlight overlay** — A radial-gradient mask dims everything except a focal region after the scroll lands. Use to draw attention to one section.
+
+For multi-step scrolling (scroll → pause → scroll), use multiple `tl.to(".page-content", { y: -<distance>, ... }, <position>)` calls at different timeline positions.
+
+## HTML
+
+```html
+<div
+  class="scene"
+  id="page-scroll-scene"
+  data-composition-id="page-scroll-scene"
+  data-start="0"
+  data-duration="5"
+  data-track-index="0"
+>
+  <div class="tilt-card">
+    <div class="page-content">
+      <!-- Full {Brand} webpage recreation, taller than card height so
+           scrolling matters. Each section is real DOM, not a screenshot. -->
+      <section class="page-hero">{heroContents}</section>
+      <section class="page-features">{featuresContents}</section>
+      <section class="page-target" id="target-section">{targetContents}</section>
+      <section class="page-cta">{ctaContents}</section>
+    </div>
+
+    <div class="spotlight"></div>
+  </div>
+</div>
+```
+
+## CSS (hero-frame layout)
+
+```css
+.scene {
+  position: relative;
+  width: 100%;
+  height: 100%;
+}
+
+.tilt-card {
+  position: absolute;
+  left: 50%;
+  top: 50%;
+  /* tilt + perspective set in CSS only if no other transform tween touches
+     this element. If GSAP also tweens scale on .tilt-card, set the tilt
+     via gsap.set() to avoid matrix overwrites. */
+  transform: translate(-50%, -50%) perspective({perspectivePx}) rotateY({tiltYDeg}) rotateX({tiltXDeg});
+  transform-style: preserve-3d;
+  width: {cardWidth};
+  height: {cardHeight};
+  border-radius: 24px;
+  background: {cardBackgroundColor};
+  overflow: hidden; /* clip the scrolling content */
+  /* shadow X-offset sign must match tiltY sign (negative tiltY ⇒ positive X) */
+  box-shadow: 40px 30px 80px rgba(0, 0, 0, 0.45);
+}
+
+.page-content {
+  position: absolute;
+  top: 0;
+  left: 0;
+  width: 100%;
+  /* height is intrinsic from sections — taller than .tilt-card.height */
+}
+
+.page-content section {
+  height: {sectionHeight}; /* sections sized so cumulative offset = target distance */
+  padding: 64px;
+  /* section-specific styling … */
+}
+
+.spotlight {
+  position: absolute;
+  inset: 0;
+  pointer-events: none;
+  opacity: 0;
+  background: radial-gradient(
+    ellipse 60% 35% at 50% 50%,
+    transparent 50%,
+    {spotlightDimColor} 100%
+  );
+}
+```
+
+## 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 });
+
+  // Phase 1 — Card enters (optional, can skip if card is in from t=0)
+  // Phase 2 — Scroll to the target section.
+  // SCROLL_DISTANCE is measured at design time from the page layout
+  // (top of .page-content origin to vertical center of #target-section,
+  // accounting for card height).
+  tl.to(
+    ".page-content",
+    {
+      y: -SCROLL_DISTANCE,
+      duration: SCROLL_DUR,
+      ease: "power3.out",
+    },
+    SCROLL_AT,
+  );
+
+  // Phase 3 — Spotlight fades in on the target after scroll settles
+  tl.to(
+    ".spotlight",
+    {
+      opacity: 1,
+      duration: SPOTLIGHT_FADE_DUR,
+      ease: "power1.inOut",
+    },
+    SPOTLIGHT_AT,
+  );
+
+  window.__timelines["page-scroll-scene"] = tl;
+</script>
+```
+
+### Multi-phase scroll variant
+
+```js
+// Scroll to section A → hold → scroll to section B.
+// SCROLL_DISTANCE_A and SCROLL_DISTANCE_B are both measured from the
+// .page-content origin (NOT delta from previous step).
+tl.to(
+  ".page-content",
+  { y: -SCROLL_DISTANCE_A, duration: SCROLL_DUR, ease: "power3.out" },
+  SCROLL_AT_A,
+);
+tl.to(
+  ".page-content",
+  { y: -SCROLL_DISTANCE_B, duration: SCROLL_DUR, ease: "power3.out" },
+  SCROLL_AT_B,
+);
+```
+
+GSAP composes successive `y:` tweens additively when targeting the same property — each tween starts from the value left by the previous tween.
+
+## How to Choose Values
+
+- **tiltYDeg** — static Y rotation in CSS (or via `gsap.set()`).
+  - Range: -12 to -4 (left-leaning) or 4 to 12 (right-leaning); 0 = no perspective rotation.
+  - Effects: bigger magnitude = more dramatic 3D; near 0 collapses to a flat panel.
+  - Constraints: shadow X-offset sign must match (negative tiltY ⇒ positive box-shadow X).
+- **tiltXDeg** — static X rotation.
+  - Range: 0-6
+  - Effects: positive tilts the top edge away from the viewer.
+- **perspectivePx** — perspective distance.
+  - Range: 800-2000 px
+  - Effects: smaller = more dramatic foreshortening; larger = nearly orthographic.
+- **cardWidth / cardHeight** — card frame size.
+  - Constraints: card height < total content height, otherwise scroll has nothing to reveal.
+- **sectionHeight** — height of each scrolled section.
+  - Constraints: sum of all section heights ≥ cardHeight + SCROLL_DISTANCE so the target section ends up within frame after scroll.
+- **SCROLL_AT** — timeline second at which the scroll tween begins.
+  - Constraints: must be ≥ end of any prior fade-in tweens on `.page-content`.
+- **SCROLL_DUR** — duration of one scroll tween.
+  - Range: 0.8-1.8 s
+  - Effects: shorter feels like a hard cut; longer feels programmatic.
+- **SCROLL_DISTANCE** — pixels to translate `.page-content` upward.
+  - Constraints: measured once at design time from the target section's offset; NOT a free tunable.
+- **SPOTLIGHT_AT** — timeline second at which the spotlight begins fading in.
+  - Constraints: should be ≥ SCROLL_AT + SCROLL_DUR (or slightly earlier for overlapping handoff) so the spotlight reveals the freshly-arrived section.
+- **SPOTLIGHT_FADE_DUR** — spotlight opacity fade-in duration.
+  - Range: 0.4-0.8 s
+- Multi-phase variant — **SCROLL_AT_A / SCROLL_AT_B**: must satisfy `SCROLL_AT_A + SCROLL_DUR ≤ SCROLL_AT_B` so the two scrolls don't fight for the y property.
+
+Ease family — discrete choice:
+
+- `power3.out` — heavy deceleration; reads as a programmatic scroll that "lands". Default.
+- `power4.out` — even heavier; reads as a momentum-driven scroll.
+- `power2.inOut` — symmetric; reads as a cinematic camera pan rather than UI scroll.
+
+Pick one and use it across all scrolls in the scene — mixing easings within one scene reads as jerky.
+
+## Key Principles
+
+- **Tilt is static**, not animated. The card holds its angle the whole scene.
+- **Shadow direction matches tilt**: a left-leaning card casts shadow to the right (positive X shadow offset). Mismatch breaks the 3D illusion.
+- **Page content is real HTML**, not a screenshot. Screenshots can't be individually highlighted or scrolled-to with precision.
+- **Use real layout for distances**: scroll target distance comes from the actual cumulative section heights, not estimated pixel values.
+- **Spotlight as overlay**, not inside the page-content — overlay sits above scrolling content and stays fixed relative to the card.
+
+## Critical Constraints
+
+- **`overflow: hidden` on `.tilt-card`** — scrolling content must clip at card boundaries, otherwise it leaks past the rounded corners
+- **`transform-style: preserve-3d`** on `.tilt-card` — required for any 3D children (or for combining `perspective` with rotations cleanly)
+- **Timeline must be paused**: `gsap.timeline({ paused: true })`. Never `tl.play()` — HF seeks frame-by-frame
+- **Registry key = `data-composition-id`**: `window.__timelines["page-scroll-scene"]` must match scene root's `data-composition-id`
+- **Finite scroll distance** — compute from actual content geometry; don't use arbitrary values that may overshoot the content end
+- **Same easing across multi-phase scroll** — mixing `power3.out` and `power1.inOut` looks jerky; pick one for the scene
+
+## Combinations
+
+- [asr-keyword-glow.md](asr-keyword-glow.md) — highlight elements on the page synced to voiceover word timestamps
+- [multi-phase-camera.md](multi-phase-camera.md) — overall camera zoom while the page scrolls (zoom-in to target section as it lands)
+- [cursor-click-ripple.md](cursor-click-ripple.md) — cursor lands on a UI element within the scrolled-into-view section
+
+## Pairs with HF skills
+
+- `/hyperframes-animation` — timeline + ease reference; `y:` tween basics
+- `/hyperframes-core` — composition wiring, `data-*` attributes
+- `/hyperframes-cli` — `hyperframes lint` to verify the registry key + duration

package/.agents/skills/hyperframes-animation/rules/3d-text-depth-layers.md

@@ -0,0 +1,297 @@
+---
+name: 3d-text-depth-layers
+description: Multiple offset text layers create a stacked 3D shadow / extrusion effect on large typography — more impactful than CSS text-shadow because each layer is a full DOM element.
+metadata:
+  tags: text, 3d, depth, layers, shadow, typography, stacked, extrusion
+---
+
+# 3D Text Depth Layers
+
+Renders the same text N times at increasing offsets, with back layers translucent and the front layer fully opaque. Creates a physical "stacked extrusion" depth illusion. Distinct from `text-shadow` (which can't have per-layer hue / opacity / animation) — each layer is a real DOM element.
+
+## How It Works
+
+- N copies of the same text in a single container
+- Each copy positioned absolutely with offset `(i * OFFSET_X, i * OFFSET_Y)`
+- Back layers (high `i`) use translucent or darkened color
+- Front layer (`i = 0`) is full opacity, full brand color
+- Optionally: each layer fades in staggered, creating a "building up" depth animation
+
+## HTML
+
+```html
+<div
+  class="scene"
+  id="depth-scene"
+  data-composition-id="depth-scene"
+  data-start="0"
+  data-duration="3"
+  data-track-index="0"
+>
+  <div class="depth-stack">
+    <!-- Layers injected by script — LAYER_COUNT copies of {label} -->
+  </div>
+</div>
+```
+
+## CSS
+
+```css
+.scene {
+  position: relative;
+  width: 100%;
+  height: 100%;
+  display: grid;
+  place-items: center;
+  background: {bgColor};
+}
+.depth-stack {
+  position: relative;
+  /* Container size set by the front layer; back layers stack behind */
+}
+.depth-text {
+  font-family: {font};
+  font-weight: 900;
+  font-size: HERO_FONT_SIZE;
+  letter-spacing: HERO_LETTER_SPACING;
+  line-height: 1;
+  color: {frontColor};
+  text-transform: uppercase;
+}
+/* Back layers — absolute, stacked behind */
+.depth-text.is-back {
+  position: absolute;
+  top: 0;
+  left: 0;
+  pointer-events: none;
+}
+/* Front layer — relative to define container size */
+.depth-text.is-front {
+  position: relative;
+  z-index: 10;
+}
+```
+
+## GSAP Timeline + Layer Setup
+
+```html
+<script src="https://cdn.jsdelivr.net/npm/gsap@3.14.2/dist/gsap.min.js"></script>
+<script>
+  window.__timelines = window.__timelines || {};
+
+  const TEXT = "{label}";
+  const stack = document.querySelector(".depth-stack");
+
+  // Build layers — back-to-front so the FRONT (i=0) is the LAST appended
+  // and `position: relative` defines container size.
+  for (let i = LAYER_COUNT - 1; i >= 0; i--) {
+    const el = document.createElement("div");
+    el.className = "depth-text " + (i === 0 ? "is-front" : "is-back");
+    el.textContent = TEXT;
+    if (i > 0) {
+      const alpha = Math.max(BACK_ALPHA_MAX - i * BACK_ALPHA_STEP, BACK_ALPHA_MIN);
+      el.style.color = `rgba({backHueRGB}, ${alpha})`;
+      el.style.transform = `translate(${i * OFFSET_X}px, ${i * OFFSET_Y}px)`;
+    } else {
+      el.style.color = "{frontColor}";
+    }
+    el.dataset.layer = String(i);
+    stack.appendChild(el);
+  }
+
+  const tl = gsap.timeline({ paused: true });
+
+  // Layered entry — back layers appear first, building forward
+  const allLayers = stack.querySelectorAll(".depth-text");
+  allLayers.forEach((el) => {
+    const i = Number(el.dataset.layer);
+    const finalAlpha = el.classList.contains("is-front")
+      ? 1
+      : Math.max(BACK_ALPHA_MAX - i * BACK_ALPHA_STEP, BACK_ALPHA_MIN);
+    tl.fromTo(
+      el,
+      { opacity: 0 },
+      {
+        opacity: finalAlpha,
+        duration: LAYER_FADE_DUR,
+        ease: "power2.out",
+      },
+      LAYER_CASCADE_START + (LAYER_COUNT - 1 - i) * LAYER_CASCADE_STEP,
+    );
+  });
+
+  // Optional: depth grows on entry (offset interpolates from 0 → full)
+  const depthState = { p: 0 };
+  tl.to(
+    depthState,
+    {
+      p: 1,
+      duration: DEPTH_GROW_DUR,
+      ease: "power2.out",
+      onUpdate: () => {
+        stack.querySelectorAll(".depth-text.is-back").forEach((el) => {
+          const i = Number(el.dataset.layer);
+          const x = i * OFFSET_X * depthState.p;
+          const y = i * OFFSET_Y * depthState.p;
+          el.style.transform = `translate(${x}px, ${y}px)`;
+        });
+      },
+    },
+    DEPTH_GROW_START,
+  );
+
+  window.__timelines["depth-scene"] = tl;
+</script>
+```
+
+## Variations
+
+### Static depth (no animation, single hero shot)
+
+Skip the cascade — render all layers in their final positions from t=0, optionally fade the entire stack in:
+
+```js
+tl.from(
+  stack,
+  { opacity: 0, scale: STATIC_ENTRY_SCALE, duration: STATIC_ENTRY_DUR, ease: "power3.out" },
+  0,
+);
+```
+
+### Dynamic depth pulse
+
+Animate `OFFSET_X` / `OFFSET_Y` based on a heartbeat — depth grows and shrinks rhythmically:
+
+```js
+const beat = { p: 0 };
+tl.to(
+  beat,
+  {
+    p: Math.PI * 2 * BEAT_CYCLES,
+    duration: BEAT_DUR,
+    ease: "none",
+    onUpdate: () => {
+      const mult = 1 + Math.sin(beat.p) * BEAT_AMP;
+      stack.querySelectorAll(".is-back").forEach((el) => {
+        const i = Number(el.dataset.layer);
+        el.style.transform = `translate(${i * OFFSET_X * mult}px, ${i * OFFSET_Y * mult}px)`;
+      });
+    },
+  },
+  BEAT_START,
+);
+```
+
+### Color-shift back layers
+
+Instead of fading to translucent, shift to a different hue — depth reads as "casting a colored shadow":
+
+```js
+el.style.color = `hsla(${HUE_BASE - i * HUE_STEP}, ${SAT_PCT}%, ${LIGHT_BASE - i * LIGHT_STEP}%, 1)`;
+```
+
+## How to Choose Values
+
+### Layer geometry
+
+- **LAYER_COUNT** — number of stacked copies (back layers + 1 front).
+  - Range: 4-6. Below 4 the depth doesn't read as 3D; above 6 the stack visually clutters on tight kerning
+  - Effects: low end reads as subtle shadow; high end reads as chunky extrusion
+- **OFFSET_X / OFFSET_Y** — per-layer translation offset, in px.
+  - Range: 1-3 px each. Above 4 px reads as a glitch / chromatic aberration rather than depth
+  - Effects: offset direction implies light direction. `(+x, +y)` = light from upper-left; `(-x, +y)` = light from upper-right. Pick one and keep it consistent across the composition
+  - Constraints: same sign convention throughout the composition
+
+### Back-layer color falloff
+
+- **BACK_ALPHA_MAX** — alpha of the back layer nearest the front.
+  - Range: 0.6-0.85. Lower than 0.5 makes even the nearest back layer disappear; higher than 0.9 fights the front layer for dominance
+- **BACK_ALPHA_STEP** — alpha decrement per layer further back.
+  - Range: 0.08-0.15. Smaller steps read as a soft gradient; larger steps read as discrete plates
+  - Constraints: choose so `BACK_ALPHA_MAX − (LAYER_COUNT − 2) × BACK_ALPHA_STEP ≥ BACK_ALPHA_MIN`
+- **BACK_ALPHA_MIN** — floor below which back layers stop fading.
+  - Range: 0.1-0.2. Below 0.1 the deepest layer disappears entirely on dark backgrounds
+
+### Typography
+
+- **HERO_FONT_SIZE** — front-layer font size, in px.
+  - Range: 60 px minimum to read as layered; 200-340 px for full-bleed hero shots. Thin text loses the layered illusion
+- **HERO_LETTER_SPACING** — letter spacing.
+  - Range: −0.03em (tight) to 0 (normal). Negative spacing tightens the stack so the offsets read as depth instead of as repetition
+- **{font}** — typeface; pick a black/900 weight family with strong horizontal strokes
+- **{frontColor}** — front-layer color; the brand or accent color
+- **{backHueRGB}** — RGB triplet for back layers (e.g. matched to a brand glow). Used inside `rgba({backHueRGB}, ${alpha})`
+
+### Cascade entry (default form)
+
+- **LAYER_CASCADE_START** — timeline offset where the cascade begins.
+  - Constraints: ≥ 0; if another beat precedes, ≥ that beat's end
+- **LAYER_CASCADE_STEP** — delay between each layer's fade-in.
+  - Range: 0.04-0.10 s. Smaller feels almost-simultaneous; larger feels stepped and mechanical
+- **LAYER_FADE_DUR** — duration of each individual layer's fade-in.
+  - Range: 0.3-0.6 s
+
+### Depth-grow tween
+
+- **DEPTH_GROW_START** — when the offset growth begins.
+  - Constraints: typically `≈ LAYER_CASCADE_START`; align so the first layer's fade and the depth growth start together
+- **DEPTH_GROW_DUR** — duration over which offsets interpolate from 0 to full.
+  - Range: 0.4-0.8 s. Roughly match `LAYER_FADE_DUR × LAYER_COUNT / 2` so depth lands as the last layer fades in
+
+### Static-depth variation
+
+- **STATIC_ENTRY_SCALE** — initial scale before the whole stack fades in.
+  - Range: 0.94-0.98 — subtle inflation; larger reads as a separate "pop" effect
+- **STATIC_ENTRY_DUR** — fade-in duration for the whole stack.
+  - Range: 0.5-0.8 s
+
+### Dynamic-pulse variation
+
+- **BEAT_CYCLES** — number of full beat cycles across `BEAT_DUR`.
+  - Range: `BEAT_DUR / 1.5s ≤ BEAT_CYCLES ≤ BEAT_DUR / 0.7s` (one beat per 0.7-1.5 s reads as a heartbeat)
+- **BEAT_DUR** — pulse tween duration.
+  - Constraints: tied to the visible window of the depth stack
+- **BEAT_AMP** — fractional amplitude of the offset pulse.
+  - Range: 0.2-0.6. Smaller is a gentle breathing depth; larger reads as a kick-drum thump
+- **BEAT_START** — when the pulse begins.
+  - Constraints: `≥ DEPTH_GROW_START + DEPTH_GROW_DUR` so the pulse modulates a fully-grown stack
+
+### Color-shift variation
+
+- **HUE_BASE / HUE_STEP** — base hue (front layer) and per-layer hue rotation.
+  - Range: `HUE_STEP` 4-12°. Larger steps cycle further around the color wheel and read as glitch
+- **SAT_PCT** — fixed saturation for all layers.
+  - Range: 60-85%
+- **LIGHT_BASE / LIGHT_STEP** — base lightness and per-layer darkening.
+  - Range: `LIGHT_STEP` 3-8 percentage points so back layers darken into the background
+
+## Key Principles
+
+- **Layer count 4-6** — fewer than 4 doesn't read as 3D, more than 6 visually clutters on tight kerning
+- **Offset 1-3 px per axis** — subtle is dramatic. `OFFSET = 6+` looks like a glitch rather than depth
+- **Offset direction implies light direction** — `(+x, +y)` = light from upper-left; `(-x, +y)` = light from upper-right. Pick one and be consistent across the composition
+- **Back layers translucent OR darker** — DON'T make them MORE saturated than the front (looks like a halo). Each back layer should be slightly more transparent (`alpha -= BACK_ALPHA_STEP per layer`) or slightly darker
+- **Last (front) layer `position: relative`** to define container size; all others `position: absolute` stack behind
+- **Bold/black weight + large size** — 900 weight, 60 px+ minimum. Thin text loses the layered illusion
+- **Don't apply per-letter animation on top of layers** — character animations (hacker-flip, typewriter) on top of 6-layer depth = chaos. If you need both effects, drop depth to 2-3 layers OR apply layers only to the static post-reveal state
+
+## Critical Constraints
+
+- **Timeline must be paused**: `gsap.timeline({ paused: true })`
+- **Registry key = `data-composition-id`**
+- **No CSS `text-shadow`** alongside layered depth — they compound and over-extrude
+- **Use `transform: translate()` for offsets, not `top`/`left`** — translate composes cleanly with parent's centering and avoids reflow
+- **`pointer-events: none` on back layers** — they're decorative; don't catch hover or selection
+- **Set layer color via `rgba()` not opacity** — opacity on the whole element fades the rendered glyph including any shadow; rgba in `color` fades just the glyph
+
+## Combinations
+
+- [counting-dynamic-scale.md](counting-dynamic-scale.md) — render the counter number with depth layers
+- [sine-wave-loop.md](sine-wave-loop.md) — idle breathing on the front layer after reveal
+- [center-outward-expansion.md](center-outward-expansion.md) — depth-stacked wordmark reveals after burst lands
+
+## Pairs with HF skills
+
+- `/hyperframes-animation` — staggered fade-ins + onUpdate for dynamic depth
+- `/hyperframes-core` — composition wiring
+- `/hyperframes-cli` — `hyperframes lint`