hyperframes-keyframes

Instalación de plugins: Antes de los comandos de configuración o actualización, sigue las reglas de ejecución de plugins cuando esta habilidad esté dentro de un plugin de HyperFrames. Las instalaciones independientes mantienen las instrucciones de actualización a continuación.

HyperFrames Keyframes

Los Keyframes son un contrato de poses: estados visibles, identidad continua del sujeto, tiempo de ejecución seguro para búsqueda, píxeles verificados.

Usa hyperframes-animation para recetas de escena amplias. Usa hyperframes-cli para la documentación completa de comandos. Usa references/keyframe-patterns.md solo al elegir mecanismos de implementación, no al decidir el estilo visual.

Límite de edición del creador

Los Keyframes controlan el movimiento visual, no el ensamblaje de clips. Los cortes duros en el rango de origen, recortes, empalmes y reordenaciones pertenecen a /hyperframes-core: escribe un elemento multimedia por rango mantenido, colócalo con data-start y data-duration, y selecciona su desplazamiento de origen con data-media-start. Los rangos adyacentes forman un corte duro. Un fundido cruzado superpone clips en diferentes pistas más fotogramas clave de opacidad visual; los fundidos de sonido usan /hyperframes-audio.

Solicitud del creador	Mecanismo fiel
Acercar / alejar	Fotograma clave scale con traslación en x/y o porcentaje dentro de un contenedor visual/recorte no temporizado dentro del clip. Usa un tween fijo/corto para un movimiento brusco y un tween para un movimiento suave.
Zoom o reencuadre multiestado suave	Mantén vivo un contenedor de sujeto y escribe múltiples estados de zoom/reencuadre como una escalera de poses con easing por segmento.
Panorámica, reencuadre o movimiento de cámara Ken Burns	Anima la traslación y escala del contenedor. La geometría es autorada; esto no es seguimiento facial ni reencuadre semántico automático.
Movimientos de cámara encadenados	Encadena beats de transformación etiquetados en una línea de tiempo registrada segura para búsqueda.
Corte coincidente o paneo panorámico	/hyperframes-animation controla la transición visual; /hyperframes-registry proporciona los primitivos; los fotogramas clave preservan la geometría, dirección y velocidad autoradas. No hay descubrimiento automático de cuadros coincidentes.
Reencuadre con recorte y máscara	Interpola clip-path o una máscara en un contenedor visual interno para recortar/reencuadrar sin cambiar el tiempo de origen. Los fotogramas clave de polígono pueden formar una transición de polígono/máscara.
Corte de barrido direccional o iris/revelación	Anima un límite de máscara/recorte entre clips visuales superpuestos; /hyperframes-animation controla la coreografía de la transición.
Transición de pantalla dividida	Mantén ambos clips visuales colocados por el núcleo, luego anima sus contenedores de recorte/máscara internos y la geometría del divisor.
Re-tiempo constante de origen	/hyperframes-core controla data-playback-rate normalizado (0.1..10) para una imagen segura para renderizar y sonido preservado en tono. Es constante para todo el elemento multimedia.
Rampas de velocidad de origen	Un carril rate en data-automation en el <video>/<audio> (t en segundos del clip, v 0.1..10, interpolación logarítmica); anula la tasa constante.
Congelar / mantener	Una pose visual, el fotograma final de origen o una subcomposición terminada puede mantenerse. No se admite una congelación arbitraria en medio del origen; preprocesa un segmento fijo/derivado, colócalo como su propio clip, luego reanuda con otro rango de origen.

Al editar imagen y sonido juntos, carga /hyperframes-core, esta habilidad para movimiento visual y /hyperframes-audio para fundidos, fundidos cruzados, automatización de volumen, ducking/carve o efectos en las pistas colocadas.

Un tratamiento visual de transición o recorte no es un recorte o empalme temporal de origen. /hyperframes-core controla la línea de tiempo, la temporización de clips y los rangos de origen; los fotogramas clave solo animan la transición visual o el recorte en los contenedores dentro de esos clips. Para recetas combinadas de imagen/sonido copiables, usa /hyperframes-core → references/creator-editing-recipes.md.

Procedimiento

