mirror of
https://github.com/heygen-com/hyperframes.git
synced 2026-09-07 18:26:17 +00:00
Miguel Angel Simon Sierra
cf7c1d7609
Scaffolded projects' npm run check now invokes the single check command instead of chaining lint, validate, and inspect (three Chrome boots become one). The CLI skill, its correctness reference, the entry skill's capability map, README/docs catalog rows, the Mintlify CLI page (new check section, deprecation banner on inspect), template CLAUDE/AGENTS (byte-identical), root CLAUDE/AGENTS, and every creation-workflow skill that taught the old sequence all point at check. snapshot keeps its standalone sections; validate/inspect stay documented as deprecated aliases with their check equivalents.
41 lines
3.1 KiB
Markdown
41 lines
3.1 KiB
Markdown
# Motion-Graphics Builder
|
||
|
||
Turn `shot-plan.json` into one renderable HyperFrames composition (`compositions/index.html`). Everything stays in the HF ecosystem — HTML is the source of truth; a single **paused** GSAP timeline carries all motion; the engine seeks it. Category-specific build rules live in `categories/<id>/module.md`; this file is the shared contract.
|
||
|
||
## Reuse-first (the default)
|
||
|
||
Default = **compose existing catalog capabilities, not hand-author**:
|
||
|
||
- `npx hyperframes add <block>` (registry) → customize in place. Most blocks bake content/data into their own script (only a few expose CSS-var params), so reuse = **add + edit**.
|
||
- `hyperframes-animation` rules / blueprints / transitions for motion; runtime adapters (GSAP default).
|
||
|
||
Hand-author only (a) gaps no block/rule covers, (b) the `asset-fusion` affordance binding. The Director named the block(s) + customizations in `shot-plan.json` (`content.block` + `content.customize`); see `catalog-map.md`.
|
||
|
||
## The HF contract (non-negotiable)
|
||
|
||
- Root `#stage` carries `data-composition-id`, `data-start="0"`, `data-duration=<s>`, `data-fps`, `data-width`, `data-height`.
|
||
- Exactly ONE `gsap.timeline({ paused:true })`; register `window.__timelines["<id>"] = tl;`; end with `tl.seek(0)`. **Never `tl.play()`** for render-critical motion. No timers / async / event-driven timeline build. Finite repeats only.
|
||
- **Timed clips** need `class="clip"` + a stable `id`. Timeline-driven groups inside one full-duration clip don't each need timing attrs.
|
||
- **Fonts**: prefer local `@font-face` (.woff2) for deterministic / offline render; CDN Google Fonts do render (compiler caches + injects `@font-face`) but warn + need network.
|
||
- **Deterministic only** — no `Date.now()` / `Math.random()` / network.
|
||
|
||
## Layout before animation
|
||
|
||
Build the **hero-frame end-state** in CSS first (flex + padding; never absolute offsets on content containers; the root must be sized). Then `gsap.from()` entrances INTO it; exits via transitions or the final scene. Full rules: `references/builder-contract.md`.
|
||
|
||
## IR → composition
|
||
|
||
- `content.block` → `hyperframes add` it (or inline) + apply `content.customize`.
|
||
- per-category `content` (text scenes / chart data / fusion positions / news-tweet content) → realize per `categories/<id>/module.md`.
|
||
- resolved `asset_needs` → reference **frozen project-local paths** (never a remote URL or a prompt).
|
||
- `palette[-1]` / bg + `font` from the envelope.
|
||
- `export: alpha-overlay` → transparent bg; render `--format webm` (or `mov`).
|
||
|
||
## Critical correctness (GSAP / seek)
|
||
|
||
Opacity-gate delayed elements (set hidden until their entrance). Clamp at tween bounds (no overshoot past a held value). Allowed eases: `power1–4`, `back`, `bounce`, `circ`, `elastic`, `expo`, `sine` (`.in/.out/.inOut`). One motif per scene. Run `hyperframes check` for overflow / collisions.
|
||
|
||
## Verify-fix
|
||
|
||
`hyperframes lint` → `inspect` → `render -q draft`. On failure, fix the offending element + re-run. (Remotion-sourced prior art is graded by the `/remotion-to-hyperframes` SSIM harness.) **Never change a fixed `data-duration` during repair.**
|