Instalação de plugins: Antes de comandos de configuração ou atualização, siga as regras de execução de plugins quando este skill estiver dentro de um plugin HyperFrames. Instalações independentes mantêm as instruções de atualização abaixo.
HyperFrames Keyframes
Keyframes são um contrato de pose: estados visíveis, identidade contínua do sujeito, runtime seguro para busca, pixels verificados.
Use hyperframes-animation para receitas amplas de cena. 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 duros de intervalo de origem, trimming, emenda e reordenação pertencem ao /hyperframes-core: crie um elemento de mídia por intervalo mantido, posicione-o com data-start e data-duration, e selecione seu deslocamento de origem com data-media-start. Intervalos adjacentes formam um corte duro. 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 x/y ou translação percentual em um wrapper visual/crop sem timing dentro do clipe. Use um curtíssimo tween para um corte duro e um tween para um movimento suave. |
| Zoom ou reenquadramento multi-estado suave | Mantenha um wrapper de sujeito vivo e crie múltiplos estados de zoom/reenquadramento como uma escada de poses com easing por segmento. |
| Pan, reenquadramento ou movimento de câmera Ken Burns | Animar translação do wrapper mais escala. A geometria é criada; isso não é rastreamento facial ou reenquadramento semântico automático. |
| Movimentos de câmera em cadeia | Encadeie batidas de transformação rotuladas em uma timeline registrada segura para busca. |
| Corte de continuidade ou whip pan | /hyperframes-animation é dono do handoff visual; /hyperframes-registry fornece primitivas; keyframes preservam geometria, direção e velocidade criadas. Não há descoberta automática de quadros correspondentes. |
| Crop e reenquadramento com máscara | Interpole clip-path ou uma máscara em um wrapper visual interno para cortar/reenquadrar sem alterar o tempo de origem. Keyframes de polígono podem formar uma transição de polígono/máscara. |
| Corte direcional com wipe ou iris/revelação | Anime um limite de máscara/clip através de clipes visuais sobrepostos; /hyperframes-animation é dono da coreografia do handoff. |
| Handoff de tela dividida | Mantenha ambos os clipes visuais posicionados pelo core, então aplique keyframes em seus wrappers internos de crop/máscara e geometria do divisor. |
| Retiming constante de fonte | /hyperframes-core é dono de data-playback-rate normalizado (0.1..10) para imagem segura para render e som com preservação de pitch. É constante para todo o elemento de mídia. |
| Ramps de velocidade de fonte | Uma faixa rate em data-automation no <video>/<audio> (t em segundos do clipe, v 0.1..10, interpolação log); ela ganha da taxa constante. |
| Congelamento / hold | Uma pose visual, quadro final da fonte ou sub-composição finalizada pode segurar. Congelamento arbitrário no meio da fonte não é suportado; pré-processe um segmento estático/derivado, coloque-o como seu próprio clipe, depois retome com outro intervalo de fonte. |
Ao editar imagem e som juntos, carregue /hyperframes-core, este 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 corte temporal de fonte ou emenda. /hyperframes-core é dono da timeline, do timing dos clipes e dos intervalos de fonte; keyframes apenas animam o handoff visual 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 runtime.
- Escolha o menor mecanismo que prove o prompt. Leia
references/keyframe-patterns.mdapenas se o mecanismo não estiver claro. - Crie keyframes seguros para busca no runtime declarado. Registre a instância de runtime somente após a construção terminar; construir dentro de
document.fonts.readyé aceitável. - Verifique com
hyperframes check(executa lint),hyperframes keyframes, um--shotfocado e snapshots nos tempos de prova. - Se a prova falhar, corrija os keyframes de origem e reexecute o menor diagnóstico falho antes de renderizar.
Contrato
- Nomeie o sujeito em movimento.
- Nomeie as poses necessárias para provar o movimento pretendido, incluindo o estado final.
- Aplique keyframes em canais visíveis, não em estado oculto auxiliar.
- Preserve a identidade do objeto quando a continuidade importa.
- Use crossfade apenas quando o movimento pretendido for substituição ou dissolução.
- Mantenha estados legíveis ou semânticos por tempo suficiente para serem vistos.
- O quadro final faz parte da animação, não da limpeza.
- Não redefina para o estado de repouso a menos que solicitado.
- Não termine com 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 no carregamento da página ou dentro de
document.fonts.ready, e registre apenas após a construção terminar - use
gsap.timeline({ paused: true }) - registre como
window.__timelines[compositionId] - a chave do 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 timing pertencer a um clipe
Anime.js:
- crie sincronamente
autoplay: false- duração finita e loops
- empurre toda instância para
window.__hfAnime
WAAPI:
durationfinitafill: "both"- construção determinística
- a superfície de texto não lista WAAPI; verifique com
--shot(que busca WAAPI) e snapshots
Nunca use para movimento crítico de renderização:
Date.now()performance.now()Math.random()não semeado- gatilhos de hover/scroll
- timers
- uma timeline registrada antes de sua construção assíncrona terminar
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("state-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 rótulos para estados semânticos. Use parâmetros de posição em vez de atrasos encadeados. Use immediateRender: false para tweens from()/fromTo() posteriores que toquem a mesma propriedade.
Formas de Keyframe
- Array keyframes: escada de poses com duração/easing por passo.
- Percentage keyframes: timing exato dentro de um tween.
- Property arrays: mudanças multi-stop compactas.
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 timings dos exemplos. Derive-os da geometria e duração reais da composição.
Para um sujeito se movendo entre duas caixas, prefira um tween de transformação contínua ou FLIP. Divida x/y/scale em múltiplos keyframes com easing apenas quando o espectador deve sentir batidas distintas; cada segmento muda a velocidade e pode ser lido como um soluço.
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 do sujeito.
Para mudanças de visibilidade, use autoAlpha na timeline GSAP registrada e buscável, ou um tl.set() com duração zero em um limite explícito. Mire apenas um elemento que não seja de clipe ou um wrapper dentro do clipe; nunca mire o próprio .clip. Nunca faça tween de duração com 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 | shared element / FLIP |
| Sujeito percorre uma rota visível | path travel |
| Traço cresce ou traça | stroke draw |
| Forma se torna outra forma | shape interpolation |
| Limite de revelação é visível | clip, mask, ou shader uniform |
| Muitos itens se movem com ordem | stagger / indexed delay |
| Próprio texto se move | line, word, character, ou band subdivision |
| Superfície dobra, estica ou corta | parent/child counter-transform |
| UI tem estados | explicit state machine |
| Cena tem profundidade | DOM 3D, Three.js, ou WebGL camera/object keyframes |
Mecanismos podem combinar, mas cada um deve esclarecer a ideia. Decoração não é prova.
Timing
- Antecipação apenas quando esclarece causa ou direção.
- Aceleração deixa o repouso.
- Prova de pico mostra o mecanismo de forma inequívoca.
- Follow-through vende energia e direção.
- Overshoot apenas quando o sujeito deve parecer elástico ou tátil.
- Movimento de path em velocidade constante geralmente precisa de
ease: "none". - Estados discretos de UI geralmente precisam de um sharp ease-out.
- Elementos repetidos precisam de offsets ordenados, não timing idêntico.
- Finais bloqueados precisam de holds mais longos do que poses de transição.
- Suavidade significa velocidade contínua no mesmo sujeito.
- Não sobreponha tweens que escrevem a mesma propriedade de transformação, 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 herói também está escalando ou viajando; use revelações aninhadas após o movimento principal se estabelecer.
Texto
Preserve caixas de linha, espaçamento entre palavras, legibilidade e ajuste final. Se o texto se move internamente, mova os glifos ou bandas mascaradas, não apenas decorações ao redor do texto. Tire 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 em 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 angulada não mostrar cruzamento de profundidade, melhore z/câmera/oclusão.
Canvas / WebGL
Aplique keyframes em posição de câmera, alvo de câmera, transformação de objeto, opacidade de material, uniforms de shader e intensidade de pós-processamento através de estado determinístico. Renderize a partir do tempo do HyperFrames. Use --ghost porque caixas de marcador não podem ver movimento interno do canvas.
Prova CLI
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-hold, e final exato. Escolha <angle> apenas quando a profundidade deve ser provada.
| Ferramenta | Prova |
|---|---|
keyframes | alvos, paradas explícitas, paths, traços, movimento composto pai/filho, paradas CSS, registro Anime |
--shot | ghosts, forma da rota, espaçamento temporal, projeção 3D DOM, prova de seletor focado |
--layout strip | movimento no lugar, sobreposições, contato, escala/opacidade sutil, ondas de texto |
--ghost | canvas, WebGL, movimento de shader, 3D renderizado |
snapshot --at | máscaras, rastros, ocupação de tela, ossos, profundidade, identidade do sujeito |