1. Identifica el sujeto animado, los estados visibles, el estado final y el tiempo de ejecución.
2. Elige el mecanismo más pequeño que demuestre la solicitud. Lee references/keyframe-patterns.md solo si el mecanismo no está claro.
3. Autorar fotogramas clave seguros para búsqueda en el tiempo de ejecución declarado. Construye sincrónicamente y registra la instancia de tiempo de ejecución.
4. Verifica con hyperframes lint, hyperframes check, hyperframes keyframes, un --shot enfocado y capturas de pantalla en los momentos de prueba.
5. Si la prueba falla, corrige los fotogramas clave de origen y vuelve a ejecutar el diagnóstico fallido más pequeño antes de renderizar.

Contrato

• Nombra el sujeto en movimiento.
• Nombra las poses necesarias para demostrar el movimiento previsto, incluido el estado final.
• Fotogramas clave en canales visibles, no en estados ocultos de ayuda.
• Preserva la identidad del objeto cuando la continuidad importa.
• Fundido cruzado solo cuando el movimiento previsto sea reemplazo o disolución.
• Mantén los estados legibles o semánticos el tiempo suficiente para verlos.
• El fotograma final es parte de la animación, no de la limpieza.
• No reinicies al estado de reposo a menos que se solicite.
• No termines en negro a menos que se solicite.
• Si editas una escena inicial, preserva el diseño, el texto, los activos, los colores y el estado final a menos que se pida rediseñar.

Reglas de tiempo de ejecución

GSAP:

• construir sincrónicamente al cargar la página
• usar gsap.timeline({ paused: true })
• registrar como window.__timelines[compositionId]
• la clave del registro debe coincidir con data-composition-id
• no llamar a tl.play() para movimiento crítico de renderizado
• mantener los ciclos finitos

CSS keyframes:

• duración e iteraciones finitas
• retraso determinista
• animation-fill-mode: both
• usar data-start cuando la temporización pertenezca a un clip

Anime.js:

• crear sincrónicamente
• autoplay: false
• duración y bucles finitos
• empujar cada instancia a window.__hfAnime

WAAPI:

• duration finito
• fill: "both"
• construcción determinista
• la superficie de texto no lista WAAPI; verifica con --shot (busca WAAPI) y capturas de pantalla

Nunca usar para movimiento crítico de renderizado:

• Date.now()
• performance.now()
• Math.random() sin semilla
• disparadores de hover/scroll
• temporizadores
• líneas de tiempo creadas asincrónicamente
• requestAnimationFrame no registrado
• bucles 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;

Usa etiquetas para estados semánticos. Usa parámetros de posición en lugar de retrasos encadenados. Usa immediateRender: false para tweens from()/fromTo() posteriores que toquen la misma propiedad.

Formas de fotogramas clave

• Fotogramas clave de matriz: escalera de poses con duración/easing por paso.
• Fotogramas clave de porcentaje: temporización exacta dentro de un tween.
• Matrices de propiedades: cambios multi-parada compactos.
• ease: "none" en el padre cuando cada parada lleve su propio easing.
• easeEach cuando cada segmento deba compartir la misma sensación.

No copies distancias numéricas o temporizaciones de los ejemplos. Deralas de la geometría real de la composición y la duración.

Para un sujeto que se mueve entre dos cajas, prefiere un tween de transformación continua o FLIP. Divide x/y/scale en múltiples fotogramas clave con easing solo cuando el espectador deba sentir beats distintos; cada segmento cambia la velocidad y puede leerse como un tropiezo.

Canales

Prefiere canales de compositor/visuales: x/y/z, xPercent/yPercent, scale, rotationX/Y/Z, skew, transformOrigin, svgOrigin, opacity, autoAlpha, clip-path, máscaras, variables CSS, valores de ruta/guion SVG, transformaciones de cámara, uniformes de shader.

Evita canales de diseño/ciclo de vida: top/left/right/bottom, width/height, margin/padding, display, visibility, creación DOM tardía, superposiciones auxiliares que realizan movimiento del sujeto.

Para cambios de visibilidad, usa autoAlpha en la línea de tiempo GSAP registrada y buscable, o un tl.set() de duración cero en un límite explícito. Apunta solo a un elemento que no sea un clip o a un contenedor dentro del clip; nunca apuntes a .clip mismo. Nunca uses un tween de duración en visibility sin procesar, y nunca uses un tween en display.

Elección del mecanismo

Elige el mecanismo más pequeño que demuestre la solicitud:

