HyperFrames Core
O HyperFrames renderiza vídeo a partir de HTML. Uma composição é um arquivo HTML cujo DOM declara temporização com atributos data-*, cujo tempo de execução da animação é buscável e cuja reprodução de mídia é gerenciada pelo framework.
Este é o contrato de composição — como construir um projeto hyperframes. O corpo abaixo é o guia de construção; os detalhes por tópico estão em references/ (índice a seguir), leia sob demanda. Outras preocupações estão em seções irmãs da mesma skill — ../cli (ciclo de desenvolvimento) e ../registry (instalar blocos/componentes) — e nas skills de design irmãs, /hyperframes-motion (receitas de animação) e /hyperframes-design (paletas, tipografia, predefinições de quadro). O mapa de capacidades em ../SKILL.md diz o que cada uma cobre.
Referências
| Arquivo | Leia para… |
|---|---|
references/minimal-composition.md | começar pelo menor esqueleto de composição renderizável |
references/composition-patterns.md | escolher entre monolítico vs. modular; estruturar um index.html modular; escolher um arquétipo de subcomposição |
references/data-attributes.md | consultar qualquer data-* (raiz / clipe / hospedeiro de subcomp / aliases legados); usar class="clip" |
references/tracks-and-clips.md | escolher data-track-index, lidar com sobreposição/z-index na mesma faixa, temporizar um clipe em relação a outro |
references/sub-compositions.md | conectar uma subcomposição (atributos do hospedeiro, <template>, variáveis por instância) e animar dentro dela |
references/variables-and-media.md | declarar variáveis; posicionar <video> para reprodução apenas visual |
references/determinism-rules.md | construir uma linha do tempo buscável; proibições de determinismo; lista de propriedades animáveis; ajuste de layout/texto |
references/full-screen-motion.md | criar movimento de quadro inteiro com fundos compartilhados |
references/storyboard-format.md | criar um plano STORYBOARD.md (+ o manifesto analisado) |
references/subagent-dispatch.md | mapear verbos de despacho de subagentes (fan-out paralelo / fundo / espera) para seu harness |
references/tailwind.md | trabalhar em um projeto Tailwind v4 (init --tailwind; contrato de tempo de execução difere do v3 do Studio) |
Para especificidades do tempo de execução de animação (API GSAP, Lottie, Three.js, etc.) vá para /hyperframes-motion → adapters/<runtime>.md.
Construindo uma composição
Duas formas raiz (não intercambiáveis)
- Independente (
index.htmlde nível superior) —<div data-composition-id="…">raiz fica diretamente em<body>, sem invólucro<template>(envolvê-lo esconde todo o conteúdo e quebra a renderização). - Subcomposição (carregada via
data-composition-src) — a raiz deve ser envolvida em<template>.
⚠ Regra de transporte: o tempo de execução apenas clona o conteúdo de
<template>; tudo fora (incluindo estilos/scripts de<head>) é descartado — coloque<style>/<script>dentro do template. ⚠ Regra do ID do hospedeiro: odata-composition-iddo slot hospedeiro deve ser exatamente igual aodata-composition-iddo template interno e à chavewindow.__timelines["<id>"]— sem sufixo-mount/-slot/-host.
Forma do arquivo, conexão do hospedeiro e lista de verificação pré-renderização → references/sub-compositions.md.
A raiz deve ter tamanho definido (bug de layout silencioso)
A raiz independente precisa de uma caixa com tamanho explícito (width/height em px), e todo ancestral até um elemento com height:100% deve ter uma altura resolvida — caso contrário, um filho flex/100% colapsa para ~0 e o conteúdo se acumula no canto superior esquerdo. lint/validate/inspect não detectam isso. Esqueleto → references/minimal-composition.md.
Uma linha do tempo pausada
Cada composição registra exatamente uma gsap.timeline({ paused: true }) em window.__timelines["<id>"] (chave = data-composition-id raiz), construída sincronamente no carregamento da página. Duração da renderização = data-duration raiz, não comprimento da linha do tempo. Não aninhe manualmente sublinhas do tempo no hospedeiro. Contrato completo (incluindo tempos de execução não-GSAP) → references/determinism-rules.md + /hyperframes-motion/adapters/.
Regras inegociáveis (bugs silenciosos que lint/validate/inspect não pegam)
Exibidas aqui; justificativa completa na referência vinculada. Não viole:
- Sem clocks de tempo de renderização /
Math.randomnão semeado / rede / estado de entrada; semrepeat: -1(use uma contagem finita). →determinism-rules.md - Anime apenas a lista de propriedades visuais permitidas; nunca
display/visibility; semgsap.setem clipes de cenas posteriores. →determinism-rules.md - Sem
<br>em texto do corpo; elementos transformados devem ser de nível de bloco + dimensionados; decorativos absolutos pulsantes precisam de folga de pico. →determinism-rules.md <video>deve ser filho direto da raiz do hospedeiro (nunca dentro de um<template>/invólucro de subcomp); o framework controla a reprodução. →variables-and-media.md- Cada
iddeve ser único em toda a página montada; dentro de uma subcomp, prefixe ids com o id da composição (#<id>-hero). IDs duplicados de<video>/<img>renderizam em branco — o produtor injeta quadros viagetElementById, e dupes entre arquivos escapam dolint. →composition-patterns.md - Um preenchimento de cena em tela cheia vai em um filho sem margens (
position:absolute; inset:0), nunca na própria raiz da composição — a composição de quadros do produtor pode descartar obackgrounddo próprio elemento raiz (o quadro renderiza preto) mesmo que a visualização/snapshotmostre-o corretamente. →composition-patterns.md
Editando composições existentes
- Leia os arquivos primeiro. Preserve temporização, faixas, IDs, variáveis, caminhos de mídia não relacionados.
- Combine IDs de composição existentes e chaves de linha do tempo.
- Adicionar um clipe: escolha um
data-track-indexnão sobreposto ou ajuste a temporização circundante intencionalmente. - Adicionar uma subcomposição: verifique seu
data-composition-idinterno antes de conectar o hospedeiro.
Validação
Execute o portão da CLI (veja ../cli/SKILL.md → Workflow + Minimum Completion Gate para a lista de verificação canônica lint / validate / inspect / snapshot / preview / render, incluindo o teste de fumaça visual necessário para projetos de subcomposição).