@mevdragon/vidfarm-devcli 0.14.0 → 0.15.0

package/.agents/skills/hyperframes-animation/rules/vertical-spring-ticker.md

@@ -0,0 +1,239 @@
+---
+name: vertical-spring-ticker
+description: Slot-machine style vertical scrolling using additive spring physics within a masked container — each spring contributes one "step" of scroll.
+metadata:
+  tags: text, ticker, spring, scroll, vertical, slot-machine, sequence
+---
+
+# Vertical Spring Ticker (Slot Machine)
+
+Multiple spring tweens are ADDED TOGETHER to produce total Y translation. Each spring contributes one discrete "step." The combined motion has snappy distinct moves with natural settling — instead of a single linear scroll, you get the slot-machine "click click click" rhythm.
+
+## How It Works
+
+Container has fixed height `ITEM_HEIGHT`, `overflow: hidden`. Inside is a vertical stack of items, each also `ITEM_HEIGHT` tall. The translate of the inner stack is computed as:
+
+```
+translateY = -ITEM_HEIGHT * sum(spring_i.progress for each spring)
+```
+
+Each spring fires at a different time, settles, then the next fires. When summed, the stack snaps forward step-by-step. The "spring" easing gives each step a tiny overshoot/settle that distinguishes it from a linear marquee.
+
+## HTML
+
+```html
+<div
+  class="scene"
+  id="ticker-scene"
+  data-composition-id="ticker-scene"
+  data-start="0"
+  data-duration="5"
+  data-track-index="0"
+>
+  <div class="stack">
+    <div class="eyebrow">{eyebrow}</div>
+    <div class="ticker" id="ticker">
+      <div class="stack-inner" id="stack-inner">
+        <!-- One .item per state the ticker rolls through.
+             The example file lists concrete labels; for the rule, treat
+             these as positional slots ({item0} … {itemN}). -->
+        <div class="item">{item0}</div>
+        <div class="item">{item1}</div>
+        <div class="item">{item2}</div>
+        <div class="item">{item3}</div>
+        <div class="item">{itemN}</div>
+      </div>
+    </div>
+    <div class="brand">{footerLine}</div>
+  </div>
+</div>
+```
+
+## CSS
+
+```css
+.scene {
+  position: relative;
+  width: 100%;
+  height: 100%;
+  display: grid;
+  place-items: center;
+  background: {bgColor};
+  font-family: {font};
+}
+.stack {
+  display: flex;
+  flex-direction: column;
+  align-items: center;
+  gap: STACK_GAP;
+}
+.eyebrow {
+  font-size: EYEBROW_FONT_SIZE;
+  font-weight: 800;
+  letter-spacing: 14px;
+  text-transform: uppercase;
+  color: {accentColor};
+}
+/* MANDATORY: container height matches the per-item height exactly */
+.ticker {
+  width: TICKER_WIDTH;
+  height: ITEM_HEIGHT;       /* MUST match .item height */
+  overflow: hidden;
+  border-top: 2px solid {dividerColor};
+  border-bottom: 2px solid {dividerColor};
+  position: relative;
+}
+.stack-inner {
+  display: flex;
+  flex-direction: column;    /* MANDATORY for vertical ticker */
+  will-change: transform;
+}
+.item {
+  height: ITEM_HEIGHT;       /* MUST equal .ticker height */
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  font-size: ITEM_FONT_SIZE;
+  font-weight: 900;
+  letter-spacing: 8px;
+  text-transform: uppercase;
+  color: {textColor};
+  /* font-variant-numeric: tabular-nums; — for numeric tickers */
+}
+.brand {
+  font-size: BRAND_FONT_SIZE;
+  font-weight: 800;
+  letter-spacing: 10px;
+  color: {accentColor};
+  text-transform: uppercase;
+}
+```
+
+## GSAP Timeline
+
+```html
+<script src="https://cdn.jsdelivr.net/npm/gsap@3.14.2/dist/gsap.min.js"></script>
+<script>
+  window.__timelines = window.__timelines || {};
+  const tl = gsap.timeline({ paused: true });
+
+  const innerEl = document.getElementById("stack-inner");
+
+  // Each spring object holds a 0→1 progress; they accumulate to a step-counter.
+  // Sum * -ITEM_HEIGHT becomes translateY.
+  const springs = Array.from({ length: STEPS }, () => ({ p: 0 }));
+
+  function applyTransform() {
+    const sumP = springs.reduce((acc, s) => acc + s.p, 0);
+    innerEl.style.transform = `translateY(${-sumP * ITEM_HEIGHT}px)`;
+  }
+  applyTransform(); // initial state
+
+  // Fire each spring sequentially with overlap — each one snaps in one step
+  springs.forEach((spring, i) => {
+    tl.to(
+      spring,
+      {
+        p: 1,
+        duration: STEP_DUR,
+        ease: `back.out(${BOUNCE_FACTOR})`,
+        onUpdate: applyTransform,
+      },
+      STEP_START + i * STEP_SPACING,
+    );
+  });
+
+  // Footer reveals after the ticker settles on the final item.
+  tl.from(
+    ".brand",
+    { opacity: 0, y: BRAND_Y, duration: BRAND_FADE_DUR, ease: "power3.out" },
+    STEP_START + STEPS * STEP_SPACING + BRAND_DELAY,
+  );
+
+  window.__timelines["ticker-scene"] = tl;
+</script>
+```
+
+## How to Choose Values
+
+- **ITEM_HEIGHT** — px height of each ticker slot AND the masked window.
+  - Range: ~`ITEM_FONT_SIZE × 1.25`; the line must hold capital descenders without clipping
+  - Constraints: **`.ticker` height MUST equal `.item` height** exactly — mismatched values cause partial items to peek above/below the mask
+  - Reference: ../../examples/proof-logo-chain.html uses `204px`
+- **TICKER_WIDTH** — px width of the masked window.
+  - Range: wide enough to hold the longest item without ellipsis; typically 30-60% of viewport width
+- **STEPS** — number of additive springs (number of state transitions, not number of items).
+  - Range: typically 1-4; each step = one "click" in the slot-machine cadence
+  - Constraints: `STEPS ≤ itemCount − 1` (you can only roll as far as there are items below the visible one)
+  - Reference: ../../examples/proof-logo-chain.html uses `1` (single roll between two states)
+- **STEP_DUR** — duration of each spring tween.
+  - Range: 0.3-0.7s; under 0.3 the overshoot is invisible, over 0.7 the click reads as a slide
+  - Reference: ../../examples/proof-logo-chain.html uses `0.45s`
+- **STEP_SPACING** — seconds between consecutive springs' start times.
+  - Range: 0.3-0.5s; closer and the steps blur together (looks like linear scroll), further and the ticker feels lazy
+  - Constraints: `STEP_SPACING ≤ STEP_DUR` so the previous step is still settling when the next fires (this is what makes them "additive")
+- **STEP_START** — when the first spring fires.
+  - Range: 0+; gate behind any preceding beat
+- **BOUNCE_FACTOR** — `back.out(BOUNCE_FACTOR)` overshoot strength per step.
+  - Range: 1.4 (gentle click) → 2.0 (firm click) → 2.5+ (cartoony spin-and-land for a climax step)
+  - Effects: low end reads as polished UI, high end reads as casino / game show
+- **BRAND_DELAY** — gap after the final step before the footer line reveals, in seconds.
+  - Range: 0.2-0.5s; lets the final overshoot settle before the next element competes for attention
+- **BRAND_FADE_DUR** — footer fade-in duration.
+  - Range: 0.4-0.7s
+- **BRAND_Y** — initial vertical offset of the footer before fade-up (in px).
+  - Range: 8-24 px; bigger feels "punched in," smaller feels gentle
+- **EYEBROW_FONT_SIZE / ITEM_FONT_SIZE / BRAND_FONT_SIZE / STACK_GAP** — typographic + layout scaling.
+  - Constraints: items are the focal beat, sized 4-8× larger than eyebrow/footer
+- **{bgColor} / {accentColor} / {textColor} / {dividerColor}** — semantic color tokens; accent reserved for the eyebrow and footer so the ticker items stay neutral.
+- **{font}** — base typography stack. For numeric tickers add `font-variant-numeric: tabular-nums` so digit widths stay constant.
+
+## Variations
+
+### Numeric ticker (price / counter rolling)
+
+Replace text items with the digit sequence and use the same spring-step pattern per decimal position (units, tens, hundreds...). Add `font-variant-numeric: tabular-nums` for digit-width stability.
+
+### Reverse direction (counting down)
+
+Swap the sign on the translate: `transform: translateY(${sumP * ITEM_HEIGHT}px)` and arrange items in reverse order. Reads as a countdown.
+
+### Continuous infinite ticker (no settling)
+
+Loop forever (e.g. news ticker) — use linear ease on a single long tween, duplicate the items list, reset when translation exceeds total height. NOT this rule — see [sine-wave-loop](sine-wave-loop.md) pattern for continuous motion vs this rule's discrete-step semantics.
+
+### Pause between groups
+
+For dramatic "spin then land" feel, group several fast spring steps (`STEP_SPACING` small) + a long `BRAND_DELAY`-style pause + a final dramatic step with bigger `BOUNCE_FACTOR`. The pause is where the eye locks in.
+
+## Key Principles
+
+- **Container height MUST equal item height** — otherwise items don't snap cleanly into the visible window. If container is 200px and items are 220px, every step shows a partial item edge above/below.
+- **`overflow: hidden` on container, NOT on inner stack** — the mask is the window; the stack inside is free to extend below.
+- **`flex-direction: column` on inner stack** — required for vertical stacking; row would make items horizontal.
+- **Step spacing tighter than step duration** — overlap is what makes the springs additive and gives the "click click" cadence; non-overlapping steps read as a linear scroll.
+- **`back.out` per step** — the overshoot is what makes each step feel like a "click." Linear ease or out-only ease loses the slot-machine feel.
+- **Sum the springs in onUpdate, don't tween the final position directly** — this is the "additive" trick; each spring contributes its OWN snap, which is the slot-machine pacing.
+- **❗ Don't update items via `innerHTML` between steps** — the ticker moves the SAME items via translate; replacing content makes the previous item visible AS the new one (broken illusion).
+- **❗ Climax dwell ≥1s after final step** — see SKILL universal constraints.
+
+## Critical Constraints
+
+- **Timeline must be paused**: `gsap.timeline({ paused: true })`
+- **Registry key = `data-composition-id`**
+- **No CSS `transition`** on stack-inner — competes with the additive transform
+- **`will-change: transform`** on stack-inner — many small transform updates per second
+- **All items same height (pixel-exact)** — mismatched heights cause cumulative drift
+- **For numeric: `font-variant-numeric: tabular-nums`** — variable digit widths break alignment
+
+## Combinations
+
+- [reactive-displacement.md](reactive-displacement.md) — ticker is "pushed" by an incoming element
+- [scale-swap-transition.md](scale-swap-transition.md) — ticker scales out after settling on final state, scaled-in subtitle replaces it
+- [press-release-spring.md](press-release-spring.md) — button press TRIGGERS the ticker spin
+
+## Pairs with HF skills
+
+- `/hyperframes-animation` — additive spring tweens via shared onUpdate
+- `/hyperframes-core` — composition wiring
+- `/hyperframes-cli` — `hyperframes lint`

