@mevdragon/vidfarm-devcli 0.14.0 → 0.16.0

package/.agents/skills/hyperframes-animation/rules/physics-press-reaction.md

@@ -0,0 +1,350 @@
+---
+name: physics-press-reaction
+description: Cursor + element synchronized press via subtractive spring forces — cursor lands on element, both compress together, then release. Distinct from press-release-spring (which has no cursor).
+metadata:
+  tags: spring, click, physics, cursor, subtractive, interaction, synchronized
+---
+
+# Physics Press Reaction (Cursor + Element Synced)
+
+Models a real click: a cursor approaches a button, lands, and both compress IN SYNC, then release together. Two distinct timing events (down-frame and up-frame) bound by spring forces. Distinct from [press-release-spring](press-release-spring.md) (which has no cursor — just a press happening); this rule is the COMBINED cursor + element behavior.
+
+## How It Works
+
+A single `PRESS_INTENSITY` value drives both cursor and button together:
+
+- **press down**: both compress to `1 - PRESS_INTENSITY`
+- **release**: both spring back to 1.0 with overshoot
+
+The cursor ALSO translates to the button's center during the approach phase BEFORE press starts. After release, the cursor may move on (next interaction) or hold.
+
+## HTML
+
+```html
+<div
+  class="scene"
+  id="press-react-scene"
+  data-composition-id="press-react-scene"
+  data-start="0"
+  data-duration="3"
+  data-track-index="0"
+>
+  <div class="stack">
+    <button class="btn" id="btn">
+      <span class="btn-icon">{ctaIcon}</span>
+      <span class="btn-label">{ctaCopy}</span>
+    </button>
+    <div class="brand">{Brand}</div>
+  </div>
+  <!-- Cursor lives at scene-root level so it can translate freely -->
+  <svg class="cursor" id="cursor" viewBox="0 0 24 24" xmlns="http://www.w3.org/2000/svg">
+    <path
+      d="M3 2 L21 12 L12 13 L7 22 Z"
+      fill="{cursorFill}"
+      stroke="{cursorStroke}"
+      stroke-width="1.5"
+    />
+  </svg>
+</div>
+```
+
+## CSS
+
+```css
+.scene {
+  position: relative;
+  width: 100%;
+  height: 100%;
+  display: grid;
+  place-items: center;
+  background: {sceneBg};
+  font-family: {font};
+  overflow: hidden;
+}
+.stack {
+  display: flex;
+  flex-direction: column;
+  align-items: center;
+  gap: STACK_GAP;
+}
+.btn {
+  display: flex;
+  align-items: center;
+  gap: BTN_INNER_GAP;
+  padding: BTN_PADDING_V BTN_PADDING_H;
+  background: {btnBg};
+  border: none;
+  border-radius: BTN_RADIUS;
+  color: {btnTextColor};
+  font-family: {font};
+  font-weight: 900;
+  font-size: BTN_FONT_SIZE;
+  letter-spacing: BTN_TRACKING;
+  text-transform: uppercase;
+  cursor: pointer;
+  box-shadow: {btnRestingShadow};
+  transform-origin: 50% 50%;
+  will-change: transform;
+}
+.btn-icon {
+  font-size: BTN_ICON_SIZE;
+  line-height: 1;
+}
+.brand {
+  font-size: BRAND_SIZE;
+  font-weight: 800;
+  letter-spacing: BRAND_TRACKING;
+  color: {brandColor};
+  text-transform: uppercase;
+}
+/* Cursor — absolute, positioned by GSAP */
+.cursor {
+  position: absolute;
+  width: CURSOR_SIZE;
+  height: CURSOR_SIZE;
+  pointer-events: none;
+  z-index: 100;
+  /* initial position is set by gsap.set() */
+  transform-origin: 0 0; /* arrow point is the click point */
+  filter: {cursorDropShadow};
+}
+```
+
+## 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 });
+
+  // Position cursor initially off-target (off-screen or far corner).
+  gsap.set("#cursor", { x: CURSOR_START_X, y: CURSOR_START_Y });
+
+  // The button's screen center, in composition coordinates.
+  const BUTTON_CENTER = { x: BUTTON_CENTER_X, y: BUTTON_CENTER_Y };
+
+  // Phase 1 — cursor approaches button
+  tl.to(
+    "#cursor",
+    {
+      x: BUTTON_CENTER.x,
+      y: BUTTON_CENTER.y,
+      duration: APPROACH_DUR,
+      ease: "power2.inOut",
+    },
+    APPROACH_START,
+  );
+
+  // Phase 2 — coordinated press down (button + cursor both scale to 1 - PRESS_INTENSITY)
+  tl.to(
+    ["#btn", "#cursor"],
+    {
+      scale: 1 - PRESS_INTENSITY,
+      duration: PRESS_DOWN_DUR,
+      ease: "power1.in",
+    },
+    PRESS_DOWN_AT,
+  );
+
+  // Phase 3 — release (both spring back to 1.0 with overshoot)
+  tl.to(
+    ["#btn", "#cursor"],
+    {
+      scale: 1,
+      duration: RELEASE_DUR,
+      ease: `back.out(${BOUNCE_FACTOR})`,
+    },
+    RELEASE_AT,
+  );
+
+  // Phase 4 — inner glow during press (boxShadow change synced to press scale)
+  tl.to(
+    "#btn",
+    {
+      boxShadow: `{btnPressedShadow}`,
+      duration: PRESS_DOWN_DUR,
+      ease: "power1.in",
+    },
+    PRESS_DOWN_AT,
+  );
+  tl.to(
+    "#btn",
+    {
+      boxShadow: `{btnRestingShadow}`,
+      duration: RELEASE_DUR,
+      ease: "power2.out",
+    },
+    RELEASE_AT,
+  );
+
+  // Brand fades in early (context)
+  tl.from(
+    ".brand",
+    { opacity: 0, y: BRAND_REVEAL_Y_PX, duration: BRAND_REVEAL_DUR, ease: "power3.out" },
+    BRAND_REVEAL_AT,
+  );
+
+  // Cursor optionally moves off after press (or holds for dwell)
+  tl.to(
+    "#cursor",
+    { x: CURSOR_EXIT_X, y: CURSOR_EXIT_Y, duration: CURSOR_EXIT_DUR, ease: "power2.out" },
+    CURSOR_EXIT_AT,
+  );
+
+  window.__timelines["press-react-scene"] = tl;
+</script>
+```
+
+## Variations
+
+### Multiple-element chain press
+
+Cursor presses button A → button A triggers swap → cursor moves to button B → presses again. Each press is one full down-release sub-routine.
+
+### Hold press (continuous pressure)
+
+Insert a `HOLD_DUR` window between press-down and release. Cursor scale stays at `1 - PRESS_INTENSITY`, button scale stays at `1 - PRESS_INTENSITY`, inner glow stays on. Suggests "thinking" or "loading."
+
+### Synchronized inner-glow pulse
+
+During the hold phase, the inner glow pulses (sin-driven). Suggests "processing":
+
+```js
+const holdGlow = { p: 0 };
+tl.to(
+  holdGlow,
+  {
+    p: Math.PI * GLOW_PULSE_CYCLES * 2,
+    duration: HOLD_DUR,
+    ease: "none",
+    onUpdate: () => {
+      const alpha = GLOW_BASE_ALPHA + Math.sin(holdGlow.p) * GLOW_PULSE_AMP;
+      document.getElementById("btn").style.boxShadow =
+        `inset 0 0 GLOW_BLUR rgba(255, 255, 255, ${alpha})`;
+    },
+  },
+  HOLD_START_AT,
+);
+```
+
+## How to Choose Values
+
+### Timing (seconds)
+
+- **APPROACH_START** — when the cursor begins moving toward the button.
+  - Range: 0-0.3 s (small lead-in is fine; long delays read as a dead frame)
+- **APPROACH_DUR** — cursor approach duration.
+  - Range: 0.7-1.3 s; faster reads as urgent, slower as deliberate
+- **PRESS_DOWN_AT** — when the press fires.
+  - Constraints: MUST equal `APPROACH_START + APPROACH_DUR` so the cursor arrives exactly when the press begins (avoids "tapping on air")
+- **PRESS_DOWN_DUR** — compression duration.
+  - Range: 0.1-0.25 s
+- **RELEASE_AT** — when the release fires.
+  - Constraints: must be > `PRESS_DOWN_AT + PRESS_DOWN_DUR`; an optional brief hold (0.05-0.4 s, or `HOLD_DUR` for the Hold-press variation) for "thinking" interactions
+- **RELEASE_DUR** — release spring duration.
+  - Range: 0.4-0.7 s (long enough for the overshoot to settle)
+- **BRAND_REVEAL_AT** — when the brand line fades in.
+  - Constraints: must be < `PRESS_DOWN_AT` (context precedes interaction)
+- **BRAND_REVEAL_DUR** — brand fade-in duration.
+  - Range: 0.4-0.8 s
+- **CURSOR_EXIT_AT / CURSOR_EXIT_DUR** — optional outbound cursor motion after release.
+  - Constraints: `CURSOR_EXIT_AT` must be ≥ `RELEASE_AT + RELEASE_DUR` so the cursor exits AFTER the press settles, not during
+
+### Physics
+
+- **PRESS_INTENSITY** — how deep the press compression goes.
+  - Range: 0.05 (subtle) - 0.10 (standard) - 0.15 (heavy)
+  - Applied as `scale: 1 - PRESS_INTENSITY` on both cursor and button (single GSAP target array)
+- **BOUNCE_FACTOR** — `back.out(${BOUNCE_FACTOR})` overshoot on the release.
+  - Range: 1.6 (soft) - 2.0 (firm) - 2.4 (cartoony)
+
+### Positioning
+
+- **CURSOR_START_X / CURSOR_START_Y** — initial cursor position in composition coordinates.
+  - Constraints: off-screen or in a corner far from the button so the approach reads as motion-in, not a teleport
+- **BUTTON_CENTER_X / BUTTON_CENTER_Y** — the button's measured screen-space center.
+  - Source: measured at composition coordinates; for `place-items: center` at 1920×1080 this is `(960, 540)`
+- **CURSOR_EXIT_X / CURSOR_EXIT_Y** — where the cursor moves after release (if used).
+  - Range: any off-stage or out-of-the-way position
+- **BRAND_REVEAL_Y_PX** — brand initial y offset.
+  - Range: 8-20 px
+
+### Layout / typography
+
+- **STACK_GAP** — gap between button and brand line.
+  - Range: 40-96 px
+- **BTN_PADDING_V / BTN_PADDING_H** — button padding.
+  - Range: V 24-40 px, H 60-100 px (horizontal padding 2-3× vertical reads as pill-shaped CTA)
+- **BTN_INNER_GAP** — gap between icon and label inside the button.
+  - Range: 16-32 px
+- **BTN_RADIUS** — button corner radius.
+  - Range: 20-40 px, or `BTN_PADDING_V + BTN_FONT_SIZE/2` for fully rounded ends
+- **BTN_FONT_SIZE / BTN_ICON_SIZE** — typographic sizes inside the button.
+  - Range: font 60-100 px at 1080p; icon ~1.0-1.1× font size
+- **BTN_TRACKING** — letter-spacing on uppercase button text.
+  - Range: 4-12 px
+- **BRAND_SIZE / BRAND_TRACKING** — brand line typography.
+  - Range: 40-60 px, tracking 8-16 px
+- **CURSOR_SIZE** — cursor SVG size.
+  - Range: 48-96 px at 1080p
+
+### Hold-press variation
+
+- **HOLD_DUR** — hold window between press down and release.
+  - Range: 0.3-0.8 s
+- **HOLD_START_AT** — when the glow pulse begins.
+  - Constraints: typically equal to `PRESS_DOWN_AT + PRESS_DOWN_DUR`
+- **GLOW_PULSE_CYCLES** — number of full sine cycles across `HOLD_DUR`.
+  - Range: 1-4 (more cycles read as faster "processing")
+- **GLOW_BASE_ALPHA** — center of the alpha pulse.
+  - Range: 0.15-0.3
+- **GLOW_PULSE_AMP** — peak deviation from `GLOW_BASE_ALPHA`.
+  - Range: 0.1-0.2; must satisfy `GLOW_BASE_ALPHA - GLOW_PULSE_AMP ≥ 0`
+- **GLOW_BLUR** — inset glow blur radius (px).
+  - Range: 24-48 px
+
+### Tokens
+
+- **{sceneBg}** — background gradient/color
+- **{font}** — typographic stack
+- **{btnBg}** — button background (typically gradient toward an accent hue)
+- **{btnTextColor}** — button text color
+- **{btnRestingShadow}** / **{btnPressedShadow}** — outer + inset box-shadow strings for the resting and pressed states
+- **{brandColor}** — accent brand color
+- **{cursorFill}** / **{cursorStroke}** — cursor SVG fill and stroke
+- **{cursorDropShadow}** — `filter: drop-shadow(...)` value for cursor depth
+- **{Brand}** — brand line copy
+- **{ctaCopy}** / **{ctaIcon}** — button label and inline icon glyph
+
+## Key Principles
+
+- **Same press scale on cursor AND button** — physical synchronicity. If only the button scales, the cursor appears to "tap on air"; if only the cursor scales, the button feels disconnected.
+- **Cursor arrives BEFORE press starts** — there must be a clear moment of "cursor over target" before scale change. Otherwise the press is unattributed.
+- **`back.out(${BOUNCE_FACTOR})` for release** — both elements need spring overshoot together. Linear release loses the tactile feel.
+- **Inner glow appears DURING press, fades on release** — visual confirmation of contact. Outer shadow shrinks (pushed-in), inner glow appears (energy concentrated).
+- **Cursor `pointer-events: none`** — the cursor is decorative; if it captures events, hover/click behaviors on button below break.
+- **Cursor `transform-origin: 0 0`** — the arrow's tip is the click point, not its center. Scale around the tip keeps the click point stable.
+- **Climax dwell ≥1 s** — after release, the comp must continue ≥1 s. The press is a beat; viewer needs time to see the result.
+
+## Critical Constraints
+
+- **Timeline must be paused**: `gsap.timeline({ paused: true })`
+- **Registry key = `data-composition-id`**
+- **No CSS `transition`** on either cursor or button — competes with GSAP
+- **Cursor SVG with `pointer-events: none`**
+- **`will-change: transform`** on button (and cursor if desired)
+- **`up-frame > down-frame`** — release MUST come after press; otherwise the comp shows release without press
+- **Don't use real `mouseenter` / `click` events** — HF is a render context, not a UI; everything must run via the timeline
+
+## Combinations
+
+- [press-release-spring.md](press-release-spring.md) — the BUTTON-only press variant; this rule layers cursor on top
+- [cursor-click-ripple.md](cursor-click-ripple.md) — adds a ripple effect at the click point
+- [scale-swap-transition.md](scale-swap-transition.md) — the press TRIGGERS the swap
+
+## Pairs with HF skills
+
+- `/hyperframes-animation` — coordinated multi-target tweens via array
+- `/hyperframes-core` — composition wiring
+- `/hyperframes-cli` — `hyperframes lint`

package/.agents/skills/hyperframes-animation/rules/press-release-spring.md

@@ -0,0 +1,296 @@
+---
+name: press-release-spring
+description: Tactile button press with linear compression, spring-based elastic recovery, and layered visual feedback (shadow shrink + release burst + background glow).
+metadata:
+  tags: spring, press, interaction, button, physics, glow, burst, ui
+---
+
+# Press-Release Spring Chain
+
+Separates input (linear compression) from output (spring recovery) to create tactile feel. The overshoot is a natural byproduct of the spring config, not manually coded. Pairs with secondary motion (shadow shrink, release burst, background glow) layered on the same trigger frame.
+
+## How It Works
+
+Two distinct phases split at the **release** moment:
+
+1. **Press**: linear ease → compression (`scale: 1 → PRESS_SCALE`, shadow shrinks). Linear, not spring — the dip must read as instant/tactile, not squishy.
+2. **Release**: `back.out(${BOUNCE_FACTOR})` spring → elastic pop back to `1.0` (overshoot proportional to `BOUNCE_FACTOR`). Optional burst glow ring expands behind the button; optional background environmental glow fades in.
+
+State continuity is critical: the release tween's start value MUST equal the press tween's end value, or the spring snaps to a different position. GSAP threads this automatically when both tweens target the same property at adjacent positions on the same timeline.
+
+## HTML
+
+```html
+<div
+  class="scene"
+  id="press-scene"
+  data-composition-id="press-scene"
+  data-start="0"
+  data-duration="DURATION"
+  data-track-index="0"
+>
+  <div class="press-stage">
+    <div class="bg-glow" id="bg-glow"></div>
+    <div class="burst" id="burst"></div>
+    <button class="btn" id="btn">{buttonLabel}</button>
+  </div>
+</div>
+```
+
+## CSS
+
+```css
+.scene {
+  position: relative;
+  width: 100%;
+  height: 100%;
+  display: grid;
+  place-items: center;
+  background: {bgColor};
+}
+.press-stage {
+  position: relative;
+  display: grid;
+  place-items: center;
+}
+.btn {
+  position: relative;
+  z-index: 2;
+  /* Visual weight: ≥4% of canvas for the press to read on a 1080p frame */
+  width: BTN_WIDTH;
+  height: BTN_HEIGHT;
+  background: {btnBg};
+  border: none;
+  border-radius: BTN_RADIUS;
+  font-family: {font};
+  font-weight: 900;
+  font-size: BTN_FONT_SIZE;
+  letter-spacing: BTN_LETTER_SPACING;
+  color: {btnTextColor};
+  text-transform: uppercase;
+  /* Anchor compression on the center — see Critical Constraints */
+  transform-origin: 50% 50%;
+  /* Initial floating shadow — large + diffuse */
+  box-shadow: {btnRestShadow};
+}
+.burst {
+  /* Sits BEHIND the button, same footprint */
+  position: absolute;
+  z-index: 1;
+  inset: 0;
+  width: BTN_WIDTH;
+  height: BTN_HEIGHT;
+  background: {burstGradient};
+  filter: blur(BURST_BLUR);
+  opacity: 0;
+  transform: scale(1);
+  pointer-events: none;
+}
+.bg-glow {
+  /* Full-stage radial — extends beyond the stage with negative inset */
+  position: absolute;
+  inset: BG_GLOW_INSET;
+  background: {bgGlowGradient};
+  opacity: 0;
+  pointer-events: none;
+}
+```
+
+## 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 — press (linear compression)
+  tl.to(
+    "#btn",
+    {
+      scale: PRESS_SCALE,
+      boxShadow: "{btnPressedShadow}",
+      duration: PRESS_DUR,
+      ease: "power1.in",
+    },
+    PRESS_START,
+  );
+
+  // Phase 2 — release (spring back with overshoot)
+  // CRITICAL: start scale == end of phase 1 (PRESS_SCALE) to maintain state continuity.
+  tl.to(
+    "#btn",
+    {
+      scale: 1,
+      boxShadow: "{btnRestShadow}",
+      duration: RELEASE_DUR,
+      ease: `back.out(${BOUNCE_FACTOR})`,
+    },
+    RELEASE_START,
+  );
+
+  // Phase 3 — burst glow (radial pop behind button), triggered with release
+  tl.fromTo(
+    "#burst",
+    { scale: 1, opacity: 0 },
+    {
+      scale: BURST_PEAK_SCALE,
+      opacity: BURST_PEAK_OPACITY,
+      duration: BURST_GROW_DUR,
+      ease: "power2.out",
+    },
+    RELEASE_START,
+  );
+  // Burst then fades out
+  tl.to("#burst", { opacity: 0, duration: BURST_FADE_DUR, ease: "power2.in" }, BURST_FADE_START);
+
+  // Phase 4 — background environmental glow fades in after release
+  tl.to(
+    "#bg-glow",
+    {
+      opacity: BG_GLOW_PEAK_OPACITY,
+      duration: BG_GLOW_FADE_DUR,
+      ease: "power2.out",
+    },
+    RELEASE_START,
+  );
+
+  window.__timelines["press-scene"] = tl;
+</script>
+```
+
+## Variations
+
+### Subtle press (status save / muted CTA)
+
+Less compression, gentler overshoot, smaller burst. `PRESS_SCALE` toward the high end of its range (~0.96), `BOUNCE_FACTOR` toward the low end (~1.4), `BURST_PEAK_SCALE` and `BURST_PEAK_OPACITY` reduced.
+
+### Dramatic press (hero CTA / "ship it" moment)
+
+Deeper compression, more overshoot, larger burst. `PRESS_SCALE` toward the low end (~0.88), `BOUNCE_FACTOR` toward the high end (~2.5), `BURST_PEAK_SCALE` and `BURST_PEAK_OPACITY` maxed.
+
+### Color shift during press
+
+Darken the button mid-press, return on release. Same timeline positions as the scale tweens — interpolated `backgroundColor` on `#btn`. State continuity rule still applies: the release-color tween's start equals the press-color tween's end.
+
+```js
+tl.to("#btn", { backgroundColor: "{btnPressedColor}", duration: PRESS_DUR }, PRESS_START);
+tl.to("#btn", { backgroundColor: "{btnRestColor}", duration: RELEASE_DUR }, RELEASE_START);
+```
+
+### State change at release (approve / confirm pattern)
+
+When the press signals confirmation, swap the button's resting color to a success token at `RELEASE_START` (instead of returning to `{btnRestColor}`), then pop a checkmark via a separate `back.out(${CHECK_BOUNCE})` tween at the same position. The button is now in its terminal state — no further presses expected.
+
+```js
+tl.to("#btn", { backgroundColor: "{successColor}", duration: RELEASE_DUR }, RELEASE_START);
+tl.to(
+  ".btn-check",
+  { scale: 1, duration: CHECK_POP_DUR, ease: `back.out(${CHECK_BOUNCE})` },
+  RELEASE_START,
+);
+```
+
+## How to Choose Values
+
+### Geometry
+
+- **BTN_WIDTH / BTN_HEIGHT** — button footprint.
+  - Range: button area ≥ 3-5% of canvas (a 320×68 button at 1080p is ~1% and reads as visually insignificant)
+  - Effects: smaller → press barely reads; larger → press dominates the frame
+  - Constraints: `BTN_WIDTH × BTN_HEIGHT / (canvasW × canvasH) ≥ 0.03`
+- **BTN_RADIUS** — corner radius.
+  - Range: `BTN_HEIGHT × 0.15` (sharp/modern) → `BTN_HEIGHT / 2` (pill)
+- **BTN_FONT_SIZE / BTN_LETTER_SPACING** — typographic weight.
+  - Range: `BTN_FONT_SIZE ≈ BTN_HEIGHT × 0.4-0.5`; letter-spacing 4-10 px reads as "actionable label"
+
+### Press dynamics
+
+- **PRESS_SCALE** — compression depth.
+  - Range: 0.88 (dramatic) → 0.92 (default) → 0.96 (subtle)
+  - Effects: lower → more tactile / weightier; higher → barely-there acknowledgment
+  - Constraints: never <0.85 (button feels broken) or >0.98 (no perceptible dip)
+- **PRESS_DUR** — compression duration.
+  - Range: 0.10-0.30 s
+  - Effects: shorter → snappier / "instant-feeling"; longer → slow squish
+  - Constraints: shorter than `RELEASE_DUR` (input is faster than spring recovery)
+- **RELEASE_DUR** — spring recovery duration.
+  - Range: 0.40-0.90 s
+  - Effects: shorter → tight pop; longer → loose, wobbly settle
+- **BOUNCE_FACTOR** — `back.out(BOUNCE_FACTOR)` overshoot strength.
+  - Range: 1.4 (soft) → 2.0 (firm pop) → 2.8 (cartoony)
+  - Effects: low end barely overshoots; high end reads as cartoonish; tune by feel
+  - Alternative: switch to `elastic.out(amplitude, period)` for a rubbery oscillation instead of a single overshoot
+- **PRESS_START / RELEASE_START** — timeline positions.
+  - Constraints: `RELEASE_START = PRESS_START + PRESS_DUR` (state continuity — see Critical Constraints)
+
+### Burst glow
+
+- **BURST_PEAK_SCALE** — radial pop max scale.
+  - Range: 3 (subtle) → 6 (default) → 8 (dramatic)
+  - Constraints: ≤ ~8 — beyond that the radial gradient pixelates visibly
+- **BURST_PEAK_OPACITY** — burst max opacity.
+  - Range: 0.4 (subtle) → 0.8 (default) → 1.0 (dramatic)
+- **BURST_GROW_DUR / BURST_FADE_DUR** — grow vs. fade timing.
+  - Range: 0.4-0.7 s each; default grow ≈ fade
+- **BURST_BLUR** — gaussian blur on the burst layer.
+  - Range: 40-100 px; smaller reads as a hard ring, larger as ambient haze
+
+### Background glow
+
+- **BG_GLOW_PEAK_OPACITY** — peak environmental glow.
+  - Range: 0.1 (subtle) → 0.25 (default) → 0.45 (dramatic)
+  - Constraints: ≤ 0.45 — higher washes the whole composition
+- **BG_GLOW_FADE_DUR** — fade-in duration.
+  - Range: 0.6-1.0 s
+- **BG_GLOW_INSET** — negative inset so the radial extends past the stage edges.
+  - Range: typically `-300` to `-500` px on a 1920×1080 canvas
+
+### Optional "approve" variation
+
+- **CHECK_BOUNCE** — checkmark pop overshoot.
+  - Range: 1.4-2.0; firmer than the button's main `BOUNCE_FACTOR` to read as a punctuating "stamp"
+- **CHECK_POP_DUR** — checkmark scale-up duration.
+  - Range: 0.3-0.6 s
+
+### Tokens
+
+- **{btnBg} / {btnRestColor} / {btnPressedColor}** — primary button surface; pressed darker than rest
+- **{btnRestShadow} / {btnPressedShadow}** — rest shadow is large + diffuse; pressed is small + tight (the button "sinks toward the surface")
+- **{burstGradient}** — radial; saturated near center, fading to transparent (color should be darker + more saturated than `{btnBg}` — same-color glow looks washed out)
+- **{bgGlowGradient}** — full-stage radial, low-opacity tint of `{btnBg}`'s hue family
+- **{successColor}** — confirmation green / brand-success for the approve variation
+
+## Key Principles
+
+- **State continuity** — release start value MUST exactly match press end value. With a GSAP timeline, the first tween's end value automatically becomes the second tween's start when they target the same property at adjacent times.
+- **Visual weight** — button area should be **≥3-5% of canvas**. Smaller and the press reads as visually insignificant.
+- **Linear press, spring release** — the compression is `power1.in/out`, the recovery is `back.out`. Both spring → squishy; both linear → mechanical / no overshoot punch.
+- **Anchor compression on center** — `transform-origin: 50% 50%` (default). Otherwise the button collapses asymmetrically.
+- **Burst behind, not in front** — burst `z-index: 1`, button `z-index: 2`. If burst sits in front, it occludes the button at peak opacity.
+- **Glow color darker + more saturated than element** — bright surface → dark, saturated glow. Same-color glow looks washed out.
+- **Don't tween `boxShadow` and `filter` together on the same element** — they compete in the layout pipeline; pick one. Shadow on the button, blur on a separate burst layer.
+- **Climax beats need dwell time** — after the burst peak + label/wordmark reveal, the composition must run for **≥1s more** (≥2s for "dramatic" variants) before ending. A reveal at `t=DURATION−0.2s` reads as "flashed and gone."
+
+## Critical Constraints
+
+- **Timeline must be paused**: `gsap.timeline({ paused: true })`
+- **Registry key = `data-composition-id`**
+- **No CSS `transition`** on the button — those interpolate independently of HF seek and cause flicker
+- **`will-change: transform`** if the button compounds with other animation layers
+- **`RELEASE_START = PRESS_START + PRESS_DUR`** — adjacency on the same property is what makes state continuity automatic; gap or overlap breaks it
+- **Burst max scale ≤ ~8** — beyond that the radial gradient pixelates visibly
+- **Background glow `opacity ≤ 0.45`** — higher and it washes the whole composition
+- **GSAP transform aliases only**: `x`, `y`, `scale`, `rotation`. Never tween `width` / `height` / `left` / `top`.
+
+## Combinations
+
+- [sine-wave-loop.md](sine-wave-loop.md) — idle micro-float on the button BEFORE the press (slight breathing, sells "ready")
+- [center-outward-expansion.md](center-outward-expansion.md) — burst of badges outward synced to the press release
+- [cursor-click-ripple.md](cursor-click-ripple.md) — cursor click that triggers the press
+
+## Pairs with HF skills
+
+- `/hyperframes-animation` — `back.out` ease + multi-tween coordination
+- `/hyperframes-core` — composition wiring
+- `/hyperframes-cli` — `hyperframes lint`