clipwise 0.6.0 → 0.6.1

package/README.ko.md

@@ -80,6 +80,37 @@ const frames = await renderer.composeAll(session.frames);
 const mp4 = await encodeMp4(frames, scenario.output);
 ```
 
+## 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`을 다시 실행하면 최신 스킬로 업데이트됩니다.
+
 ## YAML 시나리오 형식
 
 시나리오는 4개 섹션으로 구성됩니다: 메타데이터, 이펙트, 출력, 스텝.
@@ -403,37 +434,6 @@ 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

@@ -80,6 +80,37 @@ const frames = await renderer.composeAll(session.frames);
 const mp4 = await encodeMp4(frames, scenario.output);
 ```
 
+## 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.
+
 ## YAML Scenario Format
 
 A scenario has 4 sections: metadata, effects, output, and steps.
@@ -483,37 +514,6 @@ 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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "clipwise",
-  "version": "0.6.0",
+  "version": "0.6.1",
   "description": "Scriptable cinematic screen recorder for product demos — YAML in, polished MP4 out",
   "type": "module",
   "main": "dist/index.js",

package/skills/clipwise.md

@@ -64,7 +64,10 @@ steps: []                 # Array of steps (min 1, first must have navigate)
 - 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
+  transition: none            # none | fade | slide-left | slide-up | blur
+  effects:                    # Per-step effects override (optional)
+    zoom:
+      enabled: false          # Disable zoom for this step only
   actions: []                 # Array of actions
 ```
 
@@ -168,16 +171,15 @@ steps: []                 # Array of steps (min 1, first must have navigate)
 
 ### Effects Configuration
 
-#### Zoom — Adaptive zoom follows cursor on clicks
+#### Zoom — Adaptive zoom follows cursor on clicks (smart camera: auto-suppressed during scroll)
 ```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
+  intensity: light            # subtle(1.15x) | light(1.25x) | moderate(1.35x) | strong(1.5x) | dramatic(1.8x)
+  # scale: 1.25              # Or use numeric value (overridden by intensity)
+  duration: 800               # Zoom animation ms
   autoZoom:
-    followCursor: true
+    followCursor: true        # Viewport pans to follow cursor position
     transitionDuration: 300
     padding: 200
 ```
@@ -188,7 +190,7 @@ cursor:
   enabled: true
   size: 20
   color: "#000000"
-  speed: fast                 # fast (~72ms) | normal (~144ms) | slow (~288ms)
+  speed: normal               # fast (~72ms) | normal (~144ms) | slow (~288ms)
   smoothing: true
   clickEffect: true
   clickColor: "rgba(59, 130, 246, 0.3)"
@@ -215,17 +217,16 @@ background:
 ```yaml
 deviceFrame:
   enabled: true
-  type: browser               # browser | macbook | iphone | ipad | android | none
+  type: browser               # browser | 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 |
+| iphone | iPhone 15 Pro with Dynamic Island + home bar |
+| ipad | iPad Pro with front camera dot |
+| android | Android generic with punch-hole camera |
 
 #### Keystroke HUD — Shows typed keys on screen
 ```yaml
@@ -260,6 +261,39 @@ speedRamp:
   transitionFrames: 15
 ```
 
+#### Audio Narration — Attach audio to MP4 output
+```yaml
+audio:
+  file: "./narration.mp3"     # MP3, WAV, etc.
+  volume: 1.0                 # 0.0 - 2.0 (default: 1.0)
+  fadeIn: 0                   # Fade-in duration in seconds
+  fadeOut: 0                  # Fade-out duration in seconds
+```
+
+### Per-Step Effects Override
+
+Override global effects on a per-step basis. Unset properties inherit from global config.
+
+```yaml
+effects:
+  zoom:
+    enabled: true
+    intensity: light
+
+steps:
+  - name: "Overview"
+    effects:
+      zoom:
+        enabled: false        # No zoom for this step
+    actions: [...]
+
+  - name: "Detail view"
+    effects:
+      zoom:
+        intensity: strong     # Extra zoom for this step only
+    actions: [...]
+```
+
 ### Output Presets
 
 | Preset | Use case | Approx size (30s) |
@@ -277,6 +311,10 @@ speedRamp:
 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}`
+8. **Per-step effects**: any effect property can be overridden per step — unset properties inherit from global config
+9. **Smart camera**: zoom is automatically suppressed during scroll actions; `followCursor` pans to cursor position
+10. **Transitions**: use `fade` or `blur` for cinematic cuts between major sections; `slide-left`/`slide-up` for sequential flows
+11. **Audio**: audio file must exist at the specified path; only works with MP4 output format
 
 ## Timing Presets