@mevdragon/vidfarm-devcli 0.14.0 → 0.15.0

package/.agents/skills/hyperframes-animation/rules/css-marker-patterns.md

@@ -0,0 +1,373 @@
+# CSS Patterns for Marker Highlighting
+
+Pure CSS + GSAP implementations of all five MarkerHighlight.js drawing modes. Use these for deterministic rendering in HyperFrames compositions — no external library dependency, full GSAP timeline control.
+
+## Contents
+
+- [1. Highlight Mode](#1-highlight-mode) — Yellow marker sweep behind text
+- [2. Circle Mode](#2-circle-mode) — Hand-drawn ellipse around text
+- [3. Burst Mode](#3-burst-mode) — Radiating lines from text
+- [4. Scribble Mode](#4-scribble-mode) — Chaotic scribble over text
+- [5. Sketchout Mode](#5-sketchout-mode) — Rough rectangle outline
+
+## 1. Highlight Mode
+
+Yellow marker sweep behind text. The most common mode.
+
+```html
+<span class="mh-highlight-wrap">
+  <span class="mh-highlight-bar" id="hl-1"></span>
+  <span class="mh-highlight-text">highlighted text</span>
+</span>
+```
+
+```css
+.mh-highlight-wrap {
+  position: relative;
+  display: inline;
+}
+.mh-highlight-bar {
+  position: absolute;
+  top: 0;
+  left: -6px;
+  right: -6px;
+  bottom: 0;
+  background: #fdd835;
+  opacity: 0.35;
+  transform: scaleX(0);
+  transform-origin: left center;
+  border-radius: 3px;
+  z-index: 0;
+}
+.mh-highlight-text {
+  position: relative;
+  z-index: 1;
+}
+```
+
+```js
+// Sweep in from left
+tl.to("#hl-1", { scaleX: 1, duration: 0.5, ease: "power2.out" }, 0.6);
+
+// Optional: skew for hand-drawn feel
+// gsap.set("#hl-1", { skewX: -2 });
+```
+
+### Multi-line Highlight
+
+Stagger bars across multiple lines:
+
+```js
+tl.to(
+  ".mh-highlight-bar",
+  {
+    scaleX: 1,
+    duration: 0.5,
+    ease: "power2.out",
+    stagger: 0.3,
+  },
+  0.6,
+);
+```
+
+## 2. Circle Mode
+
+Hand-drawn circle around text. Use `border-radius: 50%` with a slight rotation for organic feel.
+
+```html
+<span class="mh-circle-wrap">
+  <span class="mh-circle-text" id="circle-word">IMPORTANT</span>
+  <span class="mh-circle-ring" id="circle-1"></span>
+</span>
+```
+
+```css
+.mh-circle-wrap {
+  position: relative;
+  display: inline;
+}
+.mh-circle-text {
+  position: relative;
+  z-index: 1;
+}
+.mh-circle-ring {
+  position: absolute;
+  top: 50%;
+  left: 50%;
+  width: 130%;
+  height: 160%;
+  transform: translate(-50%, -50%) rotate(-3deg) scale(0);
+  border: 3px solid #e53935;
+  border-radius: 50%;
+  pointer-events: none;
+  z-index: 0;
+}
+```
+
+```js
+// Circle scales in with a wobble
+tl.to(
+  "#circle-1",
+  {
+    scale: 1,
+    rotation: -3,
+    duration: 0.6,
+    ease: "back.out(1.7)",
+    transformOrigin: "center center",
+  },
+  0.7,
+);
+```
+
+### Variations
+
+```css
+/* Tighter circle (for short words) */
+.mh-circle-ring.tight {
+  width: 150%;
+  height: 180%;
+}
+
+/* Squared circle (rounded rectangle) */
+.mh-circle-ring.rounded {
+  border-radius: 30%;
+  width: 120%;
+  height: 140%;
+}
+
+/* Ellipse (wider than tall) */
+.mh-circle-ring.ellipse {
+  width: 150%;
+  height: 130%;
+  border-radius: 50%;
+}
+```
+
+## 3. Burst Mode
+
+Radiating lines from text center. Each line is a positioned div rotated to its angle.
+
+```html
+<span class="mh-burst-wrap">
+  <span class="mh-burst-text">WOW</span>
+  <span class="mh-burst-container" id="burst-1">
+    <span class="mh-burst-line" style="--angle: 0deg; --len: 70px;"></span>
+    <span class="mh-burst-line" style="--angle: 30deg; --len: 55px;"></span>
+    <span class="mh-burst-line" style="--angle: 60deg; --len: 80px;"></span>
+    <span class="mh-burst-line" style="--angle: 90deg; --len: 45px;"></span>
+    <span class="mh-burst-line" style="--angle: 120deg; --len: 65px;"></span>
+    <span class="mh-burst-line" style="--angle: 150deg; --len: 75px;"></span>
+    <span class="mh-burst-line" style="--angle: 180deg; --len: 50px;"></span>
+    <span class="mh-burst-line" style="--angle: 210deg; --len: 60px;"></span>
+    <span class="mh-burst-line" style="--angle: 240deg; --len: 80px;"></span>
+    <span class="mh-burst-line" style="--angle: 270deg; --len: 40px;"></span>
+    <span class="mh-burst-line" style="--angle: 300deg; --len: 70px;"></span>
+    <span class="mh-burst-line" style="--angle: 330deg; --len: 55px;"></span>
+  </span>
+</span>
+```
+
+```css
+.mh-burst-wrap {
+  position: relative;
+  display: inline;
+}
+.mh-burst-text {
+  position: relative;
+  z-index: 2;
+}
+.mh-burst-container {
+  position: absolute;
+  top: 50%;
+  left: 50%;
+  width: 0;
+  height: 0;
+  z-index: 1;
+}
+.mh-burst-line {
+  position: absolute;
+  display: block;
+  width: 3px;
+  height: var(--len);
+  background: #1e88e5;
+  left: -1.5px;
+  top: calc(-1 * var(--len));
+  transform: rotate(var(--angle));
+  transform-origin: bottom center;
+  opacity: 0;
+}
+```
+
+```js
+// All lines burst outward simultaneously with slight stagger
+tl.fromTo(
+  "#burst-1 .mh-burst-line",
+  { scaleY: 0, opacity: 0 },
+  { scaleY: 1, opacity: 1, duration: 0.4, ease: "power2.out", stagger: 0.03 },
+  0.7,
+);
+```
+
+**Vary line lengths** (40-80px range) for an organic, hand-drawn feel. Equal lengths look mechanical.
+
+## 4. Scribble Mode
+
+Wavy SVG underlines and strikethroughs that draw themselves via `stroke-dashoffset`.
+
+```html
+<span class="mh-scribble-wrap">
+  <span class="mh-scribble-text">underlined text</span>
+  <svg class="mh-scribble-svg" viewBox="0 0 500 24" preserveAspectRatio="none">
+    <path
+      id="scribble-1"
+      d="M0,12 Q31,0 62,12 Q93,24 125,12 Q156,0 187,12 Q218,24 250,12 Q281,0 312,12 Q343,24 375,12 Q406,0 437,12 Q468,24 500,12"
+      fill="none"
+      stroke="#FDD835"
+      stroke-width="3"
+      stroke-linecap="round"
+    />
+  </svg>
+</div>
+```
+
+```css
+.mh-scribble-wrap {
+  position: relative;
+  display: inline;
+}
+.mh-scribble-text {
+  position: relative;
+  z-index: 1;
+}
+.mh-scribble-svg {
+  position: absolute;
+  left: 0;
+  bottom: -6px;
+  width: 100%;
+  height: 24px;
+  z-index: 0;
+}
+```
+
+```js
+// Measure path length and set initial dash state
+var path = document.querySelector("#scribble-1");
+var len = path.getTotalLength();
+gsap.set(path, { strokeDasharray: len, strokeDashoffset: len });
+
+// Draw the line
+tl.to(
+  "#scribble-1",
+  {
+    strokeDashoffset: 0,
+    duration: 0.8,
+    ease: "power1.inOut",
+  },
+  0.7,
+);
+```
+
+### Strikethrough Variant
+
+Position the SVG at `top: 50%; transform: translateY(-50%)` instead of `bottom: -6px`.
+
+### Wavy Path Generator
+
+Scale the path's viewBox width to match text width. The wave pattern `Q x1,y1 x2,y2` alternates between `y=0` and `y=24` for a natural wobble. Adjust the control points for tighter or looser waves:
+
+- **Tight waves**: smaller x-increments (25px per half-wave)
+- **Loose waves**: larger x-increments (50px per half-wave)
+- **Amplitude**: change the y range (0-24 for standard, 0-16 for subtle)
+
+## 5. Sketchout Mode
+
+Cross-hatch lines over de-emphasized text. Multiple angled lines create a "crossed out" effect.
+
+```html
+<span class="mh-sketchout-wrap">
+  <span class="mh-sketchout-text">old price</span>
+  <span class="mh-sketchout-lines" id="sketchout-1">
+    <span class="mh-sketchout-line mh-sketchout-fwd"></span>
+    <span class="mh-sketchout-line mh-sketchout-bwd"></span>
+  </span>
+</span>
+```
+
+```css
+.mh-sketchout-wrap {
+  position: relative;
+  display: inline;
+}
+.mh-sketchout-text {
+  position: relative;
+  z-index: 0;
+}
+.mh-sketchout-lines {
+  position: absolute;
+  top: 0;
+  left: -4px;
+  right: -4px;
+  bottom: 0;
+  overflow: hidden;
+  z-index: 1;
+}
+.mh-sketchout-line {
+  position: absolute;
+  display: block;
+  top: 50%;
+  left: 0;
+  width: 100%;
+  height: 2px;
+  background: #e53935;
+  transform-origin: left center;
+  transform: scaleX(0);
+}
+.mh-sketchout-fwd {
+  transform: scaleX(0) rotate(-12deg);
+}
+.mh-sketchout-bwd {
+  transform: scaleX(0) rotate(12deg);
+}
+```
+
+```js
+// Forward slash draws first
+tl.to(
+  "#sketchout-1 .mh-sketchout-fwd",
+  {
+    scaleX: 1,
+    duration: 0.3,
+    ease: "power2.out",
+  },
+  1.0,
+);
+
+// Backward slash follows
+tl.to(
+  "#sketchout-1 .mh-sketchout-bwd",
+  {
+    scaleX: 1,
+    duration: 0.3,
+    ease: "power2.out",
+  },
+  1.15,
+);
+```
+
+## Combining Modes in Captions
+
+Use mode cycling for visual variety across caption groups:
+
+```js
+var MODES = ["highlight", "circle", "burst", "scribble"];
+
+GROUPS.forEach(function (group, gi) {
+  var mode = MODES[gi % MODES.length];
+  // Apply the mode's CSS pattern to emphasis words in this group
+  group.emphasisWords.forEach(function (word) {
+    applyMode(word.el, mode, tl, word.start);
+  });
+});
+```
+
+Cycle every 2-3 groups for high energy, every 3-4 for medium, every 4-5 for low.

package/.agents/skills/hyperframes-animation/rules/cursor-click-ripple.md

@@ -0,0 +1,262 @@
+---
+name: cursor-click-ripple
+description: Animated mouse cursor moves to target, clicks with scale depression and expanding ripple rings.
+metadata:
+  tags: cursor, click, ripple, interaction, mouse, button
+---
+
+# Cursor Click Ripple
+
+An animated cursor moves to a target element, performs a click with visual depression, and emits expanding ripple rings from the click point.
+
+## How It Works
+
+Three sequential phases driven by a single GSAP timeline:
+
+1. **Move**: eased cursor translation from entry point to the target element's center
+2. **Click**: scale depression on both cursor and target (yoyo: shrink then return)
+3. **Ripple**: expanding circles radiate outward from the click point with fade-out. 1–3 staggered rings amplify the click feedback
+
+Use a GSAP timeline because the phase ordering (move → settle → click → ripples) is exactly what timelines express cleanly.
+
+## HTML
+
+```html
+<div
+  class="scene"
+  id="cursor-click-scene"
+  data-composition-id="cursor-click-scene"
+  data-start="0"
+  data-duration="2"
+  data-track-index="0"
+>
+  <button class="target-button">{ctaLabel}</button>
+
+  <div class="cursor">
+    <svg width="24" height="24" viewBox="0 0 24 24">
+      <path
+        d="M5 3L19 12L12 13L9 20L5 3Z"
+        fill="{cursorFill}"
+        stroke="{cursorStroke}"
+        stroke-width="1.5"
+      />
+    </svg>
+  </div>
+
+  <!-- Ripple rings — centered on click target, hidden until trigger -->
+  <div class="ripple ripple-1"></div>
+  <div class="ripple ripple-2"></div>
+  <div class="ripple ripple-3"></div>
+</div>
+```
+
+## CSS
+
+Position cursor at the entry point. Button sits at its final position. Ripples are at the click-target center with `scale: 0` and `opacity: 0` so they hold invisible until the timeline trigger:
+
+```css
+.scene {
+  position: relative;
+  width: 100%;
+  height: 100%;
+}
+
+.target-button {
+  position: absolute;
+  left: 50%;
+  top: 50%;
+  transform: translate(-50%, -50%);
+  /* ...button styling (background, color, font from project tokens) */
+}
+
+.cursor {
+  position: absolute;
+  left: 10%;
+  top: 80%; /* entry corner */
+  pointer-events: none;
+  z-index: 999;
+}
+
+.ripple {
+  position: absolute;
+  left: 50%;
+  top: 50%; /* click target center */
+  width: 100px;
+  height: 100px;
+  border-radius: 50%;
+  border: 2px solid {rippleColor};
+  transform: translate(-50%, -50%) scale(0);
+  opacity: 0;
+  pointer-events: none;
+}
+```
+
+## GSAP Timeline
+
+Build a paused timeline. Register it on `window.__timelines` with the same key as `data-composition-id` on the scene root. All tuning values are named constants — see How to Choose Values below.
+
+```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 });
+
+  // MOVE_DUR, MOVE_EASE, CLICK_AT, PRESS_DUR, CURSOR_PRESS_SCALE, TARGET_PRESS_SCALE,
+  // RIPPLE_AT, RIPPLE_DUR, RIPPLE_SCALE, RIPPLE_STAGGER, RIPPLE_EASE
+  // — all named; values per How to Choose Values.
+
+  // Phase 1 — Move cursor to target center (eased, not linear)
+  tl.to(
+    ".cursor",
+    {
+      x: TARGET_X,
+      y: TARGET_Y,
+      duration: MOVE_DUR,
+      ease: MOVE_EASE,
+    },
+    0,
+  );
+
+  // Phase 2 — Click: cursor + target depress together, then return
+  tl.to(
+    ".cursor",
+    {
+      scale: CURSOR_PRESS_SCALE,
+      duration: PRESS_DUR,
+      ease: "power2.in",
+      yoyo: true,
+      repeat: 1,
+    },
+    CLICK_AT,
+  );
+  tl.to(
+    ".target-button",
+    {
+      scale: TARGET_PRESS_SCALE,
+      duration: PRESS_DUR,
+      ease: "power2.in",
+      yoyo: true,
+      repeat: 1,
+    },
+    CLICK_AT,
+  );
+
+  // Phase 3 — Ripple burst, N rings staggered from the click point
+  tl.set([".ripple-1", ".ripple-2", ".ripple-3"], { opacity: 1 }, RIPPLE_AT);
+  tl.to(
+    [".ripple-1", ".ripple-2", ".ripple-3"],
+    {
+      scale: RIPPLE_SCALE,
+      opacity: 0,
+      duration: RIPPLE_DUR,
+      ease: RIPPLE_EASE,
+      stagger: RIPPLE_STAGGER,
+      immediateRender: false,
+    },
+    RIPPLE_AT,
+  );
+
+  window.__timelines["cursor-click-scene"] = tl;
+</script>
+```
+
+## How to Choose Values
+
+- **MOVE_DUR** — cursor travel time from entry to target, in seconds
+  - Range: 0.4–1.0 s
+  - Effects: short feels darting; long feels deliberate / "considered click"
+  - Constraints: must end before `CLICK_AT` — otherwise the click fires while the cursor is still moving and reads as a misclick
+  - Reference: ../../examples/cta-orbit-collapse.html uses 0.5 s
+
+- **MOVE_EASE** — easing family for the move tween
+  - Discrete choice. Options:
+    - `power2.inOut` — symmetric, calm; good for "the user thoughtfully moves the cursor"
+    - `back.out(<n>)` — overshoot landing; good when the click target is a button you want the cursor to "settle onto" with a tiny visible recoil. Pair with a low overshoot coefficient (~1.2–1.4) — higher reads as cartoonish
+    - `power3.out` — fast start, soft landing; good for a "decisive" move
+  - Reference: ../../examples/cta-orbit-collapse.html uses `back.out(1.3)`
+
+- **CLICK_AT** — time the click fires, in seconds
+  - Range: must be ≥ `MOVE_DUR` (cursor has settled); typically `MOVE_DUR + 0.0–0.3 s` of "decision pause"
+  - Effects: zero pause reads as autopilot; >0.3 s of pause reads as hesitation
+  - Reference: ../../examples/cta-orbit-collapse.html clicks 0.2 s after the cursor settles
+
+- **PRESS_DUR** — half-duration of the depression (the yoyo runs twice this)
+  - Range: 0.06–0.12 s
+  - Effects: short feels crisp; long feels mushy
+  - Constraints: total press = `2 * PRESS_DUR`; must finish before the next scene phase needs the cursor / target back at normal scale
+  - Reference: ../../examples/cta-orbit-collapse.html uses 0.08 s
+
+- **CURSOR_PRESS_SCALE / TARGET_PRESS_SCALE** — how far each compresses during the click
+  - Range: cursor 0.80–0.90; target 0.92–0.97
+  - Effects: smaller numbers = stronger "this click counts" feel; values close to 1 read as a gentle tap
+  - Constraints: cursor compresses MORE than the target — the cursor is the actor, the target is the recipient
+  - Reference: ../../examples/cta-orbit-collapse.html uses cursor 0.85 / target 0.95
+
+- **RIPPLE_AT** — when the rings start expanding, in seconds
+  - Range: `CLICK_AT + 0.0–0.08 s`
+  - Effects: simultaneous with the press feels causal; slight delay feels acoustic ("the click happens, then the wave radiates")
+  - Reference: ../../examples/cta-orbit-collapse.html starts the ripple at `CLICK_AT` exactly
+
+- **RIPPLE_DUR** — how long each ring takes to fully expand and fade
+  - Range: 0.5–1.0 s
+  - Effects: short rings feel sharp; long rings feel like a soft sonar
+  - Constraints: must complete before any phase that depends on the ring being gone (e.g. a screen wipe)
+  - Reference: ../../examples/cta-orbit-collapse.html uses 0.7 s
+
+- **RIPPLE_SCALE** — final scale of each ring before it fades
+  - Range: 3–6
+  - Effects: 3 keeps the ring near the click site; 6 lets it sweep the surrounding area
+  - Constraints: if the ring would exit the visible frame before opacity reaches 0, lower the scale or shorten the duration
+  - Reference: ../../examples/cta-orbit-collapse.html uses 5
+
+- **RIPPLE_STAGGER** — delay between consecutive rings
+  - Range: 0.06–0.12 s (or 0 for a single ring; see Variations)
+  - Effects: below ~0.06 s reads as one thick ring; above ~0.12 s reads as separate events
+  - Reference: ../../examples/cta-orbit-collapse.html uses a single ring (no stagger)
+
+- **RIPPLE_EASE** — easing family for the expansion
+  - Discrete choice. Options:
+    - `power2.out` — fast start, soft tail; the standard "ping" feel
+    - `power3.out` — even sharper attack, longer tail
+    - `expo.out` — almost-instant expansion with a long quiet fade; reads as a strong, distant pulse
+  - Reference: ../../examples/cta-orbit-collapse.html uses `power2.out`
+
+- **TARGET_X / TARGET_Y** — pixel offset of the click target from the cursor's CSS-laid origin
+  - These are layout-derived, not creative knobs — they must match the visual centroid of the actual click target. A 4 px miss reads as missing the button
+  - Reference: ../../examples/cta-orbit-collapse.html targets the white button at `CENTER_X + 130, CENTER_Y + 15`
+
+## Variations
+
+- **Single ring** — keep one `.ripple` element, drop the stagger; reads as more elegant when the rest of the scene is busy
+- **Keyframed attack-decay** — replace the simple expand-and-fade with a `keyframes` block that ramps opacity 0 → peak → 0 across the duration; gives a clearer "energy radiates and dissipates" envelope (used in ../../examples/cta-orbit-collapse.html)
+- **Multi-ring expanding pulse** — 3 rings with 0.08 s stagger feels richer when the click is the climactic moment of the scene
+
+## Key Principles
+
+- **Move before click**: trigger the click only after the move tween has settled — clicking mid-motion reads as unintentional
+- **Synchronized depression**: cursor + target depress at the same `position` time with the same duration (and both yoyo back)
+- **Ripple from click point**: ripples expand from the exact click location (the button's visual center), not from any element's bounding-box origin
+- **Subtle scale**: cursor compresses more than the target — see `CURSOR_PRESS_SCALE` / `TARGET_PRESS_SCALE`
+- **High z-index cursor**: cursor renders above all content for the entire sequence
+
+## Critical Constraints
+
+- **Timeline must be paused**: `gsap.timeline({ paused: true })`. Never call `tl.play()` — HyperFrames seeks the timeline frame-by-frame deterministically
+- **Registry key = `data-composition-id`**: `window.__timelines["<id>"]` must match the `data-composition-id` on the scene root exactly
+- **`immediateRender: false` on the ripple expand**: holds the initial state (`scale: 0`, `opacity: 0`) until the click moment, otherwise the tween pre-renders and the rings appear at the wrong size at t=0
+- **Finite duration**: verify `tl.duration()` matches the scene's `data-duration`
+- **`pointer-events: none` on cursor + ripples**: they're purely visual; never block underlying interactivity (matters for hover-able exports)
+- **No CSS transitions / animations**: all motion lives in the GSAP timeline so seek stays deterministic
+
+## Combinations
+
+- [orbit-3d-entry.md](orbit-3d-entry.md) — when the click is the pivot that collapses orbiting elements toward the cursor's target
+- [center-outward-expansion.md](center-outward-expansion.md) — the click can be the trigger for an outward burst from the click point
+- [press-release-spring.md](press-release-spring.md) for stronger physical feel on the target button
+- [scale-swap-transition.md](scale-swap-transition.md) for the button's state change after click (button morphs into success state, next view, etc.)
+
+## Pairs with HF skills
+
+- `/hyperframes-animation` — timeline + tween API reference (eases, stagger, `immediateRender`, etc.)
+- `/hyperframes-core` — composition wiring (`data-*` attributes, scene structure, registration contract)
+- `/hyperframes-cli` — `hyperframes lint` to verify the registry key + duration match