Showcase Capture

O que Showcase Capture faz?

Use esta skill quando alguém quiser screenshots, um GIF ou um passo a passo WebM de um projeto web. A ferramenta executa o Playwright em um site local ou ao vivo, segue um cenário declarativo e gera um README e uma galeria.

O que produz

• screens/*.png
• README.md com os screenshots e legendas
• index.html galeria
• showcase.json manifesto
• *.gif opcional
• *.webm opcional

Instalação

A partir do diretório da skill:

node scripts/install.mjs

A partir do pacote npm:

npx showcase-capture install

Ou manualmente:

npm install
npm run build
npx playwright install chromium

Verifique o ambiente:

npx showcase-capture doctor

Fluxo de trabalho

1. Inspecione o projeto.

   • Framework e comando de desenvolvimento.
   • Diretório de saída da build para sites estáticos.
   • Rotas e telas principais.
   • Fluxo de autenticação e usuário de teste.
   • Mecanismo de seed ou reset, geralmente localStorage ou cookies.
   • As 5 a 8 telas que melhor explicam o produto.
   • Um fluxo de ponta a ponta para o GIF e WebM.

2. Escreva showcase.config.yaml.

   • Use uma URL de servidor estático, comando ou ao vivo.
   • Use papéis (roles) e nomes acessíveis antes de seletores CSS.
   • Adicione um bloco reset para que cada cena comece de um estado conhecido.
   • Use mask para e-mails, tokens, nomes e detalhes de pagamento.
   • Mantenha o fluxo do GIF curto: 20 a 40 segundos.

3. Valide o cenário. Isso verifica as cenas e o fluxo do GIF.

npx showcase-capture check

4. Capture.

npx showcase-capture capture

5. Revise a saída.

   • Abra README.md e index.html.
   • Verifique o GIF e WebM.
   • Corrija seletores ausentes, cortes ruins ou tempo.
   • Execute novamente com --only <scene> durante a iteração.

6. Faça commit da configuração e da saída gerada.

Exemplo de configuração

name: LaunchPad
baseUrl: http://localhost:5173
outDir: docs/showcase

server:
  mode: command
  command: npm run dev
  url: http://localhost:5173

reset:
  localStorage:
    - launchpad.demo.v2

context:
  locale: en-ZA
  timezoneId: Africa/Johannesburg
  fixedTime: "2026-11-09T09:00:00+02:00"
  reducedMotion: reduce

viewports:
  desktop: { width: 1440, height: 900 }
  mobile: { width: 390, height: 844 }

scenes:
  - name: desktop
    viewport: desktop
    steps:
      - goto: /
      - waitFor: h1
      - screenshot: 01-home

      - goto: /login
      - waitFor: form
      - click:
          role: button
          name: Continue as test user
      - waitForUrl: "#/app/dashboard"
      - screenshot: 06-dashboard

  - name: mobile
    viewport: mobile
    steps:
      - goto: /login
      - waitFor: form
      - click:
          role: button
          name: Continue as test user
      - waitForUrl: "#/app/dashboard"
      - screenshot: 21-mobile-dashboard

gif:
  viewport: { width: 1024, height: 640 }
  size: { width: 960, height: 600 }
  fps: 8
  steps:
    - goto: /
    - caption: [1, Discover, "Learn, match and book in one place"]
    - wait: 600
    - scroll: 660
    - goto: /learn
    - caption: [1, "Explore six practical modules", "Built around real freelance questions"]

video:
  enabled: true
  size: { width: 1280, height: 720 }

Modos de servidor

Site estático:

server:
  mode: static
  dir: dist
  spa: true

Servidor de desenvolvimento:

server:
  mode: command
  command: npm run dev
  url: http://localhost:5173

URL ao vivo:

server:
  mode: none
baseUrl: https://example.com

Etapa de build opcional antes de servir:

build: npm run build

Sobreposição (overlay)

A sobreposição do GIF é opcional. Use-a para combinar com a marca do projeto ou mover a legenda para longe de conteúdo importante.

overlay:
  background: "rgba(8, 20, 38, 0.93)"
  accent: "#5367e8"
  font: "Inter, system-ui, sans-serif"
  offsetX: 24
  offsetY: 24

Defina overlay.enabled: false para gravar o GIF sem legendas ou cursor.

Referência de passos

• goto: /caminho
• waitFor: h1 ou waitFor: { role: heading, name: Dashboard }
• click: ".seletor" ou click: { role: button, name: Continue }
• fill: { selector: "#email", value: "[email protected]" }
• press: Enter
• hover: ".card"
• waitForUrl: "#/app/dashboard" ou waitForUrl: { pattern: "/app/", flags: "i" }
• wait: 500
• scroll: 600 ou scroll: { selector: ".footer" }
• screenshot: 01-home
• screenshot: { name: 01-home, fullPage: true }
• viewport: mobile
• caption: [1, "Título", "Subtítulo"] (apenas fluxo do GIF)
• reset: true
• eval: "localStorage.setItem('chave', 'valor')"
• run: function (apenas configuração TypeScript ou JavaScript)

Configuração TypeScript

Use uma configuração TypeScript quando o cenário precisar de lógica personalizada:

import { defineShowcase } from 'showcase-capture'

export default defineShowcase({
  name: 'Meu projeto',
  outDir: 'docs/showcase',
  server: { mode: 'static', dir: 'dist' },
  scenes: [
    {
      name: 'desktop',
      steps: [
        { goto: '/' },
        {
          run: async ({ page }) => {
            await page.evaluate(() => localStorage.setItem('theme', 'light'))
          },
        },
        { waitFor: 'h1' },
        { screenshot: '01-home' },
      ],
    },
  ],
})

Privacidade

• Não capture telas de administração, segredos, tokens ou detalhes de pagamento.
• Use mask para e-mails, nomes e dados de conta.
• Use uma conta de teste com dados fictícios.
• Verifique o GIF e WebM antes de publicar.
• A ferramenta não faz upload de nada.

Solução de problemas

• Could not launch Chromium: execute npx playwright install chromium ou defina CHROME_PATH.
• Server did not respond: verifique o comando, porta e URL. Use reuseExisting: true se o servidor de desenvolvimento já estiver em execução.
• waitFor expira: prefira seletores getByRole, verifique o título da página ou adicione um wait.
• GIF muito longo: encurte os passos, reduza fps ou reduza o viewport.
• WebM ausente: verifique se video.enabled é true e se existe um fluxo gif.
• Screenshots com tamanho errado: defina o viewport na cena ou na configuração.