clickreel

O que clickreel faz?

Você está criando uma demonstração interativa do aplicativo real do usuário. Um visitante a abre em uma página de destino ou a partir de um link, clica no ponto destacado e a próxima tela real do aplicativo aparece. Ele decide em menos de um minuto se o aplicativo vale a pena ser testado. Um bom resultado percorre uma coisa que o aplicativo faz bem em 6 a 12 cliques.

Você escreve o storyboard e julga o resultado. O Clickreel faz o resto: abre o aplicativo em um navegador headless, executa cada etapa de verdade, fotografa a página antes e depois e empacota as telas e um player em um único arquivo HTML.

O comando

Tudo passa por um único script. Ele precisa apenas do Node e de um navegador baseado em Chromium já instalado na máquina.

node ${CLAUDE_SKILL_DIR}/scripts/clickreel.mjs <comando>

Se ${CLAUDE_SKILL_DIR} aparecer acima como texto literal, seu agente não o preencheu: use a pasta que contém este SKILL.md.

Comando	O que faz
build <storyboard>	Executa as etapas e escreve <nome>.html (a demonstração) e <nome>.stops.png (a folha de contato) ao lado do storyboard. Leva de 10 a 30 segundos.
check <storyboard>	Executa as etapas e escreve apenas a folha de contato, em uma pasta temporária. Use-o para testar um storyboard sem tocar no projeto.
doctor	Verifica se esta máquina pode construir uma demonstração. Execute-o primeiro se algo falhar ao iniciar.
init [arquivo]	Escreve um storyboard inicial.

Flags úteis: --out <dir>, --json, --headed (assista o navegador trabalhar), --force.

Como trabalhar

1. Decida o que a demonstração mostra

Uma demonstração, um fluxo. Pergunte a si mesmo qual é a coisa mais convincente que este aplicativo faz e construa a demonstração em torno dela. Se o usuário nomeou um recurso ou fluxo, esse é o assunto. Se ele disse apenas "faça uma demonstração", escolha você mesmo o fluxo principal (a coisa que a primeira frase do README promete) e diga qual você escolheu. Não peça ao usuário para escolher, a menos que o aplicativo tenha vários produtos não relacionados.

2. Execute o aplicativo e aprenda seus rótulos reais

Descubra como o aplicativo inicia (scripts do package.json, um README, uma pasta dist/). Em seguida, escolha uma:

• Já está em execução ou você pode iniciá-lo: defina "url".
• Um site estático ou uma pasta compilada: defina "serve": "./dist" e o Clickreel o serve.
• Você quer que a compilação seja repetível depois: defina "start": "npm run dev" com "url", e o Clickreel o inicia e espera.

As etapas visam elementos pelas palavras que uma pessoa vê: texto de botão, rótulo ou placeholder de um campo, aria-label. Leia os componentes do fluxo que você escolheu e copie os rótulos exatamente. Adivinhar desperdiça uma iteração.

A demonstração deve abrir em um estado que vale a pena ver. Uma tela inicial vazia ou uma barreira de login é uma abertura fraca. Se o aplicativo precisar de dados ou uma sessão autenticada, configure isso antes da primeira parada: use o script de semente do aplicativo, ou uma etapa eval que escreva em localStorage, ou faça login com uma conta de teste no início. Coloque senhas e tokens em variáveis de ambiente e refira-se a eles como ${env:NOME}; nunca escreva um segredo real no storyboard.

3. Escreva o storyboard

Salve-o como demo.click.json na raiz do projeto, a menos que o usuário queira em outro lugar. Se o projeto já tiver um storyboard Demoreel (*.reel.json), você pode construir a partir desse arquivo como ele está.

{
  "url": "http://localhost:5173",
  "displayUrl": "acme.app",
  "demo": {
    "title": "Acme",
    "intro": "Veja como um projeto vai da ideia à conclusão.",
    "cta": { "label": "Experimente grátis", "url": "https://acme.app/cadastro" }
  },
  "steps": [
    { "say": "Comece um projeto em segundos" },
    { "click": "Novo projeto" },
    { "type": "Lançamento do site", "into": "Nome do projeto" },
    { "click": "Criar projeto" },
    { "say": "Adicione tarefas tão rápido quanto você digita" },
    { "type": "Escrever o post de anúncio", "into": "Adicionar uma tarefa" },
    { "press": "Enter" }
  ]
}

