clipwise 0.7.1 → 0.9.0

package/dist/index.js

@@ -54,6 +54,115 @@ async function getElementCenter(page, selector, timeout) {
   };
 }
 
+// src/core/prepare.ts
+import { readFile } from "fs/promises";
+function buildHideCss(selectors) {
+  return `${selectors.join(",\n")} {
+  display: none !important;
+  visibility: hidden !important;
+}`;
+}
+function buildCssInjectionScript(css) {
+  return `(() => {
+  const apply = () => {
+    const style = document.createElement("style");
+    style.setAttribute("data-clipwise", "prepare");
+    style.textContent = ${JSON.stringify(css)};
+    (document.head || document.documentElement).appendChild(style);
+  };
+  if (document.readyState === "loading") {
+    document.addEventListener("DOMContentLoaded", apply);
+  } else {
+    apply();
+  }
+})();`;
+}
+function buildFreezeTimeScript(epochMs) {
+  return `(() => {
+  const frozen = ${epochMs};
+  const OrigDate = Date;
+  class FrozenDate extends OrigDate {
+    constructor(...args) {
+      if (args.length === 0) { super(frozen); } else { super(...args); }
+    }
+    static now() { return frozen; }
+  }
+  FrozenDate.parse = OrigDate.parse;
+  FrozenDate.UTC = OrigDate.UTC;
+  Object.defineProperty(globalThis, "Date", { value: FrozenDate, writable: true, configurable: true });
+})();`;
+}
+function buildSeedRandomScript(seed) {
+  return `(() => {
+  let s = (${seed}) >>> 0;
+  Math.random = () => {
+    s = (s + 0x6D2B79F5) | 0;
+    let t = Math.imul(s ^ (s >>> 15), 1 | s);
+    t = (t + Math.imul(t ^ (t >>> 7), 61 | t)) ^ t;
+    return ((t ^ (t >>> 14)) >>> 0) / 4294967296;
+  };
+})();`;
+}
+function buildStorageScript(storage) {
+  return `(() => {
+  try {
+    const seed = ${JSON.stringify(storage)};
+    for (const [k, v] of Object.entries(seed.localStorage)) localStorage.setItem(k, v);
+    for (const [k, v] of Object.entries(seed.sessionStorage)) sessionStorage.setItem(k, v);
+  } catch { /* opaque origin \u2014 storage unavailable */ }
+})();`;
+}
+async function resolveMockBody(route) {
+  if (route.fixture) {
+    return readFile(route.fixture, "utf-8");
+  }
+  if (route.body !== void 0) {
+    return typeof route.body === "string" ? route.body : JSON.stringify(route.body);
+  }
+  throw new Error(`prepare.mock "${route.url}": either "fixture" or "body" is required`);
+}
+async function applyPrepare(context, prepare) {
+  if (prepare.freezeTime) {
+    const epochMs = Date.parse(prepare.freezeTime);
+    if (Number.isNaN(epochMs)) {
+      throw new Error(`prepare.freezeTime: invalid date "${prepare.freezeTime}" (use ISO 8601, e.g. "2026-06-10T09:00:00Z")`);
+    }
+    await context.addInitScript(buildFreezeTimeScript(epochMs));
+  }
+  if (prepare.seedRandom !== void 0) {
+    await context.addInitScript(buildSeedRandomScript(prepare.seedRandom));
+  }
+  if (prepare.storage) {
+    await context.addInitScript(buildStorageScript(prepare.storage));
+  }
+  const cssChunks = [];
+  if (prepare.hide.length > 0) {
+    cssChunks.push(buildHideCss(prepare.hide));
+  }
+  if (prepare.inject?.css) {
+    const cssFiles = Array.isArray(prepare.inject.css) ? prepare.inject.css : [prepare.inject.css];
+    for (const file of cssFiles) {
+      cssChunks.push(await readFile(file, "utf-8"));
+    }
+  }
+  if (cssChunks.length > 0) {
+    await context.addInitScript(buildCssInjectionScript(cssChunks.join("\n\n")));
+  }
+  if (prepare.inject?.js) {
+    const jsFiles = Array.isArray(prepare.inject.js) ? prepare.inject.js : [prepare.inject.js];
+    for (const file of jsFiles) {
+      await context.addInitScript(await readFile(file, "utf-8"));
+    }
+  }
+  for (const mock of prepare.mock) {
+    const body = await resolveMockBody(mock);
+    await context.route(
+      (url) => url.href.includes(mock.url),
+      (route) => route.fulfill({ status: mock.status, contentType: mock.contentType, body })
+    );
+  }
+}
+
 // src/core/recorder.ts
 var CLICK_EFFECT_DURATION_MS = 500;
 var REPAINT_INTERVAL_MS = 25;
@@ -139,11 +248,23 @@ var ClipwiseRecorder = class {
     };
     this.targetFps = scenario.output.fps;
     this.cursorSpeed = scenario.effects.cursor.speed;
+    this.deviceScaleFactor = scenario.viewport.deviceScaleFactor ?? 1;
     this.loaderDetectionEnabled = scenario.effects.smartSpeed?.enabled ?? false;
     this.browser = await chromium.launch({ headless: true });
-    this.context = await this.browser.newContext({
-      viewport: this.viewport
-    });
+    const contextOptions = {
+      viewport: this.viewport,
+      deviceScaleFactor: this.deviceScaleFactor
+    };
+    if (scenario.auth?.storageState) {
+      contextOptions.storageState = scenario.auth.storageState;
+    }
+    this.context = await this.browser.newContext(contextOptions);
+    if (scenario.auth?.cookies?.length) {
+      await this.context.addCookies(scenario.auth.cookies);
+    }
+    if (scenario.prepare) {
+      await applyPrepare(this.context, scenario.prepare);
+    }
     this.page = await this.context.newPage();
     this.rawFrames = [];
     this.cursorTimeline = [];
@@ -243,7 +364,7 @@ var ClipwiseRecorder = class {
       });
       this.cdpClient = null;
     }
