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 é controlada pelo framework.
Este skill é o contrato técnico. Outros tópicos residem em skills irmãos:
hyperframes-animation— regras de movimento atômico + blueprints de cena + adaptadores por runtime (GSAP, Lottie, Three, Anime.js, CSS, WAAPI, TypeGPU)hyperframes-creative— paletas, tipografia, narração, planejamento de batida, áudio-reativohyperframes-media— TTS, transcrição Whisper, remoção de fundo, legendashyperframes-registry— instalar blocos e componentes (hyperframes add)hyperframes-cli— comandos do ciclo de desenvolvimento (lint / validate / preview / render)
Para projetos Tailwind v4 (hyperframes init --tailwind), consulte references/tailwind.md — o contrato de runtime do navegador é distinto da configuração Tailwind v3 do Studio.
Roteamento
| Se você deseja… | Leia |
|---|---|
| Ver uma composição mínima renderizável | references/minimal-composition.md |
| Decidir entre arquitetura monolítica de arquivo único e modular com sub-composições | references/composition-patterns.md |
Estruturar um index.html modular (orquestrador + slots + áudio raiz) | references/composition-patterns.md |
| Escolher um arquétipo de sub-comp (conteúdo / somente driver / mesclagem multi-cena / áudio-reativo) | references/composition-patterns.md |
Consultar um atributo data-* (raiz, clipe, host de sub-comp, aliases legados) | references/data-attributes.md |
Usar class="clip" corretamente | references/data-attributes.md |
Escolher um data-track-index; sobreposição na mesma faixa; track-index vs CSS z-index | references/tracks-and-clips.md |
Temporizar um clipe relativo a outro (data-start="intro + 2", sobreposição de crossfade, cadeias) | references/tracks-and-clips.md |
Conectar uma sub-composição (atributos do host, wrapper <template>, variáveis por instância) | references/sub-compositions.md |
Animar dentro de uma sub-composição (gsap.fromTo em vez de gsap.from, comportamento de seek-back) | references/sub-compositions.md |
Declarar variáveis (tipos, opções extras, padrões, --strict-variables no CI) | references/variables-and-media.md |
Colocar <video> / <audio>, definir volume, cortar com data-media-start | references/variables-and-media.md |
Construir uma linha do tempo buscável (pausada, construção síncrona, armadilha gsap.set em cena posterior) | references/determinism-rules.md |
Evitar estado não determinístico (relógios, Math.random, repeat: -1, fórmula finita de repetição) | references/determinism-rules.md |
Saber o que pode / não pode ser animado (lista de permissão de propriedades visuais; não display/visibility) | references/determinism-rules.md |
Ajustar texto e evitar transbordamento (fitTextFontSize assinatura, regra <br>, contrato de layout) | references/determinism-rules.md |
| Criar movimento em tela cheia com fundos compartilhados | references/full-screen-motion.md |
Trabalhar em um projeto Tailwind v4 (init --tailwind) | references/tailwind.md |
Para detalhes específicos de runtime de animação (API GSAP, Lottie, Three.js, etc.) vá para hyperframes-animation → adapters/<runtime>.md.
Estrutura da Composição
Duas formas raiz; elas não são intercambiáveis.
- Independente (o
index.htmlde nível superior) —<div data-composition-id="…">raiz fica diretamente em<body>. Sem wrapper<template>. Envolver uma raiz independente em<template>esconde todo o conteúdo do navegador e quebra a renderização. - Sub-composição (um arquivo carregado via
data-composition-src) —<div data-composition-id="…">raiz deve ser envolvida em<template>. Sem o wrapper, o runtime não consegue extraí-la e montá-la.
⚠ Regra de transporte de sub-composição: o runtime apenas clona conteúdos de
<template>para o DOM ao vivo. Tudo fora do template — incluindo<head>e quaisquer blocos<style>/<script>/<link>que estejam em<head>— é descartado. Coloque blocos<style>e<script>dentro de<template>, não em<head>.⚠ Regra de ID do host: no arquivo host,
data-composition-idno slot deve corresponder exatamente aodata-composition-iddo template interno e à chavewindow.__timelines["<id>"]. Não adicione sufixos-mount/-slot/-host.
Consulte references/sub-compositions.md para a forma do arquivo, conexão do host, exemplos de armadilhas e a lista de verificação de pré-renderização.
A raiz deve ser dimensionada (bug de layout silencioso)
A raiz independente deve estabelecer uma caixa explicitamente dimensionada, e cada ancestral entre ela e um elemento height: 100% deve ter uma altura resolvida. Se a raiz ou um wrapper intermediário não tiver altura, um contêiner de conteúdo flex/height:100% colapsa para ~0 e o conteúdo se acumula no canto superior esquerdo (frequentemente cortando o primeiro glifo em x=0). lint, validate e inspect não detectam isso — inspect substitui o data-width/data-height original por uma raiz colapsada e relata "0 problemas de layout".
<body style="margin: 0">
<div
id="root"
data-composition-id="main"
data-width="1920"
data-height="1080"
data-duration="5"
style="position: relative; width: 1920px; height: 1080px; overflow: hidden"
>
<!-- Centralize robustamente: position:absolute + inset:0 preenche a raiz dimensionada independentemente de
wrappers intermediários; ou use um contêiner flex APENAS se sua cadeia pai estiver dimensionada. -->
<section
class="clip"
data-start="0"
data-duration="5"
data-track-index="1"
style="position: absolute; inset: 0; display: grid; place-items: center; padding: 120px 160px; box-sizing: border-box"
>
<h1>Título</h1>
</section>
</div>
</body>
Mantenha o padding (≥80px) no contêiner de centralização — é a margem de segurança do título que impede que texto grande toque a borda do quadro. Consulte references/minimal-composition.md.
Contrato de Linha do Tempo (padrão GSAP)
Cada composição registra exatamente uma linha do tempo GSAP.
- Crie com
gsap.timeline({ paused: true })— o player controla a reprodução. - Registre em
window.__timelines["<composition-id>"]; a chave deve corresponder exatamente aodata-composition-idda raiz. A sintaxe de ponto (window.__timelines.<id> = tl) é equivalente quando o id é um identificador válido; use colchetes se o id contiver-. - Construa a linha do tempo sincronamente durante o carregamento da página — não dentro de
async,setTimeout,Promiseou manipuladores de eventos. O renderizador amostra após o carregamento da página estar completo; qualquer construção de linha do tempo adiada perde a amostra. - A duração da renderização vem de
data-durationna raiz, não do comprimento da linha do tempo GSAP. Não preencha a linha do tempo com tweens vazios para definir a duração. - Para sub-composições, não aninhe manualmente sub-linhas do tempo no host (
master.add(sub)); o framework as controla independentemente.
Para runtimes não-GSAP (Lottie / Three / WAAPI / CSS / Anime.js / TypeGPU), o contrato equivalente está em hyperframes-animation/adapters/<runtime>.md. Consulte references/determinism-rules.md para o Contrato de Runtime de Animação entre runtimes.
Regras Inegociáveis
Estas quebram o renderizador — ou produzem bugs visuais silenciosos que lint/validate/inspect NÃO detectam (regras 3, 7-8). (A construção síncrona da linha do tempo está coberta acima em Contrato de Linha do Tempo.)
- Nada de
Math.random()/Date.now()/performance.now()controlando visuais — use um PRNG com semente. - Nada de
repeat: -1. Userepeat: Math.max(0, Math.floor(duration / cycleDuration) - 1)—floor, nãoceil(ceilultrapassadata-duratione aciona o lintgsap_repeat_ceil_overshoot;max(0, …)evita um repeat negativo = infinito). <video>/<audio>deve ser filho direto da raiz do host (index.html) — nunca dentro de um<template>de sub-comp, nunca dentro de um<div>wrapper; caso contrário, nunca é decodificado e renderiza em branco/preto (silencioso). O framework controla a reprodução: nada devideo.play()/audio.play()/currentTime = …. Uma sub-comp não pode controlar elementos do host (seletor ouquerySelector), então anime a mídia do host a partir da linha do tempo principal no tempo global. Consultereferences/variables-and-media.md.- Nada de
gsap.set()em elementos de clipe de cenas posteriores (eles ainda não estão no DOM). Usetl.set(selector, vars, time)no ou após odata-startdo clipe. - Nada de animar
display/visibility. Animeopacity/ transformações; o ciclo de vida do clipe lida com mostrar/esconder. - Nada de
<br>no texto do corpo. Deixe o texto quebrar viamax-width. - Elementos transformados devem estar em nível de bloco + dimensionados.
transform/scaleX/scaleYé inoperante em um<span>inline, e dimensionar um elemento com largura automática (0px) não mostra nada → barras/preenchimentos invisíveis. Dê a elesdisplay: block/inline-block/flex-item e umawidth/heightreal (ex.,width: 100%dentro de um pai dimensionado). - Decorativos posicionados absolutamente (emblemas, pílulas, tags) que pulsam ou excedem (
yoyoscale,back.out) precisam de folga em seu tamanho máximo e não devem cruzar uma bordaoverflow: hidden— caso contrário, sobrepõem um vizinho ou são cortados. Posicione para o maior quadro, não o de repouso.
Editando Composições Existentes
- Leia os arquivos reais antes de editar.
- Preserve temporização, faixas, IDs, variáveis e caminhos de mídia não relacionados.
- Corresponda IDs de composição existentes e chaves de registro de linha do tempo.
- Ao adicionar um clipe, escolha um
data-track-indexnão sobreposto ou ajuste intencionalmente a temporização ao redor. - Ao adicionar 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 de console) -
npx hyperframes inspectpassa, ou o transbordamento é intencionalmente marcado - Projetos com sub-composições:
npx hyperframes snapshot --at <midpoints>e inspecione cada quadro visualmente