SixStringBny/showcase-capture

Showcase capture（ショーケースキャプチャ）

このスキルは、誰かが Web プロジェクトのスクリーンショット、GIF、または WebM ウォークスルーを必要としている場合に使用します。このツールは Playwright を使用してローカルサイトまたは公開サイトに対して実行され、宣言的なシナリオに従い、README とギャラリーを生成します。

生成されるもの

• screens/*.png
• スクリーンショットとキャプションを含む README.md
• index.html ギャラリー
• showcase.json マニフェスト
• オプションの *.gif
• オプションの *.webm

インストール

スキルディレクトリから:

node scripts/install.mjs

npm パッケージから:

npx showcase-capture install

手動で:

npm install
npm run build
npx playwright install chromium

環境を確認:

npx showcase-capture doctor

ワークフロー

1. プロジェクトを調査します。

   • フレームワークと開発コマンド。
   • 静的サイトのビルド出力ディレクトリ。
   • ルートと主要な画面。
   • 認証フローとテストユーザー。
   • シードまたはリセットメカニズム（通常は localStorage または Cookie）。
   • 製品を最もよく説明する 5 ～ 8 の画面。
   • GIF と WebM 用の 1 つのエンドツーエンドフロー。

2. showcase.config.yaml を記述します。

   • 静的、コマンド、またはライブ URL サーバーを使用します。
   • CSS セレクターの前にロールとアクセシブルな名前を使用します。
   • すべてのシーンが既知の状態から開始するように reset ブロックを追加します。
   • メール、トークン、名前、支払い詳細には mask を使用します。
   • GIF フローは短く（20 ～ 40 秒）に抑えます。

3. シナリオを検証します。これにより、シーンと GIF フローがチェックされます。

npx showcase-capture check

4. キャプチャします。

npx showcase-capture capture

5. 出力を確認します。

   • README.md と index.html を開きます。
   • GIF と WebM を確認します。
   • 不足しているセレクター、不適切な切り抜き、またはタイミングを修正します。
   • 反復中は --only <scene> を指定して再実行します。

6. 設定と生成された出力をコミットします。

設定例

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:
  mode: static
  dir: dist
  spa: true

開発サーバー:

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

公開 URL:

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

配信前のオプションのビルドステップ:

build: npm run build

オーバーレイ

GIF オーバーレイはオプションです。プロジェクトのブランドに合わせたり、キャプションを重要なコンテンツから遠ざけるために使用します。

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

overlay.enabled: false を設定すると、キャプションやカーソルなしで GIF を録画します。

ステップリファレンス

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

TypeScript 設定

シナリオにカスタムロジックが必要な場合は、TypeScript 設定を使用します:

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

プライバシー

• 管理画面、秘密情報、トークン、支払い詳細をキャプチャしないでください。
• メール、名前、アカウントデータには mask を使用してください。
• 架空のデータを使用したテストアカウントを使用してください。
• 公開前に GIF と WebM を確認してください。
• このツールは何もアップロードしません。

トラブルシューティング

• Could not launch Chromium: npx playwright install chromium を実行するか、CHROME_PATH を設定してください。
• Server did not respond: コマンド、ポート、URL を確認してください。開発サーバーが既に実行中の場合は reuseExisting: true を使用してください。
• waitFor がタイムアウトする: getByRole セレクターを優先して使用し、ページタイトルを確認するか、wait を追加してください。
• GIF が長すぎる: ステップを短縮するか、fps を下げるか、ビューポートを縮小してください。
• WebM がない: video.enabled が true で、gif フローが存在することを確認してください。
• スクリーンショットのサイズが正しくない: シーンまたは設定でビューポートを設定してください。