# Hyperframes Core

> El contrato de composición de HyperFrames: cómo construir un proyecto renderizable con atributos `data-*`, `class="clip"`, tracks, sub-composiciones, variables y reglas de renderizado determinista.

Fuente: https://skillsagentes.com/skills/heygen-com/hyperframes/hyperframes-core
Markdown: https://skillsagentes.com/skills/heygen-com/hyperframes/hyperframes-core.md

Repositorio: https://github.com/heygen-com/hyperframes
Autor: heygen-com
Licencia: Apache-2.0
Actualizado: hace 2 meses
Coste de contexto: 95 tok instalada, 2.6k tok al activarse, 37.3k tok con todos los archivos del bundle
Bundle: 19 archivos, 146 KB
Permisos que pide: ninguno declarado

## Instalación

Un skill son archivos markdown: los mismos archivos valen para cualquier agente y lo único que cambia es el directorio de destino, es decir la bandera `--agent`. Añade `-g` para instalarlo en todos los proyectos de la máquina.

```bash
# Claude Code
npx -y skills add heygen-com/hyperframes --skill hyperframes-core --agent claude-code
# Cursor
npx -y skills add heygen-com/hyperframes --skill hyperframes-core --agent cursor
# Codex
npx -y skills add heygen-com/hyperframes --skill hyperframes-core --agent codex
# Gemini CLI
npx -y skills add heygen-com/hyperframes --skill hyperframes-core --agent gemini
# Windsurf
npx -y skills add heygen-com/hyperframes --skill hyperframes-core --agent windsurf
# Cline
npx -y skills add heygen-com/hyperframes --skill hyperframes-core --agent cline
```

## Qué hace

- Define el contrato técnico de composición HyperFrames: estructura del HTML, atributos `data-*`, `class="clip"`, tracks, sub-composiciones y variables
- Impone reglas de renderizado determinista (sin relojes en tiempo de render, sin `Math.random` sin semilla, sin `repeat: -1`, allowlist de propiedades animables)
- Fija reglas de tamaño de raíz, timeline única pausada por composición y wiring de sub-composiciones vía `<template>`
- Documenta los checks de validación con `hyperframes check`, `snapshot`, `preview` y `render`
- Explica formatos de plan STORYBOARD.md / SCRIPT.md y el soporte para proyectos Tailwind v4

## Cuándo usarla

- Antes de escribir HTML de composición para HyperFrames
- Al elegir entre composición monolítica o modular, o un archetype de sub-composición
- Al depurar por qué un elemento colapsa a ~0 por falta de tamaño en la raíz o por qué un frame renderiza en negro
- Al trabajar en un proyecto Tailwind v4 con `init --tailwind`

## Cuándo no

- Para el runtime de animación específico (GSAP, Lottie, Three.js) — eso corresponde a `hyperframes-animation`
- Para detalles de CLI — usar `hyperframes-cli`

## Qué la activa

- "Ayúdame a estructurar el index.html de esta composición HyperFrames"
- "¿Por qué mi sub-composición no se renderiza y queda en blanco?"
- "Necesito armar el STORYBOARD.md de este proyecto"
- "Configura un proyecto HyperFrames con Tailwind v4"

## Antes de instalar

- Requiere el CLI `hyperframes` (comandos `check`, `snapshot`, `preview`, `render`) para validar la composición.

## Archivos

- SKILL.md — 10 KB
- references/brief-contract.md — 12 KB
- references/brief-format.md — 7 KB
- references/composition-patterns.md — 13 KB
- references/data-attributes.md — 13 KB
- references/determinism-rules.md — 7 KB
- references/frame-worker-core.md — 16 KB
- references/full-screen-motion.md — 3 KB
- references/minimal-composition.md — 2 KB
- references/production-loop.md — 7 KB
- references/review-loop.md — 7 KB
- references/script-format.md — 3 KB
- references/storyboard-format.md — 8 KB
- references/sub-compositions.md — 11 KB
- references/subagent-dispatch.md — 4 KB
- references/tailwind.md — 5 KB
- references/tracks-and-clips.md — 4 KB
- references/variables-and-media.md — 7 KB
- scripts/lib/frame-packets-core.mjs — 7 KB

## SKILL.md

Reproducido tal cual desde heygen-com/hyperframes bajo Apache-2.0. Esta sección es el documento original y está en inglés.

**Plugin installs:** Before setup or freshness commands, follow [plugin execution rules](../hyperframes/references/plugin-installation.md) when this skill is inside a HyperFrames plugin. Standalone installs keep the update instructions below.

# HyperFrames Core

**Agent pitfalls (read first):**

