takomi 2.5.1 → 2.5.4

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

@@ -1,350 +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`
+---
+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`