hyperframes-core

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 e cuja reprodução de mídia é gerenciada pela framework.

Esta skill é 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 estão nas skills de domínio irmãs — hyperframes-animation, hyperframes-creative, media-use, hyperframes-cli, hyperframes-registry. O mapa de capacidades em /hyperframes diz o que cada uma cobre.

Referências

Arquivo	Leia para…
references/minimal-composition.md	começar pelo esqueleto de composição renderizável mínimo
references/composition-patterns.md	escolher entre monolítico vs modular; estruturar um index.html modular; escolher um arquétipo de sub-comp
references/data-attributes.md	consultar qualquer data-* (raiz / clipe / host de sub-comp / aliases legadas); usar class="clip"
references/tracks-and-clips.md	escolher data-track-index, lidar com sobreposição / z-index na mesma track, temporizar um clipe relativo a outro
references/creator-editing-recipes.md	copiar receitas verdadeiras de corte/aparar/reordenar/re-temporizar/congelar/câmera/máscara/cruzamento/áudio e seus limites
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, aparar
references/determinism-rules.md	construir uma linha do tempo buscável; proibições de determinismo; a lista de propriedades animáveis permitidas; layout / ajuste de texto
references/full-screen-motion.md	criar movimento em tela cheia com fundos compartilhados
references/storyboard-format.md	criar um plano STORYBOARD.md (+ o manifesto analisado)
references/review-loop.md	executar as passagens de revisão planejar → esboçar → construir em um quadro vivo — compartilhado por todo fluxo de planejamento de storyboard
references/production-loop.md	transformar um plano aprovado em um vídeo entregue — as dependências de estágio (áudio, quadros, montagem, transições, legendas, verificar, entregar) que uma construção livre segue diretamente
references/brief-contract.md	as regras básicas do brief — derivação de modo (colaborativo / autônomo), registro de campo compartilhado, invariantes de pergunta (a própria pergunta está em /hyperframes → a camada de intenção)
references/brief-format.md	criar BRIEF.md — o documento de intenção confirmada que o Setup de um fluxo de trabalho escreve e cada etapa posterior lê
references/script-format.md	criar o opcional SCRIPT.md com narração travada
references/subagent-dispatch.md	mapear verbos de despacho de subagente (fan-out paralelo / segundo plano / espera) para seu harness
references/frame-worker-core.md	o contrato de função do frame-worker compartilhado — o construtor de pacotes de cada fluxo de trabalho narrativo o anexa ao delta sub-agents/frame-worker.md desse fluxo
references/tailwind.md	trabalhar em um projeto Tailwind v4 (init --tailwind; o contrato de runtime difere do v3 do Studio)

Para especificações 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)

• Independente (index.html de nível superior) — o <div data-composition-id="…"> raiz fica diretamente no <body>, sem invólucro <template> (envolvê-lo esconde todo o conteúdo e quebra a renderização).
• Sub-composição (carregada via data-composition-src) — a raiz deve ser envolvida 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: o data-composition-id do slot do host deve ser exatamente igual ao data-composition-id do template interno e à chave window.__timelines["<id>"] — sem sufixo -mount/-slot/-host.

Forma do arquivo, conexão do host e a 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 dimensionada explicitamente (width/height em px), e todo ancestral até um elemento height:100% deve ter uma altura resolvida — caso contrário, um filho flex/100% colapsa para ~0 e o conteúdo se amontoa no canto superior esquerdo. Não confie apenas em portões automatizados para detectar isso; inspecione um instantâneo. Esqueleto → references/minimal-composition.md.

Uma timeline 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. A duração da renderização = data-duration raiz, não o comprimento da timeline. Não aninhe sub-timelines manualmente no host. Contrato completo (incluindo runtimes não-GSAP) → references/determinism-rules.md + hyperframes-animation/adapters/.

Pegadinhas de lint na primeira passagem (uma garantia de falha na primeira construção)

Duas regras que o lint captura, mas apenas depois do fato — escreva-as corretamente da primeira vez:

• O elemento de composição raiz deve conter data-start="0" (junto com data-composition-id/data-width/data-height); omiti-lo faz o lint falhar com root_composition_missing_data_start.
• Nunca emparelhe um transform CSS inicial com um tween GSAP na mesma propriedade — o valor CSS e o início do tween entram em conflito e o lint o rejeita com gsap_css_transform_conflict. Defina o estado inicial dentro do tween com gsap.fromTo(el, { x: -40 }, { x: 0 }) em vez de um CSS transform: translateX(-40px).

Regras inegociáveis (bugs silenciosos que portões automatizados podem perder)

Expõe-se aqui; a justificativa completa está na referência vinculada. Não viole:

• Sem relógios em tempo de renderização / Math.random não semeado / rede / estado de entrada; sem repeat: -1 (use uma contagem finita). → determinism-rules.md
• Anime apenas a lista de propriedades visuais permitidas; nunca crie tween em display ou visibility bruta. As únicas exceções de visibilidade são autoAlpha do GSAP e conjuntos de limite de timeline de duração zero, e apenas em elementos que não são clipes ou invólucros dentro de um clipe. A framework sozinha controla a visibilidade de .clip. Não use gsap.set em clipes de cenas posteriores no carregamento da página. → determinism-rules.md
• Sem <br> no corpo do texto; elementos transformados devem ser em nível de bloco + dimensionados; decorativos absolutos pulsantes precisam de folga de pico. → determinism-rules.md
• <video>/<audio> funcionam em qualquer profundidade de aninhamento (incluindo dentro de um <template> ou invólucro de sub-comp); a framework gerencia a reprodução e busca/decodifica a mídia onde quer que ela esteja. A única ressalva são as timelines, não o posicionamento: uma timeline de sub-comp não pode animar elementos raiz do host. → variables-and-media.md
• Cada id deve ser único em toda a página montada; dentro de uma sub-comp, prefixe os ids com o id da composição (#<id>-hero). IDs duplicados de <video>/<img> renderizam em branco — o produtor injeta quadros por getElementById, e duplicatas entre arquivos escapam do lint. → composition-patterns.md
• O preenchimento de uma cena em tela cheia vai em um filho sangrado (position:absolute; inset:0), nunca na própria raiz da composição — a composição de quadros do produtor pode descartar o background do próprio elemento raiz (o quadro renderiza preto) mesmo que a pré-visualização/snapshot o mostrem corretamente. → composition-patterns.md

Editando composições existentes

• Leia os arquivos primeiro. Preserve temporização, tracks, IDs, variáveis, caminhos de mídia não relacionados.
• Corresponda aos IDs de composição e chaves de timeline existentes.
• Adicionar um clipe: escolha um data-track-index não sobreposto ou ajuste a temporização circundante intencionalmente.
• data-hidden em qualquer elemento de composição o oculta TANTO na pré-visualização QUANTO na renderização, substituindo sua janela de tempo; é não destrutivo/reversível e alternado pelo ícone de olho da timeline do Studio.
• Adicionar uma sub-composição: verifique seu data-composition-id interno antes de conectar o host.

Validação

Use hyperframes-cli para detalhes do comando

• npx hyperframes check passa (0 descobertas em lint, runtime, layout, movimento e contraste)
• Projetos com sub-composições: npx hyperframes snapshot --at <midpoints> e examine visualmente cada quadro
• npx hyperframes preview --background para revisão (o usuário pode editar qualquer coisa na timeline do Studio, e o servidor sobrevive ao comando de invocação)
• npx hyperframes render apenas após a aprovação do usuário