hyperframes-keyframes

HyperFrames Keyframes

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

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

Límite de edición del creador

Los keyframes poseen el movimiento visual, no el montaje de clips. Los cortes duros de rango de origen, recorte, empalme y reordenación pertenecen a /hyperframes-core: autoriza un elemento multimedia por rango conservado, 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. Una transición encadenada usa clips superpuestos en diferentes pistas más keyframes de opacidad visual; los fundidos de sonido usan /hyperframes-audio.

Solicitud del creador	Mecanismo veraz
Acercar / alejar (punch-in/punch-out)	Keyframe de scale con x/y o traslación porcentual en un envoltorio visual/de recorte no temporizado dentro del clip. Usa un tween conjunto/corto para un acercamiento brusco y un tween para un movimiento suave.
Zoom o reencuadre suave de múltiples estados	Mantén vivo un envoltorio de sujeto y autoriza 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 del envoltorio más la escala. La geometría es autorizada; 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 y segura para búsqueda.
Corte de coincidencia o giro panorámico (match cut/whip pan)	/hyperframes-animation posee la transición visual; /hyperframes-registry proporciona primitivas; los keyframes preservan la geometría, dirección y velocidad autorizadas. No existe descubrimiento automático de fotogramas de coincidencia.
Reencuadre con recorte y máscara	Interpola clip-path o una máscara en un envoltorio visual interno para recortar/reencuadrar sin cambiar el tiempo de origen. Los keyframes de polígono pueden formar una transición de polígono/máscara.
Corte de transición direccional o corte de iris/revelación	Anima un límite de máscara/clip a través de clips visuales superpuestos; /hyperframes-animation posee la coreografía de transición.
Transición de pantalla dividida (split-screen handoff)	Mantén ambos clips visuales colocados por el núcleo, luego keyframe sus envoltorios internos de recorte/máscara y la geometría del divisor.
Re-temporización constante de origen (constant source retime)	/hyperframes-core posee data-playback-rate normalizado (0.1..5) para imagen segura para renderizado y sonido con preservación de tono. Es constante para todo el elemento multimedia.
Rampas de velocidad de origen (source speed ramps)	No compatible: no hay envolvente de velocidad de reproducción variable en el tiempo. Preprocesa un recurso multimedia derivado, luego colócalo a través del núcleo.
Congelación / pausa (freeze / hold)	Una pose visual, el fotograma de origen final o una subcomposición terminada pueden mantenerse. No se admite la 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 skill para movimiento visual y /hyperframes-audio para fundidos, transiciones encadenadas, automatización de volumen, ducking/carve o efectos en las pistas colocadas.

Un tratamiento de transición visual o recorte no es un recorte temporal de origen o empalme. /hyperframes-core posee la línea de tiempo, la sincronización de clips y los rangos de origen; los keyframes solo animan la transición visible o el recorte en envoltorios 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, estados visibles, estado final y 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. Autoriza keyframes 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 tiempos de prueba.
5. Si la prueba falla, corrige los keyframes 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 probar el movimiento previsto, incluyendo el estado final.
• Keyframe canales visibles, no estado auxiliar oculto.
• Preserva la identidad del objeto cuando la continuidad importa.
• Transición encadenada solo cuando el movimiento previsto es 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 una limpieza.
• No restablezcas al reposo a menos que se solicite.
• No termines en negro a menos que se solicite.
• Si editas una escena inicial, preserva el diseño, la copia, los activos, los colores y el estado final a menos que se pida rediseñar.

Reglas de Tiempo de Ejecución

GSAP:

• construye sincrónicamente en la carga de la página
• usa gsap.timeline({ paused: true })
• registra como window.__timelines[compositionId]
• la clave del registro debe coincidir con data-composition-id
• no llames tl.play() para el movimiento crítico de renderizado
• mantén los repeticiones finitas

Keyframes CSS:

