clipwise 0.5.0 → 0.5.2

package/README.ko.md

@@ -5,7 +5,7 @@
 YAML 시나리오를 작성하면 시네마틱 데모 영상(MP4/GIF)을 자동으로 만들어주는 스크린 레코더. Playwright CDP 기반.
 
 <p align="center">
-  <img src="https://kwakseongjae.github.io/clipwise/demo.gif" alt="Clipwise 데모" width="100%" />
+  <img src="./docs/demo.gif" alt="Clipwise 데모" width="100%" />
 </p>
 
 > *`npx clipwise demo` 한 줄로 생성된 영상입니다 — YAML 파일 1개, 239줄.*
@@ -337,6 +337,37 @@ VideoToolbox는 런타임에 자동 감지되며, 사용 불가 시 `libx264`로
 
 [PROMPTS.md](./PROMPTS.md)에 바로 사용할 수 있는 AI 프롬프트 템플릿이 있습니다. ChatGPT나 Claude에 복붙하고 내 사이트 URL만 넣으면 YAML 시나리오를 생성해줍니다.
 
+## Claude Code 스킬
+
+Clipwise에는 [Claude Code](https://claude.com/claude-code) 스킬이 내장되어 있습니다. 설치 후 Claude Code에서 `/clipwise`를 입력하면 자연어로 YAML 시나리오 생성, 검증, 녹화까지 한 번에 할 수 있습니다.
+
+### 스킬 설치
+
+```bash
+npx clipwise install-skill
+```
+
+`.claude/skills/clipwise.md`에 스킬 파일이 복사됩니다 (`.claude/` 디렉토리가 있으면 프로젝트 레벨, 없으면 `~/.claude/skills/`에 설치).
+
+### 사용법
+
+Claude Code 세션에서:
+
+```
+/clipwise
+> http://localhost:3000 대시보드 데모 녹화해줘
+  — 로그인 버튼 클릭, 이메일/비밀번호 입력, 분석 페이지 이동
+```
+
+Claude가 자동으로:
+1. `clipwise.yaml` 시나리오 생성
+2. `npx clipwise validate`로 검증
+3. `npx clipwise record`로 MP4 녹화
+
+### 업데이트
+
+clipwise 업그레이드 후 `npx clipwise install-skill`을 다시 실행하면 최신 스킬로 업데이트됩니다.
+
 ## GitHub Pages
 
 `docs/` 폴더에 문서 사이트와 라이브 데모 대시보드가 포함되어 있습니다:

package/README.md

@@ -5,7 +5,7 @@
 Scriptable cinematic screen recorder for product demos — YAML in, polished MP4 out. Powered by Playwright CDP.
 
 <p align="center">
-  <img src="https://kwakseongjae.github.io/clipwise/demo.gif" alt="Clipwise demo" width="100%" />
+  <img src="./docs/demo.gif" alt="Clipwise demo" width="100%" />
 </p>
 
 > *Generated with `npx clipwise demo` — 1 YAML file, 239 lines, one command.*
@@ -421,6 +421,37 @@ npx clipwise record my-scenario.yaml -f mp4 -o ./output
 
 See [PROMPTS.md](./PROMPTS.md) for a ready-to-use prompt template. Copy-paste it to ChatGPT or Claude with your site URL, and get a working YAML scenario back.
 
+## Claude Code Skill
+
+Clipwise ships a built-in [Claude Code](https://claude.com/claude-code) skill. Once installed, type `/clipwise` in Claude Code to generate YAML scenarios, validate, and record — all through natural language.
+
+### Install the skill
+
+```bash
+npx clipwise install-skill
+```
+
+This copies the skill file to `.claude/skills/clipwise.md` (project-level if `.claude/` exists, otherwise `~/.claude/skills/`).
+
+### Usage
+
+In any Claude Code session:
+
+```
+/clipwise
+> Record a demo of my dashboard at http://localhost:3000
+  — click the login button, type credentials, navigate to analytics
+```
+
+Claude will:
+1. Generate a complete `clipwise.yaml` scenario
+2. Run `npx clipwise validate` to check for errors
+3. Run `npx clipwise record` to produce the MP4
+
+### Update
+
+Re-run `npx clipwise install-skill` after upgrading clipwise to get the latest skill.
+
 ## GitHub Pages
 
 Clipwise includes a documentation site and a live demo dashboard in the `docs/` folder. To host it:

package/dist/cli/index.js

@@ -2881,17 +2881,17 @@ var StreamingSession = class extends EventEmitter {
 };
 
 // src/cli/index.ts
-import { writeFile as writeFile2, mkdir as mkdir2, access } from "fs/promises";
+import { writeFile as writeFile2, mkdir as mkdir2, access, copyFile, readFile as readFile3 } from "fs/promises";
 import { join as join2, resolve, dirname } from "path";
-import { pathToFileURL } from "url";
+import { pathToFileURL, fileURLToPath as fileURLToPath2 } from "url";
+import { homedir } from "os";
 var program = new Command();
 program.name("clipwise").description(
   "Playwright-based cinematic screen recorder for product demos"
 ).version("0.1.0");
 program.command("record").description("Record a demo from a YAML scenario file").argument("<scenario>", "Path to YAML scenario file").option("-o, --output <dir>", "Output directory", "./output").option(
   "-f, --format <format>",
-  "Output format (gif|mp4|png-sequence)",
-  "gif"
+  "Output format (gif|mp4|png-sequence)"
 ).option("--no-effects", "Disable all effects").action(async (scenarioPath, options) => {
   const spinner = ora();
   try {
@@ -3359,4 +3359,52 @@ Error: ${message}`));
     process.exit(1);
   }
 });
+program.command("install-skill").description("Install the Clipwise skill for Claude Code").action(async () => {
+  try {
+    const __dirname = dirname(fileURLToPath2(import.meta.url));
+    const skillSource = resolve(__dirname, "..", "..", "skills", "clipwise.md");
+    try {
+      await access(skillSource);
+    } catch {
+      console.error(chalk.red("Error: Skill file not found in clipwise package."));
+      console.error(chalk.yellow("This may happen if you're running from source. Try: npm rebuild clipwise"));
+      process.exit(1);
+    }
+    const projectSkillDir = resolve(".claude", "skills");
+    const globalSkillDir = join2(homedir(), ".claude", "skills");
+    let targetDir;
+    try {
+      await access(resolve(".claude"));
+      targetDir = projectSkillDir;
+    } catch {
+      targetDir = globalSkillDir;
+    }
+    await mkdir2(targetDir, { recursive: true });
+    const targetPath = join2(targetDir, "clipwise.md");
+    try {
+      const existing = await readFile3(targetPath, "utf-8");
+      const incoming = await readFile3(skillSource, "utf-8");
+      if (existing === incoming) {
+        console.log(chalk.green("Clipwise skill is already up to date."));
+        console.log(`  Location: ${chalk.bold(targetPath)}`);
+        console.log(`
+Use ${chalk.bold("/clipwise")} in Claude Code to get started.`);
+        return;
+      }
+    } catch {
+    }
+    await copyFile(skillSource, targetPath);
+    console.log(chalk.green("Clipwise skill installed successfully!"));
+    console.log(`  Location: ${chalk.bold(targetPath)}`);
+    console.log(`
+Usage in Claude Code:`);
+    console.log(`  ${chalk.bold("/clipwise")} \u2014 Generate YAML scenarios, validate, and record demos`);
+    console.log(`
+To update the skill later, run this command again.`);
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    console.error(chalk.red(`Failed to install skill: ${message}`));
+    process.exit(1);
+  }
+});
 program.parse();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "clipwise",
-  "version": "0.5.0",
+  "version": "0.5.2",
   "description": "Scriptable cinematic screen recorder for product demos — YAML in, polished MP4 out",
   "type": "module",
   "main": "dist/index.js",
@@ -10,6 +10,7 @@
   },
   "files": [
     "dist",
+    "skills",
     "README.md",
     "LICENSE"
   ],

package/skills/clipwise.md

@@ -0,0 +1,373 @@
+# Clipwise — Cinematic Screen Recorder
+
+You are an expert at creating Clipwise YAML scenarios. Clipwise is a Playwright + CDP-based scriptable screen recorder that turns YAML scenarios into polished MP4/GIF demo videos with cinematic effects (zoom, cursor trail, device frame, keystroke HUD, etc.).
+
+TRIGGER: when the user wants to record a demo video, create a screen recording scenario, generate a product demo, or mentions "clipwise".
+
+## Setup Check
+
+Before creating a scenario, verify clipwise is installed:
+
+```bash
+npx clipwise --version
+```
+
+If not installed:
+```bash
+npm install -D clipwise
+```
+
+ffmpeg is required for MP4 output:
+```bash
+# macOS
+brew install ffmpeg
+# Ubuntu
+sudo apt install ffmpeg
+```
+
+## YAML Schema Reference
+
+### Top-Level Structure
+
+```yaml
+name: string              # Scenario name (required)
+description: string       # Optional description
+
+viewport:
+  width: 1280             # Browser width (100-3840, default: 1280)
+  height: 800             # Browser height (100-3840, default: 800)
+
+effects:                  # All optional, sensible defaults
+  zoom: ...
+  cursor: ...
+  background: ...
+  deviceFrame: ...
+  keystroke: ...
+  watermark: ...
+  speedRamp: ...
+
+output:
+  format: mp4             # mp4 | gif | png-sequence
+  width: 1280             # Output width
+  height: 800             # Output height
+  fps: 30                 # 1-60
+  preset: balanced        # social | balanced | archive
+  outputDir: "./output"
+  filename: "my-recording"
+
+steps: []                 # Array of steps (min 1, first must have navigate)
+```
+
+### Step Structure
+
+```yaml
+- name: "Step name"           # Optional label
+  captureDelay: 50            # ms to wait after actions before capturing (50-100 for snappy)
+  holdDuration: 700           # ms to hold on result (500-800 for snappy)
+  transition: none            # none | fade
+  actions: []                 # Array of actions
+```
+
+### Actions (12 types)
+
+#### Basic Actions
+
+1. **navigate** — Open a URL (MUST be the first action in step 1)
+```yaml
+- action: navigate
+  url: "https://example.com"
+  waitUntil: load             # load | domcontentloaded | networkidle (default)
+```
+
+2. **click** — Click an element
+```yaml
+- action: click
+  selector: "#my-button"
+  delay: 0                    # Optional click delay (ms)
+  timeout: 15000              # Optional element wait timeout
+```
+
+3. **type** — Type text character-by-character (auto-focuses the element)
+```yaml
+- action: type
+  selector: "#email-input"
+  text: "user@example.com"
+  delay: 18                   # ms per character (15-25 recommended, default: 50)
+  timeout: 15000              # Optional
+```
+
+4. **hover** — Hover over an element
+```yaml
+- action: hover
+  selector: ".card"
+  timeout: 15000              # Optional
+```
+
+5. **scroll** — Scroll the page
+```yaml
+- action: scroll
+  y: 400                      # Vertical px (positive=down, negative=up)
+  x: 0                        # Horizontal px
+  selector: ".container"      # Optional: scroll within element
+  smooth: true                # Default: true
+  timeout: 15000              # Optional
+```
+
+6. **wait** — Pause for a fixed duration
+```yaml
+- action: wait
+  duration: 1000              # ms
+```
+
+7. **screenshot** — Capture marker (for png-sequence)
+```yaml
+- action: screenshot
+  name: "result"              # Optional label
+  fullPage: false             # Default: false
+```
+
+#### Async Wait Actions (for dynamic/API content)
+
+8. **waitForSelector** — Wait for element state
+```yaml
+- action: waitForSelector
+  selector: ".result-panel"
+  state: visible              # visible (default) | attached | hidden
+  timeout: 15000
+```
+
+9. **waitForNavigation** — Wait for page load
+```yaml
+- action: waitForNavigation
+  waitUntil: networkidle      # load | domcontentloaded | networkidle
+  timeout: 15000
+```
+
+10. **waitForURL** — Wait for URL match
+```yaml
+- action: waitForURL
+  url: "https://example.com/dashboard"
+  timeout: 15000
+```
+
+11. **waitForFunction** — Wait for JS expression to be truthy
+```yaml
+- action: waitForFunction
+  expression: "document.querySelector('.done') !== null"
+  polling: raf                # raf (default) | number in ms (e.g. 500)
+  timeout: 30000
+```
+
+12. **waitForResponse** — Wait for network response (URL substring match)
+```yaml
+- action: waitForResponse
+  url: "/api/chat/completions"
+  status: 200                 # Optional HTTP status filter
+  timeout: 30000
+```
+
+### Effects Configuration
+
+#### Zoom — Adaptive zoom follows cursor on clicks
+```yaml
+zoom:
+  enabled: true
+  intensity: moderate         # subtle(1.15x) | light(1.25x) | moderate(1.35x) | strong(1.5x) | dramatic(1.8x)
+  # scale: 1.35              # Or use numeric value (overridden by intensity)
+  duration: 500               # Zoom animation ms
+  easing: ease-in-out         # ease-in-out | ease-in | ease-out | linear
+  autoZoom:
+    followCursor: true
+    transitionDuration: 300
+    padding: 200
+```
+
+#### Cursor — Custom cursor with click effect, trail, highlight
+```yaml
+cursor:
+  enabled: true
+  size: 20
+  color: "#000000"
+  speed: fast                 # fast (~72ms) | normal (~144ms) | slow (~288ms)
+  smoothing: true
+  clickEffect: true
+  clickColor: "rgba(59, 130, 246, 0.3)"
+  clickRadius: 30
+  trail: true
+  trailLength: 8
+  trailColor: "rgba(59, 130, 246, 0.2)"
+  highlight: true
+  highlightRadius: 40
+  highlightColor: "rgba(255, 215, 0, 0.18)"
+```
+
+#### Background — Gradient/solid padding with corners and shadow
+```yaml
+background:
+  type: gradient              # gradient | solid | image
+  value: "linear-gradient(135deg, #667eea 0%, #764ba2 100%)"
+  padding: 48
+  borderRadius: 14
+  shadow: true
+```
+
+#### Device Frame — Wraps recording in a device mockup
+```yaml
+deviceFrame:
+  enabled: true
+  type: browser               # browser | macbook | iphone | ipad | android | none
+  darkMode: true
+```
+
+| Type | Description |
+|------|-------------|
+| browser | macOS browser chrome with traffic lights |
+| macbook | MacBook Pro frame |
+| iphone | iPhone 15 Pro with Dynamic Island |
+| ipad | iPad Pro with camera dot |
+| android | Android with punch-hole camera |
+
+#### Keystroke HUD — Shows typed keys on screen
+```yaml
+keystroke:
+  enabled: true
+  showTyping: false           # true = show regular typing; false = shortcuts only (industry default)
+  position: bottom-center     # bottom-center | bottom-left | bottom-right
+  fontSize: 16
+  backgroundColor: "rgba(0, 0, 0, 0.75)"
+  textColor: "#ffffff"
+  padding: 8
+  fadeAfter: 1500
+```
+
+#### Watermark — Text overlay at corner
+```yaml
+watermark:
+  enabled: true
+  text: "My App"
+  position: bottom-right      # top-left | top-right | bottom-left | bottom-right
+  opacity: 0.5
+  fontSize: 14
+  color: "#ffffff"
+```
+
+#### Speed Ramp — Auto-adjusts speed near actions
+```yaml
+speedRamp:
+  enabled: true
+  idleSpeed: 3.0              # Skip factor for idle frames (0.5-8)
+  actionSpeed: 0.8            # Slow factor near clicks (0.25-2)
+  transitionFrames: 15
+```
+
+### Output Presets
+
+| Preset | Use case | Approx size (30s) |
+|--------|----------|--------------------|
+| social | Twitter, LinkedIn, Loom | ~2-4 MB |
+| balanced | General purpose, portfolio | ~4-6 MB |
+| archive | High-fidelity storage | larger |
+
+## Critical Rules
+
+1. **First step MUST contain a `navigate` action** — the browser needs a page to start
+2. **Selectors**: use CSS selectors (`#id`, `.class`, `[data-testid="..."]`). No control chars, semicolons, backticks, or backslashes
+3. **Type needs focus**: the `type` action auto-focuses, but the element must exist and be visible
+4. **Scroll before interact**: if an element is below the fold, `scroll` to it first
+5. **Prefer async waits over fixed `wait`**: use `waitForSelector`, `waitForFunction`, `waitForResponse` instead of guessing durations
+6. **Viewport = output**: if viewport and output dimensions differ, output will be scaled (a warning is shown)
+7. **Mobile scenarios**: use `viewport: {width: 390, height: 844}` with `deviceFrame.type: iphone` and `output: {width: 540, height: 1080}`
+
+## Timing Presets
+
+### Snappy demo (~30s)
+- `captureDelay: 50-100`
+- `holdDuration: 500-800`
+- `type.delay: 15-25`
+
+### Cinematic demo (~60s)
+- `captureDelay: 200-400`
+- `holdDuration: 1500-2500`
+- `type.delay: 40-60`
+
+## CLI Commands
+
+```bash
+# Record from YAML scenario
+npx clipwise record <scenario.yaml> -f mp4 -o ./output
+
+# Instant demo with built-in dashboard
+npx clipwise demo
+npx clipwise demo --device iphone
+npx clipwise demo --url https://my-app.com
+
+# Create template YAML
+npx clipwise init
+
+# Validate scenario without recording
+npx clipwise validate <scenario.yaml>
+```
+
+## Workflow
+
+1. Ask the user for: target URL, what actions to demo, and preferred style (snappy/cinematic)
+2. Generate a complete `clipwise.yaml` scenario
+3. Run `npx clipwise validate clipwise.yaml` to check for errors
+4. If valid, run `npx clipwise record clipwise.yaml -f mp4 -o ./output`
+5. If the user has specific selectors, use them. Otherwise suggest inspecting the page first
+
+## Selector Discovery
+
+If the user doesn't know selectors, help them find them:
+```bash
+# Open the target URL in a browser and inspect elements
+npx playwright open <url>
+```
+
+Or read the page HTML to find appropriate selectors:
+```bash
+curl -s <url> | head -200
+```
+
+## Example: Minimal Scenario
+
+```yaml
+name: "My App Demo"
+viewport:
+  width: 1280
+  height: 800
+
+effects:
+  deviceFrame:
+    enabled: true
+    type: browser
+  cursor:
+    enabled: true
+    clickEffect: true
+    highlight: true
+  background:
+    padding: 48
+    borderRadius: 14
+    shadow: true
+
+output:
+  format: mp4
+  fps: 30
+  preset: balanced
+
+steps:
+  - name: "Open app"
+    captureDelay: 100
+    holdDuration: 1000
+    actions:
+      - action: navigate
+        url: "http://localhost:3000"
+        waitUntil: load
+
+  - name: "Click CTA"
+    captureDelay: 50
+    holdDuration: 800
+    actions:
+      - action: click
+        selector: "#cta-button"
+```