journey-demo

Journey demo (Demonstração de Jornada)

Escreva uma jornada, teste-a, grave um clipe. Claude executa uma jornada de usuário no Chrome, salva cada tela como uma página HTML congelada, organiza os quadros em um storyboard que a pessoa edita no navegador, e só depois da aprovação renderiza um MP4 com HyperFrames. Nada é gravado da tela, então qualquer palavra em qualquer tela pode ser alterada posteriormente sem executar a jornada novamente.

Fonte da verdade: STORYBOARD.md + snapshots/*.html na pasta da demo. Todo o resto é gerado.

Necessidades

• Chrome com a extensão Claude no Chrome (para executar a jornada e capturar)
• Node 18+, e npx hyperframes (para as imagens e a renderização; sem etapa de instalação)
• Scripts neste skill: scripts/freeze.js (captura), scripts/demo.mjs (construção e quadro editável). Execute-os pelo caminho: node <caminho_do_skill>/scripts/demo.mjs …

A pasta da demo

docs/demos/<slug>/ no repositório da pessoa, a menos que ela nomeie outro local:

STORYBOARD.md        o plano: quadros, legendas, cliques, temporização, notas      (editar)
snapshots/*.html     as telas capturadas                                            (editar apenas texto)
index.html scenes/ boards/ .build/    gerados por demo.mjs                         (nunca editar)
out/<slug>.mp4       a renderização

Sugira adicionar ao .gitignore scenes/ .build/ boards/stills/ out/.

1. A jornada

Use um arquivo de jornada quando ele existir (docs/journeys/*.md: Start:, etapas numeradas, verificações Expect:, linhas > Note:). Se o skill browser-journeys estiver instalado, ele é o dono desse formato e de suas regras de execução, e você as seguirá. Ainda não há jornada? Escreva uma com a pessoa primeiro: a demo é tão boa quanto as etapas.

Antes de executar, pergunte em uma mensagem, com sua recomendação para cada item:

• Host: local ou staging; nunca produção, a menos que eles digam.
• Branch: quando a jornada oferecer uma escolha (copiar da biblioteca ou escrever nova, cartão salvo ou novo cartão), qual caminho a demo mostrará. Padrão: o caminho feliz mais curto.
• Valores: os valores de teste da jornada ("Teste de jornada — por favor, ignore") ou valores amigáveis para a demo que você propõe. Padrão: proponha valores amigáveis para a demo e use-os em todos os lugares onde aparecerem.
• Mensagem e público-alvo: elabore ambos a partir da jornada; eles confirmam.
• Efeitos colaterais: diga o que a execução cria naquele host (contas, pedidos, lances) e a limpeza da jornada, se houver.

Uma jornada escrita para outro host (Start: local, comandos de seed, códigos lidos de um log de desenvolvimento)? Suas linhas de configuração pertencem àquele host: pergunte pelos equivalentes neste, nunca adivinhe.

2. Execute e capture

1. resize_window para 1440×900 e mantenha esse tamanho durante toda a execução: cada quadro deve compartilhar um viewport, e a construção recusa tamanhos misturados.
2. Faça cada etapa como a jornada diz. Verifique cada Expect:; em caso de falha, pare e relate. Uma demo nunca é construída sobre um fluxo quebrado. Uma execução de captura não precisa ser em ritmo assistível: espere apenas até que a página tenha se estabilizado antes de cada congelamento.
3. Login e trocas de persona são responsabilidade da pessoa. Diga "Faça login como e me avise quando terminar", aguarde, e então continue. Um código que a jornada imprime em um log de desenvolvimento que você iniciou pode ser inserido por você; nunca uma senha ou um código da caixa de entrada de alguém. Não congele telas de login (elas mostram e-mails): o storyboard corta de antes do login para depois dele.
4. Escolha os quadros: um clique por quadro. Um quadro é a tela imediatamente antes de um clique que o espectador precisa seguir para entender o fluxo. Digitação, seleção e escolhas acontecem antes do congelamento, para que o quadro as mostre concluídas; quando o quadro deve mostrar um campo vazio, congele antes de digitar. Uma tela acessada por URL ou sem nada para pressionar é um quadro sem click (ele aparece gradualmente). Pule configuração e login. Mire em 4–8 quadros e sempre congele a tela final.
5. Congele: cole todo o conteúdo de scripts/freeze.js na página com javascript_tool (uma vez por carregamento de página; typeof window.__freeze informa), então await window.__freeze('03-open-the-orbit') (ordem de dois dígitos, depois um slug). Compare o viewport que ele retorna com o do primeiro quadro; se for diferente (uma janela de download ou barra de informações foi aberta), feche a barra e congele novamente.
6. Cada congelamento baixa <nome>.html para ~/Downloads. Mova-os para snapshots/ quando a execução terminar. Congelar um nome novamente faz o Chrome salvar <nome> (1).html: exclua o download antigo primeiro. Se o Chrome perguntar se permite vários downloads, a pessoa clica em Permitir.

3. Escreva STORYBOARD.md

Formato de storyboard do HyperFrames. Um quadro por tela congelada:

---
message: Abra um Orbit em menos de um minuto
audience: Criadores do YouTube decidindo se devem experimentar o ShoutOrbit
journey: docs/journeys/create-an-orbit.md (etapas 4–5, staging, 2026-11-13)
url: staging.shoutorbit.com
status: draft
---

## Quadro 3: Abra o Orbit (8-12s)
- duration: 4s
- snapshot: 03-open-the-orbit.html
- click: Abra o Orbit
- scene: Datas e oferta se preenchem automaticamente

A parte inferior do formulário, com as datas já preenchidas. O cursor pressiona "Abra o Orbit".
Pergunta em aberto: o campo de título ainda mostra seu placeholder. Digitar na tela ou manter?

• click: o rótulo inteiro do elemento, exatamente: seu texto visível, valor, placeholder ou aria-label ("Place bid · $25", não "Place bid"). A construção o encontra em toda execução e falha ruidosamente se não conseguir. Deixe de fora em um quadro sem clique.
• duration: segundos na tela, 3–5; 4s quando omitido.
• scene: a legenda na tela: curta, sobre o que o espectador obtém ("Datas se preenchem automaticamente"), não sobre o que eles pressionam.
• Linhas de plano: o que o quadro mostra e o cursor faz, em palavras simples.
• Pergunta em aberto: uma linha por coisa que a pessoa deve decidir. Olhe cada tela congelada em busca de: dados de teste ou lixo na tela; dados pessoais (e-mails, nomes reais, números de conta); placeholders onde valores reais pertencem; uma legenda que a tela contradiz ("ao vivo" sobre "Ainda não aceitando lances"); datas desatualizadas. Levante essas questões; nunca corrija silenciosamente.

4. Construa e entregue o quadro

node <skill>/scripts/demo.mjs serve docs/demos/<slug> --port 4321   # execute em segundo plano

Isso constrói e então serve http://127.0.0.1:4321/. Abra para a pessoa (Chrome ou open) e pare. No quadro, eles podem alterar legendas, cliques, segundos, títulos e ordem, remover quadros, escrever notas para o Claude, redigitar palavras na própria página capturada (Editar texto da página; renomear o elemento clicado carrega o clique junto), e pressionar Aprovar para renderização. Cada salvamento reconstrói as imagens.

5. Aja de acordo com as notas

Quando eles disserem que deixaram notas, leia STORYBOARD.md. Para cada linha > Note::

Eles pedem	Mudança
Legenda, tempo, ordem, clique	As chaves do quadro em STORYBOARD.md
Palavras diferentes na página	Texto naquele snapshots/*.html (apenas texto: mantenha tags e classes)
Uma tela que não foi capturada, ou um estado diferente	Execute aquela etapa da jornada novamente e congele
Algo que o fluxo não pode mostrar	Diga isso; ofereça a versão verdadeira mais próxima

Em seguida, transforme a nota em > Done: <o que mudou> (o quadro mostra estas como concluídas), defina status: draft no frontmatter (apenas a pessoa aprova), execute node <skill>/scripts/demo.mjs build docs/demos/<slug>, e diga a eles para atualizar o quadro. O servidor pode continuar rodando.

6. Renderize

Apenas quando o frontmatter disser status: approved, ou a pessoa disser para prosseguir no chat:

cd docs/demos/<slug> && npx hyperframes check && npx hyperframes render -o out/<slug>.mp4

Avisos do check sobre sub-composições, densidade de faixa e um filme mudo são esperados. Abra o MP4 para eles. Se a UI mudar posteriormente, execute a jornada novamente, recongele os quadros cujas telas mudaram, mantenha o storyboard e renderize: essa é a atualização completa.

Erros comuns

Sintoma	Causa e correção
O cursor cai abaixo ou ao lado do destino	Quadros capturados em tamanhos de janela diferentes, ou a página estava no meio da rolagem. Recapture em um tamanho.
nothing labelled "…" da construção	O texto click não corresponde exatamente à tela (maiúsculas/minúsculas, espaçamento, um →). Copie-o da página.
probe viewport was …	O chrome da janela do Chrome sem cabeça mudou; ajuste CHROME_UI em demo.mjs.
Um quadro mostra um campo vazio	Congelado antes da digitação. Preencha, então congele.
Imagens ou fontes ausentes em um quadro	Servidas de origem cruzada sem CORS, então freeze.js manteve a URL; elas carregam apenas enquanto aquele host estiver ativo. Anote como uma pergunta em aberto.
Stripe ou outros iframes em branco	freeze.js descarta iframes. Congele a tela antes ou depois deles, ou diga o que está faltando.
Chrome not found	Defina CHROME=/caminho/para/chrome.

Privacidade

Um snapshot contém tudo que estava na tela, com imagens embutidas. Antes de alguém compartilhar o quadro, a pasta ou o vídeo, verifique os quadros em busca de dados pessoais e levante o que encontrar como perguntas em aberto.