clipwise 0.1.0

package/dist/cli/index.js

@@ -0,0 +1,2150 @@
+#!/usr/bin/env node
+var __defProp = Object.defineProperty;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __esm = (fn, res) => function __init() {
+  return fn && (res = (0, fn[__getOwnPropNames(fn)[0]])(fn = 0)), res;
+};
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+
+// 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 init_types = __esm({
+  "src/script/types.ts"() {
+    "use strict";
+    SafeSelectorSchema = z.string().regex(
+      /^[a-zA-Z0-9\-_#.\[\]="':\s~^$|*,>+()@]+$/,
+      "Selector contains invalid characters"
+    );
+    NavigateActionSchema = z.object({
+      action: z.literal("navigate"),
+      url: z.string().min(1),
+      waitUntil: z.enum(["load", "domcontentloaded", "networkidle"]).default("networkidle")
+    });
+    ClickActionSchema = z.object({
+      action: z.literal("click"),
+      selector: SafeSelectorSchema,
+      delay: z.number().optional()
+    });
+    TypeActionSchema = z.object({
+      action: z.literal("type"),
+      selector: SafeSelectorSchema,
+      text: z.string(),
+      delay: z.number().default(50)
+    });
+    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)
+    });
+    WaitActionSchema = z.object({
+      action: z.literal("wait"),
+      duration: z.number().describe("Wait duration in milliseconds")
+    });
+    HoverActionSchema = z.object({
+      action: z.literal("hover"),
+      selector: SafeSelectorSchema
+    });
+    ScreenshotActionSchema = z.object({
+      action: z.literal("screenshot"),
+      name: z.string().optional(),
+      fullPage: z.boolean().default(false)
+    });
+    StepActionSchema = z.discriminatedUnion("action", [
+      NavigateActionSchema,
+      ClickActionSchema,
+      TypeActionSchema,
+      ScrollActionSchema,
+      WaitActionSchema,
+      HoverActionSchema,
+      ScreenshotActionSchema
+    ]);
+    AutoZoomConfigSchema = z.object({
+      followCursor: z.boolean().default(true),
+      maxScale: z.number().min(1).max(5).default(2),
+      transitionDuration: z.number().default(400),
+      padding: z.number().default(200)
+    });
+    ZoomEffectSchema = z.object({
+      enabled: z.boolean().default(true),
+      scale: z.number().min(1).max(5).default(1.8),
+      duration: z.number().default(600),
+      easing: z.enum(["ease-in-out", "ease-in", "ease-out", "linear"]).default("ease-in-out"),
+      autoZoom: AutoZoomConfigSchema.default({})
+    });
+    CursorEffectSchema = z.object({
+      enabled: z.boolean().default(true),
+      size: z.number().default(20),
+      color: z.string().default("#000000"),
+      speed: z.enum(["fast", "normal", "slow"]).default("fast"),
+      smoothing: z.boolean().default(true),
+      clickEffect: z.boolean().default(true),
+      clickColor: z.string().default("rgba(59, 130, 246, 0.3)"),
+      clickRadius: z.number().default(30),
+      trail: z.boolean().default(false),
+      trailLength: z.number().default(8),
+      trailColor: z.string().default("rgba(59, 130, 246, 0.2)"),
+      highlight: z.boolean().default(false),
+      highlightRadius: z.number().default(40),
+      highlightColor: z.string().default("rgba(255, 215, 0, 0.18)")
+    });
+    BackgroundSchema = z.object({
+      type: z.enum(["gradient", "solid", "image"]).default("gradient"),
+      value: z.string().default("linear-gradient(135deg, #667eea 0%, #764ba2 100%)"),
+      padding: z.number().default(60),
+      borderRadius: z.number().default(12),
+      shadow: z.boolean().default(true)
+    });
+    DeviceFrameSchema = z.object({
+      enabled: z.boolean().default(false),
+      type: z.enum(["browser", "macbook", "iphone", "ipad", "android", "none"]).default("browser"),
+      darkMode: z.boolean().default(false)
+    });
+    SpeedRampConfigSchema = z.object({
+      enabled: z.boolean().default(false),
+      idleSpeed: z.number().min(0.5).max(8).default(3),
+      actionSpeed: z.number().min(0.25).max(2).default(0.8),
+      transitionFrames: z.number().default(15)
+    });
+    KeystrokeConfigSchema = z.object({
+      enabled: z.boolean().default(false),
+      position: z.enum(["bottom-center", "bottom-left", "bottom-right"]).default("bottom-center"),
+      fontSize: z.number().default(18),
+      backgroundColor: z.string().default("rgba(0, 0, 0, 0.75)"),
+      textColor: z.string().default("#ffffff"),
+      padding: z.number().default(8),
+      fadeAfter: z.number().default(1500)
+    });
+    WatermarkConfigSchema = z.object({
+      enabled: z.boolean().default(false),
+      text: z.string().default(""),
+      position: z.enum(["top-left", "top-right", "bottom-left", "bottom-right"]).default("bottom-right"),
+      opacity: z.number().min(0).max(1).default(0.5),
+      fontSize: z.number().default(14),
+      color: z.string().default("#ffffff")
+    });
+    EffectsConfigSchema = z.object({
+      zoom: ZoomEffectSchema.default({}),
+      cursor: CursorEffectSchema.default({}),
+      background: BackgroundSchema.default({}),
+      deviceFrame: DeviceFrameSchema.default({}),
+      speedRamp: SpeedRampConfigSchema.default({}),
+      keystroke: KeystrokeConfigSchema.default({}),
+      watermark: WatermarkConfigSchema.default({})
+    });
+    OutputConfigSchema = z.object({
+      format: z.enum(["gif", "mp4", "webm", "png-sequence"]).default("gif"),
+      width: z.number().default(1280),
+      height: z.number().default(800),
+      fps: z.number().min(1).max(60).default(15),
+      quality: z.number().min(1).max(100).default(80),
+      outputDir: z.string().default("./output"),
+      filename: z.string().default("clipwise-recording")
+    });
+    StepSchema = z.object({
+      name: z.string().optional(),
+      actions: z.array(StepActionSchema),
+      captureDelay: z.number().default(300),
+      holdDuration: z.number().default(1500),
+      transition: z.enum(["fade", "none"]).default("none")
+    });
+    ScenarioSchema = z.object({
+      name: z.string(),
+      description: z.string().optional(),
+      viewport: z.object({
+        width: z.number().default(1280),
+        height: z.number().default(800)
+      }).default({}),
+      effects: EffectsConfigSchema.default({}),
+      output: OutputConfigSchema.default({}),
+      steps: z.array(StepSchema).min(1)
+    });
+  }
+});
+
+// src/script/parser.ts
+var parser_exports = {};
+__export(parser_exports, {
+  loadScenario: () => loadScenario,
+  parseScenario: () => parseScenario
+});
+import { parse as parseYaml } from "yaml";
+import { readFile } from "fs/promises";
+import { ZodError } from "zod";
+function parseScenario(yamlContent) {
+  let raw;
+  try {
+    raw = parseYaml(yamlContent);
+  } catch (error) {
+    const message = error instanceof Error ? error.message : "Unknown parse error";
+    throw new Error(`YAML parse error: ${message}`);
+  }
+  try {
+    return ScenarioSchema.parse(raw);
+  } catch (error) {
+    if (error instanceof ZodError) {
+      const details = error.issues.map((issue) => {
+        const path = issue.path.join(".");
+        return `  - ${path ? `${path}: ` : ""}${issue.message}`;
+      }).join("\n");
+      throw new Error(`Scenario validation failed:
+${details}`);
+    }
+    throw error;
+  }
+}
+async function loadScenario(filePath) {
+  let content;
+  try {
+    content = await readFile(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);
+}
+var init_parser = __esm({
+  "src/script/parser.ts"() {
+    "use strict";
+    init_types();
+  }
+});
+
+// src/cli/index.ts
+init_parser();
+import { Command } from "commander";
+import ora from "ora";
+import chalk from "chalk";
+
+// src/script/validator.ts
+function validateScenario(scenario) {
+  const errors = [];
+  const warnings = [];
+  if (scenario.steps.length > 0) {
+    const firstStep = scenario.steps[0];
+    const hasNavigate = firstStep.actions.some(
+      (a) => a.action === "navigate"
+    );
+    if (!hasNavigate) {
+      errors.push(
+        'First step must contain a "navigate" action to open a page'
+      );
+    }
+  }
+  for (let i = 0; i < scenario.steps.length; i++) {
+    const step = scenario.steps[i];
+    const stepLabel = step.name ? `"${step.name}"` : `#${i + 1}`;
+    for (let j = 0; j < step.actions.length; j++) {
+      const action = step.actions[j];
+      if ("selector" in action && action.selector !== void 0) {
+        const selector = action.selector;
+        if (selector.trim() === "") {
+          errors.push(
+            `Step ${stepLabel}, action #${j + 1} (${action.action}): selector must not be empty`
+          );
+        }
+      }
+    }
+  }
+  const { width, height } = scenario.viewport;
+  if (width < 100 || width > 3840) {
+    errors.push(
+      `Viewport width ${width} is out of range (must be 100-3840)`
+    );
+  }
+  if (height < 100 || height > 3840) {
+    errors.push(
+      `Viewport height ${height} is out of range (must be 100-3840)`
+    );
+  }
+  const output = scenario.output;
+  if (output.width < 100 || output.width > 3840) {
+    errors.push(
+      `Output width ${output.width} is out of range (must be 100-3840)`
+    );
+  }
+  if (output.height < 100 || output.height > 3840) {
+    errors.push(
+      `Output height ${output.height} is out of range (must be 100-3840)`
+    );
+  }
+  if (output.fps > 30) {
+    warnings.push(
+      `FPS is set to ${output.fps}. High FPS may produce very large files.`
+    );
+  }
+  if (output.format === "gif" && output.quality > 90) {
+    warnings.push(
+      "GIF quality above 90 has diminishing returns and increases file size significantly."
+    );
+  }
+  if (scenario.viewport.width !== output.width || scenario.viewport.height !== output.height) {
+    warnings.push(
+      "Viewport dimensions differ from output dimensions. Output will be scaled."
+    );
+  }
+  return {
+    valid: errors.length === 0,
+    errors,
+    warnings
+  };
+}
+
+// src/core/recorder.ts
+import { chromium } from "playwright";
+
+// src/core/cursor-tracker.ts
+function easeInOutCubic(t) {
+  return t < 0.5 ? 4 * t * t * t : 1 - Math.pow(-2 * t + 2, 3) / 2;
+}
+function interpolatePath(from, to, steps) {
+  if (steps <= 0) return [to];
+  if (steps === 1) return [from, to];
+  const dx = to.x - from.x;
+  const dy = to.y - from.y;
+  const cp1 = {
+    x: from.x + dx * 0.25 + dy * 0.1,
+    y: from.y + dy * 0.25 - dx * 0.1
+  };
+  const cp2 = {
+    x: from.x + dx * 0.75 - dy * 0.1,
+    y: from.y + dy * 0.75 + dx * 0.1
+  };
+  const points = [];
+  for (let i = 0; i <= steps; i++) {
+    const rawT = i / steps;
+    const t = easeInOutCubic(rawT);
+    const oneMinusT = 1 - t;
+    const x = oneMinusT * oneMinusT * oneMinusT * from.x + 3 * oneMinusT * oneMinusT * t * cp1.x + 3 * oneMinusT * t * t * cp2.x + t * t * t * to.x;
+    const y = oneMinusT * oneMinusT * oneMinusT * from.y + 3 * oneMinusT * oneMinusT * t * cp1.y + 3 * oneMinusT * t * t * cp2.y + t * t * t * to.y;
+    points.push({ x: Math.round(x), y: Math.round(y) });
+  }
+  return points;
+}
+
+// src/core/screenshot.ts
+async function getElementCenter(page, selector) {
+  if (!/^[\w\-#.\[\]="':\s,>+~*()@^$|]+$/.test(selector)) {
+    throw new Error(`Invalid selector: ${selector}`);
+  }
+  const element = page.locator(selector).first();
+  await element.waitFor({ state: "visible", timeout: 5e3 });
+  const box = await element.boundingBox();
+  if (!box) {
+    throw new Error(
+      `Element "${selector}" not found or has no bounding box`
+    );
+  }
+  return {
+    x: Math.round(box.x + box.width / 2),
+    y: Math.round(box.y + box.height / 2)
+  };
+}
+
+// src/core/recorder.ts
+var CLICK_EFFECT_DURATION_MS = 500;
+var REPAINT_INTERVAL_MS = 50;
+var ACTION_GAP_MS = 30;
+var CURSOR_SPEED_PRESETS = {
+  fast: { steps: 12, delay: 6 },
+  // ~72ms total
+  normal: { steps: 18, delay: 8 },
+  // ~144ms total
+  slow: { steps: 24, delay: 12 }
+  // ~288ms total
+};
+var ClipwiseRecorder = class {
+  browser = null;
+  context = null;
+  page = null;
+  cdpClient = null;
+  rawFrames = [];
+  cursorTimeline = [];
+  clickTimeline = [];
+  keystrokeTimeline = [];
+  currentStepIndex = 0;
+  cursorPosition = { x: 0, y: 0 };
+  viewport = { width: 1280, height: 800 };
+  isCapturing = false;
+  targetFps = 30;
+  cursorSpeed = "fast";
+  /**
+   * Launch the browser and create a page with the scenario viewport.
+   */
+  async init(scenario) {
+    this.viewport = {
+      width: scenario.viewport.width,
+      height: scenario.viewport.height
+    };
+    this.targetFps = scenario.output.fps;
+    this.cursorSpeed = scenario.effects.cursor.speed;
+    this.browser = await chromium.launch({ headless: true });
+    this.context = await this.browser.newContext({
+      viewport: this.viewport
+    });
+    this.page = await this.context.newPage();
+    this.rawFrames = [];
+    this.cursorTimeline = [];
+    this.clickTimeline = [];
+    this.keystrokeTimeline = [];
+    this.currentStepIndex = 0;
+    this.cursorPosition = { x: 0, y: 0 };
+    this.isCapturing = false;
+  }
+  /**
+   * Start CDP screencast for continuous frame capture.
+   * Frames are received asynchronously and stored in rawFrames.
+   */
+  async startCapture() {
+    if (!this.page) throw new Error("Page not initialized");
+    this.cdpClient = await this.page.context().newCDPSession(this.page);
+    this.isCapturing = true;
+    this.cdpClient.on(
+      "Page.screencastFrame",
+      async (event) => {
+        if (!this.isCapturing || !this.cdpClient) return;
+        const buffer = Buffer.from(event.data, "base64");
+        this.rawFrames.push({
+          buffer,
+          timestamp: Date.now()
+        });
+        await this.cdpClient.send("Page.screencastFrameAck", {
+          sessionId: event.sessionId
+        }).catch(() => {
+        });
+      }
+    );
+    await this.cdpClient.send("Page.startScreencast", {
+      format: "jpeg",
+      quality: 95,
+      maxWidth: this.viewport.width,
+      maxHeight: this.viewport.height,
+      everyNthFrame: 1
+    });
+    this.cursorTimeline.push({
+      position: { ...this.cursorPosition },
+      timestamp: Date.now()
+    });
+  }
+  /**
+   * Stop CDP screencast and flush remaining frames.
+   */
+  async stopCapture() {
+    this.isCapturing = false;
+    if (this.cdpClient) {
+      await this.cdpClient.send("Page.stopScreencast").catch(() => {
+      });
+      await this.cdpClient.detach().catch(() => {
+      });
+      this.cdpClient = null;
+    }
+    await new Promise((resolve2) => setTimeout(resolve2, 200));
+  }
+  /**
+   * Execute the full scenario with continuous capture and return a RecordingSession.
+   */
+  async record(scenario) {
+    await this.init(scenario);
+    const startTime = Date.now();
+    try {
+      await this.startCapture();
+      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);
+        }
+        if (step.captureDelay > 0) {
+          await this.waitWithRepaints(step.captureDelay);
+        }
+        const holdMs = step.holdDuration;
+        if (holdMs > 0) {
+          await this.waitWithRepaints(holdMs);
+        }
+      }
+      await this.stopCapture();
+      const rawFrames = this.buildCapturedFrames();
+      const recordingDurationMs = Date.now() - startTime;
+      const frames = this.resampleToTargetFps(
+        rawFrames,
+        recordingDurationMs
+      );
+      return {
+        scenario,
+        frames,
+        startTime,
+        endTime: Date.now()
+      };
+    } catch (error) {
+      await this.stopCapture().catch(() => {
+      });
+      const rawFrames = this.buildCapturedFrames();
+      const recordingDurationMs = Date.now() - startTime;
+      const frames = this.resampleToTargetFps(
+        rawFrames,
+        recordingDurationMs
+      );
+      const err = error instanceof Error ? error : new Error(String(error));
+      err.partialSession = {
+        scenario,
+        frames,
+        startTime,
+        endTime: Date.now()
+      };
+      throw err;
+    } finally {
+      await this.cleanup();
+    }
+  }
+  /**
+   * Wait for a given duration while forcing periodic repaints
+   * so CDP screencast keeps sending frames even on static pages.
+   */
+  async waitWithRepaints(durationMs) {
+    if (!this.page || durationMs <= 0) return;
+    const endTime = Date.now() + durationMs;
+    let toggle = false;
+    while (Date.now() < endTime && this.isCapturing) {
+      await this.page.evaluate((t) => {
+        document.documentElement.style.outline = t ? "0.001px solid transparent" : "none";
+      }, toggle).catch(() => {
+      });
+      toggle = !toggle;
+      const remaining = endTime - Date.now();
+      if (remaining > 0) {
+        await new Promise(
+          (resolve2) => setTimeout(resolve2, Math.min(REPAINT_INTERVAL_MS, remaining))
+        );
+      }
+    }
+  }
+  /**
+   * Execute a single action. CDP screencast captures frames continuously
+   * in the background while actions are performed.
+   */
+  async executeAction(action) {
+    if (!this.page) {
+      throw new Error("Page not initialized. Call init() first.");
+    }
+    switch (action.action) {
+      case "navigate": {
+        await this.page.goto(action.url, { waitUntil: action.waitUntil });
+        await this.waitWithRepaints(300);
+        break;
+      }
+      case "click": {
+        const target = await getElementCenter(this.page, action.selector);
+        await this.moveCursorSmooth(target);
+        this.clickTimeline.push({
+          position: { ...target },
+          timestamp: Date.now()
+        });
+        await this.page.click(action.selector, {
+          delay: action.delay
+        });
+        break;
+      }
+      case "type": {
+        const inputTarget = await getElementCenter(
+          this.page,
+          action.selector
+        );
+        await this.moveCursorSmooth(inputTarget);
+        this.clickTimeline.push({
+          position: { ...inputTarget },
+          timestamp: Date.now()
+        });
+        await this.page.click(action.selector);
+        for (const char of action.text) {
+          await this.page.keyboard.type(char, { delay: action.delay });
+          this.keystrokeTimeline.push({
+            key: char,
+            timestamp: Date.now()
+          });
+        }
+        break;
+      }
+      case "scroll": {
+        const scrollTarget = action.selector ? await getElementCenter(this.page, action.selector) : null;
+        await this.page.evaluate(
+          ({ x, y, smooth, selector }) => {
+            const target = selector ? document.querySelector(selector) : window;
+            if (target) {
+              const options = {
+                left: x,
+                top: y,
+                behavior: smooth ? "smooth" : "instant"
+              };
+              if (target === window) {
+                window.scrollBy(options);
+              } else {
+                target.scrollBy(options);
+              }
+            }
+          },
+          {
+            x: action.x,
+            y: action.y,
+            smooth: action.smooth,
+            selector: action.selector ?? null
+          }
+        );
+        if (scrollTarget) {
+          this.cursorPosition = scrollTarget;
+          this.cursorTimeline.push({
+            position: { ...scrollTarget },
+            timestamp: Date.now()
+          });
+        }
+        const scrollDistance = Math.abs(action.y) + Math.abs(action.x);
+        const scrollWait = action.smooth ? Math.max(600, Math.round(scrollDistance * 0.8)) : 100;
+        await this.waitWithRepaints(scrollWait);
+        await this.waitWithRepaints(150);
+        break;
+      }
+      case "wait": {
+        await this.waitWithRepaints(action.duration);
+        break;
+      }
+      case "hover": {
+        const hoverTarget = await getElementCenter(
+          this.page,
+          action.selector
+        );
+        await this.moveCursorSmooth(hoverTarget);
+        await this.page.hover(action.selector);
+        break;
+      }
+      case "screenshot": {
+        await this.waitWithRepaints(100);
+        break;
+      }
+    }
+    await this.waitWithRepaints(ACTION_GAP_MS);
+  }
+  /**
+   * Move cursor smoothly from current position to target using
+   * manual step-by-step movement with delays between each step.
+   * Speed is controlled by the cursor.speed preset (fast/normal/slow).
+   */
+  async moveCursorSmooth(target) {
+    if (!this.page) return;
+    const { steps, delay } = CURSOR_SPEED_PRESETS[this.cursorSpeed];
+    const from = { ...this.cursorPosition };
+    const path = interpolatePath(from, target, steps);
+    for (const point of path) {
+      await this.page.mouse.move(point.x, point.y);
+      this.cursorTimeline.push({
+        position: { x: point.x, y: point.y },
+        timestamp: Date.now()
+      });
+      await new Promise((resolve2) => setTimeout(resolve2, delay));
+    }
+    this.cursorPosition = { ...target };
+    await this.waitWithRepaints(100);
+  }
+  /**
+   * Build CapturedFrame array from raw screencast frames,
+   * interpolating cursor positions and mapping click events.
+   */
+  buildCapturedFrames() {
+    if (this.rawFrames.length === 0) return [];
+    return this.rawFrames.map((raw, index) => {
+      const cursorPos = this.interpolateCursorAt(raw.timestamp);
+      const clickEvent = this.clickTimeline.find(
+        (click) => raw.timestamp >= click.timestamp && raw.timestamp <= click.timestamp + CLICK_EFFECT_DURATION_MS
+      );
+      let clickProgress;
+      if (clickEvent) {
+        const elapsed = raw.timestamp - clickEvent.timestamp;
+        clickProgress = Math.min(1, elapsed / CLICK_EFFECT_DURATION_MS);
+      }
+      const frameKeystrokes = this.keystrokeTimeline.filter(
+        (k) => k.timestamp <= raw.timestamp
+      );
+      return {
+        index,
+        screenshot: raw.buffer,
+        timestamp: raw.timestamp,
+        cursorPosition: cursorPos,
+        clickPosition: clickEvent?.position ?? null,
+        clickProgress,
+        viewport: { ...this.viewport },
+        keystrokes: frameKeystrokes.length > 0 ? frameKeystrokes : void 0,
+        stepIndex: this.currentStepIndex
+      };
+    });
+  }
+  /**
+   * Resample captured frames to the target FPS.
+   *
+   * Even if CDP only sent a few unique screenshots, we generate enough
+   * output frames for smooth playback. Each output frame:
+   * - Uses the nearest raw screenshot (may be duplicated)
+   * - Gets a uniquely interpolated cursor position
+   * - Gets properly mapped click effects
+   */
+  resampleToTargetFps(frames, recordingDurationMs) {
+    if (frames.length === 0) return [];
+    const targetFrameCount = Math.max(
+      frames.length,
+      Math.round(recordingDurationMs / 1e3 * this.targetFps)
+    );
+    if (targetFrameCount <= frames.length) return frames;
+    const startTime = frames[0].timestamp;
+    const endTime = frames[frames.length - 1].timestamp;
+    const duration = Math.max(1, endTime - startTime);
+    const resampled = [];
+    for (let i = 0; i < targetFrameCount; i++) {
+      const t = targetFrameCount > 1 ? i / (targetFrameCount - 1) : 0;
+      const targetTimestamp = startTime + t * duration;
+      let nearestIdx = 0;
+      let minDist = Infinity;
+      for (let j = 0; j < frames.length; j++) {
+        const dist = Math.abs(frames[j].timestamp - targetTimestamp);
+        if (dist < minDist) {
+          minDist = dist;
+          nearestIdx = j;
+        }
+      }
+      const cursorPos = this.interpolateCursorAt(targetTimestamp);
+      const clickEvent = this.clickTimeline.find(
+        (click) => targetTimestamp >= click.timestamp && targetTimestamp <= click.timestamp + CLICK_EFFECT_DURATION_MS
+      );
+      let clickProgress;
+      if (clickEvent) {
+        const elapsed = targetTimestamp - clickEvent.timestamp;
+        clickProgress = Math.min(1, elapsed / CLICK_EFFECT_DURATION_MS);
+      }
+      const frameKeystrokes = this.keystrokeTimeline.filter(
+        (k) => k.timestamp <= targetTimestamp
+      );
+      resampled.push({
+        index: i,
+        screenshot: frames[nearestIdx].screenshot,
+        timestamp: targetTimestamp,
+        cursorPosition: cursorPos,
+        clickPosition: clickEvent?.position ?? null,
+        clickProgress,
+        viewport: { ...this.viewport },
+        stepName: frames[nearestIdx].stepName,
+        stepIndex: frames[nearestIdx].stepIndex,
+        keystrokes: frameKeystrokes.length > 0 ? frameKeystrokes : void 0
+      });
+    }
+    return resampled;
+  }
+  /**
+   * Interpolate cursor position at a given timestamp using the cursor timeline.
+   */
+  interpolateCursorAt(timestamp) {
+    if (this.cursorTimeline.length === 0) return { x: 0, y: 0 };
+    if (this.cursorTimeline.length === 1) {
+      return { ...this.cursorTimeline[0].position };
+    }
+    let before = this.cursorTimeline[0];
+    let after = this.cursorTimeline[this.cursorTimeline.length - 1];
+    for (let i = 0; i < this.cursorTimeline.length - 1; i++) {
+      if (this.cursorTimeline[i].timestamp <= timestamp && this.cursorTimeline[i + 1].timestamp >= timestamp) {
+        before = this.cursorTimeline[i];
+        after = this.cursorTimeline[i + 1];
+        break;
+      }
+    }
+    if (timestamp <= before.timestamp) return { ...before.position };
+    if (timestamp >= after.timestamp) return { ...after.position };
+    const t = (timestamp - before.timestamp) / (after.timestamp - before.timestamp);
+    return {
+      x: Math.round(
+        before.position.x + (after.position.x - before.position.x) * t
+      ),
+      y: Math.round(
+        before.position.y + (after.position.y - before.position.y) * t
+      )
+    };
+  }
+  /**
+   * Clean up browser resources. Always called after recording.
+   */
+  async cleanup() {
+    if (this.cdpClient) {
+      await this.cdpClient.detach().catch(() => {
+      });
+      this.cdpClient = null;
+    }
+    if (this.context) {
+      await this.context.close().catch(() => {
+      });
+      this.context = null;
+    }
+    if (this.browser) {
+      await this.browser.close().catch(() => {
+      });
+      this.browser = null;
+    }
+    this.page = null;
+  }
+};
+
+// src/compose/canvas-renderer.ts
+import sharp8 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 IPHONE_BEZEL = { sides: 12, top: 50, bottom: 34 };
+var IPHONE_OUTER_RADIUS = 47;
+var IPHONE_INNER_RADIUS = 39;
+var IPHONE_ISLAND = { width: 120, height: 36 };
+var IPHONE_HOME_BAR = { width: 134, height: 5 };
+var IPAD_BEZEL = { sides: 20, top: 24, bottom: 24 };
+var IPAD_OUTER_RADIUS = 18;
+var IPAD_INNER_RADIUS = 12;
+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) {
+  const bg = darkMode ? "#2d2d2d" : "#e8e8e8";
+  const addressBg = darkMode ? "#1a1a1a" : "#ffffff";
+  const addressBorder = darkMode ? "#444444" : "#d0d0d0";
+  const textColor = darkMode ? "#999999" : "#666666";
+  const trafficLights = [
+    { cx: TRAFFIC_LIGHTS_START_X, fill: "#ff5f57" },
+    { cx: TRAFFIC_LIGHTS_START_X + TRAFFIC_LIGHT_GAP, fill: "#febc2e" },
+    { cx: TRAFFIC_LIGHTS_START_X + TRAFFIC_LIGHT_GAP * 2, fill: "#28c840" }
+  ].map(
+    (light) => `<circle cx="${light.cx}" cy="${TRAFFIC_LIGHT_Y}" r="${TRAFFIC_LIGHT_RADIUS}" fill="${light.fill}"/>`
+  ).join("\n    ");
+  const addressBarWidth = width - ADDRESS_BAR_MARGIN * 2;
+  const addressBarX = ADDRESS_BAR_MARGIN;
+  const addressBarY = (TITLE_BAR_HEIGHT - ADDRESS_BAR_HEIGHT) / 2;
+  return `<svg xmlns="http://www.w3.org/2000/svg" width="${width}" height="${TITLE_BAR_HEIGHT}">
+    <rect width="${width}" height="${TITLE_BAR_HEIGHT}" fill="${bg}"/>
+    ${trafficLights}
+    <rect x="${addressBarX}" y="${addressBarY}" width="${addressBarWidth}" height="${ADDRESS_BAR_HEIGHT}"
+          rx="6" ry="6" fill="${addressBg}" stroke="${addressBorder}" stroke-width="1"/>
+    <text x="${width / 2}" y="${TRAFFIC_LIGHT_Y + 4}" text-anchor="middle"
+          font-family="system-ui, -apple-system, sans-serif" font-size="12" fill="${textColor}">
+      localhost
+    </text>
+  </svg>`;
+}
+function buildIPhoneFrameSvg(totalWidth, totalHeight, screenWidth, screenHeight, darkMode) {
+  const bezelColor = darkMode ? "#1a1a1a" : "#f5f5f7";
+  const islandColor = darkMode ? "#000000" : "#1a1a1a";
+  const homeBarColor = darkMode ? "#555555" : "#333333";
+  const islandX = (totalWidth - IPHONE_ISLAND.width) / 2;
+  const islandY = (IPHONE_BEZEL.top - IPHONE_ISLAND.height) / 2 + 4;
+  const homeBarX = (totalWidth - IPHONE_HOME_BAR.width) / 2;
+  const homeBarY = totalHeight - IPHONE_BEZEL.bottom / 2 - IPHONE_HOME_BAR.height / 2;
+  const screenX = IPHONE_BEZEL.sides;
+  const screenY = IPHONE_BEZEL.top;
+  return `<svg xmlns="http://www.w3.org/2000/svg" width="${totalWidth}" height="${totalHeight}">
+    <!-- Device body -->
+    <rect width="${totalWidth}" height="${totalHeight}"
+          rx="${IPHONE_OUTER_RADIUS}" ry="${IPHONE_OUTER_RADIUS}" fill="${bezelColor}"/>
+    <!-- Screen cutout (transparent) -->
+    <rect x="${screenX}" y="${screenY}" width="${screenWidth}" height="${screenHeight}"
+          rx="${IPHONE_INNER_RADIUS}" ry="${IPHONE_INNER_RADIUS}" fill="black"/>
+    <!-- Dynamic Island pill -->
+    <rect x="${islandX}" y="${islandY}" width="${IPHONE_ISLAND.width}" height="${IPHONE_ISLAND.height}"
+          rx="${IPHONE_ISLAND.height / 2}" ry="${IPHONE_ISLAND.height / 2}" fill="${islandColor}"/>
+    <!-- Home indicator bar -->
+    <rect x="${homeBarX}" y="${homeBarY}" width="${IPHONE_HOME_BAR.width}" height="${IPHONE_HOME_BAR.height}"
+          rx="${IPHONE_HOME_BAR.height / 2}" ry="${IPHONE_HOME_BAR.height / 2}" fill="${homeBarColor}"/>
+  </svg>`;
+}
+function buildIPadFrameSvg(totalWidth, totalHeight, screenWidth, screenHeight, darkMode) {
+  const bezelColor = darkMode ? "#1a1a1a" : "#f5f5f7";
+  const cameraColor = darkMode ? "#2a2a2a" : "#3a3a3a";
+  const screenX = IPAD_BEZEL.sides;
+  const screenY = IPAD_BEZEL.top;
+  const cameraCx = totalWidth / 2;
+  const cameraCy = IPAD_BEZEL.top / 2;
+  return `<svg xmlns="http://www.w3.org/2000/svg" width="${totalWidth}" height="${totalHeight}">
+    <!-- Device body -->
+    <rect width="${totalWidth}" height="${totalHeight}"
+          rx="${IPAD_OUTER_RADIUS}" ry="${IPAD_OUTER_RADIUS}" fill="${bezelColor}"/>
+    <!-- Screen cutout -->
+    <rect x="${screenX}" y="${screenY}" width="${screenWidth}" height="${screenHeight}"
+          rx="${IPAD_INNER_RADIUS}" ry="${IPAD_INNER_RADIUS}" fill="black"/>
+    <!-- Front camera dot -->
+    <circle cx="${cameraCx}" cy="${cameraCy}" r="4" fill="${cameraColor}"/>
+  </svg>`;
+}
+function buildAndroidFrameSvg(totalWidth, totalHeight, screenWidth, screenHeight, darkMode) {
+  const bezelColor = darkMode ? "#1a1a1a" : "#e8e8e8";
+  const cameraColor = darkMode ? "#2a2a2a" : "#3a3a3a";
+  const screenX = ANDROID_BEZEL.sides;
+  const screenY = ANDROID_BEZEL.top;
+  const cameraCx = totalWidth / 2;
+  const cameraCy = ANDROID_BEZEL.top / 2;
+  return `<svg xmlns="http://www.w3.org/2000/svg" width="${totalWidth}" height="${totalHeight}">
+    <!-- Device body -->
+    <rect width="${totalWidth}" height="${totalHeight}"
+          rx="${ANDROID_OUTER_RADIUS}" ry="${ANDROID_OUTER_RADIUS}" fill="${bezelColor}"/>
+    <!-- Screen cutout -->
+    <rect x="${screenX}" y="${screenY}" width="${screenWidth}" height="${screenHeight}"
+          rx="${ANDROID_INNER_RADIUS}" ry="${ANDROID_INNER_RADIUS}" fill="black"/>
+    <!-- Punch-hole camera -->
+    <circle cx="${cameraCx}" cy="${cameraCy}" r="${ANDROID_CAMERA_RADIUS}" fill="${cameraColor}"/>
+  </svg>`;
+}
+function buildScreenMaskSvg(width, height, radius) {
+  return `<svg xmlns="http://www.w3.org/2000/svg" width="${width}" height="${height}">
+    <rect width="${width}" height="${height}" rx="${radius}" ry="${radius}" fill="white"/>
+  </svg>`;
+}
+async function applyMobileFrame(frameBuffer, deviceType, darkMode, frameWidth, frameHeight) {
+  let bezel;
+  let innerRadius;
+  switch (deviceType) {
+    case "iphone":
+      bezel = IPHONE_BEZEL;
+      innerRadius = IPHONE_INNER_RADIUS;
+      break;
+    case "ipad":
+      bezel = IPAD_BEZEL;
+      innerRadius = IPAD_INNER_RADIUS;
+      break;
+    case "android":
+      bezel = ANDROID_BEZEL;
+      innerRadius = ANDROID_INNER_RADIUS;
+      break;
+  }
+  const totalWidth = frameWidth + bezel.sides * 2;
+  const totalHeight = frameHeight + bezel.top + bezel.bottom;
+  let frameSvg;
+  switch (deviceType) {
+    case "iphone":
+      frameSvg = buildIPhoneFrameSvg(totalWidth, totalHeight, frameWidth, frameHeight, darkMode);
+      break;
+    case "ipad":
+      frameSvg = buildIPadFrameSvg(totalWidth, totalHeight, frameWidth, frameHeight, darkMode);
+      break;
+    case "android":
+      frameSvg = buildAndroidFrameSvg(totalWidth, totalHeight, frameWidth, frameHeight, darkMode);
+      break;
+  }
+  const maskSvg = buildScreenMaskSvg(frameWidth, frameHeight, innerRadius);
+  const maskedScreen = await sharp(frameBuffer).resize(frameWidth, frameHeight, { fit: "fill" }).composite([
+    {
+      input: Buffer.from(maskSvg),
+      blend: "dest-in"
+    }
+  ]).png().toBuffer();
+  const canvas = await sharp({
+    create: {
+      width: totalWidth,
+      height: totalHeight,
+      channels: 4,
+      background: { r: 0, g: 0, b: 0, alpha: 0 }
+    }
+  }).png().toBuffer();
+  return sharp(canvas).composite([
+    { input: Buffer.from(frameSvg), left: 0, top: 0 },
+    { input: maskedScreen, left: bezel.sides, top: bezel.top }
+  ]).png().toBuffer();
+}
+async function applyDeviceFrame(frameBuffer, config, frameWidth, frameHeight) {
+  if (!config.enabled || config.type === "none") return frameBuffer;
+  switch (config.type) {
+    case "browser": {
+      const totalHeight = frameHeight + TITLE_BAR_HEIGHT;
+      const chromeSvg = buildBrowserChromeSvg(frameWidth, config.darkMode);
+      const chromeBuffer = Buffer.from(chromeSvg);
+      const canvas = await sharp({
+        create: {
+          width: frameWidth,
+          height: totalHeight,
+          channels: 4,
+          background: { r: 0, g: 0, b: 0, alpha: 0 }
+        }
+      }).png().toBuffer();
+      return sharp(canvas).composite([
+        { input: chromeBuffer, left: 0, top: 0 },
+        { input: frameBuffer, left: 0, top: TITLE_BAR_HEIGHT }
+      ]).png().toBuffer();
+    }
+    case "iphone":
+    case "ipad":
+    case "android":
+      return applyMobileFrame(frameBuffer, config.type, config.darkMode, frameWidth, frameHeight);
+    default:
+      return frameBuffer;
+  }
+}
+
+// src/effects/cursor.ts
+import sharp2 from "sharp";
+function buildCursorSvg(size, color) {
+  const s = size;
+  return `<svg xmlns="http://www.w3.org/2000/svg" width="${s}" height="${s}" viewBox="0 0 24 24">
+    <path d="M4 0 L4 22 L10 16 L16 24 L20 22 L14 14 L22 14 Z"
+          fill="${color}" stroke="#ffffff" stroke-width="1.5" stroke-linejoin="round"/>
+  </svg>`;
+}
+function buildClickRippleSvg(radius, color, progress) {
+  const currentRadius = radius * progress;
+  const opacity = Math.max(0, 1 - progress);
+  const size = Math.ceil(radius * 2 + 4);
+  return `<svg xmlns="http://www.w3.org/2000/svg" width="${size}" height="${size}">
+    <circle cx="${size / 2}" cy="${size / 2}" r="${currentRadius}"
+            fill="none" stroke="${color}" stroke-width="2"
+            opacity="${opacity.toFixed(3)}"/>
+    <circle cx="${size / 2}" cy="${size / 2}" r="${currentRadius * 0.6}"
+            fill="${color}" opacity="${(opacity * 0.4).toFixed(3)}"/>
+  </svg>`;
+}
+async function renderCursor(frameBuffer, position, config, frameWidth, frameHeight) {
+  if (!config.enabled) return frameBuffer;
+  const cursorSvg = buildCursorSvg(config.size, config.color);
+  const cursorBuffer = Buffer.from(cursorSvg);
+  const left = Math.max(0, Math.min(Math.round(position.x), frameWidth - 1));
+  const top = Math.max(0, Math.min(Math.round(position.y), frameHeight - 1));
+  return sharp2(frameBuffer).composite([{ input: cursorBuffer, left, top }]).png().toBuffer();
+}
+async function renderClickEffect(frameBuffer, position, config, progress, frameWidth, frameHeight) {
+  if (!config.enabled || !config.clickEffect) return frameBuffer;
+  const clampedProgress = Math.max(0, Math.min(1, progress));
+  const rippleSvg = buildClickRippleSvg(
+    config.clickRadius,
+    config.clickColor,
+    clampedProgress
+  );
+  const rippleBuffer = Buffer.from(rippleSvg);
+  const rippleSize = Math.ceil(config.clickRadius * 2 + 4);
+  const left = Math.max(
+    0,
+    Math.min(
+      Math.round(position.x - rippleSize / 2),
+      frameWidth - rippleSize
+    )
+  );
+  const top = Math.max(
+    0,
+    Math.min(
+      Math.round(position.y - rippleSize / 2),
+      frameHeight - rippleSize
+    )
+  );
+  return sharp2(frameBuffer).composite([{ input: rippleBuffer, left, top }]).png().toBuffer();
+}
+async function renderCursorHighlight(frameBuffer, position, config, frameWidth, frameHeight) {
+  if (!config.enabled || !config.highlight) return frameBuffer;
+  const r = config.highlightRadius;
+  const size = Math.ceil(r * 2 + 4);
+  const cx = size / 2;
+  const cy = size / 2;
+  const highlightSvg = `<svg xmlns="http://www.w3.org/2000/svg" width="${size}" height="${size}">
+    <defs>
+      <radialGradient id="glow">
+        <stop offset="0%" stop-color="${config.highlightColor}" />
+        <stop offset="70%" stop-color="${config.highlightColor}" />
+        <stop offset="100%" stop-color="transparent" />
+      </radialGradient>
+    </defs>
+    <circle cx="${cx}" cy="${cy}" r="${r}" fill="url(#glow)" />
+  </svg>`;
+  const left = Math.max(0, Math.min(Math.round(position.x - cx), frameWidth - size));
+  const top = Math.max(0, Math.min(Math.round(position.y - cy), frameHeight - size));
+  return sharp2(frameBuffer).composite([{ input: Buffer.from(highlightSvg), left, top }]).png().toBuffer();
+}
+async function renderCursorTrail(frameBuffer, positions, config, frameWidth, frameHeight) {
+  if (!config.enabled || !config.trail || positions.length < 2) {
+    return frameBuffer;
+  }
+  const segments = [];
+  for (let i = 1; i < positions.length; i++) {
+    const opacity = i / positions.length * 0.6;
+    const strokeWidth = 1 + i / positions.length * 2;
+    const p1 = positions[i - 1];
+    const p2 = positions[i];
+    segments.push(
+      `<line x1="${p1.x}" y1="${p1.y}" x2="${p2.x}" y2="${p2.y}"
+            stroke="${config.trailColor}" stroke-width="${strokeWidth.toFixed(1)}"
+            stroke-linecap="round" opacity="${opacity.toFixed(3)}"/>`
+    );
+  }
+  const trailSvg = `<svg xmlns="http://www.w3.org/2000/svg" width="${frameWidth}" height="${frameHeight}">
+    ${segments.join("\n    ")}
+  </svg>`;
+  return sharp2(frameBuffer).composite([{ input: Buffer.from(trailSvg), left: 0, top: 0 }]).png().toBuffer();
+}
+
+// src/effects/zoom.ts
+import sharp3 from "sharp";
+async function applyZoom(frameBuffer, focusPoint, scale, frameWidth, frameHeight) {
+  if (scale <= 1) return frameBuffer;
+  const cropWidth = Math.round(frameWidth / scale);
+  const cropHeight = Math.round(frameHeight / scale);
+  let left = Math.round(focusPoint.x - cropWidth / 2);
+  let top = Math.round(focusPoint.y - cropHeight / 2);
+  left = Math.max(0, Math.min(left, frameWidth - cropWidth));
+  top = Math.max(0, Math.min(top, frameHeight - cropHeight));
+  return sharp3(frameBuffer).extract({ left, top, width: cropWidth, height: cropHeight }).resize(frameWidth, frameHeight, { kernel: sharp3.kernel.lanczos3 }).png().toBuffer();
+}
+function calculateAdaptiveZoom(frames, currentIndex, maxScale, transitionFrames) {
+  if (maxScale <= 1) return 1;
+  let minDistance = Infinity;
+  for (let i = 0; i < frames.length; i++) {
+    if (frames[i].clickPosition) {
+      const distance = Math.abs(i - currentIndex);
+      minDistance = Math.min(minDistance, distance);
+    }
+  }
+  if (minDistance === Infinity) return 1;
+  if (minDistance <= transitionFrames) {
+    const t = 1 - minDistance / transitionFrames;
+    const eased = easeInOutCubic2(t);
+    return 1 + (maxScale - 1) * eased;
+  }
+  return 1;
+}
+function easeInOutCubic2(t) {
+  return t < 0.5 ? 4 * t * t * t : 1 - Math.pow(-2 * t + 2, 3) / 2;
+}
+
+// src/effects/background.ts
+import sharp4 from "sharp";
+function parseGradient(value) {
+  const match = value.match(
+    /linear-gradient\(\s*([\d.]+)deg\s*,\s*(.+)\s*\)/
+  );
+  if (!match) {
+    return { angle: 135, stops: [{ color: value, offset: "100%" }] };
+  }
+  const angle = parseFloat(match[1]);
+  const stopsRaw = match[2].split(",").map((s) => s.trim());
+  const stops = stopsRaw.map((stop) => {
+    const parts = stop.trim().split(/\s+/);
+    return {
+      color: parts[0],
+      offset: parts[1] ?? "0%"
+    };
+  });
+  return { angle, stops };
+}
+function angleToGradientCoords(angle) {
+  const rad = (angle - 90) * Math.PI / 180;
+  const x1 = 50 - Math.cos(rad) * 50;
+  const y1 = 50 - Math.sin(rad) * 50;
+  const x2 = 50 + Math.cos(rad) * 50;
+  const y2 = 50 + Math.sin(rad) * 50;
+  return {
+    x1: `${x1.toFixed(1)}%`,
+    y1: `${y1.toFixed(1)}%`,
+    x2: `${x2.toFixed(1)}%`,
+    y2: `${y2.toFixed(1)}%`
+  };
+}
+function buildBackgroundSvg(config, width, height) {
+  if (config.type === "solid") {
+    return `<svg xmlns="http://www.w3.org/2000/svg" width="${width}" height="${height}">
+      <rect width="${width}" height="${height}" fill="${config.value}"/>
+    </svg>`;
+  }
+  const { angle, stops } = parseGradient(config.value);
+  const coords = angleToGradientCoords(angle);
+  const stopElements = stops.map((s) => `<stop offset="${s.offset}" stop-color="${s.color}"/>`).join("\n        ");
+  return `<svg xmlns="http://www.w3.org/2000/svg" width="${width}" height="${height}">
+    <defs>
+      <linearGradient id="bg" x1="${coords.x1}" y1="${coords.y1}" x2="${coords.x2}" y2="${coords.y2}">
+        ${stopElements}
+      </linearGradient>
+    </defs>
+    <rect width="${width}" height="${height}" fill="url(#bg)"/>
+  </svg>`;
+}
+async function applyBackground(frameBuffer, config, outputWidth, outputHeight) {
+  const padding = config.padding;
+  const contentWidth = outputWidth - padding * 2;
+  const contentHeight = outputHeight - padding * 2;
+  if (contentWidth <= 0 || contentHeight <= 0) {
+    return frameBuffer;
+  }
+  const resizedFrame = await sharp4(frameBuffer).resize(contentWidth, contentHeight, { fit: "fill" }).png().toBuffer();
+  const bgSvg = buildBackgroundSvg(config, outputWidth, outputHeight);
+  const bgBuffer = Buffer.from(bgSvg);
+  const radius = config.borderRadius;
+  const roundedMask = Buffer.from(
+    `<svg xmlns="http://www.w3.org/2000/svg" width="${contentWidth}" height="${contentHeight}">
+      <rect width="${contentWidth}" height="${contentHeight}" rx="${radius}" ry="${radius}" fill="#ffffff"/>
+    </svg>`
+  );
+  const maskedFrame = await sharp4(resizedFrame).composite([
+    {
+      input: roundedMask,
+      blend: "dest-in"
+    }
+  ]).png().toBuffer();
+  const composites = [];
+  if (config.shadow) {
+    const shadowSvg = Buffer.from(
+      `<svg xmlns="http://www.w3.org/2000/svg" width="${outputWidth}" height="${outputHeight}">
+        <defs>
+          <filter id="shadow" x="-20%" y="-20%" width="140%" height="140%">
+            <feDropShadow dx="0" dy="4" stdDeviation="16" flood-color="rgba(0,0,0,0.3)"/>
+          </filter>
+        </defs>
+        <rect x="${padding}" y="${padding}" width="${contentWidth}" height="${contentHeight}"
+              rx="${radius}" ry="${radius}" fill="rgba(0,0,0,0.15)" filter="url(#shadow)"/>
+      </svg>`
+    );
+    composites.push({ input: shadowSvg, left: 0, top: 0 });
+  }
+  composites.push({ input: maskedFrame, left: padding, top: padding });
+  return sharp4(bgBuffer).resize(outputWidth, outputHeight).composite(composites).png().toBuffer();
+}
+
+// src/effects/keystroke.ts
+import sharp5 from "sharp";
+async function renderKeystrokeHud(frameBuffer, keystrokes, frameTimestamp, config, frameWidth, frameHeight) {
+  if (!config.enabled || keystrokes.length === 0) return frameBuffer;
+  const recentKeys = keystrokes.filter(
+    (k) => frameTimestamp - k.timestamp < config.fadeAfter
+  );
+  if (recentKeys.length === 0) return frameBuffer;
+  const displayText = recentKeys.map((k) => k.key).join("");
+  if (displayText.length === 0) return frameBuffer;
+  const charWidth = config.fontSize * 0.62;
+  const textWidth = Math.ceil(displayText.length * charWidth);
+  const hudPadH = config.padding * 2;
+  const hudPadV = config.padding * 1.5;
+  const hudWidth = Math.min(textWidth + hudPadH * 2, frameWidth - 40);
+  const hudHeight = Math.ceil(config.fontSize + hudPadV * 2);
+  const newest = recentKeys[recentKeys.length - 1];
+  const age = frameTimestamp - newest.timestamp;
+  const fadeStart = config.fadeAfter * 0.6;
+  const opacity = age > fadeStart ? Math.max(0, 1 - (age - fadeStart) / (config.fadeAfter - fadeStart)) : 1;
+  if (opacity <= 0) return frameBuffer;
+  let hudX;
+  const hudY = frameHeight - hudHeight - 30;
+  switch (config.position) {
+    case "bottom-left":
+      hudX = 30;
+      break;
+    case "bottom-right":
+      hudX = frameWidth - hudWidth - 30;
+      break;
+    case "bottom-center":
+    default:
+      hudX = Math.round((frameWidth - hudWidth) / 2);
+      break;
+  }
+  const maxChars = Math.floor((hudWidth - hudPadH * 2) / charWidth);
+  const truncated = displayText.length > maxChars ? displayText.slice(-maxChars) : displayText;
+  const escaped = truncated.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;");
+  const hudSvg = `<svg xmlns="http://www.w3.org/2000/svg" width="${frameWidth}" height="${frameHeight}">
+    <rect x="${hudX}" y="${hudY}" width="${hudWidth}" height="${hudHeight}"
+          rx="8" ry="8" fill="${config.backgroundColor}" opacity="${opacity.toFixed(3)}" />
+    <text x="${hudX + hudPadH}" y="${hudY + hudPadV + config.fontSize * 0.75}"
+          font-family="monospace, Menlo, Consolas" font-size="${config.fontSize}"
+          fill="${config.textColor}" opacity="${opacity.toFixed(3)}">${escaped}</text>
+  </svg>`;
+  return sharp5(frameBuffer).composite([{ input: Buffer.from(hudSvg), left: 0, top: 0 }]).png().toBuffer();
+}
+
+// src/effects/transition.ts
+import sharp6 from "sharp";
+async function applyCrossfade(fromBuffer, toBuffer, progress, width, height) {
+  const t = Math.max(0, Math.min(1, progress));
+  if (t <= 0) return fromBuffer;
+  if (t >= 1) return toBuffer;
+  const fromRaw = await sharp6(fromBuffer).ensureAlpha().raw().toBuffer({ resolveWithObject: true });
+  const toRaw = await sharp6(toBuffer).resize(fromRaw.info.width, fromRaw.info.height, { fit: "fill" }).ensureAlpha().raw().toBuffer({ resolveWithObject: true });
+  const pixels = Buffer.alloc(fromRaw.data.length);
+  for (let i = 0; i < fromRaw.data.length; i++) {
+    pixels[i] = Math.round(
+      fromRaw.data[i] * (1 - t) + toRaw.data[i] * t
+    );
+  }
+  return sharp6(pixels, {
+    raw: {
+      width: fromRaw.info.width,
+      height: fromRaw.info.height,
+      channels: 4
+    }
+  }).png().toBuffer();
+}
+
+// src/effects/watermark.ts
+import sharp7 from "sharp";
+async function renderWatermark(frameBuffer, config, frameWidth, frameHeight) {
+  if (!config.enabled || !config.text) return frameBuffer;
+  const charWidth = config.fontSize * 0.62;
+  const textWidth = Math.ceil(config.text.length * charWidth);
+  const margin = 16;
+  let x;
+  let y;
+  switch (config.position) {
+    case "top-left":
+      x = margin;
+      y = margin + config.fontSize;
+      break;
+    case "top-right":
+      x = frameWidth - textWidth - margin;
+      y = margin + config.fontSize;
+      break;
+    case "bottom-left":
+      x = margin;
+      y = frameHeight - margin;
+      break;
+    case "bottom-right":
+    default:
+      x = frameWidth - textWidth - margin;
+      y = frameHeight - margin;
+      break;
+  }
+  const escaped = config.text.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;");
+  const watermarkSvg = `<svg xmlns="http://www.w3.org/2000/svg" width="${frameWidth}" height="${frameHeight}">
+    <text x="${x}" y="${y}"
+          font-family="system-ui, -apple-system, sans-serif" font-size="${config.fontSize}"
+          font-weight="600" fill="${config.color}"
+          opacity="${config.opacity.toFixed(3)}">${escaped}</text>
+  </svg>`;
+  return sharp7(frameBuffer).composite([{ input: Buffer.from(watermarkSvg), left: 0, top: 0 }]).png().toBuffer();
+}
+
+// src/compose/canvas-renderer.ts
+function getFrameOffset(config) {
+  if (!config.enabled) return { left: 0, top: 0 };
+  switch (config.type) {
+    case "browser":
+      return { left: 0, top: 40 };
+    case "iphone":
+      return { left: 12, top: 50 };
+    case "ipad":
+      return { left: 20, top: 24 };
+    case "android":
+      return { left: 8, top: 32 };
+    default:
+      return { left: 0, top: 0 };
+  }
+}
+var CanvasRenderer = class {
+  constructor(effects, output, steps) {
+    this.effects = effects;
+    this.output = output;
+    this.steps = steps ?? [];
+  }
+  steps;
+  /**
+   * Apply the full effects pipeline to a single captured frame.
+   *
+   * Pipeline order:
+   *  1. Device frame (browser chrome / mobile mockup)
+   *  2. Cursor highlight (Screen Studio glow)
+   *  3. Cursor trail
+   *  4. Cursor rendering
+   *  5. Click ripple effect (animated progress)
+   *  6. Keystroke HUD
+   *  7. Zoom (adaptive, cursor-following)
+   *  8. Background (padding, gradient, rounded corners)
+   *  9. Watermark overlay
+   *  10. Final resize
+   */
+  async composeFrame(frame, context) {
+    let buffer = frame.screenshot;
+    let width = frame.viewport.width;
+    let height = frame.viewport.height;
+    const ctx = {
+      zoomScale: context?.zoomScale ?? 1,
+      clickProgress: context?.clickProgress ?? null,
+      cursorTrail: context?.cursorTrail ?? []
+    };
+    if (this.effects.deviceFrame.enabled) {
+      buffer = await applyDeviceFrame(
+        buffer,
+        this.effects.deviceFrame,
+        width,
+        height
+      );
+      const meta = await sharp8(buffer).metadata();
+      width = meta.width ?? width;
+      height = meta.height ?? height;
+    }
+    if (this.effects.cursor.enabled && this.effects.cursor.highlight && frame.cursorPosition) {
+      buffer = await renderCursorHighlight(
+        buffer,
+        frame.cursorPosition,
+        this.effects.cursor,
+        width,
+        height
+      );
+    }
+    if (this.effects.cursor.enabled && this.effects.cursor.trail && ctx.cursorTrail.length >= 2) {
+      buffer = await renderCursorTrail(
+        buffer,
+        ctx.cursorTrail,
+        this.effects.cursor,
+        width,
+        height
+      );
+    }
+    if (this.effects.cursor.enabled && frame.cursorPosition) {
+      buffer = await renderCursor(
+        buffer,
+        frame.cursorPosition,
+        this.effects.cursor,
+        width,
+        height
+      );
+    }
+    if (this.effects.cursor.enabled && this.effects.cursor.clickEffect && frame.clickPosition) {
+      const progress = ctx.clickProgress ?? frame.clickProgress ?? 0.5;
+      buffer = await renderClickEffect(
+        buffer,
+        frame.clickPosition,
+        this.effects.cursor,
+        progress,
+        width,
+        height
+      );
+    }
+    if (this.effects.keystroke.enabled && frame.keystrokes) {
+      buffer = await renderKeystrokeHud(
+        buffer,
+        frame.keystrokes,
+        frame.timestamp,
+        this.effects.keystroke,
+        width,
+        height
+      );
+    }
+    const scale = ctx.zoomScale;
+    if (this.effects.zoom.enabled && scale > 1) {
+      const rawFocus = frame.clickPosition ?? frame.cursorPosition ?? { x: width / 2, y: height / 2 };
+      const offset = getFrameOffset(this.effects.deviceFrame);
+      const focusPoint = {
+        x: rawFocus.x + offset.left,
+        y: rawFocus.y + offset.top
+      };
+      buffer = await applyZoom(buffer, focusPoint, scale, width, height);
+    }
+    buffer = await applyBackground(
+      buffer,
+      this.effects.background,
+      this.output.width,
+      this.output.height
+    );
+    if (this.effects.watermark.enabled) {
+      buffer = await renderWatermark(
+        buffer,
+        this.effects.watermark,
+        this.output.width,
+        this.output.height
+      );
+    }
+    buffer = await sharp8(buffer).resize(this.output.width, this.output.height, { fit: "fill" }).png().toBuffer();
+    return {
+      index: frame.index,
+      buffer,
+      timestamp: frame.timestamp
+    };
+  }
+  /**
+   * Process an entire sequence of captured frames through the effects pipeline.
+   *
+   * Multi-pass approach:
+   *   Pass 1: Speed ramping (adjust frame set).
+   *   Pass 2: Calculate per-frame contexts (zoom, click, trail).
+   *   Pass 3: Render each frame with effects.
+   *   Pass 4: Apply scene transitions at step boundaries.
+   */
+  async composeAll(frames) {
+    if (frames.length === 0) return [];
+    let processFrames = frames;
+    if (this.effects.speedRamp.enabled) {
+      processFrames = this.applySpeedRamp(frames);
+    }
+    const contexts = this.calculateFrameContexts(processFrames);
+    const composed = [];
+    for (let i = 0; i < processFrames.length; i++) {
+      const result = await this.composeFrame(processFrames[i], contexts[i]);
+      composed.push(result);
+    }
+    if (this.steps.length > 0) {
+      await this.applyTransitions(composed, processFrames);
+    }
+    return composed;
+  }
+  /**
+   * Calculate per-frame rendering context (zoom, click progress, cursor trail, tilt).
+   */
+  calculateFrameContexts(frames) {
+    const contexts = [];
+    const transitionFrames = Math.round(
+      this.output.fps * (this.effects.zoom.duration / 1e3)
+    );
+    for (let i = 0; i < frames.length; i++) {
+      const frame = frames[i];
+      let zoomScale = 1;
+      if (this.effects.zoom.enabled) {
+        zoomScale = calculateAdaptiveZoom(
+          frames,
+          i,
+          this.effects.zoom.scale,
+          transitionFrames
+        );
+      }
+      const clickProgress = frame.clickPosition != null ? frame.clickProgress ?? 0.5 : null;
+      const trailLength = this.effects.cursor.trailLength;
+      const trail = [];
+      for (let j = Math.max(0, i - trailLength); j <= i; j++) {
+        if (frames[j].cursorPosition) {
+          trail.push(frames[j].cursorPosition);
+        }
+      }
+      contexts.push({ zoomScale, clickProgress, cursorTrail: trail });
+    }
+    return contexts;
+  }
+  /**
+   * Apply speed ramping: slow down near actions, speed up during idle.
+   * Returns a new frame array with frames duplicated or skipped.
+   */
+  applySpeedRamp(frames) {
+    const config = this.effects.speedRamp;
+    if (!config.enabled) return frames;
+    const proximityRadius = Math.round(this.output.fps * 1);
+    const actionIndices = /* @__PURE__ */ new Set();
+    for (let i = 0; i < frames.length; i++) {
+      if (frames[i].clickPosition) {
+        for (let j = Math.max(0, i - proximityRadius); j <= Math.min(frames.length - 1, i + proximityRadius); j++) {
+          actionIndices.add(j);
+        }
+      }
+    }
+    const result = [];
+    for (let i = 0; i < frames.length; i++) {
+      const isAction = actionIndices.has(i);
+      if (isAction) {
+        const copies = Math.max(1, Math.round(1 / config.actionSpeed));
+        for (let c = 0; c < copies; c++) {
+          result.push({ ...frames[i], index: result.length });
+        }
+      } else {
+        const skipRate = Math.max(1, Math.round(config.idleSpeed));
+        if (i % skipRate === 0) {
+          result.push({ ...frames[i], index: result.length });
+        }
+      }
+    }
+    return result;
+  }
+  /**
+   * Apply crossfade transitions at step boundaries where configured.
+   * Modifies the composed array in-place.
+   */
+  async applyTransitions(composed, frames) {
+    const transitionFrames = Math.max(2, Math.round(this.output.fps * 0.3));
+    const boundaries = [];
+    for (let i = 1; i < frames.length; i++) {
+      if (frames[i].stepIndex !== void 0 && frames[i - 1].stepIndex !== void 0 && frames[i].stepIndex !== frames[i - 1].stepIndex) {
+        const stepIdx = frames[i].stepIndex;
+        const step = this.steps[stepIdx];
+        if (step && step.transition === "fade") {
+          boundaries.push({ index: i, stepIndex: stepIdx });
+        }
+      }
+    }
+    for (const boundary of boundaries) {
+      const startIdx = Math.max(0, boundary.index - Math.floor(transitionFrames / 2));
+      const endIdx = Math.min(composed.length - 1, boundary.index + Math.ceil(transitionFrames / 2));
+      const range = endIdx - startIdx;
+      if (range < 2) continue;
+      const fromBuffer = composed[startIdx].buffer;
+      const toBuffer = composed[endIdx].buffer;
+      const width = this.output.width;
+      const height = this.output.height;
+      for (let i = startIdx + 1; i < endIdx; i++) {
+        const progress = (i - startIdx) / range;
+        composed[i].buffer = await applyCrossfade(
+          fromBuffer,
+          toBuffer,
+          progress,
+          width,
+          height
+        );
+      }
+    }
+  }
+};
+
+// src/compose/video-encoder.ts
+import gifenc from "gifenc";
+import sharp9 from "sharp";
+import { writeFile, mkdir, readFile as readFile2, rm, mkdtemp } from "fs/promises";
+import { join } from "path";
+import { tmpdir } from "os";
+import { spawn } from "child_process";
+var { GIFEncoder, quantize, applyPalette } = gifenc;
+async function encodeGif(frames, config) {
+  if (frames.length === 0) {
+    throw new Error("Cannot encode GIF: no frames provided");
+  }
+  const width = config.width;
+  const height = config.height;
+  const gif = GIFEncoder();
+  const delay = Math.round(1e3 / config.fps);
+  for (const frame of frames) {
+    const { data, info } = await sharp9(frame.buffer).resize(width, height, { fit: "fill" }).ensureAlpha().raw().toBuffer({ resolveWithObject: true });
+    const rgba = new Uint8Array(data.buffer, data.byteOffset, data.byteLength);
+    const palette = quantize(rgba, 256);
+    const indexed = applyPalette(rgba, palette);
+    gif.writeFrame(indexed, width, height, {
+      palette,
+      delay
+    });
+  }
+  gif.finish();
+  return Buffer.from(gif.bytes());
+}
+async function encodeMp4(frames, config) {
+  if (frames.length === 0) {
+    throw new Error("Cannot encode MP4: no frames provided");
+  }
+  const tmpDir = await mkdtemp(join(tmpdir(), "clipwise-"));
+  try {
+    const padLength = String(frames.length).length;
+    for (const frame of frames) {
+      const paddedIndex = String(frame.index).padStart(padLength, "0");
+      const pngBuffer = await sharp9(frame.buffer).resize(config.width, config.height, { fit: "fill" }).png().toBuffer();
+      await writeFile(join(tmpDir, `frame-${paddedIndex}.png`), pngBuffer);
+    }
+    const outputPath = join(tmpDir, "output.mp4");
+    const crf = Math.round(51 - config.quality / 100 * 51);
+    await runFfmpeg([
+      "-y",
+      "-framerate",
+      String(config.fps),
+      "-i",
+      join(tmpDir, `frame-%0${padLength}d.png`),
+      "-c:v",
+      "libx264",
+      "-pix_fmt",
+      "yuv420p",
+      "-crf",
+      String(crf),
+      "-preset",
+      "slow",
+      "-tune",
+      "animation",
+      "-movflags",
+      "+faststart",
+      outputPath
+    ]);
+    return await readFile2(outputPath);
+  } finally {
+    await rm(tmpDir, { recursive: true, force: true }).catch(() => {
+    });
+  }
+}
+function runFfmpeg(args) {
+  return new Promise((resolve2, reject) => {
+    const proc = spawn("ffmpeg", args, { stdio: ["ignore", "pipe", "pipe"] });
+    let stderr = "";
+    proc.stderr.on("data", (data) => {
+      stderr += data.toString();
+    });
+    proc.on("close", (code) => {
+      if (code === 0) {
+        resolve2();
+      } else {
+        reject(
+          new Error(
+            `FFmpeg encoding failed (exit code ${code}). Make sure ffmpeg is installed: brew install ffmpeg
+` + stderr.slice(-500)
+          )
+        );
+      }
+    });
+    proc.on("error", (err) => {
+      if (err.code === "ENOENT") {
+        reject(
+          new Error(
+            "ffmpeg not found. Install it to encode MP4:\n  macOS: brew install ffmpeg\n  Ubuntu: sudo apt install ffmpeg\n  Windows: choco install ffmpeg"
+          )
+        );
+      } else {
+        reject(err);
+      }
+    });
+  });
+}
+async function savePngSequence(frames, config) {
+  if (frames.length === 0) {
+    throw new Error("Cannot save PNG sequence: no frames provided");
+  }
+  const outputDir = join(config.outputDir, config.filename);
+  await mkdir(outputDir, { recursive: true });
+  const paths = [];
+  const padLength = String(frames.length).length;
+  for (const frame of frames) {
+    const paddedIndex = String(frame.index).padStart(padLength, "0");
+    const filename = `frame-${paddedIndex}.png`;
+    const filePath = join(outputDir, filename);
+    const pngBuffer = await sharp9(frame.buffer).resize(config.width, config.height, { fit: "fill" }).png().toBuffer();
+    await writeFile(filePath, pngBuffer);
+    paths.push(filePath);
+  }
+  return paths;
+}
+
+// src/cli/index.ts
+import { writeFile as writeFile2, mkdir as mkdir2, access } from "fs/promises";
+import { join as join2, resolve, dirname } from "path";
+import { pathToFileURL } from "url";
+var program = new Command();
+program.name("clipwise").description(
+  "Playwright-based cinematic screen recorder for product demos"
+).version("0.1.0");
+program.command("record").description("Record a demo from a YAML scenario file").argument("<scenario>", "Path to YAML scenario file").option("-o, --output <dir>", "Output directory", "./output").option(
+  "-f, --format <format>",
+  "Output format (gif|mp4|png-sequence)",
+  "gif"
+).option("--no-effects", "Disable all effects").action(async (scenarioPath, options) => {
+  const spinner = ora();
+  try {
+    spinner.start("Loading scenario...");
+    const scenario = await loadScenario(scenarioPath);
+    const scenarioDir = dirname(resolve(scenarioPath));
+    for (const step of scenario.steps) {
+      for (const action of step.actions) {
+        if (action.action === "navigate") {
+          const url = action.url;
+          if (!url.startsWith("http://") && !url.startsWith("https://") && !url.startsWith("file://")) {
+            action.url = pathToFileURL(resolve(scenarioDir, url)).href;
+          }
+        }
+      }
+    }
+    scenario.output.outputDir = options.output;
+    if (options.format) {
+      scenario.output.format = options.format;
+    }
+    spinner.succeed(`Scenario loaded: ${chalk.bold(scenario.name)}`);
+    spinner.start("Validating scenario...");
+    const validation = validateScenario(scenario);
+    if (!validation.valid) {
+      spinner.fail("Scenario validation failed:");
+      for (const error of validation.errors) {
+        console.error(chalk.red(`  \u2717 ${error}`));
+      }
+      process.exit(1);
+    }
+    for (const warning of validation.warnings) {
+      console.warn(chalk.yellow(`  \u26A0 ${warning}`));
+    }
+    spinner.succeed("Scenario is valid");
+    spinner.start("Checking browser...");
+    try {
+      const { chromium: chromium2 } = await import("playwright");
+      const testBrowser = await chromium2.launch({ headless: true });
+      await testBrowser.close();
+      spinner.succeed("Browser ready");
+    } catch {
+      spinner.fail("Chromium not found");
+      console.log(chalk.yellow("\nInstalling Chromium (one-time setup)...\n"));
+      const { execSync } = await import("child_process");
+      try {
+        execSync("npx playwright install chromium", { stdio: "inherit" });
+        console.log(chalk.green("\nChromium installed successfully!\n"));
+      } catch {
+        console.error(chalk.red("\nFailed to install Chromium. Run manually:\n  npx playwright install chromium\n"));
+        process.exit(1);
+      }
+    }
+    spinner.start(
+      `Recording ${scenario.steps.length} steps...`
+    );
+    const recorder = new ClipwiseRecorder();
+    const session = await recorder.record(scenario);
+    spinner.succeed(
+      `Recorded ${session.frames.length} frames`
+    );
+    let composedFrames;
+    if (options.effects !== false) {
+      spinner.start(`Applying effects to ${session.frames.length} frames...`);
+      const renderer = new CanvasRenderer(
+        scenario.effects,
+        scenario.output,
+        scenario.steps
+      );
+      composedFrames = await renderer.composeAll(session.frames);
+      spinner.succeed("Effects applied");
+    } else {
+      composedFrames = session.frames.map((f) => ({
+        index: f.index,
+        buffer: f.screenshot,
+        timestamp: f.timestamp
+      }));
+      spinner.info("Effects disabled, using raw frames");
+    }
+    await mkdir2(options.output, { recursive: true });
+    if (scenario.output.format === "png-sequence") {
+      spinner.start("Saving PNG sequence...");
+      const paths = await savePngSequence(
+        composedFrames,
+        scenario.output
+      );
+      spinner.succeed(
+        `Saved ${paths.length} frames to ${chalk.bold(options.output)}`
+      );
+    } else if (scenario.output.format === "mp4") {
+      spinner.start("Encoding MP4...");
+      const mp4Buffer = await encodeMp4(
+        composedFrames,
+        scenario.output
+      );
+      const outputPath = join2(
+        options.output,
+        `${scenario.output.filename}.mp4`
+      );
+      await writeFile2(outputPath, mp4Buffer);
+      const sizeMB = (mp4Buffer.length / (1024 * 1024)).toFixed(2);
+      spinner.succeed(
+        `MP4 saved to ${chalk.bold(outputPath)} (${sizeMB} MB)`
+      );
+    } else {
+      spinner.start("Encoding GIF...");
+      const gifBuffer = await encodeGif(
+        composedFrames,
+        scenario.output
+      );
+      const outputPath = join2(
+        options.output,
+        `${scenario.output.filename}.gif`
+      );
+      await writeFile2(outputPath, gifBuffer);
+      const sizeMB = (gifBuffer.length / (1024 * 1024)).toFixed(2);
+      spinner.succeed(
+        `GIF saved to ${chalk.bold(outputPath)} (${sizeMB} MB)`
+      );
+    }
+    console.log(chalk.green("\nDone! \u{1F3AC}"));
+  } catch (error) {
+    spinner.fail("Recording failed");
+    const message = error instanceof Error ? error.message : String(error);
+    console.error(chalk.red(`
+Error: ${message}`));
+    process.exit(1);
+  }
+});
+program.command("validate").description("Validate a YAML scenario file").argument("<scenario>", "Path to YAML scenario file").action(async (scenarioPath) => {
+  const spinner = ora();
+  try {
+    spinner.start("Loading scenario...");
+    const scenario = await loadScenario(scenarioPath);
+    spinner.succeed(`Loaded: ${chalk.bold(scenario.name)}`);
+    const result = validateScenario(scenario);
+    if (result.errors.length > 0) {
+      console.log(chalk.red("\nErrors:"));
+      for (const error of result.errors) {
+        console.log(chalk.red(`  \u2717 ${error}`));
+      }
+    }
+    if (result.warnings.length > 0) {
+      console.log(chalk.yellow("\nWarnings:"));
+      for (const warning of result.warnings) {
+        console.log(chalk.yellow(`  \u26A0 ${warning}`));
+      }
+    }
+    if (result.valid) {
+      console.log(
+        chalk.green("\nScenario is valid and ready to record.")
+      );
+    } else {
+      console.log(
+        chalk.red("\nScenario has errors. Fix them before recording.")
+      );
+      process.exit(1);
+    }
+  } catch (error) {
+    spinner.fail("Validation failed");
+    const message = error instanceof Error ? error.message : String(error);
+    console.error(chalk.red(`
+Error: ${message}`));
+    process.exit(1);
+  }
+});
+program.command("init").description("Create a template clipwise.yaml in the current directory").action(async () => {
+  const targetPath = resolve("clipwise.yaml");
+  try {
+    await access(targetPath);
+    console.log(chalk.yellow("Warning: clipwise.yaml already exists in this directory."));
+    console.log(chalk.yellow("Remove it first if you want to generate a fresh template.\n"));
+    process.exit(1);
+  } catch {
+  }
+  const template = `name: "My Demo"
+viewport:
+  width: 1280
+  height: 800
+
+effects:
+  deviceFrame:
+    enabled: true
+    type: browser
+  cursor:
+    enabled: true
+    clickEffect: true
+    highlight: true
+  background:
+    type: gradient
+    value: "linear-gradient(135deg, #667eea 0%, #764ba2 100%)"
+    padding: 48
+    borderRadius: 14
+    shadow: true
+
+output:
+  format: mp4
+  fps: 30
+  quality: 80
+
+steps:
+  - name: "Open app"
+    captureDelay: 100
+    holdDuration: 1000
+    actions:
+      - action: navigate
+        url: "http://localhost:3000"
+        waitUntil: load
+
+  - name: "Click button"
+    captureDelay: 50
+    holdDuration: 800
+    actions:
+      - action: click
+        selector: "#my-button"
+`;
+  await writeFile2(targetPath, template, "utf-8");
+  console.log(chalk.green("Created clipwise.yaml\n"));
+  console.log("Next steps:");
+  console.log(`  1. Edit ${chalk.bold("clipwise.yaml")} \u2014 change the URL to your site`);
+  console.log(`  2. Run ${chalk.bold("clipwise record clipwise.yaml -f mp4")} to record`);
+  console.log(`  3. Find your output in ${chalk.bold("./output/")}`);
+  console.log(`
+Or try the built-in demo: ${chalk.bold("clipwise demo")}
+`);
+});
+program.command("demo").description("Record a demo video of the Clipwise showcase dashboard").option("-o, --output <dir>", "Output directory", "./output").option(
+  "-f, --format <format>",
+  "Output format (gif|mp4)",
+  "mp4"
+).option(
+  "--url <url>",
+  "Custom URL to record (default: Clipwise demo dashboard)"
+).option(
+  "--device <device>",
+  "Device frame (browser|iphone|ipad|android)",
+  "browser"
+).action(async (options) => {
+  const spinner = ora();
+  try {
+    const demoUrl = options.url ?? "https://kwakseongjae.github.io/clipwise/";
+    const device = options.device;
+    const isMobile = device === "iphone" || device === "android";
+    const isTablet = device === "ipad";
+    const vpWidth = isMobile ? 390 : isTablet ? 1024 : 1280;
+    const vpHeight = isMobile ? 844 : isTablet ? 768 : 800;
+    const outWidth = isMobile ? 540 : 1280;
+    const outHeight = isMobile ? 1080 : isTablet ? 960 : 800;
+    const { parseScenario: parseScenario2 } = await Promise.resolve().then(() => (init_parser(), parser_exports));
+    const yaml = await import("yaml");
+    const steps = [
+      {
+        name: "Load dashboard",
+        captureDelay: 100,
+        holdDuration: 1e3,
+        actions: [{ action: "navigate", url: demoUrl, waitUntil: "load" }]
+      },
+      {
+        name: "Hover Users stat",
+        captureDelay: 50,
+        holdDuration: 700,
+        actions: [{ action: "hover", selector: "#stat-users" }]
+      },
+      {
+        name: "Hover Revenue",
+        captureDelay: 50,
+        holdDuration: 700,
+        actions: [{ action: "hover", selector: "#stat-revenue" }]
+      },
+      {
+        name: "Switch chart",
+        captureDelay: 50,
+        holdDuration: 800,
+        actions: [{ action: "click", selector: "#tab-monthly" }]
+      },
+      {
+        name: "Search",
+        captureDelay: 50,
+        holdDuration: 800,
+        actions: [
+          { action: "click", selector: "#search-input" },
+          { action: "type", selector: "#search-input", text: "conversion", delay: 18 }
+        ]
+      },
+      ...!isMobile ? [{
+        name: "Scroll to projects",
+        captureDelay: 100,
+        holdDuration: 600,
+        actions: [{ action: "scroll", y: 420, smooth: true }]
+      }] : [{
+        name: "Scroll to chart",
+        captureDelay: 100,
+        holdDuration: 600,
+        actions: [{ action: "scroll", y: 250, smooth: true }]
+      }],
+      {
+        name: "Hover row",
+        captureDelay: 50,
+        holdDuration: 600,
+        actions: [{ action: "hover", selector: "#row-1" }]
+      },
+      {
+        name: "Open modal",
+        captureDelay: 100,
+        holdDuration: 800,
+        actions: [{ action: "click", selector: "#btn-new-project" }]
+      },
+      {
+        name: "Type name",
+        captureDelay: 50,
+        holdDuration: 600,
+        actions: [
+          { action: "click", selector: "#project-name" },
+          { action: "type", selector: "#project-name", text: "Clipwise Demo", delay: 20 }
+        ]
+      },
+      {
+        name: "Type desc",
+        captureDelay: 50,
+        holdDuration: 600,
+        actions: [
+          { action: "click", selector: "#project-desc" },
+          { action: "type", selector: "#project-desc", text: "Automated screen recording", delay: 16 }
+        ]
+      },
+      {
+        name: "Create",
+        captureDelay: 100,
+        holdDuration: 1e3,
+        actions: [{ action: "click", selector: "#btn-create" }]
+      }
+    ];
+    const scenarioObj = {
+      name: `Clipwise Demo (${device})`,
+      viewport: { width: vpWidth, height: vpHeight },
+      effects: {
+        zoom: {
+          enabled: true,
+          scale: 1.8,
+          duration: 500,
+          autoZoom: { followCursor: true, maxScale: 2 }
+        },
+        cursor: {
+          enabled: true,
+          size: isMobile ? 16 : 20,
+          clickEffect: true,
+          highlight: true,
+          trail: !isMobile,
+          trailLength: 6
+        },
+        background: {
+          type: "gradient",
+          value: "linear-gradient(135deg, #1a1a2e 0%, #16213e 50%, #0f3460 100%)",
+          padding: isMobile ? 60 : 48,
+          borderRadius: 14,
+          shadow: true
+        },
+        deviceFrame: { enabled: true, type: device, darkMode: true },
+        keystroke: {
+          enabled: true,
+          position: "bottom-center",
+          fontSize: isMobile ? 14 : 16
+        },
+        watermark: {
+          enabled: true,
+          text: "Clipwise",
+          position: "bottom-right",
+          opacity: 0.35,
+          fontSize: 13
+        }
+      },
+      output: {
+        format: options.format,
+        width: outWidth,
+        height: outHeight,
+        fps: 30,
+        quality: 80,
+        outputDir: options.output,
+        filename: `clipwise-demo-${device}`
+      },
+      steps
+    };
+    const scenario = parseScenario2(yaml.stringify(scenarioObj));
+    spinner.succeed(`Demo scenario ready: ${chalk.bold(scenario.name)}`);
+    spinner.start("Checking browser...");
+    try {
+      const { chromium: chromium2 } = await import("playwright");
+      const testBrowser = await chromium2.launch({ headless: true });
+      await testBrowser.close();
+      spinner.succeed("Browser ready");
+    } catch {
+      spinner.fail("Chromium not found");
+      console.log(chalk.yellow("\nInstalling Chromium (one-time setup)...\n"));
+      const { execSync } = await import("child_process");
+      try {
+        execSync("npx playwright install chromium", { stdio: "inherit" });
+      } catch {
+        console.error(chalk.red("\nFailed to install Chromium. Run: npx playwright install chromium\n"));
+        process.exit(1);
+      }
+    }
+    spinner.start(`Recording ${scenario.steps.length} steps...`);
+    const recorder = new ClipwiseRecorder();
+    const session = await recorder.record(scenario);
+    spinner.succeed(`Recorded ${session.frames.length} frames`);
+    spinner.start(`Applying effects to ${session.frames.length} frames...`);
+    const renderer = new CanvasRenderer(scenario.effects, scenario.output, scenario.steps);
+    const composedFrames = await renderer.composeAll(session.frames);
+    spinner.succeed("Effects applied");
+    await mkdir2(options.output, { recursive: true });
+    const ext = scenario.output.format === "gif" ? "gif" : "mp4";
+    const outputPath = join2(options.output, `clipwise-demo-${device}.${ext}`);
+    if (ext === "gif") {
+      spinner.start("Encoding GIF...");
+      const buf = await encodeGif(composedFrames, scenario.output);
+      await writeFile2(outputPath, buf);
+      spinner.succeed(`GIF saved to ${chalk.bold(outputPath)} (${(buf.length / 1048576).toFixed(2)} MB)`);
+    } else {
+      spinner.start("Encoding MP4...");
+      const buf = await encodeMp4(composedFrames, scenario.output);
+      await writeFile2(outputPath, buf);
+      spinner.succeed(`MP4 saved to ${chalk.bold(outputPath)} (${(buf.length / 1048576).toFixed(2)} MB)`);
+    }
+    console.log(chalk.green("\nDemo complete! \u{1F3AC}"));
+  } catch (error) {
+    spinner.fail("Demo recording failed");
+    const message = error instanceof Error ? error.message : String(error);
+    console.error(chalk.red(`
+Error: ${message}`));
+    process.exit(1);
+  }
+});
+program.parse();