Skill

Review

Audit score 70

hyperframes-core

heygen-com/hyperframes

Technical contract for building HyperFrames compositions—HTML-based video with seekable timing and framework-owned media.

Source View on skills.sh

What is hyperframes-core?

HyperFrames Core defines how to structure an HTML composition for video rendering, including timing attributes, clip management, sub-compositions, and deterministic animation rules. Use this before writing any composition HTML to understand the contract and avoid silent bugs.

Declare composition timing and clip scheduling with data-* attributes and class="clip"
Manage tracks, z-index, and overlapping clips with data-track-index
Wire sub-compositions with host attributes, templates, and per-instance variables
Place and control video/audio playback owned by the framework
Build seekable, deterministic timelines with GSAP or other animation runtimes
Validate compositions with lint, validate, inspect, snapshot, and preview commands

How to install hyperframes-core

npx skills add https://github.com/heygen-com/hyperframes --skill hyperframes-core

Prerequisites

HyperFrames CLI installed (npx hyperframes)
Basic HTML/CSS knowledge
Understanding of GSAP timelines or other supported animation runtimes

Claude Code

Cursor

Windsurf

Cline

How to use hyperframes-core

1.Read references/minimal-composition.md to start with a skeleton
2.Choose monolithic vs modular structure in references/composition-patterns.md
3.Declare timing with data-* attributes per references/data-attributes.md
4.Manage tracks and clips using references/tracks-and-clips.md
5.Wire sub-compositions if needed via references/sub-compositions.md
6.Place media and variables per references/variables-and-media.md
7.Follow determinism rules in references/determinism-rules.md to avoid silent bugs
8.Run npx hyperframes lint, validate, inspect, snapshot, and preview before rendering

Use cases

Good for

Structure a standalone composition with sized root, paused timeline, and clip hierarchy
Modularize a complex video by composing sub-compositions with shared variables
Add clips to existing compositions while preserving timing and track layout
Verify composition validity before rendering to video frames
Debug layout and animation issues using snapshot and preview tools

Who it's for

Video composition developers building with HyperFrames
Agents authoring or editing HTML-based video projects
Teams maintaining modular composition libraries
Developers integrating HyperFrames into custom rendering pipelines

hyperframes-core FAQ

What is the difference between standalone and sub-composition forms?

Standalone compositions have a root <div data-composition-id="…"> directly in <body> with no <template> wrapper. Sub-compositions must wrap the root in <template> because the runtime only clones template contents; everything outside (styles, scripts) is discarded.

Why does my composition render with content piled in the top-left corner?

The root element must have an explicit sized box (width/height in px), and every ancestor down to a height:100% element must have a resolved height. Flex/100% children collapse to ~0 without this. lint/validate/inspect do not catch this—check manually.

Can I use repeat: -1 or Math.random() in my timeline?

No. Compositions must be deterministic and seekable. Banned: render-time clocks, unseeded Math.random, network calls, input state, and repeat: -1. Use finite repeat counts instead.

Where should I place <video> and <audio> elements?

They must be direct children of the host root, never inside a sub-composition template or wrapper. The framework owns all media playback.

What happens if I have duplicate IDs across sub-compositions?

Every ID must be unique across the assembled page. Inside a sub-comp, prefix IDs with the composition ID (e.g., #<id>-hero). Duplicate <video>/<img> IDs render blank because the producer injects frames by getElementById.

Full instructions (SKILL.md)

Source of truth, from heygen-com/hyperframes.

name: hyperframes-core description: 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. Read before writing composition HTML.

HyperFrames Core

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.

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, hyperframes-media, hyperframes-cli, hyperframes-registry. The capability map in /hyperframes says what each one covers.

References

File	Read it to…
`references/minimal-composition.md`	start from the smallest renderable composition skeleton
`references/composition-patterns.md`	choose monolithic vs modular; structure a modular `index.html`; pick a sub-comp archetype
`references/data-attributes.md`	look up any `data-*` (root / clip / sub-comp host / legacy aliases); use `class="clip"`
`references/tracks-and-clips.md`	pick `data-track-index`, handle same-track overlap / z-index, time a clip relative to another
`references/sub-compositions.md`	wire a sub-composition (host attrs, `<template>`, per-instance vars) and animate inside it
`references/variables-and-media.md`	declare variables; place `<video>`/`<audio>`, set volume, trim
`references/determinism-rules.md`	build a seekable timeline; determinism bans; the animatable-property allowlist; layout / text fit
`references/full-screen-motion.md`	author full-frame motion with shared backgrounds
`references/storyboard-format.md`	author a `STORYBOARD.md` plan (+ the parsed manifest)
`references/script-format.md`	author the optional `SCRIPT.md` locked narration
`references/subagent-dispatch.md`	map subagent dispatch verbs (parallel fan-out / background / wait) to your harness
`references/tailwind.md`	work in a Tailwind v4 project (`init --tailwind`; runtime contract differs from Studio's v3)

For animation runtime specifics (GSAP API, Lottie, Three.js, etc.) go to hyperframes-animation → adapters/<runtime>.md.

Building a composition

Two root forms (not interchangeable)

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).
Sub-composition (loaded via data-composition-src) — root must be wrapped in <template>.

⚠ Transport rule: the runtime only clones <template> contents; everything outside (incl. <head> styles/scripts) is discarded — put <style>/<script> inside the template. ⚠ 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.

File shape, host wiring, and the pre-render checklist → references/sub-compositions.md.

Root must be sized (silent layout bug)

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. lint/validate/inspect do not catch this. Skeleton → references/minimal-composition.md.

One paused timeline

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/.

Non-negotiable rules (silent bugs `lint`/`validate`/`inspect` won't catch)

Surfaced here; full rationale in the linked reference. Do not violate:

No render-time clocks / unseeded Math.random / network / input-state; no repeat: -1 (use a finite count). → determinism-rules.md
Animate only the visual-property allowlist; never display/visibility; no gsap.set on later-scene clips. → determinism-rules.md
No <br> in body text; transformed elements must be block-level + sized; pulsing absolute decoratives need peak clearance. → determinism-rules.md
<video>/<audio> must be a direct child of the host root (never inside a sub-comp <template>/wrapper); the framework owns playback. → variables-and-media.md
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
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

Editing existing compositions

Read the files first. Preserve unrelated timing, tracks, IDs, variables, media paths.
Match existing composition IDs and timeline keys.
Adding a clip: pick a non-overlapping data-track-index or adjust surrounding timing intentionally.
Adding a sub-composition: verify its internal data-composition-id before wiring the host.

Validation

Use hyperframes-cli for command details

npx hyperframes lint passes (0 errors)
npx hyperframes validate passes (0 console errors)
npx hyperframes inspect passes (0 errors)
Projects with sub-compositions: npx hyperframes snapshot --at <midpoints> and eyeball each frame
npx hyperframes preview for review (the user can edit anything in Studio's timeline)
npx hyperframes render only after the user approves