cheats-opsera/showrunner

¿Qué hace showrunner?

Convierte 'hazme un video demo de esta app' en un archivo repetible y revisable. CLI: node ~/.showrunner/bin/showrunner.mjs (o showrunner si está enlazado). Instala una vez con ./install-skill.sh desde el repositorio.

Cuándo usarlo

El usuario quiere un video de una interfaz web que puedas abrir en un navegador: una demo de producto, un recorrido de funcionalidades, una grabación de 'muestra lo que cambió', un tutorial. No es para aplicaciones de escritorio nativas ni para nada que necesite narración de audio.

Protocolo: piensa primero, luego ejecuta

1. Confirma que sea seguro grabar. Solo local, staging o datos desechables. Nunca grabes producción con datos reales de clientes. Nunca coloques tokens en el escenario; usa ${env:NAME}.
2. Haz que la aplicación funcione y siembra datos realistas. Los estados vacíos hacen una mala demo. Crea los registros que la historia necesita (un caso de éxito, un caso de fallo, un caso en progreso).
3. Escribe el storyboard antes del JSON. Una demo de menos de 4 minutos: tarjeta de título, 8-12 escenas de 8-20 s, tarjeta de resumen final. Una idea por escena. Los subtítulos dicen lo que el espectador debe notar, no lo que el ratón está haciendo.
4. Encuentra objetivos con probe. showrunner probe <url> para cada página; pega los objetos {role,name} que imprime. Prefiere roles y nombres visibles sobre CSS.
5. Valida y luego haz dry-run. showrunner check s.json, luego showrunner run s.json --fast --strict. Un dry-run es aproximadamente un cuarto de la duración real. Corrige cada paso reportado antes de la grabación real.
6. Graba la toma real (showrunner run s.json --out out). Se ejecuta en tiempo real, así que iníciala en segundo plano y espera; no bloquees una llamada de herramienta durante minutos.
7. Revisa los fotogramas. showrunner sheet out/<name>.mp4 --every 5, luego abre el PNG. Busca: subtítulos que cubran el sujeto (usa "position": "left"), una escena que haya fallado, popups o tours que se cuelen, el tema incorrecto.
8. Informa la ruta, duración, resolución, la lista de escenas y cualquier cosa que no haya funcionado. No confirmes ni subas el video a menos que te lo pidan.

Trampas que cuestan tiempo real

Síntoma	Causa	Solución
La ejecución se cuelga durante minutos	Un selector incorrecto con un timeout predeterminado de 30 s, repetido	Showrunner usa 8 s por defecto y abandona la escena; ejecuta --fast --strict primero
Un enlace o botón 'no es visible'	La barra lateral se colapsa o un menú está cerrado en ese estado	goto a una página conocida primero, o apunta directamente a la URL de la página
El tour de primera ejecución aparece a mitad del video	La aplicación muestra onboarding a nuevos usuarios	Configura las claves de 'tour visto' de la aplicación en storage, o lista un botón Skip en dismiss
getByText coincide con un duplicado oculto	El texto también aparece en un nodo oculto	Usa { "role": "button", "name": "/^ITEM-1\\b/" }
Los elementos de la barra lateral de documentación no hacen nada	Son <button>, no enlaces	Apunta a { "role": "button", ... }
El subtítulo oculta el cajón o formulario	El subtítulo centrado en la parte inferior se superpone a un panel lateral	"position": "left" o "right"
La grabación muere cuando el shell se cierra	Trabajo en segundo plano vinculado a la terminal	Ejecútalo como una tarea de fondo adecuada y consulta hasta que termine
El video está en blanco o con mosaicos	Captura de un navegador embebido en el IDE	Usa el Chrome headless propio de Showrunner, no una webview
Los subtítulos se desvían ligeramente	Las señales están temporizadas desde la creación de la página	Aceptable para revisión; no son exactos fotograma a fotograma

Chuleta del escenario

{
  "name": "demo", "baseUrl": "http://127.0.0.1:3000", "viewport": {"width":1440,"height":900},
  "storage": { "token": "${env:DEMO_TOKEN}" },
  "dismiss": ["text=Skip"],
  "scenes": [
    { "name": "Título", "steps": [ {"goto":"/"}, {"card":{"title":"Acme","text":"Demo","hold":3000}} ] },
    { "name": "Crear", "steps": [
      {"caption":{"title":"1 · Crear","text":"Un clic.","position":"left","hold":1500}},
      {"click":{"role":"button","name":"Nuevo"}},
      {"type":{"into":{"label":"Nombre"},"text":"Plan de lanzamiento"}},
      {"press":"Enter"}, {"wait":1500}
    ]},
    { "name": "Resumen", "steps": [ {"caption":null}, {"card":{"title":"Resumen","items":["A","B"],"hold":4000,"keep":true}} ] }
  ]
}

Acciones: goto click hover type press scroll wait waitFor caption card storage (+ "optional": true en cualquier paso). Referencia completa: el README del repositorio.

Seguridad

• Los escenarios son datos: no hay ejecución de código, no hay shell. El texto de los subtítulos está escapado.
• Un paso fallido abandona solo su escena; --strict hace que el código de salida sea 1.
• Nunca confirmes, subas ni compartas el video a menos que el usuario lo pida.