JoaoIurovschi/faisca

FAÍSCA

Palabra de activación: faísca. La persona escribe "faísca" y describe el video (tema, frases, formato); esta habilidad crea el proyecto, monta la línea de tiempo y renderiza el MP4.

SKILL_DIR = carpeta de este archivo. La composición es HyperFrames (HTML + GSAP), con la línea de tiempo estirada SLOW veces y renderizada a 60 fps; el render-faisca.sh promedia cada SLOW subfotogramas, y el resultado es desenfoque de movimiento real, con aspecto de After Effects.

• Catálogo de los efectos listos, tiempos y dónde se ubican en el código: referencias/efeitos.md.
• Estudiar un video de referencia (desglosar, medir fuente y color, comparar): referencias/recriar-referencia.md.
• Pista original compuesta por código y motion que reacciona al audio: referencias/trilha-propria.md, moldes en trilha/.
• Contrato de HyperFrames: si la habilidad hyperframes está instalada, leer antes de tocar la estructura; npx hyperframes docs gsap y npx hyperframes docs data-attributes también ayudan.

Antes de todo

1. De quién es la pieza. Usa el color y las fuentes de la marca de quien va a publicar. Sin marca definida, se queda el verde lima del modelo.
2. Qué decir. Frases cortas de impacto (2 a 4 palabras por pantalla) y un subtítulo corrido. Contenido solo de lo que la persona pidió; nada inventado.
3. Formato y duración. 16:9 por defecto; Reels y TikTok en 9:16 (ver final de referencias/efeitos.md). Sin narración, el estilo rinde de 4 a 15 s; con narración, se puede ir más allá, siempre que cada pantalla cambie cada 0,4 a 0,8 s.
4. Carpeta. Una carpeta por video, fuera de carpetas sincronizadas (iCloud, Dropbox) si es posible.
5. Sin crédito. Todo se ejecuta localmente.

Etapa 1 · Crear el proyecto

SKILL_DIR/scripts/novo-faisca.sh <carpeta-del-proyecto>

Ejecuta hyperframes init, copia el modelo (composición de 4 s funcional, fuentes locales) y verifica que el lint salga con 0 errores. Sin OK:, detenerse y corregir.

Etapa 2 · Identidad

• Color de acento: las cuatro variables --acento, --acento-rgb, --acento-claro, --acento-oscuro en el :root. Todo (brillo, chispas, láser, píldora, placa, 3D) deriva de ellas.
• Fuentes en assets/fonts/ con @font-face en el propio archivo (el lint exige archivo local). Cambiar la del título solo por una pesada y condensada; medir antes (ver recriar-referencia).
• HUD (#hudBrand): nombre de la marca de la pieza. Nunca la marca de otra empresa.

Etapa 3 · Guion y línea de tiempo

1. Escribir el desglose: lista de eventos con instante (segundos reales), texto y efecto del catálogo. Una idea cada 0,4 a 0,8 s.
2. Ajustar DUR y, junto, el data-duration del #root y del #stage para DUR × SLOW (render-faisca.sh rechaza si no coinciden).
3. Cambiar textos e instantes en el bloque // ---------- línea de tiempo. Para escena nueva, copiar el patrón de un efecto del catálogo. Efecto que sigue posición en cada instante va en draw(t).
4. SLOW = 8 sirve para casi todo. Zoom o cruce muy rápido muestra "anillos" con 8 muestras: subir a 16 (duplica el tiempo de render).
5. Con narración: tomar el tiempo de cada palabra (Whisper o similar) y ajustar los efectos a esos instantes, en lugar de estimar.

Etapa 4 · Revisión por fotogramas

SKILL_DIR/scripts/quadros.sh <proyecto> 0.3,0.9,1.3,1.6,2.3,2.7,3.2,3.6,3.9

Instantes en segundos reales (el script multiplica por SLOW). Revisar la hoja: texto cortado, palabra fuera de lugar, efecto que no aparece. Los fotogramas son muestra única, sin desenfoque.

Etapa 5 · Render y verificación

SKILL_DIR/scripts/render-faisca.sh <proyecto> <proyecto>/renders/<nombre>.mp4 [--audio pista.wav]
SKILL_DIR/scripts/render-faisca.sh <proyecto> /tmp/sabotaje.mp4 --sabotar   # tiene que FALLAR

El render verifica tres cosas: data-duration = DUR × SLOW, número de fotogramas a 60 fps y presencia del desenfoque (el video final debe diferir de la muestra única en los tramos con movimiento). El --sabotar genera sin desenfoque y debe terminar en ERROR: sin desenfoque: es la prueba de que la verificación sabe fallar. 4 s tardan aproximadamente de 1 a 4 min, según la máquina.

npx hyperframes check también se ejecuta, pero la auditoría de diseño acusa por dibujo: palabras del subtítulo que aún van a aparecer (transparentes, text_not_painted) y capas 3D superpuestas (content_overlap). Exigido: lint con 0 errores; estos hallazgos de diseño son esperados.

Etapa 6 · Entrega

• Entregar el MP4 y decir dónde está.
• Contar qué quedó diferente de lo pedido, sin ocultar.
• Estudio de video de otra persona: la comparativa lado a lado es solo para estudio; no publicar.

Trampas ya resueltas

Síntoma	Causa y solución
Efecto procedural desaparece o se traba en fotogramas sueltos	draw(t) guardaba estado o medía el DOM. Debe ser función pura de t; medir en build()
Barra tiembla y deja de subir	draw escribía style.transform en el mismo elemento que anima GSAP. Temblor va en un hijo (#rbInner)
Elemento oculto nunca aparece en el render	fromTo con opacity: 1 solo en el "de". Poner opacity: 1 también en el destino
Píldora del subtítulo invisible	z-index: -1 sin contexto de apilamiento. isolation: isolate en la palabra
Fotograma de prueba en el instante equivocado	--at del snapshot es tiempo de la línea de tiempo estirada. Usar quadros.sh, que multiplica por SLOW
Anillos en el zoom final	8 muestras no bastan para escala exponencial. SLOW = 16 (y data-duration junto)
Color de referencia filmado parece otro	cámara filmando una pantalla distorsiona el color. Usar el color de origen, no la muestra
Fotogramas de prueba todos iguales (solo el fondo)	la herramienta fotografió antes de que build() terminara. quadros.sh ya espera 20 s
Render lento o congelado	partes temporales en carpeta sincronizada. Los scripts usan MOTION_TMP o la carpeta temporal del sistema
Render pide decenas de GB de disco	captura paralela grabando cada fotograma. render-faisca.sh ya activa HF_CAPTURE_PARALLEL_STREAM=true
className o textContent no cambian con GSAP	GSAP 3 no aplica estas propiedades con set. Cambiar en draw(t), como función de t
Elemento centrado con translateX(-50%) se sale de lugar	la escala de GSAP reescribe el transform. Centrar con xPercent: -50