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. Other concerns live in sibling skills:

```
hyperframes-animation
```
— atomic motion rules + scene blueprints + per-runtime adapters (GSAP, Lottie, Three, Anime.js, CSS, WAAPI, TypeGPU)
```
hyperframes-creative
```
— palettes, typography, narration, beat planning, audio-reactive
```
hyperframes-media
```
— TTS, Whisper transcribe, background removal, captions
```
hyperframes-registry
```
— install blocks and components (
```
hyperframes add
```
)
```
hyperframes-cli
```
— dev loop commands (lint / validate / preview / render)

For Tailwind v4 projects (

hyperframes init --tailwind

), see

references/tailwind.md

— the browser-runtime contract is distinct from Studio's Tailwind v3 setup.

Routing

Want to…	Read
See a minimal renderable composition	`references/minimal-composition.md`
Decide between monolithic single-file and modular sub-comp architecture	`references/composition-patterns.md`
Structure a modular `index.html` (orchestrator + slots + root audio)	`references/composition-patterns.md`
Pick a sub-comp archetype (content / driver-only / multi-scene merge / audio-reactive)	`references/composition-patterns.md`
Look up a `data-*` attribute (root, clip, sub-comp host, legacy aliases)	`references/data-attributes.md`
Use `class="clip"` correctly	`references/data-attributes.md`
Pick a `data-track-index` ; same-track overlap; track-index vs CSS `z-index`	`references/tracks-and-clips.md`
Time a clip relative to another ( `data-start="intro + 2"` , crossfade overlap, chains)	`references/tracks-and-clips.md`
Wire a sub-composition (host attributes, `<template>` wrapper, per-instance variables)	`references/sub-compositions.md`
Animate inside a sub-composition ( `gsap.fromTo` over `gsap.from` , seek-back behavior)	`references/sub-compositions.md`
Declare variables (types, extra options, defaults, `--strict-variables` in CI)	`references/variables-and-media.md`
Place `<video>` / `<audio>` , set volume, trim with `data-media-start`	`references/variables-and-media.md`
Build a seekable timeline (paused, sync construction, `gsap.set` later-scene trap)	`references/determinism-rules.md`
Avoid non-deterministic state (clocks, `Math.random` , `repeat: -1` , finite repeat formula)	`references/determinism-rules.md`
Know what can / cannot be animated (visual-property allowlist; not `display` / `visibility` )	`references/determinism-rules.md`
Fit text and prevent overflow ( `fitTextFontSize` signature, `<br>` rule, layout contract)	`references/determinism-rules.md`
Author full-frame motion with shared backgrounds	`references/full-screen-motion.md`
Work in a Tailwind v4 project ( `init --tailwind` )	`references/tailwind.md`

For animation runtime specifics (GSAP API, Lottie, Three.js, etc.) go to

hyperframes-animation

→

adapters/<runtime>.md

Composition Structure

Two root forms; they are not interchangeable.

Standalone (the top-level
```
index.html
```
) — root
```
<div data-composition-id="…">
```
sits directly in
```
<body>
```
. No
<template>
wrapper. Wrapping a standalone root in
```
<template>
```
hides all content from the browser and breaks rendering.
Sub-composition (a file loaded via
```
data-composition-src
```
) — root
```
<div data-composition-id="…">
```
must be wrapped in
```
<template>
```
. Without the wrapper the runtime cannot extract and mount it.

⚠ Sub-composition transport rule: the runtime only clones
<template>
contents into the live DOM. Everything outside the template — including
<head>
and any
<style>
/
<script>
/
<link>
that lives in
<head>
— is discarded. Put
<style>
and
<script>
blocks inside
<template>
, not in
<head>
.
⚠ Host-id rule: in the host file,
data-composition-id
on the slot must exactly equal the inner template's
data-composition-id
and the
window.__timelines["<id>"]
key. Do not add
-mount
/
-slot
/
-host
suffixes.

See

references/sub-compositions.md

for the file shape, host wiring, pitfall examples, and the pre-render verification checklist.

Root must be sized (silent layout bug)

The standalone root must establish an explicitly sized box, and every ancestor between it and a

height: 100%

element must have a resolved height. If the root or an intermediate wrapper has no height, a flex/

height:100%

content container collapses to ~0 and content piles into the top-left corner (often clipping the first glyph at x=0).

lint

validate

, and

inspect

do not catch this —

inspect

substitutes the authored

data-width

data-height

for a collapsed root and reports "0 layout issues."

html

