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): product-launch-video skill + consolidate motion knowledge into hyperframes-animation (#1745)

Browse Source 
* feat(skills): product-launch-video + consolidate motion knowledge into hyperframes-animation

- Add the product-launch-video skill: shot-sequence architecture where each
  visual frame is a time-coded shot sequence picked from a blueprint menu and
  paced to the voiceover (anti-PowerPoint). Includes the frame-worker sub-agent,
  story/visual/motion-design references, and audio/captions/transitions/
  stage-assets/assemble-index scripts.
- Consolidate motion knowledge in hyperframes-animation as the single source of
  truth: promote the updated atomic rules (31 -> 36) and rename product-launch-
  video's archetypes into hyperframes-animation blueprints (13 -> 15, replacing
  the old set). product-launch-video, faceless-explainer, and pr-to-video now
  reference them via ../hyperframes-animation/{rules-index,blueprints-index}.md
  and the rules/blueprints dirs. Fixes the discrete-text-sequence broken links;
  blueprints no longer ship per-id runnable examples, so example references in
  the consumers were dropped.
- Default HeyGen TTS voice to Marcia (deterministic; was the API's first English
  voice, which drifts on catalog re-sort). Override with --voice.
- assemble-index pre-assembly frame guards: auto-repair a sub-comp root missing
  canvas dims; hard-fail on <video>/<audio> inside a sub-comp; hard-fail on a
  timed non-root element missing class="clip" or overlapping same-track clips.
- Lint/CLI: lint media inside sub-compositions as an error; stop false-positive
  caption layout/lint findings; contrast/layout-audit skip elements hidden by an
  invisible ancestor.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

* fix(skills): clear CodeQL alerts in assemble-index.mjs

- script/style blanking regex now matches closing tags with trailing
  whitespace (</script >, </style >) — js/bad-tag-filter (high).
