clipwise 0.5.2 → 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개 섹션으로 구성됩니다: 메타데이터, 이펙트, 출력, 스텝.
@@ -109,7 +140,10 @@ steps:
         url: "https://example.com"
     captureDelay: 200       # 액션 후 대기(ms)
     holdDuration: 800       # 결과 화면 유지(ms)
-    transition: none        # none | fade
+    transition: none        # none | fade | slide-left | slide-up | blur
+    effects:                # 스텝별 이펙트 오버라이드 (선택)
+      zoom:
+        enabled: false      # 이 스텝에서만 줌 비활성화
 ```
 
 ### 액션
@@ -189,20 +223,26 @@ steps:
 ```yaml
 zoom:
   enabled: true
-  intensity: moderate  # subtle | light | moderate | strong | dramatic
+  intensity: light     # subtle | light | moderate | strong | dramatic
                        # 1.15x  | 1.25x | 1.35x    | 1.5x   | 1.8x
-  # scale: 1.35       # 숫자로 직접 지정할 때 사용 (intensity 미설정 시)
-  duration: 500        # 애니메이션 ms
+  # scale: 1.25       # 숫자로 직접 지정할 때 사용 (intensity 미설정 시)
+  duration: 800        # 애니메이션 ms
+  autoZoom:
+    followCursor: true   # 커서 위치를 따라 뷰포트 패닝
+    transitionDuration: 300
+    padding: 200
 ```
 
 | 강도 | 스케일 | 권장 사용처 |
 |------|--------|------------|
 | `subtle` | 1.15× | 정보 밀도 높은 UI, 큰 화면 |
-| `light` | 1.25× | Loom 스타일 부드러운 줌 (권장) |
-| `moderate` | 1.35× | 균형잡힌 기본값 (Camtasia 수준) |
+| `light` | 1.25× | Loom 스타일 부드러운 줌 **(기본값)** |
+| `moderate` | 1.35× | 균형잡힌 수준 (Camtasia 범위) |
 | `strong` | 1.5× | 명확한 포커스 |
 | `dramatic` | 1.8× | 최대 강조, 단순 UI 전용 |
 
+**스마트 카메라**: 스크롤 중에는 줌이 자동 억제되어 어지러운 움직임을 방지합니다. `followCursor` 활성화 시 초점이 클릭 위치뿐 아니라 커서 위치를 부드럽게 따라갑니다.
+
 ### 커서
 
 커스텀 커서 + 클릭 리플 + 트레일 + 하이라이트 + 속도 조절.
@@ -211,7 +251,7 @@ zoom:
 cursor:
   enabled: true
   size: 20
-  speed: "fast"        # fast (~72ms) | normal (~144ms) | slow (~288ms)
+  speed: "normal"      # fast (~72ms) | normal (~144ms) | slow (~288ms)
   clickEffect: true
   trail: true
   highlight: true
@@ -282,24 +322,81 @@ watermark:
 ```yaml
 speedRamp:
   enabled: true
