ext/hyperframes
2
0
Fork 0
mirror of https://github.com/heygen-com/hyperframes.git synced 2026-09-12 07:09:59 +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/avatar-cloud-network.md
+82 -308
View File
@@ -7,76 +7,29 @@ metadata:
# Avatar Cloud Network
Avatars arranged on an elliptical ring around a central element (logo / counter / brand). SVG dashed connection lines from center to each avatar. Staggered spring entry on avatars, then connection lines draw outward — communicates "community" or "social proof." Distinct from [orbit-3d-entry](orbit-3d-entry.md) (which continuously orbits) — avatar-cloud is a static composed reveal.
Avatars on an elliptical ring around a central hub (logo / counter), with SVG dashed lines drawing outward from the hub to each avatar — "community" / social proof. Distinct from [orbit-3d-entry.md](orbit-3d-entry.md) (continuous orbit): this settles into a static composed formation.
## How It Works
Three rendering layers:
Three layers: SVG lines (z-index 1, behind), avatars (z-index 2), hub (z-index 5 — lines terminate AT its edge, never pass through). Avatar positions and lines are built once at setup from ONE shared center; the timeline then runs hub fade → avatar cascade → outward line draw → breathing dwell. Drawing FROM the center is the narrative: "the hub connects to its community."
1. **SVG connection lines** (z-index 1, behind everything) — line from center hub to each avatar's position
2. **Avatars** (z-index 2) — `<div>` circles on elliptical positions
3. **Center hub** (z-index 5) — brand counter or logo (sits ABOVE the lines that converge on it)
Animation phases:
- `HUB_FADE_START → HUB_FADE_START + HUB_FADE_DUR`: hub fades in
- `AVATAR_ENTRY_START → AVATAR_ENTRY_START + (AVATAR_COUNT − 1) × AVATAR_STAGGER + AVATAR_ENTRY_DUR`: avatars cascade in
- `LINES_START → LINES_START + (AVATAR_COUNT − 1) × LINE_STAGGER + LINES_DUR`: connection lines draw outward
- climax dwell: optional idle breathing on avatars (see Variations / sine-wave-loop)
## HTML
## Recipe
```html
<div
class="scene"
id="cloud-scene"
data-composition-id="cloud-scene"
data-start="0"
data-duration="4"
data-track-index="0"
>
<!-- Connection lines layer -->
<svg class="lines" viewBox="0 0 1920 1080" xmlns="http://www.w3.org/2000/svg">
<!-- Lines injected by script — center to each avatar -->
</svg>
<!-- Avatars + center hub -->
<div class="hub-wrap">
<div class="hub" id="hub">
<div class="hub-num" id="hub-num">{counterValue}</div>
<div class="hub-label">{counterLabel}</div>
</div>
<!-- Avatars injected by script — AVATAR_COUNT around the ellipse -->
</div>
<div class="brand">{footerLine}</div>
<!-- inside a standard scene clip (hyperframes-core) -->
<svg class="lines" viewBox="0 0 1920 1080"><!-- lines injected --></svg>
<div class="hub-wrap">
<div class="hub">{counterValue} {counterLabel}</div>
<!-- avatars injected -->
</div>
```
Placeholder tokens:
- `{counterValue}` / `{counterLabel}` — the hub copy (numeric proof + category)
- `{footerLine}` — optional attribution line under the cloud
- `{avatar[i]}` — per-avatar image source (or emoji glyph if using the emoji variation below)
## CSS
```css
.scene {
position: relative;
width: 100%;
height: 100%;
background: {bgColor};
font-family: {font};
overflow: hidden;
}
.lines {
position: absolute;
inset: 0;
width: 100%;
height: 100%;
pointer-events: none;
z-index: 1;
pointer-events: none;
}
.hub-wrap {
position: absolute;
@@ -87,285 +40,106 @@ Placeholder tokens:
.hub {
position: relative;
z-index: 5;
display: flex;
flex-direction: column;
align-items: center;
gap: 12px;
padding: 48px 64px;
border-radius: 28px;
background: {hubBg};
border: 1px solid {hubBorder};
}
.hub-num {
font-size: HUB_NUM_FONT_SIZE;
font-weight: 900;
color: {textColor};
letter-spacing: -4px;
line-height: 1;
font-variant-numeric: tabular-nums;
}
.hub-label {
font-size: HUB_LABEL_FONT_SIZE;
font-weight: 800;
letter-spacing: 12px;
color: {accentColor};
text-transform: uppercase;
}
.avatar {
position: absolute;
z-index: 2;
width: AVATAR_SIZE;
height: AVATAR_SIZE;
border-radius: 50%;
border: 3px solid {avatarBorder};
box-shadow:
0 12px 32px rgba(0, 0, 0, 0.5),
0 0 24px {avatarGlow};
display: grid;
place-items: center;
font-size: AVATAR_GLYPH_SIZE;
background: {avatarBg};
transform: translate(-50%, -50%); /* centers on the (left, top) the script sets */
will-change: transform, opacity;
/* Top-left positioned by script; transform centers via -50% trick */
transform: translate(-50%, -50%);
}
.brand {
position: absolute;
bottom: 80px;
left: 50%;
transform: translateX(-50%);
font-size: BRAND_FONT_SIZE;
font-weight: 900;
letter-spacing: 14px;
color: {accentColor};
text-transform: uppercase;
}
```
## GSAP Timeline
```js
// CENTER_X/Y must equal the hub's RENDERED center exactly — every avatar
// position and line endpoint derives from it. For a place-items:center hub on
// a 1920×1080 canvas: (W/2, H × CENTER_Y_FACTOR).
const C = { x: CENTER_X, y: CENTER_Y };
const wrap = document.querySelector(".hub-wrap");
const svg = document.querySelector(".lines");
```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 });
for (let i = 0; i < AVATAR_COUNT; i++) {
const a = (i / AVATAR_COUNT) * Math.PI * 2 - Math.PI / 2; // start at top
const x = C.x + Math.cos(a) * RADIUS_X;
const y = C.y + Math.sin(a) * RADIUS_Y;
// CENTER_X / CENTER_Y must match the hub's rendered center exactly.
// For a hub-wrap with place-items:center on a 1920×1080 canvas these are
// (compositionWidth/2, compositionHeight × CENTER_Y_FACTOR).
const SCREEN_CENTER = { x: CENTER_X, y: CENTER_Y };
const av = document.createElement("div");
av.className = "avatar"; // assign image / glyph from authoring data
av.style.left = `${x}px`;
av.style.top = `${y}px`;
wrap.appendChild(av);
const hubWrap = document.querySelector(".hub-wrap");
const linesSvg = document.querySelector(".lines");
const line = document.createElementNS("http://www.w3.org/2000/svg", "line");
const attrs = {
x1: C.x,
y1: C.y,
x2: x,
y2: y,
stroke: "{lineColor}",
"stroke-dasharray": "6 8",
};
Object.entries(attrs).forEach(([k, v]) => line.setAttribute(k, String(v)));
const len = Math.hypot(x - C.x, y - C.y); // straight line — Math.hypot, not getTotalLength()
line.style.strokeDashoffset = String(len);
svg.appendChild(line);
}
// Build avatars + lines
const avatarPositions = [];
for (let i = 0; i < AVATAR_COUNT; i++) {
const angle = (i / AVATAR_COUNT) * Math.PI * 2 - Math.PI / 2; // start at top
const x = SCREEN_CENTER.x + Math.cos(angle) * RADIUS_X;
const y = SCREEN_CENTER.y + Math.sin(angle) * RADIUS_Y;
avatarPositions.push({ x, y, angle });
tl.from(".hub", { opacity: 0, scale: 0.8, duration: HUB_DUR, ease: `back.out(${HUB_BOUNCE})` }, 0);
// Avatar
const av = document.createElement("div");
av.className = "avatar";
av.style.left = `${x}px`;
av.style.top = `${y}px`;
// assign avatar image / glyph from your authoring data (see {avatar[i]})
hubWrap.appendChild(av);
// Line from hub to avatar
const line = document.createElementNS("http://www.w3.org/2000/svg", "line");
line.setAttribute("x1", SCREEN_CENTER.x);
line.setAttribute("y1", SCREEN_CENTER.y);
line.setAttribute("x2", x);
line.setAttribute("y2", y);
line.setAttribute("stroke", "{lineColor}");
line.setAttribute("stroke-width", "2");
line.setAttribute("stroke-dasharray", "6 8");
const len = Math.hypot(x - SCREEN_CENTER.x, y - SCREEN_CENTER.y);
line.style.strokeDashoffset = String(len);
line.dataset.length = String(len);
line.dataset.index = String(i);
linesSvg.appendChild(line);
}
// Phase 1 — hub fade in
const avatars = document.querySelectorAll(".avatar");
avatars.forEach((av, i) => {
tl.from(
".hub",
{ opacity: 0, scale: 0.8, duration: HUB_FADE_DUR, ease: `back.out(${HUB_BOUNCE})` },
HUB_FADE_START,
av,
{ opacity: 0, scale: 0, duration: AVATAR_DUR, ease: `back.out(${AVATAR_BOUNCE})` },
AVATAR_AT + i * AVATAR_STAGGER,
);
// Phase 2 — avatars cascade-in (staggered spring)
const avatars = document.querySelectorAll(".avatar");
avatars.forEach((av, i) => {
tl.from(
av,
{
opacity: 0,
scale: 0,
duration: AVATAR_ENTRY_DUR,
ease: `back.out(${AVATAR_BOUNCE})`,
},
AVATAR_ENTRY_START + i * AVATAR_STAGGER,
);
});
// Phase 3 — connection lines draw outward (staggered) — starts after most avatars land
const lines = linesSvg.querySelectorAll("line");
lines.forEach((line, i) => {
tl.to(
line,
{
strokeDashoffset: 0,
duration: LINES_DUR,
ease: "power2.out",
},
LINES_START + i * LINE_STAGGER,
);
});
// Phase 4 — climax dwell (network fully formed), idle breathing on avatars
// (see sine-wave-loop.md for the multiplicative onUpdate form)
const breathDriver = { p: 0 };
});
svg.querySelectorAll("line").forEach((line, i) => {
tl.to(
breathDriver,
{
p: Math.PI * 2 * BREATH_CYCLES,
duration: BREATH_DUR,
ease: "none",
onUpdate: () => {
avatars.forEach((av, i) => {
const phase = breathDriver.p + (i / avatars.length) * Math.PI * 2;
const s = 1 + Math.sin(phase) * BREATH_AMP;
av.style.transform = `translate(-50%, -50%) scale(${s})`;
});
},
},
BREATH_START,
line,
{ strokeDashoffset: 0, duration: LINE_DUR, ease: "power2.out" },
LINES_AT + i * LINE_STAGGER,
);
});
window.__timelines["cloud-scene"] = tl;
</script>
// Climax dwell — out-of-phase breathing holds the eye on the formed network:
// one phase proxy (0 → 2π·BREATH_CYCLES, ease "none"); onUpdate scales avatar i by
// 1 + sin(p + (i/n)·2π) · BREATH_AMP — sine-wave-loop's multiplicative onUpdate form.
// Keep the -50% centering in the same transform write.
```
## How to Choose Values
### Geometry
- **CENTER_X / CENTER_Y** — px coordinates of the hub center; lines and avatar positions derive from these.
- Constraints: **must equal the hub's actual rendered center** — when this rule is composed with another scene (e.g. a logo that has been recentered), `CENTER_X / CENTER_Y` must be baked from the same source as the hub's final position
- Reference: ../../examples/proof-logo-chain.html uses `(W/2, H × 0.47)` so the cloud sits slightly above the canvas midline
- **RADIUS_X / RADIUS_Y** — ellipse radii in px (RADIUS_X ≥ RADIUS_Y reads as perspective).
- Range: `RADIUS_X` ~ 20-30% of viewport width; `RADIUS_Y` ~ 18-25% of viewport height
- Constraints: `RADIUS_X / RADIUS_Y` ratio between 1.5 and 3.0 reads as natural depth; ratio = 1 (circle) reads as a flat 2D layout
- Reference: ../../examples/proof-logo-chain.html uses `W * 0.25` (`480px`) and `H * 0.22` (`237.6px`)
- **AVATAR_COUNT** — number of avatars distributed around the ring.
- Range: 8-12; fewer feels sparse, more clutters the ellipse
- Reference: ../../examples/proof-logo-chain.html uses `10`
- **AVATAR_SIZE / AVATAR_GLYPH_SIZE** — px diameter of each avatar circle and (optional) inner glyph size.
- Range: `AVATAR_SIZE` ~ 80-120 px at 1920 wide; small enough that 10+ avatars fit the ring without overlap
- **HUB_NUM_FONT_SIZE / HUB_LABEL_FONT_SIZE / BRAND_FONT_SIZE** — hub typography.
- Constraints: hub-num is the focal beat, sized 2-4× the label
### Hub fade
- **HUB_FADE_START** — when the hub fades in.
- Range: usually `0` (the hub establishes the focal point); offset if the scene precedes with another beat
- **HUB_FADE_DUR** — hub fade-in duration.
- Range: 0.4-0.6s
- **HUB_BOUNCE** — `back.out(HUB_BOUNCE)` coefficient on the hub's scale entry.
- Range: 1.4 (subtle) → 1.8 (firm)
### Avatar cascade
- **AVATAR_ENTRY_START** — when the first avatar pops in.
- Constraints: `≥ HUB_FADE_START + HUB_FADE_DUR × 0.6` so the hub is established before satellites arrive
- **AVATAR_ENTRY_DUR** — per-avatar scale-up duration.
- Range: 0.4-0.7s
- **AVATAR_STAGGER** — delay between consecutive avatar entries.
- Range: 0.06-0.10s; cascade reads as "joining"; simultaneous reads as "all already there"
- **AVATAR_BOUNCE** — `back.out(AVATAR_BOUNCE)` coefficient on each avatar's pop.
- Range: 1.4 (gentle) → 1.8 (firm); slightly firmer than hub for differentiation
### Connection lines
- **LINES_START** — when the lines begin drawing outward.
- Constraints: `LINES_START + (AVATAR_COUNT − 1) × LINE_STAGGER` should overlap the last avatar's settle by ~0.1-0.2s so the drawing reads as a consequence of the avatars landing
- **LINES_DUR** — per-line draw duration (strokeDashoffset → 0).
- Range: 0.4-0.7s
- **LINE_STAGGER** — delay between consecutive lines starting.
- Range: 0.02-0.05s; tight stagger reads as a wave outward
### Idle breathing
- **BREATH_START** — when idle breathing activates.
- Constraints: `≥ LINES_START + (AVATAR_COUNT − 1) × LINE_STAGGER + LINES_DUR + ~0.2s` (let the lines settle)
- **BREATH_DUR** — total duration of the breathing tween.
- Range: fills the remaining composition window
- **BREATH_CYCLES** — number of full sine cycles across `BREATH_DUR`.
- Range: 1.0-2.0; under 1 reads as a single sigh, over 2 starts to look anxious
- **BREATH_AMP** — sine amplitude on scale (multiplicative).
- Range: 0.02-0.06; smaller for headshots, larger for stylized glyphs
### Color tokens
- **{bgColor}** — stage background (typically a dark gradient so the cloud reads as a constellation)
- **{textColor}** — hub-num color (primary copy)
- **{accentColor}** — hub-label + footer (the brand voice)
- **{hubBg} / {hubBorder}** — hub card surfaces; gradient + 1px border reads as elevated
- **{avatarBg} / {avatarBorder} / {avatarGlow}** — avatar circle styling; soft border + glow keeps them legible on dark backgrounds
- **{lineColor}** — SVG stroke color (translucent accent reads as networky)
- **{font}** — base typography stack
## Variations
### Avatar size variation (organic feel)
- **Size variety**: vary avatar sizes by a small index-keyed array so the ring doesn't read rigidly repetitive.
- **Solid lines**: drop the dash + draw; lines fade in via opacity — more corporate, less networky.
- **Multi-orbit**: inner ring (fewer, larger) connected to the hub; outer ring is an unconnected "halo."
- **Glyph avatars**: flags / emoji / icons instead of faces — reads "global community" or role spread.
Vary avatar sizes by index — e.g. a small index-keyed array of sizes — so the ring doesn't read as rigidly repetitive.
## Values
### Solid lines instead of dashed
| token | range | notes |
| -------------- | ---------------------------- | ---------------------------------------------------------------- |
| AVATAR_COUNT | 8–12 | fewer feels sparse; more clutters the ellipse |
| RADIUS_X / \_Y | ~20–30% W / ~18–25% H | ratio X/Y 1.5–3.0 reads as perspective; 1 (circle) reads flat |
| avatar size | 80–120px @1920 | ring must fit 10+ without overlap |
| HUB_DUR | 0.4–0.6s | HUB_BOUNCE 1.4–1.8 |
| AVATAR_AT | ≥ 0.6 × HUB_DUR | hub established before satellites arrive |
| AVATAR_DUR | 0.4–0.7s | AVATAR_BOUNCE 1.4–1.8, slightly firmer than hub |
| AVATAR_STAGGER | 0.06–0.10s | cascade reads "joining"; simultaneous reads "already there" |
| LINES_AT | overlaps last avatar settle | start ~0.1–0.2s before it — draw reads as consequence of landing |
| LINE_DUR | 0.4–0.7s | LINE_STAGGER 0.02–0.05s = a wave outward |
| BREATH_CYCLES | 1.0–2.0 over the remaining s | under 1 = single sigh; over 2 = anxious. BREATH_AMP 0.02–0.06 |
Drop `stroke-dasharray` and use a solid stroke. Drop the dash-draw animation; lines fade in via opacity instead. More corporate, less networky.
### Multi-orbit (concentric rings)
Two layers of avatars: smaller inner ring (fewer avatars, slightly larger size), larger outer ring (more, smaller). Lines connect ONLY inner ring to hub; outer ring is a "halo."
### Country / role glyphs (geographic or persona spread)
Replace face images with flags / emoji / iconography. Reads as "global community" or "diverse roles."
## Key Principles
- **Hub above lines (`z-index: 5` vs lines `z-index: 1`)** — lines should appear to terminate AT the hub edge, not pass through. Hub must be in front.
- **Lines drawn outward (dash offset 0)** — drawing FROM center is the visual narrative: "the hub connects to its community."
- **8-12 avatars** — fewer feels sparse, more clutters the ellipse.
- **`RADIUS_X > RADIUS_Y`** — horizontal ellipse reads as perspective; equal radii (circle) reads as 2D flat layout.
- **Avatar entry stagger 0.06-0.10s** — cascade reads as "joining"; simultaneous reads as "all already there."
- **Stagger lines AFTER avatars are mostly settled** — line draw starts ~0.1-0.2s before last avatar settles for overlap.
- **Idle breathing post-formation** — each avatar slightly out-of-phase. Holds the eye during climax dwell.
- **❗ Climax dwell ≥1s** — after lines complete, hold for ≥1s so the formed network is readable.
Tokens: dark `{bgColor}` so the cloud reads as a constellation; translucent accent `{lineColor}`; soft border + glow keeps avatars legible on dark.
## Critical Constraints
- **Timeline must be paused**: `gsap.timeline({ paused: true })`
- **Registry key = `data-composition-id`**
- **No CSS animation** on avatars or lines
- **`will-change: transform, opacity`** on avatars
- **SVG `pointer-events: none`** — decorative overlay
- **`getTotalLength()` not needed for straight lines** — use `Math.hypot` for line length (cheaper, exact)
- **Hub `z-index` > lines z-index** — explicit layering
- **CENTER_X/Y must match the hub's actual rendered center** — when composed with another scene (e.g. a recentered logo), bake them from the same source as the hub's final position, or lines visibly miss the hub.
- **Hub z-index above lines** — lines terminate at the hub edge, never cross it.
- **Lines draw outward** (dashoffset len → 0), starting after avatars are mostly settled.
- **`RADIUS_X > RADIUS_Y`** — a horizontal ellipse reads as perspective; a circle reads flat.
- **Climax dwell ≥ 1s** after lines complete so the formed network is readable.
- Straight lines: `Math.hypot` for length — `getTotalLength()` not needed.
## Combinations
## See also
- [counting-dynamic-scale.md](counting-dynamic-scale.md) — the hub IS a growing counter
- [sine-wave-loop.md](sine-wave-loop.md) — avatar idle breathing pattern
- [3d-text-depth-layers.md](3d-text-depth-layers.md) — hub label with depth layers
## Pairs with HF skills
- `/hyperframes-animation` — staggered spring entries + SVG dash draw
- `/hyperframes-core` — composition wiring
- `/hyperframes-cli` — `hyperframes lint`
`counting-dynamic-scale` (the hub IS a growing counter) · `sine-wave-loop` (the breathing form) · `orbit-3d-entry` (the continuously-orbiting cousin).