- drop the existsSync precheck before reading/repairing a frame file; read
  directly and handle ENOENT, removing the check->write TOCTOU window —
  js/file-system-race (high).

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
This commit is contained in:
WaterrrForever
2026-06-27 02:51:35 +08:00
committed by GitHub
co-authored by Claude Opus 4.8
parent 413d8187fd
commit 05af482f22
67 changed files with 3838 additions and 3006 deletions
Download Patch File Download Diff File Expand all files Collapse all files
skills/hyperframes-animation/blueprints/cta-morph-press.md
+18 -173
View File
@@ -1,183 +1,28 @@
---
id: cta-morph-press
role: cta
duration_seconds: [4, 6]
phases: 4
visual_arc: hero-entrance → morph-swap → cursor-approach → press-react
uses_rules: [sine-wave-loop, scale-swap-transition, physics-press-reaction]
element_roles:
hero: Initial focal element (logo, brand lockup, product) that establishes presence then exits via shrink-fade
cta: Interactive target (button, card, link) that enters via bouncy scale-swap at the hero's position
cursor: Pointer that enters from off-screen along a spring path, then performs a physical click
when_to_use:
- Scene transitions from brand presence to a call-to-action
- Two elements occupy the same screen position sequentially (morph illusion)
- Simulated user interaction (cursor click) on the final element
- Hero should feel "alive" before transforming (breathing idle)
when_not_to_use:
- Hero and CTA coexist on screen — see brand-reveal-assemble-zoom
- CTA enters from off-screen — see takeover-ticker-displace
- No click interaction — use scale-swap-transition alone
- Multiple CTAs need sequential interaction
triggers:
[logo morphs into button, CTA animation, cursor clicks button, brand to action, morph transition]
---
# cta-morph-press — CTA Morph & Press
# CTA · Morph & Press (HyperFrames)
**intent**: A resting brand mark condenses at the same screen center into a smaller, brighter CTA, then a cursor arrives from off-stage and lands a human-aimed click on it. The viewer's eye is walked from "this is who we are" to "and this is what you do." The morph and the click are the two headline beats.
This is a "presence → action" arc: the hero establishes the brand for a beat or two — alive but resting, just a faint rotational breath on the logo — then condenses into a smaller, brighter CTA at the same screen center; a cursor arrives from off-stage and lands a physical click on it. The viewer's eye is moved from "this is who we are" to "and this is what you do."
**roles served**
Four phases on a single paused GSAP timeline. The morph (Phase 2) and the click (Phase 4) are the headline beats; Phases 1 and 3 are the setup and approach that make those beats legible.
- CTA (from `cta-morph-press`): when the close moves from brand identity to a single user action, two elements share the same center sequentially (a morph, not a cut), and the payoff is a simulated click with physical feedback. Reach for it for a focused "click here" sign-off — no spatial set, no multi-step UI (that's `cursor-ui-demo`).
## When to Use
**duration**: 4–6s
- Scene arc moves from brand identity to user action
- Two elements share the same screen center but appear sequentially (morph)
- Final beat is a simulated click interaction with physical feedback
- Hero needs subtle ambient motion before transformation
**shot structure** (a `[bg]` canvas; hero and CTA are flex-centered siblings sharing one `transform-origin`)
## Orchestration
- **Scene 1 (0.0–~1.4s) — presence.** The `[hero mark / brand lockup]` holds dead-center, alive but resting — only a faint rotational breath on the mark; any title text under it stays rock-stable. Camera static.
- **Scene 2 (~1.4–2.4s) — the morph (signature move).** The hero CONDENSES at the same screen center into a smaller, brighter `[CTA]` (button / card): the outgoing mark shrink-fades exactly as the CTA scales up in its place. Because they share one `transform-origin`, the eye reads it as one element transforming, not a swap.
- **Scene 3 (~2.4–3.4s) — approach.** A `[cursor]` arrives from off-stage on a **decelerating** path (it "arrives," it does not pass through) and lands a few px **off** the CTA's geometric center, so the aim reads human, not scripted.
- **Scene 4 (~3.4–end) — press.** The cursor lands a physical CLICK — cursor and CTA compress together in lockstep, then release with feedback (an optional ripple / glow bloom). Holds on the clicked state.
Each phase maps to one rule (or an inline pattern) — pick the variation that fits this scene's specific constraints, not the rule's default:
**motion vocabulary**: faint rotation-only resting breath (logo scope only); same-center morph-swap (shrink-fade ↔ scale-up sharing `transform-origin`); cursor decel-arrival from off-stage; off-center human aim; lockstep press compression; release feedback ripple / glow.
- **Phase 1 — hero entrance + breath**: inline `power3.out` fade-and-rise for the entrance, plus [sine-wave-loop](../rules/sine-wave-loop.md) in its **rotation-only, scope-restricted** variation. The rule's main form breathes scale + y on the entire focal element; here we deliberately apply it **only to `.hero-logo`**, not the whole hero. Reason: the hero's `scale` gets overwritten by the Phase 2 morph exit, and a scale-breath on the hero itself would fight that tween in the overlap. Rotation alone reads as alive, and scoping it to the logo keeps the title text rock-stable. Scale-breath below ~0.012 is under the perception threshold anyway — skip it without regret.
- **Phase 2 — morph swap**: use [scale-swap-transition](../rules/scale-swap-transition.md), but **without the rule's `inset: 0` card-in-fixed-wrap container**. Hero and CTA are flex-centered siblings here, not stacked cards. They still share `transform-origin: 50% 50%` (which is what actually sells the morph), but their footprint is governed by flex and intrinsic content size, not a `SWAP_WRAP_W × SWAP_WRAP_H` box. The CTA's `position: absolute` keeps it from displacing the hero in the document flow during the brief overlap. See "Phase 2 seam" below.
- **Phase 3 — cursor approach**: no rule — inline. [physics-press-reaction](../rules/physics-press-reaction.md) does include an APPROACH sub-phase, but its default lands the cursor dead-center on the button (`BUTTON_CENTER`) with `power2.inOut`. This scene wants a **`power2.out` deceleration from off-screen** (cursor "arrives" rather than "passes through"), and the landing point must be **a few px off the button's geometric center** so the click reads as human, not scripted. Cursor opacity also hard-cuts in via a near-zero-duration `fromTo` — see "Phase 3 seam."
- **Phase 4 — press + release**: use [physics-press-reaction](../rules/physics-press-reaction.md), but **only the PRESS_DOWN + RELEASE portion** — Phase 3 has already handled the APPROACH inline. The press fires with the rule's signature `["#cta", "#cursor"]` single-target-array tween so both elements compress in perfect lockstep. See "Phase 4 seam" for why we lean on GSAP's auto-overwrite rather than composing scales manually.
**rule mapping**
## Phase Timing
- hero → CTA condense at one center → `scale-swap-transition` (shared `transform-origin: 50% 50%` is what sells the morph; CTA `position: absolute` so it doesn't shove the hero during the brief overlap)
- resting-hero aliveness (rotation only, scoped to the mark so the Phase-2 scale doesn't fight it) → `sine-wave-loop` (low-amplitude rotation register — subtle jitter, not a scale breath)
- cursor press + release in lockstep (single-target-array so both compress together) → `physics-press-reaction` (PRESS_DOWN + RELEASE portion)
- cursor approach (decel from off-stage, off-center landing, hard-cut opacity in) → `gsap-effects` (translate on `power2.out`)
- click ripple / release glow → `cursor-click-ripple` (attack-decay ring) and/or `ambient-glow-bloom` (release bloom)
All boundaries are in seconds.
| Phase | Start ≥ | Internal duration | Notes |
| ----- | ----------------------------------- | ---------------------------------- | ------------------------------------------------------------ |
| 1 | `0.1–0.4s` (`INTRO_START`) | `INTRO_DUR` (0.35–0.7s) | Breath rotation runs from `t=0`, invisible until entry fades |
| 2 | `INTRO_START + INTRO_DUR + 1–2s` | `MORPH_EXIT_DUR` / `MORPH_ENT_DUR` | The 1–2s presence-dwell is the most important gap here |
| 3 | `MORPH_AT + MORPH_ENT_DUR + ~0.1s` | `CURSOR_PATH_DUR` (0.7–1.4s) | CTA's back.out tail must settle before the cursor enters |
| 4 | `CURSOR_ENTER_AT + CURSOR_PATH_DUR` | `CLICK_DOWN_DUR + CLICK_UP_DUR` | **Exactly equal**, not "greater than" — see Phase 3→4 seam |
The 1–2s **presence-dwell** between Phase 1 and Phase 2 is the gap that almost everyone gets wrong by making it too short. Morphing the hero away half a second after it lands robs the brand of any actual presence — the viewer registers the morph as the headline and forgets the hero ever existed. Dwell long enough that the breath rotation completes most of a cycle (so the viewer's eye notices the aliveness) before transforming.
The `~0.1s` between Phase 2 and Phase 3 is the same idea as brand-reveal's `back.out` settling gap: the CTA's overshoot is still oscillating fractionally for a few frames after its nominal duration, and a cursor entering during those frames "shakes the camera." Wait for the spring tail.
The `CLICK_DOWN_AT == CURSOR_ENTER_AT + CURSOR_PATH_DUR` constraint between Phase 3 and Phase 4 is **a strict equality, not a buffer**. The viewer perceives "cursor lands" and "button compresses" as a single causal event; any gap, even one frame, reads as the cursor pausing then clicking. Bind these two values to the same expression in code.
After the release, hold at least one full second of climax dwell (`TOTAL_DUR ≥ CLICK_UP_AT + CLICK_UP_DUR + 1s`) so the spring rebound is legible — otherwise the comp ends mid-overshoot and the press never quite "lands."
## Initial DOM Nesting
The relevant fact is that hero and CTA are **siblings sharing the same flex-centered viewport position**, not stacked `inset:0` cards as in `scale-swap-transition`'s default. The cursor is a third sibling living at scene-root level, free to translate anywhere.
```
.stage (flex; align/justify center; relative)
├── #hero
│ ├── .hero-text
│ └── .hero-logo ← Phase 1 breath target (rotation only)
├── #cta (position: absolute; z-index 10)
│ └── .cta-text ← reveals after container reaches recognizable scale
└── #cursor (position: absolute; z-index 100)
```
The CTA's `position: absolute` is essential — without it, the CTA would push the hero out of the flex layout the moment it materialises, and both elements would shift sideways instead of morphing in place. Hero stays in flow; CTA layers on top.
## Phase 1 Seam: Why Breath Lives on `.hero-logo`, Not `.hero`
The breath rotation uses the `onUpdate` form from [sine-wave-loop](../rules/sine-wave-loop.md) but written against `tl.time()` directly (not a phase-tween from 0 → 2π), and the target is **the logo sub-element only**. Three reasons stack here:
1. The Phase 2 morph exit tweens `#hero { scale: EXIT_SCALE }`. If the breath were also writing `scale` onto `#hero`, the two tweens would race and GSAP's auto-overwrite would silently drop one.
2. Scoping breath to the logo lets the hero's title text stay rigid — moving text reads as instability, not life.
3. Pure rotation at `±2–6°` is enough to communicate "alive but resting"; adding a sub-threshold scale-breath only complicates the morph exit math without adding perceptible motion.
This is a one-sentence variation of `sine-wave-loop` worth flagging: the rule's main example writes both scale and y; the rotation-only sub-element form is a real pattern but barely shown.
## Phase 2 Seam: Same Center, Different Container Topology
[scale-swap-transition](../rules/scale-swap-transition.md) assumes both swap targets share an `inset: 0` parent inside a fixed `SWAP_WRAP_W × SWAP_WRAP_H` wrap. This scene breaks that assumption because the hero is a typographic group whose intrinsic width depends on `{Brand}` — pre-locking a wrap size would either crop the brand or pad the CTA with dead space.
The substitute: both elements rely on the parent `.stage`'s `align-items: center; justify-content: center` for centering, and `#cta` is taken out of flow with `position: absolute` so its existence doesn't perturb the hero. Both still need `transform-origin: 50% 50%` (the rule's central principle), and `z-index: 10` on the CTA (above hero) so the hero's fade tail doesn't bleed through.
The morph reads as **condensation** only when `ctaTotalWidth < heroGroupWidth`. Inverted, the same scale-swap reads as expansion (small thing becoming big thing) which is the wrong narrative for "brand condenses into a focused action." `CTA_MAX_REL_HERO` (0.5–0.8) is the safety rail; values above 0.8 visibly invert the illusion. Measure both widths after `document.fonts.ready` if you want this guaranteed at render time.
Inside the CTA, the inner text reveals at `MORPH_AT + 0.17s` (or `~0.3 × MORPH_ENT_DUR`) **after** the container has scaled past the early micro-frames of the `back.out`. Revealing text during the early bounce makes it pop at micro-scale and look like a glitch.
## Phase 3 Seam: Cursor Entry — Hard-Cut Opacity, Offset Landing
Two scene-specific tricks the rule doesn't spell out:
**Hard-cut opacity.** Real cursors don't fade in — they're either there or not. Implement with a near-zero-duration `fromTo`:
```js
tl.fromTo(
"#cursor",
{ opacity: 0 },
{ opacity: 1, duration: HARD_CUT_DUR, ease: "none" },
CURSOR_ENTER_AT,
);
```
`HARD_CUT_DUR` lives in the 0.001–0.01s range — small enough to read as instant under HF's frame-stepped seek, but non-zero so it produces an actual step change in the seekable timeline rather than a `set()` that might be missed during a reverse seek.
**Offset landing, not dead-center.** The cursor's target is the button's center **plus** a small (`±30–150 px`) offset on both axes — typically a hair right and below. Real cursors land where eye + hand coordinate, which biases slightly toward the visible mass of the button rather than its geometric midpoint. Dead-center lands too perfectly and reads as scripted.
```js
const CURSOR_TARGET_X = W / 2 + CURSOR_TARGET_OFFSET_X_PX;
const CURSOR_TARGET_Y = H / 2 + CURSOR_TARGET_OFFSET_Y_PX;
```
`W` and `H` are the composition's `data-width` / `data-height`. The starting point lives `CURSOR_OFFSCREEN_X_PX / Y_PX` beyond `W` and `H` — far enough that the spring approach reads as inbound motion, not a teleport. Path duration sits at 0.7–1.4s; faster reads as urgent, slower as deliberate.
## Phase 4 Seam: Synchronized Press via Single Target Array
The press is the only place in this blueprint where two elements must move in literal lockstep. The mechanism that guarantees that is using a single GSAP target array:
```js
tl.to(
["#cta", "#cursor"],
{ scale: 1 - PRESS_INTENSITY, duration: CLICK_DOWN_DUR, ease: "power3.out" },
CLICK_DOWN_AT,
);
tl.to(["#cta", "#cursor"], { scale: 1.0, duration: CLICK_UP_DUR, ease: "power2.out" }, CLICK_UP_AT);
```
The temptation is to split this into per-element tweens with subtly different eases ("the cursor should feel slightly heavier than the button"). Don't. Any desync, even a few frames, breaks the illusion that the two are touching — the cursor floats off the button surface. One array, one ease, one duration, one start time.
By the time `CLICK_DOWN_AT` fires, the CTA's `back.out` entrance has long since settled at `scale: 1`. The press tween's `scale: 1 - PRESS_INTENSITY` overwrites cleanly via GSAP's `overwrite: "auto"`, and `scale: 1.0` overwrites back on release. No manual scale composition needed — that's only required when two tweens overlap in time, and here they don't.
## Key Values to Choose (Not Already in the Rules)
Only the parameters this blueprint introduces; for sizing ratios, eases, BOUNCE_FACTOR, PRESS_INTENSITY ranges, see the linked rules.
- **CTA_MAX_REL_HERO**: 0.5–0.8. Maximum ratio of CTA width to hero group width. Above 0.8 the morph inverts and reads as expansion — wrong narrative.
- **CURSOR_TARGET_OFFSET_X_PX / Y_PX**: ±30–150 px. Small non-zero offsets from viewport center for the cursor's landing point. Zero reads as scripted; ±200+ misses the button.
- **CURSOR_OFFSCREEN_X_PX / Y_PX**: 50–300 px beyond the composition edge. Cursor's starting position. Larger values make the approach more dramatic; too small and the cursor "pops in from the edge."
- **HARD_CUT_DUR**: 0.001–0.01s. Near-zero duration that creates a step change in opacity rather than a fade. Must be non-zero to survive frame-stepped seeking.
- **MORPH_FADE_DUR**: 25–40% of `MORPH_EXIT_DUR`. Hero's opacity fades faster than its scale shrinks, so it's gone before it lands at small scale (otherwise you see a tiny ghost-hero behind the CTA).
- **LOGO_ROT_AMP_DEG**: 2–6°. Breath rotation amplitude on the logo only. Bigger reads as a wobble; smaller is below the perception threshold.
## Critical Constraints (ordered by failure frequency)
- **`CLICK_DOWN_AT === CURSOR_ENTER_AT + CURSOR_PATH_DUR`** — exact equality, not "approximately." Bind these in code via the same expression. Any gap breaks the cursor-lands-and-clicks single-event perception.
- **Presence-dwell ≥ 1s before morph** — the most common mistake is making `MORPH_AT - (INTRO_START + INTRO_DUR)` too small. Without dwell, the hero never registers as the brand.
- **Single target array for the press** (`["#cta", "#cursor"]`, not two tweens) — desynced press = floating cursor = no contact illusion.
- **Cursor hard-cut, not fade** — a 0.4s fade-in cursor reads as a ghost; use `HARD_CUT_DUR` in the 0.001–0.01s range.
- **Breath rotation on `.hero-logo` only**, never on `#hero` — Phase 2's morph exit overwrites the hero's scale; breath on the same element would race.
- **CTA `position: absolute`** — without it, the appearing CTA shifts the hero out of flex flow at `MORPH_AT` and the morph "jumps sideways."
- **CTA z-index above hero** (`z-index: 10`) — hero's fade tail at opacity 0.3–0.5 will bleed through the popping CTA otherwise.
- **Cursor z-index above CTA** (`z-index: 100`) — during the press, the cursor must visibly sit on top of the button.
- **CTA total width < hero group width** (enforced by `CTA_MAX_REL_HERO`) — inverted ratios make the morph read as expansion, breaking the narrative.
- **Cursor landing offset from dead-center** — dead-center reads as scripted; ±30–150 px sells humanness.
- **`CLICK_UP_AT > CLICK_DOWN_AT + CLICK_DOWN_DUR`** — reversed timing inverts the press into a "lift-then-press" misplay.
- **Climax dwell ≥ 1s after release** — comps ending mid-spring rebound never feel like the press "landed."
## Spring → Ease Selection
Four distinct feels; the full mapping table lives in [hyperframes-animation/SKILL.md](../SKILL.md). This blueprint's defaults:
- Phase 1 hero entrance → `power3.out`; breath rotation → `onUpdate Math.sin`
- Phase 2 hero exit → `power3.out`; CTA pop-in → `back.out(BOUNCE_FACTOR)`
- Phase 3 cursor approach → `power2.out` (deceleration into landing)
- Phase 4 press down → `power3.out`; release → `power2.out`
## Golden Sample
- [cta-morph-press.html](../examples/cta-morph-press.html) — runnable four-phase composition on a single paused GSAP timeline. Run this before tuning values from scratch; most of the cursor-offset and dwell numbers are easier to dial in by changing constants than by deriving from text.
**camera modifier**: camera-static — the morph and click happen in element space; a camera move would compete with the click as the climax.