-  idleSpeed: 3.0
+  idleSpeed: 2.0        # 유휴 프레임 스킵 배수 (기본: 2.0)
   actionSpeed: 0.8
 ```
 
+### 트랜지션
+
+스텝 간 전환 효과를 지정합니다.
+
+```yaml
+steps:
+  - name: "스텝 1"
+    transition: fade        # none | fade | slide-left | slide-up | blur
+    actions: [...]
+```
+
+| 트랜지션 | 설명 |
+|----------|------|
+| `none` | 하드 컷 (기본값) |
+| `fade` | 크로스 디졸브 |
+| `slide-left` | 나가는 프레임 왼쪽 슬라이드, 들어오는 프레임 오른쪽에서 진입 |
+| `slide-up` | 나가는 프레임 위로 슬라이드, 들어오는 프레임 아래에서 진입 |
+| `blur` | 나가는 프레임 블러 처리 + 크로스페이드 |
+
+### 스텝별 이펙트 오버라이드
+
+글로벌 이펙트를 스텝 단위로 오버라이드할 수 있습니다. 설정하지 않은 속성은 글로벌 설정을 상속합니다.
+
+```yaml
+effects:
+  zoom:
+    enabled: true
+    intensity: light
+
+steps:
+  - name: "개요"
+    effects:
+      zoom:
+        enabled: false      # 이 스텝에서만 줌 비활성화
+    actions: [...]
+
+  - name: "상세 보기"
+    effects:
+      zoom:
+        intensity: strong   # 이 스텝에서만 강한 줌
+    actions: [...]
+```
+
+### 오디오 내레이션
+
+출력 MP4에 오디오 파일(MP3, WAV 등)을 첨부합니다.
+
+```yaml
+audio:
+  file: "./narration.mp3"
+  volume: 1.0              # 0.0 - 2.0 (기본: 1.0)
+  fadeIn: 0                 # 페이드인 시간(초)
+  fadeOut: 0                # 페이드아웃 시간(초)
+```
+
 ## 성능
 
 **Apple M1 Max (10코어)** 기준 — Pulse Dashboard 데모, 44초 @ 30fps, 1280×800:
 
-| 단계 | v0.3.0 | v0.4.0 | v0.5.0 |
-|------|--------|--------|--------|
-| 녹화 | 30.8 s | 31.1 s | 31.1 s |
-| 합성 + 인코딩 | 97.2 s | 60.6 s | 60.6 s |
-| **전체** | **127.9 s** | **91.7 s** | **91.7 s** |
-| 캡처 프레임 수 | 1,303 | 902 | 902 |
+| 단계 | v0.3.0 | v0.4.0 | v0.5.0 | v0.6.0 |
+|------|--------|--------|--------|--------|
+| 녹화 | 30.8 s | 31.1 s | 31.1 s | 31.1 s |
+| 합성 + 인코딩 | 97.2 s | 60.6 s | 60.6 s | 60.6 s |
+| **전체** | **127.9 s** | **91.7 s** | **91.7 s** | **91.7 s** |
+| 캡처 프레임 수 | 1,303 | 902 | 902 | 902 |
 
 v0.4.0 주요 최적화: 동시 스트리밍 파이프라인, 정적 프레임 중복 제거(~33% 건너뜀), 워커별 StaticLayers 캐시, raw RGBA 버퍼 파이프라인.
 
-v0.5.0은 **녹화 품질** 개선에 집중: CSS 트랜지션 억제로 커서 부드러운 이동, 줌 강도 프리셋, 멀티세션 키스트로크 HUD.
+v0.5.0은 **녹화 품질** 개선에 집중: 부드러운 커서, 줌 강도 프리셋, 멀티세션 키스트로크 HUD.
+
+v0.6.0은 **컨벤션 정렬 & 표현력** 강화: 부드러운 기본값 (light 줌, normal 커서 속도), 스텝별 이펙트 오버라이드, 새 트랜지션 (slide, blur), 오디오 내레이션, 스마트 카메라 (스크롤 줌 억제 + 커서 추적 포컬 포인트).
 
 ## 출력 압축
 
@@ -337,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.
@@ -109,7 +140,10 @@ steps:
         url: "https://example.com"
     captureDelay: 200       # ms to wait after actions
     holdDuration: 800       # ms to hold on result
-    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
@@ -189,12 +223,12 @@ Adaptive zoom follows cursor and zooms in on click targets.
 ```yaml
 zoom:
   enabled: true
-  intensity: moderate  # subtle | light | moderate | strong | dramatic
+  intensity: light     # subtle | light | moderate | strong | dramatic
                        # 1.15x  | 1.25x | 1.35x    | 1.5x   | 1.8x
-  # scale: 1.35       # Override with a numeric value instead of intensity
-  duration: 500        # Zoom animation ms
+  # scale: 1.25       # Override with a numeric value instead of intensity
+  duration: 800        # Zoom animation ms
   autoZoom:
-    followCursor: true
+    followCursor: true   # Viewport pans to follow cursor position
     transitionDuration: 300
     padding: 200
 ```
@@ -202,11 +236,13 @@ zoom:
 | Intensity | Scale | Best for |
 |-----------|-------|----------|
 | `subtle` | 1.15× | Dense UIs, large viewports |
-| `light` | 1.25× | Loom-style gentle pull-in (recommended) |
-| `moderate` | 1.35× | Balanced default — Camtasia range |
+| `light` | 1.25× | Loom-style gentle pull-in **(default)** |
+| `moderate` | 1.35× | Balanced — Camtasia range |
 | `strong` | 1.5× | Clear focus, some context sacrificed |
 | `dramatic` | 1.8× | Maximum emphasis, sparse UIs only |
 
+**Smart camera**: Zoom is automatically suppressed during scroll actions to avoid disorienting motion. When `followCursor` is enabled, the focal point smoothly pans to follow cursor position (not just click targets).
+
 ### Cursor
 
 Custom cursor with click ripple, trail, glow highlight, and speed control.
@@ -215,7 +251,7 @@ Custom cursor with click ripple, trail, glow highlight, and speed control.
 cursor:
   enabled: true
   size: 20
-  speed: "fast"        # fast (~72ms) | normal (~144ms) | slow (~288ms)
+  speed: "normal"      # fast (~72ms) | normal (~144ms) | slow (~288ms)
   clickEffect: true
   clickColor: "rgba(59, 130, 246, 0.3)"
   trail: true
@@ -289,24 +325,81 @@ Automatically slows down near clicks and speeds up idle sections.
 ```yaml
 speedRamp:
   enabled: true
