chetras-opsera/showrunner

Que fait showrunner ?

Transforme « fais-moi une vidéo de démo de cette application » en un fichier répétable et révisable. CLI : node ~/.showrunner/bin/showrunner.mjs (ou showrunner si lié). Installez une fois avec ./install-skill.sh depuis le dépôt.

Quand l'utiliser

L'utilisateur souhaite une vidéo d'une interface web que vous pouvez ouvrir dans un navigateur : une démo produit, une présentation de fonctionnalité, un enregistrement de « ce qui a changé », un tutoriel. Pas pour les applications de bureau natives ou tout ce qui nécessite une narration audio.

Protocole : réfléchir d'abord, exécuter ensuite

1. Confirmez qu'il est sûr d'enregistrer. Données locales, de staging ou jetables uniquement. N'enregistrez jamais la production avec des données réelles de clients. Ne mettez jamais de jetons dans le scénario ; utilisez ${env:NAME}.
2. Lancez l'application et ensemencez des données réalistes. Les états vides font une mauvaise démo. Créez les enregistrements dont l'histoire a besoin (un cas de succès, un cas d'échec, un cas en cours).
3. Rédigez le storyboard avant le JSON. Une démo de moins de 4 minutes : carte de titre, 8 à 12 scènes de 8 à 20 s, carte de résumé de clôture. Une idée par scène. Les légendes disent ce que le spectateur doit remarquer, pas ce que fait la souris.
4. Trouvez les cibles avec probe. showrunner probe <url> pour chaque page ; collez les objets {role,name} qu'il affiche. Préférez les rôles et les noms visibles aux CSS.
5. Validez puis faites un essai à sec. showrunner check s.json, puis showrunner run s.json --fast --strict. Un essai à sec dure environ un quart de la longueur réelle. Corrigez chaque étape signalée avant la prise réelle.
6. Lancez la prise réelle (showrunner run s.json --out out). Elle s'exécute en temps réel, donc lancez-la en arrière-plan et attendez-la ; ne bloquez pas un appel d'outil pendant plusieurs minutes.
7. Examinez les images. showrunner sheet out/<nom>.mp4 --every 5, puis ouvrez le PNG. Vérifiez : la légende cache-t-elle le sujet (utilisez "position": "left"), une scène a-t-elle échoué, des popups ou des visites guidées s'immiscent-ils, le thème est-il incorrect.
8. Rapportez le chemin, la durée, la résolution, la liste des scènes et tout ce qui n'a pas fonctionné. Ne validez pas et ne poussez pas la vidéo sauf si demandé.

Pièges qui coûtent du temps réel

Symptôme	Cause	Correctif
L'exécution plante pendant plusieurs minutes	Un mauvais sélecteur avec un délai d'attente par défaut de 30 s, répété	Showrunner utilise par défaut 8 s et abandonne la scène ; exécutez d'abord --fast --strict
Un lien ou un bouton « n'est pas visible »	La barre latérale se replie ou un menu est fermé dans cet état	Allez d'abord sur une page connue avec goto, ou ciblez directement l'URL de la page
Une visite guidée apparaît au milieu de la vidéo	L'application montre un onboarding aux nouveaux utilisateurs	Définissez les clés « visite vue » de l'application dans storage, ou listez un bouton Ignorer dans dismiss
getByText correspond à un doublon caché	Le texte apparaît aussi dans un nœud caché	Utilisez { "role": "button", "name": "/^ITEM-1\\b/" }
Les éléments de la barre latérale de documentation ne font rien	Ce sont des <button>, pas des liens	Ciblez { "role": "button", ... }
La légende cache le tiroir ou le formulaire	La légende en bas au centre chevauche un panneau latéral	"position": "left" ou "right"
La prise meurt lorsque le shell se ferme	La tâche en arrière-plan est liée au terminal	Exécutez-la comme une vraie tâche d'arrière-plan et interrogez son achèvement
La vidéo est vierge ou en mosaïque	Capture d'un navigateur intégré à un IDE	Utilisez le propre Chrome headless de Showrunner, pas une webview
Les sous-titres dérivent légèrement	Les repères sont chronométrés à partir de la création de la page	Acceptable pour une révision ; pas exact au niveau de l'image

Aide-mémoire du scénario

{
  "name": "demo", "baseUrl": "http://127.0.0.1:3000", "viewport": {"width":1440,"height":900},
  "storage": { "token": "${env:DEMO_TOKEN}" },
  "dismiss": ["text=Ignorer"],
  "scenes": [
    { "name": "Titre", "steps": [ {"goto":"/"}, {"card":{"title":"Acme","text":"Démo","hold":3000}} ] },
    { "name": "Créer", "steps": [
      {"caption":{"title":"1 · Créer","text":"Un clic.","position":"left","hold":1500}},
      {"click":{"role":"button","name":"Nouveau"}},
      {"type":{"into":{"label":"Nom"},"text":"Plan de lancement"}},
      {"press":"Entrée"}, {"wait":1500}
    ]},
    { "name": "Résumé", "steps": [ {"caption":null}, {"card":{"title":"Résumé","items":["A","B"],"hold":4000,"keep":true}} ] }
  ]
}

Actions : goto click hover type press scroll wait waitFor caption card storage (+ "optional": true sur n'importe quelle étape). Référence complète : le README du dépôt.

Sécurité

• Les scénarios sont des données : pas d'exécution de code, pas de shell. Le texte des légendes est échappé.
• Une étape en échec abandonne seulement sa scène ; --strict fait que le code de sortie est 1.
• Ne validez, ne poussez et ne partagez jamais la vidéo sauf si l'utilisateur le demande.