clipwise 0.1.1 → 0.2.0

package/README.ko.md

@@ -114,15 +114,57 @@ steps:
 
 ### 액션
 
-| 액션 | 파라미터 | 설명 |
-|------|---------|------|
-| `navigate` | `url`, `waitUntil?` | URL로 이동 |
-| `click` | `selector`, `delay?` | 요소 클릭 |
-| `type` | `selector`, `text`, `delay?` | 텍스트 입력 (한 글자씩) |
-| `hover` | `selector` | 요소에 마우스 올리기 |
-| `scroll` | `y?`, `x?`, `selector?`, `smooth?` | 스크롤 |
-| `wait` | `duration` | 대기 (ms) |
-| `screenshot` | `name?`, `fullPage?` | 캡처 마커 |
+#### 기본 액션
+
+| 액션 | 파라미터 | 기본값 | 설명 |
+|------|---------|--------|------|
+| `navigate` | `url`, `waitUntil?` | `waitUntil: "networkidle"` | URL로 이동 |
+| `click` | `selector`, `delay?`, `timeout?` | | 요소 클릭 |
+| `type` | `selector`, `text`, `delay?`, `timeout?` | `delay: 50` | 텍스트 입력 (한 글자씩) |
+| `hover` | `selector`, `timeout?` | | 요소에 마우스 올리기 |
+| `scroll` | `y?`, `x?`, `selector?`, `smooth?`, `timeout?` | `y: 0`, `x: 0`, `smooth: true` | 스크롤 |
+| `wait` | `duration` | | 대기 (ms) |
+| `screenshot` | `name?`, `fullPage?` | `fullPage: false` | 캡처 마커 |
+
+#### 비동기 대기 액션
+
+| 액션 | 파라미터 | 기본값 | 설명 |
+|------|---------|--------|------|
+| `waitForSelector` | `selector`, `state?`, `timeout?` | `state: "visible"`, `timeout: 15000` | 요소 상태 대기 |
+| `waitForNavigation` | `waitUntil?`, `timeout?` | `waitUntil: "networkidle"`, `timeout: 15000` | 페이지 로드 대기 |
+| `waitForURL` | `url`, `timeout?` | `timeout: 15000` | URL 매칭 대기 |
+| `waitForFunction` | `expression`, `polling?`, `timeout?` | `polling: "raf"`, `timeout: 30000` | JS 표현식이 truthy가 될 때까지 대기 |
+| `waitForResponse` | `url`, `status?`, `timeout?` | `timeout: 30000` | 네트워크 응답 대기 (URL 부분 문자열 매칭) |
+
+**`waitUntil`** 옵션: `"load"`, `"domcontentloaded"`, `"networkidle"` (기본)
+**`state`** 옵션: `"visible"` (기본), `"attached"`, `"hidden"`
+**`polling`** 옵션: `"raf"` (requestAnimationFrame, 기본) 또는 밀리초 숫자 (예: `500`)
+
+#### 비동기 대기 예시
+
+```yaml
+# 요소가 나타날 때까지 대기
+- action: waitForSelector
+  selector: ".result-panel"
+  state: visible
+  timeout: 20000
+
+# AI 스트리밍 응답 완료 대기
+- action: waitForFunction
+  expression: "document.querySelector('.ai-response')?.dataset.done === 'true'"
+  timeout: 60000
+
+# API 응답 완료 대기
+- action: waitForResponse
+  url: "/api/chat/completions"
+  status: 200
+  timeout: 60000
+
+# 동적 콘텐츠 길이 대기
+- action: waitForFunction
+  expression: "document.querySelector('.output')?.textContent?.length > 100"
+  polling: 500
+```
 
 ### 타이밍 팁
 
@@ -234,13 +276,14 @@ speedRamp:
 
 [PROMPTS.md](./PROMPTS.md)에 바로 사용할 수 있는 AI 프롬프트 템플릿이 있습니다. ChatGPT나 Claude에 복붙하고 내 사이트 URL만 넣으면 YAML 시나리오를 생성해줍니다.
 
