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 runtime de animação é buscável (seekable), e cuja reprodução de mídia é gerenciada pelo framework.
Esta habilidade é o contrato técnico — como construir um projeto HyperFrames. O corpo abaixo é o guia de construção; detalhes por tópico estão em references/ (índice a seguir), leia sob demanda. Outras preocupações ficam nas habilidades irmãs de domínio — hyperframes-animation, hyperframes-creative, hyperframes-media, hyperframes-cli, hyperframes-registry. O mapa de capacidades em /hyperframes informa o que cada uma cobre.
Referências
| Arquivo | Leia para… |
|---|---|
references/minimal-composition.md | começar do menor esqueleto de composição renderizável |
references/composition-patterns.md | escolher monolítico vs modular; estruturar um index.html modular; escolher um arquétipo de sub-comp |
references/data-attributes.md | consultar qualquer data-* (raiz / clip / host de sub-comp / 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 clip relativo a outro |
references/sub-compositions.md | conectar uma sub-composição (atributos do host, <template>, variáveis por instância) e animar dentro dela |
references/variables-and-media.md | declarar variáveis; posicionar <video>/<audio>, definir volume, cortar (trim) |
references/determinism-rules.md | construir uma linha do tempo buscável; proibições de determinismo; lista de propriedades animáveis; layout / ajuste de texto |
references/full-screen-motion.md | criar movimento de quadro completo com fundos compartilhados |
references/storyboard-format.md | escrever um plano STORYBOARD.md (+ o manifesto analisado) |
references/script-format.md | escrever a narração travada opcional SCRIPT.md |
references/subagent-dispatch.md | mapear verbos de despacho de subagente (fan-out paralelo / background / espera) para seu harness |
references/tailwind.md | trabalhar em um projeto Tailwind v4 (init --tailwind; contrato de runtime difere do Studio v3) |
Para especificidades do runtime de animação (API GSAP, Lottie, Three.js, etc.), vá para hyperframes-animation → adapters/<runtime>.md.
Construindo uma composição
Duas formas raiz (não intercambiáveis)
- Autônoma (top-level
index.html) — root<div data-composition-id="…">fica diretamente no<body>, sem wrapper<template>(encapsular esconde todo o conteúdo e quebra a renderização). - Sub-composição (carregada via
data-composition-src) — root deve estar encapsulada em<template>.
⚠ Regra de transporte: o runtime apenas clona o conteúdo de
<template>; tudo fora (incluindo estilos/scripts de<head>) é descartado — coloque<style>/<script>dentro do template. ⚠ Regra de ID do host: odata-composition-iddo slot host deve ser exatamente igual aodata-composition-iddo template interno e à chavewindow.__timelines["<id>"]— sem sufixo-mount/-slot/-host.
Formato do arquivo, conexão do host e checklist pré-renderização → references/sub-compositions.md.
A raiz deve ter tamanho definido (bug silencioso de layout)
A raiz autônoma precisa de uma caixa dimensionada explicitamente (width/height em px), e cada ancestral até um elemento com height:100% deve ter altura resolvida — caso contrário, um filho flex/100% colapsa para ~0 e o conteúdo se empilha no canto superior esquerdo. lint/validate/inspect não capturam 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 = root data-composition-id), construída sincronamente ao carregar a página. Duração da renderização = root data-duration, não o comprimento da timeline. Não aninhe manualmente sub-timelines no host. Contrato completo (incluindo runtimes não-GSAP) → references/determinism-rules.md + hyperframes-animation/adapters/.
Regras inegociáveis (bugs silenciosos que lint/validate/inspect não capturam)
Expostas aqui; justificativa completa na referência vinculada. Não viole:
- Sem clocks em tempo de renderização /
Math.randomsem semente / 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 clips de cenas posteriores. →determinism-rules.md - Sem
<br>no texto do corpo; elementos transformados devem ser de nível bloco + dimensionados; decorações absolutas pulsantes precisam de folga de pico. →determinism-rules.md <video>/<audio>deve ser filho direto da raiz do host (nunca dentro de um<template>/wrapper de sub-comp); o framework é dono da reprodução. →variables-and-media.md- Cada
iddeve ser único em toda a página montada; dentro de uma sub-comp, prefixe ids com o id da composição (#<id>-hero). ids duplicados de<video>/<img>renderizam em branco — o produtor injeta quadros viagetElementById, e duplicatas entre arquivos passam despercebidas pelolint. →composition-patterns.md - Um preenchimento de cena em tela cheia vai em um filho de sangria total (
position:absolute; inset:0), nunca na 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 prévia/snapshotmostre 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.
- Corresponda IDs de composição e chaves de timeline existentes.
- Adicionando um clip: escolha um
data-track-indexnão sobreposto ou ajuste a temporização circundante intencionalmente. - Adicionando uma sub-composição: verifique seu
data-composition-idinterno antes de conectar o host.
Validação
Use hyperframes-cli para detalhes de comandos
-
npx hyperframes lintpassa (0 erros) -
npx hyperframes validatepassa (0 erros no console) -
npx hyperframes inspectpassa (0 erros) - Projetos com sub-composições:
npx hyperframes snapshot --at <midpoints>e inspecione visualmente cada quadro -
npx hyperframes previewpara revisão (o usuário pode editar qualquer coisa na timeline do Studio) -
npx hyperframes renderapenas após aprovação do usuário