suxrobGM/logistics-app

Video teaser

Produce un teaser de calidad de lanzamiento (~30-45s) de una aplicación en ejecución: storyboard, grábala conduciendo la interfaz real, edítala con ffmpeg y entrega un MP4 más un GIF para el README.

El resultado debe parecer un video de producto, no una grabación de pantalla. La diferencia es la dirección (puesta en escena, encuadre y ritmo), no la resolución.

Las implementaciones de referencia están en reference/; son módulos ESM funcionales, no pseudocódigo. Configúralas en un directorio temporal, nunca dentro del proyecto:

cp -r <skill>/reference/* "$SCRATCH/" && cd "$SCRATCH" && npm install
export TEASER_BASE_URL="https://the-app.example.com"

reference/package.json declara "type": "module" y las tres dependencias. Cada script lee TEASER_BASE_URL, así que nada está codificado para una sola aplicación.

Antes que nada: las dos reglas estrictas

1. Nunca desencadenes efectos secundarios del mundo real sin consentimiento explícito y detallado.

Grabar una aplicación real significa hacer clic en botones reales. Algunos envían correos electrónicos, publican públicamente, cobran dinero o envían formularios a terceros. Antes de tocar la aplicación:

• Enumera cada acción en tu storyboard que salga de la máquina.
• Dile al usuario exactamente qué hace cada una y cuántas veces, luego obtén acuerdo sobre el recuento.
• Prefiere un modo que se detenga antes del paso irreversible (una vista previa, un simulacro, una puerta de confirmación que puedas filmar y luego rechazar).

No existe una sonda de solo lectura contra un sistema en vivo. Un clic de "diagnóstico" que aterriza en una sesión ya en ejecución se dispara de verdad. Si estás depurando por qué una acción no funcionó, asume que tu próximo clic funcionará, y prepárate para ello.

Si algo se dispara sin intención: detén el proceso en su origen inmediatamente (mata la sesión/trabajador, no solo el botón de la IU, que puede no tener efecto), verifica el estado detenido leyéndolo de nuevo, e informa al usuario claramente en tu mensaje final, recuento incluido.

2. Asume que cada fotograma es público y está lleno de PII.

Las cuentas reales contienen nombres, correos electrónicos, direcciones y documentos. Decide la política con el usuario desde el principio:

• Enmarcar alrededor (por defecto): compone tomas que excluyan la identidad. Recorta el chrome persistente (barras laterales, avatares, menús de cuenta) en la etapa de ffmpeg.
• Ocultar antes de grabar: page.evaluate un visibility: hidden en las tarjetas ofensivas antes de que la cámara ruede. Nunca filmes algo esperando recortarlo después.
• Usar una cuenta demo predefinida: la más limpia cuando exista una.

Revisa cada fotograma del corte final a resolución completa antes de entregar. No la hoja de contactos, los fotogramas.

Flujo de trabajo

1. Explora y haz storyboard

Toma capturas de pantalla autenticadas de cada pantalla candidata primero (reference/scout.js). Míralas. Luego escribe una tabla de storyboard: beat, toma, qué debe sentir el espectador y duración. Una toma sin trabajo asignado se corta antes de filmarse.

Arco que funciona: tensión (el problema) → revelación (el producto) → prueba (realmente hace lo que promete) → escala (los resultados) → confianza (dónde se ejecuta) → cierre.

Anota en el storyboard qué pantallas contienen PII y cuáles son seguras.

2. Prepara el escenario

Organiza antes de grabar, nunca después:

• Elige vistas donde los datos se vean mejor: gráficos completos, listas activas, nombres reconocibles, recuentos distintos de cero. Nunca filmes un spinner, un estado vacío o un gráfico a medio renderizar.
• Ajusta el estado de la IU deliberadamente (anchos de panel, colapsado/expandido, filtros, posición de desplazamiento) mediante localStorage en un script de inicialización o un page.evaluate previo a la grabación.
• Descarta toasts, banners y barras de cookies fuera de cámara.
• Deja que los datos se asienten: networkidle más unos segundos.

3. Graba

Usa CDP screencast (Page.startScreencast), no grabación de pantalla. Captura la página fuera de pantalla a ~100fps, por lo que nada de lo que el usuario esté haciendo aparece en el fotograma y la máquina sigue siendo utilizable. Playwright conduce; CDP graba. reference/rig.js lo implementa.

• Un sujeto por toma. Encuadra la cosa, no "toda la aplicación".
• Los movimientos de cámara provienen de desplazamiento suave con script dentro de la página (cameraScroll), nunca de un filtro. Ver la advertencia sobre zoompan más abajo.
• El cursor es un actor: usa el cursor SVG inyectado (cursorClick) que se desliza con suavidad y se hunde al presionar, o escóndelo. Sin deriva inactiva.
• Ensaya cada toma, extrae fotogramas, míralos, ajusta, luego graba de verdad.

Grabar una ventana externa (un navegador que la propia aplicación abre, una aplicación de escritorio) necesita captura del sistema operativo: gdigrab/x11grab/avfoundation (recordDesktop en el rig). Esto captura todo en la pantalla, incluido el trabajo del usuario. Advierte al usuario, pídele que se aleje, revisa el resultado fotograma por fotograma; bórralo si capturó algo privado.

4. Tarjetas de título

HTML/CSS animado grabado en el navegador, no imágenes estáticas. Inyecta el marcado de la tarjeta en una página en blanco en el mismo origen de la aplicación para que sus fuentes web y paleta se resuelvan, luego haz screencast. Obtén la fuente de visualización real de la página en vivo (getComputedStyle) y fija una pila mono conocida en lugar de adivinarla.

Haz coincidir el lenguaje de movimiento de la aplicación (sus propias curvas y duraciones de easing). Carga la habilidad frontend-design antes de diseñarlas si el proyecto no tiene un estilo de tarjeta establecido.

5. Edita

reference/build.js normaliza cada segmento a un tamaño/fps común, luego encadena con crossfade. Mantén cortes cada ~2.5-4s. Dale espacio al momento culminante a velocidad normal mientras comprimes la rutina a su alrededor.

6. Revisa, luego entrega

• Genera una hoja de contactos y fotogramas a resolución completa por segundo.
• Lee los fotogramas en busca de PII, paneles recortados y texto ilegible.
• Verifica la duración y dimensiones con una sonda.
• Entrega un MP4 más, para READMEs, un GIF optimizado con paleta (GitHub no reproducirá en línea un MP4 subido). Mantén el GIF por debajo de ~10 MB.
• Déjalo sin sonido a menos que se solicite; no puedes licenciar música. Dilo.

Específicos ganados con esfuerzo

Nunca uses zoompan para acercamientos. Recalcula el zoom por fotograma y redondea la ventana de recorte a píxeles enteros, por lo que la imagen rebota de un lado a otro: se lee como un terremoto. Usa tomas fijas más desplazamiento real dentro de la página. Si debes tener un acercamiento, preescala la fuente 4x primero y verifica con una medición de diferencia de fotogramas (reference/jitter.js): una toma estática fija debe medir un delta medio muy por debajo de 1.0; la vibración visible marca 3+.

El screencast deja de emitir fotogramas cuando la animación se asienta. Una tarjeta cuya animación termina después de 1.2s produce un clip de 1.2s. Rellena con tpad=stop_mode=clone:stop_duration=N y corta a la longitud deseada con -t.

Ensambla fotogramas con marca de tiempo, no a una tasa fija. Los fotogramas del screencast llegan con metadata.timestamp; escribe una lista de concat de ffmpeg con duraciones reales por fotograma, luego remuestrea a 60fps constantes. Asumir un intervalo fijo produce tirones.

ffmpeg-static como dependencia de desarrollo, resuelta por ruta de módulo. Nunca dependas de que ffmpeg esté en PATH. (ffprobe no está en ese paquete; analiza ffmpeg -i stderr en su lugar).

Captura autenticada: inicia sesión una vez con interfaz, guarda storageState, reutilízalo en cada toma (reference/login.js). Las sesiones caducan: termina de filmar el mismo día o vuelve a ejecutarlo. También siembra las preferencias de IU de localStorage allí.

Localhost desde un origen desplegado está bloqueado por la política de acceso a la red local de Chrome. Si la página debe alcanzar un servicio local, inicia con --disable-features=LocalNetworkAccessChecks,PrivateNetworkAccessChecks,BlockInsecurePrivateNetworkRequests.

Recorta el chrome persistente con un desplazamiento fijo. Graba con un ancho de viewport de 1920 + railWidth, luego crop=1920:1080:railWidth:0 para eliminar la barra lateral y aterrizar exactamente en 1080p.

Entregables

Informa la ruta, duración y dimensiones; declara explícitamente qué falta todavía del usuario (música, una subida de video nativa de GitHub); y revela cualquier cosa que haya ocurrido durante la grabación que el usuario deba saber.