- Center with flex/`inset`, not CSS `transform: translate(-50%,-50%)` on a node you then GSAP `x`/`y`. Lint: `gsap_css_transform_conflict`. Use `fromTo` or `xPercent`/`yPercent`.
- Do not add a scene-exit `tl.set(..., {visibility:"hidden"})`. The runtime already hides timed clips. Opacity fades on inner nodes (or `opacity` on `.clip`) are enough. Caption hard-kills are a different rule.
- `window.__timelines["id"]` must match the root `data-composition-id`.
- After `render`, read the summary's second line: `beginframe` vs `screenshot`, GPU mode, stage timings. `screenshot` + `software gpu` on Linux is the slow path.

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. Process docs (brief, storyboard, review, production, dispatch, frame-worker) live in `/hyperframes` → `references/`. 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`        | understand what `data-track-index` does (and does not) control, z-index, time a clip relative to another; list every track and clip with `npx hyperframes timeline` |
| `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; layout / text fit                                                                                                      |
| `references/full-screen-motion.md`      | author full-frame motion with shared backgrounds                                                                                                                    |
| `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 a standalone root hides all content and `lint` rejects it (`standalone_composition_wrapped_in_template`, error).
- **Sub-composition** (loaded via `data-composition-src`): wrap the root in `<template>`. This is the shape to write: the loader also accepts a plain full document and falls back to its `<body>`, but the templated form is what the examples and tooling assume.

> ⚠ Transport rule: for a **templated** sub-composition the assembler drops the file's own `<head>` `<style>`/`<script>` (`packages/core/src/compiler/compositionAssembly.ts`, the `hasTemplate` gate), so put `<style>`/`<script>` **inside** the template. `<link>` is hoisted either way.
> ⚠ Host-id convention: give the host slot, the inner template, and the `window.__timelines["<id>"]` key the **same** id. A different local id is supported (the assembler falls back to the first root in the file) but the mismatch is silent, so match them unless you have a reason not to.

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

### Root must be sized (silent layout bug)

The standalone root authors `width`/`height: 100%`. Canvas size is `data-width`/`data-height`. The runtime stamps those pixels onto the composition root. Do not hardcode `1920px`/`1080px` on `#root`. 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`). Building it inside an async callback (`document.fonts.ready`) is supported; what matters is that you **register only after the build completes**. Render length is the root's `data-duration`, **not** the timeline's length: a timeline that runs past it is cut off, and one that ends early holds its last frame. Omit the root `data-duration` and the length is inferred instead (timeline, media window, or adapter). You do not need `window.__timelines = window.__timelines || {}`: the runtime creates the registry before your inline scripts run, and `lint` no longer asks for it. Don't manually nest sub-timelines into the host; the runtime auto-nests registered child timelines. Full contract (incl. non-GSAP runtimes) → `references/determinism-rules.md` + `hyperframes-animation/adapters/`.

### First-pass lint gotchas (a guaranteed first build failure)

Rules that `lint` **does** catch, but only after the fact. Write them right the first time:

- 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)`.
- Never put `crossorigin` on `<video>`/`<audio>`. `lint` rejects it unconditionally with `media_crossorigin_breaks_preview` (error), including for canvas/WebGL/WebAudio readback. There is no suppression.
- Never give a `<video data-start>` an ancestor that also carries `data-start`. `lint` rejects it with `video_nested_in_timed_element` (error). Time the wrapper **or** the video, not both.
- Every `<audio>` needs an `id`. `lint` rejects it with `media_missing_id`, and an id-less `<audio>` is never picked up by the mixer, so the render is **silent**.
- Never tween a `.clip` with `autoAlpha` or `visibility` — `lint` rejects it with `gsap_animates_clip_element`. Animate a child instead.
- A named CSS `font-family` needs an in-file `@font-face` to a shipped local file, or `lint` fires `font_family_without_font_face`.
- Sub-composition `#root` uses `width`/`height: 100%` (or `inset: 0`), not hardcoded `1920px`/`1080px`. Canvas size is `data-width`/`data-height`.

A lint **error** also switches off the layout and contrast audits: `check` then reports `0 sample(s)` and `0/0 text checks`, which reads like a clean file but means nothing ran. Clear lint errors before you trust those numbers.

### 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`
- Never tween `display`, `visibility`, or `autoAlpha` on a `.clip` element. The framework owns clip visibility, and `lint` rejects it (`gsap_animates_clip_element`). Animate a child instead. → `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>` are found by a flat document query, so the framework seeks and decodes them at **any nesting depth** (including inside a sub-comp `<template>` or wrapper). One hard limit: `lint` errors if a `<video data-start>` sits inside another **plain** element that also has `data-start`, and the failure is real (wrong source frames, then the clip vanishes mid-slot), so put the timing on the wrapper or on the video, never both. Sub-composition hosts are exempt: media inside a sub-composition renders correctly. The other caveat is timelines, not placement: a sub-comp timeline can't animate host-root elements. → `variables-and-media.md`
- Keep every `id` unique across the **assembled** page (prefix sub-comp ids with the composition id, `#<id>-hero`) so your own `#id` CSS and `getElementById` calls resolve. Frame injection no longer depends on it: the compiler stamps a document-unique `data-hf-render-id` on every `video[src]`/`audio[src]`/`img[src]`. Media that uses `<source>` children instead of a `src` attribute is **not** stamped, so unique ids still matter there. → `composition-patterns.md`
- A full-screen fill on the composition **root** is fine on a normal render. It is dropped only on the layered-composite path (HDR content, or a composition using shader transitions), where the engine forces every composition root transparent so the layer beneath shows through. If your composition uses shader transitions or HDR media, put the fill on a full-bleed **child** (`position:absolute; inset:0`). → `composition-patterns.md`