-  idleSpeed: 3.0        # Skip factor for idle frames
+  idleSpeed: 2.0        # Skip factor for idle frames (default: 2.0)
   actionSpeed: 0.8      # Slow factor near clicks
 ```
 
+### Transitions
+
+Control how steps transition to each other.
+
+```yaml
+steps:
+  - name: "Step 1"
+    transition: fade        # none | fade | slide-left | slide-up | blur
+    actions: [...]
+```
+
+| Transition | Description |
+|------------|-------------|
+| `none` | Hard cut (default) |
+| `fade` | Cross-dissolve between steps |
+| `slide-left` | Outgoing frame slides left, incoming slides in from right |
+| `slide-up` | Outgoing frame slides up, incoming slides in from bottom |
+| `blur` | Outgoing frame blurs out while cross-fading to incoming |
+
+### Per-Step Effects Override
+
+Override global effects on a per-step basis. Any effect property can be overridden — unset properties inherit from the 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: [...]
+```
+
+### Audio Narration
+
+Attach an audio file (MP3, WAV, etc.) to the output MP4.
+
+```yaml
+audio:
+  file: "./narration.mp3"
+  volume: 1.0              # 0.0 - 2.0 (default: 1.0)
+  fadeIn: 0                 # Fade-in duration in seconds
+  fadeOut: 0                # Fade-out duration in seconds
+```
+
 ## Performance
 
 Measured on **Apple M1 Max (10 cores)** — Pulse Dashboard demo, 44s @ 30fps, 1280×800:
 
-| Stage | v0.3.0 | v0.4.0 | v0.5.0 |
-|-------|--------|--------|--------|
-| Recording | 30.8 s | 31.1 s | 31.1 s |
-| Compose + Encode | 97.2 s | 60.6 s | 60.6 s |
-| **Total** | **127.9 s** | **91.7 s** | **91.7 s** |
-| Frames captured | 1,303 | 902 | 902 |
+| Stage | v0.3.0 | v0.4.0 | v0.5.0 | v0.6.0 |
+|-------|--------|--------|--------|--------|
+| Recording | 30.8 s | 31.1 s | 31.1 s | 31.1 s |
+| Compose + Encode | 97.2 s | 60.6 s | 60.6 s | 60.6 s |
+| **Total** | **127.9 s** | **91.7 s** | **91.7 s** | **91.7 s** |
+| Frames captured | 1,303 | 902 | 902 | 902 |
 
 Key optimisations in v0.4.0: concurrent streaming pipeline, static frame deduplication (~33% skipped), per-worker StaticLayers cache, and raw RGBA buffer pipeline.
 
-v0.5.0 focuses on **recording quality** rather than throughput: smooth cursor movement (CSS transition suppression), zoom intensity presets, and multi-session keystroke HUD.
+v0.5.0 focuses on **recording quality**: smooth cursor, zoom intensity presets, multi-session keystroke HUD.
+
+v0.6.0 focuses on **convention alignment & expressiveness**: gentler defaults (light zoom, normal cursor speed), per-step effects override, new transitions (slide, blur), audio narration, and smart camera (scroll-aware zoom suppression + cursor-following focal point).
 
 ## Output Compression
 
@@ -415,43 +508,12 @@ npx clipwise record my-scenario.yaml -f mp4 -o ./output
 - Start each interaction with enough scroll to make the target element visible
 - Use `waitUntil: "networkidle"` for pages with API calls
 - Keep `type.delay` at 15-25ms for a fast but readable typing effect
-- Use `transition: fade` between major sections for cinematic cuts
+- Use `transition: fade` or `transition: blur` between major sections for cinematic cuts
 
 ### Writing Scenarios with AI
 
 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:
@@ -462,11 +524,7 @@ Clipwise includes a documentation site and a live demo dashboard in the `docs/`
 4. Docs go live at `https://kwakseongjae.github.io/clipwise/`
 5. Demo dashboard at `https://kwakseongjae.github.io/clipwise/demo/`
 
-Then anyone can record the demo site:
-
-```bash
-npx clipwise demo --url https://kwakseongjae.github.io/clipwise/demo/
-```
+The built-in `npx clipwise demo` already points to this URL by default.
 
 ## Security