-## 데모 사이트 호스팅 (GitHub Pages)
+## GitHub Pages
 
-`docs/index.html`에 데모 대시보드가 포함되어 있습니다:
+`docs/` 폴더에 문서 사이트와 라이브 데모 대시보드가 포함되어 있습니다:
 
 1. GitHub에 push: `git push origin main`
 2. **Settings > Pages** > source: `main`, folder: `/docs`
-3. `https://username.github.io/clipwise/`에서 라이브
+3. 문서: `https://username.github.io/clipwise/`
+4. 데모: `https://username.github.io/clipwise/demo/`
 
 ## 보안
 

package/README.md

@@ -114,17 +114,57 @@ steps:
 
 ### Actions
 
-| Action | Parameters | Description |
-|--------|-----------|-------------|
-| `navigate` | `url`, `waitUntil?` | Navigate to URL |
-| `click` | `selector`, `delay?` | Click an element |
-| `type` | `selector`, `text`, `delay?` | Type text (char-by-char) |
-| `hover` | `selector` | Hover over element |
-| `scroll` | `y?`, `x?`, `selector?`, `smooth?` | Scroll by offset |
-| `wait` | `duration` | Wait (ms) |
-| `screenshot` | `name?`, `fullPage?` | Capture marker |
+#### Basic Actions
+
+| Action | Parameters | Default | Description |
+|--------|-----------|---------|-------------|
+| `navigate` | `url`, `waitUntil?` | `waitUntil: "networkidle"` | Navigate to URL |
+| `click` | `selector`, `delay?`, `timeout?` | | Click an element |
+| `type` | `selector`, `text`, `delay?`, `timeout?` | `delay: 50` | Type text (char-by-char) |
+| `hover` | `selector`, `timeout?` | | Hover over element |
+| `scroll` | `y?`, `x?`, `selector?`, `smooth?`, `timeout?` | `y: 0`, `x: 0`, `smooth: true` | Scroll by offset |
+| `wait` | `duration` | | Wait (ms) |
+| `screenshot` | `name?`, `fullPage?` | `fullPage: false` | Capture marker |
+
+#### Async Wait Actions
+
+| Action | Parameters | Default | Description |
+|--------|-----------|---------|-------------|
+| `waitForSelector` | `selector`, `state?`, `timeout?` | `state: "visible"`, `timeout: 15000` | Wait for element state |
+| `waitForNavigation` | `waitUntil?`, `timeout?` | `waitUntil: "networkidle"`, `timeout: 15000` | Wait for page load |
+| `waitForURL` | `url`, `timeout?` | `timeout: 15000` | Wait for URL match |
+| `waitForFunction` | `expression`, `polling?`, `timeout?` | `polling: "raf"`, `timeout: 30000` | Wait for JS expression to be truthy |
+| `waitForResponse` | `url`, `status?`, `timeout?` | `timeout: 30000` | Wait for network response (URL substring match) |
 
 **`waitUntil`** options: `"load"`, `"domcontentloaded"`, `"networkidle"` (default)
+**`state`** options: `"visible"` (default), `"attached"`, `"hidden"`
+**`polling`** options: `"raf"` (requestAnimationFrame, default) or milliseconds (e.g. `500`)
+
+#### Async Wait Examples
+
+```yaml
+# Wait for element to appear
+- action: waitForSelector
+  selector: ".result-panel"
+  state: visible
+  timeout: 20000
+
+# Wait for AI streaming response to complete
+- action: waitForFunction
+  expression: "document.querySelector('.ai-response')?.dataset.done === 'true'"
+  timeout: 60000
+
+# Wait for API response
+- action: waitForResponse
+  url: "/api/chat/completions"
+  status: 200
+  timeout: 60000
+
+# Wait for dynamic content length
+- action: waitForFunction
+  expression: "document.querySelector('.output')?.textContent?.length > 100"
+  polling: 500
+```
 
 ### Timing Tips
 
