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

---
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`