clipwise 0.1.0

package/dist/index.js

@@ -0,0 +1,1704 @@
+// 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((resolve) => setTimeout(resolve, 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(
+          (resolve) => setTimeout(resolve, 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((resolve) => setTimeout(resolve, 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 calculatePanOffset(focusPoint, scale, frameWidth, frameHeight) {
+  if (scale <= 1) return { x: 0, y: 0 };
+  const visibleWidth = frameWidth / scale;
+  const visibleHeight = frameHeight / scale;
+  let offsetX = focusPoint.x - visibleWidth / 2;
+  let offsetY = focusPoint.y - visibleHeight / 2;
+  offsetX = Math.max(0, Math.min(offsetX, frameWidth - visibleWidth));
+  offsetY = Math.max(0, Math.min(offsetY, frameHeight - visibleHeight));
+  return { x: Math.round(offsetX), y: Math.round(offsetY) };
+}
+function lerpZoom(current, target, factor) {
+  return current + (target - current) * Math.min(1, Math.max(0, factor));
+}
+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, 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 readFile(outputPath);
+  } finally {
+    await rm(tmpDir, { recursive: true, force: true }).catch(() => {
+    });
+  }
+}
+function runFfmpeg(args) {
+  return new Promise((resolve, 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) {
+        resolve();
+      } 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/script/parser.ts
+import { parse as parseYaml } from "yaml";
+import { readFile as readFile2 } from "fs/promises";
+
+// src/script/types.ts
+import { z } from "zod";
+var SafeSelectorSchema = z.string().regex(
+  /^[a-zA-Z0-9\-_#.\[\]="':\s~^$|*,>+()@]+$/,
+  "Selector contains invalid characters"
+);
+var NavigateActionSchema = z.object({
+  action: z.literal("navigate"),
+  url: z.string().min(1),
+  waitUntil: z.enum(["load", "domcontentloaded", "networkidle"]).default("networkidle")
+});
+var ClickActionSchema = z.object({
+  action: z.literal("click"),
+  selector: SafeSelectorSchema,
+  delay: z.number().optional()
+});
+var TypeActionSchema = z.object({
+  action: z.literal("type"),
+  selector: SafeSelectorSchema,
+  text: z.string(),
+  delay: z.number().default(50)
+});
+var 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)
+});
+var WaitActionSchema = z.object({
+  action: z.literal("wait"),
+  duration: z.number().describe("Wait duration in milliseconds")
+});
+var HoverActionSchema = z.object({
+  action: z.literal("hover"),
+  selector: SafeSelectorSchema
+});
+var ScreenshotActionSchema = z.object({
+  action: z.literal("screenshot"),
+  name: z.string().optional(),
+  fullPage: z.boolean().default(false)
+});
+var StepActionSchema = z.discriminatedUnion("action", [
+  NavigateActionSchema,
+  ClickActionSchema,
+  TypeActionSchema,
+  ScrollActionSchema,
+  WaitActionSchema,
+  HoverActionSchema,
+  ScreenshotActionSchema
+]);
+var 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)
+});
+var 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({})
+});
+var 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)")
+});
+var 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)
+});
+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)
+});
+var 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)
+});
+var 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)
+});
+var 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")
+});
+var EffectsConfigSchema = z.object({
+  zoom: ZoomEffectSchema.default({}),
+  cursor: CursorEffectSchema.default({}),
+  background: BackgroundSchema.default({}),
+  deviceFrame: DeviceFrameSchema.default({}),
+  speedRamp: SpeedRampConfigSchema.default({}),
+  keystroke: KeystrokeConfigSchema.default({}),
+  watermark: WatermarkConfigSchema.default({})
+});
+var 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")
+});
+var 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")
+});
+var 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
+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 readFile2(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);
+}
+
+// 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
+  };
+}
+export {
+  CanvasRenderer,
+  ClipwiseRecorder,
+  applyCrossfade,
+  calculateAdaptiveZoom,
+  calculatePanOffset,
+  encodeGif,
+  encodeMp4,
+  lerpZoom,
+  loadScenario,
+  parseScenario,
+  renderCursorHighlight,
+  renderCursorTrail,
+  renderKeystrokeHud,
+  renderWatermark,
+  savePngSequence,
+  validateScenario
+};