ext/hyperframes
2
0
Fork 0
mirror of https://github.com/heygen-com/hyperframes.git synced 2026-09-11 06:30:03 +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/orbit-3d-entry.md
+90 -243
View File
@@ -7,295 +7,142 @@ metadata:
# Orbit with 3D Entry
Elements flip in from 3D space (rotateX + rotateY + translateZ) then transition into a continuous elliptical orbit around a focal point. Distinct from one-shot reveals — the orbit keeps running.
Elements flip in from 3D space (`rotateX` + `rotateY` + negative `z`) then settle into a continuous elliptical orbit around a center label. Distinct from one-shot reveals — the orbit keeps running, driven by a 0→1 progress tween INSIDE the timeline (never rAF).
## How It Works
Two phases per element:
Per element, two phases: (1) a `back.out` flip from a hidden 3D orientation to flat — **in place at its orbital starting position** (see Critical Constraints); (2) a continuous orbit where `onUpdate` computes `x/y` from `cos/sin(initialAngle + p·2π)` on the ellipse. The stage needs `perspective` on the scene root and `preserve-3d` on stage + items, or the flip flattens to a 2D scale.
1. **Entry (per element)**: GSAP tween from hidden 3D orientation (`rotateX`, `rotateY`, negative `z`) to flat (`rotateX: 0, rotateY: 0, z: 0`). Spring-like ease (`back.out`) for the flip-in.
2. **Orbit (after entry)**: Continuous trigonometric position around a center point. The element's `x` and `y` translate are driven by `cos(t)` and `sin(t)` at a slow angular speed.
The orbit runs **inside the timeline** — not via `requestAnimationFrame` — so HF seek-by-frame stays deterministic.
## HTML
## Recipe
```html
<div
class="scene"
id="orbit-scene"
data-composition-id="orbit-scene"
data-start="0"
data-duration="5"
data-track-index="0"
>
<div class="orbit-stage">
<div class="orbit-item" data-angle="0">{glyph1}</div>
<div class="orbit-item" data-angle="60">{glyph2}</div>
<div class="orbit-item" data-angle="120">{glyph3}</div>
<div class="orbit-item" data-angle="180">{glyph4}</div>
<div class="orbit-item" data-angle="240">{glyph5}</div>
<div class="orbit-item" data-angle="300">{glyph6}</div>
<div class="orbit-center">{centerLabel}</div>
</div>
<!-- inside a standard scene clip (hyperframes-core) -->
<div class="orbit-stage">
<div class="orbit-item" data-angle="0">{glyph1}</div>
<div class="orbit-item" data-angle="60">{glyph2}</div>
<!-- … evenly-spaced angles … -->
<div class="orbit-center">{centerLabel}</div>
</div>
```
## CSS
```css
.scene {
position: relative;
width: 100%;
height: 100%;
.scene-root {
display: grid;
place-items: center;
background: {sceneBackground};
perspective: 1800px; /* REQUIRED — without perspective, rotateX/Y flatten */
perspective: 1800px; /* REQUIRED */
}
.orbit-stage {
position: relative;
width: 1000px;
height: 700px;
display: grid;
place-items: center;
transform-style: preserve-3d;
}
.orbit-item {
position: absolute;
/* Items live at stage center; GSAP translates them along the orbit. */
top: 50%;
left: 50%;
width: 140px;
height: 140px;
display: grid;
place-items: center;
background: {accentColor};
border-radius: 50%;
font-family: {font};
font-weight: 900;
font-size: 64px;
color: {itemTextColor};
transform-style: preserve-3d;
will-change: transform;
box-shadow: 0 12px 36px {accentShadowColor};
}
.orbit-center {
position: relative;
z-index: 5;
font-family: {font};
font-weight: 900;
font-size: 96px;
letter-spacing: 8px;
color: {centerTextColor};
text-transform: uppercase;
transform: translateZ(220px); /* wins paint order inside preserve-3d */
z-index: 9999;
}
```
## GSAP Timeline
```js
const items = document.querySelectorAll(".orbit-item");
const RADIUS_Y = RADIUS_X * Y_TO_X_RATIO; // perspective-flattened ellipse
```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 });
items.forEach((el, i) => {
const a0 = (Number(el.dataset.angle) / 360) * Math.PI * 2;
const startX = Math.cos(a0) * RADIUS_X;
const startY = Math.sin(a0) * RADIUS_Y;
const items = document.querySelectorAll(".orbit-item");
// RADIUS_X, RADIUS_Y, ORBIT_DURATION, ENTRY_DUR, STAGGER, FLIP_BACK, CENTER_BACK
// — all named constants; values per "How to Choose Values" below.
const RADIUS_Y = RADIUS_X * Y_TO_X_RATIO; // perspective-flattened ellipse
items.forEach((el, i) => {
const initialAngleDeg = Number(el.dataset.angle);
const initialAngleRad = (initialAngleDeg / 360) * Math.PI * 2;
const startX = Math.cos(initialAngleRad) * RADIUS_X;
const startY = Math.sin(initialAngleRad) * RADIUS_Y;
// 1) Place at orbital position with opacity 0 — BEFORE any tween fires
gsap.set(el, {
xPercent: -50,
yPercent: -50,
x: startX,
y: startY,
rotateX: ROTATE_X_FROM,
rotateY: ROTATE_Y_FROM,
z: Z_FROM,
opacity: 0,
scale: SCALE_FROM,
});
// 2) Phase 1 — flip in IN PLACE at orbital position
tl.to(
el,
{
rotateX: 0,
rotateY: 0,
z: 0,
opacity: 1,
scale: 1,
duration: ENTRY_DUR,
ease: `back.out(${FLIP_BACK})`,
},
i * STAGGER,
);
// 3) Phase 2 — continuous orbit driven via a 0→1 progress tween
const orbitState = { p: 0 };
tl.to(
orbitState,
{
p: 1,
duration: ORBIT_DURATION,
ease: "none",
onUpdate: () => {
const angle = initialAngleRad + orbitState.p * Math.PI * 2;
const x = Math.cos(angle) * RADIUS_X;
const y = Math.sin(angle) * RADIUS_Y;
// z-index by orbit Y — see "Center label clearance" in Key Principles
// for the capped-range form when a center label is present.
el.style.zIndex = String(Math.round(y + RADIUS_Y));
el.style.transform = `translate(-50%, -50%) translate(${x}px, ${y}px)`;
},
},
i * STAGGER + ENTRY_DUR,
);
// 1) Park at the orbital position, hidden — BEFORE any tween fires
gsap.set(el, {
xPercent: -50,
yPercent: -50,
x: startX,
y: startY,
rotateX: ROTATE_X_FROM,
rotateY: ROTATE_Y_FROM,
z: Z_FROM,
opacity: 0,
scale: SCALE_FROM,
});
// Center label fades in once a few orbit items have landed
tl.from(
".orbit-center",
{ opacity: 0, scale: 0.6, duration: ENTRY_DUR, ease: `back.out(${CENTER_BACK})` },
CENTER_FADE_AT,
// 2) Flip in IN PLACE — rotation/opacity/scale only, never translate
tl.to(
el,
{
rotateX: 0,
rotateY: 0,
z: 0,
opacity: 1,
scale: 1,
duration: ENTRY_DUR,
ease: `back.out(${FLIP_BACK})`,
},
i * STAGGER,
);
window.__timelines["orbit-scene"] = tl;
</script>
```
// 3) Continuous orbit — each item gets its OWN progress tween (own initialAngle)
const orbit = { p: 0 };
tl.to(
orbit,
{
p: 1,
duration: ORBIT_DURATION,
ease: "none",
onUpdate: () => {
const a = a0 + orbit.p * Math.PI * 2;
const x = Math.cos(a) * RADIUS_X;
const y = Math.sin(a) * RADIUS_Y;
// capped z-index band [1, 50] — see center-label clearance below
el.style.zIndex = String(1 + Math.round(((y + RADIUS_Y) / (2 * RADIUS_Y)) * 49));
el.style.transform = `translate(-50%, -50%) translate(${x}px, ${y}px)`;
},
},
i * STAGGER + ENTRY_DUR,
);
});
## How to Choose Values
- **RADIUS_X** — horizontal radius of the orbit ellipse, in px
- Range: 300–900 px
- Effects: small radius reads as a tight cluster; large radius spreads the ring across the frame and lets a large center element breathe
- Constraints: must clear the center element horizontally at every angle — see Key Principles for the `RADIUS_X * min(|cos(θ)|) ≥ L_w + I_w + breathing_room` rule
- Reference: ../../examples/cta-orbit-collapse.html uses 480
- **Y_TO_X_RATIO** — `RADIUS_Y / RADIUS_X`, the orbit's perspective flattening
- Range: 0.4–0.7
- Effects: low values read as a near-horizontal disc seen from above; values approaching 1 read as a flat plane facing the camera
- Constraints: keep < 1 — the orbit should look like a tilted ring, not a frontal halo
- Reference: ../../examples/cta-orbit-collapse.html uses ≈ 0.58
- **ORBIT_DURATION** — seconds for one full revolution
- Range: 4–25 s (longer for ambient backdrop, shorter for active feature motion)
- Effects: short durations look frenetic; long durations read as drifting / calm
- Constraints: must be ≥ the time the orbit is on screen, otherwise the tween ends and items stop
- Reference: ../../examples/cta-orbit-collapse.html uses ~25 s effective (orbit speed 0.25 rad/s)
- **ENTRY_DUR** — per-element flip-in duration
- Range: 0.4–0.8 s
- Effects: short feels punchy; long feels stately
- Constraints: must be ≤ the gap between the first and last element's start so the cascade doesn't overlap to incoherence
- Reference: ../../examples/cta-orbit-collapse.html uses 0.55 s
- **STAGGER** — delay between consecutive element entries
- Range: 0.06–0.12 s
- Effects: below ~0.06 s reads as "popcorn"; above ~0.12 s reads as plodding
- Constraints: total cascade `(n - 1) * STAGGER` should still complete before the next scene phase begins
- Reference: ../../examples/cta-orbit-collapse.html uses 0.10 s
- **FLIP_BACK** — `back.out(<n>)` overshoot for the flip-in
- Range: 1.2–2.0
- Effects: low end is a soft arrive; high end snaps with visible overshoot
- Constraints: pair with a calmer `CENTER_BACK` if both fire close together — competing overshoots cancel each other
- Reference: ../../examples/cta-orbit-collapse.html uses 1.4
- **CENTER_BACK** — `back.out(<n>)` overshoot for the center label fade-in
- Range: 1.2–1.8
- Effects: low end keeps the label calm under the busy orbit; high end gives it a small "pop" of arrival
- Reference: ../../examples/cta-orbit-collapse.html uses 1.4
- **CENTER_FADE_AT** — when the center label fades in, in seconds
- Range: just after the first 2–4 elements have landed
- Effects: too early competes with the cascade; too late leaves a hole at the center of the orbit
- Reference: ../../examples/cta-orbit-collapse.html starts the center brand near the front of the scene
- **ROTATE_X_FROM / ROTATE_Y_FROM / Z_FROM / SCALE_FROM** — initial 3D orientation
- Range: rotateX ±60° to ±120°; rotateY ±45° to ±120°; z −200 to −400; scale 0.2–0.6
- Effects: higher absolute rotation + deeper negative z = more dramatic "card flipping out of depth"; lower = subtle reorientation
- Constraints: pick a direction consistent with the scene's perspective; mixing positive and negative rotateY across items reads as noise
- Reference: ../../examples/cta-orbit-collapse.html uses rotateX 90, rotateY −45, z −100, scale 0
## Variations
### Collapse to center
To reverse — orbit then collapse inward — interpolate `RADIUS_X` and `RADIUS_Y` to 0 in a final phase by multiplying both radii by a 1→0 driver:
```js
const collapse = { r: 1 };
tl.to(
collapse,
{
r: 0,
duration: COLLAPSE_DUR,
ease: "power3.inOut",
onUpdate: () =>
items.forEach((el) => {
const a = (Number(el.dataset.angle) / 360) * Math.PI * 2;
const x = Math.cos(a) * RADIUS_X * collapse.r;
const y = Math.sin(a) * RADIUS_Y * collapse.r;
el.style.transform = `translate(-50%,-50%) translate(${x}px,${y}px) scale(${collapse.r})`;
}),
},
COLLAPSE_AT,
tl.from(
".orbit-center",
{ opacity: 0, scale: 0.6, duration: ENTRY_DUR, ease: `back.out(${CENTER_BACK})` },
CENTER_FADE_AT,
);
```
### Tilted orbit plane
## Variations
For a more dramatic 3D orbit, rotate the entire `.orbit-stage` on the X axis:
- **Collapse to center**: a final 1→0 driver multiplies both radii (and item scale) in `onUpdate` — the ring condenses into the center element; pairs with a CTA "click" igniting the collapse.
- **Tilted orbit plane**: `rotateX(25deg)` on `.orbit-stage` — items visibly arc through the plane.
```css
.orbit-stage {
transform: rotateX(25deg);
}
```
## Values
Items rendered above/below the equator visually arc through the plane.
## Key Principles
- **`perspective` on scene root REQUIRED** — without it, rotateX/Y read as 2D scale and the flip-in looks flat
- **`transform-style: preserve-3d`** on both the stage and each item — preserves the 3D context as items have their own transforms
- **Stagger entries** — cascade reads as "swarm forming," simultaneous reads as "popcorn." See `STAGGER` in How to Choose Values
- **Element count 4-12** — fewer feels empty, more crowds the center
- **❗ Center label clearance — translateZ + capped item z-index** — `z-index` ALONE is unreliable inside a `transform-style: preserve-3d` stage (paint order follows Z position, not stacking-context z-index). For the orbit to NEVER occlude the headline:
1. Push the center label forward: `transform: translateZ(220px); z-index: 9999;`
2. Cap orbit-item dynamic z-index in `[1, 50]` so bottom-of-orbit items still read as "in front of" top-of-orbit items, but **never above the center label**. e.g.: `el.style.zIndex = String(1 + Math.round((y + RADIUS_Y) / (2 * RADIUS_Y) * 49));`
3. **Choose `RADIUS_X` so items also clear the center label HORIZONTALLY at all angles.** If the label's half-width is `L_w` and the item's half-width is `I_w`, then `RADIUS_X` must satisfy `RADIUS_X * min(|cos(θ_minimum)|) ≥ L_w + I_w + breathing_room`. For a 6-item orbit with 60° angular spacing, the worst case is `cos(30°) ≈ 0.866` between items. Scale `RADIUS_X` with the center label's width — a heavier wordmark needs a wider ring.
- **❗ Center element is the headline** — the orbit is ornamental motion around it. If the orbit dominates the eye, increase center element size or fade orbit items down
| token | range | notes |
| ----------------------- | ----------------------------- | ------------------------------------------------------------------- |
| RADIUS_X | 300–900px | must also clear the center label horizontally (see below) |
| Y_TO_X_RATIO | 0.4–0.7 | keep < 1 — a tilted ring, not a frontal halo |
| ORBIT_DURATION | 4–25s per revolution | ≥ time on screen, or the tween ends and items freeze |
| ENTRY_DUR | 0.4–0.8s | |
| STAGGER | 0.06–0.12s | below reads "popcorn", above reads plodding |
| FLIP_BACK / CENTER_BACK | 1.2–2.0 / 1.2–1.8 | calm the center pop if both fire close together |
| CENTER_FADE_AT | after 2–4 items land | too early competes; too late leaves a hole |
| ROTATE_X/Y_FROM, Z_FROM | ±60–120°, ±45–120°, −200…−400 | one consistent rotation direction across items; mixed signs = noise |
| SCALE_FROM | 0.2–0.6 | |
| item count | 4–12 | fewer feels empty, more crowds the center |
## Critical Constraints
- **No `requestAnimationFrame`** — orbit must run inside the timeline so HF seeks frame-by-frame deterministically
- **Timeline must be paused**: `gsap.timeline({ paused: true })`
- **Registry key = `data-composition-id`**
- **Each item gets its OWN orbit tween** — don't share one tween with `targets: '.orbit-item'` because each starts at a different `initialAngle`
- **`will-change: transform`** — many simultaneous orbital transforms benefit from compositor hints
- **Don't animate `left`/`top`** — use `translate()` (composes with `translate(-50%, -50%)` centering)
- **❗ Entry must flip IN PLACE at orbital position, NOT at center** — a fromTo whose "from" and "to" both have `x: 0, y: 0` keeps the item at the stage center during phase 1, so it collides with the center label during flip-in (and then snaps to orbit on phase 2 start — a visible teleport).
- **❗ Entry must flip IN PLACE at the orbital position, NOT at center** — `gsap.set` each item at `(cos(a0)·RADIUS_X, sin(a0)·RADIUS_Y)` with `opacity: 0` BEFORE adding tweens, then phase 1 animates only rotation/opacity/scale. A fromTo that keeps `x/y: 0` flips at the stage center, collides with the center label, then teleports to the orbit when phase 2 starts.
- **❗ Center-label clearance** — `z-index` alone is unreliable inside `preserve-3d` (paint order follows actual Z): push the label forward with `translateZ(220px)` + `z-index: 9999`, cap item z-index to `[1, 50]`, AND size the ring so items clear the label horizontally at every angle: `RADIUS_X × min|cos(θ)| ≥ L_w + I_w + breathing_room` (label/item half-widths; for 6 items the worst case is `cos(30°) ≈ 0.866`). A heavier wordmark needs a wider ring.
- **Each item gets its OWN orbit tween** — a shared `targets: ".orbit-item"` tween can't carry per-item `initialAngle`.
- **The center element is the headline** — the orbit is ornament; if it dominates, grow the center or fade the items down.
The correct pattern (see GSAP Timeline above) is to `gsap.set()` each item at `(cos(initialAngle)*RADIUS_X, sin(initialAngle)*RADIUS_Y)` with `opacity: 0` BEFORE adding tweens, then have phase 1 animate only rotation/opacity/scale — NOT translate. The item fades in IN PLACE at its orbital starting point, and phase 2 picks up the orbit smoothly from there.
## See also
## Combinations
- [center-outward-expansion.md](center-outward-expansion.md) — alternative entry pattern (burst, not orbit); also the reversed driver for an orbit-collapse finish
- [cursor-click-ripple.md](cursor-click-ripple.md) — pairs naturally when the center element is a CTA the user "clicks" to trigger the collapse
- [sine-wave-loop.md](sine-wave-loop.md) — per-item idle wobble layered on top of the orbit
## Pairs with HF skills
- `/hyperframes-animation` — timeline + `onUpdate` API
- `/hyperframes-core` — composition wiring
- `/hyperframes-cli` — `hyperframes lint`
`center-outward-expansion` (burst entry; reversed driver = the collapse finish) · `cursor-click-ripple` (the click that triggers a collapse) · `depth-scatter-assemble` (3D entrance that resolves flat instead of orbiting).