repo-cinema

Habilidad Director de repo-cinema

Crea videos demo de producto de 60fps con calidad Screen Studio directamente desde un código base. En lugar de grabaciones de pantalla improvisadas o movimientos de cursor sin rumbo, repo-cinema ejecuta un pipeline determinista de 5 etapas: analyze -> plan -> stage -> render -> verify.

Principios Arquitectónicos Centrales

1. Casos de uso basados en personas (analyze): Nunca muestres estadísticas internas de depuración o pantallas de configuración en bruto. Lee puntos de entrada, comandos CLI, rutas, componentes y pruebas para sintetizar escenas concretas de Persona -> Punto de dolor -> Acción de usuario -> Resultado duradero.
2. Encuadre causal (plan): Encuadra el bounding box unión bbox(trigger ∪ outcome) en lugar de perseguir el puntero del ratón. Bloquea el enfoque horizontal fx = viewport.width / 2 siempre que el ancho del contenido ocupe >= 70% del escenario para que los ejes, encabezados y columnas derechas nunca se recorten fuera de pantalla.
3. Pausas de lectura estacionarias: Aplica zoom antes de una acción, luego mantén (zoom, fx, fy) 100% congelado durante la interacción + comprensión para que los espectadores puedan leer gráficos y notificaciones toast.
4. Determinismo de reloj virtual a 60fps (render): Inyecta el Virtual Clock Shim (Date, performance.now, requestAnimationFrame) antes de cargar la página para que las transiciones CSS, las animaciones de ECharts, las trayectorias de cursor C2 de jerk mínimo (arcos sin^3(pi * u), ≤12% de overshoot de velocidad, inclinación de +/-6 grados, morfosis de flecha <-> mano señaladora) y los dobles clics con ondas avancen deterministamente fotograma a fotograma en FFmpeg.
5. Autoinspección con panel de contacto (verify): Genera un contact-sheet.png de 3x3 junto con verify-report.json (validación de flujo ffprobe + cero clics fuera de pantalla) e inspecciona visualmente cada panel antes de entregar.

Comandos CLI de utilidad (repo-cinema)

Cuando se instala globalmente o se ejecuta desde el repositorio (npx repo-cinema ... o node dist/cli.js ...), cada etapa produce archivos estructurados:

# 1. Leer cualquier repo y extraer escenarios de caso de uso (opcionalmente ejecutar repomix primero)
repo-cinema analyze --repo ./my-project --output ./out/dossier.json [--repomix]

# 2. Construir storyboard JSON de cámara/cursor causal + vista previa HTML visual
repo-cinema plan --dossier ./out/dossier.json --output ./out/storyboard.json --html ./out/storyboard.html --theme aurora-indigo

# 3. Construir escenario 4 en 1 (web-url | plugin-or-component | cli-terminal | hybrid)
repo-cinema stage --dossier ./out/dossier.json --plan ./out/storyboard.json --output ./out/stage.html [--url http://localhost:3000]

# 4. Captura CDP determinista a 60fps + SFX estéreo 48kHz (o TTS opcional)
repo-cinema render --plan ./out/storyboard.json --stage ./out/stage.html --output ./out/demo.mp4 --gif ./out/demo.gif --audio sfx

# 5. Validar flujos, límites de telemetría y construir panel de contacto visual 3x3
repo-cinema verify --video ./out/demo.mp4 --telemetry ./out/demo.telemetry.json --contact-sheet ./out/contact-sheet.png --output ./out/verify.json

# O ejecutar el pipeline completo de 5 etapas en un solo comando:
repo-cinema run --repo ./my-project --out-dir ./out --theme aurora-indigo

Flujo de trabajo del Director

Paso 1: Analizar repositorio y audiencia

Ejecuta repo-cinema analyze --repo <path> --output <dossier.json>. Lee los useCases generados:

• Verifica el archetype detectado (web-app, desktop-or-ide-plugin, cli-tool, ui-library, hybrid).
• Refina los subtítulos o añade fixtures de muestra auténticos del dominio si el repo tiene flujos de trabajo especializados (recuerda: cero datos personales, cero contadores solo para desarrolladores).

Paso 2: Planificar storyboard y aprobar encuadre

Ejecuta repo-cinema plan con --html e inspecciona storyboard.html (o revisa beats, captionWarnings y cameraKeyframes):

• Corrige cualquier advertencia del Anti-Slop Caption Linter (sin "sin precedentes", "de última generación", "sin fisuras" o subtítulos de más de 96 caracteres).
• Asegúrate de que el fotograma inicial (t=0) y el fotograma final (t=durationMs) estén limpios con zoom: 1.0 para un bucle perfecto del GIF del README.

Paso 3: Seleccionar adaptador de escenario

• web-url: La aplicación ya se ejecuta localmente (http://localhost:PORT). El grabador inyecta Virtual Clock Shim + superposición no intrusiva de cursor/cámara/subtítulos directamente en la página en vivo.
• plugin-or-component: Plugins de escritorio (Obsidian, VS Code, Raycast) o paquetes de componentes UI renderizados dentro de un cromo macOS Studio oscuro con módulos centrales reales empaquetados mediante esbuild.
• cli-terminal: Herramientas de terminal mostradas en una terminal macOS de vidrio con salida de comandos sincronizada, mosaicos de KPI y tarjetas de impacto de resultados.
• hybrid: Studio macOS de varias pestañas que combina la ejecución CLI junto con la salida visual en vivo y diagramas de arquitectura.

Paso 4: Renderizar master 60fps + GIF + Audio

Ejecuta repo-cinema render:

• Por defecto, --audio sfx sintetiza micro-SFX estéreo 48kHz sin dependencias (clics con paneo estéreo alineados con el cursor x, suave whoosh de aire al hacer zoom, timbre de confirmación de toast) — sin necesidad de claves API externas.
• Opcionalmente, --audio tts --tts-provider <macos-say|edge-tts|openai|elevenlabs> mezcla la narración limpiamente con los micro-SFX.

Paso 5: Verificar e inspeccionar visualmente

Ejecuta repo-cinema verify e inspecciona contact-sheet.png directamente con tu visor de archivos/imágenes:

• Confirma passed: true, offscreenClicks: 0 y texto legible en las 9 miniaturas de fotogramas clave.
• Si algún elemento se recorta cerca de los bordes del viewport, aumenta marginPx en computeCausalFraming o reduce zoom en 0.06 y vuelve a renderizar.

Guías de referencia

• Física de cámara y cursor
• Adaptadores de escenario 4 en 1
• Esquema de storyboard
• Arquitectura de código abierto y atribuciones

Errores comunes a evitar

• Seguir el puntero fotograma a fotograma durante la escritura/arrastre: Provoca mareos. Siempre bloquea el encuadre de la cámara por beat durante las pausas.
• Usar setTimeout del reloj real / captura de pantalla en tiempo real: Pierde fotogramas cuando la CPU se dispara y produce grabaciones entrecortadas de 24–40fps. Siempre maneja las animaciones mediante __rcStep(dtMs).
• Hacer zoom demasiado agresivo (> 1.35x) en gráficos o tablas anchas: Recorta las etiquetas del eje Y o las columnas de resumen más a la derecha. Mantén wideLockRatio en 0.70 para que fx = width / 2.
• Subir binarios .mp4 grandes directamente al repositorio de GitHub: Rastrea el .gif optimizado con paleta ligera + contact-sheet.png en docs/assets/ y adjunta el .mp4 a GitHub Releases o ignora *.mp4 localmente.