<body style="margin: 0">
  <div
    id="root"
    data-composition-id="main"
    data-width="1920"
    data-height="1080"
    data-duration="5"
    style="position: relative; width: 1920px; height: 1080px; overflow: hidden"
  >
    <!-- Center robustly: position:absolute + inset:0 fills the sized root regardless of
         intermediate wrappers; or use a flex container ONLY if its parent chain is sized. -->
    <section
      class="clip"
      data-start="0"
      data-duration="5"
      data-track-index="1"
      style="position: absolute; inset: 0; display: grid; place-items: center; padding: 120px 160px; box-sizing: border-box"
    >
      <h1>Title</h1>
    </section>
  </div>
</body>

Keep the

padding

(≥80px) on the centering container — it is the title-safe margin that stops large type touching the frame edge. See

references/minimal-composition.md

Timeline Contract (GSAP default)

Every composition registers exactly one GSAP timeline.

Create with
```
gsap.timeline({ paused: true })
```
— the player owns playback.
Register at
```
window.__timelines["<composition-id>"]
```
; the key must exactly match the root's
```
data-composition-id
```
. Dot syntax (
```
window.__timelines.<id> = tl
```
) is equivalent when the id is a valid identifier; use brackets if the id contains
```
-
```
.
Build the timeline synchronously during page load — not inside
```
async
```
,
```
setTimeout
```
,
```
Promise
```
, or event handlers. The renderer samples after page load completes; any deferred timeline construction misses the sample.
Render duration comes from
```
data-duration
```
on the root, not from GSAP timeline length. Do not pad the timeline with empty tweens to set duration.
For sub-compositions, do not manually nest sub-timelines into the host (
```
master.add(sub)
```
); the framework drives them independently.

For non-GSAP runtimes (Lottie / Three / WAAPI / CSS / Anime.js / TypeGPU), the equivalent contract lives in

hyperframes-animation/adapters/<runtime>.md

. See

references/determinism-rules.md

for the cross-runtime Animation Runtime Contract.

Non-Negotiable Rules

These break the renderer — or produce silent visual bugs that
lint
/
validate
/
inspect
do NOT catch (rules 3, 7-8). (Synchronous timeline construction is covered above in Timeline Contract.)

No
```
Math.random()
```
/
```
Date.now()
```
/
```
performance.now()
```
driving visuals — use a seeded PRNG.

repeat: -1

. Use

repeat: Math.max(0, Math.floor(duration / cycleDuration) - 1)

— floor
, not
ceil
(

ceil

overshoots

data-duration

and trips the

gsap_repeat_ceil_overshoot

lint;

max(0, …)

avoids a negative repeat = infinite).

```
<video>
```
/
```
<audio>
```
must be a direct child of the host root (
```
index.html
```
) — never inside a sub-comp
```
<template>
```
, never inside a wrapper
```
<div>
```
; otherwise it is never decoded and renders blank/black (silent). The framework owns playback: no
```
video.play()
```
/
```
audio.play()
```
/
```
currentTime = …
```
. A sub-comp cannot drive host elements (selector or
```
querySelector
```
), so animate host media from the main timeline at global time. See
```
references/variables-and-media.md
```
.
No
```
gsap.set()
```
on clip elements from later scenes (they are not in the DOM yet). Use
```
tl.set(selector, vars, time)
```
at or after the clip's
```
data-start
```
.
No animating
```
display
```
/
```
visibility
```
. Animate
```
opacity
```
/ transforms; the clip lifecycle handles show/hide.
No
```
<br>
```
in body text. Let text wrap via
```
max-width
```
.
Transformed elements must be block-level + sized.
```
transform
```
/
```
scaleX
```
/
```
scaleY
```
is a no-op on an inline
<span>
, and scaling an auto-width (0px) element shows nothing → invisible bars/fills. Give them
```
display: block
```
/
```
inline-block
```
/flex-item and a real
```
width
```
/
```
height
```
(e.g.
```
width: 100%
```
inside a sized parent).
Absolutely-positioned decoratives (badges, pills, tags) that pulse or overshoot (
```
yoyo
```
scale,
```
back.out
```
) need clearance at their peak size and must not straddle an
```
overflow: hidden
```
edge — else they overlap a neighbor or get clipped. Position for the largest frame, not the resting one.

Editing Existing Compositions

Read the actual files before editing.
Preserve unrelated timing, tracks, IDs, variables, and media paths.
Match existing composition IDs and timeline registry keys.
When adding a clip, choose a non-overlapping
```
data-track-index
```
or intentionally adjust surrounding timing.
When 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, or overflow is intentionally marked
Projects with sub-compositions:
```
npx hyperframes snapshot --at <midpoints>
```
and eyeball each frame

hyperframes-core

NPX Install

Tags

SKILL.md Content