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, media-use, 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/creator-editing-recipes.md |
copy truthful cut/trim/reorder/retime/freeze/camera/mask/crossfade/audio editing recipes and their limits |
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/review-loop.md |
run the plan → sketch → build review passes on a live board — shared by every storyboard-planning workflow |
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 |
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) |
references/brief-format.md |
author BRIEF.md — the confirmed intent document a workflow's Setup writes and every later step reads |
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/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 |
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. Do not rely on automated gates alone to catch this; inspect a snapshot. 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/.
First-pass lint gotchas (a guaranteed first build failure)
Two rules that lint does catch, but only after the fact — write them right the first time:
- The root composition element must carry
data-start="0" (alongside data-composition-id/data-width/data-height); omitting it fails lint with root_composition_missing_data_start.
- Never pair a CSS initial
transform with a GSAP tween on the same property — the CSS value and the tween's start fight and lint rejects it with gsap_css_transform_conflict. Set the initial state inside the tween with gsap.fromTo(el, { x: -40 }, { x: 0 }) instead of a CSS transform: translateX(-40px).
Non-negotiable rules (silent bugs automated gates may miss)
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 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
- No
<br> in body text; transformed elements must be block-level + sized; pulsing absolute decoratives need peak clearance. → determinism-rules.md
<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- 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.
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.- Adding a sub-composition: verify its internal
data-composition-id before wiring the host.
Validation
Use hyperframes-cli for command details
1---2name: hyperframes-core3description: HyperFrames composition contract: data-* attributes, tracks, sub-compositions, determinism, validation. Read before writing HTML.4---56# HyperFrames Core78HyperFrames 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.910This 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.1112## References1314| File | Read it to… |15| --------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |16| `references/minimal-composition.md` | start from the smallest renderable composition skeleton |17| `references/composition-patterns.md` | choose monolithic vs modular; structure a modular `index.html`; pick a sub-comp archetype |18| `references/data-attributes.md` | look up any `data-*` (root / clip / sub-comp host / legacy aliases); use `class="clip"` |19| `references/tracks-and-clips.md` | pick `data-track-index`, handle same-track overlap / z-index, time a clip relative to another |20| `references/creator-editing-recipes.md` | copy truthful cut/trim/reorder/retime/freeze/camera/mask/crossfade/audio editing recipes and their limits |21| `references/sub-compositions.md` | wire a sub-composition (host attrs, `<template>`, per-instance vars) and animate inside it |22| `references/variables-and-media.md` | declare variables; place `<video>`/`<audio>`, set volume, trim |23| `references/determinism-rules.md` | build a seekable timeline; determinism bans; the animatable-property allowlist; layout / text fit |24| `references/full-screen-motion.md` | author full-frame motion with shared backgrounds |25| `references/storyboard-format.md` | author a `STORYBOARD.md` plan (+ the parsed manifest) |26| `references/review-loop.md` | run the plan → sketch → build review passes on a live board — shared by every storyboard-planning workflow |27| `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 |28| `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) |29| `references/brief-format.md` | author `BRIEF.md` — the confirmed intent document a workflow's Setup writes and every later step reads |30| `references/script-format.md` | author the optional `SCRIPT.md` locked narration |31| `references/subagent-dispatch.md` | map subagent dispatch verbs (parallel fan-out / background / wait) to your harness |32| `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 |33| `references/tailwind.md` | work in a Tailwind v4 project (`init --tailwind`; runtime contract differs from Studio's v3) |3435For animation runtime specifics (GSAP API, Lottie, Three.js, etc.) go to `hyperframes-animation` → `adapters/<runtime>.md`.3637## Building a composition3839### Two root forms (not interchangeable)4041- **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).42- **Sub-composition** (loaded via `data-composition-src`) — root **must** be wrapped in `<template>`.4344> ⚠ Transport rule: the runtime **only clones `<template>` contents**; everything outside (incl. `<head>` styles/scripts) is discarded — put `<style>`/`<script>` **inside** the template.45> ⚠ 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.4647File shape, host wiring, and the pre-render checklist → `references/sub-compositions.md`.4849### Root must be sized (silent layout bug)5051The 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`.5253### One paused timeline5455Each 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/`.5657### First-pass lint gotchas (a guaranteed first build failure)5859Two rules that `lint` **does** catch, but only after the fact — write them right the first time:6061- The **root** composition element must carry `data-start="0"` (alongside `data-composition-id`/`data-width`/`data-height`); omitting it fails `lint` with `root_composition_missing_data_start`.62- Never pair a CSS initial `transform` with a GSAP tween on the **same** property — the CSS value and the tween's start fight and `lint` rejects it with `gsap_css_transform_conflict`. Set the initial state inside the tween with `gsap.fromTo(el, { x: -40 }, { x: 0 })` instead of a CSS `transform: translateX(-40px)`.6364### Non-negotiable rules (silent bugs automated gates may miss)6566Surfaced here; full rationale in the linked reference. Do not violate:6768- No render-time clocks / unseeded `Math.random` / network / input-state; no `repeat: -1` (use a finite count). → `determinism-rules.md`69- 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`70- No `<br>` in body text; transformed elements must be block-level + sized; pulsing absolute decoratives need peak clearance. → `determinism-rules.md`71- `<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`72- 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`73- 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`7475## Editing existing compositions7677- Read the files first. Preserve unrelated timing, tracks, IDs, variables, media paths.78- Match existing composition IDs and timeline keys.79- Adding a clip: pick a non-overlapping `data-track-index` or adjust surrounding timing intentionally.80- `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.81- Adding a sub-composition: verify its internal `data-composition-id` before wiring the host.8283## Validation8485Use `hyperframes-cli` for command details8687- [ ] `npx hyperframes check` passes (0 findings across lint, runtime, layout, motion, and contrast)88- [ ] Projects with sub-compositions: `npx hyperframes snapshot --at <midpoints>` and eyeball each frame89- [ ] `npx hyperframes preview` for review (the user can edit anything in Studio's timeline)90- [ ] `npx hyperframes render` only after the user approves
kitfunso