-    await new Promise((resolve) => setTimeout(resolve, 200));
+    await new Promise((resolve3) => setTimeout(resolve3, 200));
   }
   /**
    * Execute the full scenario with continuous capture and return a RecordingSession.
@@ -461,11 +582,36 @@ var ClipwiseRecorder = class {
       const remaining = endTime - Date.now();
       if (remaining > 0) {
         await new Promise(
-          (resolve) => setTimeout(resolve, Math.min(REPAINT_INTERVAL_MS, remaining))
+          (resolve3) => setTimeout(resolve3, Math.min(REPAINT_INTERVAL_MS, remaining))
         );
       }
     }
   }
+  /**
+   * 조건 대기 중 프레임을 연속 캡처하는 헬퍼.
+   * smartWait과 동일한 패턴: isWaitingPhase 플래그 + forceRepaint 루프를 조건 promise와 병렬 실행.
+   */
+  async waitForConditionWithCapture(conditionPromise, displaySpeed) {
+    this.isWaitingPhase = true;
+    this.currentDisplaySpeed = displaySpeed;
+    try {
+      let waitDone = false;
+      const repaintLoop = (async () => {
+        let toggle = false;
+        while (!waitDone && this.isCapturing && this.page) {
+          await this.forceRepaint(toggle);
+          toggle = !toggle;
+          await new Promise((r) => setTimeout(r, REPAINT_INTERVAL_MS));
+        }
+      })();
+      await conditionPromise;
+      waitDone = true;
+      await repaintLoop;
+    } finally {
+      this.isWaitingPhase = false;
+      this.currentDisplaySpeed = void 0;
+    }
+  }
   /**
    * Pre-register waitForResponse listeners at the start of each step.
    * This ensures the listener is active before any preceding action
@@ -546,7 +692,7 @@ var ClipwiseRecorder = class {
             timestamp: Date.now(),
             sessionId: currentSessionId
           });
-          await new Promise((resolve) => setTimeout(resolve, action.delay));
+          await new Promise((resolve3) => setTimeout(resolve3, action.delay));
           const now = Date.now();
           if (now - lastClickRefresh >= 400) {
             this.clickTimeline.push({
@@ -556,6 +702,17 @@ var ClipwiseRecorder = class {
             lastClickRefresh = now;
           }
         }
+        await this.page.evaluate((sel) => {
+          const el = document.querySelector(sel);
+          if (!el) return;
+          const proto = el instanceof HTMLTextAreaElement ? HTMLTextAreaElement.prototype : HTMLInputElement.prototype;
+          const setter = Object.getOwnPropertyDescriptor(proto, "value")?.set;
+          if (setter) {
+            setter.call(el, el.value);
+            el.dispatchEvent(new Event("input", { bubbles: true }));
+            el.dispatchEvent(new Event("change", { bubbles: true }));
+          }
+        }, action.selector);
         this.clickTimeline.push({
           position: { ...inputTarget },
           timestamp: Date.now()
@@ -581,7 +738,7 @@ var ClipwiseRecorder = class {
               },
               { dy: yStep, dx: xStep, sel: action.selector ?? null }
             );
-            await new Promise((resolve) => setTimeout(resolve, 30));
+            await new Promise((resolve3) => setTimeout(resolve3, 30));
           }
           await this.waitWithRepaints(150);
         } else {
@@ -629,83 +786,89 @@ var ClipwiseRecorder = class {
       }
       case "waitForSelector": {
         const locator = this.page.locator(action.selector).first();
-        await locator.waitFor({ state: action.state, timeout: action.timeout });
+        const selectorPromise = locator.waitFor({ state: action.state, timeout: action.timeout });
+        if (action.captureWhileWaiting) {
+          await this.waitForConditionWithCapture(selectorPromise, action.displaySpeed);
+        } else {
+          await selectorPromise;
+        }
         break;
       }
       case "waitForNavigation": {
-        await this.page.waitForLoadState(action.waitUntil, { timeout: action.timeout });
+        const navPromise = this.page.waitForLoadState(action.waitUntil, { timeout: action.timeout });
+        if (action.captureWhileWaiting) {
+          await this.waitForConditionWithCapture(navPromise, action.displaySpeed);
+        } else {
+          await navPromise;
+        }
         break;
       }
       case "waitForURL": {
-        await this.page.waitForURL(action.url, { timeout: action.timeout });
+        const urlPromise = this.page.waitForURL(action.url, { timeout: action.timeout });
+        if (action.captureWhileWaiting) {
+          await this.waitForConditionWithCapture(urlPromise, action.displaySpeed);
+        } else {
+          await urlPromise;
+        }
         break;
       }
       case "waitForFunction": {
-        await this.page.waitForFunction(action.expression, void 0, {
+        const fnPromise = this.page.waitForFunction(action.expression, void 0, {
           polling: action.polling,
           timeout: action.timeout
         });
+        if (action.captureWhileWaiting) {
+          await this.waitForConditionWithCapture(fnPromise, action.displaySpeed);
+        } else {
+          await fnPromise;
+        }
         break;
       }
       case "waitForResponse": {
         const pending = this.pendingResponsePromises.get(actionIndex);
         if (pending) {
-          await pending;
+          if (action.captureWhileWaiting) {
+            await this.waitForConditionWithCapture(pending, action.displaySpeed);
+          } else {
+            await pending;
+          }
         }
         break;
       }
       case "smartWait": {
-        this.isWaitingPhase = true;
-        this.currentDisplaySpeed = action.displaySpeed;
-        try {
-          let conditionPromise;
-          switch (action.until) {
-            case "networkIdle":
-              conditionPromise = this.page.waitForLoadState("networkidle", { timeout: action.timeout });
-              break;
-            case "selector":
-              conditionPromise = action.selector ? this.page.locator(action.selector).first().waitFor({ state: "visible", timeout: action.timeout }) : Promise.resolve();
-              break;
-            case "domStable":
-              conditionPromise = this.page.waitForFunction(
-                () => new Promise((resolve) => {
-                  let timer;
-                  const observer = new MutationObserver(() => {
-                    clearTimeout(timer);
-                    timer = setTimeout(() => {
-                      observer.disconnect();
-                      resolve(true);
-                    }, 500);
-                  });
-                  observer.observe(document.body, { childList: true, subtree: true, attributes: true });
+        let conditionPromise;
+        switch (action.until) {
+          case "networkIdle":
+            conditionPromise = this.page.waitForLoadState("networkidle", { timeout: action.timeout });
+            break;
+          case "selector":
+            conditionPromise = action.selector ? this.page.locator(action.selector).first().waitFor({ state: "visible", timeout: action.timeout }) : Promise.resolve();
+            break;
+          case "domStable":
+            conditionPromise = this.page.waitForFunction(
+              () => new Promise((resolve3) => {
+                let timer;
+                const observer = new MutationObserver(() => {
+                  clearTimeout(timer);
                   timer = setTimeout(() => {
                     observer.disconnect();
-                    resolve(true);
+                    resolve3(true);
                   }, 500);
-                }),
-                void 0,
-                { timeout: action.timeout }
-              );
-              break;
-            default:
-              conditionPromise = Promise.resolve();
-          }
-          let waitDone = false;
-          const repaintLoop = (async () => {
-            let toggle = false;
-            while (!waitDone && this.isCapturing && this.page) {
-              await this.forceRepaint(toggle);
-              toggle = !toggle;
-              await new Promise((r) => setTimeout(r, REPAINT_INTERVAL_MS));
-            }
-          })();
-          await conditionPromise;
-          waitDone = true;
-          await repaintLoop;
-        } finally {
-          this.isWaitingPhase = false;
-          this.currentDisplaySpeed = void 0;
+                });
+                observer.observe(document.body, { childList: true, subtree: true, attributes: true });
+                timer = setTimeout(() => {
+                  observer.disconnect();
+                  resolve3(true);
+                }, 500);
+              }),
+              void 0,
+              { timeout: action.timeout }
+            );
+            break;
+          default:
+            conditionPromise = Promise.resolve();
         }
+        await this.waitForConditionWithCapture(conditionPromise, action.displaySpeed);
         break;
       }
     }
@@ -785,7 +948,7 @@ var ClipwiseRecorder = class {
           position: { x: point.x, y: point.y },
           timestamp: Date.now()
         });
-        await new Promise((resolve) => setTimeout(resolve, preset.stepDelayMs));
+        await new Promise((resolve3) => setTimeout(resolve3, preset.stepDelayMs));
       }
     } finally {
       await this.restoreTransitions();
@@ -961,13 +1124,11 @@ import sharp7 from "sharp";
 
 // src/effects/frame.ts
 import sharp from "sharp";
-var TITLE_BAR_HEIGHT = 40;
-var TRAFFIC_LIGHT_Y = 14;
-var TRAFFIC_LIGHT_RADIUS = 6;
-var TRAFFIC_LIGHTS_START_X = 16;
-var TRAFFIC_LIGHT_GAP = 22;
-var ADDRESS_BAR_HEIGHT = 24;
-var ADDRESS_BAR_MARGIN = 70;
+var TITLE_BAR_HEIGHT = 48;
+var TRAFFIC_LIGHT_RADIUS = 6.5;
+var TRAFFIC_LIGHTS_START_X = 22;
+var TRAFFIC_LIGHT_GAP = 20;
+var URL_PILL_HEIGHT = 30;
 var IPHONE_BEZEL = { sides: 12, top: 50, bottom: 34 };
 var IPHONE_OUTER_RADIUS = 47;
 var IPHONE_INNER_RADIUS = 39;
@@ -980,38 +1141,89 @@ var ANDROID_BEZEL = { sides: 8, top: 32, bottom: 20 };
 var ANDROID_OUTER_RADIUS = 35;
 var ANDROID_INNER_RADIUS = 30;
 var ANDROID_CAMERA_RADIUS = 6;
-function buildBrowserChromeSvg(width, darkMode, dpr = 1) {
-  const bg = darkMode ? "#2d2d2d" : "#e8e8e8";
-  const addressBg = darkMode ? "#1a1a1a" : "#ffffff";
-  const addressBorder = darkMode ? "#444444" : "#d0d0d0";
-  const textColor = darkMode ? "#999999" : "#666666";
-  const tbarH = TITLE_BAR_HEIGHT * dpr;
-  const tlY = TRAFFIC_LIGHT_Y * dpr;
+function buildBrowserChromeSvg(width, darkMode, dpr = 1, url = "localhost") {
+  const c = darkMode ? {
+    bgTop: "#3c3c3e",
+    bgBottom: "#343436",
+    border: "#232325",
+    pillBg: "#28282a",
+    pillBorder: "#48484b",
+    text: "#d8d8da",
+    icon: "#a8a8ac",
+    iconDim: "#5f5f63"
+  } : {
+    bgTop: "#f8f7f6",
+    bgBottom: "#eeedeb",
+    border: "#d8d6d3",
+    pillBg: "#ffffff",
+    pillBorder: "#dedcd9",
+    text: "#3a3a3c",
+    icon: "#6f6f72",
+    iconDim: "#bdbdc0"
+  };
+  const h = TITLE_BAR_HEIGHT * dpr;
+  const midY = h / 2;
   const tlR = TRAFFIC_LIGHT_RADIUS * dpr;
   const tlStartX = TRAFFIC_LIGHTS_START_X * dpr;
   const tlGap = TRAFFIC_LIGHT_GAP * dpr;
-  const aBarH = ADDRESS_BAR_HEIGHT * dpr;
-  const aBarMargin = ADDRESS_BAR_MARGIN * dpr;
-  const fontSize = 12 * dpr;
+  const s = dpr;
   const trafficLights = [
-    { cx: tlStartX, fill: "#ff5f57" },
-    { cx: tlStartX + tlGap, fill: "#febc2e" },
-    { cx: tlStartX + tlGap * 2, fill: "#28c840" }
-  ].map(
-    (light) => `<circle cx="${light.cx}" cy="${tlY}" r="${tlR}" fill="${light.fill}"/>`
-  ).join("\n    ");
-  const addressBarWidth = width - aBarMargin * 2;
-  const addressBarX = aBarMargin;
-  const addressBarY = (tbarH - aBarH) / 2;
-  return `<svg xmlns="http://www.w3.org/2000/svg" width="${width}" height="${tbarH}">
-    <rect width="${width}" height="${tbarH}" fill="${bg}"/>
+    { cx: tlStartX, fill: "#ff5f57", stroke: "#e0443e" },
+    { cx: tlStartX + tlGap, fill: "#febc2e", stroke: "#d89e24" },
+    { cx: tlStartX + tlGap * 2, fill: "#28c840", stroke: "#1ea133" }
+  ].map((l) => `<circle cx="${l.cx}" cy="${midY}" r="${tlR}" fill="${l.fill}" stroke="${l.stroke}" stroke-width="${0.5 * s}"/>`).join("\n    ");
+  const navX = tlStartX + tlGap * 2 + 34 * s;
+  const back = `<path d="M ${navX + 4 * s} ${midY - 6 * s} l ${-6 * s} ${6 * s} l ${6 * s} ${6 * s}"
+      fill="none" stroke="${c.icon}" stroke-width="${1.8 * s}" stroke-linecap="round" stroke-linejoin="round"/>`;
+  const fwdX = navX + 28 * s;
+  const forward = `<path d="M ${fwdX - 4 * s} ${midY - 6 * s} l ${6 * s} ${6 * s} l ${-6 * s} ${6 * s}"
+      fill="none" stroke="${c.iconDim}" stroke-width="${1.8 * s}" stroke-linecap="round" stroke-linejoin="round"/>`;
+  const relX = fwdX + 28 * s;
+  const reload = `<path d="M ${relX + 6 * s} ${midY - 3.5 * s} a ${6 * s} ${6 * s} 0 1 0 ${1.2 * s} ${5.5 * s}"
+      fill="none" stroke="${c.icon}" stroke-width="${1.7 * s}" stroke-linecap="round"/>
+    <path d="M ${relX + 6.4 * s} ${midY - 7.5 * s} l ${0.4 * s} ${4.6 * s} l ${-4.6 * s} ${-0.4 * s} z" fill="${c.icon}"/>`;
+  const fontSize = 12.5 * dpr;
+  const pillH = URL_PILL_HEIGHT * dpr;
+  const pillW = Math.max(200 * s, Math.min(width * 0.42, 520 * s));
+  const pillX = (width - pillW) / 2;
+  const pillY = midY - pillH / 2;
+  const textW = url.length * fontSize * 0.56;
+  const lockX = width / 2 - textW / 2 - 16 * s;
+  const lockY = midY - 5 * s;
+  const padlock = `
+    <rect x="${lockX}" y="${lockY + 4 * s}" width="${9 * s}" height="${7 * s}" rx="${1.5 * s}" fill="${c.icon}"/>
+    <path d="M ${lockX + 2 * s} ${lockY + 4 * s} v ${-2 * s} a ${2.5 * s} ${2.5 * s} 0 0 1 ${5 * s} 0 v ${2 * s}"
+      fill="none" stroke="${c.icon}" stroke-width="${1.4 * s}"/>`;
+  const dotsX = width - 26 * s;
+  const dots = [-4.5, 0, 4.5].map((dy) => `<circle cx="${dotsX}" cy="${midY + dy * s}" r="${1.6 * s}" fill="${c.icon}"/>`).join("");
+  const avatar = `
+    <circle cx="${width - 56 * s}" cy="${midY}" r="${11 * s}" fill="url(#cwAvatar)"/>
+    <text x="${width - 56 * s}" y="${midY + 4 * s}" text-anchor="middle"
+      font-family="system-ui, -apple-system, sans-serif" font-size="${10.5 * dpr}" font-weight="600" fill="#ffffff">S</text>`;
+  return `<svg xmlns="http://www.w3.org/2000/svg" width="${width}" height="${h}">
+    <defs>
+      <linearGradient id="cwChromeBg" x1="0" y1="0" x2="0" y2="1">
+        <stop offset="0" stop-color="${c.bgTop}"/>
+        <stop offset="1" stop-color="${c.bgBottom}"/>
+      </linearGradient>
+      <linearGradient id="cwAvatar" x1="0" y1="0" x2="1" y2="1">
+        <stop offset="0" stop-color="#818cf8"/>
+        <stop offset="1" stop-color="#6366f1"/>
+      </linearGradient>
+    </defs>
+    <rect width="${width}" height="${h}" fill="url(#cwChromeBg)"/>
+    <rect y="${h - s}" width="${width}" height="${s}" fill="${c.border}"/>
     ${trafficLights}
-    <rect x="${addressBarX}" y="${addressBarY}" width="${addressBarWidth}" height="${aBarH}"
-          rx="${6 * dpr}" ry="${6 * dpr}" fill="${addressBg}" stroke="${addressBorder}" stroke-width="${dpr}"/>
-    <text x="${width / 2}" y="${tlY + 4 * dpr}" text-anchor="middle"
-          font-family="system-ui, -apple-system, sans-serif" font-size="${fontSize}" fill="${textColor}">
-      localhost
-    </text>
+    ${back}
+    ${forward}
+    ${reload}
+    <rect x="${pillX}" y="${pillY}" width="${pillW}" height="${pillH}"
+          rx="${pillH / 2}" ry="${pillH / 2}" fill="${c.pillBg}" stroke="${c.pillBorder}" stroke-width="${s}"/>
+    ${padlock}
+    <text x="${width / 2 + 7 * s}" y="${midY + fontSize * 0.35}" text-anchor="middle"
+          font-family="system-ui, -apple-system, sans-serif" font-size="${fontSize}" fill="${c.text}">${url}</text>
+    ${dots}
+    ${avatar}
   </svg>`;
 }
 function buildIPhoneFrameSvg(totalWidth, totalHeight, screenWidth, screenHeight, darkMode, dpr = 1) {
@@ -1163,7 +1375,7 @@ async function applyDeviceFrame(frameBuffer, config, frameWidth, frameHeight, dp
     case "browser": {
       const tbarH = TITLE_BAR_HEIGHT * dpr;
       const totalHeight = frameHeight + tbarH;
-      const chromeSvg = buildBrowserChromeSvg(frameWidth, config.darkMode, dpr);
+      const chromeSvg = buildBrowserChromeSvg(frameWidth, config.darkMode, dpr, config.url);
       const chromeBuffer = Buffer.from(chromeSvg);
       const canvas = await sharp({
         create: {
@@ -1551,6 +1763,44 @@ import sharp5 from "sharp";
 function escapeXml(s) {
   return s.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;");
 }
+function isCJK(ch) {
+  const code = ch.codePointAt(0) ?? 0;
+  return code >= 4352 && code <= 4607 || // 한글 자모
+  code >= 11904 && code <= 40959 || // CJK 부수, 한자
+  code >= 44032 && code <= 55215 || // 한글 음절
+  code >= 63744 && code <= 64255 || // CJK 호환 한자
+  code >= 65072 && code <= 65103 || // CJK 호환 형태
+  code >= 65280 && code <= 65519 || // Full-width 문자
+  code >= 12288 && code <= 12543 || // CJK 기호, 히라가나, 가타카나
+  code >= 12784 && code <= 12799 || // 가타카나 확장
+  code >= 131072 && code <= 195103;
+}
+function displayWidth(text) {
+  let w = 0;
+  for (const ch of text) {
+    w += isCJK(ch) ? 1.7 : 1;
+  }
+  return w;
+}
+function wrapText(text, maxWidth) {
+  if (displayWidth(text) <= maxWidth) return [text];
+  const lines = [];
+  let current = "";
+  let currentWidth = 0;
+  for (const ch of text) {
+    const chWidth = isCJK(ch) ? 1.7 : 1;
+    if (currentWidth + chWidth > maxWidth && current.length > 0) {
+      lines.push(current);
+      current = ch;
+      currentWidth = chWidth;
+    } else {
+      current += ch;
+      currentWidth += chWidth;
+    }
+  }
+  if (current.length > 0) lines.push(current);
+  return lines;
+}
 function buildSessions(keystrokes) {
   const hasSessionIds = keystrokes.some((k) => k.sessionId !== void 0);
   if (!hasSessionIds) {
@@ -1584,16 +1834,22 @@ async function renderKeystrokeHud(frameBuffer, keystrokes, frameTimestamp, confi
   const lineGap = Math.round(fontSize * 0.45);
   const charWidth = fontSize * 0.615;
   const maxHudWidth = frameWidth - 60 * dpr;
-  const maxCharsPerLine = Math.max(10, Math.floor((maxHudWidth - hudPadH * 2) / charWidth));
-  const lines = sessions.map(
-    (text) => text.length > maxCharsPerLine ? text.slice(-maxCharsPerLine) : text
-  );
-  const maxLineLen = Math.max(...lines.map((l) => l.length));
+  const maxDisplayWidth = Math.max(10, (maxHudWidth - hudPadH * 2) / charWidth);
+  const wrappedLines = [];
+  sessions.forEach((text, sIdx) => {
+    const wrapped = wrapText(text, maxDisplayWidth);
+    for (const line of wrapped) {
+      wrappedLines.push({ text: line, sessionIdx: sIdx });
+    }
+  });
+  const lines = wrappedLines.map((l) => l.text);
+  const totalLineCount = lines.length;
+  const maxLineDisplayWidth = Math.max(...lines.map((l) => displayWidth(l)));
   const hudWidth = Math.min(
-    Math.ceil(maxLineLen * charWidth) + hudPadH * 2,
+    Math.ceil(maxLineDisplayWidth * charWidth) + hudPadH * 2,
     maxHudWidth
   );
-  const hudHeight = Math.ceil(fontSize * lineCount + lineGap * (lineCount - 1) + hudPadV * 2);
+  const hudHeight = Math.ceil(fontSize * totalLineCount + lineGap * (totalLineCount - 1) + hudPadV * 2);
   const margin = 30 * dpr;
   const hudY = frameHeight - hudHeight - margin;
   let hudX;
@@ -1608,18 +1864,20 @@ async function renderKeystrokeHud(frameBuffer, keystrokes, frameTimestamp, confi
     default:
       hudX = Math.round((frameWidth - hudWidth) / 2);
   }
-  const LINE_OPACITY_FACTORS = [0.45, 0.7, 1];
-  const opacityFactors = LINE_OPACITY_FACTORS.slice(-lineCount);
+  const SESSION_OPACITY_FACTORS = [0.45, 0.7, 1];
+  const sessionOpacities = SESSION_OPACITY_FACTORS.slice(-lineCount);
   const rx = (8 * dpr).toFixed(1);
   const boxOp = (globalOpacity * 0.92).toFixed(3);
   const textX = hudX + hudPadH;
   const baselineY = hudY + hudPadV + fontSize * 0.82;
-  const textElements = lines.map((line, i) => {
-    const op = (globalOpacity * opacityFactors[i]).toFixed(3);
+  const textElements = wrappedLines.map(({ text, sessionIdx }, i) => {
+    const sessionPos = sessions.length <= 3 ? sessionIdx : sessionIdx - (sessions.length - 3);
+    const opFactor = sessionOpacities[Math.max(0, sessionPos)] ?? 1;
+    const op = (globalOpacity * opFactor).toFixed(3);
     const lineY = baselineY + i * (fontSize + lineGap);
     return `<text x="${textX}" y="${lineY}"
           font-family="monospace, Menlo, Consolas" font-size="${fontSize}"
-          fill="${config.textColor}" opacity="${op}">${escapeXml(line)}</text>`;
+          fill="${config.textColor}" opacity="${op}">${escapeXml(text)}</text>`;
   }).join("\n    ");
   const hudSvg = `<svg xmlns="http://www.w3.org/2000/svg" width="${frameWidth}" height="${frameHeight}" shape-rendering="geometricPrecision" text-rendering="geometricPrecision">
     <rect x="${hudX}" y="${hudY}" width="${hudWidth}" height="${hudHeight}"
@@ -2093,7 +2351,7 @@ var CanvasRenderer = class {
    * Workers process frames concurrently; results are collected in order.
    */
   processWithWorkers(frames, contexts, workerCount, perFrameEffects) {
-    return new Promise((resolve, reject) => {
+    return new Promise((resolve3, reject) => {
       const results = new Array(frames.length);
       let completed = 0;
       let nextIndex = 0;
@@ -2131,7 +2389,7 @@ var CanvasRenderer = class {
           completed++;
           if (completed === frames.length) {
             workers.forEach((wk) => wk.terminate());
-            resolve(results);
+            resolve3(results);
           } else {
             dispatch(worker);
           }
@@ -2805,7 +3063,7 @@ var CanvasRenderer = class {
 // src/compose/video-encoder.ts
 import gifenc from "gifenc";
 import sharp9 from "sharp";
-import { writeFile, mkdir, readFile, rm } from "fs/promises";
+import { writeFile, mkdir, readFile as readFile2, rm } from "fs/promises";
 import { join } from "path";
 import { tmpdir } from "os";
 import { spawn } from "child_process";
@@ -2828,20 +3086,20 @@ function resolveEncodingParams(config) {
 var encoderScanPromise = null;
 function scanAvailableEncoders() {
   if (!encoderScanPromise) {
-    encoderScanPromise = new Promise((resolve) => {
+    encoderScanPromise = new Promise((resolve3) => {
       const proc = spawn("ffmpeg", ["-encoders"], {
         stdio: ["ignore", "pipe", "ignore"]
       });
       let out = "";
       proc.stdout.on("data", (d) => out += d.toString());
       proc.on("close", () => {
-        resolve({
+        resolve3({
           hevcHw: out.includes("hevc_videotoolbox"),
           h264Hw: out.includes("h264_videotoolbox"),
           av1: out.includes("libsvtav1")
         });
       });
-      proc.on("error", () => resolve({ hevcHw: false, h264Hw: false, av1: false }));
+      proc.on("error", () => resolve3({ hevcHw: false, h264Hw: false, av1: false }));
     });
   }
   return encoderScanPromise;
@@ -2954,7 +3212,7 @@ async function encodeMp4(frames, config, audio) {
     const encoder = await detectVideoEncoder(config.codec);
     const params = resolveEncodingParams(config);
     await pipeFramesToFfmpeg(frames, config, params, encoder, outputPath, audio);
-    return await readFile(outputPath);
+    return await readFile2(outputPath);
   } finally {
     await rm(outputPath, { force: true }).catch(() => {
     });
@@ -2970,7 +3228,7 @@ async function pipeFramesToFfmpeg(frames, config, params, encoder, outputPath, a
     if (audio.fadeOut > 0) audioFilters.push(`afade=t=out:st=999999:d=${audio.fadeOut / 1e3}`);
   }
   const audioFilterArgs = audioFilters.length > 0 ? ["-af", audioFilters.join(",")] : [];
-  return new Promise((resolve, reject) => {
+  return new Promise((resolve3, reject) => {
     const ffmpeg = spawn(
       "ffmpeg",
       [
@@ -3005,7 +3263,7 @@ async function pipeFramesToFfmpeg(frames, config, params, encoder, outputPath, a
     ffmpeg.stderr.on("data", (d) => stderr += d.toString());
     ffmpeg.on("close", (code) => {
       if (code === 0) {
-        resolve();
+        resolve3();
       } else {
         reject(
           new Error(
@@ -3044,7 +3302,7 @@ async function encodeMp4Stream(frames, config, audio) {
     const encoder = await detectVideoEncoder(config.codec);
     const params = resolveEncodingParams(config);
     await pipeStreamToFfmpeg(frames, config, params, encoder, outputPath, audio);
-    return await readFile(outputPath);
+    return await readFile2(outputPath);
   } finally {
     await rm(outputPath, { force: true }).catch(() => {
     });
@@ -3097,7 +3355,7 @@ async function pipeStreamToFfmpeg(frames, config, params, encoder, outputPath, a
     if (audio.fadeOut > 0) audioFilters.push(`afade=t=out:st=999999:d=${audio.fadeOut / 1e3}`);
   }
   const audioFilterArgs = audioFilters.length > 0 ? ["-af", audioFilters.join(",")] : [];
-  return new Promise((resolve, reject) => {
+  return new Promise((resolve3, reject) => {
     const ffmpeg = spawn(
       "ffmpeg",
       [
@@ -3130,7 +3388,7 @@ async function pipeStreamToFfmpeg(frames, config, params, encoder, outputPath, a
     ffmpeg.stderr.on("data", (d) => stderr += d.toString());
     ffmpeg.on("close", (code) => {
       if (code === 0) {
-        resolve();
+        resolve3();
       } else {
         reject(
           new Error(
@@ -3254,9 +3512,342 @@ var StreamingSession = class extends EventEmitter {
   }
 };
 
-// src/script/parser.ts
+// src/scenes/runner.ts
+import { chromium as chromium2 } from "playwright";
+import { createServer } from "http";
+import { execSync } from "child_process";
+import { readFile as readFile3, writeFile as writeFile2, mkdtemp, rm as rm2 } from "fs/promises";
+import { existsSync as existsSync2 } from "fs";
+import { tmpdir as tmpdir2 } from "os";
+import { join as join2, resolve, dirname, isAbsolute } from "path";
+import { pathToFileURL, fileURLToPath as fileURLToPath2 } from "url";
 import { parse as parseYaml } from "yaml";
-import { readFile as readFile2 } from "fs/promises";
+import sharp10 from "sharp";
+async function loadBrandMotion(scenarioDir) {
+  const defaults = { accent: "#6366f1", font: "editorial", annotations: true };
+  for (const candidate of [
+    resolve(scenarioDir, "..", "brand.yaml"),
+    // .clipwise/scenarios/x.yaml → .clipwise/brand.yaml
+    resolve(scenarioDir, "brand.yaml"),
+    resolve(process.cwd(), ".clipwise", "brand.yaml")
+  ]) {
+    try {
+      const raw = parseYaml(await readFile3(candidate, "utf-8"));
+      return {
+        accent: raw.accent ?? defaults.accent,
+        font: raw.font ?? defaults.font,
+        annotations: raw.annotations ?? defaults.annotations
+      };
+    } catch {
+    }
+  }
+  return defaults;
+}
+function resolveMotionTemplate(template, scenarioDir) {
+  if (template.endsWith(".html")) {
+    const p = isAbsolute(template) ? template : resolve(scenarioDir, template);
+    if (!existsSync2(p)) throw new Error(`Motion template not found: ${p}`);
+    return pathToFileURL(p).href;
+  }
+  const here = dirname(fileURLToPath2(import.meta.url));
+  for (const base of [
+    resolve(here, "..", "templates", "motion"),
+    // dist/ 기준 → 패키지 루트
+    resolve(here, "..", "..", "templates", "motion")
+    // src/scenes/ 기준
+  ]) {
+    const p = join2(base, `${template}.html`);
+    if (existsSync2(p)) return pathToFileURL(p).href;
+  }
+  throw new Error(
+    `Unknown built-in motion template "${template}" (built-ins: intro-title, feature-callout, kinetic-type, vignette)`
+  );
+}
+function footageEffects(effects) {
+  return {
+    ...effects,
+    zoom: { ...effects.zoom, enabled: false },
+    deviceFrame: { ...effects.deviceFrame, enabled: false },
+    keystroke: { ...effects.keystroke, enabled: false },
+    speedRamp: { ...effects.speedRamp, enabled: false },
+    smartSpeed: effects.smartSpeed ? { ...effects.smartSpeed, enabled: false } : effects.smartSpeed,
+    background: {
+      ...effects.background,
+      type: "solid",
+      value: "#000000",
+      padding: 0,
+      borderRadius: 0,
+      shadow: false
+    }
+  };
+}
+async function executeStepsForProbe(page, scene) {
+  for (const step of scene.steps) {
+    for (const action of step.actions) {
+      switch (action.action) {
+        case "navigate":
+          await page.goto(action.url, { waitUntil: action.waitUntil ?? "networkidle" });
+          break;
+        case "click":
+          await page.click(action.selector, { timeout: action.timeout ?? 15e3 });
+          break;
+        case "type":
+          await page.fill(action.selector, action.text, { timeout: action.timeout ?? 15e3 });
+          break;
+        case "hover":
+          await page.hover(action.selector, { timeout: action.timeout ?? 15e3 });
+          break;
+        case "scroll":
+          await page.evaluate(
+            ({ x, y }) => window.scrollBy(x, y),
+            { x: action.x ?? 0, y: action.y ?? 0 }
+          );
+          break;
+        case "wait":
+          await page.waitForTimeout(Math.min(action.duration, 3e3));
+          break;
+        case "waitForSelector":
+          await page.waitForSelector(action.selector, {
+            state: action.state ?? "visible",
+            timeout: action.timeout ?? 15e3
+          });
+          break;
+        case "waitForFunction":
+          await page.waitForFunction(action.expression, void 0, { timeout: action.timeout ?? 3e4 });
+          break;
+        default:
+          break;
+      }
+    }
+  }
+}
+function segmentOutput(scenario) {
+  const dpr = scenario.viewport.deviceScaleFactor ?? 1;
+  return {
+    ...scenario.output,
+    width: scenario.output.width * dpr,
+    height: scenario.output.height * dpr,
+    preset: "archive"
+  };
+}
+async function recordFootageTake(scenario, scene, selectors) {
+  const boxes = /* @__PURE__ */ new Map();
+  if (selectors.length > 0) {
+    const browser = await chromium2.launch();
+    const context = await browser.newContext({
+      viewport: { width: scenario.viewport.width, height: scenario.viewport.height }
+    });
+    if (scenario.prepare) await applyPrepare(context, scenario.prepare);
+    const page = await context.newPage();
+    await executeStepsForProbe(page, scene);
+    await page.evaluate(() => window.scrollTo(0, 0));
+    for (const selector of selectors) {
+      const box = await page.locator(selector).first().boundingBox();
+      if (box) boxes.set(selector, box);
+    }
+    await browser.close();
+  }
+  const takeScenario = {
+    ...scenario,
+    steps: scene.steps,
+    scenes: void 0,
+    effects: footageEffects(scenario.effects)
+  };
+  const recorder = new ClipwiseRecorder();
+  const session = await recorder.record(takeScenario);
+  const renderer = new CanvasRenderer(takeScenario.effects, segmentOutput(scenario), scene.steps);
+  const composed = [];
+  for await (const f of renderer.composeStream(session.frames)) composed.push(f);
+  const frames = await Promise.all(
+    composed.map(
+      (f) => f.rawInfo ? sharp10(f.buffer, {
+        raw: { width: f.rawInfo.width, height: f.rawInfo.height, channels: f.rawInfo.channels }
+      }).png().toBuffer() : Promise.resolve(f.buffer)
+    )
+  );
+  const anchors = [];
+  for (let k = 0; k < scene.steps.length; k++) {
+    const idx = session.frames.findIndex((f) => (f.stepIndex ?? 0) >= k);
+    anchors.push(Math.max(0, idx) / scenario.output.fps);
+  }
+  return { frames, anchors, boxes };
+}
+function fitCardW(cw, ch, maxW = 940, maxH = 540) {
+  return Math.round(Math.min(maxW, maxH * cw / ch));
+}
+async function captureMotionSegment(templateUrl, props, durationMs, scenario) {
+  const fps = scenario.output.fps;
+  const totalFrames = Math.round(durationMs / 1e3 * fps);
+  const browser = await chromium2.launch();
+  const page = await browser.newPage({
+    viewport: { width: scenario.output.width, height: scenario.output.height },
+    deviceScaleFactor: scenario.viewport.deviceScaleFactor ?? 1
+  });
+  const params = new URLSearchParams(
+    Object.fromEntries(Object.entries(props).map(([k, v]) => [k, String(v)]))
+  );
+  await page.goto(`${templateUrl}?${params}`, { waitUntil: "load" });
+  await page.evaluate(() => document.fonts.ready);
+  const frames = [];
+  for (let i = 0; i < totalFrames; i++) {
+    const t = i / fps * 1e3;
+    await page.evaluate(
+      (time) => window.__clipwiseSeek(time),
+      t
+    );
+    frames.push({ index: i, buffer: await page.screenshot({ type: "png" }), timestamp: t });
+  }
+  await browser.close();
+  return { buffer: await encodeMp4(frames, segmentOutput(scenario)), seconds: totalFrames / fps };
+}
+function vignetteProps(scene, take, serverBase, scenario, brand) {
+  const W = scenario.viewport.width;
+  const H = scenario.viewport.height;
+  let crop = { x: 0, y: 0, w: W, h: H };
+  if (scene.crop) {
+    const c = scene.crop;
+    if (c.selector) {
+      const box = take.boxes.get(c.selector);
+      if (!box) throw new Error(`vignette crop selector "${c.selector}" not found in footage "${scene.footage}"`);
+      crop = {
+        x: Math.max(0, box.x - c.pad),
+        y: Math.max(0, box.y - c.pad),
+        w: box.width + c.pad * 2,
+        h: box.height + c.pad * 2
+      };
+    } else if (c.w !== void 0) {
+      crop = { x: c.x ?? 0, y: c.y ?? 0, w: c.w, h: c.h ?? H };
+    }
+    if (c.maxH) crop.h = Math.min(crop.h, c.maxH);
+  }
+  const start = typeof scene.start === "number" ? scene.start : (take.anchors[scene.start.step] ?? 0) + scene.start.offset;
+  const props = {
+    accent: brand.accent,
+    font: brand.font,
+    dur: scene.duration / 1e3,
+    layout: scene.layout,
+    num: scene.num ?? "",
+    label: scene.label ?? "",
+    caption: scene.caption ?? "",
+    base: serverBase,
+    count: take.frames.length,
+    fps: scenario.output.fps,
+    start,
+    rate: scene.rate,
+    cropX: crop.x,
+    cropY: crop.y,
+    cropW: crop.w,
+    cropH: crop.h,
+    cardW: fitCardW(crop.w, crop.h),
+    pushFrom: scene.push?.from ?? 1,
+    pushTo: scene.push?.to ?? 1
+  };
+  if (scene.code?.length) props.code = scene.code.join("||");
+  if (brand.annotations && scene.fx.length > 0) {
+    props.fx = scene.fx.map((fx) => {
+      let coords = fx.coords;
+      if (fx.selector) {
+        const box = take.boxes.get(fx.selector);
+        if (!box) throw new Error(`vignette fx selector "${fx.selector}" not found in footage "${scene.footage}"`);
+        coords = fx.kind === "circle" ? [box.x, box.y, box.width, box.height] : [box.x - 160, box.y + 120, box.x - 12, box.y + box.height / 2];
+      }
+      return `${fx.kind}@${coords.join(",")}@${fx.delay}`;
+    }).join(";");
+  }
+  return props;
+}
+async function renderScenesTimeline(scenario, scenarioDir, onProgress) {
+  const scenes = scenario.scenes ?? [];
+  const screens = scenes.filter((s) => s.type === "screen");
+  const timeline = scenes.filter((s) => s.type !== "screen");
+  const brand = await loadBrandMotion(scenarioDir);
+  const selectorsByFootage = /* @__PURE__ */ new Map();
+  for (const scene of timeline) {
+    if (scene.type !== "vignette") continue;
+    const set = selectorsByFootage.get(scene.footage) ?? /* @__PURE__ */ new Set();
+    if (scene.crop?.selector) set.add(scene.crop.selector);
+    for (const fx of scene.fx) if (fx.selector) set.add(fx.selector);
+    selectorsByFootage.set(scene.footage, set);
+  }
+  const takes = /* @__PURE__ */ new Map();
+  for (const screen of screens) {
+    onProgress?.({ scene: 0, total: timeline.length, label: `footage "${screen.id}"` });
+    takes.set(
+      screen.id,
+      await recordFootageTake(scenario, screen, [...selectorsByFootage.get(screen.id) ?? []])
+    );
+  }
+  const server = createServer((req, res) => {
+    const m = req.url?.match(/^\/([\w-]+)\/(\d+)\.png$/);
+    const take = m ? takes.get(m[1]) : void 0;
+    if (take) {
+      const idx = Math.min(take.frames.length - 1, parseInt(m[2], 10));
+      res.writeHead(200, { "content-type": "image/png", "cache-control": "max-age=3600" });
+      res.end(take.frames[idx]);
+    } else {
+      res.writeHead(404);
+      res.end();
+    }
+  });
+  await new Promise((r) => server.listen(0, r));
+  const port = server.address().port;
+  const totalMs = timeline.reduce((s, sc) => s + sc.duration, 0);
+  let elapsedMs = 0;
+  const segments = [];
+  const tmp = await mkdtemp(join2(tmpdir2(), "clipwise-scenes-"));
+  try {
+    for (let i = 0; i < timeline.length; i++) {
+      const scene = timeline[i];
+      const label = scene.type === "motion" ? scene.template : `vignette(${scene.footage})`;
+      onProgress?.({ scene: i + 1, total: timeline.length, label });
+      const thread = brand.annotations ? {
+        threadFrom: (elapsedMs / totalMs).toFixed(4),
+        threadTo: ((elapsedMs + scene.duration) / totalMs).toFixed(4)
+      } : {};
+      elapsedMs += scene.duration;
+      let segment;
+      if (scene.type === "motion") {
+        const url = resolveMotionTemplate(scene.template, scenarioDir);
+        segment = await captureMotionSegment(
+          url,
+          { accent: brand.accent, font: brand.font, dur: scene.duration / 1e3, ...scene.props, ...thread },
+          scene.duration,
+          scenario
+        );
+      } else {
+        const take = takes.get(scene.footage);
+        const url = resolveMotionTemplate("vignette", scenarioDir);
+        segment = await captureMotionSegment(
+          url,
+          { ...vignetteProps(scene, take, `http://localhost:${port}/${scene.footage}`, scenario, brand), ...thread },
+          scene.duration,
+          scenario
+        );
+      }
+      const segPath = join2(tmp, `s${i}.mp4`);
+      await writeFile2(segPath, segment.buffer);
+      segments.push({ path: segPath, seconds: segment.seconds });
+    }
+  } finally {
+    server.close();
+  }
+  const filters = segments.map((_, i) => `[${i}:v]format=yuv420p[v${i}]`).join(";");
+  const concatInputs = segments.map((_, i) => `[v${i}]`).join("");
+  const outPath = join2(tmp, "timeline.mp4");
+  execSync(
+    `ffmpeg -y ${segments.map((s) => `-i "${s.path}"`).join(" ")} -filter_complex "${filters};${concatInputs}concat=n=${segments.length}:v=1:a=0[v]" -map "[v]" -c:v libx264 -crf 16 -preset slow -movflags +faststart "${outPath}"`,
+    { stdio: ["ignore", "ignore", "pipe"] }
+  );
+  const buffer = await readFile3(outPath);
+  await rm2(tmp, { recursive: true, force: true }).catch(() => {
+  });
+  return buffer;
+}
+
+// src/script/parser.ts
+import { parse as parseYaml2 } from "yaml";
+import { readFile as readFile4 } from "fs/promises";
+import { dirname as dirname2, isAbsolute as isAbsolute2, resolve as resolve2 } from "path";
 
 // src/script/types.ts
 import { z } from "zod";
@@ -3308,29 +3899,41 @@ var WaitForSelectorActionSchema = z.object({
   action: z.literal("waitForSelector"),
   selector: SafeSelectorSchema,
   state: z.enum(["visible", "attached", "hidden"]).default("visible"),
-  timeout: z.number().min(0).default(15e3)
+  timeout: z.number().min(0).default(15e3),
+  /** 대기 중 프레임 연속 캡처 (로딩 애니메이션 보존). */
+  captureWhileWaiting: z.boolean().default(false),
+  /** captureWhileWaiting 사용 시 출력 영상 속도 배율 (1-32). */
+  displaySpeed: z.number().min(1).max(32).default(8)
 });
 var WaitForNavigationActionSchema = z.object({
   action: z.literal("waitForNavigation"),
   waitUntil: z.enum(["load", "domcontentloaded", "networkidle"]).default("networkidle"),
-  timeout: z.number().min(0).default(15e3)
+  timeout: z.number().min(0).default(15e3),
+  captureWhileWaiting: z.boolean().default(false),
+  displaySpeed: z.number().min(1).max(32).default(8)
 });
 var WaitForURLActionSchema = z.object({
   action: z.literal("waitForURL"),
   url: z.string().min(1),
-  timeout: z.number().min(0).default(15e3)
+  timeout: z.number().min(0).default(15e3),
+  captureWhileWaiting: z.boolean().default(false),
+  displaySpeed: z.number().min(1).max(32).default(8)
 });
 var 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)
+  timeout: z.number().min(0).default(3e4),
+  captureWhileWaiting: z.boolean().default(false),
+  displaySpeed: z.number().min(1).max(32).default(8)
 });
 var 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)
+  timeout: z.number().min(0).default(3e4),
+  captureWhileWaiting: z.boolean().default(false),
+  displaySpeed: z.number().min(1).max(32).default(8)
 });
 var SmartWaitActionSchema = z.object({
   action: z.literal("smartWait"),
@@ -3415,7 +4018,9 @@ var BackgroundSchema = z.object({
 var DeviceFrameSchema = z.object({
   enabled: z.boolean().default(false),
   type: z.enum(["browser", "macbook", "iphone", "ipad", "android", "none"]).default("browser"),
-  darkMode: z.boolean().default(false)
+  darkMode: z.boolean().default(false),
+  /** browser 타입의 주소창에 표시할 URL (실제 녹화 URL과 무관한 표시용). */
+  url: z.string().default("localhost")
 });
 var SpeedRampConfigSchema = z.object({
   enabled: z.boolean().default(false),
@@ -3486,7 +4091,8 @@ var OutputConfigSchema = z.object({
   preset: z.enum(["social", "balanced", "archive"]).optional(),
   /** Codec override: h264 (default), hevc (10-bit), av1 (smallest files, slow encode) */
   codec: z.enum(["auto", "h264", "hevc", "av1"]).default("auto"),
-  outputDir: z.string().default("./output"),
+  // Zero-Footprint 계약 (v0.8): 모든 산출물은 .clipwise/ 아래로.
+  outputDir: z.string().default(".clipwise/output"),
   filename: z.string().default("clipwise-recording")
 });
 var StepEffectsOverrideSchema = z.object({
@@ -3525,18 +4131,140 @@ var AudioConfigSchema = z.object({
   /** Fade-out duration in milliseconds. */
   fadeOut: z.number().min(0).default(0)
 });
+var AuthConfigSchema = z.object({
+  /** Path to a Playwright storageState JSON file (cookies + localStorage). */
+  storageState: z.string().optional(),
+  /** Inline cookie definitions (applied after storageState if both specified). */
+  cookies: z.array(
+    z.object({
+      name: z.string(),
+      value: z.string(),
+      domain: z.string(),
+      path: z.string().default("/"),
+      httpOnly: z.boolean().default(false),
+      secure: z.boolean().default(false),
+      sameSite: z.enum(["Strict", "Lax", "None"]).default("Lax")
+    })
+  ).optional()
+});
+var MockRouteSchema = z.object({
+  /** 매칭할 URL 부분 문자열 (예: "/api/dashboard/stats"). */
+  url: z.string().min(1),
+  /** 응답 본문 JSON 파일 경로 (시나리오 파일 기준 상대 경로). */
+  fixture: z.string().optional(),
+  /** 인라인 응답 본문 — fixture 대신 YAML에 직접 작성. */
+  body: z.unknown().optional(),
+  status: z.number().int().min(100).max(599).default(200),
+  contentType: z.string().default("application/json")
+});
+var PrepareConfigSchema = z.object({
+  /** 녹화에서 숨길 요소의 CSS 셀렉터 (쿠키 배너, dev 오버레이 등). */
+  hide: z.array(z.string().min(1)).default([]),
+  /** Date/Date.now를 이 시각으로 고정 (ISO 8601, 예: "2026-06-10T09:00:00Z"). */
+  freezeTime: z.string().optional(),
+  /** Math.random을 이 시드의 결정론적 PRNG로 대체. */
+  seedRandom: z.number().int().optional(),
+  /** 페이지 로드 전 시드할 웹 스토리지 항목. */
+  storage: z.object({
+    localStorage: z.record(z.string()).default({}),
+    sessionStorage: z.record(z.string()).default({})
+  }).optional(),
+  /** 네트워크 응답 목(mock) — 사용자 DB를 시드하지 않고 데모 데이터 제공. */
+  mock: z.array(MockRouteSchema).default([]),
+  /** 임의 CSS/JS 파일 주입 (시나리오 파일 기준 상대 경로). */
+  inject: z.object({
+    css: z.union([z.string(), z.array(z.string())]).optional(),
+    js: z.union([z.string(), z.array(z.string())]).optional()
+  }).optional()
+});
+var MotionSceneSchema = z.object({
+  type: z.literal("motion"),
+  /** 내장 템플릿(intro-title|feature-callout|kinetic-type|vignette) 또는 .html 경로. */
+  template: z.string().min(1),
+  /** 신 길이 (ms). */
+  duration: z.number().min(200).max(6e4),
+  /** 템플릿에 query param으로 주입할 props. */
+  props: z.record(z.union([z.string(), z.number(), z.boolean()])).default({})
+});
+var ScreenSceneSchema = z.object({
+  type: z.literal("screen"),
+  /** vignette가 참조할 푸티지 ID. */
+  id: z.string().min(1),
+  steps: z.array(StepSchema).min(1)
+});
+var SceneFxSchema = z.object({
+  kind: z.enum(["circle", "arrow"]),
+  /** 대상 요소 셀렉터 — bounding box를 실측해 좌표로 사용. */
+  selector: z.string().optional(),
+  /** 명시 좌표 — circle: [x,y,w,h], arrow: [x1,y1,x2,y2]. */
+  coords: z.array(z.number()).length(4).optional(),
+  /** 신 내 드로잉 시작 시각 (ms). */
+  delay: z.number().min(0).default(0)
+});
+var VignetteSceneSchema = z.object({
+  type: z.literal("vignette"),
+  /** 인용할 screen 신의 id. */
+  footage: z.string().min(1),
+  duration: z.number().min(500).max(6e4),
+  layout: z.enum(["hero", "crop", "split"]).default("hero"),
+  num: z.string().optional(),
+  label: z.string().optional(),
+  caption: z.string().optional(),
+  /** split 레이아웃의 코드 카드 라인들. */
+  code: z.array(z.string()).optional(),
+  /** 크롭 영역 — selector 실측(+pad) 또는 명시 좌표. 생략 시 전체 화면. */
+  crop: z.object({
+    selector: z.string().optional(),
+    pad: z.number().default(14),
+    x: z.number().optional(),
+    y: z.number().optional(),
+    w: z.number().optional(),
+    h: z.number().optional(),
+    /** 크롭 높이 상한 (px, 원본 기준) — 와이드 스트립 연출용. */
+    maxH: z.number().optional()
+  }).optional(),
+  /** 푸시인 카메라 (스케일 from→to). */
+  push: z.object({ from: z.number().default(1), to: z.number().default(1) }).optional(),
+  /** 푸티지 인용 시작점 — 초(number) 또는 step 경계 anchor. */
+  start: z.union([z.number(), z.object({ step: z.number().int().min(0), offset: z.number().default(0) })]).default(0),
+  /** 푸티지 재생 배속. */
+  rate: z.number().min(0.1).max(8).default(1),
+  fx: z.array(SceneFxSchema).default([])
+});
+var SceneSchema = z.discriminatedUnion("type", [
+  MotionSceneSchema,
+  ScreenSceneSchema,
+  VignetteSceneSchema
+]);
 var ScenarioSchema = z.object({
   name: z.string(),
   description: z.string().optional(),
   viewport: z.object({
     width: z.number().default(1280),
-    height: z.number().default(800)
+    height: z.number().default(800),
+    /** HiDPI 캡처 배율 — 2면 물리 픽셀 2배(레티나급)로 녹화·합성한다. */
+    deviceScaleFactor: z.number().min(1).max(3).default(1)
   }).default({}),
+  /** Optional authentication — restores browser session for logged-in pages. */
+  auth: AuthConfigSchema.optional(),
+  /** Optional recording-time runtime injection (hide/mock/freezeTime/...). */
+  prepare: PrepareConfigSchema.optional(),
   effects: EffectsConfigSchema.default({}),
   output: OutputConfigSchema.default({}),
   /** Optional audio narration — muxed into MP4 output. */
   audio: AudioConfigSchema.optional(),
-  steps: z.array(StepSchema).min(1)
+  /** steps 기반(클래식) 시나리오. scenes가 있으면 생략 가능. */
+  steps: z.array(StepSchema).default([]),
+  /** Scene System (v0.9 preview) — motion/screen/vignette 타임라인. */
+  scenes: z.array(SceneSchema).optional()
+}).superRefine((s, ctx) => {
+  if (s.steps.length === 0 && !s.scenes?.length) {
+    ctx.addIssue({
+      code: z.ZodIssueCode.custom,
+      path: ["steps"],
+      message: "Array must contain at least 1 element(s) \u2014 provide steps or scenes"
+    });
+  }
 });
 
 // src/script/parser.ts
@@ -3544,7 +4272,7 @@ import { ZodError } from "zod";
 function parseScenario(yamlContent) {
   let raw;
   try {
-    raw = parseYaml(yamlContent);
+    raw = parseYaml2(yamlContent);
   } catch (error) {
     const message = error instanceof Error ? error.message : "Unknown parse error";
     throw new Error(`YAML parse error: ${message}`);
@@ -3563,21 +4291,69 @@ ${details}`);
     throw error;
   }
 }
+function resolvePreparePaths(scenario, scenarioDir) {
+  const prepare = scenario.prepare;
+  if (!prepare) return;
+  const abs = (p) => isAbsolute2(p) ? p : resolve2(scenarioDir, p);
+  for (const mock of prepare.mock) {
+    if (mock.fixture) mock.fixture = abs(mock.fixture);
+  }
+  if (prepare.inject?.css) {
+    prepare.inject.css = Array.isArray(prepare.inject.css) ? prepare.inject.css.map(abs) : abs(prepare.inject.css);
+  }
+  if (prepare.inject?.js) {
+    prepare.inject.js = Array.isArray(prepare.inject.js) ? prepare.inject.js.map(abs) : abs(prepare.inject.js);
+  }
+}
 async function loadScenario(filePath) {
   let content;
   try {
-    content = await readFile2(filePath, "utf-8");
+    content = await readFile4(filePath, "utf-8");
   } catch (error) {
     const message = error instanceof Error ? error.message : "Unknown file error";
     throw new Error(`Failed to read scenario file "${filePath}": ${message}`);
   }
-  return parseScenario(content);
+  const scenario = parseScenario(content);
+  resolvePreparePaths(scenario, dirname2(resolve2(filePath)));
+  return scenario;
 }
 
 // src/script/validator.ts
 function validateScenario(scenario) {
   const errors = [];
   const warnings = [];
+  if (scenario.scenes?.length) {
+    const screenIds = new Set(
+      scenario.scenes.filter((s) => s.type === "screen").map((s) => s.id)
+    );
+    const timeline = scenario.scenes.filter((s) => s.type !== "screen");
+    if (timeline.length === 0) {
+      errors.push("scenes: at least one motion or vignette scene is required (screen scenes are footage sources only)");
+    }
+    if (scenario.output.format !== "mp4") {
+      errors.push(`scenes timeline requires output.format mp4 (got "${scenario.output.format}")`);
+    }
+    for (const scene of scenario.scenes) {
+      if (scene.type === "screen") {
+        const hasNavigate = scene.steps[0]?.actions.some((a) => a.action === "navigate");
+        if (!hasNavigate) {
+          errors.push(`scenes: screen "${scene.id}" must start with a navigate action`);
+        }
+      } else if (scene.type === "vignette") {
+        if (!screenIds.has(scene.footage)) {
+          errors.push(`scenes: vignette references unknown footage "${scene.footage}"`);
+        }
+        for (const fx of scene.fx) {
+          if (!fx.selector && !fx.coords) {
+            errors.push(`scenes: vignette fx (${fx.kind}) needs "selector" or "coords"`);
+          }
+        }
+        if (scene.crop && !scene.crop.selector && scene.crop.w === void 0) {
+          warnings.push("scenes: vignette crop without selector/coords falls back to full frame");
+        }
+      }
+    }
+  }
   if (scenario.steps.length > 0) {
     const firstStep = scenario.steps[0];
     const hasNavigate = firstStep.actions.some(
@@ -3626,6 +4402,32 @@ function validateScenario(scenario) {
       `Output height ${output.height} is out of range (must be 100-3840)`
     );
   }
+  if (scenario.prepare) {
+    const prepare = scenario.prepare;
+    if (prepare.freezeTime && Number.isNaN(Date.parse(prepare.freezeTime))) {
+      errors.push(
+        `prepare.freezeTime "${prepare.freezeTime}" is not a valid date (use ISO 8601, e.g. "2026-06-10T09:00:00Z")`
+      );
+    }
+    for (let i = 0; i < prepare.mock.length; i++) {
+      const mock = prepare.mock[i];
+      if (!mock.fixture && mock.body === void 0) {
+        errors.push(
+          `prepare.mock #${i + 1} ("${mock.url}"): either "fixture" or "body" is required`
+        );
+      }
+      if (mock.fixture && mock.body !== void 0) {
+        warnings.push(
+          `prepare.mock #${i + 1} ("${mock.url}"): both "fixture" and "body" set \u2014 fixture takes precedence`
+        );
+      }
+    }
+    for (const selector of prepare.hide) {
+      if (selector.trim() === "") {
+        errors.push("prepare.hide: selector must not be empty");
+      }
+    }
+  }
   if (output.fps > 30) {
     warnings.push(
       `FPS is set to ${output.fps}. High FPS may produce very large files.`
@@ -3655,9 +4457,15 @@ export {
   ZOOM_INTENSITY_SCALES,
   applyBlur,
   applyCrossfade,
+  applyPrepare,
   applySlide,
   applyTransition,
   applyZoomEasing,
+  buildCssInjectionScript,
+  buildFreezeTimeScript,
+  buildHideCss,
+  buildSeedRandomScript,
+  buildStorageScript,
   buildZoomClickLookup,
   calculateAdaptiveZoom,
   calculateAdaptiveZoomFromLookup,
@@ -3674,7 +4482,9 @@ export {
   renderCursorHighlight,
   renderCursorTrail,
   renderKeystrokeHud,
+  renderScenesTimeline,
   renderWatermark,
+  resolvePreparePaths,
   resolveZoomScale,
   savePngSequence,
   springEasing,