Drama2557/4RealDigital-Video-Studio

HyperFrames Core

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 pertence ao 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 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 / clipe / hospedeiro 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 clipe em relação a outro
references/sub-compositions.md	conectar uma sub-composição (atributos do hospedeiro, <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 permissões de propriedades animáveis; 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 etapas de revisão plano → esboço → construção em um quadro vivo — compartilhado por todo fluxo de planejamento de storyboard
references/production-loop.md	levar um plano aprovado a um vídeo entregue — as dependências de estágio (áudio, quadros, montagem, transições, legendas, verificar, entregar) uma construção livre segue diretamente
references/brief-contract.md	as regras básicas do briefing — derivação de modo (colaborativo / autônomo), registro de campos compartilhados, invariantes de perguntas (a pergunta em si vive em /hyperframes → a camada de intenção)
references/brief-format.md	criar o BRIEF.md — o documento de intenção confirmada que a Configuração de um fluxo de trabalho escreve e cada etapa posterior lê
references/script-format.md	criar a narração travada opcional SCRIPT.md
references/subagent-dispatch.md	mapear verbos de despacho de subagentes (fan-out paralelo / background / wait) para seu harness
references/frame-worker-core.md	o contrato compartilhado do papel de frame-worker — o construtor de pacotes de cada fluxo narrativo o antepõe ao delta sub-agents/frame-worker.md daquele fluxo
references/tailwind.md	trabalhar em um projeto Tailwind v4 (init --tailwind; o contrato de runtime difere do Studio v3)

Para especificidades de 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)

• Standalone (index.html de nível superior) — data-composition-id="…" 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 envolta 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 hospedeiro: o data-composition-id do slot hospedeiro 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 hospedeiro e checklist de pré-renderização → references/sub-compositions.md.

Raiz deve ser dimensionada (bug de layout silencioso)

A raiz standalone 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 portões automatizados 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 = raiz data-composition-id), construída sincronamente no carregamento da página. Duração da renderização = raiz data-duration, não comprimento da linha do tempo. Não aninhe manualmente sub-linhas do tempo no hospedeiro. Contrato completo (incl. runtimes não-GSAP) → references/determinism-rules.md + hyperframes-animation/adapters/.

Pegadinhas de primeira passada de lint (garantia de primeira falha de build)

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

• O elemento de composição raiz deve carregar 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 não negociáveis (bugs silenciosos que portões automatizados podem perder)

Expadas aqui; fundamentação completa na referência vinculada. Não viole:

• Sem relógios em tempo de renderização / Math.random sem semente / rede / estado de entrada; sem repeat: -1 (use uma contagem finita). → determinism-rules.md
• Anime apenas a lista de permissões de propriedades visuais; nunca tween display ou visibility bruto. autoAlpha do GSAP e conjuntos de limites de linha do tempo de duração zero são as únicas exceções de visibilidade, e apenas em elementos não-clipe ou wrappers dentro de um clipe. O framework sozinho controla a visibilidade de .clip. Não faça gsap.set de clipes de cena posterior no carregamento da página. → determinism-rules.md
• Sem <br> em texto do corpo; elementos transformados devem ser de nível de bloco + dimensionados; decorações absolutas 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-comp); o framework possui a reprodução e busca/decodifica a mídia onde quer que ela viva. A única ressalva são as linhas do tempo, não o posicionamento: uma linha do tempo de sub-comp não pode animar elementos da raiz do hospedeiro. → variables-and-media.md
• Cada id deve 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 por getElementById, e duplicatas entre arquivos passam despercebidas pelo lint. → 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 o background do próprio elemento raiz (o quadro renderiza preto) mesmo que a pré-visualização/snapshot mostre-o corretamente. → composition-patterns.md

Editando composições existentes

• Leia os arquivos primeiro. Preserve temporização não relacionada, faixas, IDs, variáveis, caminhos de mídia.
• Combine 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 circundante intencionalmente.
• data-hidden em qualquer elemento de composição o esconde 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 linha do tempo do Studio.
• Adicionando uma sub-composição: verifique seu data-composition-id interno antes de conectar o hospedeiro.

Validação

Use hyperframes-cli para detalhes de comando

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