cheatas-opsera/showrunner

O que showrunner faz?

Transforma "faça um vídeo de demonstração deste aplicativo" em um arquivo repetível e revisável. CLI: node ~/.showrunner/bin/showrunner.mjs (ou showrunner se linkado). Instale uma vez com ./install-skill.sh a partir do repositório.

Quando usar

O usuário deseja um vídeo de uma interface web que você pode abrir em um navegador: uma demonstração de produto, um tour de funcionalidades, uma gravação de "mostre o que mudou", um tutorial. Não para aplicativos desktop nativos ou qualquer coisa que precise de narração de áudio.

Protocolo: pense primeiro, depois execute

1. Confirme que é seguro gravar. Apenas dados locais, de staging ou descartáveis. Nunca grave produção com dados reais de clientes. Nunca coloque tokens no cenário; use ${env:NOME}.
2. Coloque o aplicativo em execução e semeie dados realistas. Estados vazios resultam em uma demonstração ruim. Crie os registros que a história precisa (um caso de sucesso, um caso de falha, um caso em andamento).
3. Escreva o storyboard antes do JSON. Uma demonstração com menos de 4 minutos: cartão de título, 8-12 cenas de 8-20 s, cartão de resumo de encerramento. Uma ideia por cena. As legendas dizem o que o espectador deve notar, não o que o mouse está fazendo.
4. Encontre alvos com probe. showrunner probe <url> para cada página; cole os objetos {role,name} que ele imprime. Prefira roles e nomes visíveis em vez de CSS.
5. Valide e depois simule. showrunner check s.json, depois showrunner run s.json --fast --strict. Uma simulação tem cerca de um quarto da duração real. Corrija cada etapa relatada antes da tomada real.
6. Grave a tomada real (showrunner run s.json --out out). Ela é executada em tempo real, então inicie-a em segundo plano e aguarde; não bloqueie uma chamada de ferramenta por minutos.
7. Revise os quadros. showrunner sheet out/<nome>.mp4 --every 5, depois abra o PNG. Verifique: legenda cobrindo o assunto (use "position": "left"), uma cena que apresentou erro, pop-ups ou tours vazando, o tema errado.
8. Relate o caminho, duração, resolução, a lista de cenas e qualquer coisa que não funcionou. Não faça commit ou push do vídeo a menos que solicitado.

Armadilhas que custam tempo real

Sintoma	Causa	Correção
A execução trava por minutos	Um seletor errado com tempo limite padrão de 30 s, repetido	Showrunner usa 8 s por padrão e abandona a cena; execute --fast --strict primeiro
Um link ou botão "não está visível"	A barra lateral recolhe ou um menu está fechado naquele estado	goto para uma página conhecida primeiro, ou aponte diretamente para a URL da página
Tour de primeira execução aparece no meio do vídeo	O aplicativo mostra integração para novos usuários	Defina as chaves de "tour visto" do aplicativo em storage, ou liste um botão Pular em dismiss
getByText corresponde a uma duplicata oculta	O texto aparece em um nó oculto também	Use { "role": "button", "name": "/^ITEM-1\\b/" }
Itens da barra lateral da documentação não fazem nada	Eles são <button>s, não links	Mire em { "role": "button", ... }
Legenda esconde a gaveta ou formulário	Legenda central inferior sobrepõe um painel lateral	"position": "left" ou "right"
A gravação morre quando o shell fecha	Tarefa em segundo plano vinculada ao terminal	Execute como uma tarefa de fundo adequada e consulte a conclusão
O vídeo está em branco ou quadriculado	Capturando um navegador incorporado ao IDE	Use o próprio Chrome headless do Showrunner, não uma webview
Legendas desviam ligeiramente	As indicações são temporizadas a partir da criação da página	Bom para revisão; não exato por quadro

Folha de dicas do cenário

{
  "name": "demo", "baseUrl": "http://127.0.0.1:3000", "viewport": {"width":1440,"height":900},
  "storage": { "token": "${env:DEMO_TOKEN}" },
  "dismiss": ["text=Pular"],
  "scenes": [
    { "name": "Título", "steps": [ {"goto":"/"}, {"card":{"title":"Acme","text":"Demonstração","hold":3000}} ] },
    { "name": "Criar", "steps": [
      {"caption":{"title":"1 · Criar","text":"Um clique.","position":"left","hold":1500}},
      {"click":{"role":"button","name":"Novo"}},
      {"type":{"into":{"label":"Nome"},"text":"Plano de lançamento"}},
      {"press":"Enter"}, {"wait":1500}
    ]},
    { "name": "Resumo", "steps": [ {"caption":null}, {"card":{"title":"Resumo","items":["A","B"],"hold":4000,"keep":true}} ] }
  ]
}

Ações: goto click hover type press scroll wait waitFor caption card storage (+ "optional": true em qualquer etapa). Referência completa: o README do repositório.

Segurança

• Cenários são dados: sem execução de código, sem shell. O texto da legenda é escapado.
• Uma etapa com falha abandona apenas sua cena; --strict faz o código de saída ser 1.
• Nunca faça commit, push ou compartilhe o vídeo a menos que o usuário solicite.