Necesidad	Mecanismo
El mismo sujeto cambia de caja o jerarquía	Elemento compartido / FLIP
El sujeto recorre una ruta visible	Viaje por ruta
Un trazo crece o traza	Dibujo de trazo
Una forma se convierte en otra forma	Interpolación de formas
El límite de revelación es visible	Recorte, máscara o uniforme de shader
Muchos elementos se mueven con orden	Stagger / retraso indexado
El texto en sí mismo se mueve	Subdivisión de línea, palabra, carácter o banda
La superficie se dobla, estira o recorta	Contra-transformación padre/hijo
La interfaz de usuario tiene estados	Máquina de estados explícita
La escena tiene profundidad	DOM 3D, Three.js o fotogramas clave de cámara/objeto WebGL

Los mecanismos pueden combinarse, pero cada uno debe clarificar la idea. La decoración no es prueba.

Temporización

• Anticipación solo cuando aclara causa o dirección.
• La aceleración deja el reposo.
• La prueba máxima muestra el mecanismo de manera inequívoca.
• El seguimiento vende energía y dirección.
• El sobreimpulso solo cuando el sujeto deba sentirse elástico o táctil.
• El viaje por ruta a velocidad constante generalmente necesita ease: "none".
• Los estados discretos de interfaz de usuario generalmente necesitan un ease-out pronunciado.
• Los elementos repetidos necesitan desplazamientos ordenados, no temporización idéntica.
• Los cierres finales necesitan pausas más largas que las poses de transición.
• Suavidad significa velocidad continua en el mismo sujeto.
• No superpongas tweens que escriban la misma propiedad de transformación a menos que la superposición sea intencional y verificada.
• Evita animar grandes cambios de clip-path/máscara mientras la misma superficie principal también se escala o viaja; usa revelaciones anidadas después de que el movimiento principal se asiente.

Texto

Preserva los cuadros de línea, el espaciado entre palabras, la legibilidad y el ajuste final. Si el texto se mueve internamente, mueve los glifos o las bandas enmascaradas, no solo las decoraciones alrededor del texto. Captura cuadros legibles.

SVG

Para el crecimiento de trazos, prefiere DrawSVGPlugin, luego stroke-dasharray/stroke-dashoffset. Para la interpolación de formas, prefiere MorphSVGPlugin; convierte primitivas a rutas cuando sea necesario y divide siluetas complejas en partes más simples.

3D

La escala por sí sola es profundidad falsa. Usa perspectiva en un padre estable, transform-style: preserve-3d, viaje en z, rotación, movimiento de cámara/mundo, oclusión y orden de capas cuando los objetos se crucen.

Usa uno o dos ángulos de diagnóstico que expongan la relación de profundidad. Si la prueba angular no muestra cruce de profundidad, mejora z/cámara/oclusión.

Canvas / WebGL

Fotogramas clave de posición de cámara, objetivo de cámara, transformación de objeto, opacidad de material, uniformes de shader e intensidad de postprocesamiento a través de un estado determinista. Renderiza desde el tiempo de HyperFrames. Usa --ghost porque los cuadros de marcador no pueden ver el movimiento interno del canvas.

Pruebas 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 "<archivo>" --samples <n>
npx hyperframes keyframes . --selector "<selector>" --shot "<archivo>" --layout strip --from <t0> --to <t1>
npx hyperframes keyframes . --shot "<archivo>" --ghost --angle <ángulo>
npx hyperframes snapshot . --at <tiempos>

Elige <selector> para el sujeto animado real. Elige <tiempos> para el primer fotograma, las poses de prueba, el final menos la pausa y el final exacto. Elige <ángulo> solo cuando la profundidad deba probarse.

Herramienta	Demuestra
keyframes	Destinos, paradas explícitas, rutas, trazos, movimiento padre/hijo compuesto, paradas CSS, registro de Anime
--shot	Fantasmas, forma de ruta, espaciado temporal, proyección DOM 3D, prueba de selector enfocada
--layout strip	Movimiento en el lugar, superposiciones, contacto, escala/opacidad sutiles, ondas de texto
--ghost	Canvas, WebGL, movimiento de shader, 3D renderizado
snapshot --at	Máscaras, legibilidad del texto, estado completo, cierre final, colas negras/de reinicio

Si la prueba del selector se ve extraña...