heygen-com/hyperframes

Instalação de plugins: Antes dos 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 poses: estados visíveis, identidade contínua do sujeito, tempo seguro para busca, 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 o movimento visual, não a montagem de clipes. Cortes diretos na fonte, cortes, remontagem 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 direto. 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 não temporizado dentro do clipe. Use um tween curto/configurado para um punch forte e um tween para um movimento suave.
Zoom ou reframe suave com múltiplos estados	Mantenha um wrapper de sujeito ativo e crie múltiplos estados de zoom/reframe como uma escada de poses com easing por segmento.
Pan, reframe ou movimento de câmera Ken Burns	Animar translação do wrapper mais escala. A geometria é autorada; isso não é rastreamento facial ou reframe semântico automático.
Movimentos de câmera encadeados	Encadeie marcadores de transformação rotulados em uma linha do tempo registrada e segura para busca.
Match cut ou whip pan	/hyperframes-animation gerencia a transição visual; /hyperframes-registry fornece primitivas; keyframes preservam geometria, direção e velocidade autoradas. Não há descoberta automática de quadros correspondentes.
Crop e reframe com máscara	Interpole clip-path ou uma máscara em um wrapper visual interno para cortar/reframe sem alterar o tempo da fonte. Keyframes de polígono podem formar uma transição de polígono/máscara.
Corte de wipe direcional ou corte de íris/revelação	Anime um limite de máscara/clipe em clipes visuais sobrepostos; /hyperframes-animation gerencia a coreografia da transição.
Transição de tela dividida	Mantenha ambos os clipes visuais posicionados pelo core, depois coloque keyframes em seus wrappers de crop/máscara internos e geometria do divisor.
Retemporização constante da fonte	/hyperframes-core gerencia data-playback-rate normalizado (0.1..10) para imagem segura de renderização e som com tom preservado. É constante para todo o elemento de mídia.
Rampas de velocidade na fonte	Uma pista rate em data-automation no <video>/<audio> (t em segundos de clipe, v 0.1..10, interpolação logarítmica); ela sobrepuja a taxa constante.
Congelamento / pausa	Uma pose visual, quadro final da fonte ou subcomposição finalizada podem pausar. Congelamentos arbitrários no meio da fonte não são suportados; pré-processe um segmento estático/derivado, coloque-o como seu próprio clipe e 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 colocadas.

Um tratamento visual de transição ou corte não é um corte ou splice temporal na fonte. /hyperframes-core gerencia a linha do tempo, tempo de clipe e intervalos de fonte; keyframes apenas animam a transição 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

1. Identifique o sujeito animado, estados visíveis, estado final e tempo de execução.
2. Escolha o menor mecanismo que comprove o prompt. Leia references/keyframe-patterns.md apenas se o mecanismo não estiver claro.
3. Crie keyframes seguros para busca no tempo de execução declarado. Construa de forma síncrona e registre a instância do tempo de execução.
4. Verifique com hyperframes lint, hyperframes check, hyperframes keyframes, um --shot focado e snapshots nos tempos de prova.
5. Se a prova falhar, corrija os keyframes de origem e execute novamente o menor diagnóstico falho antes de renderizar.

Contrato

• Nomeie o sujeito em movimento.
• Nomeie as poses necessárias para comprovar o movimento pretendido, incluindo o estado final.
• Keyframe apenas canais visíveis, não estado auxiliar oculto.
• Preserve a identidade do objeto quando a continuidade importar.
• 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 de limpeza.
• Não retorne ao repouso a menos que solicitado.
• Não termine em preto a menos que solicitado.
• Se estiver editando uma cena inicial, preserve layout, cópia, ativos, cores e estado final, a menos que seja solicitado a redesenhar.

Regras de Tempo de Execução

GSAP:

• construir de forma síncrona no carregamento da página
• usar gsap.timeline({ paused: true })
• registrar como window.__timelines[compositionId]
• chave de registro deve corresponder a data-composition-id
• não chamar tl.play() para movimento crítico de renderização
• manter repetições finitas

CSS keyframes:

• duração finita e contagem de iterações
• atraso determinístico
• animation-fill-mode: both
• usar data-start quando a temporização pertence a um clipe

Anime.js:

• criar de forma síncrona
• autoplay: false
• duração e loops finitos
• empurrar cada instância para window.__hfAnime

WAAPI:

• duration finito
• fill: "both"
• construção determinística
• a superfície de texto não lista WAAPI; verificar com --shot (que 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
• temporizadores
• linhas do tempo criadas assíncronamente
• requestAnimationFrame nã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 encadeamento de atrasos. 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.
• Porcentagem keyframes: tempo exato dentro de um único tween.
• Propriedade arrays: mudanças multi-parada compactas.
• ease: "none" no pai quando cada parada carrega seu próprio easing.
• easeEach quando cada segmento deve compartilhar a mesma sensação.

Não copie distâncias numéricas ou temporização de exemplos. Derive-as da geometria e duração reais da composição.

Para um sujeito se movendo entre duas caixas, prefira um único 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 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 caminho/tracejado 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 linha do tempo 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-clipe ou um wrapper dentro do clipe; nunca mire no próprio .clipe. Nunca faça tween de visibility bruto, e nunca faça tween de display.

Escolha de Mecanismo

Escolha o menor mecanismo que comprove 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	shape interpolation
Limite de revelação é visível	clip, mask, ou shader uniform
Muitos itens se movem com ordem	stagger / indexed delay
Texto em si 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 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 de forma inconfundível.
• Follow-through vende energia e direção.
• Overshoot apenas quando o sujeito deve parecer elástico ou tátil.
• Path travel em velocidade constante geralmente precisa de ease: "none".
• Estados discretos de UI geralmente precisam de um ease-out acentuado.
• Elementos repetidos precisam de deslocamentos ordenados, não temporização idêntica.
• Travamentos finais precisam de pausas mais longas do que as 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 principal 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 as 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 caminhos 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

Keyframe posição da câmera, alvo da 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 HyperFrames. Use --ghost porque caixas de marcador não podem ver movimento interno de 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 exato final. Escolha <angle> apenas quando a profundidade deve ser provada.

Ferramenta	Prova
keyframes	alvos, paradas explícitas, caminhos, traços, movimento composto pai/filho, paradas CSS, registro Anime
--shot	fantasmas, forma da rota, espaçamento de tempo, projeção DOM 3D, prova de seletor focada
--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, legibilidade de texto, estado completo, travamento final, caudas pretas/reset

Se a prova do seletor parecer instável, use --layout strip para prova de contato direto e --shot para geometria. Se a prova de fantasma parecer vazia, verifique se o tempo de execução de canvas/WebGL foi registrado.

Referências

• references/keyframe-patterns.md — mecanismos de implementação
• /hyperframes-core — tempo de clipe, intervalo de fonte, linha do tempo
• /hyperframes-audio — fades, crossfades, automação de volume
• /hyperframes-registry — primitivas de transição
• /hyperframes-animation — coreografia de transição visual