Keyframes HyperFrames
Keyframes são um contrato de pose: estados visíveis, identidade contínua do sujeito, execução segura para seek, pixels verificados.
Use hyperframes-animation para receitas de cena amplas. Use hyperframes-cli para documentação completa de comandos. Use references/keyframe-patterns.md apenas ao escolher mecanismos de implementação, não estilo visual.
Limite de edição do criador
Keyframes controlam movimento visual, não montagem de clipes. Cortes secos de intervalo de origem, trim, splice e reordenação pertencem a /hyperframes-core: autorize um elemento de mídia por intervalo mantido, coloque-o com data-start e data-duration, e selecione seu deslocamento de origem com data-media-start. Intervalos adjacentes formam um corte seco. Um crossfade usa clipes sobrepostos em trilhas diferentes mais keyframes de opacidade visual; fades de som usam /hyperframes-audio.
| Solicitação do criador | Mecanismo verdadeiro |
|---|---|
| Punch-in / punch-out | Keyframe scale com translação x/y ou percentual em um wrapper visual/crop não temporal dentro do clipe. Use um tween curto/definido para um punch brusco e um tween para um movimento suave. |
| Zoom ou reframe suave de vários estados | Mantenha um wrapper de sujeito ativo e autorize vários estados de zoom/reframe como uma escada de pose com easing por segmento. |
| Pan, reframe, ou movimento de câmera Ken Burns | Anime a translação do wrapper mais a escala. A geometria é autorizada; isso não é rastreamento facial ou reframing semântico automático. |
| Movimentos de câmera encadeados | Encadeie beats de transformação rotulados em uma timeline registrada e segura para seek. |
| Corte de correspondência ou whip pan | /hyperframes-animation controla o handoff visual; /hyperframes-registry fornece primitivas; keyframes preservam geometria, direção e velocidade autorizadas. Não há descoberta automática de quadros de correspondência. |
| Reframe com crop e máscara | Interpole clip-path ou uma máscara em um wrapper visual interno para cortar/reframear sem alterar o tempo de origem. Keyframes de polígono podem formar uma transição de polígono/máscara. |
| Corte de wipe direcional ou corte íris/revelação | Anime um limite de máscara/clip entre clipes visuais sobrepostos; /hyperframes-animation controla a coreografia do handoff. |
| Handoff de tela dividida | Mantenha ambos os clipes visuais colocados pelo core, então aplique keyframes em seus wrappers internos de crop/máscara e na geometria do divisor. |
| Retiming constante de origem | /hyperframes-core controla data-playback-rate normalizado (0.1..10) para imagem segura para render e som com preservação de tom. É constante para todo o elemento de mídia. |
| Rampas de velocidade de origem | Uma faixa rate em data-automation no <video>/<audio> (t em segundos de clipe, v 0.1..10, interpolação log); ela prevalece sobre a taxa constante. |
| Congelamento / pausa | Uma pose visual, quadro de origem final ou subcomposição concluída pode pausar. Congelamento arbitrário no meio da origem não é suportado; pré-processe um segmento estático/derivado, coloque-o como seu próprio clipe e depois retome com outro intervalo de origem. |
Ao editar imagem e som juntos, carregue /hyperframes-core, esta skill para movimento visual e /hyperframes-audio para fades, crossfades, automação de volume, ducking/carve, ou efeitos nas trilhas posicionadas.
Uma transição visual ou tratamento de crop não é um trim ou splice temporal de origem. /hyperframes-core controla a timeline, o tempo do clipe e os intervalos de origem; keyframes apenas animam o handoff visível ou crop em wrappers dentro desses clipes. Para receitas combinadas de imagem/som copiáveis, use /hyperframes-core → references/creator-editing-recipes.md.
Procedimento
- Identifique o sujeito animado, estados visíveis, estado final e tempo de execução.
- Escolha o menor mecanismo que prove o prompt. Leia
references/keyframe-patterns.mdapenas se o mecanismo não estiver claro. - Autorize keyframes seguros para seek no tempo de execução declarado. Construa de forma síncrona e registre a instância de runtime.
- Verifique com
hyperframes lint,hyperframes check,hyperframes keyframes, um--shotfocado e snapshots nos tempos de prova. - Se a prova falhar, corrija os keyframes de origem e execute novamente o menor diagnóstico de falha antes de renderizar.
Contrato
- Nomeie o sujeito em movimento.
- Nomeie as poses necessárias para provar o movimento pretendido, incluindo o estado final.
- Keyframe canais visíveis, não estado auxiliar oculto.
- Preserve a identidade do objeto quando a continuidade for importante.
- Faça crossfade apenas quando o movimento pretendido for substituição ou dissolução.
- Mantenha estados legíveis ou semânticos tempo suficiente para serem vistos.
- O quadro final faz parte da animação, não da limpeza.
- Não retorne ao repouso a menos que solicitado.
- Não termine no preto a menos que solicitado.
- Se estiver editando uma cena inicial, preserve layout, cópia, assets, cores e estado final a menos que seja solicitado a redesenhar.
Regras de Runtime
GSAP:
- construa de forma síncrona no carregamento da página
- use
gsap.timeline({ paused: true }) - registre como
window.__timelines[compositionId] - a chave de registro deve corresponder a
data-composition-id - não chame
tl.play()para movimento crítico de renderização - mantenha repetições finitas
CSS keyframes:
- duração finita e contagem de iterações
- atraso determinístico
animation-fill-mode: both- use
data-startquando o tempo pertence a um clipe
Anime.js:
- crie de forma síncrona
autoplay: false- duração finita e loops
- envie cada instância para
window.__hfAnime
WAAPI:
durationfinitafill: "both"- construção determinística
- a superfície de texto não lista WAAPI; verifique com
--shot(ele busca WAAPI) e snapshots
Nunca use para movimento crítico de renderização:
Date.now()performance.now()Math.random()sem semente- gatilhos de hover/scroll
- timers
- timelines criadas de forma assíncrona
requestAnimationFramenão registrado- loops infinitos
Esqueleto GSAP
const root = document.querySelector("[data-composition-id]");
const compositionId = root.dataset.compositionId;
const tl = gsap.timeline({ paused: true });
tl.addLabel("estado-a", 0);
tl.to(".subject", {
keyframes: [
{ x: 0, opacity: 1, duration: 0.2 },
{ x: 120, opacity: 1, duration: 0.4, ease: "power2.out" },
{ x: 100, opacity: 1, duration: 0.2, ease: "power2.inOut" },
],
ease: "none",
});
window.__timelines = window.__timelines || {};
window.__timelines[compositionId] = tl;
Use labels para estados semânticos. Use parâmetros de posição em vez de delays encadeados. Use immediateRender: false para tweens from()/fromTo() posteriores que toquem na mesma propriedade.
Formas de Keyframe
- Keyframes de array: escada de pose com duração/easing por etapa.
- Keyframes percentuais: temporização exata dentro de um tween.
- Arrays de propriedades: mudanças compactas de várias paradas.
ease: "none"no pai quando cada parada carrega seu próprio easing.easeEachquando cada segmento deve compartilhar a mesma sensação.
Não copie distâncias numéricas ou temporizações dos exemplos. Derive-as da geometria real da composição e duração.
Para um sujeito se movendo entre duas caixas, prefira um tween de transformação contínua ou FLIP. Divida x/y/scale em vários keyframes com easing apenas quando o visualizador deve sentir beats distintos; cada segmento muda a velocidade e pode ser lido como uma pausa.
Canais
Prefira canais de compositor/visual: x/y/z, xPercent/yPercent, scale, rotationX/Y/Z, skew, transformOrigin, svgOrigin, opacity, autoAlpha, clip-path, máscaras, variáveis CSS, valores de path/dash SVG, transformações de câmera, uniforms de shader.
Evite canais de layout/ciclo de vida: top/left/right/bottom, width/height, margin/padding, display, visibility, criação tardia de DOM, overlays auxiliares fazendo movimento de sujeito.
Para mudanças de visibilidade, use autoAlpha na timeline GSAP registrada e buscável, ou um tl.set() de duração zero em um limite explícito. Mire apenas em um elemento não-clip ou um wrapper dentro do clipe; nunca mire o próprio .clip. Nunca faça tween de duração em visibility bruto e nunca faça tween de display.
Escolha de Mecanismo
Escolha o menor mecanismo que prove o prompt:
| Necessidade | Mecanismo |
|---|---|
| Mesmo sujeito muda de caixa ou hierarquia | elemento compartilhado / FLIP |
| Sujeito percorre uma rota visível | path travel |
| Traço cresce ou traça | stroke draw |
| Forma se torna outra forma | interpolação de forma |
| Limite de revelação é visível | clip, máscara, ou uniform de shader |
| Muitos itens se movem com ordem | stagger / índice atrasado |
| O próprio texto se move | subdivisão de linha, palavra, caractere ou banda |
| Superfície dobra, estica ou corta | contra-transformação pai/filho |
| UI tem estados | máquina de estado explícita |
| Cena tem profundidade | DOM 3D, Three.js, ou keyframes de câmera/objeto WebGL |
Mecanismos podem se combinar, mas cada um deve esclarecer a ideia. Decoração não é prova.
Temporização
- Antecipação apenas quando esclarece causa ou direção.
- Aceleração deixa o repouso.
- Pico de prova mostra o mecanismo inequivocamente.
- Follow-through vende energia e direção.
- Overshoot apenas quando o sujeito deve parecer elástico ou tátil.
- Path travel de velocidade constante geralmente precisa de
ease: "none". - Estados discretos de UI geralmente precisam de um ease-out brusco.
- Elementos repetidos precisam de deslocamentos ordenados, não temporização idêntica.
- Lockups finais precisam de pausas mais longas do que poses de transição.
- Suavidade significa velocidade contínua no mesmo sujeito.
- Não sobreponha tweens que escrevem a mesma propriedade de transform, a menos que a sobreposição seja intencional e verificada.
- Evite animar grandes mudanças de
clip-path/máscara enquanto a mesma superfície hero também está escalando ou viajando; use revelações aninhadas após o movimento principal se estabilizar.
Texto
Preserve caixas de linha, espaçamento entre palavras, legibilidade e ajuste final. Se o texto se mover internamente, mova os glifos ou faixas mascaradas, não apenas decorações ao redor do texto. Faça snapshot de quadros legíveis.
SVG
Para crescimento de traço, prefira DrawSVGPlugin, depois stroke-dasharray/stroke-dashoffset. Para interpolação de forma, prefira MorphSVGPlugin; converta primitivas para paths quando necessário e divida silhuetas complexas em partes mais simples.
3D
Escala sozinha é profundidade falsa. Use perspectiva em um pai estável, transform-style: preserve-3d, viagem em z, rotação, movimento de câmera/mundo, oclusão e ordem de camada quando objetos se cruzam.
Use um ou dois ângulos de diagnóstico que exponham a relação de profundidade. Se a prova em ângulo não mostrar cruzamento de profundidade, melhore z/câmera/oclusão.
Canvas / WebGL
Keyframe a posição da câmera, alvo da câmera, transformação do objeto, opacidade do material, uniforms de shader e intensidade de pós-processamento por meio de estado determinístico. Renderize a partir do tempo HyperFrames. Use --ghost porque as caixas de marcador não podem ver o movimento interno do canvas.
Prova CLI
npx hyperframes lint
npx hyperframes check
npx hyperframes keyframes .
npx hyperframes keyframes . --json
npx hyperframes keyframes . --runtime all
npx hyperframes keyframes . --selector "<selector>" --shot "<file>" --samples <n>
npx hyperframes keyframes . --selector "<selector>" --shot "<file>" --layout strip --from <t0> --to <t1>
npx hyperframes keyframes . --shot "<file>" --ghost --angle <angle>
npx hyperframes snapshot . --at <times>
Escolha <selector> para o sujeito animado real. Escolha <times> para primeiro quadro, poses de prova, final-menos-pausa e final exato. Escolha <angle> apenas quando a profundidade deve ser provada.
| Ferramenta | Prova |
|---|---|
keyframes | alvos, paradas explícitas, paths, traços, movimento pai/filho composto, paradas CSS, registro Anime |
--shot | fantasmas, forma da rota, espaçamento de tempo, projeção DOM 3D, prova de seletor focado |
--layout strip | movimento in-loco, sobreposições, contato, escala/opacidade sutis, ondas de texto |
--ghost | canvas, WebGL, movimento de shader, 3D renderizado |
snapshot --at | máscaras, legibilidade de texto, estado completo, lockup final, caudas pretas/reset |
Se a prova do seletor parecer errada:
- execute novamente
--json - encontre o alvo animado real
- fotografe esse alvo
- faça snapshot de quadros completos
- confie em pixels pintados sobre logs
Leitura de Diagnóstico
flat significa sem poses intermediárias explícitas. keyframes significa que existem paradas explícitas. m...