Cada etapa se torna uma parada (algo que o visitante faz) ou nada:

Etapa	Na demonstração
{ "click": "Novo projeto" }	Um ponto de interação no elemento. O visitante clica nele e vê o resultado real.
{ "type": "olá", "into": "Email" }	Um ponto de interação no campo. Clicar nele reproduz o texto sendo digitado. Deixe into de fora para continuar digitando no campo focado.
{ "press": "Enter" }	Teclas para clicar, ou o visitante pressiona a tecla real. "Mod+K" é Cmd no macOS e Ctrl em outros lugares.
{ "hover": "Gráfico" }	Um ponto de interação que reage ao passar o mouse, ou a um toque em um telefone.
{ "select": "Pro", "in": "Plano" }	Um ponto de interação em um menu suspenso nativo.
{ "say": "Uma linha curta" }	A legenda mostrada durante as paradas depois dela. Ela permanece até o próximo say. Um say sem parada depois dele se torna um cartão com um botão Próximo.
{ "zoom": "Total" }	Uma nota: o elemento é iluminado, o resto da página escurece e um cartão mostra a legenda com um botão Próximo.
{ "scroll": 600 }, { "goto": "/configuracoes" }, { "wait": 800 }, { "waitFor": "Relatório pronto" }, { "eval": "..." }	Sem parada. A demonstração passa por eles sozinha. Use-os para configuração e para chegar ao lugar certo.

As palavras ao lado de cada ponto de interação são escritas para você: Clique em “Novo projeto”, Digite “Lançamento do site”, Pressione com as teclas. Adicione "hint": "Abra as configurações" a uma etapa para dizer do seu próprio jeito. Faça isso quando uma etapa usar um seletor que não tem nome legível (o padrão é então "Clique aqui").

Os alvos são correspondidos por nomes visíveis, correspondência exata primeiro. Quando um nome é ambíguo, adicione "nth": 2, ou use um seletor: "css=.sidebar button", "#save", "testid=submit". Adicione "optional": true a uma etapa que pode não ter nada em que agir, como descartar um banner de cookies.

A lista completa de etapas, opções, estilos e molduras está em references/storyboard.md. Leia-o antes de usar algo não mostrado aqui.

4. Construir

node ${CLAUDE_SKILL_DIR}/scripts/clickreel.mjs build demo.click.json

Uma etapa que não pode ser feita interrompe a construção e informa exatamente o que está errado:

Etapa 4 (click "Criar projeto") falhou: Não foi possível encontrar "Criar projeto" para clicar.
  Você quis dizer: "Create project"?
  Na tela agora: "Cancelar", "Criar projeto", "Nome do projeto"
  Captura de tela da página naquele momento: /tmp/clickreel/demo-123/step-04-failed.jpg

Corrija a etapa e construa novamente. Se o projeto já tiver um <nome>.html que o Clickreel não escreveu, a construção se recusa a substituí-lo: defina "name" no storyboard ou passe --out <dir>.

Uma construção bem-sucedida ainda pode imprimir notas. Leia-as. Nota: Etapa 4 (...) não mudou nada que você possa ver na página significa que a etapa encontrou algo em que agir, mas a página parecia igual depois: quase sempre encontrou o elemento errado, e sua parada na demonstração não faz nada. Corrija o alvo (um nome mais exato, nth, ou um seletor) e construa novamente.

5. Veja o resultado antes de relatá-lo

build escreve uma folha de contato, <nome>.stops.png: uma imagem por parada, com o ponto de interação desenhado nela e a etapa e legenda abaixo dela, depois a última tela. Abra-a e veja cada imagem. É assim que você verifica sua própria demonstração.

Verifique cada imagem para:

