# Hyperframes Core

> El contrato de composición de HyperFrames para construir un proyecto renderizable: estructura, atributos data-* de tiempo, class="clip", tracks, sub-composiciones, variables y reglas de render determinista.

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

Repositorio: https://github.com/calesthio/OpenMontage
Autor: calesthio
Licencia: AGPL-3.0
Actualizado: el mes pasado
Coste de contexto: 75 tok instalada, 1.8k tok al activarse, 19.9k tok con todos los archivos del bundle
Bundle: 13 archivos, 78 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 calesthio/OpenMontage --skill hyperframes-core --agent claude-code
# Cursor
npx -y skills add calesthio/OpenMontage --skill hyperframes-core --agent cursor
# Codex
npx -y skills add calesthio/OpenMontage --skill hyperframes-core --agent codex
# Gemini CLI
npx -y skills add calesthio/OpenMontage --skill hyperframes-core --agent gemini
# Windsurf
npx -y skills add calesthio/OpenMontage --skill hyperframes-core --agent windsurf
# Cline
npx -y skills add calesthio/OpenMontage --skill hyperframes-core --agent cline
```

## Qué hace

- Define el contrato de composición de HyperFrames: cómo construir un proyecto renderizable
- Distingue las dos formas de raíz: standalone en `index.html` sin `<template>`, y sub-composición que sí debe ir envuelta en `<template>`
- Impone la regla de transporte: el runtime solo clona el contenido del `<template>`, así que `<style>` y `<script>` van dentro
- Exige que el `data-composition-id` del host coincida exactamente con el de la plantilla y con la clave de `window.__timelines`
- Cada composición registra exactamente una `gsap.timeline({ paused: true })`, construida de forma síncrona al cargar

## Cuándo usarla

- Se va a escribir HTML de composición: léelo antes
- Hay dudas sobre atributos `data-*` de tiempo, `class="clip"`, tracks, sub-composiciones o variables
- Hace falta reproducción de medios gobernada por el framework o reglas de render determinista
- Se edita una composición existente o se valida

## Qué la activa

- "¿Cómo estructuro esta composición de HyperFrames?"
- "Mi sub-composición no se monta, ¿por qué?"
- "Explícame los atributos data-* de tiempo"

## Antes de instalar

- Hay errores silenciosos que `lint`, `validate` e `inspect` no detectan, como una raíz sin dimensionar o un id de host con sufijo.

## Archivos

- SKILL.md — 7 KB
- references/composition-patterns.md — 13 KB
- references/data-attributes.md — 8 KB
- references/determinism-rules.md — 5 KB
- references/full-screen-motion.md — 3 KB
- references/minimal-composition.md — 2 KB
- references/script-format.md — 3 KB
- references/storyboard-format.md — 5 KB
- references/sub-compositions.md — 11 KB
- references/subagent-dispatch.md — 8 KB
- references/tailwind.md — 5 KB
- references/tracks-and-clips.md — 4 KB
- references/variables-and-media.md — 5 KB

## SKILL.md

Reproducido tal cual desde calesthio/OpenMontage bajo AGPL-3.0. Esta sección es el documento original y está en inglés.

# 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`, `hyperframes-media`, `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/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/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/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. `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

## Dónde encaja

- Categoría: [Diseño y UI](https://skillsagentes.com/categorias/diseno-ui.md) — Sistemas de diseño, trabajo con componentes y acabado visual.
- Creador: [calesthio](https://skillsagentes.com/creators/calesthio.md) — 0 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

- [Seedance 2 5](https://skillsagentes.com/skills/calesthio/openmontage/seedance-2-5.md): Genera vídeo cinematográfico de 4-30 s con ByteDance Seedance 2.5 por fal.ai, Volcengine Ark, Runway o ComfyUI. Cubre el contrato de prompt 2.5, cortes duros, locks de continuidad y voz.
- [Comfyui](https://skillsagentes.com/skills/calesthio/openmontage/comfyui.md): Úsalo al trabajar con workflows de ComfyUI en OpenMontage: comfyui_image/video/music, workflows propios, selección de output_node, modelos que faltan, LoRAs, poca VRAM e importación de workflows de la comunidad.
- [Fish Audio Tts](https://skillsagentes.com/skills/calesthio/openmontage/fish-audio-tts.md): Genera narración expresiva y multilingüe con fish.audio (modelos S1 / S2) y reutiliza voces clonadas mediante reference_id.
- [Minimax H3](https://skillsagentes.com/skills/calesthio/openmontage/minimax-h3.md): Genera vídeo con MiniMax H3 (Hailuo 3.0) por la API oficial v2, fal.ai, Runway, nodos partner de ComfyUI o pesos abiertos locales. Clips de 4-15s a 2K con animación de primer/último fotograma.
- [Gemini Omni](https://skillsagentes.com/skills/calesthio/openmontage/gemini-omni.md): Genera y edita conversacionalmente vídeos cortos con Google Gemini Omni Flash: itera con ediciones en lenguaje natural, clips de 3-10s a 720p con audio y texto en pantalla, e imágenes de referencia por etiquetas.

---

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