hyperframes-keyframes

HyperFrames Keyframes

Keyframes são um contrato de pose: estados visíveis, identidade contínua do sujeito, tempo de execução seguro para busca e 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 possuem o motion visual, não a montagem de clipes. Cortes abruptos de intervalo de origem, corte, emenda e reordenação pertencem ao /hyperframes-core: autor 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 abrupto. Um crossfade usa clipes sobrepostos em faixas 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 timeline dentro do clipe. Use um tween curto/set para um punch duro e um tween para um movimento suave.
Zoom suave multi-estado ou reenquadramento	Mantenha um wrapper de sujeito ativo e autor múltiplos estados de zoom/reenquadramento como uma escada de pose com easing por segmento.
Pan, reenquadramento ou movimento Ken Burns	Animar translação do wrapper mais escala. A geometria é de autoria; isso não é rastreamento facial ou reenquadramento semântico automático.
Movimentos de câmera encadeados	Encadeie beats de transformação rotulados em uma timeline registrada segura para busca.
Match cut ou whip pan	/hyperframes-animation possui a transição visual; /hyperframes-registry fornece primitivas; keyframes preservam a geometria, direção e velocidade de autoria. Não há descoberta automática de molduras correspondentes.
Reenquadramento com crop e máscara	Interpole clip-path ou uma máscara em um wrapper visual interno para cortar/reenquadrar 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 íris/revelação	Anime um limite de máscara/clip em clipes visuais sobrepostos; /hyperframes-animation possui a coreografia da transição.
Transição de tela dividida	Mantenha ambos os clipes visuais posicionados pelo core, então keyframe seus wrappers de crop/máscara internos e geometria do divisor.
Retemporização constante da fonte	/hyperframes-core possui data-playback-rate normalizado (0.1..5) para imagem segura para renderização e som com preservação de tom. É constante para todo o elemento de mídia.
Rampas de velocidade da fonte	Não suportado: não há envelope de taxa de reprodução variável no tempo. Pré-processe um ativo de mídia derivado, então coloque-o através do core.
Congelamento / pausa	Uma pose visual, quadro final da fonte ou subcomposição finalizada pode segurar. Congelamento arbitrário no meio da fonte não é suportado; pré-processe um segmento derivado/estático, coloque-o como seu próprio clipe, então retome com outro intervalo de origem.

Ao editar imagem e som juntos, carregue /hyperframes-core, esta skill para motion visual, e /hyperframes-audio para fades, crossfades, automação de volume, ducking/carve, ou efeitos nas faixas posicionadas.

Um tratamento de transição visual ou corte não é um corte temporal ou emenda de origem. /hyperframes-core possui a timeline, o tempo do clipe e os intervalos de origem; keyframes apenas animam a transição visível ou o corte 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. Autor keyframes seguros para busca no tempo de execução declarado. Construa sincronamente e registre a instância 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 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.
• Keyframe 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.
• Segure estados legíveis ou semânticos o tempo suficiente para serem vistos.
• O quadro final é parte da animação, não uma limpeza.
• Não reinicie para o 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 Execução

GSAP:

• construir sincronamente 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 motion 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-start quando o tempo pertence a um clipe

Anime.js:

• crie sincronamente
• autoplay: false
• duração finita e loops
• empurre cada instância para window.__hfAnime

WAAPI:

• duration finita
• fill: "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 motion crítico de renderização:

• Date.now()
• performance.now()
• Math.random() sem semente
• gatilhos de hover/scroll
• temporizadores
• timelines criadas assincronamente
• 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 atrasos encadeados. Use immediateRender: false para tweens from()/fromTo() posteriores que tocam a mesma propriedade.

Formas de Keyframe

• Array de keyframes: escada de pose com duração/easing por etapa.
• Keyframes percentuais: tempo exato dentro de um tween.
• Arrays de propriedade: 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 tempo de exemplos. Derive-as 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 vários keyframes com easing apenas quando o espectador deve sentir beats distintos; cada segmento muda a velocidade e pode ser lido como um soluço.

Canais

Prefira canais visuais/compositor: x/y/z, xPercent/yPercent, scale, rotationX/Y/Z, skew, transformOrigin, svgOrigin, opacity, autoAlpha, clip-path, máscaras, variáveis CSS, valores SVG path/dash, transformações de câmera, uniformes de shader.

Evite canais de layout/ciclo de vida: top/left/right/bottom, width/height, margin/padding, display, visibility, criação tardia de DOM, sobreposições auxiliares fazendo motion 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. Alveje apenas um elemento que não seja clipe ou um wrapper dentro do clipe; nunca alveje o .clip em si. Nunca faça tween de duração com visibility bruto, e nunca faça tween com 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 viaja por uma rota visível	path travel
Traço cresce ou traça	stroke draw
Forma se transforma em outra forma	shape interpolation
Limite de revelação é visível	clip, máscara, ou uniforme de shader
Muitos itens se movem com ordem	stagger / atraso indexado
O próprio texto se move	subdivisão de linha, palavra, caractere ou banda
Superfície dobra, estica ou corta	contra-transforma 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 combinar, mas cada um deve esclarecer a ideia. Decoração não é prova.

Tempo

• Antecipação apenas quando esclarece causa ou direção.
• Aceleração deixa o repouso.
• Prova de pico mostra o mecanismo inequivocamente.
• Follow-through vende energia e direção.
• Overshoot apenas quando o sujeito deve parecer elástico ou tátil.
• Viagem de path a velocidade constante geralmente precisa de ease: "none".
• Estados discretos de UI geralmente precisam de um sharp ease-out.
• Elementos repetidos precisam de deslocamentos ordenados, não tempo idêntico.
• Travas finais precisam de segurações 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 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 hero também está escalando ou viajando; use revelações aninhadas depois que 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. Snapshots 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 é falsa profundidade. 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 do objeto, opacidade do material, uniformes 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 motion 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 o primeiro quadro, poses de prova, final-menos-seguração 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	fantasmas, forma da rota, espaçamento temporal, projeção DOM 3D, prova de seletor focado
--layout strip	movimento no lugar, sobreposições, contato, escala/opacidade sutil, ondas de texto
--ghost	canvas, WebGL, motion de shader, 3D renderizado
snapshot --at	máscaras, legibilidade de texto, estado completo, trava final, cauda preta/reset

Se a prova do seletor parecer errada:

1. reexecute --json
2. encontre o alvo animado real
3. atire nesse alvo
4. snapshot de quadros completos
5. confie em pixels pintados sobre logs

Leitura de Diagnóstico

flat significa que não há poses intermediárias explícitas. keyframes significa que paradas explícitas existem. `m