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 é controlada pelo framework.
Este 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/ (index próximo), 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 diz o que cada um 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 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 / anfitrião 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 trilha, temporizar um clipe em relação a outro |
references/sub-compositions.md | conectar uma sub-composição (atributos do anfitrião, <template>, vars por instância) e animar dentro dela |
references/variables-and-media.md | declarar variáveis; colocar <video>/<audio>, definir volume, cortar |
references/determinism-rules.md | construir uma linha do tempo buscável; proibições de determinismo; a lista de permissão de propriedades animáveis; layout / ajuste de texto |
references/full-screen-motion.md | criar movimento de 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 ao 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 brief — derivação de modo (colaborativo / autônomo), registro de campos compartilhados, invariantes de pergunta (o próprio questionamento vive em /hyperframes → a camada de intenção) |
references/brief-format.md | criar BRIEF.md — o documento de intenção confirmado que o Setup de um fluxo de trabalho escreve e cada passo 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 / espera) para seu harness |
references/frame-worker-core.md | o contrato compartilhado de função de frame-worker — cada construtor de pacote de fluxo narrativo o anexa 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 v3 do Studio) |
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)
- Autônoma (
index.htmlde 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 conteúdos de
<template>; tudo fora (incluindo estilos/scripts de<head>) é descartado — coloque<style>/<script>dentro do template. ⚠ Regra de ID do anfitrião: odata-composition-iddo slot anfitrião deve ser exatamente igual aodata-composition-iddo template interno e à chavewindow.__timelines["<id>"]— sem sufixo-mount/-slot/-host.
Forma do arquivo, conexão do anfitrião e checklist de pré-renderização → references/sub-compositions.md.
A raiz deve ser dimensionada (bug de layout silencioso)
A raiz autônoma 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 pegar 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 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 sub-linhas do tempo no anfitrião. Contrato completo (incl. runtimes não-GSAP) → references/determinism-rules.md + hyperframes-animation/adapters/.
Pegadinhas do lint na primeira passagem (falha garantida na primeira construção)
Duas regras que o lint pega, mas apenas depois do fato — escreva-as corretamente da primeira vez:
- O elemento de composição raiz deve carregar
data-start="0"(junto comdata-composition-id/data-width/data-height); omiti-lo faz olintfalhar comroot_composition_missing_data_start. - Nunca emparelhe um
transformCSS inicial com um tween GSAP na mesma propriedade — o valor CSS e o início do tween brigam e olintrejeita comgsap_css_transform_conflict. Defina o estado inicial dentro do tween comgsap.fromTo(el, { x: -40 }, { x: 0 })em vez de um CSStransform: translateX(-40px).
Regras inegociáveis (bugs silenciosos que portões automatizados podem perder)
Expadas aqui; justificativa completa na referência vinculada. Não viole:
- Sem relógios em tempo de renderização /
Math.randomnão seedado / rede / estado de entrada; semrepeat: -1(use uma contagem finita). →determinism-rules.md - Anime apenas a lista de permissão de propriedades visuais; nunca aplique tween em
displayouvisibilitybruto.autoAlphado 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 não-clip ou wrappers dentro de um clip. O framework sozinho controla a visibilidade de.clip. Não façagsap.setem clipes de cena posterior no carregamento da página. →determinism-rules.md - Sem
<br>em texto do corpo; elementos transformados devem ser 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 wrapper de sub-comp); o framework controla 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: a linha do tempo de uma sub-comp não pode animar elementos raiz do anfitriã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 porgetElementById, e duplicatas entre arquivos escapam dolint. →composition-patterns.md - Um preenchimento de cena de 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é-visualização/snapshotmostre-o corretamente. →composition-patterns.md
Editando composições existentes
- Leia os arquivos primeiro. Preserve temporização, trilhas, IDs, variáveis, caminhos de mídia não relacionados.
- Combine IDs de composição e chaves de linha do tempo existentes.
- Adicionando um clipe: escolha um
data-track-indexsem sobreposição ou ajuste a temporização circundante intencionalmente. data-hiddenem 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-idinterno antes de conectar o anfitrião.
Validação
Use hyperframes-cli para detalhes de comando
-
npx hyperframes checkpassa (0 descobertas em lint, runtime, layout, motion e contraste) - Projetos com sub-composições:
npx hyperframes snapshot --at <midpoints>e examine cada quadro -
npx hyperframes previewpara revisão (o usuário pode editar qualquer coisa na linha do tempo do Studio) -
npx hyperframes renderapenas após o usuário aprovar