package/.agents/skills/hyperframes-animation/rules/viewport-change.md

@@ -0,0 +1,349 @@
+---
+name: viewport-change
+description: Virtual camera — simulate zoom / pan / focus-lock by transforming a wrapper around all scene content. Camera moves right → world translates left.
+metadata:
+  tags: viewport, camera, zoom, pan, focus-lock, virtual-camera
+---
+
+# Viewport Change (Virtual Camera)
+
+Simulates camera effects (zoom / pan / focus-lock on a moving element) by transforming a wrapper around ALL scene content. The "world" moves opposite to the perceived camera. Distinct from [multi-phase-camera](multi-phase-camera.md) (which is 2-3 discrete phases + drift) — viewport-change is a single continuous zoom/pan, often used for focus-lock following a moving element.
+
+## How It Works
+
+Camera intent → world transform:
+
+- Camera **pans right** → world `translateX(-distance)`
+- Camera **zooms in** → world `scale(>1)`
+- Camera **follows element X** → world `translateX(viewportCenter - elementWorldX)` updated per-frame
+
+The wrapper holds the camera transform; the elements inside are positioned in "world space" unchanged.
+
+**Single-element composite transform (this rule's form).** Both scale and translate live on ONE wrapper as `translate(x, y) scale(S)`. CSS applies scale FIRST, then translate (right-to-left matrix composition), so a point at world offset `(ox, oy)` lands on screen at `(S × ox + x, S × oy + y)`. To map the target to viewport center:
+
+```
+T = -offset × S
+```
+
+This is **different from [coordinate-target-zoom](coordinate-target-zoom.md)**, which uses two nested wrappers (outer scales, inner translates) and derives `T = -offset` (independent of S). Use this rule's single-wrapper form when you want one source of truth for camera state (`cam.scale`, `cam.x`, `cam.y`) updated via `onUpdate`; use nested wrappers when scale and translate can tween independently with shared ease.
+
+## HTML
+
+```html
+<div
+  class="scene"
+  id="viewport-scene"
+  data-composition-id="viewport-scene"
+  data-start="0"
+  data-duration="5"
+  data-track-index="0"
+>
+  <div class="world" id="world">
+    <div class="content">
+      <div class="hero" id="hero">{Brand}</div>
+      <div class="tagline">{tagline}</div>
+      <div class="cta-row">
+        <div class="cta" id="cta">{ctaUrl}</div>
+      </div>
+    </div>
+  </div>
+</div>
+```
+
+## CSS
+
+```css
+.scene {
+  position: relative;
+  width: 100%;
+  height: 100%;
+  overflow: hidden;
+  background: {bgGradient};
+  font-family: {font};
+}
+.world {
+  position: absolute;
+  inset: 0;
+  display: grid;
+  place-items: center;
+  transform-origin: 50% 50%;
+  will-change: transform;
+}
+.content {
+  display: flex;
+  flex-direction: column;
+  align-items: center;
+  gap: CONTENT_GAP;
+  text-align: center;
+}
+.hero {
+  font-size: HERO_FONT_SIZE;
+  font-weight: 900;
+  letter-spacing: HERO_LETTER_SPACING;
+  text-transform: uppercase;
+  color: {textColor};
+}
+.tagline {
+  font-size: TAGLINE_FONT_SIZE;
+  font-weight: 600;
+  color: {labelColor};
+}
+.cta {
+  display: inline-block;
+  padding: CTA_PADDING_Y CTA_PADDING_X;
+  font-family: {monoFont};
+  font-size: CTA_FONT_SIZE;
+  font-weight: 700;
+  letter-spacing: CTA_LETTER_SPACING;
+  color: {accentColor};
+  text-transform: uppercase;
+  background: {ctaBg};
+  border: 1px solid {ctaBorder};
+  border-radius: CTA_BORDER_RADIUS;
+}
+```
+
+## GSAP Timeline
+
+```html
+<script src="https://cdn.jsdelivr.net/npm/gsap@3.14.2/dist/gsap.min.js"></script>
+<script>
+  window.__timelines = window.__timelines || {};
+  const tl = gsap.timeline({ paused: true });
+
+  const world = document.getElementById("world");
+
+  // Camera state — single source of truth. World transform is composed from
+  // this object inside applyCamera() so the transform string order is stable.
+  const cam = { scale: 1, x: 0, y: 0 };
+
+  function applyCamera() {
+    world.style.transform = `translate(${cam.x}px, ${cam.y}px) scale(${cam.scale})`;
+  }
+  applyCamera();
+
+  // Phase 1 — content reveal at neutral camera
+  tl.from(".hero", { opacity: 0, y: HERO_Y, duration: HERO_DUR, ease: "power3.out" }, HERO_START);
+  tl.from(
+    ".tagline",
+    { opacity: 0, y: TAGLINE_Y, duration: TAGLINE_DUR, ease: "power3.out" },
+    TAGLINE_START,
+  );
+
+  // Phase 2 — zoom in on CTA (single-element composite transform)
+  // CSS applies scale FIRST then translate: world point (ox, oy) lands at
+  // (S × ox + x, S × oy + y). Solve S × offset + T = 0 → T = -offset × S.
+  // This is DIFFERENT from coordinate-target-zoom (nested wrappers, T = -offset).
+  const counterY = -TARGET_OFFSET_Y * TARGET_SCALE;
+
+  tl.to(
+    cam,
+    {
+      scale: TARGET_SCALE,
+      y: counterY,
+      duration: ZOOM_DUR,
+      ease: "power3.inOut",
+      onUpdate: applyCamera,
+    },
+    ZOOM_START,
+  );
+
+  // Phase 3 — CTA reveals/dwells after zoom settles
+  tl.from(
+    "#cta",
+    {
+      opacity: 0,
+      scale: CTA_REVEAL_SCALE,
+      duration: CTA_REVEAL_DUR,
+      ease: `back.out(${BOUNCE_FACTOR})`,
+    },
+    CTA_REVEAL_START,
+  );
+
+  window.__timelines["viewport-scene"] = tl;
+</script>
+```
+
+## Scale Value Guide
+
+| Effect      | Scale       | Feel                                |
+| ----------- | ----------- | ----------------------------------- |
+| Subtle      | 1.02 - 1.05 | Barely perceptible — "professional" |
+| Medium      | 1.05 - 1.15 | "Ta-da" emphasis                    |
+| Noticeable  | 1.15 - 1.30 | Focus on region                     |
+| Dramatic    | 1.5 - 2.5   | Element fills screen                |
+| Full-screen | 3.0+        | Element covers viewport             |
+
+| Perception threshold | Result               |
+| -------------------- | -------------------- |
+| < 5%                 | Imperceptible        |
+| 10-15%               | Comfortable emphasis |
+| > 30%                | Cinematic / dramatic |
+
+## Variations
+
+### Focus-lock (camera follows moving cursor/character)
+
+For an element moving across the world, keep it at fixed screen X. Compute world offset per-frame:
+
+```js
+const focusEl = document.querySelector(".moving-cursor");
+const targetScreenX = VIEWPORT_WIDTH * FOCUS_SCREEN_X_FRAC;
+const focusUpdate = { p: 0 };
+tl.to(
+  focusUpdate,
+  {
+    p: 1,
+    duration: FOLLOW_DUR,
+    ease: "power2.inOut",
+    onUpdate: () => {
+      const rect = focusEl.getBoundingClientRect();
+      const focusWorldX = rect.left + rect.width / 2;
+      cam.x = targetScreenX - focusWorldX;
+      applyCamera();
+    },
+  },
+  FOLLOW_START,
+);
+```
+
+### Composite scale (multi-phase)
+
+Multiply two scale tweens for compound effects:
+
+```js
+const scaleUp = { v: 1 };
+const scaleDown = { v: 1 };
+function applyCompositeCamera() {
+  cam.scale = scaleUp.v * scaleDown.v;
+  applyCamera();
+}
+tl.to(
+  scaleUp,
+  { v: SCALE_UP_TARGET, duration: SCALE_UP_DUR, onUpdate: applyCompositeCamera },
+  SCALE_UP_START,
+);
+tl.to(
+  scaleDown,
+  { v: SCALE_DOWN_TARGET, duration: SCALE_DOWN_DUR, onUpdate: applyCompositeCamera },
+  SCALE_DOWN_START,
+);
+```
+
+### Camera mode transition (centered → follow)
+
+Crossfade between two camera modes via a 0→1 weight tween. At weight 0, mode A; at weight 1, mode B; intermediate is interpolated.
+
+## How to Choose Values
+
+### Layout (CSS)
+
+- **CONTENT_GAP** — vertical gap between hero, tagline, and CTA.
+  - Range: 16-48 px
+  - Effects: small → tightly stacked (logo-lockup feel); large → airy, editorial
+- **HERO_FONT_SIZE / TAGLINE_FONT_SIZE / CTA_FONT_SIZE** — typographic hierarchy.
+  - Range: hero >> tagline > CTA (hero is the brand mark, CTA is the actionable footer)
+  - Constraints: hero must remain readable when scaled DOWN at neutral camera AND when scaled UP during the zoom — pick the size at neutral camera, the zoom only enlarges it
+- **HERO_LETTER_SPACING / CTA_LETTER_SPACING** — uppercase tracking.
+  - Range: 4-10 px for uppercase display type; 0 for sentence case
+- **CTA_PADDING_X / CTA_PADDING_Y / CTA_BORDER_RADIUS** — pill geometry around the CTA text.
+  - Constraints: `CTA_BORDER_RADIUS ≥ CTA_FONT_SIZE` to keep the pill ends fully rounded
+
+### Phase 1 — Content reveal
+
+- **HERO_START** — when the hero begins fading in.
+  - Range: 0.2-0.5s (small offset for a beat of black before content appears)
+- **HERO_DUR** — hero fade-up duration.
+  - Range: 0.6-1.2s
+- **HERO_Y** — initial Y offset of hero before fade-up (in px).
+  - Range: 16-48 px
+- **TAGLINE_START** — when the tagline begins fading in.
+  - Constraints: `≥ HERO_START + 0.3` (let the hero land first so the eye reads top-down)
+- **TAGLINE_DUR / TAGLINE_Y** — same shape as hero, typically smaller (`TAGLINE_Y` half of `HERO_Y`).
+
+### Phase 2 — Zoom
+
+- **TARGET_OFFSET_Y** — measured Y offset (in px) of the CTA from viewport center at neutral camera.
+  - Constraints: derived from layout, NOT a free parameter. Measure via `getBoundingClientRect()` OR compute from `CONTENT_GAP + (HERO_HEIGHT + TAGLINE_HEIGHT) / 2`. Sign matters — positive = below center.
+- **TARGET_SCALE** — final magnification of the world.
+  - Range: 1.3× (modest) → 1.6-2.0× (typical CTA zoom) → 3×+ (cinematic)
+  - Constraints: raster source media needs `sourceResolution ≥ rendered × TARGET_SCALE`; text remains crisp at any scale
+- **ZOOM_START** — when the zoom begins.
+  - Constraints: `≥ TAGLINE_START + TAGLINE_DUR + viewer-scan-time` (give viewer ~0.5s after content lands before camera moves)
+- **ZOOM_DUR** — duration of the zoom tween.
+  - Range: 1.0-2.0s; under 0.8s feels like a teleport, over 2.5s drags
+
+### Phase 3 — CTA reveal + dwell
+
+- **CTA_REVEAL_START** — when the CTA pops in.
+  - Constraints: `≥ ZOOM_START + ZOOM_DUR × 0.9` (start near the end of the zoom so the CTA "lands" with the camera)
+- **CTA_REVEAL_DUR** — CTA fade-in / pop duration.
+  - Range: 0.4-0.8s
+- **CTA_REVEAL_SCALE** — initial scale of the CTA before pop.
+  - Range: 0.85-0.95 (sub-1 → grows into place); >1.0 inverts to a shrink-into-place feel
+- **BOUNCE_FACTOR** — overshoot coefficient for `back.out(${BOUNCE_FACTOR})`.
+  - Range: 1.2-2.5; lower = subtle settle, higher = pronounced overshoot. The ease family (`back.out`) is the choice; this number tunes its intensity.
+  - Reference: ease family options: `back.out` (overshoot then settle), `elastic.out` (oscillation), `power3.out` (clean decel, no overshoot)
+- **DWELL_DUR** — implicit hold after `CTA_REVEAL_START + CTA_REVEAL_DUR` until `data-duration` ends.
+  - Range: ≥ 1.0s (see "Climax dwell" in Key Principles)
+
+### Focus-lock variation
+
+- **VIEWPORT_WIDTH** — composition width in px. Real value (`data-width` on the root); not abstract.
+- **FOCUS_SCREEN_X_FRAC** — where on screen to lock the focused element.
+  - Range: 0.4-0.7 (rule of thirds positions); 0.5 is dead center
+- **FOLLOW_START / FOLLOW_DUR** — when the follow-cam engages and for how long.
+  - Constraints: `FOLLOW_DUR` matches the duration the focused element is in motion
+
+### Composite-scale variation
+
+- **SCALE_UP_TARGET / SCALE_DOWN_TARGET** — multiplicative factors composed via `cam.scale = scaleUp.v * scaleDown.v`.
+  - Effects: combine a slow push-in (`SCALE_UP_TARGET` ~1.15) with a brief release (`SCALE_DOWN_TARGET` ~0.9) for a breath/punch shape
+- **SCALE_UP_START / SCALE_UP_DUR / SCALE_DOWN_START / SCALE_DOWN_DUR** — phase timing for each multiplicand.
+
+### Color tokens
+
+- **{bgGradient}** — scene background (typically a dark radial vignette so edges fall off as zoom reveals them)
+- **{textColor}** — hero text; highest contrast against `{bgGradient}`
+- **{labelColor}** — tagline / secondary copy; one step softer than `{textColor}`
+- **{accentColor}** — CTA text + border; reserved hue that pops on reveal
+- **{ctaBg} / {ctaBorder}** — semi-transparent fills derived from `{accentColor}` (typical `rgba` at 10-15% / 35-45% alpha)
+
+### Font tokens
+
+- **{font}** — sans-serif body / hero stack (e.g. `"Inter", sans-serif`)
+- **{monoFont}** — monospace CTA stack (e.g. `"JetBrains Mono", monospace`); reserved for the URL/code-like CTA so it reads as actionable
+
+## Key Principles
+
+- **World moves opposite to perceived camera** — pan camera right = `translateX(-x)` on the world wrapper. Get this sign right, otherwise everything moves the wrong way.
+- **Single-wrapper transform order matters** — `translate(x, y) scale(S)` applies scale first; counter-translate is `T = -offset × S`. Mixing this up with the nested-wrapper form (`T = -offset`) drifts the target off-center as scale changes.
+- **`overflow: hidden` on `.scene` REQUIRED** — at any non-1.0 scale the world transform reveals edges or pushes content off-frame.
+- **`transform-origin: 50% 50%`** on the world wrapper — centered scaling is what the math assumes.
+- **Background on `.scene`, NOT on `.world`** — if background is on the world, transforming the world warps/translates the background.
+- **Single source of truth via `cam` object + `applyCamera()`** — when scale and translate both change, write them in ONE place. Otherwise the transform string composition order is unpredictable.
+- **Subtle continuous motion > big sudden zoom** — for a feel-natural product video, use 1.05-1.15× zoom over 2-3s. Big > 1.3× zooms read as dramatic narrative moments, save them.
+- **Climax dwell >=1s** — after the zoom settles, the comp must continue for >=1s so the viewer can read the focal point.
+
+## Critical Constraints
+
+- **Timeline must be paused**: `gsap.timeline({ paused: true })`
+- **Registry key = `data-composition-id`**
+- **No CSS `transition` on `.world`** — competes with GSAP
+- **`will-change: transform`** on `.world`
+- **`overflow: hidden` on `.scene`**
+- **`transform-origin: 50% 50%` on `.world`**
+- **Background on `.scene`** — never on `.world`
+- **Scale and translate share one `onUpdate`** — both read from `cam` and write the composite transform string together; never split them across tweens that touch `world.style.transform` directly
+
+## Combinations
+
+- [multi-phase-camera.md](multi-phase-camera.md) — viewport-change inside one phase of a multi-phase camera
+- [coordinate-target-zoom.md](coordinate-target-zoom.md) — alternative for off-center zoom (nested wrappers, `T = -offset` form)
+- [sine-wave-loop.md](sine-wave-loop.md) — idle micro-drift after viewport settles
+
+## Pairs with HF skills
+
+- `/hyperframes-animation` — single tween writing composite transform
+- `/hyperframes-core` — composition wiring
+- `/hyperframes-cli` — `hyperframes lint`