## Editing existing compositions

- Read the files first. Preserve unrelated timing, tracks, IDs, variables, media paths.
- To know what is on a project's timeline (tracks, clips, starts, ends, what plays), run `npx hyperframes timeline [--json]` instead of reading `index.html` and every sub-composition file.
- Match existing composition IDs and timeline keys.
- Adding a clip: set its `data-start`/`data-duration` intentionally against the clips around it. `data-track-index` is a Studio display lane, not a timing constraint, so it does not need to be free.
- A clip that ends past the root `data-duration` is cut off: extend the root `data-duration` to the clip's end in the same edit (`lint` warns `clip_ends_past_root_duration`).
- `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

- [ ] `npx hyperframes check` passes (0 findings across lint, runtime, layout, motion, and contrast)
- [ ] Projects with sub-compositions: `npx hyperframes snapshot --at <midpoints>` and eyeball each frame
- [ ] `npx hyperframes preview --background` for review (the user can edit anything in Studio's timeline, and the server survives the invoking command)
- [ ] `npx hyperframes render` only after the user approves

## Dónde encaja

- Categoría: [Vídeo y animación](https://skillsagentes.com/categorias/video.md) — Skills que generan, editan y animan vídeo: guion y storyboard, render, subtítulos y doblaje, y los modelos que lo producen.
- Creador: [heygen-com](https://skillsagentes.com/creators/heygen-com.md) — 25 skills en el directorio
- [Todas las skills](https://skillsagentes.com/skills.md)
- [Ranking de instalaciones](https://skillsagentes.com/ranking.md)

## Otras skills del mismo repositorio

- [Media Use](https://skillsagentes.com/skills/heygen-com/hyperframes/media-use.md): Agent Media OS: resuelve BGM, SFX, imágenes, iconos, logos, voz, gradación de color o LUTs en un archivo local o bloque listo para usar; genera, opera y reutiliza assets en proyectos HyperFrames.
- [Pr To Video](https://skillsagentes.com/skills/heygen-com/hyperframes/pr-to-video.md): Convierte un pull request de GitHub (URL, owner/repo#N o 'este PR') en un video explicativo del cambio de código —changelog, feature, fix o refactor— construido a partir del diff, commits y archivos.
- [Hyperframes](https://skillsagentes.com/skills/heygen-com/hyperframes/hyperframes.md): Punto de entrada obligatorio para crear, editar, animar o renderizar video, animaciones o motion graphics con HyperFrames, así como para inspeccionar, validar o publicar proyectos existentes.
- [Product Launch Video](https://skillsagentes.com/skills/heygen-com/hyperframes/product-launch-video.md): Convierte una URL de producto o marketing, un guion pegado o un brief en un video de lanzamiento/promoción — promos SaaS, revelaciones de funciones, demos, lanzamientos de apps y empresas.
- [Hyperframes Cli](https://skillsagentes.com/skills/heygen-com/hyperframes/hyperframes-cli.md): Usa el flujo de desarrollo de la CLI de HyperFrames: init, add, catalog, capture, lint, check, snapshot, compare, preview, render, publish, cloud, lambda, feedback, doctor y más; también para diagnosticar fallos de build o render.

## Skills relacionadas

- [Captions Overlay](https://skillsagentes.com/skills/heygen-com/hyperframes/captions-overlay.md): Doctrina de overlay para captions embebidos: el modelo drop/rail/embed y la regla de que los captions son un overlay compuesto sobre el film, nunca una banda inferior reservada.
- [Changelog Video](https://skillsagentes.com/skills/heygen-com/hyperframes/changelog-video.md): Convierte un changelog .md semanal en un video de marca terminado (cuadrado 1080, ~45-60s, voz de Annie, fondo animado, mock-UI, captions lowkey). Autocontenido: fuentes, fondo, léxico y scripts incluidos.
- [Embedded Captions](https://skillsagentes.com/skills/heygen-com/hyperframes/embedded-captions.md): Añade subtítulos o captions a un vídeo de un solo sujeto hablando a cámara sin editar el metraje, usando el catálogo de 35 identidades visuales.
- [Faceless Explainer](https://skillsagentes.com/skills/heygen-com/hyperframes/faceless-explainer.md): Convierte texto (artículo, notas, tema o brief) en un video explicativo faceless: sin sitio ni material que capturar, los visuales se inventan por escena (tipografía, gráficos abstractos, diagramas, data-viz).
- [Figma](https://skillsagentes.com/skills/heygen-com/hyperframes/figma.md): Importa contenido de Figma a una composición de HyperFrames: assets renderizados, tokens de marca, componentes, secciones de storyboard reconstruidas como movimiento y shaders.

---

Skills Agentes · [Índice de páginas en markdown](https://skillsagentes.com/sitemap.md) · [Inicio](https://skillsagentes.com/index.md)