hyperframes-core
byheygen-com· 46 skills
The HyperFrames composition contract — build one renderable project. Use for composition structure, the data-* timing attributes, class="clip", tracks, sub-compositions, variables, framework-owned media playback, deterministic-render rules, and validation. Also covers Tailwind projects and the STORYBOARD.md / SCRIPT.md plan formats. Read before writing composition HTML.
How to install hyperframes-core?
heygen-com/hyperframes/hyperframes-core
$npx -y skills add heygen-com/hyperframes --skill hyperframes-coreInstalls into the current project.
›Prefer a prompt? Paste this to your agent
Run `npx skills use "https://github.com/heygen-com/hyperframes" --skill "heygen-com/hyperframes/hyperframes-core"` and follow the generated skill instructions now. Read its complete output, redirecting it to a temporary file first if necessary. Resolve relative paths from the supporting-files directory it provides.
Use the skills in "https://github.com/heygen-com/hyperframes" that are relevant to the current task. Run `npx skills add "https://github.com/heygen-com/hyperframes"` and select the relevant skills, then follow their instructions.
SKILL.md
| 1 | # HyperFrames Core |
| 2 | |
| 3 | HyperFrames renders video from HTML. A composition is an HTML file whose DOM declares timing with `data-*` attributes, whose animation runtime is seekable, and whose media playback is owned by the framework. |
| 4 | |
| 5 | This skill is the **technical contract** — how to build one hyperframes project. The body below is the build guide; per-topic detail lives in `references/` (index next), read on demand. Other concerns live in the sibling domain skills — `hyperframes-animation`, `hyperframes-creative`, `media-use`, `hyperframes-cli`, `hyperframes-registry`. The capability map in `/hyperframes` says what each one covers. |
| 6 | |
| 7 | ## References |
| 8 | |
| 9 | | File | Read it to… | |
| 10 | | ------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | |
| 11 | | `references/minimal-composition.md` | start from the smallest renderable composition skeleton | |
| 12 | | `references/composition-patterns.md` | choose monolithic vs modular; structure a modular `index.html`; pick a sub-comp archetype | |
| 13 | | `references/data-attributes.md` | look up any `data-*` (root / clip / sub-comp host / legacy aliases); use `class="clip"` | |
| 14 | | `references/tracks-and-clips.md` | pick `data-track-index`, handle same-track overlap / z-index, time a clip relative to another | |
| 15 | | `references/sub-compositions.md` | wire a sub-composition (host attrs, `<template>`, per-instance vars) and animate inside it | |
| 16 | | `references/variables-and-media.md` | declare variables; place `<video>`/`<audio>`, set volume, trim | |
| 17 | | `references/determinism-rules.md` | build a seekable timeline; determinism bans; the animatable-property allowlist; layout / text fit | |
| 18 | | `references/full-screen-motion.md` | author full-frame motion with shared backgrounds | |
| 19 | | `references/storyboard-format.md` | author a `STORYBOARD.md` plan (+ the parsed manifest) | |
| 20 | | `references/review-loop.md` | run the plan → sketch → build review passes on a live board — shared by every storyboard-planning workflow | |
| 21 | | `references/production-loop.md` | take an approved plan to a delivered video — the stage dependencies (audio, frames, assembly, transitions, captions, verify, deliver) a freeform build follows directly | |
| 22 | | `references/brief-contract.md` | the brief's ground rules — mode derivation (collaborative / autonomous), shared field registry, question invariants (the asking itself lives in `/hyperframes` → the intent layer) | |
| 23 | | `references/brief-format.md` | author `BRIEF.md` — the confirmed intent document a workflow's Setup writes and every later step reads | |
| 24 | | `references/script-format.md` | author the optional `SCRIPT.md` locked narration | |
| 25 | | `references/subagent-dispatch.md` | map subagent dispatch verbs (parallel fan-out / background / wait) to your harness | |
| 26 | | `references/frame-worker-core.md` | the shared frame-worker role contract — each narrative workflow's packet builder prepends it to that workflow's `sub-agents/frame-worker.md` delta | |
| 27 | | `references/tailwind.md` | work in a Tailwind v4 project (`init --tailwind`; runtime contract differs from Studio's v3) | |
| 28 | |
| 29 | For animation runtime specifics (GSAP API, Lottie, Three.js, etc.) go to `hyperframes-animation` → `adapters/<runtime>.md`. |
| 30 | |
| 31 | ## Building a composition |
| 32 | |
| 33 | ### Two root forms (not interchangeable) |
| 34 | |
| 35 | - **Standalone** (top-level `index.html`) — root `<div data-composition-id="…">` sits directly in `<body>`, **no `<template>` wrapper** (wrapping it hides all content and breaks rendering). |
| 36 | - **Sub-composition** (loaded via `data-composition-src`) — root **must** be wrapped in `<template>`. |
| 37 | |
| 38 | > ⚠ Transport rule: the runtime **only clones `<template>` contents**; everything outside (incl. `<head>` styles/scripts) is discarded — put `<style>`/`<script>` **inside** the template. |
| 39 | > ⚠ Host-id rule: the host slot's `data-composition-id` must **exactly equal** the inner template's `data-composition-id` **and** the `window.__timelines["<id>"]` key — no `-mount`/`-slot`/`-host` suffix. |
| 40 | |
| 41 | File shape, host wiring, and the pre-render checklist → `references/sub-compositions.md`. |
| 42 | |
| 43 | ### Root must be sized (silent layout bug) |
| 44 | |
| 45 | The standalone root needs an explicit **sized box** (`width`/`height` in px), and every ancestor down to a `height:100%` element must have a resolved height — otherwise a flex/`100%` child collapses to ~0 and content piles into the top-left corner. Do not rely on automated gates alone to catch this; inspect a snapshot. Skeleton → `references/minimal-composition.md`. |
| 46 | |
| 47 | ### One paused timeline |
| 48 | |
| 49 | Each composition registers **exactly one** `gsap.timeline({ paused: true })` at `window.__timelines["<id>"]` (key = root `data-composition-id`), built **synchronously** at page load. Render duration = root `data-duration`, not timeline length. Don't manually nest sub-timelines into the host. Full contract (incl. non-GSAP runtimes) → `references/determinism-rules.md` + `hyperframes-animation/adapters/`. |
| 50 | |
| 51 | ### Non-negotiable rules (silent bugs automated gates may miss) |
| 52 | |
| 53 | Surfaced here; full rationale in the linked reference. Do not violate: |
| 54 | |
| 55 | - No render-time clocks / unseeded `Math.random` / network / input-state; no `repeat: -1` (use a finite count). → `determinism-rules.md` |
| 56 | - Animate only the visual-property allowlist; never tween `display` or raw `visibility`. GSAP `autoAlpha` and zero-duration timeline boundary sets are the only visibility exceptions, and only on non-clip elements or wrappers inside a clip. The framework alone controls `.clip` visibility. Do not `gsap.set` later-scene clips at page load. → `determinism-rules.md` |
| 57 | - No `<br>` in body text; transformed elements must be block-level + sized; pulsing absolute decoratives need peak clearance. → `determinism-rules.md` |
| 58 | - `<video>`/`<audio>` work at **any nesting depth** (including inside a sub-comp `<template>` or wrapper); the framework owns playback and seeks/decodes media wherever it lives. The one caveat is timelines, not placement: a sub-comp timeline can't animate host-root elements. → `variables-and-media.md` |
| 59 | - Every `id` must be unique across the **assembled** page; inside a sub-comp, prefix ids with the composition id (`#<id>-hero`). Duplicate `<video>`/`<img>` ids render **blank** — the producer injects frames by `getElementById`, and cross-file dupes slip past `lint`. → `composition-patterns.md` |
| 60 | - A full-screen scene fill goes on a full-bleed **child** (`position:absolute; inset:0`), never on the composition root itself — the producer's frame compositing can drop the root element's own `background` (the frame renders **black**) even though preview/`snapshot` show it correctly. → `composition-patterns.md` |
| 61 | |
| 62 | ## Editing existing compositions |
| 63 | |
| 64 | - Read the files first. Preserve unrelated timing, tracks, IDs, variables, media paths. |
| 65 | - Match existing composition IDs and timeline keys. |
| 66 | - Adding a clip: pick a non-overlapping `data-track-index` or adjust surrounding timing intentionally. |
| 67 | - `data-hidden` on any composition element hides it in BOTH preview and render, overriding its time window; it is non-destructive/reversible and toggled by Studio's timeline eye icon. |
| 68 | - Adding a sub-composition: verify its internal `data-composition-id` before wiring the host. |
| 69 | |
| 70 | ## Validation |
| 71 | |
| 72 | Use `hyperframes-cli` for command details |
| 73 | |
| 74 | - [ ] `npx hyperframes check` passes (0 findings across lint, runtime, layout, motion, and contrast) |
| 75 | - [ ] Projects with sub-compositions: `npx hyperframes snapshot --at <midpoints>` and eyeball each frame |
| 76 | - [ ] `npx hyperframes preview` for review (the user can edit anything in Studio's timeline) |
| 77 | - [ ] `npx hyperframes render` only after the user approves |
Related
6 picksType
- remotion-best-practicesRouter for all Remotion skillsJul 2026
- ai-image-generationGenerate AI images with GPT-Image-2, FLUX, Gemini, Grok, Seedream, Reve and 50+ models via inference.sh CLI.Jul 2026
- hyperframes-cliUse the HyperFrames CLI development loop: init, add, catalog, capture, lint, check, snapshot, compare, grade-compare, preview, play, present, beats, keyframes,…Jul 2026
- hyperframesMandatory entry point: read this first for any request to make, create, edit, animate, or render a video, animation, or motion graphic, including a promo,…Jul 2026
- remotion-to-hyperframesPort an existing Remotion (React) composition''s source to HyperFrames HTML.Jul 2026
- hyperframes-animationAll animation knowledge for HyperFrames — atomic motion rules, multi-phase scene blueprints, scene transitions, broader motion-design techniques, AND the seven…Jul 2026