@@ -335,19 +375,20 @@ 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.
 
-## Hosting the Demo Site (GitHub Pages)
+## GitHub Pages
 
-Clipwise includes a demo dashboard in `docs/index.html`. To host it:
+Clipwise includes a documentation site and a live demo dashboard in the `docs/` folder. To host it:
 
 1. Push to GitHub: `git push origin main`
 2. Go to **Settings > Pages**
 3. Set source to **Deploy from a branch**, select `main`, folder `/docs`
-4. Demo goes live at `https://kwakseongjae.github.io/clipwise/`
+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/
+npx clipwise demo --url https://kwakseongjae.github.io/clipwise/demo/
 ```
 
 ## Security

package/dist/cli/index.js

@@ -11,13 +11,13 @@ var __export = (target, all) => {
 
 // src/script/types.ts
 import { z } from "zod";
-var SafeSelectorSchema, NavigateActionSchema, ClickActionSchema, TypeActionSchema, ScrollActionSchema, WaitActionSchema, HoverActionSchema, ScreenshotActionSchema, StepActionSchema, AutoZoomConfigSchema, ZoomEffectSchema, CursorEffectSchema, BackgroundSchema, DeviceFrameSchema, SpeedRampConfigSchema, KeystrokeConfigSchema, WatermarkConfigSchema, EffectsConfigSchema, OutputConfigSchema, StepSchema, ScenarioSchema;
+var SafeSelectorSchema, NavigateActionSchema, ClickActionSchema, TypeActionSchema, ScrollActionSchema, WaitActionSchema, HoverActionSchema, ScreenshotActionSchema, WaitForSelectorActionSchema, WaitForNavigationActionSchema, WaitForURLActionSchema, WaitForFunctionActionSchema, WaitForResponseActionSchema, StepActionSchema, AutoZoomConfigSchema, ZoomEffectSchema, CursorEffectSchema, BackgroundSchema, DeviceFrameSchema, SpeedRampConfigSchema, KeystrokeConfigSchema, WatermarkConfigSchema, EffectsConfigSchema, OutputConfigSchema, StepSchema, ScenarioSchema;
 var init_types = __esm({
   "src/script/types.ts"() {
     "use strict";
-    SafeSelectorSchema = z.string().regex(
-      /^[a-zA-Z0-9\-_#.\[\]="':\s~^$|*,>+()@]+$/,
-      "Selector contains invalid characters"
+    SafeSelectorSchema = z.string().min(1, "Selector must not be empty").regex(
+      /^[^\x00-\x1f\x7f;`\\{}]+$/,
+      "Selector contains invalid characters (control chars, semicolons, backticks, or backslashes are not allowed)"
     );
     NavigateActionSchema = z.object({
       action: z.literal("navigate"),
@@ -27,20 +27,23 @@ var init_types = __esm({
     ClickActionSchema = z.object({
       action: z.literal("click"),
       selector: SafeSelectorSchema,
-      delay: z.number().optional()
+      delay: z.number().optional(),
+      timeout: z.number().min(0).optional()
     });
     TypeActionSchema = z.object({
       action: z.literal("type"),
       selector: SafeSelectorSchema,
       text: z.string(),
-      delay: z.number().default(50)
+      delay: z.number().default(50),
+      timeout: z.number().min(0).optional()
     });
     ScrollActionSchema = z.object({
       action: z.literal("scroll"),
       selector: SafeSelectorSchema.optional(),
       y: z.number().default(0),
       x: z.number().default(0),
-      smooth: z.boolean().default(true)
+      smooth: z.boolean().default(true),
+      timeout: z.number().min(0).optional()
     });
     WaitActionSchema = z.object({
       action: z.literal("wait"),
@@ -48,13 +51,42 @@ var init_types = __esm({
     });
     HoverActionSchema = z.object({
       action: z.literal("hover"),
-      selector: SafeSelectorSchema
+      selector: SafeSelectorSchema,
+      timeout: z.number().min(0).optional()
     });
     ScreenshotActionSchema = z.object({
       action: z.literal("screenshot"),
       name: z.string().optional(),
       fullPage: z.boolean().default(false)
     });
+    WaitForSelectorActionSchema = z.object({
+      action: z.literal("waitForSelector"),
+      selector: SafeSelectorSchema,
+      state: z.enum(["visible", "attached", "hidden"]).default("visible"),
+      timeout: z.number().min(0).default(15e3)
+    });
+    WaitForNavigationActionSchema = z.object({
+      action: z.literal("waitForNavigation"),
+      waitUntil: z.enum(["load", "domcontentloaded", "networkidle"]).default("networkidle"),
+      timeout: z.number().min(0).default(15e3)
+    });
+    WaitForURLActionSchema = z.object({
+      action: z.literal("waitForURL"),
+      url: z.string().min(1),
+      timeout: z.number().min(0).default(15e3)
+    });
+    WaitForFunctionActionSchema = z.object({
+      action: z.literal("waitForFunction"),
+      expression: z.string().min(1),
+      polling: z.union([z.literal("raf"), z.number().min(0)]).default("raf"),
+      timeout: z.number().min(0).default(3e4)
+    });
+    WaitForResponseActionSchema = z.object({
+      action: z.literal("waitForResponse"),
+      url: z.string().min(1),
+      status: z.number().min(100).max(599).optional(),
+      timeout: z.number().min(0).default(3e4)
+    });
     StepActionSchema = z.discriminatedUnion("action", [
       NavigateActionSchema,
       ClickActionSchema,
@@ -62,7 +94,12 @@ var init_types = __esm({
       ScrollActionSchema,
       WaitActionSchema,
       HoverActionSchema,
-      ScreenshotActionSchema
+      ScreenshotActionSchema,
+      WaitForSelectorActionSchema,
+      WaitForNavigationActionSchema,
+      WaitForURLActionSchema,
+      WaitForFunctionActionSchema,
+      WaitForResponseActionSchema
     ]);
     AutoZoomConfigSchema = z.object({
       followCursor: z.boolean().default(true),
@@ -328,12 +365,13 @@ function interpolatePath(from, to, steps) {
 }
 
 // src/core/screenshot.ts
-async function getElementCenter(page, selector) {
-  if (!/^[\w\-#.\[\]="':\s,>+~*()@^$|]+$/.test(selector)) {
+var DEFAULT_ELEMENT_TIMEOUT = 5e3;
+async function getElementCenter(page, selector, timeout) {
+  if (/[\x00-\x1f\x7f;`\\{}]/.test(selector) || selector.length === 0) {
     throw new Error(`Invalid selector: ${selector}`);
   }
   const element = page.locator(selector).first();
-  await element.waitFor({ state: "visible", timeout: 5e3 });
+  await element.waitFor({ state: "visible", timeout: timeout ?? DEFAULT_ELEMENT_TIMEOUT });
   const box = await element.boundingBox();
   if (!box) {
     throw new Error(
@@ -374,6 +412,7 @@ var ClipwiseRecorder = class {
   targetFps = 30;
   cursorSpeed = "fast";
   firstContentTimestamp = 0;
+  pendingResponsePromises = /* @__PURE__ */ new Map();
   /**
    * Launch the browser and create a page with the scenario viewport.
    */
@@ -458,8 +497,9 @@ var ClipwiseRecorder = class {
       for (let si = 0; si < scenario.steps.length; si++) {
         const step = scenario.steps[si];
         this.currentStepIndex = si;
-        for (const action of step.actions) {
-          await this.executeAction(action);
+        this.preRegisterResponseListeners(step.actions);
+        for (let ai = 0; ai < step.actions.length; ai++) {
+          await this.executeAction(step.actions[ai], ai);
         }
         if (step.captureDelay > 0) {
           await this.waitWithRepaints(step.captureDelay);
@@ -525,11 +565,33 @@ var ClipwiseRecorder = class {
       }
     }
   }
+  /**
+   * Pre-register waitForResponse listeners at the start of each step.
+   * This ensures the listener is active before any preceding action
+   * (e.g. click) triggers the request, preventing race conditions
+   * where the response arrives before the listener is set up.
+   */
+  preRegisterResponseListeners(actions) {
+    this.pendingResponsePromises.clear();
+    if (!this.page) return;
+    for (let i = 0; i < actions.length; i++) {
+      const action = actions[i];
+      if (action.action === "waitForResponse") {
+        this.pendingResponsePromises.set(
+          i,
+          this.page.waitForResponse(
+            (response) => response.url().includes(action.url) && (action.status === void 0 || response.status() === action.status),
+            { timeout: action.timeout }
+          )
+        );
+      }
+    }
+  }
   /**
    * Execute a single action. CDP screencast captures frames continuously
    * in the background while actions are performed.
    */
-  async executeAction(action) {
+  async executeAction(action, actionIndex = 0) {
     if (!this.page) {
       throw new Error("Page not initialized. Call init() first.");
     }
@@ -547,7 +609,7 @@ var ClipwiseRecorder = class {
         break;
       }
       case "click": {
-        const target = await getElementCenter(this.page, action.selector);
+        const target = await getElementCenter(this.page, action.selector, action.timeout);
         await this.moveCursorSmooth(target);
         this.clickTimeline.push({
           position: { ...target },
@@ -561,7 +623,8 @@ var ClipwiseRecorder = class {
       case "type": {
         const inputTarget = await getElementCenter(
           this.page,
-          action.selector
+          action.selector,
+          action.timeout
         );
         await this.moveCursorSmooth(inputTarget);
         this.clickTimeline.push({
@@ -579,7 +642,7 @@ var ClipwiseRecorder = class {
         break;
       }
       case "scroll": {
-        const scrollTarget = action.selector ? await getElementCenter(this.page, action.selector) : null;
+        const scrollTarget = action.selector ? await getElementCenter(this.page, action.selector, action.timeout) : null;
         await this.page.evaluate(
           ({ x, y, smooth, selector }) => {
             const target = selector ? document.querySelector(selector) : window;
@@ -623,7 +686,8 @@ var ClipwiseRecorder = class {
       case "hover": {
         const hoverTarget = await getElementCenter(
           this.page,
-          action.selector
+          action.selector,
+          action.timeout
         );
         await this.moveCursorSmooth(hoverTarget);
         await this.page.hover(action.selector);
@@ -633,6 +697,33 @@ var ClipwiseRecorder = class {
         await this.waitWithRepaints(100);
         break;
       }
+      case "waitForSelector": {
+        const locator = this.page.locator(action.selector).first();
+        await locator.waitFor({ state: action.state, timeout: action.timeout });
+        break;
+      }
+      case "waitForNavigation": {
+        await this.page.waitForLoadState(action.waitUntil, { timeout: action.timeout });
+        break;
+      }
+      case "waitForURL": {
+        await this.page.waitForURL(action.url, { timeout: action.timeout });
+        break;
+      }
+      case "waitForFunction": {
+        await this.page.waitForFunction(action.expression, void 0, {
+          polling: action.polling,
+          timeout: action.timeout
+        });
+        break;
+      }
+      case "waitForResponse": {
+        const pending = this.pendingResponsePromises.get(actionIndex);
+        if (pending) {
+          await pending;
+        }
+        break;
+      }
     }
     await this.waitWithRepaints(ACTION_GAP_MS);
   }