HyperFrames Core

data-*

references/

hyperframes-animation

hyperframes-creative

hyperframes-media

hyperframes-cli

hyperframes-registry

/hyperframes

References

references/minimal-composition.md

references/composition-patterns.md

index.html

references/data-attributes.md

data-*

class="clip"

references/tracks-and-clips.md

data-track-index

references/sub-compositions.md

<template>

references/variables-and-media.md

<video>

<audio>

references/determinism-rules.md

references/full-screen-motion.md

references/storyboard-format.md

STORYBOARD.md

references/script-format.md

SCRIPT.md

references/subagent-dispatch.md

references/tailwind.md

init --tailwind

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.

references/sub-compositions.md

Root must be sized (silent layout bug)

width

height

height:100%

100%

lint

validate

inspect

references/minimal-composition.md

One paused timeline

gsap.timeline({ paused: true })

window.__timelines["<id>"]

data-composition-id

data-duration

references/determinism-rules.md

hyperframes-animation/adapters/

Non-negotiable rules (silent bugs

lint

/

validate

/

inspect

won't catch)

• 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

hyperframes-cli

• 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