SixStringBny/showcase-capture

Captura de presentaciones

Usa este skill cuando alguien quiera capturas de pantalla, un GIF o un recorrido WebM de un proyecto web. La herramienta ejecuta Playwright contra un sitio local o en vivo, sigue un escenario declarativo y genera un README y una galería.

Qué produce

• screens/*.png
• README.md con las capturas y subtítulos
• index.html galería
• showcase.json manifiesto
• *.gif opcional
• *.webm opcional

Instalación

Desde el directorio del skill:

node scripts/install.mjs

Desde el paquete npm:

npx showcase-capture install

O manualmente:

npm install
npm run build
npx playwright install chromium

Verifica el entorno:

npx showcase-capture doctor

Flujo de trabajo

1. Inspecciona el proyecto.

   • Framework y comando de desarrollo.
   • Directorio de salida de compilación para sitios estáticos.
   • Rutas y pantallas clave.
   • Flujo de autenticación y usuario de prueba.
   • Mecanismo de inicialización o restablecimiento, normalmente localStorage o cookies.
   • Las 5 a 8 pantallas que mejor explican el producto.
   • Un flujo de extremo a extremo para el GIF y WebM.

2. Escribe showcase.config.yaml.

   • Usa una URL estática, de comando o en vivo.
   • Usa roles y nombres accesibles antes que selectores CSS.
   • Agrega un bloque reset para que cada escena comience desde un estado conocido.
   • Usa mask para correos electrónicos, tokens, nombres y detalles de pago.
   • Mantén el flujo del GIF corto: de 20 a 40 segundos.

3. Valida el escenario. Esto verifica las escenas y el flujo del GIF.

npx showcase-capture check

4. Captura.

npx showcase-capture capture

5. Revisa la salida.

   • Abre README.md e index.html.
   • Verifica el GIF y WebM.
   • Corrige selectores faltantes, recortes incorrectos o tiempos.
   • Vuelve a ejecutar con --only <escena> mientras iteras.

6. Confirma la configuración y la salida generada.

Ejemplo de configuración

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

Sitio estático:

server:
  mode: static
  dir: dist
  spa: true

Servidor de desarrollo:

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

URL en vivo:

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

Paso de compilación opcional antes de servir:

build: npm run build

Superposición

La superposición del GIF es opcional. Úsala para que coincida con la marca del proyecto o para mover el subtítulo lejos del contenido importante.

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

Establece overlay.enabled: false para grabar el GIF sin subtítulos ni cursor.

Referencia de pasos

• goto: /ruta
• waitFor: h1 o waitFor: { role: heading, name: Dashboard }
• click: ".selector" o click: { role: button, name: Continue }
• fill: { selector: "#email", value: "[email protected]" }
• press: Enter
• hover: ".card"
• waitForUrl: "#/app/dashboard" o waitForUrl: { pattern: "/app/", flags: "i" }
• wait: 500
• scroll: 600 o scroll: { selector: ".footer" }
• screenshot: 01-home
• screenshot: { name: 01-home, fullPage: true }
• viewport: mobile
• caption: [1, "Título", "Subtítulo"] (solo en flujo GIF)
• reset: true
• eval: "localStorage.setItem('key', 'value')"
• run: function (solo en configuración TypeScript o JavaScript)

Configuración TypeScript

Usa una configuración TypeScript cuando el escenario necesite lógica personalizada:

import { defineShowcase } from 'showcase-capture'

export default defineShowcase({
  name: 'My project',
  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' },
      ],
    },
  ],
})

Privacidad

• No captures pantallas de administración, secretos, tokens ni detalles de pago.
• Usa mask para correos electrónicos, nombres y datos de cuenta.
• Usa una cuenta de prueba con datos ficticios.
• Verifica el GIF y WebM antes de publicar.
• La herramienta no sube nada.

Solución de problemas

• Could not launch Chromium: ejecuta npx playwright install chromium o establece CHROME_PATH.
• Server did not respond: verifica el comando, puerto y URL. Usa reuseExisting: true si el servidor de desarrollo ya está en ejecución.
• waitFor se agota: prefiere selectores getByRole, verifica el título de la página o agrega un wait.
• El GIF es demasiado largo: acorta los pasos, reduce fps o reduce el viewport.
• Falta WebM: verifica que video.enabled sea true y que exista un flujo gif.
• Las capturas tienen el tamaño incorrecto: establece el viewport en la escena o en la configuración.