ext/hyperframes
2
0
Fork 0
mirror of https://github.com/heygen-com/hyperframes.git synced 2026-09-11 14:50:02 +00:00
Code Issues Packages Projects Releases Wiki Activity

feat(skills): c2v mining pass — 7 new blueprints, 10 new rules, compacted recipe corpus (#2680)

Browse Source 
* feat(skills): c2v mining pass over animation blueprints and rules

Compacts ~45 existing animation rules/blueprints into tighter recipe form
(net -3.4k lines) and adds 17 mined from the c2v corpus:

- 7 blueprints: agent-progress-theater, camera-journey, fixed-anchor-cycle,
  panel-edit-live-sync, prompt-type-submit-generate,
  transcript-scroll-artifact-reveal, zoom-out-workspace-reveal
- 10 rules: 3d-camera-flight, anchored-layout-expand, chart-scrub-readout,
  chromatic-glitch, control-target-sync, cursor-drag, gradient-text-sweep,
  multi-cursor-choreography, particle-burst, theme-crossfade-morph






Both indexes updated.

* feat(skills): sync product-launch script bank with mined blueprint roles

The role->blueprint script bank in product-launch-video/story-design.md is
kept 1:1 with blueprints-index role declarations, which the c2v mining pass
expanded. Adds the 25 missing entries (script-shape descriptor + example
lines + pattern): 13 for the 7 new blueprints, 12 for role widenings on 7
existing ones (cursor-ui-demo, dataviz-countup, titlecard-reveal, et al.),
and states the 1:1 sync contract in the bank's intro.

* docs(skills): cover constellation-hub scatter-drift variant in the script bank

Review follow-up on #2680: the SOCIAL_PROOF constellation-hub entry
patterned only the orbit shape; the c2v pass added a scatter-drift
end-card variant with the opposite geometry (no hub, no ring). Adds an
example line and extends the pattern so a scatter-drift beat's VO isn't
steered toward the orbit shape.
This commit is contained in:
WaterrrForever
2026-07-21 17:28:55 +08:00
committed by GitHub
parent 8f171433f9
commit 853256403b
68 changed files with 4911 additions and 8179 deletions
Download Patch File Download Diff File Expand all files Collapse all files
skills/hyperframes-animation/rules/viewport-change.md
+68 -269
View File
@@ -7,161 +7,74 @@ metadata:
# 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.
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) (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 intent → world transform. Camera **pans right** → world `translateX(-distance)`; camera **zooms in** → world `scale(>1)`; camera **follows element X** → world `translateX(viewportCenter - elementWorldX)` per-frame. Get the sign right or everything moves the wrong way. The single `.world` wrapper holds the camera transform; elements inside are positioned in world space, unchanged.
- 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:
**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, solve `S × offset + T = 0`:
```
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.
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). Mixing up the two forms drifts the target off-center as scale changes. Use this single-wrapper form when you want one source of truth for camera state (`cam.scale`, `cam.x`, `cam.y`) written via `onUpdate`; use nested wrappers when scale and translate can tween independently with shared ease.
## HTML
## Recipe
```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 class="world" id="world">
<div class="content">
<div class="hero">{Brand}</div>
<div class="tagline">{tagline}</div>
<div class="cta" id="cta">{ctaUrl}</div>
</div>
</div>
```
## CSS
```css
.scene {
position: relative;
width: 100%;
height: 100%;
overflow: hidden;
background: {bgGradient};
font-family: {font};
overflow: hidden; /* REQUIRED — any non-1.0 scale reveals edges or pushes content off-frame */
background: {bgGradient}; /* on .scene, NOT .world — a world-borne background warps with the camera */
}
.world {
position: absolute;
inset: 0;
display: grid;
place-items: center;
transform-origin: 50% 50%;
transform-origin: 50% 50%; /* centered scaling is what the math assumes */
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
```js
const world = document.getElementById("world");
```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 });
// Camera state — single source of truth. The world transform is composed from
// this object in ONE place 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(); // seed frame 0
const world = document.getElementById("world");
// Zoom in on the CTA: single-element composite transform → T = -offset × S.
// TARGET_OFFSET_Y is the target's measured offset from viewport center at
// neutral camera (sign matters — positive = below center).
const counterY = -TARGET_OFFSET_Y * TARGET_SCALE;
// 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>
tl.to(
cam,
{
scale: TARGET_SCALE,
y: counterY,
duration: ZOOM_DUR,
ease: "power3.inOut",
onUpdate: applyCamera,
},
ZOOM_START,
);
```
## Scale Value Guide
@@ -174,32 +87,34 @@ This is **different from [coordinate-target-zoom](coordinate-target-zoom.md)**,
| 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 |
Perception: < 5% scale change is imperceptible; 10-15% is comfortable emphasis; > 30% is cinematic/dramatic. For a natural product feel, prefer 1.05-1.15× over 2-3s; save big > 1.3× zooms for dramatic narrative moments.
### Extreme range — 4–12× outward (workspace reveal)
The same single-cam math runs far past the table: a zoom-out workspace reveal opens punched-in at **4–12×** on one detail (a single cell, message, or button) and pulls out to the full workspace in one continuous move. The mechanics don't change — one `cam` object, `T = -offset × S`, one `applyCamera()` writer — only the authoring direction does:
- **Build the workspace at its final (1×) layout and OPEN scaled-in** (`cam.scale = 8`, counter-translate aiming the opening detail; state it in a `fromTo` / seed via `applyCamera()` so a seek to t=0 lands punched-in). The wide landing frame is then everything at native design size — text crisp, raster assets at source resolution.
- **Never the inverse** — authoring the close-up at 1× and scaling the world down to 0.08–0.25 for the wide frame drops every label below legible pixel size and softens raster media; the reveal lands on mush.
- **Measure the opening target** — at S = 8, a 1 px error in the baked offset is 8 px on screen at the opening pose. Take the offset from the target's real laid-out center (`getBoundingClientRect` after `fonts.ready`, once at setup — the measuring doctrine in [coordinate-target-zoom.md](coordinate-target-zoom.md)), never from a layout formula.
- **The opening detail must survive ×S** — it renders at `S ×` its design size on the first frames (vector/DOM text is safe; raster needs `sourceResolution ≥ rendered × S`).
## 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:
- **Focus-lock (camera follows a moving cursor/character)** — keep the element at a fixed screen X by computing the world offset per-frame inside the driver's `onUpdate`:
```js
const focusEl = document.querySelector(".moving-cursor");
const targetScreenX = VIEWPORT_WIDTH * FOCUS_SCREEN_X_FRAC;
const targetScreenX = VIEWPORT_WIDTH * FOCUS_SCREEN_X_FRAC; // 0.4–0.7; 0.5 = dead center
const focusUpdate = { p: 0 };
tl.to(
focusUpdate,
{
p: 1,
duration: FOLLOW_DUR,
duration: FOLLOW_DUR, // matches how long the focused element is in motion
ease: "power2.inOut",
onUpdate: () => {
const rect = focusEl.getBoundingClientRect();
const focusWorldX = rect.left + rect.width / 2;
cam.x = targetScreenX - focusWorldX;
cam.x = targetScreenX - (rect.left + rect.width / 2);
applyCamera();
},
},
@@ -207,143 +122,27 @@ tl.to(
);
```
### Composite scale (multi-phase)
- **Composite scale (multi-phase)** — two proxy tweens multiplied through one writer: `cam.scale = scaleUp.v * scaleDown.v; applyCamera()`. Combine a slow push-in (~1.15) with a brief release (~0.9) for a breath/punch shape.
- **Camera mode transition (centered → follow)** — crossfade two camera modes via a 0→1 weight tween; intermediate frames interpolate between the modes' offsets.
Multiply two scale tweens for compound effects:
## Values
```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.
| token | range | notes |
| --------------- | ------------------------------------ | ------------------------------------------------------------------------------------------- |
| TARGET_OFFSET_Y | measured, not a free parameter | target's offset from viewport center at neutral camera; measure via `getBoundingClientRect` |
| TARGET_SCALE | 1.3× modest → 1.6–2.0× typical → 3×+ | raster media needs `sourceResolution ≥ rendered × TARGET_SCALE` |
| ZOOM_START | content landed + ~0.5s scan time | let the viewer read before the camera moves |
| ZOOM_DUR | 1.0–2.0s | under 0.8s teleports, over 2.5s drags |
| DWELL | ≥ 1.0s after the zoom settles | the viewer must be able to read the focal point (climax dwell) |
| VIEWPORT_WIDTH | = the root's `data-width` | real value, not abstract |
## 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
- **One `.world` wrapper carries the whole camera** — every scene element lives inside it; a second transformed wrapper is a second camera.
- **Single source of truth via the `cam` object + `applyCamera()`** — when scale and translate both change, write them in ONE place; never split them across tweens that touch `world.style.transform` directly (the transform string composition order becomes unpredictable).
- **Single-wrapper counter-translate is `T = -offset × S`** — don't import the nested-wrapper `T = -offset` formula.
- **`overflow: hidden` on `.scene`**; **`transform-origin: 50% 50%` on `.world`**; **background on `.scene`, never on `.world`**.
## Combinations
## See also
- [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`
[coordinate-target-zoom.md](coordinate-target-zoom.md) (nested-wrapper alternative, `T = -offset`) · [multi-phase-camera.md](multi-phase-camera.md) (viewport-change inside one phase) · [sine-wave-loop.md](sine-wave-loop.md) (idle micro-drift after the viewport settles).