• duración finita y número de iteraciones
• retardo determinista
• animation-fill-mode: both
• usa data-start cuando la temporización pertenece a un clip

Anime.js:

• crea sincrónicamente
• autoplay: false
• duración y bucles finitos
• inserta cada instancia en window.__hfAnime

WAAPI:

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

Nunca uses 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 Keyframe

• Keyframes de array: escalera de pose con duración/easing por paso.
• Keyframes de porcentaje: temporización exacta dentro de un tween.
• Arrays de propiedades: cambios multi-parada compactos.
• ease: "none" en el padre cuando cada parada lleva su propio easing.
• easeEach cuando cada segmento debe compartir la misma sensación.

No copies distancias numéricas o temporizaciones de los ejemplos. Derívalas de la geometría y duración real de la composició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 keyframes con easing solo cuando el espectador deba sentir beats distintos; cada segmento cambia la velocidad y puede leerse como un tropiezo.

Canales

Prefiere canales visuales/de compositor: x/y/z, xPercent/yPercent, scale, rotationX/Y/Z, skew, transformOrigin, svgOrigin, opacity, autoAlpha, clip-path, máscaras, variables CSS, valores de ruta/dash 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 tardía de DOM, superposiciones auxiliares que hacen movimiento de 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 no clip o un envoltorio dentro del clip; nunca apuntes a .clip en sí mismo. Nunca hagas tween de duración con visibility bruto, y nunca hagas tween de display.

Elección de 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 viaja una ruta visible	recorrido de ruta
El trazo crece o traza	dibujo de trazo
Una forma se convierte en otra	interpolación de forma
El límite de revelación es visible	clip, máscara o uniforme de shader
Muchos elementos se mueven con orden	escalonamiento / retardo indexado
El texto 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 keyframes de cámara/objeto WebGL

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

Temporización

• Anticipación solo cuando aclara causa o dirección.
• Aceleración sale del reposo.
• Prueba máxima muestra el mecanismo inequívocamente.
• Seguimiento (follow-through) vende energía y dirección.
• Sobreimpulso (overshoot) solo cuando el sujeto debe sentirse elástico o táctil.
• El recorrido de ruta a velocidad constante generalmente necesita ease: "none".
• Los estados discretos de interfaz de usuario generalmente necesitan un ease-out agudo.
• Los elementos repetidos necesitan desplazamientos ordenados, no temporización idéntica.
• Los bloqueos finales necesitan mantenimientos más largos 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 cambios grandes de clip-path/máscara mientras la misma superficie principal también está escalando o viajando; usa revelaciones anidadas después de que el movimiento principal se asiente.

Texto

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

SVG

Para el crecimiento de trazo 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 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 angulada no muestra cruce de profundidad, mejora z/cámara/oclusión.

Canvas / WebGL

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

Prueba 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>

Elige <selector> para el sujeto animado real. Elige <times> para el primer fotograma, poses de prueba, final-menos-mantener y final exacto. Elige <angle> solo cuando la profundidad deba demostrarse.

Herramienta	Demuestra
keyframes	objetivos, paradas explícitas, rutas, trazas, movimiento padre/hijo compuesto, paradas CSS, registro de Anime
--shot	fantasmas, forma de ruta, espaciado de tiempo, proyección DOM 3D, prueba de selector enfocado
--layout strip	movimiento en el lugar, superposiciones, contacto, escala/opacidad sutil, ondas de texto
--ghost	canvas, WebGL, movimiento de shader, 3D renderizado
snapshot --at	máscaras, legibilidad de texto, estado completo, bloqueo final, colas de negro/restablecimiento

Si la prueba del selector parece incorrecta:

1. vuelve a ejecutar --json
2. encuentra el objetivo animado real
3. dispara ese objetivo
4. captura fotogramas completos
5. confía en los píxeles pintados sobre los registros

Lectura de Diagnóstico

flat significa que no hay poses intermedias explícitas. keyframes significa que existen paradas explícitas. `m... [truncado para traducción]