hyperframes-core Checked

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