topcheer/ggcode

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 pelo framework.

Este skill é o contrato técnico — como construir um projeto do HyperFrames. O corpo abaixo é o guia de construção; detalhes por tópico estão em references/ (índice abaixo), leia sob demanda. Outras preocupações estão nos skills de domínio irmãos — hyperframes-animation, hyperframes-creative, media-use, hyperframes-cli, hyperframes-registry. O mapa de capacidades em /hyperframes informa o que cada um cobre.

Referências

Arquivo	Leia para…
references/minimal-composition.md	começar a partir do 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 sub-composição
references/data-attributes.md	consultar qualquer data-* (raiz / clip / 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 faixa, temporizar um clipe em relação 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
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 animação 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 plano → esboço → construção em um quadro vivo — compartilhado por todos os fluxos 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 campos compartilhados, invariantes de pergunta (a própria pergunta está em /hyperframes → camada de intenção)
references/brief-format.md	criar BRIEF.md — o documento de intenção confirmada que o Setup de um fluxo escreve e cada etapa posterior lê
references/script-format.md	criar a SCRIPT.md opcional, com narração fixa
references/subagent-dispatch.md	mapear verbos de despacho de subagentes (fan-out paralelo / background / 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 narrativo o prefixa ao delta desse fluxo em sub-agents/frame-worker.md
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)

• Independente (index.html de nível superior) — <div data-composition-id="…"> raiz fica diretamente em <body>, sem wrapper <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 <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 lista de verificação pré-renderização → references/sub-compositions.md.

A raiz deve ter tamanho (bug de layout silencioso)

A raiz independente precisa de uma caixa dimensionada explícita (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. Não confie apenas em verificações automatizadas para detectar isso; inspecione um snapshot. 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 da raiz), construída sincronamente no carregamento da página. Duração da renderização = data-duration da raiz, não comprimento da linha do tempo. 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 verificações automatizadas podem perder)

Listadas aqui; justificativa completa 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 anime display ou visibility bruta. autoAlpha do GSAP e conjuntos de limite de linha do tempo de duração zero são as únicas exceções de visibilidade, e apenas em elementos que não são clipe ou wrappers dentro de um clipe. Somente o framework 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> em texto do corpo; elementos transformados devem ser de nível de bloco + dimensionados; elementos 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 wrapper de sub-composição); o framework gerencia a reprodução e busca/decodifica a mídia onde quer que ela esteja. A única ressalva são as linhas do tempo, não o posicionamento: uma linha do tempo de sub-composição 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-composição, prefixe 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 visualização/snapshot mostre 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 linha do tempo existentes.
• Adicionando um clipe: escolha um data-track-index não sobreposto ou ajuste a temporização ao redor intencionalmente.
• data-hidden em qualquer elemento de composição o oculta TANTO na visualização QUANTO na renderização, substituindo sua janela de tempo; é não destrutivo/reversível e alternado pelo ícone de olho da linha do tempo do Studio.
• Adicionando uma sub-composição: verifique seu data-composition-id interno antes de conectar o host.

Validação

Use hyperframes-cli para detalhes de comando

• npx hyperframes check passa (0 descobertas entre lint, runtime, layout, movimento e contraste)
• Projetos com sub-composições: npx hyperframes snapshot --at <midpoints> e inspecione cada quadro manualmente
• npx hyperframes preview para revisão (o usuário pode editar qualquer coisa na linha do tempo do Studio)
• npx hyperframes render somente após o usuário aprovar