Movimiento seguro para búsqueda (seek-safe motion)
HyperFrames no reproduce la línea de tiempo. La busca (seek): para cada fotograma, el renderizador establece la línea de tiempo en el tiempo de ese fotograma y captura la página. Con HyperFrames 0.8.x, esto se hace con tres workers en paralelo, cada uno tomando cada tercer fotograma, y cada paso de búsqueda retrocede 1 ms y luego avanza para estabilizarse. Por lo tanto, cada fotograma debe ser una función pura de su tiempo. Cualquier cosa que dependa de lo que se representó antes, del reloj o del azar, se renderiza de manera diferente en cada worker, y el resultado es un elemento que falta en cada tercer fotograma.
Ese error es invisible en la vista previa del Studio (que reproduce en orden) y en instantáneas individuales. En la producción de la que provienen estas habilidades, fue el único defecto que llegó al revisor: el título de apertura "tartamudeaba y destellaba" durante sus primeros siete segundos.
Lint primero
PVS_HOME="$(cd "$(cd "${CLAUDE_SKILL_DIR}" && pwd -P)/../.." && pwd)"
"$PVS_HOME/bin/pvs-py" "$PVS_HOME/skills/seek-safe-motion/scripts/lint_motion.py" <video_dir>/video
Lee index.html, src/*.tpl y los *.js junto a ellos (solo scripts en línea), imprime archivo:línea: severidad REGLA: por qué más la corrección, y sale con 1 en caso de error (--strict hace que las advertencias también fallen, --json para herramientas). Ejecútalo después de cada edición en la línea de tiempo y antes de cada render. Es estático: no puede ver variables calculadas en tiempo de ejecución (las cuenta como "no comprobables") ni dos tweens que se superponen en el tiempo. Esos quedan bajo tu responsabilidad, con la reproducción a continuación. qa.py (render-qa) también lo ejecuta y falla el informe si hay un error.
Las reglas y por qué existe cada una
- Cada clave en
fromVarsde unfromTotambién aparece en sustoVars(SS001, error). Cuando el fotograma de un worker cae exactamente en el inicio de un tween, el retroceso de 1 ms revierte el tween a antes de que comenzara, y una clave que solo existe enfromVarsnunca se vuelve a escribir. El tween del título erafromTo(sel, {yPercent: 110, opacity: 1}, {yPercent: 0}):opacity: 1vivía solo enfromVars, por lo que un worker mantuvo el título con opacidad 0 durante el resto del tween. Escribe{yPercent: 110, opacity: 1}a{yPercent: 0, opacity: 1}, o untl.set()seguido de untl.to(). Lo mismo aplica parastartAtdentro de unto()(SS002). immediateRender: falseen cadafromTodespués del tiempo 0 (SS003, advertencia). De lo contrario, el tween escribe sus valores iniciales cuando se construye la línea de tiempo, sobrescribiendo lo que establecieron tweens anteriores, y una búsqueda en medio de la línea de tiempo comienza desde el estado incorrecto.- Prefiere
fromToafrom(SS004, advertencia). Unfrom()termina en el estado en que estaba el elemento en el momento de la construcción; una vez que tweens anteriores tocan el elemento, los workers no se ponen de acuerdo sobre eso. - Nunca animar
displayovisibility(SS005, error). No se pueden interpolar; cambian en un punto arbitrario del tween. Cámbialos con untl.set()de duración cero en un tiempo explícito y desvanece conopacityoautoAlpha. - Sin reloj, sin azar, sin temporizadores (SS006, error): nada de
Date,performance.now(),Math.random(),setTimeout,setIntervalorequestAnimationFramepara nada visible. Un jitter de escritura o una forma de onda usa un generador con semilla; un temporizador de llamada mostrado en pantalla se calcula desdetl.time()dentro delonUpdatede la línea de tiempo. - Una línea de tiempo en pausa, registrada, nunca reproducida (SS007, SS011, SS012). Créala con
gsap.timeline({ paused: true }), constrúyela completamente (dentro dedocument.fonts.readycuando las posiciones dependan de las métricas de texto), y solo entonces asignawindow.__timelines["<id de composición>"] = tl. Registrar una línea de tiempo vacía antes de que termine la construcción renderiza un vídeo en blanco;tl.play()lucha contra las búsquedas del renderizador. - Los desplazamientos son
fromTocon inicio y fin explícitos para que cada worker calcule el mismo desplazamiento, limitado al contenido real para que ninguna línea o icono se detenga en un borde. - Nunca dos tweens en la misma propiedad del mismo elemento a la vez. Un restablecimiento del cursor que cayó dentro del siguiente movimiento dejó el puntero en el lugar equivocado después de una búsqueda. No se verifica con lint: verifica la tabla de tiempos de la compilación.
- Animaciones de transformación, no de diseño (SS009, advertencia):
x,y,scale,clip-pathen lugar deleft,top,width,margin. Los tweens de diseño refluyen cada fotograma yhyperframes checklos marca comogsap_non_transform_motion. Un cambio breve de ancho en un control de producto real (una barra lateral que se expande) puede aceptarse cuando reproduce el producto. - Nunca animar un elemento
.clip(SS010, error). HyperFrames controla la visibilidad de un clip a través dedata-startydata-duration; anima un contenedor dentro de él. - Repeticiones finitas (SS008, advertencia).
repeat: -1solo se permite bajo undata-durationraíz finito; calcula un recuento conMath.max(0, Math.floor(span / period) - 1). - Establece cada estado inicial explícitamente en el tiempo 0. Un helper que hace
gsap.set(sel, vars)también debería hacertl.set(sel, vars, 0), para que buscar de vuelta a 0 restaure el primer fotograma en lugar de mantener el último estado que renderizó un worker.
Reproducir un error sospechoso antes de renderizar
El lint encuentra patrones; una instantánea demuestra píxeles. Para un tween sospechoso que comienza en t0:
npx --yes hyperframes@<fijado> snapshot . --at <t0 + 0.3> --no-end --describe false -o a
npx --yes hyperframes@<fijado> snapshot . --at <t0>,<t0 + 0.3> --no-end --describe false -o b
El fotograma en t0 + 0.3 debe ser idéntico en a y b. Si difiere, buscar a través del inicio del tween cambió el estado. Para reproducir exactamente un worker, toma instantáneas de los fotogramas 0, 3, 6, ... en ese orden hasta justo después del tween. Bisecciona dividiendo el rango de tiempo a la mitad hasta que quede un solo tween. Después del renderizado, scan_render.py (render-qa) informa el mismo error como una ejecución de WORKER PATTERN: fotogramas atípicos que todos comparten un índice de fotograma módulo 3.
Referencias
references/patterns.md: código antes y después para cada regla, los helpers que mantienen segura una plantilla (lineIn,init, escritura, desplazamientos, clics del cursor) y lo que el lint puede y no puede ver. Léelo al escribir un nuevo helper o corregir un hallazgo del lint.