SixStringBny/showcase-capture

Was macht showcase-capture?

Verwende diese Fähigkeit, wenn jemand Screenshots, ein GIF oder eine WebM-Durchlaufaufnahme eines Webprojekts wünscht. Das Tool führt Playwright gegen eine lokale oder Live-Seite aus, folgt einem deklarativen Szenario und erstellt eine README sowie eine Galerie.

Was erstellt wird

• screens/*.png
• README.md mit den Screenshots und Bildunterschriften
• index.html Galerie
• showcase.json Manifest
• optional *.gif
• optional *.webm

Installation

Aus dem Skill-Verzeichnis:

node scripts/install.mjs

Aus dem npm-Paket:

npx showcase-capture install

Oder manuell:

npm install
npm run build
npx playwright install chromium

Überprüfe die Umgebung:

npx showcase-capture doctor

Arbeitsablauf

1. Projektdurchsicht.

   • Framework und Dev-Befehl.
   • Build-Ausgabeverzeichnis für statische Seiten.
   • Routen und wichtige Bildschirme.
   • Authentifizierungsablauf und Testbenutzer.
   • Seed- oder Reset-Mechanismus, normalerweise localStorage oder Cookies.
   • Die 5 bis 8 Bildschirme, die das Produkt am besten erklären.
   • Ein End-to-End-Ablauf für das GIF und das WebM.

2. showcase.config.yaml schreiben.

   • Verwende eine statische, Befehls- oder Live-URL als Server.
   • Verwende Rollen und zugängliche Namen vor CSS-Selektoren.
   • Füge einen reset-Block hinzu, damit jede Szene aus einem bekannten Zustand startet.
   • Verwende mask für E-Mails, Tokens, Namen und Zahlungsdetails.
   • Halte den GIF-Ablauf kurz: 20 bis 40 Sekunden.

3. Szenario validieren. Dies überprüft die Szenen und den GIF-Ablauf.

npx showcase-capture check

4. Aufnahme.

npx showcase-capture capture

5. Ausgabe überprüfen.

   • Öffne README.md und index.html.
   • Überprüfe das GIF und das WebM.
   • Korrigiere fehlende Selektoren, schlechte Ausschnitte oder Timing-Probleme.
   • Führe während der Iteration erneut mit --only <scene> aus.

6. Die Konfiguration und die generierte Ausgabe committen.

Konfigurationsbeispiel

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 }

Server-Modi

Statische Seite:

server:
  mode: static
  dir: dist
  spa: true

Entwicklungsserver:

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

Live-URL:

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

Optionaler Build-Schritt vor dem Ausliefern:

build: npm run build

Overlay

Das GIF-Overlay ist optional. Verwende es, um es an die Marke des Projekts anzupassen oder die Bildunterschrift von wichtigen Inhalten fernzuhalten.

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

Setze overlay.enabled: false, um das GIF ohne Bildunterschriften oder Cursor aufzuzeichnen.

Schritt-Referenz

• goto: /path
• waitFor: h1 oder waitFor: { role: heading, name: Dashboard }
• click: ".selector" oder click: { role: button, name: Continue }
• fill: { selector: "#email", value: "[email protected]" }
• press: Enter
• hover: ".card"
• waitForUrl: "#/app/dashboard" oder waitForUrl: { pattern: "/app/", flags: "i" }
• wait: 500
• scroll: 600 oder scroll: { selector: ".footer" }
• screenshot: 01-home
• screenshot: { name: 01-home, fullPage: true }
• viewport: mobile
• caption: [1, "Title", "Subtitle"] (nur GIF-Ablauf)
• reset: true
• eval: "localStorage.setItem('key', 'value')"
• run: function (nur TypeScript- oder JavaScript-Konfiguration)

TypeScript-Konfiguration

Verwende eine TypeScript-Konfiguration, wenn das Szenario benutzerdefinierte Logik benötigt:

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' },
      ],
    },
  ],
})

Datenschutz

• Erfasse keine Admin-Bildschirme, Geheimnisse, Tokens oder Zahlungsdetails.
• Verwende mask für E-Mails, Namen und Kontodaten.
• Verwende ein Testkonto mit fiktiven Daten.
• Überprüfe das GIF und das WebM vor der Veröffentlichung.
• Das Tool lädt nichts hoch.

Fehlerbehebung

• Could not launch Chromium: führe npx playwright install chromium aus oder setze CHROME_PATH.
• Server did not respond: überprüfe den Befehl, den Port und die URL. Verwende reuseExisting: true, wenn der Dev-Server bereits läuft.
• waitFor läuft ab: bevorzuge getByRole-Selektoren, überprüfe den Seitentitel oder füge ein wait hinzu.
• GIF ist zu lang: kürze die Schritte, reduziere fps oder verkleinere den Viewport.
• WebM fehlt: stelle sicher, dass video.enabled wahr ist und ein gif-Ablauf existiert.
• Screenshots haben die falsche Größe: setze den Viewport in der Szene oder Konfiguration.