• O ponto de interação. A caixa está no elemento que você quis dizer, e esse elemento está visível? Uma caixa na coisa errada significa que o nome correspondeu a outra coisa: use nth ou um seletor.
• Verdade. A imagem mostra o aplicativo funcionando? Procure por mensagens de erro, estados vazios, spinners que nunca terminaram, texto placeholder. Cada imagem é o que o visitante vê antes de clicar, então a imagem depois dela mostra o que o clique fez.
• Legendas. A legenda abaixo da imagem descreve o que está acontecendo nela?
• A última imagem. Ela fica atrás do cartão final. Deve ser o estado de melhor aparência do aplicativo.

Corrija o storyboard e construa novamente. Duas ou três rodadas é normal. Pare quando a folha parecer correta.

6. Entregue

Diga ao usuário onde está o arquivo, seu tamanho, quantas paradas tem e qual fluxo mostra. Dê a linha de incorporação que build imprimiu:

<iframe src="demo.html" title="Acme: demonstração interativa" loading="lazy" allowfullscreen style="width:100%;aspect-ratio:1372/889;border:0;border-radius:12px"></iframe>

Diga claramente o que é o arquivo: um arquivo HTML com imagens do aplicativo dentro, que funciona a partir do disco e de qualquer servidor web, e não carrega nada da rede. Relate quaisquer notas que o Clickreel imprimiu (erros de página, elementos cobertos, arquivo grande). Se você não conseguiu fazer uma etapa funcionar e a removeu, diga isso.

Um README do GitHub não pode executar um arquivo HTML. Para um README, link para a demonstração onde ela está hospedada (GitHub Pages serve docs/ bem), ou use um GIF do Demoreel.

Escrevendo uma boa demonstração, em resumo

• Seis a doze paradas. Cada parada é um clique que o visitante tem que fazer. Corte a configuração, ou faça-a com eval antes da primeira parada.
• Legendas são manchetes. Sete palavras ou menos, sobre o benefício ("Marque as coisas enquanto avança"), não a ação ("Agora clique na caixa de seleção"). A dica já diz o que clicar. Três a cinco legendas em uma demonstração.
• Digite coisas reais. "Lançamento do site", não "teste" ou "asdf". O texto digitado faz parte da apresentação.
• Abra e feche bem. Defina demo.title e um demo.intro de uma linha para o cartão inicial. Termine no melhor estado do aplicativo e defina demo.cta para onde o visitante deve ir a seguir.
• Escolha o tamanho para onde ele ficará. A viewport padrão desktop é adequada para uma página de destino. Para um aplicativo web móvel, use "viewport": "phone". Uma viewport menor faz o aplicativo parecer maior em uma incorporação pequena.

Mais sobre estrutura, notas, reprodução automática e escuta dos eventos da demonstração: references/writing.md.

Privacidade e honestidade

• Tudo é executado nesta máquina. O Clickreel não abre nenhuma conexão de rede própria; o navegador carrega apenas o aplicativo para o qual você o aponta. O arquivo finalizado não faz requisições e não rastreia nada.
• A demonstração é feita de imagens do que estava na página e é feita para ser publicada. Use contas de teste e dados inventados. Não capture dados reais de clientes, endereços de email reais ou URLs internas sem a autorização do usuário.
• Mostre o aplicativo como ele é. Não use eval para fingir um recurso, esconder um erro real ou fazer algo parecer mais rápido do que é. Alimentar dados e esconder sobreposições de desenvolvimento é aceitável; inventar comportamento não é.

O que não pode fazer

Apenas aplicativos web. As telas são imagens, então um visitante não pode rolar dentro de uma parada, selecionar texto ou sair do caminho que você escolheu. Uma etapa drag é reproduzida quando seu ponto de interação é clicado. Não segue links que abrem uma nova aba, não pode acessar iframes e não pode enviar arquivos. Caixas nativas alert() e confirm() são aceitas automaticamente e não aparecem. Se o fluxo depender de uma dessas, diga isso e construa a parte que funciona.

Quando algo falha de uma forma que a mensagem de erro não explica, veja references/troubleshooting.md.