SixStringBny/showcase-capture

쇼케이스 캡처 (Showcase capture)

이 스킬은 사용자가 웹 프로젝트의 스크린샷, 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 또는 쿠키를 사용하는 시드 또는 리셋 메커니즘.
   • 제품을 가장 잘 설명하는 5~8개의 화면.
   • GIF 및 WebM을 위한 하나의 종단 간 흐름.

2. showcase.config.yaml을 작성합니다.

   • 정적, 명령어 또는 라이브 URL 서버를 사용합니다.
   • CSS 선택자보다 역할(role)과 접근 가능한 이름(accessible name)을 우선 사용합니다.
   • 모든 장면이 알려진 상태에서 시작하도록 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

캡션이나 커서 없이 GIF를 녹화하려면 overlay.enabled: false로 설정하세요.

단계 참조

• 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 흐름이 있는지 확인하세요.
• 스크린샷 크기가 잘못되었습니다: 장면 또는 설정에서 뷰포트를 설정하세요.